@nurix/etna 0.14.0 → 0.15.2

package/data/harnesses/code/skills/distiller/references/method.md

@@ -0,0 +1,166 @@
+# Distillation Method — the algorithm spec
+
+The shared knowledge root for the `distiller` skill. Every mode reads this file.
+It carries the four mechanisms the distiller runs, the fact-card format, and the
+high-water-mark protocol.
+
+**These methods are stolen, not invented.** Each is sourced to its primary paper
+with an arXiv id — provenance matters here of all places. Embed them faithfully;
+do not paraphrase the retention signal away.
+
+---
+
+## The four methods
+
+### 1. Surprisal filter — *what to keep* (Nemori, arXiv:2508.03341)
+
+Present the LLM with **(a)** a summary of the *current* fact-set, and **(b)** the
+new undigested ledger entries. Keep only what is **surprising** relative to
+(a) — what the existing knowledge would **not** have predicted. Predictable ⇒
+dropped.
+
+No importance scores. No emotional tags. No templates. **Prediction error is the
+only retention signal.**
+
+> **First run, empty fact-set.** With nothing to predict against, "predictable" =
+> mechanical routine — e.g. a bare commit echo, or a transient exit-1 with no
+> lesson attached. Keep decisions, reversals, discovered constraints, and
+> failures with a cause worth remembering. Drop the rote.
+
+**Surprisal sources are not only ledger entries.** The ledger is the *default*
+stream, but the retention signal is prediction error wherever it lives. On a
+commit-less or thin-ledger project — where the ledger holds only droppable
+mechanical entries — the decision record carries the surprise instead:
+`docs/architecture/adr/**` (each accepted ADR is, by construction, a decision the
+prior knowledge would not have predicted) and `docs/memory/brainstorm.md`
+(reversals, owner pronouncements, discovered constraints). Treat these as
+input (b) alongside any ledger entries; the filter (keep the surprising, drop the
+predictable) is unchanged. Provenance then points at the ADR file or brainstorm
+section rather than a ledger `#HH:MM`.
+
+(Independently corroborated by Honcho's "Dream" — same prediction-error
+retention, arrived at separately.)
+
+### 2. Fact-card representation — *non-lossy EDUs* (EMem, arXiv:2511.17208)
+
+Each survivor becomes **ONE atomic, self-contained statement** — an Elementary
+Discourse Unit (EDU). Entity names normalized; the minimal context needed to
+stand alone baked into the sentence itself. Each card carries **provenance**: the
+ledger entries and/or commits it derives from.
+
+This is **decomposition, not summarization.** No information is destroyed; one
+survivor may decompose into several cards; everything stays auditable back to the
+raw ledger.
+
+### 3. Reconciliation — *consistency* (Mem0, arXiv:2504.19413)
+
+For each candidate card, retrieve the existing facts' **semantic neighbors**,
+then decide one of:
+
+- **ADD** — genuinely new fact; write a new card.
+- **UPDATE** — refines/extends a known fact; edit the existing card in place,
+  extend its provenance.
+- **SUPERSEDE** — contradicts/replaces a known fact; invalidate the old, write
+  the new (see §4).
+- **NOOP** — already known; write nothing.
+
+Neighbor retrieval: `qmd query --format json -c {repo}-facts "<statement>"`
+(scope with `-c`, one collection) — **only when the `{repo}-facts` collection
+exists** (`qmd collection list` shows it). The gate is the collection, not the
+binary: a present qmd whose facts collection has never been built (first run)
+returns nothing useful. **Fallback when the collection is missing** — qmd absent,
+*or* present but `{repo}-facts` not yet built: filename / grep similarity over
+`docs/memory/facts/*.md` (slug overlap + entity-name grep), and note in the
+report that reconciliation ran without semantic retrieval.
+
+### 4. Bi-temporal supersession — *never delete* (Zep/Graphiti, arXiv:2501.13956)
+
+Superseding **never deletes.** On the **old** card, set `invalid_from:` (the date
+it stopped being true) and `superseded_by:` (the new fact's id), and **leave the
+file in place.** Write the **new** card with today's `valid_from:`. The old fact
+stays queryable as history; nothing vanishes.
+
+This is the *valid-time* axis of a bi-temporal model — a fact is true within
+`[valid_from, invalid_from)`; transaction time is the git history of the file.
+
+#### Self-contained reversal — *both cards in one pass*
+
+`SUPERSEDE` (§3) assumes the old fact already lives as a card. But a single input
+can state a reversal whole — "X was decided, then reversed to Y" in one sentence
+(e.g. brainstorm.md: *single-tenant → multi-tenant, same session*; or an ADR
+whose **Options Considered** (the `documentation` §10 ADR template's
+rejected-alternatives section) names a path "proposed and reversed within the
+brainstorm"). Here there is no pre-existing X card to invalidate — both X and Y
+arrive together.
+
+Emit **two cards in one pass**:
+
+1. A **born-invalid historical card for X** — the superseded decision. Write it
+   with `valid_from:` (when X was decided, if known, else the input date),
+   `invalid_from:` (when it was reversed — the same date, for an in-session
+   reversal), and `superseded_by:` pointing at Y's fact-id. It is created already
+   carrying its own death so the reversal stays auditable.
+2. A **live card for Y** — the decision that won. `valid_from:` the reversal date,
+   `invalid_from: null`, `superseded_by: null`.
+
+Both share the input's provenance (the one ADR / brainstorm line). This is the
+ADD-side mirror of SUPERSEDE: SUPERSEDE invalidates a card that already exists;
+the self-contained reversal *manufactures* the invalidated card so the
+abandoned-X history is recorded rather than silently dropped.
+
+---
+
+## Fact-card format (`docs/memory/facts/{kebab-slug}.md`)
+
+```markdown
+---
+id: fact-{slug}
+valid_from: YYYY-MM-DD
+invalid_from: null          # set on supersession — never delete the file
+superseded_by: null         # fact-id
+entities: [qmd, anchors, maintenance]
+provenance: [ledger/YYYY-MM-DD--{actor}.md#HH:MM, commit abc123]
+---
+One atomic, self-contained statement of the fact, entities normalized.
+```
+
+- `id` — `fact-{slug}`, the slug matching the filename.
+- `valid_from` — the date the fact became true (the entry/commit date, or the
+  distill date if no better signal).
+- `invalid_from` — `null` until superseded; then the date it stopped being true.
+  **Never delete the file** to express invalidity — set this field.
+- `superseded_by` — `null`, or the `fact-id` of the card that replaced it.
+- `entities` — normalized names the fact concerns (used by the grep fallback and
+  by retrieval).
+- `provenance` — the ledger entries (`ledger/YYYY-MM-DD--{actor}.md#HH:MM`) and
+  commits this card decomposes from. Must resolve back to raw.
+- The body — exactly one atomic, self-contained statement. Entities normalized,
+  context baked in, so the card stands alone.
+
+---
+
+## High-water-mark protocol (`docs/memory/facts/.digest-state.md`)
+
+The mark is what makes the distiller idempotent. Frontmatter records, **per
+actor**, the last-digested ledger file and entry timestamp.
+
+```markdown
+---
+# per-actor high-water mark — last ledger entry digested into facts
+last_digested:
+  joyjeet-sarkar: { file: ledger/2026-06-04--joyjeet-sarkar.md, entry: "00:31" }
+  claude: { file: ledger/2026-06-08--claude.md, entry: "14:32" }
+---
+High-water mark for the facts distiller. Read first, advanced last.
+```
+
+**Protocol:**
+
+1. **Read it first.** Absent ⇒ start of history — digest every ledger entry.
+2. Process only entries **newer** than each actor's mark.
+3. **Advance it last** — only after every card is written. Last, so a crash
+   mid-run causes a re-digest (safe — reconciliation NOOPs the already-written
+   cards) rather than a silent skip of un-digested entries.
+
+A second run immediately after a successful one finds nothing past the mark and
+is a clean NOOP.

package/data/harnesses/code/skills/documentation/references/templates.md

@@ -77,7 +77,7 @@ Use for: defining which folder owns which topic and how docs are maintained.
 
 ```
 ---
-harness-version: 10
+harness-version: 12
 ---
 
 # Documentation Structure
@@ -124,7 +124,7 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 <!-- Updated by maintenance agent -->
 | Date | Review Summary |
 | ---- | -------------- |
-| {today} | Initial baseline — v9 structure established |
+| {today} | Initial baseline — v{harness-version} structure established |
 ```
 
 ---
@@ -142,12 +142,15 @@ touches:
   - src/shared/utils/feature-helper.js
 depends_on:
   - docs/architecture/system-design.md
+anchors:
+  - "qmd query: feature-name persistence shape"
 ---
 ```
 
 - `owns`: Glob patterns for files this feature doc is the canonical reference for
 - `touches`: Files this feature interacts with but doesn't own
 - `depends_on`: Other docs that must be read for full context
+- `anchors` (optional): A list of qmd queries (or `#docid`s) that re-resolve to the code/facts this doc abstracts as they move; anchors are retrieval context plus a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, nothing auto-rewrites from an anchor result, and the doc's prose stays the human-owned abstraction. They detect **doc-area drift** (the subject moving or vanishing from the corpus), not a pure code rename — the query also matches the doc's own prose, so a rename that leaves the text unchanged won't shift the result; code-symbol drift is the maintenance named-referent check's job, and anchors complement it rather than replace it. Resolved via `qmd query --format json -c <collection>` against this repo's collections; absent qmd ⇒ anchors are inert (no error). Never required on any doc. The feature and boundary templates ship the exemplar, but `anchors:` may appear on any living doc the maintenance anchor-drift check globs — `docs/features/`, `docs/boundaries/`, `docs/architecture/`, and `docs/operations/` — so the convention and the check stay one mental model.
 
 ---
 
@@ -240,8 +243,17 @@ description: Shared knowledge accumulated across agent sessions. All agents shou
 ## Documentation Baseline
 
 - **Baselined:** {today}
-- **Structure:** v9 (architecture, features, operations, history, memory; + boundaries/, modules/, tests/ when present)
-- **Spec version:** v9
+- **Structure:** v{harness-version} (architecture, features, operations, history, memory; + boundaries/, modules/, tests/ when present)
+- **Spec version:** v{harness-version}
+<!-- v{harness-version} resolves to the installed design epoch — read it from `.claude/harness.json` (`epoch`) / `docs/structure.md` frontmatter (`harness-version`); never hardcode a literal version here. -->
+
+## Knowledge Tiers
+
+Memory is a gradient — volume falls, signal rises, one hop down each tier. Tiers describe themselves here even before they fill:
+
+- **Ledger** (`docs/memory/ledger/`) — raw, high-volume dump tier. Hooks append every decision/action/observation/failure as it happens (one day-file per actor). The firehose, rarely read directly.
+- **Fact-cards** (`docs/memory/facts/`) — distilled, provenance-linked atomic facts, written by the distiller (`facts` mode) from undigested ledger entries. `.digest-state.md` holds the high-water mark.
+- **This index** — the curated read tier: the learnings list below, distilled from the colder tiers and hand-appended.
 
 ## Learnings
 
@@ -272,6 +284,8 @@ Append entries below, oldest at bottom. Format:
 Memory file initialized during documentation baseline.
 ```
 
+> The per-day event **ledger** (`docs/memory/ledger/`) is *not* a baseline scaffold — hooks create its day-files mechanically on first event. See **§12 Memory ledger entry** for its format.
+
 ---
 
 ## 5. Boundary File (docs/boundaries/{boundary}.md)
@@ -321,6 +335,11 @@ When mapping a boundary (the `boundary` skill's `generate`/`create` job — this
 One file per boundary in `docs/boundaries/`. The `boundary` skill emits typed files using its boundary taxonomy; this is the generic fallback shape.
 
 ```markdown
+---
+anchors:                    # optional — see §3 frontmatter reference
+  - "qmd query: store slice rehydration fallback"
+---
+
 # {Boundary Name}
 
 [BOUNDARY: {type} · {severity}]   <!-- type from the Application Boundary Scale; severity CRITICAL | HIGH | MED | LOW -->
@@ -329,7 +348,8 @@ One file per boundary in `docs/boundaries/`. The `boundary` skill emits typed fi
 
 ## Shape
 <!-- `transcribe`: a synthesized contract with no single code home (composed store tree, API envelope, the IA entity model, tenancy) — written inline, canonical here.
-     `point`: a self-locating shape (DB schema, route table) — a `file:line` pointer + invariants. Never copy a self-locating shape; it rots on the next change. -->
+     `point`: a self-locating shape (DB schema, route table) — a `file:line` pointer + invariants. Never copy a self-locating shape; it rots on the next change.
+     greenfield/pre-code `point` (contract decided, no code yet — e.g. boundary generate after a brainstorm): there's no file:line to point at, so instead (a) record the decided conventions inline here, (b) add a `planned <path>` line naming where the canonical source will land (e.g. `planned packages/api/src/db/schema.ts`), and (c) mark this row `point*` in the README index. Converts to (or gains) a real file:line pointer when the module lands. README index footnote: "* point-mode boundary whose pointer lands at implementation". -->
 
 ## Invariants
 <!-- The rules that must hold across the boundary. -->
@@ -357,6 +377,8 @@ touches:
   - src/shared/state/feature.js
 depends_on:
   - docs/features/related-feature.md
+anchors:                    # optional — see §3 frontmatter reference
+  - "qmd query: wire envelope invariants"
 ---
 ```
 
@@ -874,3 +896,54 @@ src/
 The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
 
 **Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.
+
+---
+
+## 12. Memory ledger entry (docs/memory/ledger/YYYY-MM-DD--{actor}.md)
+
+Use for: the raw, high-volume **dump tier** of the knowledge gradient — every decision, action, observation, and failure, appended as it happens. Hooks write it mechanically; humans rarely read it directly. It is the raw input to distillation: the durable `docs/memory/` files (index, main, agent) are the curated read tier; this is the firehose they're distilled from.
+
+### File grain
+
+One file per day **per actor**: `docs/memory/ledger/YYYY-MM-DD--{actor}.md`. `actor` is `git config user.name` lowercased and kebab-slugged; fall back to `$USER`, then `agent`. Because two actors working the same day write to different files, the ledger is **append-only without merge conflicts** — no shared file to contend over, no lock, no last-writer-wins.
+
+### Day-file header
+
+Written once, on the first event of a given day-file:
+
+```
+# Ledger — YYYY-MM-DD — {actor}
+Append-only event ledger. Raw input to distillation — see docs/memory/.
+```
+
+### Entry shape
+
+One block per event, 1–5 lines. Never the full tool I/O — one line of `what`, optionally one of `why`. `why` and `refs` are omitted when empty.
+
+```
+## HH:MM · {actor} · {repo}@{branch}
+- type: decision | action | observation | failure
+- what: <one line>
+- why: <one line — optional>
+- refs: <commit hashes / file paths / session id — optional>
+```
+
+### Examples
+
+```
+## 14:02 · jane-doe · etna@dev
+- type: action
+- what: task "bump structure scaffold to harness v11", 6 turns, 1 file edited
+- refs: session a1b2c3d4 · 1 files
+
+## 14:09 · jane-doe · etna@dev
+- type: failure
+- what: deploy script rejected auth header Authorization: [redacted:api-key]
+- why: stale key in .env.local — rotated, see docs/operations/setup.md
+```
+
+### Rules
+
+- **Append, never edit.** The ledger records what was true when written; corrections go in a later entry, not by rewriting an old one.
+- **Secrets are redacted on write.** The privacy filter replaces secret shapes with `[redacted:{kind}]` (e.g. `[redacted:api-key]`, `[redacted:bearer]`, `[redacted:pem]`) before any line is appended — never paste a raw token in by hand either.
+- **Don't curate here.** Patterns worth keeping get promoted to `docs/memory/main.md` (or an agent file) during distillation; the ledger stays a raw, lossy-by-volume dump.

package/data/harnesses/kb-agi/CLAUDE.md

@@ -13,7 +13,7 @@ keywords:
 plugin: kb-agi
 ---
 
-# nuStack Knowledge Hub — router
+# NuStack Knowledge Hub — router
 
 This repo is a flat Obsidian vault that you read on the user's behalf. It's the bridge from the front (positioning, claims) to the back (product and service specs); detailed execution lives downstream in the service repos.
 

package/data/harnesses/kb-agi/agents/kb-agi-init.md

@@ -151,7 +151,7 @@ Upkeep is run by the kb-agi agents (invoked by name); there is no `meta/goals/`
 ````markdown
 # genre — Sales
 
-The reader is positioning nuStack to someone else: a prospect, a partner, a teammate who needs the pitch. They want the claim and the proof behind it, not the implementation.
+The reader is positioning NuStack to someone else: a prospect, a partner, a teammate who needs the pitch. They want the claim and the proof behind it, not the implementation.
 
 **Default depth.** Start crisp. Lead with the answer in one or two sentences — what we can do, what makes it different — then offer the supporting detail rather than front-loading it. Go deeper only when the question reaches for it ("how exactly…", "what's underneath…").
 
@@ -213,7 +213,7 @@ This is a living index. It is hand-maintained today and kept fresh by the `kb-re
 ---
 
 ## "I want to understand the product"
-_What nuStack is, what it can do, the claims and their proof._
+_What NuStack is, what it can do, the claims and their proof._
 
 - _populated on migration_
 

package/data/harnesses/kb-agi/agents/kb-catch-stale.md

@@ -6,7 +6,7 @@ model: inherit
 plugins: [kb-agi]
 ---
 
-You are the **kb-catch-stale** goal-agent for the nuStack knowledge hub. One job: surface notes that have drifted out of date.
+You are the **kb-catch-stale** goal-agent for the NuStack knowledge hub. One job: surface notes that have drifted out of date.
 
 **Read first:** `meta/guidance.md` (the note model, `maturity` + `canonical` hints) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
 

package/data/harnesses/kb-agi/agents/kb-find-gaps.md

@@ -1,12 +1,12 @@
 ---
 name: kb-find-gaps
-description: Audits the nuStack vault for missing notes — diffs each folder's metadata.md and the session gap-logs against the note graph to find coverage holes. Use when asked to find gaps, check coverage, or "what's missing". Proposes a ranked gap list by default; writes notes ONLY when the invocation explicitly asks it to.
+description: Audits the NuStack vault for missing notes — diffs each folder's metadata.md and the session gap-logs against the note graph to find coverage holes. Use when asked to find gaps, check coverage, or "what's missing". Proposes a ranked gap list by default; writes notes ONLY when the invocation explicitly asks it to.
 tools: Read, Grep, Glob, Bash
 model: inherit
 plugins: [kb-agi]
 ---
 
-You are the **kb-find-gaps** goal-agent for the nuStack knowledge hub. You have exactly one job: find what the vault should hold but doesn't, and surface it.
+You are the **kb-find-gaps** goal-agent for the NuStack knowledge hub. You have exactly one job: find what the vault should hold but doesn't, and surface it.
 
 ## First, read the contract
 

package/data/harnesses/kb-agi/agents/kb-fix-links.md

@@ -6,7 +6,7 @@ model: inherit
 plugins: [kb-agi]
 ---
 
-You are the **kb-fix-links** goal-agent for the nuStack knowledge hub. One job: keep the note graph sound — no dead links, no orphans.
+You are the **kb-fix-links** goal-agent for the NuStack knowledge hub. One job: keep the note graph sound — no dead links, no orphans.
 
 **Read first:** `meta/guidance.md` (the note model) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
 

package/data/harnesses/kb-agi/agents/kb-refresh-frontdoor.md

@@ -6,7 +6,7 @@ model: inherit
 plugins: [kb-agi]
 ---
 
-You are the **kb-refresh-frontdoor** goal-agent for the nuStack knowledge hub. One job: keep the entry points pointing at the right notes.
+You are the **kb-refresh-frontdoor** goal-agent for the NuStack knowledge hub. One job: keep the entry points pointing at the right notes.
 
 **Read first:** `meta/guidance.md` (the note model, `canonical` hint) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
 

package/data/harnesses/kb-agi/agents/kb-refresh-summaries.md

@@ -6,7 +6,7 @@ model: inherit
 plugins: [kb-agi]
 ---
 
-You are the **kb-refresh-summaries** goal-agent for the nuStack knowledge hub. One job: keep summary notes current with the raw material beneath them.
+You are the **kb-refresh-summaries** goal-agent for the NuStack knowledge hub. One job: keep summary notes current with the raw material beneath them.
 
 **Read first:** `meta/guidance.md` (the note model, the `maturity` ladder) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
 

package/data/harnesses/kb-agi/agents/kb-sync-metadata.md

@@ -6,7 +6,7 @@ model: inherit
 plugins: [kb-agi]
 ---
 
-You are the **kb-sync-metadata** goal-agent for the nuStack knowledge hub. One job: keep folder `metadata.md` files honest.
+You are the **kb-sync-metadata** goal-agent for the NuStack knowledge hub. One job: keep folder `metadata.md` files honest.
 
 **Read first:** `meta/guidance.md` (the note model + the fixed `metadata.md` shape) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
 

package/data/harnesses/kb-agi/harness.json

@@ -0,0 +1,6 @@
+{
+  "name": "kb-agi",
+  "version": "0.10.0",
+  "epoch": null,
+  "digest": "8973cf3a762d"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.14.0",
+    "version": "0.15.2",
     "description": "Bootstrap a project with a Nurix harness — installs a Claude Code plugin from the nurixlabs/skills marketplace and drops the harness's CLAUDE.md at the project root.",
     "type": "module",
     "bin": {

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

@@ -1,99 +0,0 @@
-# Greenfield writing doctrine
-
-> **The reader has no past.** They've never seen an earlier version of the system, never heard of the alternative you considered, never knew about the repo you were going to fold in. Write for them.
-
-For projects with nothing built yet — no production deploys, no users, no legacy code — architecture docs describe the system as it **will be**, in present tense. The temptation to narrate the design journey ("we considered X, chose Y, dropped Z") produces documents full of phantoms — references to things the reader has no way to imagine.
-
-These rules apply equally to the first draft and to subsequent edits. After every design decision, the architecture doc should look as though the chosen option was always the plan.
-
----
-
-## The rule
-
-Describe what the system **is** (or will be — same thing in greenfield). Never describe what it isn't, used to be, replaces, supersedes, or is migrating from.
-
-There is no past tense in a doc for software that doesn't exist yet.
-
----
-
-## Banned patterns
-
-| Don't write | Why it's wrong | Write instead |
-|---|---|---|
-| "X replaces Y" / "X supersedes Y" | Reader doesn't know Y. | "X is the [role]." |
-| "Previously planned" / "originally proposed" / "we used to" | There is no previous. | Describe the current plan. |
-| "What was dropped" / "What we ruled out" sections | Only useful when readers carry a stale model. | Move reasoning to `decisions.md` if load-bearing; otherwise delete. |
-| `~~strike-through~~` text | Tracks edits for live readers; pollutes fresh docs. | Delete the struck text. Keep the surviving prose. |
-| "ex-Foo", "from ex-Bar" annotations on packages | Repo-fold bookkeeping. | Just name the package. |
-| "Folded into monorepo" / `import-legacy.sh` / migration scripts | Migration mechanic, not architecture. | Describe the monorepo as the steady state. |
-| "v1 vs v2" / "future migration target" | Implies one is becoming the other. | Describe v1. Phase-2 ideas can be a "future scope" subsection without "migration" framing. |
-| "(existing — `~/dev/foo`)" / "no build needed" markers | Differentiates from non-existing; in greenfield everything is to-build. | Just list the service. |
-| "There is no foo_table" / "we don't have a foo service" | Reader didn't expect one. | Don't mention it. |
-| "Per Decision-N resolution" inline citations on every paragraph | Architecture doc isn't a decision log. | Plain prose. One cross-ref per section, only when the *why* is non-obvious. |
-| "Resolved (was: open question)" / "(retired)" markers | Edit-history bookkeeping. | Delete — the resolution **is** the doc now. |
-| "What this kills" / "Trade-off accepted" headings | Decision-capture format leaking into architecture. | Keep these in `decisions.md` only. |
-| "We no longer X" / "X is no longer needed" | Reader had no expectation that X existed. | Don't mention X. |
-| "Renamed from foo to bar" / "(formerly known as …)" | The rename doesn't matter — only the current name does. | Use the current name. |
-
----
-
-## Smell-words grep
-
-`stop` runs this automatically. Manual invocation:
-
-```sh
-grep -rEni \
-  'replaces|supersedes|superseded|previously|formerly|originally proposed|what was dropped|fully retired|~~|ex-[a-z-]+|folded in|import-legacy|migration target|migrate from|no longer|we used to|resolved per|renamed from|formerly known' \
-  plan/
-```
-
-In a clean greenfield architecture doc, this should return no hits in `01–NN` numbered docs.
-
-Hits **are** acceptable in:
-- `decisions.md` — scoped to a specific decision-capture entry.
-- `rejected.md` — scoped to a rejected alternative.
-- `references.md` — describing external prior art.
-- Commit messages and PR descriptions.
-- `./plan/sources/` — copies of input documents (not authored under these rules).
-
----
-
-## Where the past DOES belong
-
-- `decisions.md` — alternatives + why the chosen option won, **only** when the reasoning isn't obvious from the architecture itself.
-- `rejected.md` — paths considered and rejected.
-- `references.md` — external prior art.
-- Commit messages, PR descriptions — what changed and why; lives in git, not docs.
-
-These are the only four places. Architecture docs (`01-foo.md`, `02-bar.md`, ...) are present-tense.
-
----
-
-## What's still allowed (don't over-correct)
-
-- **Forward planning that names a phase** ("ships in M7 so the bus already knows about `lead.created` when CRM sync arrives") — describes a positive future, not a past.
-- **Constraint statements** ("we accept a 5-second tile lag for predictable server load") — current tradeoffs, stated as facts. Live in `decisions.md`, not architecture.
-- **Cross-refs** ("see `04 §4.3`") — pointers, not history.
-- **Negative assertions about external systems** ("the upstream service has no native fan-in") — describing a real third-party limitation is fine.
-- **Future-scope subsections** ("Phase 2 considerations") — labelled clearly, not framed as migrations.
-
----
-
-## Before merging an architecture doc, ask
-
-1. If a brand-new collaborator read this section cold, would they need to know about the alternative I'm comparing to? If no, delete the comparison.
-2. Does the section read as present-tense description, or as a story of "we went from X to Y"? Rewrite the story form.
-3. Are there strike-throughs? Delete them.
-4. Does an open-questions list still contain resolved items? Move them to `decisions.md` and drop from the list.
-5. Are there inline "(per Decision-X)" citations sprinkled through the prose? Strip — keep at most one cross-ref per section.
-
----
-
-## Why this matters
-
-A greenfield doc that reads like a migration guide signals two things to a new reader:
-
-1. **There is hidden context I don't have.** Every "previously" / "replaces" makes them wonder what they're missing.
-2. **The author is still in the middle of deciding.** Strike-throughs and "(resolved)" markers feel provisional.
-
-Both undermine the doc's authority. A clean greenfield doc reads as an act of architecture, not an act of revision.

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

@@ -1,44 +0,0 @@
-# Inventory
-
-This file is the **authoritative list of components in scope** — services, repos, packages, databases, external integrations. It answers the question "what are we actually building?" and stops the team from inventing services that already exist or "folding in" things that should stay separate.
-
-The inventory is grouped by category (application monorepo, edge services, shared packages, managed externals, reference-only prior art). Each entry carries a **status**:
-
-- **build** — in scope, we're constructing this in this project.
-- **external** — managed elsewhere (third-party SaaS, another team's service). We integrate with it but don't own it.
-- **reference** — prior art we read or copy patterns from but do not deploy.
-
-Do **not** mark items as "retired", "deprecated", or "previously planned" — if it's not being built or used, omit it. (See the greenfield doctrine.) The inventory describes the steady state, not the history of how the steady state was arrived at.
-
-When scope changes (a service moves from "build" to "external", a non-goal flips to a build, a planned component gets dropped), update this file immediately and run a semantic sweep across plan docs.
-
----
-
-## A. Application monorepo
-
-| Name | Status | Notes |
-|---|---|---|
-| (example: `apps/gateway`) | build | (one-line role) |
-| (example: `apps/web`) | build | (one-line role) |
-
-## B. Edge services
-
-| Name | Status | Notes |
-|---|---|---|
-
-## C. Shared packages
-
-| Name | Status | Notes |
-|---|---|---|
-
-## D. Managed externals
-
-| Name | Status | Notes |
-|---|---|---|
-| (example: Temporal Cloud) | external | (one-line — what we use it for) |
-
-## E. Reference / prior art
-
-| Name | Status | Notes |
-|---|---|---|
-| (example: `~/dev/vibe/foo-poc`) | reference | (what pattern we borrow from it) |