@nurix/etna 0.18.16 → 0.18.18

package/data/harnesses/etna/CLAUDE.md

@@ -1,150 +1,160 @@
 # Agent Instructions
 
-This file defines how AI agents (Claude, GPT, etc.) should work on this project.
+This repo is **etna — the forge** where every Nurix harness is authored: skills, agents, rules, and harness definitions, composed into plugins and shipped to consumer repos by the `@nurix/etna` CLI. Working here means editing **authoring artifacts** — almost all markdown, plus the CLI and hook scripts (ESM JS) — not application source. etna has no `src/` app, no database, and no runtime API of its own; the code-project scaffolding you may expect (schema, wire contracts, a test suite) mostly doesn't apply, and where a rule below would in a normal repo, it's reframed for the forge.
+
+etna governs itself with the **`etna`** harness — deliberately forked from the **`code`** harness it ships, so a capability added to `code` (a new mode, a new agent) never silently lands in the forge's own governance. Rules marked **[override]** deliberately replace a Claude Code default; the rule here wins.
 
 ---
 
-## Getting Started
+## Maintenance
 
-- Read **[`docs/structure.md`](docs/structure.md)** for the documentation map and folder authority (architecture, features, operations)
-- Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent)
-- Ignore **[`README.md`](README.md)** – it's for human reference only
-- Check **[`package.json`](package.json)** for available scripts. Detect the package manager from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm) and use the matching command. Don't hardcode a specific manager.
-- Look at similar modules/files and follow existing patterns
+Invoke the `maintenance` agent whenever you judge the docs need it — not just at first setup. Standing triggers: a `harness-version` marker behind the installed version, docs contradicting the components they describe, unowned source paths, or drift you notice while working. Don't reconcile these by hand:
 
-> **If you are a Claude agent** (for example, `claude-4.5-sonnet`) — other agents ignore: Check **[`.claude/rules/`](.claude/rules/)** for specialized instructions (automatically loaded into memory) Skip the next step — `.github/instructions/` contains the same files as `.claude/rules/`
+1. Invoke `maintenance` ("reconcile the harness" / "docs health"). It auto-selects its mode — baseline when the version marker is missing or behind, coherence audit otherwise — then hands back.
+2. If it hands back a follow-up (typically the module proposal), re-invoke it to finish.
 
-- Review **[`.github/instructions/`](.github/instructions/)** for coding conventions (Claude agents: see note above)
+Each component's internals live in the component, not here.
 
 ---
 
-## Workflows
+## Getting Started
 
-For new features or new systems, enter **LLD Mode** (low-level design) before Plan Mode.
+- Read **[`docs/structure.md`](docs/structure.md)** — the documentation authority map (what belongs in `architecture/`, `features/`, `operations/`, `skills/`, `history/`, `memory/`). Don't restate it here.
+- Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent).
+- Prefer `docs/` over `README.md` — `docs/` is canonical for agents.
+- The CLI and hooks are the only real code — detect the package manager from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else npm) for anything under `packages/`.
 
-### LLD Mode → Plan Mode → Completion
+---
 
-1. **LLD Mode**: Create or update the feature LLD in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see `.claude/skills/documentation/references/templates.md` §6. Use the **`lld-mode`** agent (`.claude/agents/lld-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the LLD for approval before proceeding.
+## Authoring & Distribution
 
-2. **Plan Mode**: Once the LLD is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template** (see `.claude/skills/documentation/references/templates.md` §8). Link back to the feature LLD in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill parses them to check boundary impact.
+etna authors the components it also runs and ships, so **three copies of every component exist** — know which you are editing:
 
-3. **Completion**: When a plan is fully implemented:
-   - Mark the plan `Status: Complete` in `docs/history/plans/` and fill the **Completed:** date. The plan is now frozen.
-   - **Flip the feature LLD** to `status: active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. Confirm the feature's `owns:` globs against actual code; resolve any unresolved Open Questions by folding them into Background.
-   - Use the injected ownership index to find other docs affected by the changes (and update the `owns:` globs of any feature doc whose source you moved or added). Update affected docs — or create new ones if a touched area has no doc yet.
+| Copy | Where | Role |
+| --- | --- | --- |
+| **Source** (canonical) | the shared catalogs — `skills/`, `agents/`, `rules/`, plus `plugins/*/` (composition) and `harness/*/` (harness definitions) | Edit here. Etna is the source of truth. |
+| **Dogfood** | `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, `.claude/hooks/` (git-tracked) | The subset the `etna` harness installs on itself — the copy this repo actually runs this session. |
+| **Shipped bundle** | `packages/cli/data/harnesses/*/` (gitignored, built by `packages/cli/scripts/build-data.js`) | Generated at publish. Never hand-edit. |
 
-For **Product-level** work (new systems, unclear scope), the LLD should also include: problem statement, key hypotheses, and open questions.
+- **Keep source and dogfood in sync.** When you edit a component etna dogfoods, mirror the change into its `.claude/` copy in the same change — otherwise the skill this session runs diverges from the one you authored.
+- **A component edit ships.** On push to `dev`, CI fingerprints the payload, patch-bumps, and publishes to the marketplace and `@nurix/etna` npm — reaching every consumer repo. Weigh catalog edits with that blast radius in mind. The pipeline authority is **[`docs/architecture/distribution.md`](docs/architecture/distribution.md)** — link, don't restate.
 
-`docs/features/` is _what_ we're building (lives on as documentation). `docs/history/plans/` is _how_ we built it (historical record).
+---
 
-### Context Routing
+## Workflows
 
-Before modifying code in an unfamiliar area:
+Three peer modes plus a Completion step — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here. "Code" below means **authoring artifacts** — a feature LLD owns `skills/**`, `plugins/**`, `packages/cli/**`, not `src/`.
 
-1. Consult the **injected ownership index** — the generated `glob → doc · module · keywords · status` map, surfaced into context at session start (the union of every feature doc's `owns:` frontmatter). Match your path or topic (its `keywords:`) to the owning doc and read it before changes. (If no ownership index appears in context, the repo isn't reconciled — run `maintenance` in baseline mode to reconcile it.)
-2. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
-3. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
+| Mode | Enter when | Implemented by | Exits to |
+| --- | --- | --- | --- |
+| **Brainstorming** | explicit ask (`/brainstorm start`); or the user brings a large piece of work — a new component, a design with many unknowns — most users don't know this mode exists, so recommend it: name what makes the work big and offer a session; or a user utterance contradicts a recorded design principle (a pillar) → name the principle and offer a session. Never auto-enter. | `brainstorm` agent + skill | LLD, Plan, or close + harvest |
+| **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 |
 
-For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
+> 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.
 
-### Project Memory
+**On Plan Completion:**
 
-Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in `~/.claude/` (untracked).
+1. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
+2. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual components.
+3. The `boundary` skill must already have gated this plan before its first implementation step — see Ownership, Boundaries & Documentation.
 
-| File | Owner | Contents |
-| --- | --- | --- |
-| `docs/memory/main.md` | Main agent | Project-wide patterns, conventions confirmed in this codebase, recurring failure modes, decisions whose rationale isn't obvious from the code |
-| `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective on this project (research patterns, taxonomy, ownership conflict zones). Never user-centric. |
-| `~/.claude/projects/...` | Auto-memory system | User preferences, role, communication style, cross-project habits |
+**On Brainstorm Close** (when a session ends, not when a plan completes):
 
-**Override the default auto-memory location for project-relevant facts.** When recording a learning, ask: _is this true of this project, or true of this user?_ Project facts → `docs/memory/`. User facts → `~/.claude/`.
+- 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`.
+- Open questions block close.
 
-`docs/memory/main.md` is created on first write. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
+---
 
-### Out-of-Scope Discovery
+## Ownership, Boundaries & Documentation
 
-When implementing a plan, if you discover work that is important but outside the current plan's scope:
+These three mechanisms keep the repo self-updating: **ownership** routes you to the canonical doc before you touch a component, the **boundary** check reads both sides of every contract your change participates in so you can't ship one side of it, and **documentation** closes the loop so the next session inherits the truth. Skipping any leg breaks the other two.
 
-- Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
-- Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
-- Do NOT ask permission. Just append and mention it in your response.
+### Ownership — route before you edit
 
-### Doc Ownership
+Which doc is canonical for which paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (path globs — the only ownership key, pointing at `skills/**`, `plugins/**`, `packages/cli/**`, …), an optional `module:` label, `keywords:`, and `status:`. Path → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and own nothing; operations docs describe procedures.
 
-Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures.
+Before modifying a component in an unfamiliar area:
 
-The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the LLD before proceeding.
+1. Consult the **injected ownership index** — the `glob → doc · module · keywords · status` map. Match your path or topic to the owning feature doc and read it first. (No index in context ⇒ the repo isn't reconciled — see Maintenance.)
+2. If a `docs/memory/` file exists for the area, read it for domain knowledge and failure modes.
 
----
+The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. Resolve them in the LLD before proceeding.
 
-## Boundaries
+### Boundaries — check while you change
 
-A boundary is a horizontal cross-cutting contract — entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config — where editing one side silently breaks the other. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source whenever a check runs, so they are never persisted as docs and can never go stale.
+etna has no db schema, wire envelope, or auth of its own — the `boundary` skill's stack mechanisms describe the contracts of the **rules etna ships**, checked in the consumer's repo, not here. etna's **own** live contracts are authoring and distribution ones, each with no static link between the two sides:
 
-**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/mechanisms.md` defines the failure mechanisms; technology packs under `references/packs/` carry stack specifics), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
+- a plugin `definition.md`'s `skills:` / `rules:` / `agents:` list ↔ the shared catalogs it resolves from (local-first);
+- a component's **source ↔ `.claude/` dogfood ↔ shipped bundle** (three-way parity, per Authoring & Distribution);
+- a hook script ↔ its `hooks.json` registration;
+- the CLI's managed-block edits ↔ a consumer's `settings.json` / `.env`.
 
-> Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
+Invoke the `boundary` skill after a plan is approved and before its first implementation step — it parses the plan's Proposed Changes, reads the touched source fresh, and reports severity-ranked violations with a pass/block verdict, read-only. Fold the amendments in before coding. For a component etna ships, its boundaries also include whatever contracts that component asserts once installed in a consumer repo.
 
----
-
-## Boundaries & Defaults
+### Documentation — close the loop
 
-Unless explicitly requested:
+- **[override]** Keep `docs/` updated when a change alters documented behaviour — creating and updating docs is part of the work.
+- After plan completion **[override]**: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md`, no confirmation needed (include `Commits:` if multi-commit). Non-plan changes (refactors, fixes): prompt first.
+- When you move or rename a component: update the `owns:` globs of the feature doc that owns it so the ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter.
+- `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; one canonical source per topic, link don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
-❌ **Tests** – Never generate, update, or modify test files. ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies. ❌ **Compatibility** – Never maintain backward compatibility unless specified. ❌ **Browser Automation** – Never use "Claude in Chrome" (CDP/MCP browser tools) unless the user explicitly requests it. ❌ **Protected Files** – Never modify these read-only files: `AGENTS.md`, `.github/instructions/`, `.github/prompts/`, `docs/operations/protected-files.md` ✅ **Documentation** – Keep `docs/` updated when code changes affect documented behavior. ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one. ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
+> Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
 
 ---
 
-## File Structure
+## Project Memory
+
+Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in `~/.claude/` (untracked).
+
+| File | Owner | Contents |
+| --- | --- | --- |
+| `docs/memory/main.md` | Main agent | Project-wide patterns, conventions confirmed in this repo, recurring failure modes, decisions whose rationale isn't obvious from the components |
+| `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective here. Never user-centric. |
+| `~/.claude/projects/...` | Auto-memory system | User preferences, role, communication style, cross-project habits |
 
-- Add file path at top of each file: `// src/modules/example.js - Module for handling user authentication`
-- Add a 1-line function description as a comment above each function: `// Extract JWT token from request based on endpoint type`
-- Keep related code together in a logical hierarchy.
-- No inline comments that restate obvious code. No commented-out code. If a block of code needs a comment to be understandable, refactor for clarity instead.
+Override the auto-memory default for project-relevant facts. When recording a learning, ask: _true of this project, or true of this user?_ Project facts → `docs/memory/`. User facts → `~/.claude/`. `docs/memory/main.md` is created on first write; append entries dated `## YYYY-MM-DD — {topic}`.
 
 ---
 
-## Documentation
+## Out-of-Scope Discovery
 
-- **[`docs/structure.md`](docs/structure.md)** – Documentation authority map (start here for all docs)
-- Only `CLAUDE.md`, `AGENTS.md`, and `README.md` are allowed in the repository root
-- One canonical source per topic — link, don't copy
+When implementing a plan, if you discover work that is important but outside the current plan's scope:
 
-### Folder Structure
+- Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
+- Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
+- Do NOT ask permission. Just append and mention it in your response.
 
-The six procedural folders below are fixed. Domain folders (e.g. `core/`) live as subfolders inside these — `docs/architecture/core/` for core module internals, `docs/features/{group}/` as browse-only groupings (never modules). Discovery flows through the generated **ownership index** (from feature `owns:`/`keywords:` frontmatter), injected at session start.
+---
 
-| Folder | Purpose | Mutability |
-| --- | --- | --- |
-| `docs/architecture/` | System-wide patterns, technical decisions, API specs | Living |
-| `docs/features/` | How implemented features work today | Living |
-| `docs/operations/` | Setup, development, deployment | Living |
-| `docs/history/` | Plans, changelogs, backlog | Frozen or append-only |
-| `docs/memory/` | Project knowledge + agent state | Living |
-| `docs/tests/` | Test plans and automation | Living |
+## Guardrails & Defaults
+
+❌ prohibitions hold unless the user explicitly asks otherwise; ✅ and ⚠️ items are standing policy:
 
-### Naming & Lifecycle
+- ❌ **Tests** — etna is a markdown-authoring repo plus a small CLI with no test suite; never generate, update, or modify test files unless the user explicitly asks. (The `code` harness ships a suite-first posture for the projects it governs — that is a shipped rule, not etna's own.)
+- ❌ **Dependencies** — never upgrade frameworks, libraries, or dependencies.
+- ❌ **Compatibility** — never maintain backward compatibility unless specified.
+- ❌ **Branches & Worktrees [override]** — never self-create git branches or worktrees; commit straight to the checked-out branch. This replaces any built-in "branch first on the default branch" default. Exception: when the user asks for a pull request, create the branch the PR requires before committing its changes.
+- ❌ **Protected Files** — before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; never modify `AGENTS.md` or that file itself.
+- ✅ **Browser Automation** — Claude in Chrome / CDP browser tools only when the user explicitly asks.
+- ✅ **Delegate at scale** — offload large, independent, or parallelizable work (broad research, audits, multi-file sweeps) to sub-agents with self-contained prompts; keep small, well-understood edits inline. Sub-agents can't run skills or spawn sub-agents — do that work in the main session.
+- ⚠️ **Plans** — created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Abandoned`, frozen — never edited. If scope changes after completion, write a new dated plan linking back.
+- ⚠️ **Tool Issues** — if any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool, command, and error to the user so they can fix the underlying library.
 
-- Features: `kebab-case.md` — living reference, status `Active`
-- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
-- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
-- Memory: `{agent-name}.md` — agent-maintained
+---
 
-### Documentation Maintenance
+## Authoring Conventions
 
-- **Prerequisite**: Before creating changelogs, feature docs, or plans, check that `docs/memory/index.md` exists and records a baseline. If not, prompt the user to baseline docs first.
-- After plan completion: create a `docs/history/changelog/YYYY-MM-DD-feature-name.md` entry + update the index in `docs/history/CHANGELOG.md` (no confirmation needed). Root-level `CHANGELOG.md` is not used — only `CLAUDE.md`, `AGENTS.md`, and `README.md` live in the repo root.
-- Update related docs affected by the changes (use the injected ownership index — feature `owns:` globs — to find the right files)
-- Non-plan changes (refactors, bug fixes, API changes): prompt user first
-- Multi-commit changes: include `Commits: abc1234, def5678`
+Most artifacts are markdown — skills, agents, rules, docs. Follow the conventions in `docs/skills/` and the `kb` / `nomenclature` rules; markdown has no file-path-comment rule. Keep the `.claude/rules/*` reference docs frontmatter-free.
 
-### Keeping the Loop Tight
+For real code (the CLI under `packages/`, hook scripts):
 
-When you create a new doc that owns code:
+- File-path header comment at the top, in the file's comment syntax: `// packages/cli/bin/etna.js - the installer entry`.
+- A 1-line description above each function whose purpose isn't evident from its name and signature. A comment that restates the name is noise; no commented-out code — if a block needs a comment to be understandable, refactor instead.
 
-- Declare the code paths it owns in its own `owns:` frontmatter (plus `module:`/`keywords:`/`status:`); the generated ownership index picks it up at the next session start.
-- Verify its `owns:` globs don't overlap another feature doc's at equal specificity.
+---
 
-When you move or rename source files:
+## Runtime Notes
 
-- Update the `owns:` globs of the feature doc that owns them to the new paths.
+etna runs in Claude Code. Sub-agent dispatch is the Agent tool; sub-agents can't run skills, spawn sub-agents, or hold the browser connection (browser work is Claude in Chrome, main session only). The user-level memory store is `~/.claude/` (auto-memory under `~/.claude/projects/...`). The ownership index and skill/agent descriptions are injected at session start; skills are invoked as slash commands (e.g. `/brainstorm start`). If pinning dispatch tiers: strong tier (opus-class) for judgment-heavy work, fast tier (sonnet-class) for mechanical fan-out — tier names go stale, re-check on model releases.

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

@@ -80,6 +80,8 @@ For each changed file:
 - If no glob matches → flag as **unowned**.
 - If an owner exists → compare last-modified dates (`git log -1 --format="%ci" -- <path>`), flag docs where code changed more recently (14-day threshold).
 
+**Audit priority.** Rank the docs to inspect by their `last-reviewed:` frontmatter (optional key): never-stamped first, then oldest-first. A doc reviewed last week rarely needs a re-read; one never stamped is the likeliest to have drifted.
+
 ### Step 4: Check architecture & backlog
 
 **Unowned paths.** Compare the repo's actual top-level source directories (derive them — the top-level dirs that contain code, or the roots named across the `owns:` globs; do not assume `src/`) against the `owns:` map. Report directories no `owns:` glob covers.
@@ -97,6 +99,8 @@ For each stale doc:
 - If drift is clear (renamed function, new export, changed props) → update the doc directly.
 - If drift is ambiguous (major refactor, unclear intent) → backlog it.
 
+For each feature doc you verified accurate or updated this pass, stamp `last-reviewed:` in its frontmatter with today's date (add the key if absent). Never write review dates into the body — it's frontmatter metadata only.
+
 For unowned code paths:
 
 - Append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory).

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "018554d4192f"
+  "digest": "e76a61b23051"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, or (10) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD".
+description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance), or (11) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD".
 ---
 
 # Technical Documentation Skill
@@ -9,9 +9,11 @@ description: Template & generator library for technical docs — the skill agent
 
 Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
 
+**No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
+
 **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
 
-**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans, ADRs); `docs/memory/` is the agent's dated log and is likewise exempt. A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
+**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans); `docs/memory/` is the agent's dated log and is likewise exempt, and an ADR's **Decision Changelog** section is the one sanctioned dated-history section inside an active doc (the ADR body itself stays current-truth-only). A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
 
 ---
 
@@ -34,6 +36,8 @@ User request
     │
     ├─ "Record architecture decision" ─▶ ADR Template
     │
+    ├─ "Document a procedure/setup" ───▶ Operations Procedure Template
+    │
     ├─ "Create/update root README" ────▶ Project Root README Template
     │
     ├─ "Create/update plan" ───────────▶ Plan Template
@@ -66,7 +70,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ### How to derive the frontmatter
 
-A feature doc's launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required).
+A feature doc's launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
 
 **1. `owns:`** (the path scope)
 
@@ -119,6 +123,6 @@ For docs that don't match templates:
 
 | File | Use For |
 | --- | --- |
-| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, protected files, ADR, project root README templates |
+| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, protected files, ADR, project root README templates |
 | `references/style-guide.md` | Writing rules, formatting conventions |
 | `references/examples.md` | Good vs bad documentation examples |

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

@@ -105,7 +105,7 @@ Replaced change-tracking merge with version-based conflict resolution.
   - Purpose: Single-pass merge with change detection
   - Returns: `{ merged, changes }`
 
-### Modified
+### Changed
 
 - `useDataSync()` in `src/hooks/useDataSync.js`
   - Changed: Now compares versions before merge

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

@@ -222,7 +222,7 @@ Use for structured info:
 
 ## Tense & History
 
-**Active docs describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans, ADRs). (`docs/memory/` is the agent's own dated log and is likewise exempt from this rule.)
+**Active docs describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans). Two sanctioned exceptions: `docs/memory/` is the agent's own dated log, and an ADR's **Decision Changelog** section carries that decision's dated revision history (the rest of the ADR body stays current-truth-only).
 
 Strip this language from active docs:
 
@@ -257,6 +257,8 @@ Rules:
 #### Detail (H4 - sparingly)
 ```
 
+**Headings are retrieval keys.** Search and agents retrieve sections out of context, and a bare `## State` reads identically across every feature doc. In long docs, qualify generic headings with the feature name — `## State — invoice-pdf`, `### Merge rules — data sync` — so a section stands alone when retrieved. Short docs whose H1 disambiguates can keep bare headings.
+
 ### Standard Layout
 
 ```markdown