@nurix/etna 0.20.24 → 0.20.26

package/data/harnesses/delivery/skills/documentation/templates/docs-readme.md

@@ -2,67 +2,46 @@
 
 Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
+**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`) or draws a tree (`index-file-tree`).
+
 **Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.
 
 ```
 # {Project Name} Documentation
 
-Technical documentation for {project description}.
+Technical documentation for {project description}. {Two or three sentences: what the product is, its planes or packages, who the docs are for.}
 
 > For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.
 
 ---
 
-## Quick Links
-
-| Document                          | Description                          |
-| --------------------------------- | ------------------------------------ |
-| [Structure](structure.md)         | Documentation entry point and rules  |
-| [Setup](operations/setup.md)      | Installation and configuration guide |
-
----
-
 ## Architecture
 
-System design, steering docs, and standing decisions — the truth layer.
-
-- [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}
-
----
+The design layer — [architecture/](architecture/): {what the folder holds — the system overview, steering docs, cross-cutting doctrine, the per-package and per-system documents, and `decisions/` (one Architecture Decision per subject, `AD-NNN-{slug}.md`, status in each file's frontmatter)}.
 
 ## Features
 
-Living reference docs for implemented features (how things currently work).
+[features/](features/) — one living reference per feature (how it works today), flat, named `{feature}.md`; each carries `owns:` for the code it speaks for. Find a feature by its name or by the ownership index, never by a row here.
 
-- [feature-name.md](features/feature-name.md) - Feature description
-{list all feature docs}
+## Tests
 
----
+[tests/](tests/) — one behavioral checklist per documented surface, `{feature}.md`, `verifies:` naming the document whose promises it proves.
 
 ## Operations
 
-How to run, develop, and deploy.
+[operations/](operations/) — how to set up, run, develop, deploy and recover. Start at [`setup.md`](operations/setup.md) on a new machine; every other procedure is named for its task.
+
+## History
 
-- [setup.md](operations/setup.md) - Installation and configuration guide
-{list all operations docs — environment.md when present}
+[history/](history/) — the records: `plans/` (one dated plan per unit of work, frozen at completion), `changelog/` (one entry per unit of work, indexed by [CHANGELOG.md](history/CHANGELOG.md)), `migrations/` (one-shot runbooks), `brainstorms/`, `research/`, and [backlog.md](history/backlog.md).
 
----
+## Research and memory
 
-## History
+[research/](research/) — in-progress brainstorm sessions and standing research. [memory/](memory/) — project memory, one file per agent.
 
-The records — everything dated, frozen, or append-only.
+## Notes for this repository
 
-- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
-- [changelog/](history/changelog/) - Individual changelog entries
-- [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
+{The one place project-specific placement facts live, because `structure.md` is the harness's and is overwritten on every refresh: legacy folders kept as frozen provenance, a retired genre whose residue is still on disk, a local exception to a folder rule. One bullet each; delete the section when there are none.}
 
 ---
 

package/data/harnesses/delivery/skills/documentation/templates/doctrine.md

@@ -0,0 +1,82 @@
+# Doctrine Documentation (docs/architecture/common/{concern}.md)
+
+Truth document. Use for **one concern the platform handles everywhere**: authentication, authorization, storage, the API protocol, credentials, telemetry. One file per concern, named for the concern. A doctrine document owns no code and carries no `owns:`. A surface declares that it is bound by one through its own `applies:`.
+
+**A doctrine document states the design and nothing beneath it** (`references/style-guide.md` § Shape — the model first, the detail after). It is the most stable document in the tree, because it says why the platform is shaped the way it is, and that changes far less often than the code. It explains no mechanism: no function, file, column, cookie attribute, header value or per-route error code, since each of those fails the stability test. The code graph answers what the code does. This document answers why, and which principles any new code in the concern must keep.
+
+**Required:**
+
+- the frontmatter
+- the opening (the question, the boundary, and the authority sentence)
+- **The model**, ending in numbered principles, each with its reason
+- **The parts**: one table or diagram placing every part in the model, then how the parts relate
+- **one section per part**
+- **For the agent**
+
+**Optional:**
+
+- an `UNBUILT` block for decided-but-unbuilt intent
+- **Related**
+
+Nothing else. Expect one hundred and fifty to three hundred lines; past that, mechanism has usually crept in.
+
+```yaml
+---
+type: doctrine                                   # required tooling key
+status: active                                   # required — active | draft
+objects: [principal, credential, device grant]   # recommended — the concepts this doctrine governs, by their graph names
+---
+```
+
+```
+# {Concern}
+
+{The question this concern answers for every request, row or run, in one sentence, bolded — then what it does not answer and which document does. One paragraph.}
+
+{The authority sentence: this document states the design, not the code; for what does what, read the code roots in the footer or ask the code graph; where this document and the code disagree on *what*, the code is right; on *why* or a principle, the disagreement is a defect to raise.}
+
+## The model
+
+### {What the platform owns here, and what it delegates}
+
+{The one framing fact a reader needs before anything else — e.g. "NuStack checks identity; it does not own it". Plain words, no addresses.}
+
+### {The parties or parts}
+
+{Who or what participates, in a short list of one-liners — each named in plain words first, its term of art in parentheses.}
+
+### {The axis that organizes them}
+
+{The one or two dimensions every part is placed on — e.g. "who issued the proof decides how it is checked". A small table is right here.}
+
+### The principles
+
+{Numbered invariants that hold across every part. Each one sentence of rule plus its reason. Later sections cite them by number.}
+
+## {The parts} — e.g. "The credential families"
+
+{One table: each part placed on the model's axes. Then "How the parts relate": what they share, where they meet, what keeps them apart, and the order in which they are tried — each as a bold-led paragraph with its reason. A role-level diagram (mermaid) where the relationships are a flow.}
+
+## {Each part, one section per part} — e.g. "How each family works"
+
+### {A part, named for who meets it} — e.g. "A person in a browser"
+
+{Why the part exists, then the decisions it rests on, each with its reason, citing principles by number. A sequence diagram at role level where the part is a flow. Detail that a person or test can check is welcome; detail that only restates the code is not.}
+
+## For the agent
+
+{Pointers, not an inventory: the objects with one line each; the code roots as directories; any cross-cutting seam by name; the neighbouring doctrine with a purpose each.}
+```
+
+### Marking what is decided and unbuilt
+
+Code cannot reveal what it does not yet do, so decided-but-unbuilt intent is one of the few places a doctrine document records something the code does not. Wrap it in `<!-- UNBUILT:START — {what, and the evidence it is not built} -->` … `<!-- UNBUILT:END -->`, in plain words. A design decided *against* carries no marker.
+
+### What a doctrine document is not
+
+| It is not | That is |
+| --- | --- |
+| A tour of the code that implements the concern | The code graph |
+| The catalog of routes, error codes or variables | An API reference or environment registry |
+| The one feature that happens to use the concern most | That feature's own document, which `applies:` this one |
+| The story of how the concern got this way | A decision record (`decisions/`) for the why, and the changelog for the when |

package/data/harnesses/delivery/skills/documentation/templates/feature.md

@@ -1,151 +1,59 @@
-# Feature Documentation — the LLD (docs/features/{feature}.md)
+# Feature Documentation (docs/features/{feature}.md)
 
-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.
+Truth document. Use for: every feature in `docs/features/` — something a person points at: an address, a command family, a named control. One file per feature, cut by the objects it designs, never by the code's routers, tables, plans or packages. The file persists from design (`status: draft`) to live reference (`status: active`).
 
-**Required vs optional.** Required in every feature doc: the frontmatter, **Goal**, and **Background** — plus **Files** once implementation exists (a Draft for unbuilt code has no real paths to list) and **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.
+**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Documents are read by people). The body is plain English a newcomer reads top to bottom: what the thing is, why it is shaped that way, how a person meets it, what it promises. Every computable fact — columns, vocabularies, foreign keys, writers, routes, guards, codes, files — is the code graph's (`docs/architecture/systems/knowledge-layer.md`); a hand-typed copy is the defect this genre removes. The only code the body names is a cross-cutting seam the graph would not lead a reader to from the feature's own files: a middleware, a gate, a hook, a scheduler, a shared store. Everything else by plain name. Identifiers the graph cannot find from the roots live in the footer.
 
-The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to the `lld-mode` agent's return shape. The orchestrator drops its findings into those slots without restructuring.
+**A feature document runs deepest toward its end** (`references/style-guide.md` § Shape — the model first, the detail after). The opening and Why it exists are the model; How it works is the journey; **What it promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It still stops before mechanism: a promise reads "a removed membership shows a panel, not a redirect, because nothing can restore it", never which route answers it.
+
+**Required:** the frontmatter, the goal line, **Why it exists**, **How it works**, **What it promises**, **For the agent**. **What was decided** once any choice was made the code cannot explain. **Known gaps** only when there is one. Nothing else — `doc-lint` blocks the retired mechanism sections (`mechanism-section`) and warns on identifiers in the body (`body-identifier`), on a section that is a list rather than prose (`list-not-prose`), and on three bold-led bullets in a row (`formula-run`). Forty to a hundred and twenty lines.
 
 ```yaml
 ---
-owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs this doc owns (the only ownership key)
-module: billing                                  # optional — single bounded-context label; omit if cross-cutting
-keywords: [invoice, pdf]                         # required — discovery terms
+type: feature                                    # required tooling key — preserve, never narrate
 status: active                                   # required — active | draft | deprecated
-applies: [docs/architecture/common/security.md]  # optional — architecture docs this surface is BOUND by (obligation, not a bibliography); omit when none
-last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
-type: feature                                    # required tooling key — genre stamp (generator-written or authored; enum = the template names), read by tooling (UI grouping, protected-file mapping); preserve on edits, never narrate
+objects: [device, credential grant]              # required — the product objects this document designs, by their graph names
+owns: ["packages/studio/src/server/routes/devices.ts"]  # required until the graph computes ownership — the code this document speaks for; narrower glob wins
+module: identity                                 # optional — one bounded-context label
+applies: [docs/architecture/common/security.md]  # optional — doctrine this surface is BOUND by
 ---
 ```
 
-> Declare the code paths it owns in its `owns:` frontmatter — projected at Draft, confirmed against real code at Active.
-
 ```
-# {Feature Name}
-
-<!-- Lifecycle lives in the frontmatter `status:` key (active | draft | deprecated) — the single source of truth. Don't restate it in the body. -->
-**Plan:** [history/plans/YYYY-MM-DD-feature-name.md](../history/plans/YYYY-MM-DD-feature-name.md)   <!-- added once a plan exists -->
-
-## Goal
-
-One sentence. What this feature accomplishes, in user-facing terms.
-
-## Goals & Non-Goals
-
-**In scope**
-- Bullet 1
-- Bullet 2
-
-**Out of scope**
-- Bullet 1
-
-## Background
-
-Why this feature exists. The user need, the business trigger, the constraint that pushed it above the line. One paragraph.
-
-(For Product-level work, also include: problem statement, key hypotheses, open questions.)
-
-## Approach
-
-High-level shape of the solution. ASCII diagram if it helps. Implementation specifics belong in the plan.
-
-## Affected Modules
-
-(From lld-mode research) Files, routes, components, slices this feature involves. Group by module.
-
-| Module | Path | Role in this feature |
-|--------|------|----------------------|
+# {Feature name}
 
-## Conventions to Follow
+{One sentence: what this lets a person do.}
 
-(From lld-mode research) Naming patterns, structural patterns, doc-fit heuristics confirmed for the area being touched. Cite the source file(s) where the convention is established.
+## Why it exists
 
-## Current Behavior
+{The need, the trigger, the constraint; what it is deliberately not for and why. Prose, one or two paragraphs. An AD is cited by number for the reasoning it holds, never restated.}
 
-(From lld-mode research) How the relevant part of the system works *today*, before this feature lands. Without this baseline the design intent is hard to evaluate.
+## How it works
 
-## Ownership Conflicts
+{The feature as a person meets it, start to finish, present tense, plain words: what they see, what happens, what refuses them and what they are told. Introduce each term of art the first time. Name code only at a cross-cutting seam — "every request passes the organization gate before this page is reached (`requireAuth`)" — and nothing else. No columns, routes, guards, functions, files or diagrams: that is the graph's.}
 
-(From lld-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
+## What was decided
 
-| Conflicting doc | Overlapping path(s) | Resolution |
-|-----------------|---------------------|------------|
+{The choices the code cannot explain, as two to four themed paragraphs. A rejected alternative is named only where a reader would reach for it. No formula; no bullet per decision.}
 
-## Architecture
+## What it promises
 
-[ASCII diagram. Fill once implementation lands. See style-guide.md for box-drawing patterns.]
+{The guarantees and refusals a person or a test can check, grouped by theme, as short paragraphs — or a short list only where the items are genuinely parallel one-liners. Positive where possible. This is the deepest section: each state, edge case and refusal the person can meet, and the wording where it is promised. A table of states is right when the states are genuinely parallel.}
 
-## Key Functions
+## Known gaps
 
-### `functionName(param1, param2)`
-**Goal:** What it accomplishes
-**Input:**
-- `param1` (type) - Description
-- `param2` (type) - Description
-**Output:** Return type and shape
-**Side Effects:** DB writes, API calls, state updates
+{One paragraph, only when the code does not keep something the document would otherwise promise. What is missing and what it would take; the backlog row carries the rest.}
 
-### `hookName(config)`
-**Goal:** What it provides
-**Returns:** `{ data, loading, error }`
-**Triggers:** On mount, on change, manual
+## For the agent
 
-## State
-
-**Frontend (at persistence):**
-{
-  "data": [],
-  "changes": { "added": [], "updated": [], "removed": [] }
-  // "cache": {}  // UNUSED: dead key; kept so old persisted state rehydrates
-}
-
-**Storage:** localStorage `app_state`
-
-**Backend:**
-export const resources = pgTable('resources', {
-  id: text('id').primaryKey(),
-  data: jsonb('data'),
-  // oldField: text('old_field'),  // UNUSED: dead column; nothing reads it
-});
-
-**API Shape:**
-{ "status": 1, "data": {...} }
-
-## Redux (if applicable)
-
-**Slice:** `sliceName`
-
-**Actions:**
-- `setData(payload)` - Replace all data
-- `upsertItem(item)` - Add or update single item
-
-**Selectors:**
-- `selectAll(state)` → `Array<Item>`
-- `selectById(state, id)` → `Item | undefined`
-
-## Files
-
-- `src/path/to/main.js` - Core logic
-- `src/path/to/hooks.js` - React hooks
-
-## Open Questions
-
-- Question — who decides, by when
-- (Resolved questions: fold the resolution into Background.)
-
-## Risks
-
-- Risk — likelihood / impact / mitigation
+Objects: {object} — {one plain-words line}; {object} — {…}. Pages {`/…`}. Code roots {`packages/…/src/…/`} — directories, where the graph should start. Seams {`name`} only where the roots would not lead to them. Checklist `tests/{feature}.md`. See also {neighbour} ({why}), {neighbour} ({why}). No tables, routes or symbol rosters — those are the graph's.
 ```
 
-### Section evolution
-
-Sections fill in across the feature's lifecycle. No template swap — they accumulate in place.
+### Lifecycle
 
-| When | Sections written | Source |
-| --- | --- | --- |
-| Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
-| Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | lld-mode agent |
-| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `owns:` globs confirmed against real code | Main agent (from actual code) |
+| When | What is written |
+| --- | --- |
+| `status: draft` (design) | goal, Why it exists, What was decided, What it promises (with gaps named), For the agent; the LLD research goes to the plan |
+| `status: active` | How it works written from the shipped surface; `owns:` confirmed against real code |
 
-Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
+A feature whose code is gone is deleted, or `status: deprecated` with its footer pointing at what replaced it.

package/data/harnesses/delivery/skills/documentation/templates/handover.md

@@ -0,0 +1,174 @@
+# Hand-over (`docs/history/handovers/YYYY-MM-DD-{slug}.md`)
+
+Record. Use for: the account an **unattended or multi-session build** leaves the person who owns it — written by the orchestrating session as its last act, before the owner's first decision, read in one sitting. It is a **decision queue, an undo manual and a resume file**, in that order: is it done · what must I decide today · what escaped the repository and how do I undo it · can I see it working · what was decided for me and how do I overturn it · what is red and whose it is. Everything below the divider is for the next session, not the owner. It is not a pull-request description (which argues for a diff), not a changelog entry (which carries refinement context) and not a plan (which is frozen). It is mutable while `status: open` — a successor that re-proves a state line corrects it in place and appends one Timeline row — and **freezes when the owner has acted on § 1 (`status: accepted`)**; a correction after that is a new dated hand-over linking back. Raw artefacts (plans, hand-offs, notes) live in a same-named folder beside it.
+
+Required: **Verdict**, **Decide today**, **Live-world ledger** (even when empty), **See it work**, **Decided for you**, **Red board**, **What was built**, **Proof**, **State**, **Open loops**, **Artefacts & mandate**. Optional: Left alone, Discoveries, Debt, Cost, Timeline.
+
+**Reading order is act → verify → understand.** Owner half, ~20 minutes: Verdict (1) · § 1 (2) · § 2 (2) · § 3 (10, at the product) · § 4 (3) · § 5–6 (2). Successor half, read when the job arrives: § 8–14 (~10).
+
+````markdown
+---
+type: handover
+status: {open | accepted}
+date: {YYYY-MM-DD}
+as_of: {YYYY-MM-DDTHH:MM±TZ}
+as_of_commit: {sha}                # every § 9 claim is true of THIS commit and no other
+verdict: {done | done-needs-calls | partial | stopped-at-budget | failed}
+decide_today: {N}   irreversible_acts: {N}   decisions: {N}   red_mine: {N}   open_loops: {N}
+deployed:
+  - { plane: {dev|staging|production}, artifact: {name}, version: "{id}", by: {automatic|manual}, verify: "{command}" }
+prs:
+  - { n: {N}, base: {branch}, state: {open|draft|merged}, action: "{what the owner does}" }
+---
+
+# Hand-over — {what was built}, {YYYY-MM-DD}
+
+**{VERDICT TOKEN}.** {One sentence in the product's words: what exists and what a person can now do.}
+
+| | |
+| --- | --- |
+| Built | {N} units · {N} plans · ledger rows {N}, discharged {N}, blocked {N} |
+| Proof | {N} tests pass / {N} fail — on `{sha}`, verified {HH:MM} |
+| Decide today | **{N}** — § 1 |
+| Touched the live world | **{N}** acts, **{N}** you cannot undo — § 2 |
+| Red | {N} mine · {N} pre-existing · {N} environment — § 5 |
+| See it work | {N} min — § 3 |
+| Taken alone | {N} decisions, {N} stops filed of {N} — § 4 |
+
+**Start here:** `{the one command that brings the reader's machine to the state everything below describes}`
+**If you only act on one thing:** {act} — by {YYYY-MM-DD}, or {consequence}.
+
+## 1. Decide today
+
+| # | Decision or act | Why today | If you say nothing | Decide by | Do it (exact) | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | {one line, no mechanism} | {what a week costs} | {the outcome silence produces} | {date} | `{command}` / {PR link} / {UI path} | `{path:line · sha · PR}` |
+
+## 2. Live-world ledger
+
+Everything that left the repository, hardest to undo first. Verified {HH:MM}.
+
+| # | Act (past tense, dated) | Target (system + id) | Command | Reversible | Undo — exact | Evidence / backup + expiry |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | {what was done, {YYYY-MM-DD HH:MM}} | {named system} | `{exact}` | {no / with loss / yes} | `{command}` or {runbook path} — {or "forward only: …"} | {artefact · where · when it expires} |
+
+**Did not happen, and the proof:** {claim} — `{command}`.
+
+## 3. See it work in ten minutes
+
+**Before you start:** `{command}` · **Sign in as:** {who} · **Total:** {N} min
+
+| # | Do (URL → click) | You should see | It proves | If not |
+| --- | --- | --- | --- | --- |
+| 1 | {url} → {action} | {an observable a person can be wrong about} | {unit from § 6} | {§ 5 row, or "file it — new"} |
+
+## 4. Decided for you
+
+Each was taken because waiting would have stopped the run. Sorted by cost to reverse.
+
+| # | I decided | Instead of | Why | Authority | Landed at | Overturn — exact | If you say nothing | Hardens when |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| D-1 | {the ruling} | {the alternative, fairly} | {the constraint} | {owner said so HH:MM "…" / auto-ruled as recommended / taken alone — by {agent · model}} | `{file:line}` | `{edit or command}` | {default} | {event} |
+
+*Bulk: {N} per-plan questions ruled `as recommended, overturnable` — index at `{path}`. Only rows costing more than one commit to reverse are listed.*
+
+## 5. Red board
+
+| What's red | Where | Mine? | Proof | Blocks | Next step + owner |
+| --- | --- | --- | --- | --- | --- |
+| {test or command} | `{file:line}` | {mine / pre-existing / environment} | `{the command or stash that settled it}` | {what it stops, or nothing} | {act} — {who} |
+
+## 6. What was built
+
+| Unit | What it does for a person | Landed | Proof |
+| --- | --- | --- | --- |
+| {name} | {one clause, behaviour before mechanism} | {branch · PR · release} | {suite + counts, or "driven only", or empty} |
+
+## 7. Left alone
+
+| Thing | State | Why untouched |
+| --- | --- | --- |
+
+---
+
+*Everything above is for the owner. Everything below is for the next session.*
+
+## 8. Proof
+
+| Unit | Promise (clause) | Code @ | Pinned @ | Independent? | Rows p/o/b | Gap |
+| --- | --- | --- | --- | --- | --- | --- |
+| {plan} | {ruling n — five words} | `{sha7}` | `{sha7}` | {yes / **no — {who did both}**} | {n}/{n}/{n} | {G-n / —} |
+
+| # | Claim that is not proven | Why | What would prove it | Sev |
+| --- | --- | --- | --- | --- |
+| G-1 | {stated as the build would state it} | {blocked row / never driven / self-authored pin / no suite on this head / not recorded} | `{exact command}` | P{0-3} |
+
+## 9. State
+
+Present tense; every row true of `as_of_commit`, and every row re-provable by its own command.
+
+| Repo · branch | HEAD | vs upstream | Working tree | Worktrees | Re-prove |
+| --- | --- | --- | --- | --- | --- |
+
+| Plane | Artifact | Version | Deployed by | Re-prove |
+| --- | --- | --- | --- | --- |
+
+| Store | Env | Last destructive act | Backup + expiry | Re-prove |
+| --- | --- | --- | --- | --- |
+
+| Process / connection / token | Where | State | Check or stop |
+| --- | --- | --- | --- |
+
+## 10. Open loops
+
+| # | Loop | Whose | Next command or ask | Blocked by | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| L-1 | {present tense} | {session / owner / external} | `{command}` or {the question, with the default in force} | {id / —} | `{path:line}` |
+
+## 11. Discoveries — do not pay for these twice
+
+| # | Trap | The truth | Cost paid | Guard |
+| --- | --- | --- | --- | --- |
+| X-1 | {what it looks like from outside} | {present-tense fact} | {hours / runs} | `{command}` or `none — {what would hold it}` |
+
+## 12. Debt and can wait
+
+| # | What | Why not now | Re-open when | Parked at |
+| --- | --- | --- | --- | --- |
+| T-1 | {one line} | {the ruling} | {a trigger, not a date} | `{backlog row · issue · path:line}` |
+
+## 13. Cost
+
+**Wall-clock:** {Nh Nm} ({start} → {end}) · **unattended:** {Nh} · **Agents:** {N} · **Tokens:** {N | unmeasured — {what would measure it}} · **Rework:** {what was thrown away} · **Stops filed:** {N} of {N}
+
+## 14. Artefacts & mandate
+
+| Path | Holds | Volatile | Safe to delete after |
+| --- | --- | --- | --- |
+
+**Corpus:** {tracked at `{path}` @ {sha} | **UNTRACKED at `{path}` — {what would durably hold it}**}
+**May, alone:** {one line each} · **Must file or ask:** {one line each} · **Never:** {one line each}
+
+## 15. Timeline
+
+<!-- Append only. Never rewritten. -->
+
+- {YYYY-MM-DD HH:MM} — {event} (`{sha7}` / PR #{n})
+````
+
+## Field rules
+
+- **Verdict (≤14 lines).** One token from the closed set — `DONE` · `DONE, NEEDS YOUR CALLS` · `PARTIAL` · `STOPPED AT BUDGET` · `FAILED` — first in the body; a paragraph before it is a format violation. The scoreboard is always the same seven rows in that order, and a zero is written `0` — `Touched the live world: 0` is one of the most valuable lines the file can carry. `Start here` is exactly one command.
+- **§ 1 Decide today (≤7 rows).** Owner-only acts, sorted by cost of deferral descending. `Do it (exact)` is a command, a link or a literal UI path — `git revert -m 1 {sha}`, never "revert the merge". `If you say nothing` is mandatory and honest. **A decision has an alternative and belongs in § 4; an act outside the repository with no alternative is a chore and belongs here.**
+- **§ 2 Live-world ledger.** Required even when empty — `none — nothing left the repository`, with the command that proves it. Sorted hardest-to-undo first, never chronologically. `Reversible` takes three values: `no` states what now exists in the world, `with loss` names what is lost, `yes` carries the command. An act reversible only forward (redeploy, reseed, a superseding publish) is `no`, and the forward path goes in `Undo`. A backup states its expiry; copying a volatile backup somewhere durable is row 1 of § 1.
+- **§ 3 See it work (≤6 steps, ≤10 min).** Every `You should see` is an observable a person can be wrong about — a number, a named control, a status code — never "the page loads". It is the only check the owner performs with his own eyes rather than on the build's word.
+- **§ 4 Decided for you (≤10 rows).** Sorted by cost to reverse. `Authority` takes exactly three values — the owner said so (with the words and the time) · auto-ruled as recommended · taken alone — recorded per decision, never per run: it is the distinction an unattended run exists to preserve. `Overturn` is an edit or a command. `Hardens when` names the event after which reversal stops being cheap. A ruling with no reversal path is a constraint, not a decision — it moves to § 12.
+- **§ 5–7.** One home per fact: a red appears in § 5 even when a decision caused it, and the decision cites the row. `Mine?` is proved by the command or stash in `Proof`; `mine` is the default when no proof is offered. § 6 leads with behaviour, not plan slugs. § 7 exists so an owner scanning the repository does not mistake somebody else's branch for the run's debris.
+- **§ 8 Proof.** **An unproven claim is an empty cell, never a sentence** — prose has no empty cell to scan for. `Independent?` reads `no` whenever one agent authored both the code and its pin, or found, fixed and pinned the same defect, and names who. Ledger counts are parsed from the plan, never quoted from an agent's summary, so `blocked` cannot hide inside "discharged". Every `G-n` names the command that would close it.
+- **§ 9 State.** Present tense; a claim that cannot be re-proved by its `Re-prove` command does not belong here — it moves to § 15 as a dated event. Volatile things (`/tmp`, pid files, ports, tokens, browser connections) declare a lifetime and the command that makes them durable.
+- **§ 10–12.** A loop is a runnable command or a named question, never a noun phrase and never "investigate"; one needing a person's judgment states the question and the default in force. A discovery is a present-tense fact with a guard — "Workers Builds does not fire on a `dev` merge", not "we found that it didn't"; `none — {what would hold it}` is an honest guard that feeds the backlog. Debt names where it now lives, so this file can be deleted without losing it.
+- **§ 13–14.** Every uninstrumented number reads `unmeasured — {what would have measured it}`; a blank reports a cheaper run than the one that happened. **State whether the run's own corpus is version-controlled** — an untracked corpus is one `rm -rf` from being three PR descriptions, and archiving it is a § 1 row.
+- **Ids are stable and run-global** — `D-`, `G-`, `L-`, `X-`, `T-` — so a PR comment or a successor cites a row instead of re-describing it. A withdrawn row keeps its id and states what disproved it.
+- **Evidence is an address that outlives the run** — `path:line`, a 7-char sha, a PR number, a URL, or a command. A branch name is not a pointer; a `/tmp` log is not evidence — copy it into the record folder first.
+- **Blanket claims are banned.** "All suites green", "every ledger discharged", "nothing was deployed" carry a count and the sha they are true of, or they become a `G-n` row.
+- **The last act before showing the file is a contradiction pass**: the scoreboard against § 2, § 6 against § 1, every count against its source, every `{…}` resolved. An unresolved placeholder in an action cell is a defect of the same class as a broken command.

package/data/harnesses/delivery/skills/documentation/templates/operations-procedure.md

@@ -1,6 +1,6 @@
 # Operations Procedure (docs/operations/{procedure}.md)
 
-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.
+Truth document. Use for: any **recurring** procedure — development, deployment, maintenance. The one-time first run (prerequisites, install, env files, first commands, the stack) is not one of these: it has its own template and a fixed name, `templates/setup.md` → `docs/operations/setup.md`, one per repo. 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.