@nurix/etna 0.18.0 → 0.18.2

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

@@ -1,526 +0,0 @@
-# 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).