@nurix/etna 0.15.7 → 0.16.0

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

@@ -0,0 +1,35 @@
+# Open Questions
+
+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.
+
+The session is **coherent** exactly when this file is empty after a fresh sync. That makes hygiene load-bearing:
+
+- 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.
+
+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.
+
+IDs are `QN`, stable while open, never reused after deletion.
+
+---
+
+## Q1 — [Title in the user's words]
+
+**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.]
+
+**Raised by.** user | sync | probe
+
+**Closes when.** [What resolution looks like — a pick between options, a confirmed fact, an accepted risk.]
+
+**Options.** *(optional — only when named by the user or entering converge)*
+- A. [one line]
+- B. [one line]
+
+**Lean.** *(optional — the user's lean, never the skill's)*
+
+**Claude's take.** *(opt-in only — write only when the user asks for a recommendation on this question; delete if it goes stale)*
+
+**Resolution lands in.** *(optional)* [pillar or doc + section]
+
+**Blocks.** *(optional)* [milestone or other Q-numbers]

package/data/harnesses/code-fable/skills/brainstorm/templates/references.md

@@ -0,0 +1,28 @@
+# References
+
+This file collects **external prior art** — repos, docs, papers, talks — with one-line pointers to what we use each for. Reference implementations beat invented solutions: if someone has already solved the problem you're about to design, the right move is to link it here and use it, not re-derive.
+
+References are not bookmarks. Every entry should answer the question "what specific pattern, idea, or implementation do we lift from this?" A reference without that grounding decays into noise. If you can't write the one-line "what we use it for", you probably don't need the entry.
+
+References to **source materials** copied into `./plan/sources/` during the session also live here — point at the local copy, not the original location. This keeps the brainstorm self-contained.
+
+When a referenced thing changes (renames, moves, deprecation), **update or remove the entry**. A stale reference that no longer points at what the description claims is worse than no reference — it teaches the reader to distrust the file.
+
+---
+
+## Internal repos / paths
+
+- `~/path/to/repo` — [what pattern we borrow]
+- `~/path/to/another` — [what pattern we borrow]
+
+## Source materials (this session)
+
+- `./plan/sources/[file]` — [original location, why it's relevant]
+
+## External docs
+
+- `https://example.com/foo` — [what we use it for]
+
+## Papers / talks
+
+- [Title] — [link or citation] — [the specific idea we're applying]

package/data/harnesses/code-fable/skills/brainstorm/templates/rejected.md

@@ -0,0 +1,29 @@
+# Rejected alternatives
+
+This file captures **paths that were considered and rejected**, with the reason for rejection. Its purpose is to prevent re-litigation: when someone proposes the same alternative six weeks later, this file answers "we already looked at that; here's why we didn't go that way."
+
+Each entry needs three load-bearing parts: **Considered** (what was proposed, in concrete terms), **Rejected because** (the specific reason — "didn't fit" is useless to future-you; name the constraint, the cost, the risk), and **Re-evaluate if** (what would need to change for the rejected path to become viable again). The re-evaluate field stops the rejection from looking permanent when it isn't — most rejections are scope-conditional, not absolute.
+
+This is one of the four places inside the brainstorm folder where past tense and "we considered X" framing is permitted (the others: `decisions.md`, `references.md`, git history). The whole point of this file is to capture the path-not-taken so future architects don't have to re-discover it.
+
+If circumstances change and a rejected path becomes attractive again, **do not silently revive it**. Add a new question to `questions.md` that references the rejection here, and resolve it explicitly. The new decision can override the rejection — but it should override, not pretend the rejection never happened.
+
+---
+
+## R1 — [Rejected option]
+
+**Considered.** [What was proposed.]
+
+**Rejected because.** [The reason. Be specific.]
+
+**Re-evaluate if.** [What would change to make this viable.]
+
+**Came up during.** [Q-number or D-number for context.]
+
+---
+
+## R2 — [Rejected option]
+
+(same format)
+
+---

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

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

package/data/harnesses/code-fable/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-fable/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-fable/skills/distiller/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: distiller
+description: The one place captured session lessons are distilled into colder, higher-signal knowledge. One skill, two modes — `facts` (memory inbox → 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. Consumes the inbox entries it digests (the inbox is a queue, not an audit log — git history and commit/session provenance are the audit trail); NEVER auto-runs (invoked by the user, or by accepting the maintenance agent's threshold proposal). Triggers on "distill the inbox", "distill facts", "run the distiller", "distill into fact-cards", "facts from the inbox", "distill docs", "draft doc deltas", "distiller docs", "/distiller".
+---
+
+# 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.
+
+---
+
+## 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.
+
+## 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.
+
+---
+
+## 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.
+
+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. **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.
+
+---
+
+## 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.
+
+## 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).