@nurix/etna 0.18.19 → 0.18.21

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

@@ -132,7 +132,7 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
 
 - **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`.
 

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

@@ -136,7 +136,7 @@ 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.
+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 `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."_
 
 ## Conduct — holds for the whole session

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

@@ -21,7 +21,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,10 +44,10 @@ 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 |

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

@@ -4,7 +4,7 @@
 > 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.
+> `docs/brainstorm/{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,7 +41,7 @@ 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/brainstorm/{topic}/questions.md` if any remain open. Omit if none.]
 
 ---
 

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, research, migrations), `docs/brainstorm/`, `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.
 
 ---