@nurix/etna 0.20.25 → 0.20.26

package/data/harnesses/etna/skills/documentation/templates/setup.md

@@ -0,0 +1,138 @@
+# Setup (docs/operations/setup.md)
+
+Truth document, operations genre (`type: operations`). Use for: **the one-time path from a fresh machine to a first verified run.** It covers what the repo is built on, prerequisites, install, env files, local services, the first commands, proof that it works, and the failures a fresh clone hits. There is **one per repo**, always named `setup.md`, and it is a mandated scaffold. The root README's only setup content is a Where-to-go row linking it.
+
+It is distinct from `local-development.md`, the daily loop: watch modes, resetting state, per-package traps, the inner test cycle. Setup runs once per machine. Local development runs every session. Setup ends by handing off to it, and neither copies the other. Deploying is `deployment.md`.
+
+Required: **Goal**, **Stack**, **Prerequisites**, **Install**, **First run**, **Verify**. Optional, included only with real content: the audience fork, **Before cloning**, **Environment files**, **Local services**, **Reset**, **Common failures**.
+
+### Writing rules
+
+- **Never write a version a file already pins.** Each row names the pinning file (`.nvmrc`, `package.json` `engines` / `packageManager`, `rust-toolchain.toml`, `go.mod`) and the command that checks it. A typed number is a second source that drifts on the next bump.
+- **Stack is one row per layer.** Give the technology, what it is for in this repo, and where its version is pinned. Why it was chosen belongs to `docs/architecture/`, linked once. Don't repeat the dependency list: the manifests are the roster.
+- **One path, from the lockfile.** `pnpm-lock.yaml` gives pnpm, `yarn.lock` gives yarn, otherwise npm. Say how it is activated (`corepack enable`). Never write "or npm / yarn". Give a per-OS variant only where the commands really differ.
+- **Traps before commands.** Anything a fresh clone hits before the first command goes in Before cloning, not halfway down the steps: LFS, submodules, a required stub file, an access grant, a credential that has to be requested.
+- **Copy-paste runnable, one action per step, each with its expected outcome.** Run non-interactively where the tool allows it, so an agent can execute the step unchanged. "It should work now" is never a step.
+- **Script first, then document.** If a bootstrap script or task exists, it is the step, and the doc carries only the judgment around it. A setup sequence run often with no script gets a script.
+- **Env files as a table, never a variable dump.** One row per file: where it is copied from, what must be filled, where the values come from, whether it is required to boot. The variable contract is the example file and the code's env type, linked and never copied. Secret values never appear.
+- **Destructive commands state their blast radius where they appear:** what is deleted or truncated, whether it prompts, and the flag that skips the prompt.
+- **Verification is observable:** a health probe and its expected status, a URL and what it shows, a seeded login, a doctor command and its output, or the test command passing from a cold shell.
+- **Common failures are keyed by the exact error text,** followed by the cause and the fix, where the fix is a command or a file edit. Append a failure only once it has been root-caused, never as speculation.
+- **Per-package divergence is a subsection of this file.** A unit whose setup differs gets a `### {unit}` block under First run, or a row linking its own procedure. It never gets a second setup doc.
+
+### Template
+
+```markdown
+---
+type: operations
+---
+
+# Setup
+
+**Goal:** take a fresh machine from clone to a verified first run of {what runs: e.g. "the product Worker on :{port} and the web shell on :{port}, signed in as the dev fixture"}. Done once per machine; the daily loop is [`local-development.md`]({local-development}.md).
+
+{Optional audience fork: "Only running {the CLI / one package}? Stop after Install and see [`{procedure}`]({path})."}
+
+## Stack
+
+| Layer | Technology | For | Version pinned by |
+| --- | --- | --- | --- |
+| {Runtime} | {Node} | {what runs on it} | [`.nvmrc`](../../.nvmrc) |
+| {Server} | {framework · data layer} | {what it serves} | [`{package.json}`](../../{path}/package.json) |
+| {Client} | {framework · build tool · styling} | {which surfaces} | [`{package.json}`](../../{path}/package.json) |
+| {Tests} | {runners} | {unit · e2e} | {manifest} |
+
+Why these were chosen: [{system overview}](../architecture/{overview}.md).
+
+## Prerequisites
+
+| Tool | Version from | Check |
+| --- | --- | --- |
+| {Node} | [`.nvmrc`](../../.nvmrc) | `node -v` |
+| {pnpm} | `packageManager` in [`package.json`](../../package.json), via `corepack enable` | `pnpm -v` |
+| {Docker / Rust / wrangler / …} | {pinning file, or "any current"} | `{command}` |
+
+- **Access:** {repo, secrets store, cloud account, registry token, and who grants each}.
+
+## Before cloning ← delete if none
+
+- **{Trap}:** {what a fresh clone hits and the one command that clears it, e.g. `git lfs install`, `git submodule update --init`}.
+
+## Install
+
+\`\`\`bash
+git clone {url} && cd {repo}
+corepack enable
+{pm} install                  # expect: {what a clean install ends with}
+\`\`\`
+
+## Environment files ← delete if none
+
+| File | Copy from | Fill | Values come from | Required to boot |
+| --- | --- | --- | --- | --- |
+| `{path/.dev.vars}` | `{path/.dev.vars.example}` | {keys, or "every blank"} | {vault, the owner, a generated local value} | {yes / no} |
+
+The contract is [`{example file or typed Env}`](../../{path}). Read it before concluding a value is missing. {Which of these files are gitignored.}
+
+## Local services ← delete if none
+
+| Service | Start | Port | Ready when |
+| --- | --- | --- | --- |
+| {local DB / emulator} | `{command}` | {port} | `{probe}` returns {expected} |
+
+## First run
+
+1. Prepare local state.
+
+   \`\`\`bash
+   {pm} --filter {unit} {migrate-and-seed}   # expect: {output}
+   \`\`\`
+
+2. Start the {backend}.
+
+   \`\`\`bash
+   {pm} --filter {unit} {dev:server}         # expect: listening on :{port}
+   \`\`\`
+
+3. Start the {frontend / CLI}.
+
+   \`\`\`bash
+   {pm} --filter {unit} {dev}                # expect: {URL}
+   \`\`\`
+
+4. Open `{http://localhost:port}` and {sign in as `{seeded user}` / reach `{first screen}`}.
+
+## Verify
+
+- `{curl -fsS http://localhost:{port}/{health}}` returns `200` {and `{body}`}.
+- `{doctor or status command}` reports {expected}. ← keep whichever exists
+- `{pm} {test}` passes from this cold shell ({expected tail}).
+
+## Reset ← delete if none
+
+| Command | Deletes | Prompts? |
+| --- | --- | --- |
+| `{pm} {reset-script}` | {local state at `{path}`} | {yes; `{FORCE=1}` skips / no} |
+
+## Common failures
+
+- **`{exact error text}`.** {Cause.} Fix: `{command or file edit}`.
+
+## Next
+
+The daily loop and its per-package traps: [`local-development.md`]({local-development}.md). Deploying: [`deployment.md`](deployment.md). Standing rules: [`CLAUDE.md`](../../CLAUDE.md).
+```
+
+### Baseline scaffolding behavior
+
+The baseline scaffolds `docs/operations/setup.md` when it is missing and the repo has a lockfile and at least one runnable root script. It fills each section from the repo:
+
+- **Stack:** from the workspace manifests, one row per layer.
+- **Prerequisites:** from the pinning files.
+- **Install and First run:** from the root README's getting-started block (if one exists) and the root scripts.
+- **Environment files:** from every `*.example` / `.dev.vars.example` in the workspace.
+- **Verify:** from a health route, a doctor command or the test script.
+
+It leaves Common failures empty until a failure is root-caused, and it drops every section it cannot fill concretely.
+
+**It never overwrites an existing `setup.md`.** If the repo already has a first-run procedure under another name, the baseline proposes the rename with a `note:` row and does not create a second file.

package/data/harnesses/etna/skills/documentation/templates/system.md

@@ -1,143 +1,59 @@
 # System Documentation (docs/architecture/systems/{system}.md)
 
-Truth document. Use for: **one machine that spans packages** — exactly how it works, end to end, in one place. One file per machine, named for the machine (`docs/architecture/systems/update-engine.md`). It states the machine's model and its whole path: what enters it, every stage it passes through, what it writes, what re-drives it when it stalls, and what a reader sees at the far end.
+Truth document. Use for: **one machine that spans packages**, which a person cannot point at — the walk, the egress, the ingest, the settlement, a gate, a sweep, a door an agent calls. One file per machine, named for the machine. A thing a person navigates to is a feature document, even when it owns tables; a unit of distribution is a package document.
 
-**A system document's globs win by specificity.** Its `owns:` names the subtrees and exact files the machine is made of — `packages/studio/src/server/execution/**`, `packages/ui/src/shared/harnessVocabulary.ts` — and those are narrower than the package document's `packages/studio/**`, so the system takes them and the package keeps the residue. That is the whole mechanism: **the package document is the residual owner and the system document is the specific one**, and nothing needs to be subtracted by hand. A machine confined to one package still gets a system document if the machine is the thing worth stating; it is the *narrower glob* that makes it a system, not the package count.
+**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Documents are read by people). A system document explains a machine to a person: what it is for, why it is split where it is split, how it behaves from the outside, what it guarantees at the far end, what re-drives it when it stalls. Its stages, tables, routes, frames, bindings and files are the code graph's (`docs/architecture/systems/knowledge-layer.md`), not a hand-typed tour. The body names code only at a cross-cutting seam another machine or feature would not find from its own files.
 
-**Two rules bind the globs.** Neither genre may claim a path another document claims at **equal specificity** — equal-specificity overlap is an ownership conflict to resolve before either document ships. And every glob **matches at least one file on disk** at `status: active`; projected globs are permitted only at `draft` and are confirmed when the document flips. Because a system's `owns:` list is long and hand-assembled, re-glob it whenever the machine's code moves — a stale entry here silently un-owns real code back to the package document, which does not describe it.
+**A system document's deepest layer is the machine's behaviour across packages** (`references/style-guide.md` § Shape — the model first, the detail after): the order it runs in, the sequence and state diagrams at role level, the invariant that holds at each place where parts meet, and what re-drives a stall. That layer is earned because no single file shows a cross-package flow. It stops before per-function steps, tables, columns and routes.
 
-**How this differs from its neighbours — and the mistake this template exists to prevent.** A **feature** document covers one capability or one page a person names and owns that surface's globs. A **package** document covers one unit of distribution and owns what is left of its tree. A **system** document covers a *machine*: something with an entry, stages, state and an outcome, which a person does not open and cannot point at. **The failure mode is a system document written as a giant feature document** — a tour of screens and what each button does, at ten times a feature doc's length. The test is mechanical: if the subject can be named by an address a person navigates to, it is a feature; if it can be named only as a verb over the product's own nouns — the walk, the egress, the ingest, the settlement — it is a system. A system document says what a surface *renders from* and links to the feature document for what the surface looks like; it never describes the surface.
+**A system document's globs win by specificity.** Its `owns:` names the subtrees and exact files the machine is made of, narrower than the package glob. Two documents never claim a path at equal specificity; every glob matches a file on disk at `status: active`.
 
-**Required vs optional.** Required in every system document: the **frontmatter**, the **opening statement** (what the machine is, then what this document states end to end), the **boundary paragraph** (what this document does not restate, and which document holds each part), the **machine diagram**, at least one **stage section**, **Files**, and **Related**. Everything else is optional. Do not add a section because it seems owed — a stage the machine does not have is a section that will be filled with something untrue.
-
-System documents are long by nature, because the point is that the whole machine is in one place — roughly 300 to 1000 lines. Length is earned by stages, never by restating a neighbour: every paragraph that could have been a link to the document that owns it is the genre's characteristic waste.
+**Required:** the frontmatter, the opening paragraph (the machine defined in its first sentence, what enters, what it leaves behind), the **boundary paragraph** (what this document does not decide, and which document does — subjects with owners, never bare links), **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 — the lint rules of the feature template apply. Sixty to a hundred and sixty lines.
 
 ```yaml
 ---
-owns:                                              # required — the machine's subtrees and exact files; narrower than the package glob
+type: system                                     # required tooling key
+status: active                                   # required — draft = the machine as a whole does not run
+objects: [run, run ledger, settlement]           # required — the objects this machine owns or moves
+owns:                                            # required until the graph computes ownership — narrower than the package glob
   - packages/{pkg}/src/{machine}/**
-  - packages/{pkg}/src/routes/{machine}.ts
-  - packages/{other}/src/shared/{machine}Vocabulary.ts
-keywords: [machine name, its nouns, its verbs]     # required — discovery terms: the machine's own vocabulary, the table and route names
-status: active                                     # required — active | draft | deprecated
-applies:                                           # optional — the decisions and doctrine this machine is BOUND by (obligation, not a bibliography)
+applies:                                         # optional — decisions and doctrine this machine is BOUND by
   - docs/architecture/decisions/AD-0NN-{slug}.md
-  - docs/architecture/common/{doctrine}.md
-type: system                                       # required tooling key — genre stamp; preserve on edits, never narrate
 ---
 ```
 
-> A system document carries no `module:` — a machine that spans packages belongs to no single
-> bounded context, and labelling it with one asserts a boundary it crosses by definition.
-> `last-reviewed:` is optional tooling metadata: preserve it, never narrate it.
-
 ```
 # {The machine}
 
-{One paragraph that defines the machine in its own first sentence — bold the term being defined —
-then says what this document states, in the order the body states it. The enumeration is the
-contract: a reader who wants one stage finds it by reading this sentence. Where the machine's
-purpose is easier stated as an outcome, lead with `**Goal:**` and one sentence instead.}
-
-{One paragraph: the boundary. What this document does **not** restate, and which document holds
-each part — the neighbouring systems, the package documents whose residue this sits inside, the
-feature documents that render from it, the common-plane doctrine it obeys, the decision records
-behind its shape. Name each with a link and the subject it holds. This paragraph is what keeps the
-document from growing into its neighbours.}
-
-```text
-{The machine diagram. One fenced block, drawn as the thing flows — entry at the top or left,
-each stage a box or a labelled arrow, the durable writes named, the re-drive path shown returning.
-Label the arrows with what crosses them, not with verbs. This is the picture a reader holds while
-reading the rest, so it carries the machine's real names — routes, tables, classes, files — and
-not generic boxes.}
-```
-
-{Optional, and worth its line whenever the body names paths: "Every path below is relative to
-`packages/{pkg}/src/{dir}/` unless it names another package."}
+{The machine defined in its first sentence — bold the term — then what it takes in, what it leaves behind, and what a reader sees at the far end. Plain words.}
 
-{Optional: a reading order for a long document — "§ X is the data; § Y is the code that reads it;
-§ Z is what re-drives it" — where the section list is not self-evidently a sequence.}
+{The boundary paragraph: what this document does not decide and which document does.}
 
-## The shape
+## Why it exists
 
-{Optional. Where the machine has parts a reader must hold at once before any stage makes sense,
-name them in one table before the stages begin.}
+{Why this is one machine and not two, what it deliberately is not, the constraint that shaped it.}
 
-| Part | Where | What it holds |
-| --- | --- | --- |
-| {Entry} | `routes/{x}.ts` | {thin, tenancy first} |
-| {Ledger} | `{machine}/ledger.ts` | {the durable row} |
+## How it works
 
-## {Stage sections — one per stage, in the order the machine runs them}
+{The machine's behaviour from the outside, in the order it runs, in plain words: what starts it, what it does at each step as a person would describe it, what it writes that outlives it, what re-drives it, what it refuses. Terms of art introduced on first use. Code named only at a seam.}
 
-{The body, and the only genre where the section order is decided for you: the machine's own order.
-Entry, then each stage, then what is written durably, then what re-drives a stalled one, then what
-reads the result. Name each section for its stage in the product's own vocabulary. Within a
-section, state the mechanism and its reason: what the code does, what it refuses, and why it
-refuses that rather than something else. Tables for rosters (routes, columns, frames, states,
-bindings); prose for a rule and the defect it prevents. Never paste an implementation — a
-signature, a state list, a wire shape, a table's columns.}
+## What was decided
 
-## Tests
+{Themed paragraphs; alternatives named only where a reader would reach for them.}
 
-{Optional. What proves this machine, and what each suite pins — a `Suite | Pins` table. Include it
-where the machine has a suite of its own; omit the heading where the coverage lives in the package
-documents' suites.}
+## What it promises
 
-## Files
+{Checkable guarantees and refusals, grouped; what holds at the far end; what a stalled run gets.}
 
-| Path | Role |
-| --- | --- |
-| `packages/{pkg}/src/{machine}/{file}.ts` | {what it holds, by name — the exports a reader is looking for} |
+## Known gaps
 
-{One row per file this document owns — the roster is the `owns:` list, made readable. Close with
-the inverse: "Read here, owned elsewhere:" naming the paths the body describes but another document
-claims, each with the document that claims it. That closing line is what stops a system document
-from quietly annexing the code it reads.}
+{One paragraph, only when needed.}
 
-## Related
+## For the agent
 
-- [AD-0NN — {the ruling}](../decisions/AD-0NN-{slug}.md) — {the decision behind this shape, the options weighed}
-- [`{neighbour}.md`]({neighbour}.md) — {the machine on the other side of this seam}
-- [`{feature}.md`](../../features/{feature}.md) — {what a person sees of this machine}
-- [`{doctrine}.md`](../common/{doctrine}.md) — {the cross-cutting contract this machine answers to}
+Objects: {…}. Code roots {…} — directories, one per package the machine spans. Seams {…} by name. Checklist `tests/{system}.md`. See also {neighbour} ({why}). No tables, routes or symbol rosters — those are the graph's.
 ```
 
-### The boundary paragraph is the genre's load-bearing section
-
-Systems overlap: they share tables, call each other, and render into the same surfaces. Without a
-paragraph that names the seams, two system documents describe the same stage from two angles and
-drift apart on the first change — and a reader has no way to tell which is authoritative. So the
-boundary paragraph is not a courtesy list of related reading; it is the statement of what this
-document is *not*, written specifically enough that a later editor can tell where to put a fact.
-Write it as a list of subjects with their owners — "the coordinator's tables, alarm and drive claim
-are `harness.md`; a run's ledger row and settlement are `generation-runs.md`" — never as bare
-links.
-
 ### Marking what is decided and unbuilt
 
-Where the machine has a stage that is decided and not built — a predicate that selects but never
-acts, a column that is written and never read, a door with no caller — wrap the prose in a marker
-so the gap is machine-findable and its evidence travels with it:
-
-```
-<!-- UNBUILT:START — {what is decided, where it is decided (an AD § or an owner ruling), and the
-source evidence that it is not built: the function with no caller, the route that is not mounted,
-the value written and never read} -->
-{the prose describing the unbuilt stage, and what runs in its place}
-<!-- UNBUILT:END -->
-```
-
-**State what runs instead.** A machine with a hole in it still works somehow, and the workaround is
-the fact a reader needs. **A design decided *against* carries no marker** — a marker means the work
-is owed and absent, so using one for a rejected design turns the register of debt into a register
-of opinions.
-
-### `status: draft` on a system
-
-A system document is `draft` when the **machine as a whole** does not run — the code is on disk and
-nothing reaches it. Say so in the first section, in plain words, with the evidence: which halves
-exist, which do not, and what a reader who invokes it actually observes. A scoped gap in a working
-machine is not a draft: the document stays `active` and takes an UNBUILT marker at the stage that
-has the hole.
+Where a stage is decided and not built, wrap its prose in `<!-- UNBUILT:START — {what, where decided, the evidence it is not built} -->` … `<!-- UNBUILT:END -->` and say in What it promises what runs instead. A design decided *against* carries no marker.

package/lib/install/materialize.mjs

@@ -3,20 +3,12 @@
 // harness's files land — a bundle says `skills/design/SKILL.md`, a project says
 // `.claude/skills/design/SKILL.md`, and this module is the only place that mapping exists.
 //
-// TWO SHIPPERS, ONE MAPPING. `bin/etna.js` calls this against the user's cwd; the NuStack push
-// (`.github/scripts/push-harnesses.mjs`) calls it against a throwaway directory and ships the
-// result, so an App's export from NuStack extracts as the same tree `npx @nurix/etna` writes.
-// They diverged once — the push sent the BUNDLE layout, so a downloaded project had its
-// instruction tree at the archive root, no AGENTS.md, and no wired hooks, while the manifest
-// claimed otherwise. One function is what stops that recurring.
-//
-// ZERO DEPENDENCIES, BY NECESSITY. The push runs in CI without an `npm install` (that workflow
-// reaches `npm publish` → `prepack` and nothing else), so this module and everything it imports
-// may use only what Node ships. That rules out importing `bin/etna.js`, which pulls in
-// @clack/prompts for its UI — hence the extraction rather than a re-export.
+// ONE MAPPING, COMPUTED ONCE. `bin/etna.js` calls this against the user's cwd; the placement
+// itself comes from `planHarnessFiles`, so the installed tree and the compiler's array cannot
+// describe different trees — the suite runs both and compares.
 //
 // PURE FILE OPS, NO UI. Every human-facing string is RETURNED (installed/notices/warnings) and
-// printed by the caller, so the push can discard what the CLI renders.
+// printed by the caller, which is what leaves presentation to the CLI alone.
 
 import {
   existsSync,

package/lib/install/plan.mjs

@@ -2,17 +2,10 @@
 // THE HARNESS COMPILER: one bundled harness definition in, the exact file list a fresh install
 // produces out. Pure — it reads the bundle and returns data, and writes nothing.
 //
-// This is the single authority on WHERE a harness's files land and WHAT is in them. Both shippers
-// consume it and neither re-derives it:
-//
-//   push-harnesses.mjs  → publishes the array to NuStack verbatim
-//   materializeHarness  → writes the array to a project, applying each entry's policy
-//
-// They diverged once, and that is the whole reason this file exists. The NuStack push used to walk
-// the BUNDLE directory and send those paths, so a project downloaded from NuStack Studio extracted
-// with its instruction tree at the archive root where no runtime looks for it, no AGENTS.md, and no
-// hooks wired into settings.json — while the export manifest claimed the folder was ready to open.
-// Nothing failed: every file was present, only its location was wrong.
+// This is the single authority on WHERE a harness's files land and WHAT is in them.
+// `materializeHarness` writes the array this returns, applying each entry's policy, and re-derives
+// nothing — so a bundle path (`skills/design/SKILL.md`) becomes an installed path
+// (`.claude/skills/design/SKILL.md`) in exactly one place.
 //
 // PURE, AND THAT IS THE POINT. Deriving the payload by installing into a temp directory and reading
 // it back works, but it is disk I/O to compute a mapping — and it hides the mapping inside a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.25",
+  "version": "0.20.26",
   "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
   "scripts": {
     "test": "node --test 'tests/**/*.test.mjs' '../../harness/code/hooks/tests/*.test.mjs'",
     "build:data": "node scripts/build-data.js",
+    "harness:cdn": "node scripts/build-data.js && node scripts/upload-harness-cdn.mjs code",
     "prepack": "node scripts/build-data.js",
     "validate:codex-agents": "node lib/codex/validate-codex-agents.mjs"
   },
@@ -42,5 +43,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "c24bc6f1af10"
+  "etnaFingerprint": "9db89d92a35b"
 }

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

@@ -1,71 +0,0 @@
-# docs/structure.md (Authority Map)
-
-Truth document. Use for: defining which folder owns which topic and how docs are maintained.
-
-```
----
-harness-version: 1.0.0
----
-
-# Documentation Structure
-
-> This file is the entry point for understanding the docs folder.
-> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
-
-## Authority Map
-
-Each topic has one canonical location. Read from here, not from plans or changelogs.
-
-| Topic | Authority | Key Files |
-| ----- | --------- | --------- |
-| Code-path ownership (path → doc + module) | `owns:` frontmatter on features, packages and systems | the generated ownership index |
-| System overview | `docs/architecture/` | system-design.md |
-| One workspace package | `docs/architecture/packages/` | {package-folder}.md |
-| One machine spanning packages | `docs/architecture/systems/` | {machine}.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/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
-| 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/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
-| Backlog | `docs/history/` | backlog.md |
-
-## The Two Natures
-
-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.
-
-- 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 owning doc's `owns:` globs into the injected ownership index.
-- `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. The cross-cutting doctrine directly under `architecture/` (and under `architecture/common/` where a repo separates it) **owns no code** — it describes patterns every surface obeys, and `applies:` is how a surface declares it is bound.
-- `docs/architecture/packages/`: One doc per workspace package (`{package-folder}.md`), present in a workspace repo. Each is the **residual owner** of its tree — `owns: ["packages/{name}/**"]` — describing the manifest, build, entry, layout and every behavior no system or feature doc claims at higher specificity. Template: the `documentation` skill's `templates/package.md`.
-- `docs/architecture/systems/`: One doc per machine that spans packages (`{machine}.md`) — the walk, the egress, the ingest. Its `owns:` names the machine's own subtrees and files, narrower than the package glob, so it wins those paths by specificity and the package doc keeps the rest. Not a surface doc: what a person sees stays in `docs/features/`. Template: the `documentation` skill's `templates/system.md`.
-
-**Three genres carry `owns:`** — features, packages, systems — and no others. Their globs layer by specificity (package `**` residual, system and feature narrower), and two docs may never claim a path at **equal** specificity: that is an ownership conflict to resolve, not a duplication to live with. Every glob matches at least one file on disk at `status: active`.
-- `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. One entry per unit of work (`YYYY-MM-DD-{three-words}.md`), written by whoever does the work and frozen inside the commit it describes. Entries carry the refinement context a diff cannot show — the ask in the user's words, iterations and rejections, skill survived/overridden verdicts, discoveries, pins. Format is the `documentation` skill's `templates/changelog-entry.md`; trigger and lifecycle are the `changelog` rule; distillation is the `retro` agent. Immutability begins at commit — a draft in the working tree is mutable until then, never after. Every entry appends a row to `docs/history/CHANGELOG.md`.
-- `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/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. 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 routes its conclusions into `architecture/`/`features/`/`history/`. (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
-
-<!-- Updated by maintenance agent — the sanctioned dated tail in this truth doc (SKILL.md § The Two Natures names the two bridges) -->
-| Date | Review Summary |
-| ---- | -------------- |
-| {today} | Initial baseline — v{harness-version} structure established |
-```

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

@@ -1,71 +0,0 @@
-# docs/structure.md (Authority Map)
-
-Truth document. Use for: defining which folder owns which topic and how docs are maintained.
-
-```
----
-harness-version: 1.0.0
----
-
-# Documentation Structure
-
-> This file is the entry point for understanding the docs folder.
-> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
-
-## Authority Map
-
-Each topic has one canonical location. Read from here, not from plans or changelogs.
-
-| Topic | Authority | Key Files |
-| ----- | --------- | --------- |
-| Code-path ownership (path → doc + module) | `owns:` frontmatter on features, packages and systems | the generated ownership index |
-| System overview | `docs/architecture/` | system-design.md |
-| One workspace package | `docs/architecture/packages/` | {package-folder}.md |
-| One machine spanning packages | `docs/architecture/systems/` | {machine}.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/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
-| 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/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
-| Backlog | `docs/history/` | backlog.md |
-
-## The Two Natures
-
-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.
-
-- 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 owning doc's `owns:` globs into the injected ownership index.
-- `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. The cross-cutting doctrine directly under `architecture/` (and under `architecture/common/` where a repo separates it) **owns no code** — it describes patterns every surface obeys, and `applies:` is how a surface declares it is bound.
-- `docs/architecture/packages/`: One doc per workspace package (`{package-folder}.md`), present in a workspace repo. Each is the **residual owner** of its tree — `owns: ["packages/{name}/**"]` — describing the manifest, build, entry, layout and every behavior no system or feature doc claims at higher specificity. Template: the `documentation` skill's `templates/package.md`.
-- `docs/architecture/systems/`: One doc per machine that spans packages (`{machine}.md`) — the walk, the egress, the ingest. Its `owns:` names the machine's own subtrees and files, narrower than the package glob, so it wins those paths by specificity and the package doc keeps the rest. Not a surface doc: what a person sees stays in `docs/features/`. Template: the `documentation` skill's `templates/system.md`.
-
-**Three genres carry `owns:`** — features, packages, systems — and no others. Their globs layer by specificity (package `**` residual, system and feature narrower), and two docs may never claim a path at **equal** specificity: that is an ownership conflict to resolve, not a duplication to live with. Every glob matches at least one file on disk at `status: active`.
-- `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. One entry per unit of work (`YYYY-MM-DD-{three-words}.md`), written by whoever does the work and frozen inside the commit it describes. Entries carry the refinement context a diff cannot show — the ask in the user's words, iterations and rejections, skill survived/overridden verdicts, discoveries, pins. Format is the `documentation` skill's `templates/changelog-entry.md`; trigger and lifecycle are the `changelog` rule; distillation is the `retro` agent. Immutability begins at commit — a draft in the working tree is mutable until then, never after. Every entry appends a row to `docs/history/CHANGELOG.md`.
-- `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/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. 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 routes its conclusions into `architecture/`/`features/`/`history/`. (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
-
-<!-- Updated by maintenance agent — the sanctioned dated tail in this truth doc (SKILL.md § The Two Natures names the two bridges) -->
-| Date | Review Summary |
-| ---- | -------------- |
-| {today} | Initial baseline — v{harness-version} structure established |
-```