@nurix/etna 0.19.20 → 0.19.22

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

@@ -0,0 +1,70 @@
+# docs/README.md (Documentation Root)
+
+Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
+
+```
+# {Project Name} Documentation
+
+Technical documentation for {project description}.
+
+> For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.
+
+---
+
+## Quick Links
+
+| Document                          | Description                          |
+| --------------------------------- | ------------------------------------ |
+| [Structure](structure.md)         | Documentation entry point and rules  |
+| [Setup](operations/setup.md)      | Installation and configuration guide |
+
+---
+
+## Architecture
+
+System design, steering docs, and standing decisions — the truth layer.
+
+- [system-design.md](architecture/system-design.md) - System overview: subsystems and key flows
+- [domain-model.md](architecture/domain-model.md) - Entities, relationships, state ownership
+- [glossary.md](architecture/glossary.md) - Project vocabulary
+- [non-goals.md](architecture/non-goals.md) - What this system deliberately does not do
+- [decisions/](architecture/decisions/Readme.md) - Architecture Decisions (ADs)
+{list other architecture docs — api.md, security.md — when present}
+
+---
+
+## Features
+
+Living reference docs for implemented features (how things currently work).
+
+- [feature-name.md](features/feature-name.md) - Feature description
+{list all feature docs}
+
+---
+
+## Operations
+
+How to run, develop, and deploy.
+
+- [setup.md](operations/setup.md) - Installation and configuration guide
+{list all operations docs — environment.md when present}
+
+---
+
+## History
+
+The records — everything dated, frozen, or append-only.
+
+- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
+- [changelog/](history/changelog/) - Individual changelog entries
+- [plans/](history/plans/) - Implementation plans (frozen at completion)
+- [migrations/](history/migrations/) - One-shot migration runbooks (frozen once executed)
+- [research/](history/research/) - Deep-research artifacts (one folder per topic)
+- [backlog.md](history/backlog.md) - Tracked work items and technical debt
+
+---
+
+## Contributing
+
+See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
+```

package/data/harnesses/code/skills/documentation/templates/domain-model.md

@@ -0,0 +1,30 @@
+# Domain Model (docs/architecture/domain-model.md)
+
+Truth document. Use for: the entities the system is about — what they are, how they relate, and who owns their state. The vocabulary here must match the glossary and the code; when they disagree, fix the disagreement, don't document around it.
+
+Required: **Entities**, **Relationships**. Optional: Lifecycle states, Invariants.
+
+```
+# Domain Model
+
+## Entities
+
+| Entity | What it is | State lives in |
+| ------ | ---------- | -------------- |
+| {Entity} | {one line} | {table / slice / service} |
+
+## Relationships
+
+- {EntityA} 1—N {EntityB} — {the meaning of the link}
+- {EntityB} N—N {EntityC} via {join} — {meaning}
+
+## Lifecycle states
+
+{Only for entities with real state machines.}
+
+- **{Entity}**: draft → active → archived — {what moves it between states}
+
+## Invariants
+
+- {A relationship or state rule that must always hold, stated as a constraint}
+```

package/data/harnesses/code/skills/documentation/templates/environment-registry.md

@@ -0,0 +1,15 @@
+# Environment Registry (docs/operations/environment.md)
+
+Truth document. Use for: the config surface — every variable the code reads, in one table. `.env.example` mirrors this doc's variable list.
+
+**Placeholders only, never real values.** A real-looking password, account ID, or personal profile name in a doc is a leak, and one developer's local setup written as the canonical value is a trap for everyone else. Values in this doc are `{placeholder}` descriptions.
+
+```
+# Environment Registry
+
+Every variable the code reads. `.env.example` mirrors this list.
+
+| Variable | Purpose | Required | Where set | Secret |
+| -------- | ------- | -------- | --------- | ------ |
+| `DATABASE_URL` | {one line} | yes / default: `{value}` | local `.env` / CI / prod | yes |
+```

package/data/harnesses/code/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/code/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/code/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/code/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/code/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/code/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/code/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/code/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/code/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/code/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}.
+```