@nurix/etna 0.18.20 → 0.18.22

package/data/harnesses/etna/rules/general.md

@@ -1,5 +1,7 @@
 # General Standards
 
+Runtime versions and the canonical package list — the workspace baseline every Nurix code harness loads. Web-frontend/styling conventions are [`frontend.md`](frontend.md); the Express server and the API response envelope are [`express.md`](express.md).
+
 ## Runtime Versions
 
 - **Node.js:** 22 LTS (latest)
@@ -45,43 +47,3 @@ No alternatives. Just use these.
 | fast-deep-equal          | ^3.1.3    | Deep equality checks   | lodash.isEqual             |
 | @ngneat/falso            | latest    | Fake data generation   | @faker-js/faker, chance    |
 | pino                     | ^10.1.0   | Logging                | winston                    |
-
-## Frontend
-
-Tailwind v4 + shadcn-based UI; conventions below.
-
-- **Build every UI through the `design` skill** — route the brief through it instead of hand-rolling layouts; it owns the archetype, personality tokens, and `@nurix/components` wiring.
-- **Light mode is the default** — design for the light theme as the default; dark mode is opt-in, never the default.
-- **@nurix/\* are restricted-scope npm packages** — installed from the npm registry, auto-authed by a read token in `~/.npmrc`. Just attempt the install; the token authenticates you automatically. Don't pre-empt or second-guess it. If the install actually fails, flag it to the user — never reach for alternatives, a substitute package, or `npm login`.
-- **@nurix/components** — the UI component library (restricted-scope npm package, pre-built); import by subpath, e.g. `@nurix/components/button`.
-- No components.json / shadcn CLI scaffold (.tsx, not .jsx) — consume the prebuilt library; never `npx shadcn add`.
-- Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin react / react-dom / react/jsx-runtime / react/jsx-dev-runtime to the app's single copy via `resolve.alias` (@nurix/\* ship nested react — keep one hook dispatcher).
-- Tailwind v4, CSS-only (no tailwind.config.js, no PostCSS): styling runs through the `@tailwindcss/vite` plugin.
-- CSS entry `globals.css`, imports in order — `@import "./personality.css"` (token source) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
-- Tokens: CSS vars in `:root, :root[data-theme="light"]` + the archetype selector `[data-style="…"]` (personality.css), consumed as semantic Tailwind tokens (bg-card, text-foreground). Honor the archetype's radius/theme decisions (e.g. re-assert `--radius-*` to 0 for a flat archetype; add `@custom-variant dark` only if the project opts into dark mode, and keep light as the default). The library bundles class-variance-authority, clsx, tailwind-merge.
-- Plus general styling rules (spacing in 2/4/6/8, object-cover, truncate, motion, color tokens — never hardcoded hex in components).
-
-## Express 5.x
-
-```javascript
-app.use(cors({ origin: process.env.FRONTEND_URL }));
-app.use(compression());
-app.use(express.json({ limit: '10mb' }));
-app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
-```
-
-- Middleware order: body parsers → custom middleware → routes → error handlers (centralized, last). Auth via middleware. Use Express Router for modular routes.
-
-## API Response Format
-
-```json
-{
-  "status": 1,
-  "message": "Message sent successfully",
-  "data": { "delivered": [{ "user@example.com": 2 }] }
-}
-```
-
-Error: `{ "status": 0, "message": "Error description", "data": null }`
-
-HTTP codes: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`

package/data/harnesses/etna/rules/nomenclature.md

@@ -31,11 +31,4 @@
 
 ## Database
 
-Naming for D1 tables, columns, indexes, and their Drizzle mirrors. (For column **types** — PK shape, timestamp columns — see the Cloudflare D1 Schema rule, not here; this section governs names only.)
-
-- **Tables** : snake_case. Entity / hub tables use the plural noun for the thing they hold. Examples: `users`, `apps`, `devices`, `services`.
-- **Junction (M:N) tables** : name a many-to-many join `<entityA>_<entityB>_map` — **always**, even when the join carries its own columns (a `role`, a secret, a status). The `_map` suffix is the signal that a row is a relationship, not an entity; extra attributes on the join do **not** earn it a standalone noun. Use the **singular** stem of each side, owning/anchor entity first (mirror the existing tables — `app_*`). Examples: `app_user_map` (apps ⨯ users), `app_device_map` (apps ⨯ devices), `app_service_map` (apps ⨯ services).
-  - ❌ Don't invent a "nice" noun for a junction — no `members`, `installs`, `memberships`, `enrolments`. A reviewer should read the table name and know both sides and that it's a join.
-- **Columns** : snake_case. Foreign keys are `<entity>_id` (`user_id`, `app_id`, `device_id`, `service_id`). Booleans follow the boolean rule (`is_*`/`has_*`); timestamps are `created_at` / `updated_at`.
-- **Indexes** : `<table>_<col(s)>_idx`; unique indexes `<table>_<col(s)>_unique`. The composite unique on a junction reads `<table>_<colA>_<colB>_unique` — e.g. `app_user_map_app_user_unique`, `app_device_map_device_app_unique`.
-- **Drizzle mirror** : the exported table object is the camelCase of the snake_case table name (`app_user_map` → `appUserMap`); column TS properties are the camelCase of the column (`created_at` → `createdAt`, `service_key` → `serviceKey`). The snake_case string passed to `sqliteTable("…")` and every index name must match `seed/init.sql` exactly (the G1 schema-parity boundary).
+Table, column, index, and key naming for relational schemas — the `id` / `slug` / `label` vocabulary, junction `_map` tables, and Drizzle mirrors — lives in [`database.md`](database.md), the cross-project database conventions rule. Kept there, not here, so there is one canonical home and the same concept carries the same name in every project.

package/data/harnesses/etna/skills/brainstorm/README.md

@@ -128,13 +128,13 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
 
 ## Exit artifacts
 
-The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
+The session writes a design record at `docs/research/{topic}-brainstorming/` (one folder per topic), moved to `docs/history/brainstorms/{topic}/` on harvest. At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
 
 - **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
 - **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
-- **Harvest into the living docs** — conclusions dispersed by scope into ADRs, the domain model, and the backlog.
+- **Harvest into the living docs** — conclusions dispersed by scope into ADs (architecture decisions), the domain model, and the backlog.
 
-The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never deleted; it is the provenance every artifact traces back to. See `exit-artifacts.md`.
+The session record is **kept** whichever you pick — never deleted; on harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance every artifact traces back to. See `exit-artifacts.md`.
 
 ---
 
@@ -159,4 +159,4 @@ brainstorm/                  # the skill (in .claude/skills/)
 └── templates/        # pillar templates + evidence.md + source-of-truth.md, used in the record and at stop
 ```
 
-The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.
+The session itself is written to `docs/research/{topic}-brainstorming/` (committed; moved to `docs/history/brainstorms/{topic}/` on harvest) — not here.

package/data/harnesses/etna/skills/brainstorm/SKILL.md

@@ -42,6 +42,8 @@ Write as if the transcript is already deleted — it will be. The folder must le
 
 ## `start`
 
+First, consult the two indexes — never scan folders. `docs/research/Readme.md` lists **active** sessions; `docs/history/brainstorms/Readme.md` lists **harvested** ones. Match the topic against both: an active match → resume it (§3, reusing its folder); a harvested match → surface that prior exploration and ask whether to reopen it (move the folder back to `docs/research/{topic}-brainstorming/`) or branch a fresh topic; no match → a new session. Then:
+
 ### 1. The entry gate
 
 A session needs substance before it opens. Ask for a **basis**: a reference document (path or URL), or a one-shot brain dump of the whole idea, right now, in prose.
@@ -62,7 +64,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
 
 ### 3. Bootstrap
 
-Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
+Session folder: `docs/research/{topic}-brainstorming/` — a **committed** design record, one folder per design topic (slug the topic; confirm it in one line). Add a row to the `docs/research/Readme.md` index. Resume an existing topic by reusing its folder if it already holds a `state.md`. The record lives here while the session is active; on close **and** harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance the exit artifacts distil from (see `stop` and `exit-artifacts.md`). Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
 
 ```
 STATE: open
@@ -136,8 +138,8 @@ Zero means _"audited against the five sources and clean"_ — never _"nothing ca
 
 1. Run a final sync (wait for any in-flight sync first). It audits all five sources — self-containment included, so the record is verified standalone-readable exactly when it is about to become the only survivor of the session.
 2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off. Flag parked **self-containment** gaps distinctly: parking one means the record ships not fully standalone.
-3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
-4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
+3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADs — architecture decisions — the domain model, the backlog). The session record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
+4. Write `STATE: closed` + one-line reason. If the harvest is complete (conclusions dispersed into the living docs), **move** the folder from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/` and update both indexes — drop its row from `docs/research/Readme.md`, add it to `docs/history/brainstorms/Readme.md`. If the session is only paused (questions parked, more to come), leave it in `docs/research/` and update its index row's status. Print: _"Run `/brainstorm start` to resume."_
 
 ## Conduct — holds for the whole session
 

package/data/harnesses/etna/skills/brainstorm/exit-artifacts.md

@@ -1,8 +1,9 @@
 # Exit artifacts
 
-What `/brainstorm stop` publishes from a closed session. The `docs/brainstorm/{topic}/` record is **kept
+What `/brainstorm stop` publishes from a closed session. The session record is **kept
 either way** — committed provenance, never a scratchpad. Exit artifacts copy the session's _conclusions_
-outward into the form the work needs; the record stays as the source they trace back to.
+outward into the form the work needs; the record stays as the source they trace back to — and, once
+harvested, moves from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/`.
 
 At `stop`, after the final sync, **offer the artifact choice** (`AskUserQuestion`, multi-select — a session
 can publish more than one):
@@ -21,7 +22,7 @@ does; pick it too if you want both the one-doc reference and the integrated head
 
 One consolidated, README-style document — the canonical reference for the thing designed. Distil every
 pillar into it: `thesis.md` → what it is; `domain-model.md` → how it works + parts; `decisions.md` →
-present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADRs);
+present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADs);
 `non-goals.md` + accepted tradeoffs → constraints; still-open questions → a one-line pointer back to the
 record. Template: `templates/source-of-truth.md`.
 
@@ -44,19 +45,22 @@ not folders — a finding scoped to one module still lands in `docs/architecture
 
 | Session source | Destination |
 | --- | --- |
-| Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md` (`documentation` skill ADR template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the ADR's Options Considered table) |
+| Decisions (any scope) | one AD per decision subject → `docs/architecture/decisions/AD-NNN-{slug}.md` (`documentation` skill AD template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the AD's Options Considered table). A decision that revises an already-recorded subject does **not** mint a new AD — update that AD's body in place and append the revision to its Decision Changelog |
 | `domain-model.md` | `docs/architecture/domain-model.md`; note any IA / cross-cutting contract change there — the `boundary` skill reads it from source at the next plan check |
-| Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant ADR |
-| `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
+| Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant AD |
+| `tech.md` deviations | `docs/architecture/references.md` or the relevant AD |
 | `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 |
 
 Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}.md` listing what was published where.
 
-## After publishing — keep the record
+## After publishing — move the record to history
 
-**Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
-conclusions, but the record stays committed as their provenance: a traceable source for every published
-headline, and the seed the next `/brainstorm start` on this topic resumes from. Retire a topic's folder
-by hand only when the design line is truly dead.
+**Move `docs/research/{topic}-brainstorming/` → `docs/history/brainstorms/{topic}/`, and update both
+`Readme.md` indexes** (drop the row from `docs/research/Readme.md`, add it to
+`docs/history/brainstorms/Readme.md`). The exit artifacts now carry the distilled conclusions; the record
+itself is **kept** — never deleted — but as harvested provenance it belongs under `docs/history/brainstorms/`:
+a traceable source for every published headline, and the seed the next `/brainstorm start` on this topic
+resumes from. A session that is only **paused** (not harvested) stays in `docs/research/`. Retire a topic's
+folder by hand only when the design line is truly dead.

package/data/harnesses/etna/skills/brainstorm/templates/source-of-truth.md

@@ -3,8 +3,8 @@
 > This is a **source-of-truth doc**: the standing, canonical reference for [thing]. Write it like a
 > README — present tense, reader-first, the thing described as it _is_. It is **not a plan** (no steps,
 > status, or sequencing — those go to `docs/history/plans/`) and **not the brainstorm record** (no
-> `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in
-> `docs/brainstorm/{topic}/` and any ADRs). One document; if a section outgrows it, link out, don't sprawl.
+> `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in the harvested
+> record at `docs/history/brainstorms/{topic}/` and any ADs). One document; if a section outgrows it, link out, don't sprawl.
 >
 > **Placement.** In a repo with a feature-doc system this lands as `docs/features/{slug}.md` and carries
 > that system's frontmatter (`owns:` / `module:` / `keywords:` / `status:`). Cross-cutting → `docs/architecture/{slug}.md`.
@@ -31,7 +31,7 @@ reader-first description. Prose and tables; a diagram only if it earns its token
 
 [The load-bearing decisions, folded into present-tense rationale — "the index is single-writer because
 concurrent writes corrupted it," not "we decided X over Y." No decision codes, no options-considered
-table. The full rationale and the roads not taken live in the brainstorm record and ADRs — cite them,
+table. The full rationale and the roads not taken live in the brainstorm record and ADs — cite them,
 don't reproduce them.]
 
 ## Constraints & non-goals
@@ -41,9 +41,9 @@ and what is explicitly out of scope.]
 
 ## Open questions
 
-[One line pointing at `docs/brainstorm/{topic}/pillars/questions.md` if any remain open. Omit if none.]
+[One line pointing at `docs/history/brainstorms/{topic}/questions.md` if any remain open. Omit if none.]
 
 ---
 
-_Distilled from `docs/brainstorm/{topic}/`. That record holds the rationale, the rejected alternatives,
+_Distilled from `docs/history/brainstorms/{topic}/`. That record holds the rationale, the rejected alternatives,
 and the provenance for everything above._

package/data/harnesses/etna/skills/documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance), or (11) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD".
+description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record or revise an architecture decision (an AD), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance) or a one-shot migration runbook, (11) write a steering doc (system overview, domain model, glossary, non-goals, security overview, testing strategy), (12) catalog the API surface or the environment/config registry, or (13) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "AD", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD", "glossary", "domain model", "runbook", "API reference".
 ---
 
 # Technical Documentation Skill
@@ -9,12 +9,31 @@ description: Template & generator library for technical docs — the skill agent
 
 Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
 
+---
+
+## The Two Natures
+
+Every document is exactly one of two things. Decide which before writing a word — every rule in this skill derives from the split.
+
+| | **Truth document** | **Record** |
+| --- | --- | --- |
+| States | Absolutes — how the system is, **now** | What happened — a dated account of activity |
+| Named by | Topic: `auth.md`, `AD-003-persistence.md` | Date: `YYYY-MM-DD-slug.md` (or append position) |
+| On change | Body rewritten in place the moment reality changes | Never edited — frozen at completion or append-only |
+| Read to | Act correctly today | Trace provenance, diagnose, audit |
+| Lives in | `docs/features/`, `docs/architecture/`, `docs/operations/`, `docs/tests/`, READMEs | `docs/history/` (plans, changelog, brainstorms, research, migrations), `docs/research/`, `docs/memory/` |
+
+The two guarantees are complementary and both break on mixing: a reader holding a **truth document** must never need history to interpret it; a reader holding a **record** must be able to trust it was never rewritten. So the natures never share a document body.
+
+- **Truth documents never narrate history.** No migration/fold stories, no dated "shipped/verified on YYYY-MM-DD" markers, no "was X → now Y" journeys, no provenance asides ("ex-`@nurix/X`, folded 2026-06-12"). When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
+- **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
+- **The one bridge — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog**: the single sanctioned dated-history section inside a truth document, because for a decision the journey (what each revision reversed, and what triggered it) is part of the reasoning. The AD body stays current-truth-only; the tail carries the dates and links to the plans that implemented each revision. No other truth document carries dated history.
+- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents — never to a plan or changelog entry as the "read first" source.
+
 **No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
 
 **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
 
-**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans); `docs/memory/` is the agent's dated log and is likewise exempt, and an ADR's **Decision Changelog** section is the one sanctioned dated-history section inside an active doc (the ADR body itself stays current-truth-only). A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
-
 ---
 
 ## Decision Tree
@@ -24,23 +43,39 @@ User request
     │
     ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
     │
-    ├─ "Document feature/module (LLD)" ▶ Module Template
+    ├─ "Document feature/module (LLD)" ▶ Feature (LLD) Template
     │
-    ├─ "Create/update changelog" ──────▶ Changelog Template
+    ├─ "Create/update changelog" ──────▶ Changelog Template (record)
     │
-    ├─ "Document data flow" ───────────▶ Module Template (Architecture section)
+    ├─ "Document data flow" ───────────▶ Feature Template (Architecture section)
     │
-    ├─ "Document Redux/state" ─────────▶ Module Template (State section)
+    ├─ "Document Redux/state" ─────────▶ Feature Template (State section)
     │
     ├─ "Add to protected files" ───────▶ Protected Files Template
     │
-    ├─ "Record architecture decision" ─▶ ADR Template
+    ├─ "Record/revise architecture
+    │    decision" ────────────────────▶ AD Template (one per subject; revisions update it in place)
+    │
+    ├─ "System at a glance" ───────────▶ System Overview Template
+    │
+    ├─ "Domain model / glossary /
+    │    non-goals" ───────────────────▶ Steering Templates
+    │
+    ├─ "Catalog the API surface" ──────▶ API Reference Template
+    │
+    ├─ "Document env vars / config" ───▶ Environment Registry Template
+    │
+    ├─ "Security / threat model" ──────▶ Security Overview Template
+    │
+    ├─ "Testing strategy" ─────────────▶ Testing Strategy Template
+    │
+    ├─ "Recurring procedure/setup" ────▶ Operations Procedure Template
     │
-    ├─ "Document a procedure/setup" ───▶ Operations Procedure Template
+    ├─ "One-shot migration/upgrade" ───▶ Migration Runbook Template (record)
     │
     ├─ "Create/update root README" ────▶ Project Root README Template
     │
-    ├─ "Create/update plan" ───────────▶ Plan Template
+    ├─ "Create/update plan" ───────────▶ Plan Template (record)
     │
     ├─ "Update existing doc" ──────────▶ Preserve existing structure
     │
@@ -51,10 +86,19 @@ User request
 
 ## Naming & Lifecycle
 
-- Features: `kebab-case.md` — living reference, status `Active`
-- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
-- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
-- Memory: `{agent-name}.md` — agent-maintained
+| Document | Nature | Name | Lifecycle |
+| --- | --- | --- | --- |
+| Feature (LLD) | Truth | `kebab-case.md` | Living; `status:` `draft` → `active` → `deprecated` |
+| Architecture Decision | Truth | `AD-NNN-kebab-case.md` | Living; `Proposed` → `Accepted` → `Deprecated`; revisions rewrite the body + append to its Decision Changelog |
+| Steering docs (overview, domain model, glossary, non-goals, security, testing strategy) | Truth | fixed names | Living |
+| API reference / environment registry | Truth | fixed names | Living |
+| Operations procedure | Truth | `kebab-case.md` | Living |
+| Protected files | Truth | `protected-files.md` | Living |
+| Plan | Record | `YYYY-MM-DD-kebab-case.md` | Freezes at `Complete` / `Abandoned` |
+| Changelog entry | Record | `YYYY-MM-DD-kebab-case.md` | Frozen; master index append-only |
+| Migration runbook | Record | `YYYY-MM-DD-kebab-case.md` | Freezes once executed, outcome stamped |
+| Research | Record | `history/research/{topic}/` | Frozen snapshot |
+| Memory | Record | `{agent-name}.md` | Append-only dated ledger |
 
 ---
 
@@ -65,7 +109,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 ### When to run
 
 - **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New feature doc** — when creating a doc via the Feature/Module template, project its `owns:` globs
+- **New feature doc** — when creating a doc via the Feature template, project its `owns:` globs
 - **Doc update** — when the documented scope changes, update the doc's `owns:` globs
 
 ### How to derive the frontmatter
@@ -123,6 +167,6 @@ For docs that don't match templates:
 
 | File | Use For |
 | --- | --- |
-| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, protected files, ADR, project root README templates |
-| `references/style-guide.md` | Writing rules, formatting conventions |
+| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, migration runbook, protected files, AD, steering docs (system overview, domain model, glossary, non-goals, security, testing strategy), API reference, environment registry, project root README templates |
+| `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
 | `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/etna/skills/documentation/references/examples.md

@@ -151,6 +151,46 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 
 ---
 
+## Example 5: Architecture Decision revision
+
+### ❌ Bad: Supersession chain
+
+```
+docs/architecture/decisions/
+├── AD-002-auth-keycloak.md        (status: Superseded)
+├── AD-006-auth-better-auth.md     (status: Superseded, "supersedes AD-002")
+└── AD-011-auth-better-auth-v2.md  (status: Accepted, "supersedes AD-006")
+```
+
+**Problems:** Three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
+
+### ✅ Good: One subject, updated in place
+
+```
+docs/architecture/decisions/
+└── AD-002-auth.md                 (status: Accepted, last-updated bumped)
+```
+
+```markdown
+## Decision
+
+We use Better Auth with one-shot credential issuance…   ← current truth, no journey
+
+…
+
+## Decision Changelog
+
+- 2026-05-02 — Moved issuance to one-shot tokens because refresh-token theft
+  surfaced in review. Implemented by [plan](…). (Previously: long-lived refresh tokens.)
+- 2026-03-18 — Replaced Keycloak with Better Auth because self-hosting cost
+  outweighed SSO needs. Implemented by [plan](…). (Previously: Keycloak.)
+- 2026-01-10 — Initial decision accepted. Implemented by [plan](…).
+```
+
+**Why it works:** The body answers "how does auth work and why" without archaeology; the tail preserves every reversal with its trigger; the rejected alternatives stay findable in the one file a reader actually opens.
+
+---
+
 ## Quick Comparison
 
 | Aspect     | Bad                  | Good                        |
@@ -159,4 +199,5 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 | State      | Every occurrence     | Persistence points only     |
 | Flows      | Prose paragraphs     | ASCII diagrams              |
 | Changelogs | "Updated X"          | Function names + migrations |
+| Decisions  | New doc per revision | One AD per subject, updated in place |
 | Length     | 100+ lines           | 20-40 lines                 |

package/data/harnesses/etna/skills/documentation/references/style-guide.md

@@ -220,26 +220,31 @@ Use for structured info:
 
 ---
 
-## Tense & History
+## The Two Natures — Tense & History
 
-**Active docs describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans). Two sanctioned exceptions: `docs/memory/` is the agent's own dated log, and an ADR's **Decision Changelog** section carries that decision's dated revision history (the rest of the ADR body stays current-truth-only).
+Every document is a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — see `SKILL.md` § The Two Natures. The tense rules follow directly:
 
-Strip this language from active docs:
+**Truth documents describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Two sanctioned exceptions: `docs/memory/` is the agent's own dated ledger, and an AD's **Decision Changelog** tail carries that decision's dated revision history (the AD body stays current-truth-only — head is truth, tail is provenance).
 
-| ❌ Historical narration (belongs in `docs/history/`) | ✅ Present-tense fact (belongs in the active doc) |
+**Records are never edited to match the present.** A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
+
+Strip this language from truth documents:
+
+| ❌ Historical narration (belongs in a record) | ✅ Present-tense fact (belongs in the truth doc) |
 | --- | --- |
 | "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
 | "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
 | "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
 | "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
-| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-SOT>.md`" |
+| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
 
 Rules:
 
-- **No dates in active docs** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
-- **Cite the ADR for the _why_, never the _when_.** `Provenance: ADR-002` is good (it points to the decision rationale). "Decided in ADR-002 and shipped 2026-06-13" is not.
-- **Routing/index docs point only to current authority docs.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current SOT doc, or drop the row.
-- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the active doc simply becomes correct in present tense.** Never leave the diff narrated in place.
+- **No dates in truth documents** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
+- **Cite the AD for the _why_, never the _when_.** `Provenance: AD-002` is good (it points to the decision rationale). "Decided in AD-002 and shipped 2026-06-13" is not.
+- **Routing/index docs point only to truth documents.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row.
+- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the truth document simply becomes correct in present tense.** Never leave the diff narrated in place.
+- **A decision that moves is an edit, not a new document.** Rewrite the AD's affected sections to the new truth and append the revision to its Decision Changelog — never mint a parallel doc and never leave the old choice narrated in the body.
 
 ---