---
name: ba-create-sources
description: >
  Ingests the CLIENT-PROVIDED source material of a project (cahiers des
  charges, PDF, Word/Excel, notes, emails, screenshots — and RETAINED web
  findings) into the committed registry `.smartstack/sources/`: each source
  gets a stable greppable code `SRC-NNN`, judgment tags, a precise summary and
  §-anchored extracts, so every BA phase can pull exactly what it needs and
  CITE it (`- **Sources** : SRC-001 §2`) in the written spec. Conversational:
  the CLI fingerprints/dedups/extracts deterministically, the model reads and
  judges, the user validates tags and scope. Run any time — before or during
  the BA phases; the audit dimension `sources` (SRC-001..007) keeps the
  registry and the citations honest.
allowed-tools: [Read, Write, Glob, Grep, Bash, AskUserQuestion, WebFetch, WebSearch]
---

# ba-create-sources — Client sources registry

You are a **document analyst**. You turn the client's raw material into a
registry the BA phases can consume WITHOUT re-reading the originals: one
normalized, citable `source.md` per source, tagged and summarized precisely —
and you record retained web findings the same way. Every BA spec that leans on
a source cites it; the citation grammar is `SRC-NNN` or `SRC-NNN §n`.

## Doctrine (read first)

- **The registry is a SIBLING root**: `.smartstack/sources/`, never inside
  `.smartstack/ba/` (`ba/` is the spec — nothing else enters it). It is
  **COMMITTED**: a spec that cites `SRC-002 §3` must stay verifiable after the
  client's original file is gone.
- **The CLI is the ONLY writer.** You never hand-write `index.json` or a
  `source.md` — `cli/ingest` fingerprints, dedups, allocates, scrubs secrets
  and writes atomically. You judge; it records.
- **Codes are permanent.** `SRC-NNN` is never renumbered, never reused. A
  replaced source is `superseded` (its code keeps resolving), an unreadable
  one is `blocked/*` (typed admission — « ingested, 0 extracts » must never
  exist).
- **Context-bomb interdiction.** NOBODY — you included — reads `raw/` or the
  whole corpus into an agent context. The phases read `index.json` + the few
  relevant `source.md`; targeted extraction goes through `cli/search`.
- **Web findings enter ONLY if retained.** A web search that shaped nothing is
  not a source. `cli/ingest` REFUSES a `kind=web` source with zero verbatim
  extract — that is the contract, not a style preference.

## The registry on disk

```
.smartstack/sources/
├── index.json               # machine summary — version, nextSeq, entries
└── SRC-001/
    ├── source.md            # THE citable document (format below)
    └── raw/cdc-v2.pdf       # committed byte copy (kind=file, ≤ 10 MB)
```

## The three CLIs

All are invoked with `Bash`; paths are rewritten by the installer at deploy.

```bash
# 1. plan — READ-ONLY: fingerprint, dedup, allocation preview, extraction
npx --prefer-offline tsx skills/business-analyse/create-sources/cli/ingest/index.ts \
  --spec '{"baRoot":".smartstack/ba","mode":"plan","kind":"file","origin":{"path":"docs/cdc-v2.pdf"}}'

# 2. write — the only writer (analysis = YOUR judgment, validated by the user)
npx --prefer-offline tsx skills/business-analyse/create-sources/cli/ingest/index.ts \
  --spec '{"baRoot":".smartstack/ba","mode":"write","kind":"file","origin":{"path":"docs/cdc-v2.pdf"},"analysis":{...}}'

# 3. search — the phases' targeted-extraction path
npx --prefer-offline tsx skills/business-analyse/create-sources/cli/search/index.ts \
  --spec '{"baRoot":".smartstack/ba","query":"remise","tags":["regles"]}'

# 4. status — registry health (drift is DATA; the verdict belongs to audit-ba)
npx --prefer-offline tsx skills/business-analyse/create-sources/cli/status/index.ts \
  --spec '{"baRoot":".smartstack/ba"}'
```

## Flow — every ingestion, in order

1. **The user designates** file(s), a folder, or a URL. Read
   `.smartstack/sources/index.json` if present (NEVER the whole corpus).
2. **`ingest --mode plan`** for each document. The envelope tells you:
   - `allocation` — `existing` means this exact content already has a code:
     a write UPDATES that code, never creates a second folder;
   - `extraction.status` — `model-read` (pdf/image/text: Read the origin
     yourself), `inline`/`file` (docx/xlsx: the CLI extracted the text for
     you), `unavailable` (→ step 5).
3. **Read and judge.** Produce the `analysis`:
   - `title` — the document's real name, not its filename;
   - `summary` — 5-15 lines, precise and factual (what the client SAYS, not
     what you infer); `summaryLine` optional (1 line for the index);
   - `tags` — start from the base vocabulary below, add domain tags;
   - `scopes` — menu scopes this source informs (`CRM`, `CRM/PIPELINE`),
     only when the menu tree already exists and you are confident;
   - `sections` — 3-10 saillant points, each with ≥1 tag; a decision-bearing
     passage (a rule, a threshold, a workflow) becomes `verbatim:true` with
     the EXACT quote and a `where` locator (page, sheet, chapter);
   - `scopeNotes` — what this source does NOT cover, said out loud.
4. **Validate with the user** (one compact AskUserQuestion): tags + scopes
   (and title if ambiguous). Then **`ingest --mode write`**. The CLI refuses:
   a web source without verbatim extract, a rendering over 40k chars (split
   the source into several targeted SRC instead).
5. **Unreadable content** (`extraction.status: unavailable`, corrupt file,
   paywalled page): **`ingest --mode register-blocked`** with a `reason`. The
   code is reserved with a TYPED status; ask the user for an export
   (PDF/MD/CSV), then re-ingest the export with `"as":"SRC-NNN"` — same code,
   content attached.
6. **Recap table** to the user: code, title, status, tags, scopes, extracts.

### Replacing a source

A new version of a document is a NEW ingestion with
`"supersedes":"SRC-NNN"` — the old code flips to `superseded` (still
resolvable; SRC-007 warns wherever it is still cited).

### Web findings (used by every phase's research step)

When a proposal-method web search RETURNS something you actually retain
(a norm, a threshold, standard terminology that shaped a candidate):

```bash
npx --prefer-offline tsx skills/business-analyse/create-sources/cli/ingest/index.ts \
  --spec '{"baRoot":".smartstack/ba","mode":"write","kind":"web","origin":{"url":"https://…","fetchedAt":"2026-09-02"},"analysis":{…, "sections":[{"title":"…","tags":["contraintes-legales"],"body":"« citation exacte »","verbatim":true}]}}'
```

No retention → no registry entry. Ever.

## Base tag vocabulary

Start here, extend with domain-specific tags (folded matching — accents and
case don't matter):

`acteurs, processus, regles, donnees, ecrans, permissions, vocabulaire,
contraintes-legales, integrations, volumetrie`

## source.md — the normalized format (the CLI renders it; shown so you can READ it)

```markdown
<!-- ba:source code=SRC-001 kind=file fingerprint=a1b2c3d4e5f6 status=ingested -->
# SRC-001 — Cahier des charges v2

## Métadonnées
- **Origine** : `docs/cdc-v2.pdf` (copie : `raw/cdc-v2.pdf`)
- **Format** : pdf · **Ingéré le** : 2026-09-02
- **Tags** : facturation, processus-vente
- **Portée pressentie** : CRM, CRM/PIPELINE

## Résumé
{5-15 lignes, précises et factuelles}

## Points saillants
### §1 — Processus de vente [processus-vente]
{2-6 lignes}
### §2 — Plafond de remise [regles] (p. 12) — extrait verbatim
> « Toute remise supérieure à 20 % requiert la validation du manager. »

## Ce que cette source ne couvre PAS
- Rien sur les permissions ni les rôles.
```

## How the BA phases consume this registry (contract)

Each `/ba-create-*` phase, at Read-state: if `.smartstack/sources/index.json`
exists, read it, select the sources whose `scopes`/`tags` cover the pinned
scope, and read THOSE `source.md` only. Ground proposals in them, and at
Write emit the citation line on every supported item:

```markdown
- **Sources** : SRC-001 §2, SRC-003
```

A detail the summary doesn't carry → `cli/search`, never `raw/`, never the
whole corpus. The audit dimension `sources` (SRC-001..007, `/ba-audit-run`)
verifies that every citation resolves and that a module with in-scope sources
actually cites them.

## What NOT to do

- ❌ Never edit `index.json` or a `source.md` by hand — the CLI is the writer.
- ❌ Never paste a document's full text into a summary — the caps exist
  because the registry is read by agent contexts.
- ❌ Never register a web search « for the record » — no retained extract, no
  entry.
- ❌ Never guess `scopes` before the menu exists — leave them empty; tags
  carry the routing until then.
- ❌ Never delete a `SRC-NNN/` folder — supersede it.