@nurix/etna 0.18.0 → 0.18.1

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

@@ -1,73 +1,47 @@
 # 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 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:
+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.
+> **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.
+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.
+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). |
+| **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).
+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:
+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.
+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
 
@@ -77,100 +51,54 @@ distiller docs --feature <slug>      # just-completed feature → resolve to its
 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.
+`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").
+> 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).
+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.
+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.
+   - `--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. 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**.
+   - 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.
+   - **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*
+### 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.
+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:
+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.
+- **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.
+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):
+The output of this step is a **single presented delta document** (in chat, not written to disk):
 
 ```
 TARGET: docs/features/memory-capture.md
@@ -198,61 +126,38 @@ TARGET: docs/features/memory-capture.md
 ──────────────────────────────────────────────────────────
 ```
 
-### 4. PRESENT and await disposition — never auto-write (locked default #4) — *the gate itself*
+### 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:
+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).
+- **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.
+- **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*
+### 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):
+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.
+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*.
+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*
+### 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:
+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.
+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**.
+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**.
 
 ---
 
@@ -260,72 +165,37 @@ run where no undigested card touches the target is **valid**: say "no undigested
 
 ### 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 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.
+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. |
+| --- | --- | --- |
+| **`## 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.
+| **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
 
@@ -337,7 +207,7 @@ 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
+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]
@@ -345,67 +215,28 @@ 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.
+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.
+- **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:
+**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) ───────────────
@@ -418,109 +249,51 @@ and never an auto-entry into Brainstorming Mode:
   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.)
+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:
+**(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:
+**(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).
+`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.
+**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).
+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).