@nurix/etna 0.14.0 → 0.15.2

package/data/harnesses/code/skills/brainstorm/harvest.md

@@ -0,0 +1,26 @@
+# Harvest adapter
+
+Harvest is **optional and offered, never assumed**. By default the session folder is the product: a self-contained registry the next `/brainstorm start` resumes from. Run this adapter only when (a) the repo is v9-harnessed — `docs/architecture/` and `docs/modules/` exist — and (b) the user accepts the offer at `stop`.
+
+## Routing
+
+The harvest is a structured diff between the session pillars and the live docs, routed by scope: module-local findings → `docs/modules/{m}/pillars/`, cross-module → `docs/architecture/`, IA/contract changes → `docs/boundaries/` (via the `boundary` skill), backlog → `docs/history/`.
+
+| Session source | Destination |
+|---|---|
+| `thesis.md` narrative | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft, `documentation` skill §8 Plan template) |
+| `domain-model.md` | `docs/architecture/domain-model.md`; if it changes the IA or a cross-cutting contract, **flag for the `boundary` skill (`create`)** — don't hand-write boundary files |
+| Decisions spanning 2+ modules | one ADR per cohesive theme → `docs/architecture/adr/ADR-NNN-{slug}.md`, authored to the **`documentation` skill §10 ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
+| Module-local decisions / doctrine / glossary / rejected | `docs/modules/{m}/pillars/{decisions,doctrine,glossary,rejected}.md` |
+| Cross-module doctrine / glossary | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md` |
+| `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
+| `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
+| `backlog.md` | `docs/history/backlog.md` (P0–P3) |
+| Still-open questions | `docs/architecture/open-questions.md`, each with a *Resolution lands in* pointer |
+| `build.md` (brownfield/hybrid: migration strategy, gotchas, rollout) | the plan doc in `docs/history/plans/` — execution content is plan content, not architecture |
+
+Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harvest-{slug}.md` listing what was written where.
+
+## After harvest
+
+Offer to delete the session folder (the dispersed homes now carry the content; the next session primes from them by copying relevant docs into `basis/`). Default to **keep** if the user is unsure — a kept folder simply resumes.

package/data/harnesses/code/skills/brainstorm/templates/build.md

@@ -0,0 +1,37 @@
+# Build
+
+This pillar holds **how the work gets executed** — decided during brainstorming, not deferred to plan mode. Migration constraints and execution gotchas discovered late invalidate designs; surfacing them here, while the design is still fluid, is the point.
+
+At `start` the skill asks: *"Is this greenfield, or are we changing something that exists?"* The answer sets **Mode** below and opens or closes the execution sections. The sync agent treats this file as a contradiction source — a decision that implies migration work with no entry here raises a question.
+
+## Mode
+
+`greenfield` *(default)* | `brownfield` | `hybrid`
+
+- **greenfield** — nothing built yet: no production deploys, no users, no legacy code. The execution sections below are closed — mark them *Not applicable (greenfield)*. **Writing posture:** all pillars describe the system as it *will be*, in present tense, as though the chosen design was always the plan. Banned: "replaces" / "supersedes" / "previously" / "formerly" / "no longer" / "originally proposed" / `~~strikethrough~~` / "(resolved)" markers — the reader has no past, so don't reference one. Past tense lives only in `decisions.md`, `rejected.md`, `references.md`, and git history.
+- **brownfield** — the idea changes a system that already exists. All sections below are live, and migration vocabulary — "replaces", "currently", "migrate from" — is legitimate and load-bearing **in this file**. Other pillars still describe the *target* state in present tense; the journey from here to there lives here.
+- **hybrid** — a new surface attached to a live system (a new module in a shipping product). The sections below apply to the seams only: integration points, shared state, contract changes. The new surface itself follows greenfield posture.
+
+## Current state
+
+*(brownfield/hybrid)* What exists today, as relevant to the change. Link code paths or docs rather than restating them.
+
+## Target state
+
+One or two orienting sentences — cross-reference `thesis.md` rather than duplicating it.
+
+## Migration strategy
+
+How we get from current to target: phases, order of operations, coexistence windows, rollback points. Harvest routes this section into the implementation plan.
+
+## Gotchas
+
+Execution hazards known *now*, before plan mode — each one a bullet with why it bites:
+
+- [e.g. data backfill must run before the new index exists, or reads 404 during the window]
+- [e.g. auth cutover can't be phased — sessions are shared, it's all-or-nothing]
+- [e.g. the event consumer is not idempotent; dual-write window will double-process]
+
+## Rollout & risks
+
+Sequencing, feature flags, kill switches, and the failure modes each phase accepts.

package/data/harnesses/code/skills/brainstorm/templates/decisions.md

@@ -1,42 +1,29 @@
 # Decisions
 
-This file is the **append-only ledger of resolved decisions**. Every decision the brainstorm produces lands here, with the reasoning that future-you will need to judge edge cases.
+This file is the **append-only ledger of resolved decisions**, with the reasoning future-you needs to judge edge cases.
 
-Each entry has these load-bearing fields:
+Load-bearing fields:
 
-- **Status** — `tentative | committed | rescinded`. New decisions land as `tentative` (no cascade dispatched, question stays open in `questions.md`). User explicitly says "commit" to lock in (cascade fires, question deletes). User explicitly says "rescind" to reverse (cascade reversals if previously committed, question restored if needed).
 - **Decision** — what was decided, in one or two sentences.
-- **Why** — the motivation: a past incident, a constraint, a deadline, a stakeholder ask. Without the *why*, decisions decay into rules no one understands.
-- **How to apply** — when and where this decision should shape future work. Without it, decisions get ignored at the boundaries where they matter most.
+- **Why** — the motivation: a constraint, an incident, a deadline, a stakeholder ask. Without the *why*, decisions decay into rules no one understands.
+- **How to apply** — when and where this decision shapes future work. Name the files, layers, or situations where it kicks in.
 
-This file is **append-only**. If a decision is reversed, mark it `STATUS: rescinded` with the reason — do not delete the entry. The ledger is a record of what was true (or proposed) when it was written. It is one of the four places inside the brainstorm folder where past tense is permitted (the others: `rejected.md`, `references.md`, git history).
+There is no tentative/committed state machine. A decision is a decision the moment it's written; the next sync handles its ripples. **Reversing** a decision = append a new decision that names what it reverses, add a one-line `Reversed by D-M (YYYY-MM-DD)` note to the old entry, and let the sync raise questions for anything downstream.
 
-When a question in `questions.md` is resolved, the question is **NOT** immediately deleted — it is marked tentatively-answered (referenced by the new decision's `Resolves Q-N` field). The question is deleted only when the decision transitions to `committed`. This gives the user space to reverse a tentative call without restoring text by hand.
+This ledger is one of the places where past tense is permitted (with `rejected.md`, `references.md`, `build.md`'s execution sections, and git history).
 
 ---
 
 ## D1 — [Title]
 
-**Status.** tentative
+**Decision.** [What was decided.]
 
-**Decision.** [What was decided, in one or two sentences.]
+**Why.** [The motivation future-you needs.]
 
-**Why.** [The motivation — past incident, constraint, deadline, stakeholder ask. The reason future-you needs to judge edge cases.]
+**How to apply.** [Where this rule kicks in — be specific.]
 
-**How to apply.** [When and where this decision shapes future work. Be specific — name the files, layers, or situations where this rule kicks in.]
+**Resolves.** Q1 (deleted from `questions.md`).
 
-**Resolves.** Q1 (deleted from `questions.md` on commit).
+**Alternatives considered.** *(optional — reference `rejected.md` if substantial)*
 
-**Alternatives considered.** [Optional. Reference `rejected.md` entries if substantial. Skip if obvious.]
-
-**Committed on.** [YYYY-MM-DD — filled when STATUS transitions to committed. Omit until then.]
-
-**Rescinded on.** [YYYY-MM-DD with one-line reason — filled when STATUS transitions to rescinded. Omit until then.]
-
----
-
-## D2 — [Title]
-
-(same format)
-
----
+**Reverses.** *(only when this decision reverses an earlier one — name it and say what changed)*

package/data/harnesses/code/skills/brainstorm/templates/domain-model.md

@@ -0,0 +1,25 @@
+# Domain model
+
+This file holds the **information architecture** of the idea: entities, relationships, cardinalities, and who owns what state. This is where facts like "an account has many leads" land the moment they're said — they are neither principles (`doctrine.md`) nor terms (`glossary.md`), and they must not be lost to the transcript.
+
+The loop's *abstract* step feeds this file: when the user implies structure without naming it, propose the entry here.
+
+## Entities
+
+### [Entity]
+
+[One paragraph: what it is, what state it owns, where it lives (client / server / external system).]
+
+## Relationships
+
+| From | To | Cardinality | Notes |
+|---|---|---|---|
+| Account | Lead | 1 : N | [e.g. leads cannot transfer between accounts — see D3] |
+
+Cardinality changes are design changes — when one shifts, expect the sync to raise questions against routing, storage, and milestones.
+
+## Invariants
+
+Rules the model must always satisfy, stated as present-tense facts:
+
+- [e.g. Every lead belongs to exactly one account at any point in time.]

package/data/harnesses/code/skills/brainstorm/templates/non-goals.md

@@ -1,12 +1,12 @@
 # Non-goals
 
-This file is the **explicit list of things we are not building** in the current scope, with the reason for each. It is the mirror of `inventory.md`: where inventory says "this is in scope", non-goals say "this looked plausible but is deliberately out".
+This file is the **explicit list of things we are not building** in the current scope, with the reason for each. It is the mirror of the scope described in `thesis.md`: where the thesis says "this is what we're building", non-goals say "this looked plausible but is deliberately out". Distinguish it from `backlog.md` (things we *will* build, just later) — a non-goal may never be built.
 
 Non-goals carry real weight. Every entry here is a constraint that future decisions should respect — a scope-creep guard. The reason field is load-bearing: without it, a non-goal looks like an arbitrary "no" that future-you will second-guess at the first complication. With the reason, future-you knows whether the non-goal still holds when circumstances change.
 
 Each non-goal should include a **Re-evaluate when** clause where applicable. Non-goals are not permanent vows; they are scope decisions tied to current constraints. When the constraint changes (a customer signs in a new region, a competitor ships the feature, infrastructure costs drop), the non-goal may move into scope. The re-evaluate clause names the trigger so the team doesn't carry a stale non-goal forever.
 
-At milestone boundaries, scan this file. If a non-goal's re-evaluate trigger has fired, move the item to `inventory.md` with status `build` and delete the non-goal entry here — do not strikethrough, do not leave a "(promoted)" marker.
+At milestone boundaries, scan this file. If a non-goal's re-evaluate trigger has fired, fold the item into scope (`thesis.md`, or `backlog.md` if it's planned-but-later) and delete the non-goal entry here — do not strikethrough, do not leave a "(promoted)" marker.
 
 ---
 

package/data/harnesses/code/skills/brainstorm/templates/questions.md

@@ -1,84 +1,35 @@
 # Open Questions
 
-This file is the **live ledger of unresolved concerns and pending decisions**. Every open design question or worry lives here, and only here — plan docs never host their own questions, they link back to this file with the relevant Q-numbers.
+This file is the **single convergence currency** of the session. Every unresolved design call lives here and only here — whether the user raised it, the sync agent found it, or a probe surfaced it. Plan docs and pillars never host their own questions; they link back here.
 
-Each question is **self-contained**: full text, optional options, optional lean, and where the resolution lands. You should be able to read any question and understand it without opening another doc. Duplicating one paragraph of context is much cheaper than the cognitive cost of context-switching.
+The session is **coherent** exactly when this file is empty after a fresh sync. That makes hygiene load-bearing:
 
-**In Explore mode**, questions land here in the user's framing — possibly just a concern stated in prose, without Options or Lean. That is fine. Captured concerns are valid questions even when their shape is fuzzy. Resist the urge to immediately structure them into A/B/C/D choices; that happens when the user invites decide-mode for a specific question.
+- Every entry must be **closeable** — the `Closes when.` field says what resolution looks like. Vague musings are not questions; distill them until they're closeable or leave them in the conversation.
+- Only **design-calls** belong here — items whose resolution changes the idea. Editorial bookkeeping is the sync agent's job, applied directly and noted in its report.
+- A resolved question is **deleted** (its decision lives in `decisions.md`). A parked question is deleted too, with an explicit entry in `backlog.md` or `non-goals.md`. No strikethrough, no "(resolved)" markers.
 
-When a question transitions through a decision flow:
-1. User signals "let's resolve Q-N" → enter decide mode for this Q.
-2. Decision lands in `decisions.md` with `STATUS: tentative`. **The question stays here**, in a tentatively-answered state (cross-reference the D-N).
-3. User says "commit D-N" → the question is **deleted** from this file. No strikethrough, no "(resolved)" marker.
-4. User says "rescind D-N" before commit → the question stays, the decision is marked rescinded.
+Each question is **self-contained**: full text in the user's framing, readable without opening another doc. Group under `## Category` headers when the list grows past ~10.
 
-When you add a new question, fill in fields the user has actually given you. Leave others blank. The dependency graph (`Blocks.` field) is computed only when the user moves into decide mode and needs sequencing.
+IDs are `QN`, stable while open, never reused after deletion.
 
 ---
 
-## Conventions
+## Q1 — [Title in the user's words]
 
-**Group questions by domain** when the list grows past ~10 entries. Use `## Category` headers (e.g. `## Data & Schema`, `## Runtime`, `## Connectors`). Categories are project-specific.
+**Question.** [Full prose — paraphrase what the user said, or state the contradiction/gap the sync found. Repeat context; a future reader should need nothing else.]
 
-**Question ID** is `QN` where N is the next free integer. IDs are stable for as long as the question is open. On commit-delete, the ID disappears with the question — do not reuse it.
+**Raised by.** user | sync | probe
 
-**Question body fields** (per entry):
+**Closes when.** [What resolution looks like — a pick between options, a confirmed fact, an accepted risk.]
 
-- **Question.** Full prose, may be multi-paragraph. Repeat context if needed. Use the user's words when capturing in Explore mode.
-- **Options.** *(optional)* Lettered list (A / B / C ...) with one-line description per option. Add only when the user has named alternatives, or when entering decide mode for this question.
-- **Lean.** *(optional)* The user's current preference, one line. Drop the field entirely if no lean exists yet — don't write "none yet". This field reflects the user's lean, not the skill's.
-- **Claude's take.** *(optional, OPT-IN ONLY)* The skill's recommendation. **Default: do not write this field.** Emit only when the user explicitly asks "what would you recommend?" / "what's your take?" / similar on this specific question. Phrase as a clear pick + one-line reason. If the field becomes stale (options change, scope shifts), delete it.
-- **Tentatively answered by.** *(only when a tentative D-N exists)* Cross-reference to `decisions.md`. Marks the question as in-flight rather than fully open.
-- **Resolution lands in.** *(optional)* Target doc + section (e.g. `04-runtime.md §3.2`). Tells the resolver where to absorb the answer.
-- **Blocks.** *(optional)* Milestone (`M0`) or other Q-numbers (`Q5, Q7`) that depend on this. Empty = "nothing yet".
+**Options.** *(optional — only when named by the user or entering converge)*
+- A. [one line]
+- B. [one line]
 
-**Extension sections** beyond plain questions are allowed:
+**Lean.** *(optional — the user's lean, never the skill's)*
 
-- `## Upstream feature requests` — items that aren't questions we own; they're features we need from upstream services. Use IDs like `U-foo-1`.
-- `## Doc completeness follow-ups` — work items that aren't decisions but should not be forgotten. Use IDs like `F1`, `F2`.
+**Claude's take.** *(opt-in only — write only when the user asks for a recommendation on this question; delete if it goes stale)*
 
-Resolved upstream-feature items and completed follow-ups get **deleted**, same rule as questions.
+**Resolution lands in.** *(optional)* [pillar or doc + section]
 
----
-
-## Q1 — [Title]
-
-**Question.** [Full text. Repeat context if needed — a future reader should be able to read this without leaving the doc. In Explore mode, capture in the user's words.]
-
-**Options.** *(optional — only when named by the user or entering decide mode)*
-- A. [Option A — what it means in one line]
-- B. [Option B]
-- C. [Option C]
-
-**Lean.** *(optional, user's lean)*
-
-**Tentatively answered by.** *(only if a tentative D-N exists)*
-
-**Resolution lands in.** *(optional)* `XX-foo.md` §N
-
-**Blocks.** *(optional)* [Milestone (e.g., M0) or other Q-numbers.]
-
----
-
-## Q2 — [Title]
-
-(same format)
-
----
-
-## Upstream feature requests *(optional section)*
-
-### U-foo-1 — [Title]
-
-[What we want from the upstream service.]
-
-**Why we want it.** [Reason — usually a current workaround that's costing us something.]
-
-[Current status: filed, tracked, ETA, etc.]
-
----
-
-## Doc completeness follow-ups *(optional section)*
-
-- **F1** — [Doc name + one-line scope]. [What triggers writing it.] [Which milestone it must precede.]
-- **F2** — [Doc name + one-line scope]. [What triggers writing it.] [Which milestone it must precede.]
+**Blocks.** *(optional)* [milestone or other Q-numbers]

package/data/harnesses/code/skills/brainstorm/templates/state.md

@@ -1,8 +1,8 @@
 STATE: open
-MODE: explore
+MODE: dump
+COMPLEXITY: medium
 SESSION STARTED: YYYY-MM-DD
 SESSION CLOSED:
-CURRENT TOPIC: (one-line summary — updated on every detected topic shift)
-LAST UPDATED: YYYY-MM-DD
-CASCADE LOCKS: none
-CASCADE QUEUE: none
+CURRENT TOPIC: (one line — updated on every topic shift)
+LAST SYNC: never
+SYNC IN FLIGHT: no

package/data/harnesses/code/skills/brainstorm/templates/tech.md

@@ -0,0 +1,23 @@
+# Tech
+
+This file holds the **technology choices** for the idea. It is seeded at bootstrap from the harness's opinionated stack (e.g. `.claude/rules/general.md` recommended-packages table) when one exists — those rows arrive as defaults, not decisions.
+
+Its job afterward is to be a **lens**: when a conversation move conflicts with a row here, the sync (or the skill, in the moment) surfaces it — *"you just proposed local component stores; the stack says Redux Toolkit — deviating or steering back?"* A confirmed deviation gets recorded below with its why; an unconfirmed conflict becomes an open question.
+
+## Stack
+
+| Layer | Choice | Source |
+|---|---|---|
+| [e.g. UI] | [react ^19] | harness default |
+| [e.g. state] | [@reduxjs/toolkit] | harness default |
+| [layer] | [choice] | decided this session — D[n] |
+
+## Deviations
+
+Each deviation from a harness default carries a why:
+
+### [Choice] instead of [default]
+
+**Why.** [Constraint, requirement, or incident that justifies the deviation.]
+
+**Scope.** [Whole project, or only a named module/surface.]

package/data/harnesses/code/skills/brainstorm/templates/thesis.md

@@ -0,0 +1,21 @@
+# Thesis
+
+This file is the **running narrative of what we are designing** — the single place a cold reader (or the next session) goes to understand the idea as it currently stands. It is rewritten freely as the idea evolves; it always describes the *current* shape, never the journey (writing posture per `build.md`'s mode).
+
+Keep it prose-first. If a section outgrows this file at high complexity, it may move to a numbered deep-dive doc (`01-foo.md`) at the session root with a one-line pointer left here.
+
+## What this is
+
+[2–5 paragraphs. What the thing is, who it's for, what it does. Distilled from the basis at `start` and kept current by the loop.]
+
+## Aspect map
+
+The thinking dimensions for *this* idea — proposed by the skill from the basis, edited by the user at `start`. The sync agent audits coverage against this list: an aspect with no content anywhere becomes an open question.
+
+- [ ] [aspect — e.g. users & jobs]
+- [ ] [aspect — e.g. domain model]
+- [ ] [aspect — e.g. architecture]
+- [ ] [aspect — e.g. tech]
+- [ ] [aspect — e.g. risks]
+
+Check an aspect only when it has real content in the pillars, not when it has merely been mentioned.

package/data/harnesses/code/skills/distiller/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: distiller
+description: The one place the raw event ledger is distilled into colder, higher-signal knowledge. One skill, two modes — `facts` (ledger → atomic provenance-linked fact-cards in `docs/memory/facts/`) and `docs` (fact-cards → proposed, human-approved doc deltas). Both modes read one shared algorithm spec, `references/method.md` (surprisal filter, EDU fact-cards, reconciliation, bi-temporal supersession — all stolen, all cited), so they can never drift apart. NEVER edits the ledger (append-only audit substrate); NEVER auto-runs (invoked by the user, or by accepting the maintenance agent's threshold proposal). Triggers on "distill the ledger", "distill facts", "run the distiller", "distill into fact-cards", "facts from the ledger", "distill docs", "draft doc deltas", "distiller docs", "/distiller".
+plugins: [code]
+---
+
+# Distiller Skill
+
+The one place a repo's **raw event ledger** is distilled into colder,
+higher-signal knowledge. The ledger (`docs/memory/ledger/`) is a high-volume,
+append-only stream of what happened; the distiller turns the *surprising* part of
+it into atomic, self-contained, provenance-linked **fact-cards**
+(`docs/memory/facts/`). Volume falls, signal rises — one hop down the
+distillation gradient.
+
+The methods this skill runs are **stolen, not invented** — surprisal-based
+retention (Nemori), non-lossy EDU fact-cards (EMem), per-fact ADD/UPDATE/
+SUPERSEDE/NOOP reconciliation (Mem0), and bi-temporal supersession (Zep/
+Graphiti). They live in exactly one place:
+
+> **Read [`references/method.md`](references/method.md) first, in every mode.**
+> It carries the four mechanisms verbatim-grade (with their arXiv ids — provenance
+> matters here of all places), the fact-card format, and the high-water-mark
+> protocol. This SKILL.md only orchestrates those mechanisms over the ledger.
+
+The reason the two modes are one skill: **both read one algorithm root.** Two
+components would mean two copies of the surprisal/reconciliation/supersession
+model that drift apart. One skill, one spec, zero drift.
+
+---
+
+## Picking a mode
+
+| You want to… | Mode | Ships |
+|---|---|---|
+| Distill new ledger entries into fact-cards | **`facts`** | now |
+| Distill fact-cards into proposed doc deltas | **`docs`** | now — procedure in [`references/docs-mode.md`](references/docs-mode.md) |
+
+Both modes read [`references/method.md`](references/method.md); each mode's
+procedure that sequences it lives in its own section below.
+
+## Execution model — pure skill, never autonomous
+
+Runs **in the main session** — no standing sub-agents, no daemon, no cron, no
+watch. The harness **proposes**, the user **disposes**: this skill runs only when
+the user asks, when the **Completion flow** invokes it (the kit `CLAUDE.md`
+Completion step distils the just-finished plan's trail — `facts` if the ledger
+advanced past the high-water mark, then `docs` which still drafts for approval),
+or when the user accepts the `maintenance` agent's threshold proposal (≥20
+undigested ledger entries). It never schedules itself, never runs on a hook,
+never gates anything.
+
+---
+
+## Mode: `facts` (ledger → fact-cards)
+
+Distill ledger entries newer than the high-water mark into fact-cards. The
+algorithm is in [`references/method.md`](references/method.md) — follow it; this
+section is the procedure that sequences it.
+
+1. **Read the high-water mark.** Read `docs/memory/facts/.digest-state.md`
+   (the frontmatter records the last-digested file + entry timestamp **per
+   actor**). Absent ⇒ start of history — digest everything. Then collect ledger
+   entries from `docs/memory/ledger/YYYY-MM-DD--{actor}.md` that are **newer**
+   than the per-actor mark. This is what makes the run idempotent — an immediate
+   second run finds nothing new and is a clean NOOP.
+
+   **Thin or empty ledger ⇒ not a NOOP — distill the decision record.** A
+   commit-less project, or one whose ledger holds only mechanical entries the
+   surprisal filter would drop (a transient exit-1, a bare echo), is **not** a
+   project with nothing to distill. Architecture decisions and reversals are
+   high-surprisal by nature — they exist precisely because they were *not*
+   predictable. So when the ledger is thin/empty, also ingest, as surprisal
+   sources for steps 2–5:
+   - `docs/architecture/adr/**` — each accepted ADR is a surprising decision
+     (its `Decision` + **Options Considered** — the rejected-alternatives section
+     in the `documentation` §10 ADR template — carry the prediction error).
+   - `docs/memory/brainstorm.md` — owner pronouncements, reversals, and
+     discovered constraints recorded outside the ledger.
+   Provenance points at the ADR file / brainstorm section, not a ledger
+   `#HH:MM`. These sources sit outside the high-water mark (which tracks ledger
+   entries only) — reconciliation (step 4) is what keeps a re-run idempotent.
+
+2. **Surprisal filter → survivors** (method §1). Present the LLM with (a) a
+   summary of the *current* fact-set, (b) the new undigested entries. Keep only
+   what is **surprising** relative to (a). Predictable ⇒ dropped — no importance
+   scores, no templates, prediction error is the only retention signal. (First
+   run, empty fact-set: "predictable" = mechanical routine — a bare commit echo,
+   a transient exit-1 with no lesson; keep decisions, reversals, discovered
+   constraints, and failures with a cause worth remembering.)
+
+3. **Decompose survivors → EDU candidates** (method §2). Each survivor becomes
+   **one** atomic, self-contained statement — entity names normalized, minimal
+   context baked into the sentence — with `provenance` pointing back at the
+   ledger entries/commits it derives from. Decomposition, **not** summarization:
+   one survivor may yield several cards; no information is destroyed; everything
+   stays auditable back to raw.
+
+4. **Reconcile each candidate against existing cards** (method §3). Query the
+   existing facts for semantic neighbors, then decide
+   **ADD / UPDATE / SUPERSEDE / NOOP** for each. Gate on the **facts collection
+   holding cards**, not on the binary and not on the collection merely being
+   registered — a present qmd whose `{repo}-facts` collection is *registered but
+   empty* (the common first run: harness-manager's baseline registers + embeds
+   `{repo}-facts` over a freshly-scaffolded `docs/memory/facts/` that has zero
+   cards) returns nothing useful, exactly like an unregistered collection.
+   - **Cards present** — `command -v qmd` succeeds **and** `docs/memory/facts/`
+     holds at least one card (`docs/memory/facts/*.md` is non-empty): query
+     scoped to the collection —
+     `qmd query --format json -c {repo}-facts "<the candidate statement>"`.
+     `{repo}` = the repo's directory name. Scope with `-c` always. (If the query
+     returns nothing on a non-empty card set, the collection is registered-but-
+     unbuilt — treat that as the fallback trigger below, not as "no neighbors.")
+   - **No cards to query** (qmd absent, **or** `docs/memory/facts/*.md` empty —
+     the common first-run case where the facts dir was scaffolded but never
+     distilled into): fall back to filename/grep similarity over
+     `docs/memory/facts/*.md` (slug overlap + entity-name grep), and **note in
+     the report** that reconciliation ran without semantic retrieval. Step 7
+     builds/refreshes the collection at the end of the run, so the *next* run —
+     with cards now present — reconciles semantically.
+
+5. **Write the results** (method §4 — bi-temporal, never delete).
+   - **ADD** → write a new card `docs/memory/facts/{kebab-slug}.md` in the format.
+   - **UPDATE** → refine the existing card's statement in place; extend its
+     `provenance`.
+   - **SUPERSEDE** → on the **old** card set `invalid_from:` (today) and
+     `superseded_by:` (the new fact-id); write the **new** card with `valid_from:`
+     today. The old file stays in place — history stays queryable, nothing
+     vanishes.
+   - **Self-contained reversal** (one input states X-then-reversed-to-Y, no old
+     card exists yet) → emit **two** cards in one pass: a born-invalid historical
+     card for X (`invalid_from` + `superseded_by` → Y) and a live card for Y.
+     See method.md §4 "Self-contained reversal."
+   - **NOOP** → the fact is already known; write nothing.
+
+6. **Update the high-water mark LAST.** Only after every card is written, update
+   `docs/memory/facts/.digest-state.md` to the newest entry timestamp processed
+   per actor. Last, so a crash mid-run re-digests rather than silently skips.
+
+7. **If qmd present, refresh the lens** (skip silently if `command -v qmd`
+   finds nothing):
+   - `qmd collection add docs/memory/facts --name {repo}-facts` — register the
+     collection. Re-adding an existing name exits non-zero with "already exists";
+     **treat that as success.** Never register `docs/memory` as a whole — that
+     would sweep the raw ledger into the index.
+   - `qmd context add qmd://{repo}-facts/ "Distilled recent decisions/observations, provenance-linked"`
+     — upserts, safe to re-run.
+   - `qmd update` — **re-scan the collection for the cards you just wrote.** In
+     qmd 2.5.3 `collection add` on an already-registered name does NOT re-index
+     new files; `qmd update` is what picks them up. Skipping this leaves the new
+     cards invisible to retrieval (and to distill②).
+   - `qmd embed -c {repo}-facts` — regenerate vectors for the new/changed cards.
+     Always scope with `-c`; a bare `qmd embed` re-embeds every repo on the
+     machine.
+
+8. **Report** (in chat). Cards added / updated / superseded / NOOP'd, the
+   high-water mark advance per actor, and — if reconciliation fell back to
+   filename/grep (qmd absent, **or** `{repo}-facts` registered but holding no
+   cards yet — the first-run-on-a-scaffolded-facts-dir case) — the one advisory
+   line saying so. Fire this advisory whenever semantic retrieval was effectively
+   unavailable, even if the collection appeared in `qmd collection list`: a
+   registered-but-empty collection is not semantic retrieval. A run that finds
+   nothing surprising is **valid**: say
+   "no surprising entries since the mark," don't pad.
+
+---
+
+## Mode: `docs` (fact-cards → proposed doc deltas)
+
+Distill fact-cards into proposed edits to `docs/` (the cold, human-owned SSoT) —
+the next hop down the gradient from `facts`. The full procedure (input selection,
+delta drafting, digestion marking, the pillar escape valve, trigger wiring) is in
+[`references/docs-mode.md`](references/docs-mode.md) — follow it; reuses
+`method.md`'s surprisal / EDU / reconciliation / bi-temporal vocabulary unchanged.
+It NEVER writes a doc on its own — it **drafts and presents**; the human disposes.
+
+---
+
+## Rules
+
+- **One algorithm root.** Every mode reads `references/method.md`. Extend the
+  spec there — never inline a divergent copy of the four methods in a mode.
+- **Never edit the ledger.** `docs/memory/ledger/` is the append-only audit
+  substrate. The distiller is **read-only** on it — no deletes, no rewrites, no
+  reordering, not even archiving. It writes only under `docs/memory/facts/`.
+- **Idempotent via the mark.** The high-water mark is the only thing standing
+  between this skill and reprocessing. Read it first, advance it last; a second
+  run with no new entries is a NOOP.
+- **Cards are atomic and provenance-linked.** One self-contained statement per
+  card; every card resolves back to the ledger entries/commits it came from.
+  Decompose — never lossily summarize.
+- **Supersede ≠ delete.** Bi-temporal only: set `invalid_from:` +
+  `superseded_by:` on the old card and leave the file in place. Nothing is ever
+  removed from `docs/memory/facts/`.
+- **Findings are questions, not verdicts.** When a candidate appears to
+  contradict an existing card, phrase it as a question (is X now superseded by
+  Y?) — never assert staleness or falsity.
+- **Never auto-runs.** Invoked by the user, by the Completion flow (kit
+  `CLAUDE.md`), or by accepting the maintenance proposal. No cron, no daemon, no
+  hook self-trigger — a workflow step the agent runs is not a self-trigger.
+- **qmd is strictly optional.** Guard every qmd call on `command -v qmd`; absent
+  ⇒ silent skip. Reconciliation additionally needs the `{repo}-facts` collection
+  to hold **cards** — not merely to be registered. "Unbuilt" here means **no
+  cards** (`docs/memory/facts/*.md` empty), not "unregistered": harness-manager's
+  baseline registers + embeds `{repo}-facts` over an empty scaffolded facts dir,
+  so on a qmd-equipped, freshly-baselined repo the collection *appears in*
+  `qmd collection list` yet indexes zero cards. Binary present but collection
+  cardless (first run) falls back to filename/grep too, same as qmd being absent.
+
+## Output locations
+
+- `facts` writes fact-cards to `docs/memory/facts/{kebab-slug}.md` and the
+  high-water mark to `docs/memory/facts/.digest-state.md`; the report goes to
+  chat. It reads `docs/memory/ledger/` but never writes there.
+- `docs` presents doc deltas in chat and, **only on approval**, writes the accepted
+  prose into the target doc under `docs/` (+ a new `docs/history/changelog/` entry if
+  drafted) and appends `digested_into:` to each consumed card in `docs/memory/facts/`.
+  See [`references/docs-mode.md`](references/docs-mode.md).