@nurix/etna 0.18.20 → 0.18.22

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

@@ -1,12 +1,12 @@
 # Documentation Templates
 
-Templates for all documentation needs.
+Templates for all documentation needs. Every template is either a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — the split is defined in `SKILL.md` § The Two Natures, and each template below names its nature.
 
 ---
 
 ## docs/README.md (Documentation Root)
 
-Use for: the entry point for all documentation in a repo. Created during baseline audit.
+Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
 ```
 # {Project Name} Documentation
@@ -28,10 +28,14 @@ Technical documentation for {project description}.
 
 ## Architecture
 
-System design, patterns, and technical decisions.
+System design, steering docs, and standing decisions — the truth layer.
 
-- [system-design.md](architecture/system-design.md) - High-level system architecture
-{list all architecture docs}
+- [system-design.md](architecture/system-design.md) - System overview: subsystems and key flows
+- [domain-model.md](architecture/domain-model.md) - Entities, relationships, state ownership
+- [glossary.md](architecture/glossary.md) - Project vocabulary
+- [non-goals.md](architecture/non-goals.md) - What this system deliberately does not do
+- [decisions/](architecture/decisions/Readme.md) - Architecture Decisions (ADs)
+{list other architecture docs — api.md, security.md — when present}
 
 ---
 
@@ -49,17 +53,18 @@ Living reference docs for implemented features (how things currently work).
 How to run, develop, and deploy.
 
 - [setup.md](operations/setup.md) - Installation and configuration guide
-{list all operations docs}
+{list all operations docs — environment.md when present}
 
 ---
 
 ## History
 
-Everything frozen or append-only.
+The records — everything dated, frozen, or append-only.
 
 - [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
 - [changelog/](history/changelog/) - Individual changelog entries
-- [plans/](history/plans/) - Historical implementation plans
+- [plans/](history/plans/) - Implementation plans (frozen at completion)
+- [migrations/](history/migrations/) - One-shot migration runbooks (frozen once executed)
 - [research/](history/research/) - Deep-research artifacts (one folder per topic)
 - [backlog.md](history/backlog.md) - Tracked work items and technical debt
 
@@ -74,7 +79,7 @@ See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
 
 ## docs/structure.md (Authority Map)
 
-Use for: defining which folder owns which topic and how docs are maintained.
+Truth document. Use for: defining which folder owns which topic and how docs are maintained.
 
 ```
 ---
@@ -93,32 +98,41 @@ Each topic has one canonical location. Read from here, not from plans or changel
 | Topic | Authority | Key Files |
 | ----- | --------- | --------- |
 | Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
-| System architecture + steering | `docs/architecture/` | domain-model, glossary, non-goals, references, adr/ |
+| System overview | `docs/architecture/` | system-design.md |
+| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
+| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
+| API surface | `docs/architecture/` | api.md |
+| Security | `docs/architecture/` | security.md |
 | Feature behavior | `docs/features/` | {key files} |
 | Setup & development | `docs/operations/` | {key files} |
+| Environment / config surface | `docs/operations/` | environment.md |
+| Testing strategy | `docs/tests/` | strategy.md |
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | Individual entries |
+| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
 | Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
-| Brainstorm design records | `docs/brainstorm/{topic}/` | state.md + pillars/ |
+| Brainstorm design records | `docs/research/{topic}-brainstorming/` (active) → `docs/history/brainstorms/{topic}/` (harvested) | state.md + pillars/ |
 | Backlog | `docs/history/` | backlog.md |
 
-## Document Lifecycle
+## The Two Natures
 
-Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update → Changelog Entry
+Every doc is a **truth document** (states current absolutes, topic-named, updated in place) or a **record** (dated account of activity, frozen or append-only). `architecture/`, `features/`, `operations/`, `tests/` hold truth; `history/`, `research/`, `memory/` hold records.
 
-- Plans freeze at completion — never updated to reflect current code
-- Changelogs summarize + link to feature docs — no duplicated schemas
-- Feature docs are the living reference — updated when code changes
+- Truth documents are rewritten in place when reality changes — the change-story goes to a changelog entry, never into the truth doc's body.
+- Records freeze: plans at `Complete`/`Abandoned`, changelog entries and migration runbooks once written/executed. A scope change is a new dated record that links back.
+- Feature docs are the living reference for implemented features; an AD is the living truth for one decision subject, with its dated journey confined to its Decision Changelog tail.
 
 ## Folder Rules
 
 - `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
-- `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). A module's cross-cutting prose lives here (or in a browse-folder `Readme.md`). Update when cross-cutting concerns change.
-- `docs/operations/`: How-to procedures for setup, development, and deployment. Update when workflows change.
-- `docs/history/plans/`: Historical. Must have `Status:` field. Never modify after completion.
-- `docs/history/changelog/`: Historical. Append-only.
+- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
+- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
+- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
+- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
+- `docs/history/changelog/`: Records. Append-only.
+- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
 - `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
-- `docs/brainstorm/{topic}/`: Kept design records — the committed Brainstorming-Mode session for a topic (`state.md` + `pillars/`), written by the `brainstorm` skill and **kept** after harvest as the provenance the steering pillars distil from. Author-created (never scaffolded empty), one subfolder per design conversation. Owns no code (no `owns:` frontmatter); the harvest copies its conclusions into `architecture/`/`history/` while the record stays in place. Retire a topic's folder by hand only when the design line is dead.
+- `docs/research/{topic}-brainstorming/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the committed Brainstorming-Mode session for a topic (`state.md` + `pillars/`), written by the `brainstorm` skill. An active session lives under `docs/research/`; on close + harvest it **moves** to `docs/history/brainstorms/` and is **kept** as the provenance the truth layer distils from. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest copies its conclusions into `architecture/`/`history/`. Retire a topic's folder by hand only when the design line is dead. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
 - `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
 
 ## Health Log
@@ -263,7 +277,7 @@ Memory file initialized during documentation baseline.
 
 ## Feature Documentation — the LLD (docs/features/{feature}.md)
 
-Use for: every feature in `docs/features/`. The feature doc is the feature's **LLD (low-level design)**: the same file persists from design (Status: Draft, written in LLD Mode) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap.
+Truth document. Use for: every feature in `docs/features/`. The feature doc is the feature's **LLD (low-level design)**: the same file persists from design (Status: Draft, written in LLD Mode) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap. The body always describes the feature as it currently is; the journey lives in the linked plan and changelog entries.
 
 **Required vs optional.** Four things are required in every feature doc: the frontmatter, **Goal**, **Background**, and **Files** — plus **Current Behavior** once research or implementation exists (at Draft it's the pre-feature baseline; at Active it's how the feature works today). Every other section is optional: include it only when the feature has something real to put in it (no Redux → no Redux section; no risks worth naming → no Risks section). A **minimal form** is sanctioned for small features: frontmatter + Goal + a short how-it-works section + Files. A two-screen doc that is accurate beats a full-template doc with empty sections.
 
@@ -415,7 +429,7 @@ Resolved Open Questions can be summarized into Background; unresolved ones stay
 
 ## Changelog
 
-Use for: recording code changes with function-level detail.
+Record. Use for: recording code changes with function-level detail. Entries are frozen once written — they describe the change as it shipped, and are never edited to match later reality.
 
 Change categories follow the Keep a Changelog vocabulary — **Added / Changed / Deprecated / Removed / Fixed / Security** — the same six the master `CHANGELOG.md` scaffold instructs. Include only the categories that apply; all six share the same bullet shape (function/file, then detail lines).
 
@@ -478,7 +492,7 @@ Brief description of what changed and why.
 
 ## Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
 
-Use for: every implementation plan. Plans are created here directly with `Status: Draft`, flip to `Status: In Progress` when work starts, and freeze at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes.
+Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`, flip to `Status: In Progress` when work starts, and freeze at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
 
 The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
 
@@ -545,7 +559,9 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 ## Operations Procedure (docs/operations/{procedure}.md)
 
-Use for: any doc in `docs/operations/` — setup, development, deployment, maintenance procedures. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative.
+Truth document. Use for: any **recurring** procedure — setup, development, deployment, maintenance. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
+
+A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
 
 Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
 
@@ -580,9 +596,46 @@ If a procedure is a deterministic command list run frequently, script it and hav
 
 ---
 
+## Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
+
+Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).
+
+Required: **Goal**, **Steps**, **Verification**, and — after execution — the **Outcome** stamp. Optional: Preconditions, Rollback.
+
+```
+# Migration: {Title}
+
+**Goal:** What this migration accomplishes and why it runs now, one or two lines.
+**Executes against:** {environment / database / system}
+
+## Preconditions
+
+- Backups taken, feature flags set, access confirmed — exact checks
+
+## Steps
+
+1. One action per step, exact command in a code block
+2. Note expected output where it disambiguates success from failure
+
+## Verification
+
+- The observable end state that confirms success — exact check commands
+
+## Rollback
+
+- How to undo, and the point of no return
+
+## Outcome
+
+<!-- Stamped once, immediately after execution; the file freezes with it. -->
+**Executed:** YYYY-MM-DD — {result: clean | issues encountered + how resolved | aborted + why}
+```
+
+---
+
 ## Protected Files
 
-Use for: documenting critical files that need approval before modification.
+Truth document. Use for: documenting critical files that need approval before modification.
 
 This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
 
@@ -620,19 +673,23 @@ path/to/another/file.js
 
 ---
 
-## Architecture Decision Record (ADR)
+## Architecture Decision (AD)
 
-Use for: capturing a single architectural decision with its context, alternatives considered, and consequences. Lives in `docs/architecture/adr/` — co-located with the architecture it decides. An ADR is the **source of truth for its decision**: the body always states the current truth. When the decision is revisited, update the ADR in place — rewrite the affected sections to what is now true, bump `last-updated`, and record the revision in the **Decision Changelog**. Readers get the current decision from the body; the journey lives only in the changelog section.
+Truth document — with the one sanctioned dated tail. Use for: the standing decision on one architectural **subject** — a system shape, a contract, a substrate choice. Lives in `docs/architecture/decisions/`. The body always states the current decision and its current reasoning. When the decision moves, rewrite the affected sections to what is now true, bump `last-updated`, and append the revision to the **Decision Changelog** — the journey lives in that tail, never in the body. Head is truth; tail is provenance.
 
-### When to write an ADR
+### One subject per AD
 
-Write an ADR when **all three** apply:
+The unit is the subject, not the individual call. "The persistence layer", "auth", "the design-skill architecture" are subjects; every decision, reversal, and re-decision on a subject lands in that subject's one AD, however many times it moves. Write a second AD only when a genuinely separate subject emerges — never to record a revision of an existing one.
+
+### When to write an AD
+
+Write an AD when **all three** apply:
 
 1. The decision is architectural — affects system shape, contracts, or substrate choice, not internal implementation
 2. Alternatives were genuinely considered and rejected
-3. Future maintainers will ask "why did we do it this way?"
+3. Future maintainers will ask "why is it this way?"
 
-Don't write an ADR for:
+Don't write an AD for:
 
 - Standing principles or style preferences (those are stances, not decisions — put them in `docs/architecture/`)
 - Routine implementation choices with no rejected alternatives
@@ -642,38 +699,38 @@ Don't write an ADR for:
 
 `Proposed` → `Accepted` → `Deprecated`
 
-An ADR stays `Accepted` for as long as its question is live — revisions update it in place. Set `Deprecated` only when the decision's question itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
+Frontmatter `status:` is the single lifecycle source of truth. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
 
 ### Naming
 
-`ADR-NNN-short-title.md` — three-digit zero-padded number, kebab-case title. Numbers are assigned sequentially across the project and never reused.
+`AD-NNN-short-title.md` — three-digit zero-padded number, kebab-case subject. Numbers are assigned sequentially across the project and never reused.
 
 ### Structure
 
-Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the ADR has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
+Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the AD has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
 
 ### Template
 
 ```markdown
 ---
-title: "ADR-NNN: Short title in sentence case"
+title: "AD-NNN: Short title in sentence case"
 status: Accepted # Proposed | Accepted | Deprecated
 created: YYYY-MM-DD
 last-updated: YYYY-MM-DD # bump on every revision
 decision-owner: Name
 reviewers: [] # optional
-tags: [adr]
+tags: [ad]
 ---
 
-# ADR-NNN: Short Title
+# AD-NNN: Short Title
 
 ## Decision
 
-[One paragraph, active voice. "We will…" Lead with the answer.]
+[One paragraph, active voice. "We will…" Lead with the answer — the current answer, whatever the journey was.]
 
 ## Context
 
-[The forces in play. What is the problem? Why does it need a decision now? Technical, political, social, and project-local pressures.]
+[The forces in play. What is the problem? Why does it need a decision? Technical, political, social, and project-local pressures — stated as present-tense forces, not as a history of the subject.]
 
 ## Consequences
 
@@ -714,37 +771,234 @@ tags: [adr]
 
 1. **[Question]** — _Default_: [stated default until resolved].
 
-## Acknowledgements
-
-[Credit reviewers; name what they corrected. Include when reviewers materially shaped the doc.]
-
 ## References
 
 - [External link or cross-reference]
 
 ## Decision Changelog
 
-<!-- Append-only, newest first. One entry per revision: what changed in the decision, the trigger, and the previous choice. Added on the first revision; the initial acceptance is the first entry. -->
+<!-- The provenance tail — append-only, newest first. One entry per revision: what changed, the trigger, the previous choice, and the plan that implemented it. Added on the first revision; the initial acceptance is the last entry. -->
 
-- YYYY-MM-DD — [What changed] because [trigger]. (Previously: [old choice].)
-- YYYY-MM-DD — Initial decision accepted.
+- YYYY-MM-DD — [What changed] because [trigger]. Implemented by [plan link]. (Previously: [old choice].)
+- YYYY-MM-DD — Initial decision accepted. Implemented by [plan link].
 ```
 
 ### Rules
 
-- One decision per ADR. If you find yourself describing two decisions, split into two ADRs.
+- **One subject per AD; all its revisions stay inside it.** Two genuinely different subjects means two ADs — a revision of an existing subject never does.
+- **The body is always the current truth.** Rewrite affected sections on every revision; never leave a superseded choice narrated in the body — the Decision Changelog carries the journey, with each entry naming the old choice and the trigger.
 - Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
+- **Consequences lists positives, negatives, AND risks.** Pros-only Consequences is the genre's classic failure — one AD's honest resulting context is the input context for the next.
+- **Options Considered keeps every genuinely rejected alternative with the real reason.** Informed rejections are the most expensive knowledge to lose; a rejection made with strong prior art in view says so explicitly.
+- **Keep it short — one to two pages.** Long decision docs don't get updated. How-it-works detail belongs in the owning feature doc; execution in a plan. Link, don't embed.
 - No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything.
 - Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body.
-- **Revisions update the body in place.** Rewrite the affected sections to the current truth, bump `last-updated`, and append a Decision Changelog entry naming the old choice and the trigger. Never leave the superseded decision narrated in the body — the changelog carries the journey.
-- The **Decision Changelog** is the one sanctioned dated-history section in an active doc: append-only, newest first. Typo and formatting fixes don't get entries.
-- Execution detail lives in a plan doc, not the ADR — link, don't embed.
+- The Decision Changelog is append-only, newest first. Typo and formatting fixes don't get entries.
+
+---
+
+## System Overview (docs/architecture/system-design.md)
+
+Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
+
+Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
+
+```
+# System Overview
+
+## What this is
+
+{Two or three sentences: what the system does, for whom, in what environment it runs.}
+
+## Subsystem map
+
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Frontend │────▶│   API    │────▶│    DB    │
+└──────────┘     └──────────┘     └──────────┘
+{One box per subsystem; label the arrows with the contract that crosses them.}
+
+- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
+
+## Key flows
+
+{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
+
+## Where the truth lives
+
+| Area | Canonical doc |
+| ---- | ------------- |
+| {area} | [{doc}](path) |
+```
+
+---
+
+## Domain Model (docs/architecture/domain-model.md)
+
+Truth document. Use for: the entities the system is about — what they are, how they relate, and who owns their state. The vocabulary here must match the glossary and the code; when they disagree, fix the disagreement, don't document around it.
+
+Required: **Entities**, **Relationships**. Optional: Lifecycle states, Invariants.
+
+```
+# Domain Model
+
+## Entities
+
+| Entity | What it is | State lives in |
+| ------ | ---------- | -------------- |
+| {Entity} | {one line} | {table / slice / service} |
+
+## Relationships
+
+- {EntityA} 1—N {EntityB} — {the meaning of the link}
+- {EntityB} N—N {EntityC} via {join} — {meaning}
+
+## Lifecycle states
+
+{Only for entities with real state machines.}
+
+- **{Entity}**: draft → active → archived — {what moves it between states}
+
+## Invariants
+
+- {A relationship or state rule that must always hold, stated as a constraint}
+```
+
+---
+
+## Glossary (docs/architecture/glossary.md)
+
+Truth document. Use for: the project's vocabulary — one name per concept, one line per name. Alphabetical. When the code uses a different name than the docs, record it in **In code** so readers can bridge; one concept never gets two doc names.
+
+```
+# Glossary
+
+| Term | Meaning | In code |
+| ---- | ------- | ------- |
+| {Term} | {one-line definition} | `{identifier}` |
+```
+
+---
+
+## Non-Goals (docs/architecture/non-goals.md)
+
+Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
+
+```
+# Non-Goals
+
+Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
+
+- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
+```
+
+---
+
+## API Reference (docs/architecture/api.md)
+
+Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **index**: request/response shapes stay in the owning feature docs; this doc answers "what exists and where is it documented." If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
+
+Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.
+
+```
+# API Reference
+
+## Conventions
+
+- Base path: `/api/v{N}` · Auth: {scheme} · Envelope: `{ "status": 1, "message": "...", "data": {...} }`
+- Errors: `{ "status": 0, "message": "...", "data": null }` · Codes: 200/201/400/401/403/404/500
+
+## {Resource group}
+
+| Method | Path | Purpose | Auth | Owning doc |
+| ------ | ---- | ------- | ---- | ---------- |
+| GET | `/api/foo` | {one line} | {role} | [feature](../features/{feature}.md) |
+```
+
+---
+
+## Environment Registry (docs/operations/environment.md)
+
+Truth document. Use for: the config surface — every variable the code reads, in one table. `.env.example` mirrors this doc's variable list.
+
+**Placeholders only, never real values.** A real-looking password, account ID, or personal profile name in a doc is a leak, and one developer's local setup written as the canonical value is a trap for everyone else. Values in this doc are `{placeholder}` descriptions.
+
+```
+# Environment Registry
+
+Every variable the code reads. `.env.example` mirrors this list.
+
+| Variable | Purpose | Required | Where set | Secret |
+| -------- | ------- | -------- | --------- | ------ |
+| `DATABASE_URL` | {one line} | yes / default: `{value}` | local `.env` / CI / prod | yes |
+```
+
+---
+
+## Security Overview (docs/architecture/security.md)
+
+Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
+
+Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
+
+```
+# Security Overview
+
+## Assets
+
+- {What's worth protecting — data classes, credentials, tenant isolation}
+
+## Trust boundaries
+
+- {Boundary} — {what crosses it, and what checks the crossing} 
+
+## Controls
+
+| Control | Protects against | Implemented in |
+| ------- | ---------------- | -------------- |
+| {control} | {threat} | `{file/module}` |
+
+## Accepted risks
+
+- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
+```
+
+---
+
+## Testing Strategy (docs/tests/strategy.md)
+
+Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
+
+Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
+
+```
+# Testing Strategy
+
+## Levels
+
+| Layer | Runner | Lives in | Covers |
+| ----- | ------ | -------- | ------ |
+| Unit / integration | {runner} | `tests/` | {what} |
+| E2E | {runner} | `e2e/` | {what} |
+
+## Running
+
+- `{pm} test` — the whole unit suite (CI gate)
+- `{pm} run test:e2e` — {when to run}
+
+## Deliberately untested
+
+- {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
+
+## Adding a test
+
+1. {Where the file goes, what it's named, where fixtures live}
+```
 
 ---
 
 ## Project Root README
 
-Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
+Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
 
 ### Strategy
 

package/data/harnesses/etna/CLAUDE.md

@@ -51,7 +51,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 | **LLD** (low-level design) | new component/feature work | `lld-mode` agent + `documentation` skill | Plan |
 | **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a one-line fix) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: kept records under `docs/brainstorm/`, harvested doctrine under `docs/architecture/`. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
+> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a one-line fix) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: in-progress sessions under `docs/research/`, harvested ones under `docs/history/brainstorms/`, harvested doctrine under `docs/architecture/`. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
 
 **On Plan Completion:**
 
@@ -61,8 +61,8 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 **On Brainstorm Close** (when a session ends, not when a plan completes):
 
-- The session record lives at `docs/brainstorm/{topic}/` (committed, one subfolder per topic) and stays in place as provenance.
-- Harvest conclusions by scope: doctrine, glossary, non-goals, IA changes → `docs/architecture/`; decisions → `docs/architecture/adr/`; backlog items → `docs/history/backlog.md`.
+- The session record lives at `docs/research/{topic}-brainstorming/` (committed) while active; on close + harvest it moves to `docs/history/brainstorms/{topic}/` as provenance — see `docs/structure.md`.
+- Harvest conclusions by scope: doctrine, glossary, non-goals, IA changes → `docs/architecture/`; decisions → `docs/architecture/decisions/` (one AD per subject — revising a recorded subject updates its AD in place); backlog items → `docs/history/backlog.md`.
 - Open questions block close.
 
 ---

package/data/harnesses/etna/agents/brainstorm.md

@@ -14,7 +14,7 @@ You are a **thin orchestrator.** Every mechanic — the constant loop, the four
 ## When to offer a session
 
 - An explicit ask to think through a design at a strategic level (not "fix this bug" / "add this button"). This is the user invoking the work; hand it to `/brainstorm start`.
-- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind — skim `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `open-questions.md`) and its `adr/` decision titles. The steering layer lives there; there are no `docs/modules/` or `docs/pillars/` folders. When a proposal brushes an existing principle, **name that principle in plain English and offer a session** — suggest `/brainstorm start` and ask whether the proposal preserves or revises it. Detection is yours; entry is the user's. **Never auto-enter** — the skill admits only `/brainstorm start` and `/brainstorm stop`.
+- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind — skim `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `open-questions.md`) and its `decisions/` AD titles. The steering layer lives there; there are no `docs/modules/` or `docs/pillars/` folders. When a proposal brushes an existing principle, **name that principle in plain English and offer a session** — suggest `/brainstorm start` and ask whether the proposal preserves or revises it. Detection is yours; entry is the user's. **Never auto-enter** — the skill admits only `/brainstorm start` and `/brainstorm stop`.
 
 If none of those steering files exist yet (a freshly-baselined repo), a session still runs from the skill's templates, and the basis gate seeds it from a reference doc or a one-shot brain dump.
 

package/data/harnesses/etna/agents/maintenance.md

@@ -127,28 +127,29 @@ docs/
 ├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
-│   └── adr/               # Architecture Decision Records (numbered, immutable)
+│   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
-├── brainstorm/            # Optional — kept design records, one {topic}/ subfolder per session (state.md + pillars/)
-│   └── {topic}/           #   created by the `brainstorm` skill; NOT scaffolded empty
+├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorming/) + standing research; Readme.md is the index
+│   └── {topic}-brainstorming/  #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on harvest
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual entries
 │   ├── plans/             # Implementation plans (Status field required)
+│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/), kept as provenance; Readme.md is the index
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
 ├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
 └── tests/                 # Optional, author-maintained — create only if test docs exist
 ```
 
-There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records are kept design records.
+There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
-> `docs/brainstorm/{topic}/` is **author-created, never scaffolded** — the `brainstorm` skill writes it when a session opens, and it is **kept** (committed) as the provenance the steering pillars distil from. Recognize it as canonical: never flag it as a doc "outside the structure" and never delete it during reconcile.
+> Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorming/` and moves it to `docs/history/brainstorms/{topic}/` on harvest, kept (committed) as the provenance the steering pillars distil from. Recognize both as canonical: never flag them as docs "outside the structure" and never delete them during reconcile. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; no stale or missing rows), since the `brainstorm` skill reads the indexes instead of scanning.
 
 ### Step B1 — Inventory and classify
 
-Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/brainstorm/{topic}/` is a **kept design record** — leave it in place untouched; never reclassify its pillars as Architecture/Stale or relocate them.
+Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/research/{topic}-brainstorming/` or `docs/history/brainstorms/{topic}/` is a **kept design record** — leave it in place untouched; never reclassify its pillars as Architecture/Stale or relocate them.
 
 While reading each markdown doc to classify it, if the doc names a code symbol it asserts exists that **statically resolves to nothing**, note it as an observation for the Part A audit — **only** on stacks where static resolution is reliable (stay silent on codegen/reflection/DI/barrel stacks); scoped to docs already being read here, never a whole-repo prose sweep; **docs only**, never code-file comments.
 
@@ -166,7 +167,7 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/OWNERSHIP_INDEX.md` (legacy derived ownership index) | delete — ownership is the union of feature `owns:` frontmatter, surfaced by the generated index |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
-| a root `brainstorm/` or `brainstorming/` folder (legacy transient/per-harness location) | move each design record into `docs/brainstorm/{topic}/`, kept; delete the root folder |
+| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorming/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "2e0c2a4cd5a8"
+  "digest": "287a6a528ec4"
 }