@nurix/etna 0.19.33 → 0.19.34

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

@@ -0,0 +1,129 @@
+---
+name: documentation
+description: "Use when creating or substantively editing ANY markdown doc — invoke BEFORE writing. Templates + style authority for technical docs: LLDs, ADs, plans, changelogs, READMEs, runbooks. Owns the tense rule: truth docs state the present; history only in dated records. Baselining is the maintenance agent."
+---
+
+# Technical Documentation Skill
+
+**This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
+
+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 stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
+
+---
+
+## Present tense, always
+
+**A document states what is — never how it got there, and never how far along it is.** Write as if the current design had always been the plan. This is the most-violated rule in the skill, so it sits at the top; it applies to every document written or edited through this skill, whatever the template.
+
+| ❌ Strip this | ✅ Write this |
+| --- | --- |
+| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — fix the references; state only the present design |
+| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
+| "was X, now Y", "the old worker", "Phase 2 softened this", "v1 → v2" | The current fact, with no predecessor named |
+
+The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
+
+The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch.
+
+---
+
+## The Two Natures
+
+Every document is exactly one of two things. Decide which before writing a word — every rule in this skill derives from the split.
+
+| | **Truth document** | **Record** |
+| --- | --- | --- |
+| States | Absolutes — how the system is, **now** | What happened — a dated account of activity |
+| Named by | Topic: `auth.md`, `AD-003-persistence.md` | Date: `YYYY-MM-DD-slug.md` (or append position) |
+| On change | Body rewritten in place the moment reality changes | Never edited — frozen at completion or append-only |
+| Read to | Act correctly today | Trace provenance, diagnose, audit |
+| Lives in | `docs/features/`, `docs/architecture/`, `docs/operations/`, `docs/tests/`, READMEs | `docs/history/` (plans, changelog, brainstorms, research, migrations), `docs/research/`, `docs/memory/` |
+
+The two guarantees are complementary and both break on mixing: a reader holding a **truth document** must never need history to interpret it; a reader holding a **record** must be able to trust it was never rewritten. So the natures never share a document body.
+
+- **Truth documents never narrate history** — the § Present tense, always rule above, applied to this nature. When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
+- **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
+- **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and `docs/structure.md` ends with the maintenance agent's **Health Log** (tooling-stamped audit rows, the structural cousin of `last-reviewed:`). In both, the body stays current-truth-only; the tail carries the dates. No other truth document carries dated history.
+- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
+
+**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.
+
+---
+
+## Routing
+
+| Request | Route |
+| --- | --- |
+| Baseline / reconcile docs | `maintenance` agent (baseline mode) — it calls this skill per template |
+| Document feature/module (LLD) | [`templates/feature.md`](templates/feature.md) |
+| Document data flow / state / Redux | [`templates/feature.md`](templates/feature.md) — they are sections of the feature doc |
+| Create/update changelog entry | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record — one per unit of work; carries the refinement fields, frozen inside its commit, distilled by the `retro` agent) |
+| Create/update plan | [`templates/plan.md`](templates/plan.md) (record) |
+| Record/revise architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md) — one AD per subject; revisions update it in place |
+| System at a glance | [`templates/system-overview.md`](templates/system-overview.md) |
+| Domain model | [`templates/domain-model.md`](templates/domain-model.md) |
+| Glossary | [`templates/glossary.md`](templates/glossary.md) |
+| Non-goals | [`templates/non-goals.md`](templates/non-goals.md) |
+| Catalog the API surface | [`templates/api-reference.md`](templates/api-reference.md) |
+| Document env vars / config | [`templates/environment-registry.md`](templates/environment-registry.md) |
+| Security / threat model | [`templates/security-overview.md`](templates/security-overview.md) |
+| Testing strategy | [`templates/testing-strategy.md`](templates/testing-strategy.md) |
+| Recurring procedure/setup | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
+| One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |
+| Add to protected files | [`templates/protected-files.md`](templates/protected-files.md) |
+| Create/update root README | [`templates/root-readme.md`](templates/root-readme.md) |
+| Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
+| Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
+| Update existing doc | § Editing an existing doc (below) |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | Not these templates — every-load prose stays lean: assertion—reason bullets, tables over diagrams, no ASCII; the present-tense rule still applies |
+| **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
+
+---
+
+## Editing an existing doc
+
+"Substantive" = anything beyond typo, link, or formatting fixes. On a substantive edit:
+
+1. **Determine the nature first.** A frozen record (a `Status: Complete`/`Abandoned` plan, a changelog entry, an executed runbook) is never edited — write a new dated record that links back.
+2. **Preserve structure, not violations.** Keep the doc's existing section shape, but every section touched sheds history narration, progress markers, and stale tripwires on the way through (§ Present tense, always).
+3. **Stamp and re-derive.** A substantive feature-doc update bumps `last-reviewed:`; if the documented scope moved, update `owns:` ([`references/frontmatter.md`](references/frontmatter.md)).
+
+---
+
+## Naming & Lifecycle
+
+| Document | Nature | Name | Lifecycle |
+| --- | --- | --- | --- |
+| Feature (LLD) | Truth | `kebab-case.md` | Living; `status:` `draft` → `active` → `deprecated` |
+| Architecture Decision | Truth | `AD-NNN-kebab-case.md` | Living; `Proposed` → `Accepted` → `Deprecated`; revisions rewrite the body + append to its Decision Changelog |
+| Steering docs (overview, domain model, glossary, non-goals, security, testing strategy) | Truth | fixed names | Living |
+| API reference / environment registry | Truth | fixed names | Living |
+| Operations procedure | Truth | `kebab-case.md` | Living |
+| Protected files | Truth | `protected-files.md` | Living |
+| Plan | Record | `YYYY-MM-DD-kebab-case.md` | Freezes at `Complete` / `Abandoned` |
+| Changelog entry | Record | `YYYY-MM-DD-kebab-case.md` | Frozen; master index append-only |
+| Migration runbook | Record | `YYYY-MM-DD-kebab-case.md` | Freezes once executed, outcome stamped |
+| Research | Record | `history/research/{topic}/` | Frozen snapshot |
+| Memory | Record | `{agent-name}.md` | Append-only dated ledger |
+
+---
+
+## Frontmatter Derivation
+
+A feature doc carries ownership frontmatter — `owns:` (required), `module:` (optional), `keywords:` (required), `status:` (required), optional `last-reviewed:`. Deriving it from code and keeping it accurate is [`references/frontmatter.md`](references/frontmatter.md) — every feature-doc create or update, and the `maintenance` agent's baseline pass, route there.
+
+---
+
+## Resources
+
+| File | Use For |
+| --- | --- |
+| `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
+| `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
+| `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
+| `references/examples.md` | Good vs bad documentation examples |
+| `scripts/doc-lint.mjs` | Mechanical checks over written docs (tense narration, dates, stubs, redirects) — run over changed docs before finishing |

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

@@ -0,0 +1,279 @@
+# Documentation Examples
+
+Good vs bad examples showing the key differences.
+
+---
+
+## Example 1: Function Documentation
+
+### ❌ Bad: Full Implementation
+
+```markdown
+### mergeData
+
+function mergeData(server, local, changes) { const result = {}; const serverMap = new Map(server.map((i) => [i.id, i])); // ... 30 more lines return result; }
+```
+
+**Problems:** Will become obsolete, focuses on HOW not WHAT.
+
+### ✅ Good: Contract Only
+
+```markdown
+### `mergeData(serverData, localData, changes)`
+
+**Goal:** Merge server data with local changes
+
+**Input:**
+
+- `serverData` (array) - Fresh from API
+- `localData` (array) - Current state
+- `changes` (object) - `{ added, updated, removed }`
+
+**Output:** `{ merged: array, conflicts: array }`
+
+**Merge Rules:**
+
+- Server wins for conflicts
+- Local additions preserved
+- Local removals marked as intent
+```
+
+---
+
+## Example 2: State Documentation
+
+### ❌ Bad: State Everywhere
+
+```markdown
+## Component State
+
+const [items, setItems] = useState([]);
+
+## Hook State
+
+{ data: items, isLoading: loading, error: null }
+
+## Redux State
+
+{ items: [], loading: false, error: null }
+```
+
+**Problems:** Documents transient state, repeats shapes.
+
+### ✅ Good: Persistence Points Only
+
+```markdown
+## 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 items = pgTable('items', {
+  id: text('id').primaryKey(),
+  data: jsonb('data'),
+});
+```
+
+---
+
+## Example 3: Changelog
+
+### ❌ Bad: Vague
+
+```markdown
+# 2025-01-05 - Updates
+
+## Changes
+
+- Updated editor
+- Fixed bugs
+- Improved performance
+
+## Files
+
+- Various files in src/
+```
+
+### ✅ Good: Function-Level Detail
+
+```markdown
+# 2025-01-05 - Version-Based Merge
+
+## Summary
+
+Replaced change-tracking merge with version-based conflict resolution.
+
+## Changes
+
+### Added
+
+- `mergeAndDerive(server, local, versionsMatch, type)` in `src/utils/merge.js`
+  - Purpose: Single-pass merge with change detection
+  - Returns: `{ merged, changes }`
+
+### Changed
+
+- `useDataSync()` in `src/hooks/useDataSync.js`
+  - Changed: Now compares versions before merge
+
+### Removed
+
+- `deriveChanges()` from `src/utils/derive.js`
+  - Replaced by: Logic in `mergeAndDerive()`
+
+## Breaking Changes
+
+⚠️ **Merge behavior changed**
+
+- Old: Local changes always preserved
+- New: Local preserved only if versions match
+
+## Files Changed
+
+- `src/hooks/useDataSync.js`
+- `src/utils/merge.js`
+- `src/utils/derive.js` (deleted)
+```
+
+---
+
+## Example 4: Data Flow
+
+### ❌ Bad: Prose Description
+
+```markdown
+When the page loads, the useAppInit hook calls the syncData function. This function first fetches data from the server using the API. Then it gets the local data from Redux. After that, it compares versions...
+```
+
+### ✅ Good: Diagram + Key Points
+
+```markdown
+## Data Flow
+
+┌─────────────────────────────────────────┐
+│               DATA SYNC                 │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌──────┐     ┌──────┐     ┌──────┐    │
+│   │Server│────▶│Merge │────▶│Redux │    │
+│   │ API  │     │      │     │Store │    │
+│   └──────┘     └──────┘     └──────┘    │
+│        │                                │
+│        ▼                                │
+│   Version Check                         │
+│                                         │
+└─────────────────────────────────────────┘
+
+**Trigger:** `useAppInit()` on page load
+
+**Version Rule:** Match → local wins, Mismatch → server wins
+```
+
+---
+
+## Example 5: Architecture Decision revision
+
+### ❌ Bad: Supersession chain
+
+```
+docs/architecture/decisions/
+├── AD-002-auth-keycloak.md        (status: Superseded)
+├── AD-006-auth-better-auth.md     (status: Superseded, "supersedes AD-002")
+└── AD-011-auth-better-auth-v2.md  (status: Accepted, "supersedes AD-006")
+```
+
+**Problems:** Three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
+
+### ✅ Good: One subject, updated in place
+
+```
+docs/architecture/decisions/
+└── AD-002-auth.md                 (status: Accepted, last-updated bumped)
+```
+
+```markdown
+## Decision
+
+We use Better Auth with one-shot credential issuance…   ← current truth, no journey
+
+…
+
+## Decision Changelog
+
+- 2026-05-02 — Moved issuance to one-shot tokens because refresh-token theft
+  surfaced in review. Implemented by [plan](…). (Previously: long-lived refresh tokens.)
+- 2026-03-18 — Replaced Keycloak with Better Auth because self-hosting cost
+  outweighed SSO needs. Implemented by [plan](…). (Previously: Keycloak.)
+- 2026-01-10 — Initial decision accepted. Implemented by [plan](…).
+```
+
+**Why it works:** The body answers "how does auth work and why" without archaeology; the tail preserves every reversal with its trigger; the rejected alternatives stay findable in the one file a reader actually opens.
+
+---
+
+## Example 6: Stripping history from a truth doc
+
+The move agents fumble: deleting narration is only half the job — the story must land in a record.
+
+### ❌ Bad: The journey narrated in place
+
+```markdown
+## Export Pipeline
+
+The exporter was extracted from the legacy `reports` worker (2026-06-02) and
+now lives in `src/export/`. Phases 0–2 of the rewrite are complete; streaming
+output is not yet implemented. Treat any reference to `reports/export.js` as
+stale — it was superseded by `src/export/run.js`.
+```
+
+### ✅ Good: Present-tense truth doc + a dated record carrying the story
+
+The feature doc states only what is:
+
+```markdown
+## Export Pipeline
+
+`src/export/run.js` renders every export format from one job queue. Output is
+buffered per job (streaming is out of scope — see `docs/history/backlog.md`).
+```
+
+And the change-story goes to `docs/history/changelog/2026-06-02-export-extraction.md`:
+
+```markdown
+# 2026-06-02 — Export pipeline extracted
+
+## Summary
+
+Extracted export logic from the `reports` worker into `src/export/`.
+
+## Changes
+
+### Removed
+
+- `reports/export.js` — replaced by `src/export/run.js`; all callers repointed.
+```
+
+**Why it works:** the truth doc needs no archaeology to act on; the dates, the predecessor, and the supersession live in a frozen record; the unbuilt part is a backlog pointer, not a "not yet" hedge; and no stale-reference tripwire survives because the references themselves were fixed.
+
+---
+
+## Quick Comparison
+
+| Aspect     | Bad                  | Good                        |
+| ---------- | -------------------- | --------------------------- |
+| Code       | Full implementations | Signatures + contracts      |
+| State      | Every occurrence     | Persistence points only     |
+| Flows      | Prose paragraphs     | ASCII diagrams              |
+| Changelogs | "Updated X"          | Function names + migrations |
+| Decisions  | New doc per revision | One AD per subject, updated in place |
+| History    | Narrated in the doc  | Present-tense doc + dated record |
+| Length     | 100+ lines           | 20-40 lines                 |

package/data/harnesses/delivery/skills/documentation/references/frontmatter.md

@@ -0,0 +1,44 @@
+# Frontmatter Derivation — feature-doc ownership
+
+Load when: creating a feature doc, updating one whose documented scope moved, or running a baseline/reconcile pass over many docs.
+
+When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
+
+## When to run
+
+- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
+- **New feature doc** — when creating a doc via the [Feature template](../templates/feature.md), project its `owns:` globs
+- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
+
+## How to derive the frontmatter
+
+A feature doc's ownership 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)
+
+Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
+
+| Doc references                       | Glob                      |
+| ------------------------------------ | ------------------------- |
+| Multiple files under one directory   | `src/feature/**`          |
+| Specific files in a shared directory | List each file explicitly |
+| A single entry-point file            | The exact file path       |
+
+Glob each pattern against the codebase. At `status: active`, drop any that match nothing; at `status: draft`, projected globs may match nothing yet — confirm them against real code when the doc flips to `active`.
+
+**2. `module:`**
+
+The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
+
+**3. `keywords:` & `status:`**
+
+`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
+
+A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
+
+## Rules
+
+- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
+- Use glob patterns for directories, explicit paths for individual files. At `active`, never list paths that don't exist in the codebase; a `draft`'s projected paths are confirmed at `active`.
+- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
+- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.