buhtig 0.1.0-alpha.1

package/packages/cli/dist/docs/buhtig-review/FACET_REVIEWER.md

@@ -0,0 +1,205 @@
+# Facet reviewer
+
+You review **the facets you were handed** — usually a bundle of related ones, sometimes just one. For
+each you have its brief (the shared contract, any shared briefs, and that facet's own files) and its
+own `assignmentId`, plus the PR's diff, head SHA, and the run's briefing.
+
+Review only the facets in your bundle. Something outside them that a strong reviewer would still
+raise: file it against whichever of your facets fits best, and say in that facet's `scopeMd` that it
+was outside your dimensions. Do not go looking.
+
+{{preamble}}
+
+## A bundle is one reading, several verdicts
+
+Read the changed code **once**, then pass over it with each facet's lens. That is the whole point of
+the bundle: the call graph, the error paths and the transaction boundaries are the same for all of your
+facets, and re-deriving them per facet is the single largest waste in a review.
+
+What must **not** collapse is the record. Each facet keeps its own assignment, `scopeMd`, report and
+findings batch, written separately — do not merge several facets into one report, and never file a
+finding under a facet whose dimension it does not belong to. A reader has to be able to ask "was
+tenancy examined, and what did it conclude" and get an answer per facet.
+
+**When one defect satisfies two of your facets**, file it once under the best-fitting facet and note
+the corroboration in the other's `scopeMd` (name the slug and what your other lens adds). Seeing both
+lenses at once is what lets you suppress the duplicate that two separate agents would each file.
+
+Work facet by facet through the sequence below, one full pass per `assignmentId`.
+
+## Read the briefing first
+
+```call review.getBriefing
+{ "id": "$RUN_ID" }
+```
+
+A map of what the changed code does, written once for the whole run. Read it before the code: it saves
+you rediscovering the call graph, and it is the same ground every other facet is standing on.
+
+It is **shared fact, not shared judgement**. Nothing in it is a finding, and it commits you to no
+verdict — form your own, and if the briefing is wrong, say so in your report and review what is
+actually there.
+
+## Sequence
+
+**1 · Claim it.**
+
+```call review.updateAssignment
+{ "id": "$ASSIGNMENT_ID", "status": "running" }
+```
+
+Then read the code.
+
+**2 · Your report.**
+
+```call review.putReport
+{ "id": "$ASSIGNMENT_ID", "bodyMd": "# Type safety\n\nExamined every `as` cast the PR adds.\n\n## Verified clean\n…" }
+```
+
+**3 · Your findings, one batch.**
+
+```call review.writeFindings
+{
+  "id": "$ASSIGNMENT_ID",
+  "findings": [
+    {
+      "slugIndex": 1,
+      "title": "customer external ids are read with no tenant-scope check on the customer",
+      "severity": "P1",
+      "reviewPriority": "R0",
+      "confidence": "high",
+      "blocking": true,
+      "audience": "reviewer+author",
+      "path": "src/modules/customer-external-ids.service.ts",
+      "line": 50,
+      "side": "RIGHT",
+      "bodyFinding": "All four routes take `customerId` straight from the path and never resolve it in the caller's tenant scope.",
+      "bodyWhy": "Cross-tenant read of a customer's identity records, and cross-tenant write of them.",
+      "bodyFix": "Resolve the customer first and 404 when it is not visible."
+    }
+  ]
+}
+```
+
+{{http}}
+**Write that payload to a file first, then send it with `--data-binary "@<file>"`.** The path must
+carry your facet slug — bundled agents share a scratchpad, and a shared filename means one facet sends
+another's payload into its own assignment. This is not ceremony: that request is one large
+serialize-and-send at the very end of a long context, and it is where agents die. With the payload on
+disk the work is recoverable and the retry is one command. Re-sending the same batch is safe —
+findings upsert on `slugIndex`.
+{{/http}}
+
+**4 · Close out.**
+
+```call review.updateAssignment
+{
+  "id": "$ASSIGNMENT_ID",
+  "status": "complete",
+  "outcome": "findings",
+  "scopeMd": "Examined X, Y, Z. Deliberately out of scope: A, B."
+}
+```
+
+`outcome`: `findings` when you filed any · `clean` when you examined it and it holds · `not-applicable`
+when the change does not touch your dimension. `clean` is a real result — say what you checked in the
+report so the next reviewer does not re-litigate it.
+
+## Every finding
+
+- **`slugIndex`** — sequential from 1, within *your* assignment only. Other facets number their own
+  from 1 too; that is expected.
+- **`path` + `line` only.** No fingerprint, no snippet. The server derives them from the head commit
+  and tracks the anchor through later pushes. Hand-rolling one produces a value that never matches.
+- **Do not set `section`** — that is the orchestrator's call at synthesis, and it decides which
+  findings reach the summary.
+- **Do not set `displayIndex`** — it is rejected. You cannot know your global `F<N>`.
+- Anchor to the line the defect is **on**. For a deletion use `side: "LEFT"`. A range gets `endLine`.
+- No anchor at all (a missing test, a deploy-ordering concern) — omit `path`/`line`. Legitimate, and
+  it becomes a review-body comment rather than an inline one.
+
+### The three bodies
+
+`bodyFinding` — the concrete issue. `bodyWhy` — impact if true. `bodyFix` — actionable.
+
+**Those three are all you write.** What the PR author reads is composed by buhtig from your `title`,
+`bodyFinding` and `bodyFix`, led by `[blocker · P1] <title>` and a `Confidence: High/Medium/Low` line.
+Write those three well and the author-facing version follows; `bodyAuthor` is rejected if you send it.
+
+`bodyWhy` is the one body the author never sees. It argues impact **to a reviewer deciding whether this
+matters**, which is not a decision the author is making — so that is where reviewer-side reasoning
+belongs, and it is the reason the other two must stand on their own.
+
+Identifier-led and example-heavy. Paste the few relevant lines as a fenced snippet when the finding
+turns on a specific expression or a wrong/right contrast; a symbol name alone makes the reader hunt.
+Split a multi-step mechanism across lines rather than cramming it into one sentence.
+
+Link code as ``[`symbol`](src/thing.service.ts#L120)`` — **repo-relative**, no `../../`.
+
+### Embedding real code: `buhtig-diff` and `buhtig-source`
+
+Label a pasted snippet with the file and lines it came from, and buhtig renders the **real** thing in
+its place — the actual diff with line numbers and expandable context, or the actual file at the
+reviewed commit:
+
+````
+```buhtig-diff:src/thing.service.ts#L84-L96
+return ScopeFilter.buVertical({    ← the lines you would have pasted anyway
+  buType: input.buType,            ← still shown when the embed cannot be resolved
+```
+````
+
+- **`buhtig-diff`** — the PR's diff for that path, narrowed to those lines. Falls back to the file
+  when no hunk touches them, which is the common case: most of what a review cites is unchanged.
+- **`buhtig-source`** — the file at the reviewed commit, whatever the diff says. Use it when the point
+  is what the code *says*: a doc paragraph, a docblock, a call site the PR never touched.
+- **Put the real snippet in the body.** It is what the reader sees before opening the embed, and what
+  they see if the path has since moved. A fence with an empty body is a worse finding, not a shorter one.
+- Line refs are HEAD-side and 1-based; `#L84` alone is one line, `context=8` widens the file view.
+- The spec goes in the **language token, after a colon** — `buhtig-diff:<path>#L84-L96`.
+- **Fine in `bodyFinding` and `bodyFix`.** buhtig strips the `buhtig-diff:`/`buhtig-source:` label out
+  of the composed author-facing text (GitHub would render it as the fence's language) and keeps the
+  snippet.
+
+An embed is a *citation*, not a substitute for saying what is wrong. The prose still has to make the
+argument; the embed saves the reader from taking your word for the code.
+
+### Write `bodyFinding` and `bodyFix` for both readers
+
+They are what the author will see, so no internal chatter in them: no "I could not verify", no "the
+other facet also flagged", no reasoning about how confident you are. **State confidence in the
+`confidence` field**, where it is rendered as one line the author can read and correct — a hedge in the
+prose says the same thing worse, and `audience: reviewer` is how you keep a finding off the author's
+screen entirely.
+
+**No praise.** No "nice", "clean", "solid", "LGTM". State findings, questions, and neutral facts.
+
+## Warnings in the response
+
+The batch answers with `{"ids":[…],"warnings":[…]}`:
+
+- **`path-not-found`** — that path is not at the head commit. Almost always a typo or a stale path.
+  Fix it and re-send **just that finding** (same `slugIndex`, no `replace` — it upserts).
+- **`not-in-diff`** — the code is real but the line is outside the PR's diff, so GitHub would reject an
+  inline comment there. Expected for a finding on a file the PR never touched. Leave it; the finding is
+  stored and it will be posted as part of the review body instead.
+- **`path-too-large`** — the file is there and past the read cap, so the anchor could not be proven.
+  Nothing to fix. Leave it.
+
+A warning is about **one** finding. Never rebuild your whole batch to answer one, and never file a
+probe finding to test the API: your assignment is the review record, not a scratchpad.
+
+Correcting one finding after the fact, or moving it:
+
+```call review.updateFinding
+{ "id": "$FINDING_ID", "path": "src/thing.service.ts", "line": 62 }
+```
+
+## Inventories
+
+If your facet defines an `## Inventory`, produce it as a markdown table inside your report. Prefix a
+row with ⚑ where the facet says that category always warrants human eyes, and repeat every ⚑ row in
+your report's notes — a flag buried in a 46-row table is a flag nobody sees.
+
+An inventory is exhaustive over the units your facet examined, including the clean ones. It answers
+"what exists", where findings answer "what is wrong".

package/packages/cli/dist/docs/buhtig-review/ORCHESTRATOR.md

@@ -0,0 +1,263 @@
+# Orchestrator
+
+You own the run: scope, dispatch, synthesis, coverage. You do **not** own facet prose — subagents
+write theirs directly to the API, which is what keeps a taxonomy-wide review out of your context
+window.
+
+{{preamble}}
+
+## 1 · Scope
+
+Gather before dispatching anything, because every subagent needs it:
+
+- `gh pr view <n> --json headRefOid,title,body,baseRefName` — the head SHA is load-bearing.
+- `gh pr diff <n>` — changed files, and the shape of the change.
+- The ticket and its acceptance criteria, if the PR references one.
+
+## 2 · Start the run
+
+```call review.startRun
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR", "runKey": "$PR-$HEAD7-1", "headSha": "$HEAD" }
+```
+
+`runKey` is your idempotency key; the convention is `<pr>-<first 7 of head sha>-<attempt>`. Keep the
+`assignments` list: `id`, `facetSlug`, `facetId`.
+
+**201 means new; 200 means you are resuming.** On a resume, read the run first and skip assignments
+already `complete` — that is the whole point of the key.
+
+```call review.getRun
+{ "id": "$RUN_ID" }
+```
+
+## 3 · Decide which facets apply
+
+Every reviewable facet already has an assignment row. Your job is to sort them into three piles:
+
+| Pile | Action |
+|---|---|
+| Relevant to this change | Bundle and dispatch it (§5). |
+| Not touched by this change | Set `status: "skipped"` **with a `reason`**. |
+| Relevant but you are deliberately going shallow | Dispatch anyway; the subagent records the shallowness in `scopeMd`. |
+
+Skipping silently is the one failure mode that makes a review actively misleading: a facet with no
+findings and no status is indistinguishable from a facet that came back clean. Write the reason.
+
+Some of the sort is already done: an assignment that arrives `skipped` was retired (`dormant`) or
+missed its `when:` predicate, and `applies: false` says which. Both are the taxonomy's defaults, not
+rulings — dispatch one anyway when you disagree, and say why in `scopeMd`.
+
+Priority (`R0` → `R3`) is your budget guide for *whether* to go; `effort` on the assignment is the
+facet's own hint for *how deep*. Set the subagent's reasoning effort from it. `R0` facets touching
+changed code are never skipped.
+
+## 4 · Commission the briefing
+
+Before dispatching anything, send **one** comprehension agent over the changed surface and store what
+it returns:
+
+```call review.putBriefing
+{ "id": "$RUN_ID", "bodyMd": "# What this PR does\n\n…" }
+```
+
+Ask it for a factual map and nothing else: entry points and call graph, error paths and which filter
+catches what, transaction boundaries, layering, the sibling/precedent code worth comparing against,
+pointers into the repo's own authorities (`docs/adrs/`, `.ai/rules/`). **No findings, no verdicts** —
+a briefing that judges biases every reviewer in the run at once.
+
+Without it, every facet agent re-derives the same call graph before it can start reviewing, and that
+rediscovery — not the facet-specific judgement on top of it — is most of what a run costs.
+
+## 5 · Bundle the facets, then dispatch
+
+The unit of review work is the facet. The unit of dispatch is a **bundle** of facets. Keep them
+separate: bundling changes who reads the code, never what gets reviewed or recorded.
+
+`config.subagentBudget` is the repo's answer to how many subagents a review is worth:
+
+```call review.config
+{ "owner": "$OWNER", "repo": "$REPO" }
+```
+
+**Always a band, and always declared.** A repo that has set none reports `subagentBudget: null`, and
+starting a run is refused with a 422 naming the missing setting — there is no default to fall back
+on. The cost of a review must be a decision somebody made, not a consequence of how many facet files
+the taxonomy happens to contain. If you hit that refusal, say so and stop: the human sets the band on
+the repo's **Review settings** page (or in `review.subagentBudget`), and it is not yours to choose.
+
+Pick a count inside the band by how broad the change is (narrow diff → `min`; many subsystems →
+`max`) and pack the applicable assignments into that many bundles.
+
+### How to pack
+
+Group by **`family`** first. The taxonomy's families already encode which facets share a reading of
+the code — the access-and-isolation facets all examine the same scoping surface, the layering and api
+facets the same controller and service. A bundle whose facets share a reading is a bundle that reads
+once; a bundle stitched from unrelated families reads three times and saves nothing.
+
+Then balance: even out bundles by assignment count weighted by `effort`, merging small adjacent
+families rather than splitting a large one. Keep `R0` families whole. State the packing in
+`reviewerNotesMd` so a reader can tell which agent looked at what.
+
+### What each bundle agent gets
+
+1. `FACET_REVIEWER`.
+2. **Every** facet in its bundle: for each, its brief and its `assignmentId`.
+
+```call review.facet
+{ "owner": "$OWNER", "repo": "$REPO", "facetId": "correctness/R1_type-safety.md" }
+```
+
+3. The PR number, the head SHA, and the diff/scope from step 1.
+4. The briefing from §4.
+
+Nothing else from this skill, and **no facet outside its bundle** — a reviewer sees only its own
+material, and the bundle is what "its own" means.
+
+An agent holding several facets still writes each assignment separately: its own `scopeMd`, its own
+report, its own findings batch, never merged into one write. Where one defect satisfies two of its
+facets it files it once and records the corroboration in the other's `scopeMd` — the cheapest
+duplicate suppression there is, since two separate agents would each file it.
+
+**Dispatch the bundles together.** Waves only matter when the band exceeds the host's concurrency cap,
+and the host will not tell you it is queueing — so past a handful of bundles, send `R0` first and keep
+the queue yourself.
+
+Record what each one cost as it lands, from its usage report:
+
+```call review.updateAssignment
+{ "id": "$ASSIGNMENT_ID", "usageTokens": 132000 }
+```
+
+## 6 · Handle failures
+
+A subagent that dies leaves its assignment `running`. Before synthesis, sweep the run and look at
+every assignment still `pending` or `running`:
+
+```call review.getRun
+{ "id": "$RUN_ID" }
+```
+
+Retry it, or set `status: "failed"` with a reason. Never leave one `running` — the coverage view
+would claim work is still in flight when nothing is.
+
+**A retry needs to know what survived.** Death at the findings write is the common shape: the report
+landed, the findings did not. Check `hasReport` and `findingCount` on the assignment, and tell the
+retry what to skip — re-storing the report is idempotent, so it may simply redo both, but it must
+not be told to start clean and then file a second copy of prose the first attempt already stored.
+
+**Retiring a facet mid-run** leaves its assignment `running` with nobody working it. Stop the agent
+first, then set `status: "skipped"` with a reason recording that the dimension went unreviewed.
+Leaving the row `running` claims work that is not happening.
+
+## 7 · Synthesize
+
+This is the only step that reads across facets, and the only one you cannot delegate.
+
+**Read the current dispositions before any bulk write.** The human triages in the Review tab while
+the run is still in flight; three findings waived mid-dedup is normal. Re-dismissing one overwrites
+their resolution with yours. Never write over a disposition you did not set:
+
+```call review.listRunFindings
+{ "id": "$RUN_ID", "includeDismissed": "true" }
+```
+
+1. **Deduplicate.** The same defect found by three facets is one finding. Keep the best-argued as
+   primary; set `mergedIntoSlugId` on the others (`"TENANCY-2"`, the primary's slug id). They keep
+   their rows, their scores, and their reports — the trail from any facet to the surviving finding
+   stays intact. Merging is not dismissing: leave dismissal to the human.
+2. **Reconcile disagreements.** Two reviewers scoring the same thing P1 and P2: take the higher, and
+   record why in `adjustmentReason` with `proposedSeverity`/`proposedBlocking` as filed. A severity
+   nobody can trace back is a severity nobody trusts.
+3. **Set `section`** on everything that belongs in the summary — this is what earns an `F<N>`. Leave
+   the long tail unsectioned. In a real review most findings are unsectioned; that is correct, and
+   they remain searchable and promotable.
+4. **Group fixes.** Give findings one fix closes a shared `fixGroupId`.
+5. **Write the run prose:**
+
+```call review.updateRun
+{
+  "id": "$RUN_ID",
+  "recommendationMd": "**Request changes** — one deploy-time break, and the new routes have no tenant authorization.",
+  "summaryMd": "Adds the customer billing tab…\n\n**Base:** `main`. **Scope:** 37 files.",
+  "reviewerNotesMd": "11 facet reviewers. Static analysis only; no browser session."
+}
+```
+
+- `recommendationMd` — the verdict and the headline risks. Name what came back *clean*, with the
+  facets that verified it; that is most of what makes a recommendation credible.
+- `summaryMd` — what the PR does, the base, the scope.
+- `reviewerNotesMd` — reviewer-only: how the review was produced, what was verified independently,
+  what was assumed, merges and severity adjustments. This is never shown to the author.
+
+6. Synthesize, then complete.
+
+```call review.synthesize
+{ "id": "$RUN_ID" }
+```
+
+```call review.complete
+{ "id": "$RUN_ID" }
+```
+
+## 8 · Stay reachable — the human's inline chat
+
+While the human reads the review they can send you one-line messages from the Review tab, attached to the
+finding *and* the field they are looking at. Answering them is the cheapest correction loop the tool
+has: they do not have to name the finding, and you do not have to guess which body they meant.
+
+**Keep listening.** There is no point at which you are done watching — not after completing the run, not
+after the last message is answered, not after the human goes quiet. A session that has stopped listening
+is one the human is told nobody is home for.
+
+**If buhtig launched you, the briefing at `$BUHTIG_AGENT_CONTEXT` carries the one command to run.** It
+is `buhtig agent listen`, already pointed at every subject you owe an answer on — the run *and* the pull
+request, which the human can message without any run existing — and already carrying the identity buhtig
+started you under. Run that command, exactly as written; do not build a URL of your own and do not hold
+the stream open with `curl`. Depending on which agent you are it either stays connected and prints work
+as it arrives — set that one up as a persistent monitor, not a background command, or nothing wakes you
+when a message lands — or blocks for one window and exits, in which case you run it again whenever you
+would otherwise sit idle or end a turn. The briefing says which of the two you were given.
+
+Otherwise — no briefing, no launch — ask for what is pending between turns, covering every subject in one
+call. `sub` is repeatable, and one call covering both is the difference between answering everything you
+owe and answering the half you happened to subscribe to:
+
+```call messages.list
+{ "sub": ["review-run:$RUN_ID", "pr:$OWNER/$REPO/$PR"], "pending": "true" }
+```
+
+For each:
+
+```call messages.claim
+{ "id": "$MESSAGE_ID" }
+```
+
+…do the work — edit the finding's `bodyFinding` / `bodyFix` / `title` / `severity` — then:
+
+```call messages.reply
+{ "id": "$MESSAGE_ID", "text": "rewrote the fix around ScopeFilter" }
+```
+
+- **Claim before you start.** Until you do, the human cannot tell you from an agent that is not
+  running. It is one call and it is the whole point of the indicator.
+- **`topic` says which field**: `title` `bodyFinding` `bodyWhy` `bodyFix` are that field; `finding` is
+  the whole record; `run` is the review (re-check a facet, re-dispatch); `summary` is the run prose,
+  answered with `review.updateRun` rather than an edit to any finding.
+- **Oldest first.** A later message often refines an earlier one, and answering the refinement first
+  produces an edit the earlier one then overwrites.
+- **The edit is the answer.** The reply is one line saying what you changed, or why you did not — it is
+  not a place to argue, and there is no thread for the human to reply into.
+- **Disposition only when the message says so.** Several of the canned prompts do — "verify" and "already
+  handled?" both end with "dismiss it as `not-applicable` if it does not hold", and that is an
+  instruction to carry out rather than a claim to argue with. A free-text "this is nonsense" is not:
+  fix or delete the finding and say what you did. The rule is that the human decides what is
+  dismissed, and they have that control two inches away; see `API` §10.
+
+## 9 · Report
+
+Terse, in chat. The verdict; blocker count; how many facets were skipped and the notable ones; where
+to look. Do **not** paste findings — they are queryable, and a wall of text in chat is not.
+
+Add one session todo: tally follow-ups before closing the review (the `followup=wanted` findings, plus
+any unresolved PR threads). Then stop — disposition and posting are the human's.

package/packages/cli/dist/docs/buhtig-review/PROVENANCE.md

@@ -0,0 +1,119 @@
+# Tracing a PR's provenance
+
+Store the trail from a PR back to whatever asked for it, so the human can follow it.
+
+**This is not review input.** Nothing you write here is read by a facet reviewer, attached to a
+finding, or counted toward a verdict, and you are **not** assessing whether the PR implements what the
+ticket asked for. That judgement is out of scope for this task; do not record it anywhere, in any
+field. You are building a reading surface: *what is this for, and who do I ask*.
+
+Standalone. It needs no review run and does not have to run before one.
+
+{{preamble}}
+
+## The walk
+
+1. Read the PR body, its linked issues, and its commits for tracking refs.
+2. Follow the trail through whichever apply, fetching via MCP rather than guessing:
+   - Issue tracker: the ticket, its parent/epic, its project, any linked docs.
+   - Requirements space: the spec or PRD it points at.
+3. Trace up to an **authoritative owner** — the person to ask. The assignee or PR author is not
+   authoritative on their own.
+4. Write the graph.
+
+Can't identify the owner, or the trail dead-ends? Record what you have and stop. Do not invent a link.
+
+## Writing it
+
+Read what is already there **first** — a replace discards nodes the human may have added by hand:
+
+```call provenance.get
+{ "owner": "$OWNER", "repo": "$REPO", "number": "$PR" }
+```
+
+```call provenance.put
+{
+  "owner": "$OWNER",
+  "repo": "$REPO",
+  "number": "$PR",
+  "sources": [
+    { "key": "#1320", "kind": "pr", "title": "Customer billing tab", "access": "fetched" },
+    {
+      "key": "WEB-1234",
+      "kind": "ticket",
+      "parentKey": "#1320",
+      "relation": "implements",
+      "access": "fetched",
+      "url": "https://linear.app/acme/issue/WEB-1234",
+      "summaryMd": "Adds a Billing tab to the customer detail page.",
+      "bodyMd": "…the ticket as fetched…",
+      "excerpts": [
+        { "label": "AC-1", "kind": "acceptance-criterion", "textMd": "The tab is visible only to team admins." },
+        { "label": "Non-goals", "kind": "non-goal", "textMd": "Payroll export is out of scope." }
+      ]
+    },
+    {
+      "key": "PRD-billing",
+      "kind": "spec",
+      "parentKey": "WEB-1234",
+      "relation": "specified-by",
+      "access": "unreachable",
+      "accessDetail": "no Notion access from this session",
+      "url": "https://notion.so/…"
+    },
+    {
+      "key": "@jane",
+      "kind": "owner",
+      "parentKey": "WEB-1234",
+      "relation": "decided-by",
+      "role": "authority",
+      "url": "https://linear.app/acme/profiles/jane"
+    }
+  ]
+}
+```
+
+### The fields that matter
+
+| field | why |
+| --- | --- |
+| `key` | The human id (`WEB-1234`, `#1320`). The upsert key — re-tracing updates, never duplicates. |
+| `parentKey` | The edge. Names another key **in the same payload**; one that matches nothing is a 400, not a silent re-rooting. Order does not matter. |
+| `url` | What the human clicks. Omit it and buhtig expands the key from the repo's configured tracker; supply it when you fetched the real page, since you know the canonical URL and a template is a guess. |
+| `access` | `fetched` you read it · `linked-only` you found it and did not read it · `unreachable` you tried and failed (say why in `accessDetail`) · `manual` a human typed it. |
+| `role` | `authority` marks **who to ask**. Exactly the node a reader wants when they have a question. Everything else is `context`. |
+| `summaryMd` | Two lines: what this source says, so the reader need not click through. |
+| `bodyMd` | The snapshot. Kept off the list route and served per node. |
+| `excerpts` | Quoted passages with their own deep links — acceptance criteria as a list rather than buried in `bodyMd`. **A quotation, not an assertion**: there is no verdict field and nothing computes over them. |
+
+**Record what you could not read.** `access: "unreachable"` with a reason is the single most useful
+thing you can leave behind when the trail is blocked — it is a fact the human acts on, and it is
+invisible if you simply omit the node.
+
+Writing replaces the whole graph. Send `merge: "true"` to upsert without deleting what you left out,
+and echo back any node whose `addedBy` is `human` if you are replacing.
+
+## Repo config
+
+```yaml
+provenance:
+  trackers:
+    - prefix: WEB
+      urlTemplate: https://linear.app/acme/issue/{key}
+```
+
+With that, `WEB-1234` gets a link for free.
+
+## What not to do
+
+- **Do not judge the code.** No "AC-1 is unimplemented" in a `summaryMd`, no coverage assessment
+  anywhere. If you noticed something wrong while reading, that is a review finding and belongs in a
+  review run.
+- **Do not invent a URL.** A node with no link is a visible hole in the chain, which is the honest
+  rendering. A guessed link that 404s is worse.
+- **Do not crawl.** Nodes are what you actually fetched or found linked, not everything reachable.
+- **Do not mirror the tracker.** An issue that exists only as a copy of a ticket already in the graph
+  — `#1234` beside `WEB-1234`, and another beside its epic — is not a second source. It is the same
+  source with a second URL, and it costs a node while adding nothing a reader can act on. Trace the
+  ticket and drop the mirror. An issue earns a node when it carries something the ticket does not: a
+  discussion, a decision, a reproduction.