---
name: context-documents
description: Cross-phase rules for client-provided reference documents. SUPERSEDED as free-floating doctrine — the material now lives in the committed registry `.smartstack/sources/` written by /ba-create-sources, and the specs CITE it (SRC-NNN §n). This file redirects; the operational contract is inlined in create-sources/SKILL.md (deployed) because _workflow/ never deploys.
phase: '*'
kind: companion
mode_pinned: true
section_label: '_WORKFLOW — CONTEXT DOCUMENTS'
---

# Context documents (cross-phase) — → `/ba-create-sources`

Client reference material (specs, cahiers des charges, glossaries, Excel
sheets, PDFs, schemas, screenshots) is **authoritative source material** — and
since the sources registry, it is a FIRST-CLASS artefact, not an ad-hoc read:

- **Where it lives**: `.smartstack/sources/` — sibling root of `ba/`,
  COMMITTED (see `ba-files.md` § Sibling root). The historical ad-hoc drop
  `.smartstack/ba/_docs/` is retired: nothing globbed it, nothing audited it,
  and it sat inside the spec tree it did not belong to.
- **How it enters**: `/ba-create-sources` — the model reads and judges
  (summary, tags, §-anchored extracts), the `cli/ingest` fingerprints, dedups,
  scrubs and writes. Every source gets a stable `SRC-NNN` code.
- **How the phases consume it**: read `index.json`, select by `scopes`/`tags`
  for the pinned scope, read THOSE `source.md` only; targeted extraction via
  `cli/search`. Never `raw/`, never the whole corpus (the 394M-token lesson).
- **How it shows in the specs**: the citation line
  `- **Sources** : SRC-001 §2` on every supported item. The `sources` audit
  dimension (SRC-001..007) verifies that citations resolve and that in-scope
  sources are actually consumed.

## What changed vs the old doctrine

The old rule « don't list every document you read » is **INVERTED**:
provenance is now mandatory and auditable. A spec item grounded in a client
document that does not cite its `SRC-NNN` is a defect (SRC-005), not
discretion. What remains true:

- **Treat sources as authoritative.** When a request can be answered from a
  registered source, ground the proposal in it and cite the code — in prose
  during the conversation ("d'après SRC-001 §2, le cahier des charges…") and
  in the `**Sources**` line at Write.
- **Quote accurately.** Verbatim extracts live in the source.md as `§n`
  blockquotes — cite the anchor rather than re-quoting from memory.
- **A document the user mentions but never registered** → run
  `/ba-create-sources` first (or ask where the file is). Reading a client
  document and using it WITHOUT registering it recreates the untraceable
  state this registry exists to end.