@nurix/etna 0.18.0 → 0.18.1

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

@@ -5,215 +5,86 @@ description: The one place captured session lessons are distilled into colder, h
 
 # Distiller Skill
 
-The one place a repo's **captured session lessons** are distilled into colder,
-higher-signal knowledge. The memory inbox (`docs/memory/inbox/{actor}.md`) is a
-per-actor queue of lessons the `session-reflect` hook extracted at session end;
-the distiller reconciles the *surprising* part of it into atomic, self-contained,
-provenance-linked **fact-cards** (`docs/memory/facts/`) and consumes the entries
-it digests. 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 inbox-consumption
-> protocol. This SKILL.md only orchestrates those mechanisms over the inbox.
-
-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.
+The one place a repo's **captured session lessons** are distilled into colder, higher-signal knowledge. The memory inbox (`docs/memory/inbox/{actor}.md`) is a per-actor queue of lessons the `session-reflect` hook extracted at session end; the distiller reconciles the _surprising_ part of it into atomic, self-contained, provenance-linked **fact-cards** (`docs/memory/facts/`) and consumes the entries it digests. 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 inbox-consumption protocol. This SKILL.md only orchestrates those mechanisms over the inbox.
+
+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 inbox 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.
+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 inbox
-holds entries, then `docs` which still drafts for approval), or when the user
-accepts the `maintenance` agent's threshold proposal (≥5 undigested inbox
-entries). It never schedules itself, never runs on a hook, never gates anything.
+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 inbox holds entries, then `docs` which still drafts for approval), or when the user accepts the `maintenance` agent's threshold proposal (≥5 undigested inbox entries). It never schedules itself, never runs on a hook, never gates anything.
 
 ---
 
 ## Mode: `facts` (inbox → fact-cards)
 
-Distill the inbox's undigested entries into fact-cards. The algorithm is in
-[`references/method.md`](references/method.md) — follow it; this section is the
-procedure that sequences it.
-
-1. **Collect the inbox.** Read every entry block
-   (`## <timestamp> · session <id> · <repo>@<branch>`) across
-   `docs/memory/inbox/*.md`. The inbox is a consume-on-digest queue — what is
-   present is exactly what is undigested, so there is no separate high-water
-   mark. An immediate second run finds an empty inbox and is a clean NOOP.
-
-   **Thin or empty inbox ⇒ not a NOOP — distill the decision record.** A
-   project whose sessions produced no reflected lessons 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 inbox 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 inbox.
-   Provenance points at the ADR file / brainstorm section, not a session id.
-   These sources are **never consumed** — reconciliation (step 4) is what keeps
-   a re-run over them idempotent.
-
-2. **Surprisal filter → survivors** (method §1). Present the LLM with (a) a
-   summary of the *current* fact-set, (b) the undigested entries. Keep only
-   what is **surprising** relative to (a). Predictable ⇒ dropped — no importance
-   scores, no templates, prediction error is the only retention signal. Inbox
-   entries arrive semi-distilled (the reflection hook already dropped routine
-   work), so the filter's job here is narrower: drop what the existing fact-set
-   already predicts. (First run, empty fact-set: 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 at the session
-   ids and commits its inbox entry names. Decomposition, **not** summarization:
-   one survivor may yield several cards; no information is destroyed; everything
-   stays auditable back to its session and commits.
-
-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.
+Distill the inbox's undigested entries into fact-cards. The algorithm is in [`references/method.md`](references/method.md) — follow it; this section is the procedure that sequences it.
+
+1. **Collect the inbox.** Read every entry block (`## <timestamp> · session <id> · <repo>@<branch>`) across `docs/memory/inbox/*.md`. The inbox is a consume-on-digest queue — what is present is exactly what is undigested, so there is no separate high-water mark. An immediate second run finds an empty inbox and is a clean NOOP.
+
+   **Thin or empty inbox ⇒ not a NOOP — distill the decision record.** A project whose sessions produced no reflected lessons 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 inbox 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 inbox. Provenance points at the ADR file / brainstorm section, not a session id. These sources are **never consumed** — reconciliation (step 4) is what keeps a re-run over them idempotent.
+
+2. **Surprisal filter → survivors** (method §1). Present the LLM with (a) a summary of the _current_ fact-set, (b) the undigested entries. Keep only what is **surprising** relative to (a). Predictable ⇒ dropped — no importance scores, no templates, prediction error is the only retention signal. Inbox entries arrive semi-distilled (the reflection hook already dropped routine work), so the filter's job here is narrower: drop what the existing fact-set already predicts. (First run, empty fact-set: 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 at the session ids and commits its inbox entry names. Decomposition, **not** summarization: one survivor may yield several cards; no information is destroyed; everything stays auditable back to its session and commits.
+
+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."
+   - **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. **Consume the digested entries LAST.** Only after every card is written,
-   delete exactly the entry blocks this run digested from
-   `docs/memory/inbox/*.md` (keep each file's header; never touch undigested
-   blocks). Last, so a crash mid-run leaves the entries in place and the re-run
-   re-digests them — reconciliation NOOPs the already-written cards. This
-   consumption is the only bookkeeping; there is no `.digest-state.md`.
-
-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 inbox queue 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 (to the `prompt-recall` hook, 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. The `prompt-recall` hook's vector fallback only sees embedded
-     cards, so skipping this hides new cards from prompt-time recall.
-
-8. **Report** (in chat). Cards added / updated / superseded / NOOP'd, the
-   entries consumed 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 in the inbox," don't pad.
+6. **Consume the digested entries LAST.** Only after every card is written, delete exactly the entry blocks this run digested from `docs/memory/inbox/*.md` (keep each file's header; never touch undigested blocks). Last, so a crash mid-run leaves the entries in place and the re-run re-digests them — reconciliation NOOPs the already-written cards. This consumption is the only bookkeeping; there is no `.digest-state.md`.
+
+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 inbox queue 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 (to the `prompt-recall` hook, 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. The `prompt-recall` hook's vector fallback only sees embedded cards, so skipping this hides new cards from prompt-time recall.
+
+8. **Report** (in chat). Cards added / updated / superseded / NOOP'd, the entries consumed 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 in the inbox," 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.
+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.
-- **Consume, never rewrite.** `docs/memory/inbox/` is a queue owned by the
-  `session-reflect` capture hook. The distiller deletes exactly the entry blocks
-  it digested this run — no edits, no reordering, no touching undigested blocks.
-  Beyond that consumption it writes only under `docs/memory/facts/`.
-- **Idempotent via consumption.** What is in the inbox is what is undigested.
-  Consume last; a second run finds an empty inbox and is a NOOP.
-- **Cards are atomic and provenance-linked.** One self-contained statement per
-  card; every card resolves back to the session ids and 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.
+- **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.
+- **Consume, never rewrite.** `docs/memory/inbox/` is a queue owned by the `session-reflect` capture hook. The distiller deletes exactly the entry blocks it digested this run — no edits, no reordering, no touching undigested blocks. Beyond that consumption it writes only under `docs/memory/facts/`.
+- **Idempotent via consumption.** What is in the inbox is what is undigested. Consume last; a second run finds an empty inbox and is a NOOP.
+- **Cards are atomic and provenance-linked.** One self-contained statement per card; every card resolves back to the session ids and 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` reads `docs/memory/inbox/`, writes fact-cards to
-  `docs/memory/facts/{kebab-slug}.md`, and deletes the consumed entry blocks
-  from the inbox; the report goes to chat.
-- `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).
+- `facts` reads `docs/memory/inbox/`, writes fact-cards to `docs/memory/facts/{kebab-slug}.md`, and deletes the consumed entry blocks from the inbox; the report goes to chat.
+- `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).