@nurix/etna 0.19.20 → 0.19.22

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

@@ -0,0 +1,149 @@
+# Feature Documentation — the LLD (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.
+
+**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.
+
+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.
+
+```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
+status: active                                   # required — active | draft | deprecated
+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)
+---
+```
+
+> 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 |
+|--------|------|----------------------|
+
+## Conventions to Follow
+
+(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.
+
+## Current Behavior
+
+(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.
+
+## Ownership Conflicts
+
+(From lld-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
+
+| Conflicting doc | Overlapping path(s) | Resolution |
+|-----------------|---------------------|------------|
+
+## Architecture
+
+[ASCII diagram. Fill once implementation lands. See style-guide.md for box-drawing patterns.]
+
+## Key Functions
+
+### `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
+
+### `hookName(config)`
+**Goal:** What it provides
+**Returns:** `{ data, loading, error }`
+**Triggers:** On mount, on change, manual
+
+## 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
+```
+
+### Section evolution
+
+Sections fill in across the feature's lifecycle. No template swap — they accumulate in place.
+
+| 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) |
+
+Resolved Open Questions can be summarized into Background; unresolved ones stay visible.

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

@@ -0,0 +1,11 @@
+# Glossary (docs/architecture/glossary.md)
+
+Truth document. Use for: the project's vocabulary — one name per concept, one line per name. Alphabetical. When the code uses a different name than the docs, record it in **In code** so readers can bridge; one concept never gets two doc names.
+
+```
+# Glossary
+
+| Term | Meaning | In code |
+| ---- | ------- | ------- |
+| {Term} | {one-line definition} | `{identifier}` |
+```

package/data/harnesses/etna/skills/documentation/templates/memory-main.md

@@ -0,0 +1,25 @@
+# Scaffold: docs/memory/main.md
+
+Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/memory/main.md`.
+
+```
+---
+type: project-memory
+owner: main-agent
+description: Project-wide patterns and conventions confirmed in this codebase. Project facts only — user-centric facts go in ~/.claude/.
+---
+
+# Main Agent — Project Memory
+
+Append entries below, oldest at bottom. Format:
+
+## YYYY-MM-DD — {topic}
+
+{1-3 line fact, with file paths or references where relevant}
+
+---
+
+## {today} — Baseline
+
+Memory file initialized during documentation baseline (structure v{harness-version} — read from `.claude/harness.json` / `docs/structure.md` frontmatter; never hardcode a literal version).
+```

package/data/harnesses/etna/skills/documentation/templates/migration-runbook.md

@@ -0,0 +1,34 @@
+# Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
+
+Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).
+
+Required: **Goal**, **Steps**, **Verification**, and — after execution — the **Outcome** stamp. Optional: Preconditions, Rollback.
+
+```
+# Migration: {Title}
+
+**Goal:** What this migration accomplishes and why it runs now, one or two lines.
+**Executes against:** {environment / database / system}
+
+## Preconditions
+
+- Backups taken, feature flags set, access confirmed — exact checks
+
+## Steps
+
+1. One action per step, exact command in a code block
+2. Note expected output where it disambiguates success from failure
+
+## Verification
+
+- The observable end state that confirms success — exact check commands
+
+## Rollback
+
+- How to undo, and the point of no return
+
+## Outcome
+
+<!-- Stamped once, immediately after execution; the file freezes with it. -->
+**Executed:** YYYY-MM-DD — {result: clean | issues encountered + how resolved | aborted + why}
+```

package/data/harnesses/etna/skills/documentation/templates/non-goals.md

@@ -0,0 +1,11 @@
+# Non-Goals (docs/architecture/non-goals.md)
+
+Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
+
+```
+# Non-Goals
+
+Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
+
+- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
+```

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

@@ -0,0 +1,36 @@
+# 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.
+
+A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
+
+Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
+
+If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.
+
+```
+# {Procedure Name}
+
+**Goal:** What this procedure accomplishes, one line.
+
+## Preconditions
+
+- Access, tools, or state required before starting — exact versions, env vars, credentials location
+
+## Steps
+
+1. One action per step, exact command in a code block
+2. Note expected output where it disambiguates success from failure
+
+## Verification
+
+- The observable end state that confirms it worked — exact check commands, not "it should work now"
+
+## Troubleshooting
+
+- Symptom → cause → fix (append entries as failures are root-caused)
+
+## Rollback
+
+- How to undo, and when undo stops being possible
+```

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

@@ -0,0 +1,64 @@
+# Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
+
+Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`, flip to `Status: In Progress` when work starts, and freeze at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
+
+The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
+
+```
+# {Feature Name}
+
+**Status:** Draft | In Progress | Complete | Abandoned
+**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
+**Started:** YYYY-MM-DD
+**Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
+
+## Background
+
+Why this work is happening *now*. Link to the spec for *what* we're building; this section is the motivation and the trigger. One paragraph.
+
+## Proposed Changes
+
+### New Files
+
+- `src/path/new-file.js` — purpose
+
+### Modified Files
+
+- `src/path/existing.js` — what changes and why
+
+### New Entities / State
+
+- `entities.foo` — new Redux slice / DB table / persisted shape
+- Persisted state addition: `state.bar.baz` (default `null` for existing users on rehydrate)
+
+### API Changes
+
+- `POST /api/foo` — new route, request `{...}`, response `{status, data}`
+- `PUT /api/bar` — request shape changes; see Migration
+
+### Cross-Module Contracts Affected
+
+- List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
+- "None" is a valid answer and means the `boundary` check will pass cleanly
+
+## Implementation Steps
+
+1. Concrete, ordered, testable
+2. Each step ends with something verifiable
+3. ...
+
+## Done Criteria
+
+- [ ] Implementation complete and verified
+- [ ] Affected docs updated (use the injected ownership index to find them)
+- [ ] Changelog entry created in `docs/history/changelog/`
+- [ ] Plan marked `Status: Complete`, **Completed:** date filled
+
+## Open Questions
+
+- Question — who decides, by when
+
+## Risks
+
+- Risk — likelihood / impact / mitigation
+```

package/data/harnesses/etna/skills/documentation/templates/protected-files.md

@@ -0,0 +1,37 @@
+# Protected Files
+
+Truth document. Use for: documenting critical files that need approval before modification.
+
+This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
+
+```
+# Protected Files
+
+Critical files requiring approval before modification.
+
+## File List
+
+# Category 1 - Description
+path/to/critical/file1.js
+path/to/critical/file2.js
+
+# Category 2 - Description
+path/to/another/file.js
+
+## Risk Summary
+
+| Category   | Risk if Broken  |
+|------------|-----------------|
+| Category 1 | Specific impact |
+| Category 2 | Specific impact |
+
+## Why Protected
+
+### Category 1: [Name]
+
+**Purpose:** What these files do, one or two lines
+**Owning doc:** [docs/features/{feature}.md] — canonical reference for how this code works
+**Invariants:**
+- The behavior that must not break, stated as a constraint (not a function tour)
+- Important point 2
+```

package/data/harnesses/etna/skills/documentation/templates/root-readme.md

@@ -0,0 +1,104 @@
+# Project Root README
+
+Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
+
+### Strategy
+
+The root README answers, in order:
+
+1. **What is this?** — one to two sentences, no marketing claims
+2. **What do I get if I install it?** — capability families
+3. **What's it built on?** — terse stack list with versions
+4. **How do I run it?** — the three or four scripts that matter
+5. **How is it laid out?** — directory tree, one-liner per significant folder
+6. **How do I extend it?** — numbered contribution checklist
+7. **What state is it in?** — pre-publish, beta, stable, internal
+
+Skip any section that doesn't apply. Don't pad to fill the template.
+
+### Writing rules
+
+- **Sentence-case headings.** "Getting started", not "Getting Started".
+- **Concrete over abstract.** Real versions, real paths, real commands. No "leverages cutting-edge…".
+- **The tagline answers "what is this?"** — not "why is it great?". Two sentences max.
+- **Tables for enumeration** (routes, commands, endpoints). **Bullets for families and categories.**
+- **Directory tree as a code block**, not a nested markdown list.
+- **Numbered checklist** for "how to add a thing" — readers should be able to follow it top-to-bottom without re-reading.
+- **Point to `docs/` for depth.** The root README links into deep docs; it doesn't host them.
+- **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and write commands accordingly. Don't hardcode `npm` if the repo uses pnpm.
+
+### Template
+
+```markdown
+# {package-name}
+
+{One- to two-sentence positioning. What it is and what scope it covers. No superlatives, no value claims.}
+
+## What's in the box
+
+- **{Family 1}** — {what's in it; a few specific items, comma-listed.}
+- **{Family 2}** — {what's in it.}
+- **{Family 3}** — {what's in it.}
+
+The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries
+
+## Stack
+
+- {Framework} {version} · {Language} {version}
+- {Build tool} {version}
+- {Other load-bearing deps}
+
+## Getting started
+
+\`\`\`bash
+{pm} install
+{pm} run dev        # what it does (port, URL)
+{pm} run build      # what it does
+{pm} run preview    # what it does (omit if not applicable)
+\`\`\`
+
+{Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}
+
+## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"
+
+{Brief description of the dev/runtime surface.}
+
+| {Thing}              | {What it shows / does} |
+| -------------------- | ---------------------- |
+| `{route or command}` | {description}          |
+
+## Layout
+
+\`\`\`
+src/
+├── {entry-file}        # {purpose}
+├── {folder}/           # {purpose}
+│   └── ...
+└── {folder}/           # {purpose}
+\`\`\`
+
+## Adding a {primary unit}
+
+1. {Drop the source under the right family/folder.}
+2. {Re-export from the public surface.}
+3. {Wire into the playground / example app / test harness so reviewers can see it render.}
+4. {Document any divergence from upstream in `docs/{...}`.}
+
+## Styling ← optional; replace with whichever cross-cutting concern matters most
+
+{Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}
+
+## Status
+
+{Pre-publish, beta, stable, internal-only. State the stability tier per surface — which APIs are contracts and which are experimental — so readers know what can be relied on.}
+
+## License
+
+{License name — scope. e.g., "UNLICENSED — internal use only", "MIT".}
+```
+
+### Baseline scaffolding behavior
+
+The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
+
+**Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.

package/data/harnesses/etna/skills/documentation/templates/security-overview.md

@@ -0,0 +1,27 @@
+# Security Overview (docs/architecture/security.md)
+
+Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
+
+Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
+
+```
+# Security Overview
+
+## Assets
+
+- {What's worth protecting — data classes, credentials, tenant isolation}
+
+## Trust boundaries
+
+- {Boundary} — {what crosses it, and what checks the crossing} 
+
+## Controls
+
+| Control | Protects against | Implemented in |
+| ------- | ---------------- | -------------- |
+| {control} | {threat} | `{file/module}` |
+
+## Accepted risks
+
+- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
+```

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

@@ -0,0 +1,65 @@
+# 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) | feature `owns:` frontmatter | the generated ownership index |
+| System overview | `docs/architecture/` | system-design.md |
+| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
+| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
+| API surface | `docs/architecture/` | api.md |
+| Security | `docs/architecture/` | security.md |
+| Feature behavior | `docs/features/` | {key files} |
+| Setup & development | `docs/operations/` | {key files} |
+| Environment / config surface | `docs/operations/` | environment.md |
+| Testing strategy | `docs/tests/` | strategy.md |
+| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
+| Change records | `docs/history/changelog/` | Individual entries |
+| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
+| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
+| Brainstorm design records | `docs/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 feature'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.
+- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
+- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
+- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
+- `docs/history/changelog/`: Records. Append-only.
+- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
+- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
+- `docs/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/etna/skills/documentation/templates/system-overview.md

@@ -0,0 +1,32 @@
+# System Overview (docs/architecture/system-design.md)
+
+Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
+
+Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
+
+```
+# System Overview
+
+## What this is
+
+{Two or three sentences: what the system does, for whom, in what environment it runs.}
+
+## Subsystem map
+
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Frontend │────▶│   API    │────▶│    DB    │
+└──────────┘     └──────────┘     └──────────┘
+{One box per subsystem; label the arrows with the contract that crosses them.}
+
+- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
+
+## Key flows
+
+{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
+
+## Where the truth lives
+
+| Area | Canonical doc |
+| ---- | ------------- |
+| {area} | [{doc}](path) |
+```

package/data/harnesses/etna/skills/documentation/templates/testing-strategy.md

@@ -0,0 +1,29 @@
+# Testing Strategy (docs/tests/strategy.md)
+
+Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
+
+Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
+
+```
+# Testing Strategy
+
+## Levels
+
+| Layer | Runner | Lives in | Covers |
+| ----- | ------ | -------- | ------ |
+| Unit / integration | {runner} | `tests/` | {what} |
+| E2E | {runner} | `e2e/` | {what} |
+
+## Running
+
+- `{pm} test` — the whole unit suite (CI gate)
+- `{pm} run test:e2e` — {when to run}
+
+## Deliberately untested
+
+- {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
+
+## Adding a test
+
+1. {Where the file goes, what it's named, where fixtures live}
+```

package/data/harnesses/etna/skills/workflow-mapper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-mapper
-description: Discover and document all major workflows in a codebase by tracing call chains from user action to database/external system. Produces mermaid sequence diagrams and markdown documentation. Use when the user asks to map workflows, trace flows, document sequences, understand how features work end-to-end, or generate architecture diagrams. Triggers on "map workflows", "trace workflows", "workflow diagram", "sequence diagram", "how does X work end-to-end", "document flows", "codebase workflows", "how does this feature work", "trace the request flow", "show me the call chain", "what happens when a user does X", "end-to-end flow".
+description: "Discover and document a codebase's major workflows by tracing call chains from user action to database or external system — produces mermaid sequence diagrams and markdown. Triggers on 'map workflows', 'trace flows', 'sequence diagram', or 'how does X work end-to-end'."
 ---
 
 # Workflow Mapper Skill

package/data/harnesses/hr/.prettierignore

@@ -10,3 +10,9 @@ yarn.lock
 
 # Harness-managed agent/skill definitions (installed under .claude/)
 .claude
+
+# Source catalogs — authored markdown; prettier collapses template/example blocks
+skills
+rules
+agents
+harness