@nurix/etna 0.15.7 → 0.16.0

package/data/harnesses/code-fable/skills/distiller/references/docs-mode.md

@@ -0,0 +1,526 @@
+# distiller · mode `docs` — facts → documentation deltas
+
+The shared knowledge root for this mode is still [`references/method.md`](method.md) —
+**read it first, in this mode too.** `docs` mode reuses its surprisal, EDU-decomposition,
+reconciliation (ADD/UPDATE/SUPERSEDE/NOOP), and bi-temporal vocabulary unchanged. This
+file is the *procedure* that sequences those mechanisms one hop further down the gradient:
+from `docs/memory/facts/` (warm, distilled cards) into proposed edits to `docs/` (the cold,
+human-owned SSoT). It NEVER writes a doc on its own — it **drafts and presents**; the human
+disposes (P7).
+
+> `facts` mode = inbox → cards. `docs` mode = cards → *presented* doc deltas. One component,
+> two modes, one algorithm root. distill② is the greenfield hop no surveyed tool has built
+> (prior art stops at index/retrieval); the discipline below is what keeps it from corrupting
+> documentation.
+
+---
+
+## The audit-trail invariant (the spine)
+
+Every rule here serves one invariant, because the load-bearing moment in this mode is the
+**human-approval moment**, and that moment is only trustworthy if the reviewer can
+mechanically check every claim:
+
+> **Two-way traceability.** Every drafted delta *line* names the fact-card(s) it decomposes
+> from (forward: delta → card). Every consumed card names the doc(s) it was digested into
+> (backward: card → delta). Every card already names the sessions/commits it came from
+> (`provenance`, from `facts` mode). The chain **doc-line → card → session/commit**
+> must resolve end to end with no orphan link. A delta line with no card, or a card marked
+> digested into a doc that does not contain its content, is a **defect**: the run fails its
+> acceptance check, the line is not presented.
+
+This mode introduces **no prose that is not a decomposition of a card** — decomposition-with-
+citation, exactly as `facts` mode decomposes inbox entries into cards. If the agent cannot
+cite a card for a sentence, that sentence is not written.
+
+---
+
+## Design lens: the six ways facts→docs corrupts documentation
+
+Designed **failure-modes-outward.** Every step below names the hole it closes; if a step
+seems heavy, trace it to the failure it prevents.
+
+| # | Failure mode | What it looks like | The protection that closes it |
+|---|---|---|---|
+| **F1** | **Invention** | The draft asserts something no card says — interpolated, generalized, or hallucinated prose. | Decomposition-never-invention: every line carries `[from: fact-…]`; a line with no card behind it is illegal and dropped (Step 3, Acceptance A2). |
+| **F2** | **Stale-card application** | A superseded/invalidated card is written into a doc as if current. | Bi-temporal gate: only `invalid_from: null` cards are eligible; superseded cards are skipped and named in the report (Step 2). |
+| **F3** | **Double digestion** | The same card is written into the same doc twice across runs. | `digested_into:` on the card is the idempotency mark — a (card, doc) pair already recorded is not re-drafted (Resolution 3, Step 2). |
+| **F4** | **Conflict steamrolling** | A card contradicts existing prose and the draft silently overwrites it. | Card-vs-prose conflicts become **D7 questions**, never edits (Resolution 2, Step 4). |
+| **F5** | **Pillar-drift absorption** | A card contradicting a doctrine/decision headline is quietly written into a doc, laundering a belief change. | Pillar escape valve: such a card emits a *propose-Brainstorming-Mode* item, never a doc edit (Resolution 4, Step 2.4). |
+| **F6** | **Partial-approval limbo** | Human approves 3 of 5 lines; the card is marked fully digested (losing 2) or fully un-digested (re-proposing 3). | Partial digestion: `digested_into:` records only the (card → doc) pairs *actually written*; declined lines → backlog (D10); the card recirculates only its un-applied content (Resolution 3, Step 6). |
+
+Two structural failures sit above these: **frozen-record corruption** (editing a pillar, a
+`Complete`/`Abandoned` plan, or changelog history — forbidden outright) and **axis merge**
+(folding distill② into maintenance — refused: reconcile owns *structure*, maintenance owns
+*docs-vs-code fidelity*, distill② owns the *facts→docs distillation* hop; three distinct axes,
+P19).
+
+---
+
+## Execution model
+
+Runs **in the main session.** No standing sub-agent, no daemon, no cron, no hook self-trigger
+(P6). The harness proposes; the user disposes. Invoked one of three ways, all human-gated:
+
+1. The user asks (`distiller docs`, "distill the facts into docs", "draft pending doc deltas").
+2. The **Completion flow** points at it (one router line in the kit `CLAUDE.md` — Resolution 5a).
+3. The user accepts the **maintenance threshold proposal** (≥N undigested cards map to one doc — Resolution 5b).
+
+In every path the output is **a presented draft, never a written doc.** Nothing mutates a doc
+without an explicit human "yes" on that specific draft.
+
+### Invocation shapes
+
+```
+distiller docs                       # Completion default: resolve target from the active plan/spec
+distiller docs --feature <slug>      # just-completed feature → resolve to its owning doc
+distiller docs --doc <path>          # threshold path / direct: digest cards touching one named doc
+```
+
+`docs` mode runs against **one target doc at a time** — the unit of a delta is a single doc.
+The Completion caller uses the bare/`--feature` form (it knows what just shipped); the
+threshold caller (maintenance) uses `--doc` (it knows which doc the cards piled up against).
+A card-first run may surface several single-doc deltas; each is presented and approved
+independently.
+
+---
+
+## Procedure (executable, numbered)
+
+> Each step names the failure mode(s) it closes. Ordering is load-bearing: the pillar check
+> precedes drafting (a belief-changing card never reaches the draft); the digestion mark is
+> written **last** (a crash re-presents rather than silently swallows — the mirror of `facts`
+> mode's "consume the digested entries last").
+
+### 0. Read the roots
+
+Read [`method.md`](method.md) (surprisal / EDU / reconciliation / bi-temporal vocabulary) and
+this file. Confirm the target doc exists, or note that none does (Edge Case A).
+
+### 1. Resolve the target doc, read the three roots in order
+
+1. `method.md` (algorithm vocabulary).
+2. The **target doc** — full current prose + its `owns`/`touches` frontmatter. This is the
+   SSoT you are proposing to revise; you read it before you draft so conflicts surface as
+   questions, not silent overwrites.
+   - `--doc <path>` → that doc.
+   - `--feature <slug>` / bare → the spec that just flipped to `Active` (Completion names it),
+     or the feature doc whose `owns` glob covers the plan's Proposed-Changes paths. Glob
+     `docs/{features,modules/*/features}/**/*.md`, match `owns` against changed paths.
+     Architecture/operations docs have no `owns` — for those, fall to entity/semantic match.
+   - No doc resolves → Edge Case A.
+3. The **pillar headlines** — the doctrine pillar (`## Pn —` headlines) and the decisions
+   pillar (`## Dn —` headlines) plus each one's one-line Principle/Decision statement. Read
+   **every** decision headline except those marked superseded: a decision carrying a
+   `Reversed by D-M` marker (or a legacy `Status: tentative`) is NOT a binding pillar headline
+   and is skipped; absence of any status marker means the decision is live (the new
+   append-only model has no `Status: committed` field — a live decision is simply one nothing
+   has reversed). Headlines only, never the bodies — this is the conservative
+   contradiction-check substrate (Resolution 4).
+
+### 2. INPUT SELECTION — gather the cards "touching" the target (Resolution 1) — *closes F2, F3, F5*
+
+1. **Structural retriever (always runs, qmd-independent).** Read every card in
+   `docs/memory/facts/*.md`. A card *structurally touches* the target when its `provenance`
+   paths or `entities` intersect the target's `owns`/`touches` globs — match defined precisely
+   in Resolution 1.
+2. **Semantic retriever (qmd, optional).** If `command -v qmd` succeeds, for the target's
+   identity (title + each `owns` glob stem + any `anchors:` query) run
+   `qmd query --format json -c {repo}-facts "<the doc's subject>"`. `{repo}` = repo dir name;
+   scope with `-c` always; repeat `-c` per relevant `{repo}-*` facts collection (the set
+   `qmd collection list` names). qmd absent ⇒ skip silently, note in the report that selection
+   ran structural-only (changes recall, not correctness).
+3. **Bi-temporal + digestion gate (F2, F3).** From the union, drop:
+   - any card with `invalid_from` ≠ `null` (superseded — list as "skipped: superseded");
+   - any card whose `digested_into:` already lists the target doc path (already consumed here);
+   - any card whose `superseded_by:` chain leads to a live card already in the set (the live
+     card wins; keep the superseded one out of drafting, keep its trail — Edge Case D).
+   What remains is the **working card-set**.
+4. **Partition the working card-set (F5):**
+   - **pillar-conflicting** — cards in explicit headline-level conflict with a pillar/decision
+     (Resolution 4). These NEVER become a doc edit; they route to the escape valve **before**
+     drafting, so a belief-changing fact can never be laundered into prose.
+   - **doc-bound** — everything else (most cards).
+   A card can be both: handle both arms; do not let one suppress the other.
+
+### 3. DELTA DRAFTING — classify, then decompose doc-bound cards (Resolution 2) — *closes F1, F4*
+
+First **surprisal-gate** each doc-bound card against the *doc* (method §1, retargeted): a card
+whose content the doc already states is predictable ⇒ **NOOP** — draft nothing, but still mark
+it digested on accept (Step 5; it is absorbed, so it must not re-surface forever). This is the
+only retention signal; no importance scores.
+
+For each surviving card, classify against existing prose — the card-vs-doc decision (method §3,
+retargeted), exactly one of:
+
+- **EXTEND** — adds behavior/rationale the doc lacks, no conflict → draft an additive line.
+- **REFINE** — sharpens an existing doc claim that is incomplete, not wrong → draft an in-place
+  refinement (additive; never deletes prose).
+- **CONFLICT** — card and prose disagree on a matter of fact → **do not resolve.** Emit a D7
+  question; draft the line only *conditionally*, gated on the answer (F4).
+- **ESCALATE** — contradicts a pillar headline → already routed to the valve in Step 2.4
+  (Resolution 4); never drafted here.
+- **NOOP** — doc already states it → mark digested, draft nothing.
+
+For each EXTEND/REFINE card, decide which **allowed section** it informs (Resolution 2 fixes
+the allow-list) and draft the smallest faithful prose change. Every drafted line carries an
+inline provenance marker `[from: fact-<slug>]` for each contributing card. These markers are
+**scaffolding for the review moment, not final doc text** — stripped on accept (Step 5.1), so
+the human-owned prose stays clean. The durable forward-link survives as the card's
+`digested_into:` back-pointer.
+
+The output of this step is a **single presented delta document** (in chat, not written to
+disk):
+
+```
+TARGET: docs/features/memory-capture.md
+
+── PROPOSED DELTA ────────────────────────────────────────
+§ Current Behavior  (EXTEND)
+  + The qmd retrieval lens is organized into per-subtree collections, with the
+    memory inbox excluded from indexing by construction.   [from: fact-qmd-optional-retrieval-lens]
+
+§ Changelog entry  (new — docs/history/changelog/2026-06-04-...md)
+  ### Modified
+  - capture-hook merge is now idempotent across re-install   [from: fact-etna-hook-merge-idempotent]
+
+── QUESTIONS (D7 phrasing — answer before accept) ────────
+  Q1. docs/features/memory-capture.md §Current Behavior says the index spans all of
+      docs/memory; fact-qmd-optional-retrieval-lens says the memory inbox is excluded.
+      Confirm the doc is stale before I revise it — I will not overwrite it silently.
+
+── PILLAR-CONFLICT ESCAPE (NOT a doc edit) ───────────────
+  (see Resolution 4 — emitted as a propose-Brainstorming-Mode item, if any)
+
+── DIGESTION PLAN (applied only on accept) ───────────────
+  On accept I will set `digested_into:` on: fact-qmd-..., fact-etna-hook-..., and the
+  NOOP'd cards already stated by the doc: fact-...
+──────────────────────────────────────────────────────────
+```
+
+### 4. PRESENT and await disposition — never auto-write (locked default #4) — *the gate itself*
+
+Present the delta document in chat and **stop.** The agent does not edit the target doc, write
+the changelog, or touch any card frontmatter at this point. The human disposes:
+
+- **Accept (whole or per-line)** → Step 5.
+- **Accept with edits** → the human's edits are authored prose; apply them as doc text, but
+  digestion-marking (Step 5) still records the contributing cards as evidence consumed (the
+  human edited the *abstraction*; the *evidence* is unchanged). Lines the human deletes
+  entirely → their sole-source cards are **not** marked digested (nothing landed for them).
+- **Decline** → Step 6 (backlog at par, D10).
+- **Blocked-on-question (CONFLICT)** → leave undigested; the question re-surfaces next run if
+  unanswered. Not backlogged unless the user explicitly declines to engage it.
+
+### 5. ON ACCEPT — write doc, write changelog, mark digestion LAST (Resolution 3) — *closes F3, F6*
+
+Apply in this order so a crash leaves the audit trail consistent (doc content exists before
+any card claims to have landed in it):
+
+1. **Write the accepted prose into the target doc**, stripping the `[from: ...]` markers from
+   the final text (review scaffolding; the doc's prose is the human-owned abstraction).
+   Prefer handing approved lines to the **`documentation` skill**, which owns the
+   feature/changelog templates — this mode carries no copy of them.
+2. **Write the changelog entry** if the delta included one (via the `documentation` skill's
+   Changelog template, `docs/history/changelog/`). Append-only; never edit an existing entry.
+3. **Mark digestion LAST:** on each card that contributed an *accepted* line (and each NOOP'd
+   card the doc already stated), append the target doc path (and changelog path, if it
+   contributed there) to `digested_into:`. Marking last means a crash mid-write re-presents
+   the delta rather than falsely claiming digestion.
+
+Cards STAY — `digested_into:` is the only mutation; bi-temporal rules from `method.md` still
+apply (a card is never deleted; supersession is `facts` mode's surface). The card is now both
+evidence-for-the-doc and a queryable audit record of *where its content went*.
+
+### 6. ON DECLINE — backlog at par, deduped (D10) — *closes F6*
+
+Append the declined delta to `docs/history/backlog.md` at the finding's own P0–P3 severity
+(same scale as code work), deduped:
+
+```
+- **[P2]** distiller-docs proposed updating docs/features/memory-capture.md §Current Behavior from fact-qmd-optional-retrieval-lens (declined) — discovered by distiller docs
+```
+
+Dedupe by (target doc § section, contributing card-ids): if an identical pending item exists,
+leave it. Never a segregated section, never auto-lowest-tier (D10). Never block Completion.
+The declined cards stay undigested, so they re-surface next pass.
+
+### 7. Report (in chat)
+
+Target doc; working-set cards; lines drafted and their cards; cards classified EXTEND / REFINE
+/ NOOP / CONFLICT-question / ESCALATE / skipped-as-superseded; questions raised; pillar-conflict
+items verbatim; on accept — doc + changelog written and cards marked digested; on decline — the
+backlog line. If qmd was absent, the one advisory line that selection ran structural-only. A
+run where no undigested card touches the target is **valid**: say "no undigested cards touch
+{target}," do not pad — and **touch nothing**.
+
+---
+
+## The five resolutions
+
+### Resolution 1 — INPUT SELECTION: what "touching" means, precisely
+
+A card **touches** the target doc iff it satisfies **either** retriever, and is not removed by
+the Step-2.3 gates. "Touching" is a **union of retrievers, intersected with eligibility** —
+broad capture, conservative gating.
+
+**(a) Structural intersection (exact, always evaluated).** True when ANY of:
+
+1. **Provenance match (STRONG signal).** A `commit <sha>` entry in the card's `provenance`
+   resolves to changed files (`git show --name-only <sha>` when the commit is local); a changed
+   file under the target's `owns`/`touches` globs is a match. (`session <id>` entries carry no
+   paths and do not participate; an ADR/brainstorm path matches the globs directly.) This is
+   strong because the card derives from a commit that edited code the doc
+   owns.
+2. **Entity match (SUPPORTING signal).** A normalized name in the card's `entities` equals
+   (case-insensitively, after kebab/camel normalization) a module/feature stem in an `owns`
+   glob, the doc title, or a symbol the doc explicitly names. **Bare prose mentions do NOT
+   count** — only declared ownership, so "touching" can't be triggered by a doc that merely
+   discusses an entity it doesn't own.
+
+**(b) Semantic neighborhood (qmd, optional, recall-only).** A card returned by
+`qmd query -c {repo}-facts "<doc subject>"` within qmd's default result window. Semantic hits
+with **no** structural intersection are still candidates but flagged `[semantic-only]` in the
+delta — the link is associative, not provenance-grounded, so the reviewer treats it as
+lower-trust and may reject on link-strength alone.
+
+The candidate set is the **union** of (a) and (b); correctness rests on (a) (exact,
+deterministic, qmd-independent), (b) only raises recall. This is why the mode runs fully
+without qmd, and why the maintenance threshold (Resolution 5b) counts on (a) alone.
+
+A card may touch **several** docs (its entities span modules) — expected, handled by partial
+digestion (Resolution 3): the card is processed once per target doc, and `digested_into:`
+accumulates each doc it actually fed.
+
+### Resolution 2 — DELTA DRAFTING RULES: what a fact may update, with provenance
+
+**Allow-list of writable targets** (a card may inform ONLY these):
+
+| Target | What a card may do | Why bounded here |
+|---|---|---|
+| **`## Current Behavior`** (feature doc) | Add/modify a sentence describing how the system works *today*, when a card reports a now-true behavior the section omits or contradicts. The primary target. | The "how it works now" section cards are evidence for. |
+| **`## Background`** — why-built metadata (feature doc) | Add a sentence of *why* a decision was made, when a card records a decision/constraint/reversal Background omits. | Cards carry the "why" the loop captured; Background is its home. |
+| **`## Architecture` / `## Key Functions`** (feature doc) | Additive correction only when a card names a concrete, code-anchored fact (a new function, a moved file). Prefer Current Behavior unless the card is structural. | Code-anchored structure, not prose. |
+| **A new changelog entry** in `docs/history/changelog/` (via `documentation` skill's Changelog template, `### Added`/`### Modified`/`### Removed`) | Draft a changelog line for a code change a card witnesses, when a plan just completed. | Append-only history; a *new* file, never an edit. |
+
+**Never writable by distill②** (hard stops): `## Goal`, `## Goals & Non-Goals`, `## Approach`,
+`## Open Questions`, `## State`, frontmatter `owns`/`touches`/`anchors` (maintenance/spec axis
+— P19), any **pillar** file, any **plan** (frozen), any **existing** changelog entry (frozen
+history), any **boundary** file. A card implying one of these needs a change becomes a
+**question** (below) or, for pillars, an **escape item** (Resolution 4).
+
+**Per-line provenance (the invariant, mechanized).** Every drafted line carries
+`[from: fact-<slug>]` for each contributing card. A line with no such tag is a **defect** — not
+presented (Acceptance A2). On accept the tag is stripped from the final doc prose (it was
+review scaffolding); the durable forward-link survives as `digested_into:` (Resolution 3) — so
+traceability is preserved without polluting human-owned prose.
+
+**Decomposition, never invention.** As in `facts` mode: one card may yield several doc lines;
+the agent rephrases the card's atomic statement into doc-fit prose but **adds no claim the card
+does not support.** When two cards are needed for one line, both ids attach. If doc-fit prose
+would require a fact in no card, that fact is *missing* — raise it as a gap in the report, do
+not invent it.
+
+**Conflict → question (D7 phrasing), never silent resolution.** When a card contradicts an
+existing sentence, the agent does NOT overwrite. It emits a D7 question — *"docs/x.md §S says
+A; fact-<slug> (from <provenance>) says B. Confirm the doc is stale before I revise it."* —
+and drafts the conflicting line only as a *conditional* proposal gated on the answer. Docs stay
+SSoT: the card is evidence for revision, the human decides.
+
+### Resolution 3 — DIGESTION MARKING: `digested_into:` semantics
+
+On accept, each contributing (and each NOOP'd) card gains a `digested_into:` frontmatter list:
+
+```yaml
+---
+id: fact-qmd-optional-retrieval-lens
+valid_from: 2026-06-04
+invalid_from: null
+superseded_by: null
+digested_into:                                  # ← added by docs mode, on accept, never on draft
+  - docs/features/memory-capture.md
+  - docs/history/changelog/2026-06-04-qmd-lens.md
+entities: [qmd, retrieval-lens, per-subtree-collections, inbox]
+provenance: [session e3c4a623, commit d262e18]
+---
+```
+
+A **flat list of doc paths** — the brief's shape. Track *which doc* a card landed in, not which
+sentence; whole-card-vs-target is the granularity, which keeps selection (Step 2.3) a simple
+list-membership test.
+
+Semantics:
+
+- **Absent / empty** ⇒ undigested ⇒ eligible for selection and counted by the maintenance
+  threshold. The default state of a fresh `facts`-mode card.
+- **A list of doc paths** ⇒ the card's content has been decomposed into each listed doc — the
+  backward audit link completing the two-way trace.
+- **Partial digestion (F6), keyed on whether THE CURRENT TARGET is listed.** A card may
+  contribute to doc X yet have residual facts not placed elsewhere. Mark it
+  `digested_into: [docs/X.md]` — digested into X, but **still selectable** for other targets,
+  because selection drops a card only when the list already contains *the current target*. A
+  card stays in circulation until every doc it touches has consumed it. No separate flag.
+  Lines the human declined are not represented in the list (their cards recirculate); only
+  *applied* content is recorded.
+- **One card, several docs** ⇒ the list grows **append-only across runs.** Each entry is
+  independently meaningful; order is run-order. **Never rewrite or remove an entry** — a doc
+  later reverted does not un-digest the card (the card *was* digested there at that transaction
+  time; the doc's own git history records the revert). This mirrors `method.md`'s bi-temporal
+  stance: the trail only grows.
+- **Supersession interaction (F2 + F4 seam).** If a digested card is later superseded by a
+  `facts`-mode run, the *old* card keeps its `digested_into:` (it documents what the doc once
+  said and why) AND gains `invalid_from:`/`superseded_by:` from the normal bi-temporal path.
+  The *new* card is undigested → on the next `docs` run its content surfaces the now-stale doc
+  prose as a **CONFLICT question** (Resolution 2), never an auto-rewrite. The trail shows: doc
+  prose ← old card (now invalid) ← superseded_by → new card (pending). No link is ever broken.
+
+`digested_into:` is the **only** field `docs` mode writes on a card. It never edits the card's
+body, `provenance`, `entities`, or bi-temporal fields — those are `facts` mode's surface.
+
+### Resolution 4 — PILLAR ESCAPE VALVE: "contradicts a pillar," conservatively
+
+**Definition (deliberately narrow).** A card *contradicts a pillar* iff its atomic statement is
+in **explicit, headline-level conflict** with a doctrine principle (`## Pn —` headline) or a
+live decision (`## Dn —` headline) — i.e. the card asserts X and the headline (or its one-line
+Principle/Decision statement) asserts not-X about the *same* subject. A decision counts as a
+binding headline unless it has been superseded: a `Reversed by D-M` marker (or a legacy
+`Status: tentative`) drops it from the substrate, and the reversing decision is the live
+headline in its place. The operative test: **could you point to the exact pillar headline the
+card negates?** If not, it is not a pillar contradiction.
+
+- ✅ Escapes: a card stating "the harness auto-runs the distiller on a cron" vs P6's "build no
+  enforcement machinery / no cron" — direct negation of a headline claim. A card recording a
+  reversal that negates a live decision headline — e.g. "modules auto-create at a
+  flat→modules threshold" vs a live D-headline "the user sets module granularity."
+- ❌ Does NOT escape: a card that merely *touches a topic a pillar discusses*; adds nuance,
+  scope, or an exception not contemplated by a pillar (normal doc evolution); is "in tension
+  with the spirit"; or conflicts only with a pillar's **body** but not its headline (that is a
+  normal doc CONFLICT question — D7 — or nothing). **Vibes do not escape.**
+
+If uncertain whether a conflict is headline-level, **do not escape** — treat it as a doc CONFLICT
+question or drop it. Rationale (the decision rule under uncertainty): a false-negative — a real
+conflict slips through as a question — is **recoverable** by the human in the review moment; a
+false-positive — a spurious brainstorm proposal — costs the operator a mode-entry decision and
+**erodes the valve's signal.** When unsure, the cheaper miss is the question.
+
+**Emission (P7 mode-entry instance — propose, never enter).** A pillar-conflicting card
+produces a **propose-Brainstorming-Mode item** in the PILLAR-CONFLICT block, never a doc edit
+and never an auto-entry into Brainstorming Mode:
+
+```
+── PILLAR-CONFLICT ESCAPE (NOT a doc edit) ───────────────
+  fact-<slug> (from <provenance>) appears to contradict doctrine headline
+  "P6 — the harness builds no enforcement machinery":
+    card says:    <the card's atomic statement>
+    P6 headline:  <the headline claim>
+  This is a belief-level conflict, not a doc revision. Propose entering Brainstorming
+  Mode to reconcile it? (I will not edit the pillar, and I have NOT digested this card
+  into any doc.)   [from: fact-<slug>, contradicts: P6]
+```
+
+The conflicting card is **NOT marked digested** (it was not absorbed — it escaped) and **NOT
+backlogged** as a doc-delta (it awaits the brainstorm disposition). It stays undigested so the
+conflict re-surfaces until brainstorm resolves it (the recurrence *is* the dedupe). Distillation
+never quietly rewrites belief — the pillars are the human-owned headwater that *steers*;
+distill② may not silently change what they steer. (If a brainstorm later lands a pillar change
+plus a downstream doc edit, that doc edit re-enters this mode normally.)
+
+### Resolution 5 — TRIGGER WIRING (P10: at most one line each)
+
+**(a) Completion-flow pointer — ONE router-grade line in the kit `CLAUDE.md` Completion step.**
+Added to the "On **Completion**" flow in `harness/code/CLAUDE.md` §Workflows. Terse, points,
+does not re-teach (the procedure lives in this file). Verbatim:
+
+> On Completion, after flipping the spec to `Active`, consult `distiller docs` for the just-completed feature's doc — it drafts any pending fact-card deltas for your approval (presented, never auto-written).
+
+**(b) Maintenance threshold — ONE line in `agents/maintenance.md` Step 7**, sibling to the
+existing inbox-distillation threshold (the `facts` analogue: ≥5 undigested *inbox entries*
+proposes a `facts` run). Verbatim:
+
+> **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by Resolution 1's structural intersection (exact, qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined/ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence is the dedupe, so never backlog the proposal itself.
+
+`N = 10` default (vs the inbox threshold's 5 — inbox entries are rare and rich; cards accrue per doc). "Touch" uses the
+**structural** retriever only (deterministic, no qmd dependency in the maintenance loop).
+Per-doc count, not repo-wide: the proposal names the one doc, so the run is already scoped. This
+lands as a proposal emitter only — maintenance does not run the distiller (P19: distinct axis).
+
+---
+
+## Edge cases
+
+**A. No target doc exists yet for a completed feature.** distill② does **not** create the
+feature doc — that is the Completion step's job (flip spec to `Active`) via the `documentation`
+skill. If the invocation finds no doc, the mode reports *"no target doc yet for {feature};
+create it via the spec flow first, then re-invoke `distiller docs`"* and stops. It never
+scaffolds a doc from cards alone — a doc born purely from distilled facts would have no
+human-authored abstraction (Background/Goal/Approach) and would violate docs-as-SSoT +
+decomposition-never-invention. Cards stay undigested; they'll be drafted once the doc exists. If
+the gap persists, backlog at par: `- **[P2]** Feature {slug} has {N} undigested cards but no owning doc — discovered by distiller docs`.
+
+**B. A card touching zero docs.** Not selected for any target — it stays undigested, queryable,
+counted toward no threshold. Normal and valid: not every fact belongs in a doc (a transient
+observation, a fact about an unowned path). **Never** force-fit into the nearest doc (that is
+invention). If maintenance reports many undigested cards touching *no* doc, that is an
+**unowned-code** signal for maintenance's existing unowned-path step, not a distill② action.
+Report it as a count (*"{N} cards touch no current doc"*); do not absorb it. No doc is touched.
+
+**C. A card touching a FROZEN record (a plan, an existing changelog entry, a pillar).** Never
+edited (hard stop). A card whose only relevant target is frozen:
+- if it *contradicts* a pillar headline → escape valve (Resolution 4);
+- if it reports a code change worth recording → draft a **new** changelog entry (append-only is
+  allowed; editing an existing one is not);
+- otherwise → it touches a writable doc section instead, or touches zero docs (Edge Case B).
+The frozen file is never the write target.
+
+**D. Conflicting cards (two live cards disagree about the target's area).** distill② does not
+adjudicate which is true — that is `facts`-mode reconciliation's job (ADD/UPDATE/SUPERSEDE/NOOP,
+`method.md` §3). If two *live* (non-superseded) cards make contradictory claims about the same
+doc sentence, surface **both** as a single D7 question — *"fact-A says X, fact-B says Y about §S;
+these disagree — which holds? I will not draft a revision until the cards reconcile"* — and draft
+**neither** line. Suggest the user run `distiller facts` to reconcile first. If one card is
+already `superseded_by` the other, the live card wins and the superseded one is excluded from
+drafting (Step 2.3) but its trail is preserved. distill② never resolves a fact-vs-fact conflict
+by picking one — that crosses into fabricating belief.
+
+**E. A card hand-edited into the doc (accept-with-edits), then re-surfaces.** Because
+`digested_into:` was set on accept (Step 5.3) listing the target, selection (Step 2.3) drops the
+card on the next run — it is digested into that doc regardless of whether the landed prose is the
+agent's draft or the human's edit (the human edited the *abstraction*; the *evidence* is recorded
+either way). The card does not re-surface for that doc. Only if the human *deleted* a line
+entirely (so nothing landed for its sole-source card) does that card stay undigested and re-
+surface — which is correct: its content never reached the doc.
+
+**F. Disambiguation — prose-conflict vs pillar-conflict.** If a card collides with *both* a doc
+sentence and a pillar headline, the **pillar escape wins** (the heavier, more conservative path):
+emit the propose-Brainstorming-Mode item and do not draft the doc line, because the doc prose may
+itself be downstream of the belief now in question. Resolve the belief first, then let any
+resulting doc edit re-enter normally.
+
+---
+
+## Acceptance checks
+
+1. **Presented, never auto-written.** A run produces a chat-presented draft and waits; no doc
+   file changes until the human approves (locked default #4).
+2. **Per-line provenance.** Every drafted prose line / changelog bullet carries a `[from: ...]`
+   tag naming ≥1 source card; a line with no card behind it does not exist in the draft (F1).
+3. **Digestion recorded + cards survive.** On approval, every consumed (incl. NOOP'd) card gains
+   the target path in `digested_into:` and the file remains in `docs/memory/facts/` (F3); marking
+   happens last, after the doc write.
+4. **Pillar-contradicting card → brainstorm proposal, not a doc edit.** A planted card negating a
+   doctrine/decision headline produces a propose-Brainstorming-Mode item and zero doc/pillar
+   edits; it is neither digested nor backlogged (Resolution 4, F5).
+5. **Conflict surfaces as a question.** A card disagreeing with doc prose yields a D7-phrased
+   QUESTION, never a silent rewrite (Resolution 2, F4).
+6. **Declined delta → backlog at par, deduped.** Declining produces one P-tiered backlog line
+   interleaved with code items; a second decline adds nothing (D10).
+7. **Docs without relevant cards untouched.** A doc no card touches is never opened or modified;
+   a run with an empty working set reports "no undigested cards touch {target}" and changes
+   nothing.
+8. **Idempotent via the digestion mark.** An immediate re-run on the same doc finds its touching
+   cards already `digested_into:` that doc and is a clean NOOP — the digestion mark is to `docs`
+   mode what inbox consumption is to `facts` mode (F3).
+9. **Trigger budget.** Exactly one line added to `CLAUDE.md` Completion; exactly one line added to
+   maintenance Step 7. No procedure inlined into either (P10).
+10. **Not autonomous.** No cron/daemon/hook; invoked by the Completion step, by accepting
+    maintenance's threshold proposal, or by direct user request only (P6).