@nurix/etna 0.19.33 → 0.19.35

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.

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

@@ -0,0 +1,340 @@
+# Documentation Style Guide
+
+Writing rules for clear, maintainable documentation.
+
+---
+
+## Function Documentation
+
+### Signature Format
+
+```markdown
+### `functionName(param1, param2, options)`
+
+**Goal:** One-line purpose
+
+**Input:**
+
+- `param1` (type) - Description
+- `param2` (type, optional) - Description
+
+**Output:** `{ field1, field2 }`
+
+**Side Effects:** State updates, API calls, etc.
+```
+
+### Parameter Rules
+
+- Name + type + one-line purpose
+- Mark optional params with `(type, optional)`
+- Nest object properties:
+  ```markdown
+  - `options` (object) - Configuration
+    - `options.retry` (boolean) - Enable retries
+    - `options.timeout` (number) - Timeout in ms
+  ```
+
+### Return Values
+
+Always specify:
+
+- Type: `Array<Object>`, `boolean`, `{ merged, changes }`
+- Shape for objects/arrays
+- Meaning: "True if sync successful"
+
+---
+
+## State Documentation
+
+### When to Document State
+
+✅ Do:
+
+- Redux persistence (localStorage, IndexedDB)
+- Database schemas
+- API request/response shapes
+
+❌ Don't:
+
+- Component-level state
+- Derived/computed state
+- Temporary UI state
+
+### Format
+
+````markdown
+**Frontend (at persistence):**
+
+```json
+{
+  "activeField": "value"
+  // "deprecated": null  // UNUSED: dead key; kept so old persisted state rehydrates
+}
+```
+
+**Storage:** localStorage key `state_key`
+
+**Backend:**
+
+```ts
+export const table = pgTable('table', {
+  id: text('id').primaryKey(),
+  data: jsonb('data'),
+  // old: text('old'),  // UNUSED: dead column; nothing reads it
+});
+```
+````
+
+### Mark Unused Keys
+
+Always comment deprecated/unused fields. The annotation states why the field is dead _now_ — never where it went, what replaced it, or when it will be removed (no "Remove in v3", no "Migrated to newField"; that is history narration, § The Two Natures below):
+
+```json
+{
+  "active": [],
+  // "legacy": {}  // UNUSED: dead key; kept for rehydrate compatibility
+}
+```
+
+---
+
+## ASCII Diagrams
+
+### When to Use
+
+- Data flows
+- System architecture
+- Component interactions
+- Process flows
+
+**Docs only.** Diagrams belong in documents read on demand (feature docs, ADs, operations). Instruction files — `CLAUDE.md`, rules, agent definitions, `SKILL.md` prose — never carry them: they load on every turn or every invocation, and a table or a sentence carries the same information at a fraction of the tokens.
+
+### Pattern
+
+```
+┌─────────────────────────────────────────┐
+│              TITLE                       │
+├─────────────────────────────────────────┤
+│                                          │
+│   ┌──────┐     ┌──────┐     ┌──────┐   │
+│   │  A   │────▶│  B   │────▶│  C   │   │
+│   └──────┘     └──────┘     └──────┘   │
+│        │                          │     │
+│        ▼                          ▼     │
+│    Detail                     Detail    │
+│                                          │
+└─────────────────────────────────────────┘
+```
+
+### Characters
+
+- Boxes: `┌─┐│└┘├┤┬┴┼`
+- Arrows: `───▶` `◀───` `│▼` `│▲`
+- Width: ~70 chars max
+
+### UI Wireframes
+
+For screen layouts (not data flows), use these conventions:
+
+```
+**Route:** `path/:id`
+**Tab:** Tab Name
+
+┌────────────────────────────────────┐
+│ Title   [i]3                [Button]│
+│ [i]Label   [Tag1][Tag2][+Add]       │
+└────────────────────────────────────┘
+```
+
+- `[text]` = clickable button/badge
+- `[i]` = icon (followed by label or count)
+- `v` / `^` = expand/collapse indicator
+- Show each UI state (collapsed/expanded) as separate diagrams
+- Include Route/Tab context above wireframe
+
+---
+
+## Code Examples
+
+### Rules
+
+- Under 15 lines
+- Show contracts, not implementations
+- Use pseudocode for algorithms
+
+✅ Good:
+
+```javascript
+// Critical: Balanced brace matching
+function extract(json) {
+  // Track brace depth
+  // Ignore braces inside strings
+  // Return complete objects only
+}
+```
+
+❌ Bad: Full 50-line implementation
+
+(Worked example: [`examples.md`](examples.md) Example 1.)
+
+---
+
+## Writing Style
+
+### Voice
+
+Use imperative/active:
+
+- ✅ "Fetches data from server"
+- ✅ "Returns array of objects"
+- ❌ "This function is used to fetch"
+- ❌ "An array is returned"
+
+### When Prose Adds Value
+
+Prose is valuable for context that contracts can't capture:
+
+| Use Prose For | Example |
+| --- | --- |
+| Section intros | "When the editor mounts, `useAppInit` is called with the `appId` from URL." |
+| Non-obvious behavior | "The hook always fetches fresh data. There is no caching or version checking." |
+| Design rationale | "Why parallel fetches? Each entity type is independent, reducing load time." |
+| Edge cases | "If created then deleted before save, it's removed from `added[]` without adding to `removed[]`." |
+| Limitations, stated as facts | "`useAppInit` is standalone — nothing in the mount path calls it." |
+| Usage context | "Used to show 'Unsaved' badge, warn before navigation, enable save buttons." |
+
+### When to Avoid Prose
+
+- Describing WHAT code does (use signatures instead)
+- Step-by-step flows (use diagrams instead)
+- Structured comparisons (use tables instead)
+
+### Conciseness
+
+One line when possible:
+
+- ✅ "Merge server data with local changes using version-based conflict resolution"
+- ❌ "This function takes the data from the server and also takes the local data..."
+
+### Tables
+
+Use for structured info:
+
+```markdown
+| Parameter | Type   | Description    |
+| --------- | ------ | -------------- |
+| `data`    | object | Fresh from API |
+| `local`   | object | Current state  |
+```
+
+---
+
+## The Two Natures — Tense & History
+
+Every document is a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — see `SKILL.md` § The Two Natures. The tense rules follow directly:
+
+**Truth documents 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 journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Three sanctioned exceptions: `docs/memory/` is the agent's own dated ledger; an AD's **Decision Changelog** tail carries that decision's dated revision history; and `docs/structure.md`'s **Health Log** tail carries the maintenance agent's tooling-stamped audit rows. In both tail bridges the body stays current-truth-only — head is truth, tail is provenance.
+
+**Records are never edited to match the present.** A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
+
+Strip this language from truth documents:
+
+| ❌ Historical narration (belongs in a record) | ✅ Present-tense fact (belongs in the truth doc) |
+| --- | --- |
+| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
+| "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
+| "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
+| "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
+| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record; the doc describes what exists |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — delete or repoint the stale references; state only the present design |
+| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
+
+Rules:
+
+- **No dates and no progress narration in truth documents.** Nothing about _when_ something shipped, was verified, folded, or was removed — and no completion markers either: no "phases 0–4 are complete", no per-item `✅ shipped` / `⏳ pending`. Progress tracking is a **record's** job (the plan, the backlog); a truth document describes what exists, as if it had always been so.
+- **No stale-reference tripwires.** Never write "X is gone — treat references to X as stale"; that is a redirect doc compressed into one sentence. Delete or repoint every stale reference instead (same rule as the **No redirect docs** rule in `SKILL.md` § The Two Natures) and state only the present fact.
+- **No version or phase framing.** A bare `v1`/`v2` as a label, "Phase 1/2", "the old X", "supersedes the earlier" — there is one design; describe it without its predecessors. (A version naming an external present-tense fact stays: a schema literal like `design-tokens/v2`, a dependency pin like `@0.14.0`.)
+- **Temporal hedges are progress markers in prose.** "currently", "not yet", "still", "for now" smuggle a ⏳ into a truth document — state the fact without the hedge ("the hook is standalone; nothing in the mount path calls it") and let the backlog record carry the intention.
+- **A published artifact's own version surface is external fact.** Release notes and upgrade guides for a shipped package may use version framing (`v1 → v2`) — that is the artifact's public contract, not the doc narrating its own past. They live beside the artifact or under `docs/operations/`, never in `docs/features/` or `docs/architecture/`.
+- **Cite the AD for the _why_, never the _when_.** `Provenance: AD-002` is good (it points to the decision rationale). "Decided in AD-002 and shipped 2026-06-13" is not.
+- **Routing/index docs point only to truth documents as a topic's authority.** A row whose "read first" target for a topic is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned: that indexes records, it doesn't route a topic.)
+- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the truth document simply becomes correct in present tense.** Never leave the diff narrated in place.
+- **A decision that moves is an edit, not a new document.** Rewrite the AD's affected sections to the new truth and append the revision to its Decision Changelog — never mint a parallel doc and never leave the old choice narrated in the body.
+
+Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Example 6.
+
+---
+
+## Mechanics
+
+- Inline-code every identifier, filename, command, and config key.
+- Bullet rules take the form "**bold assertion** — explanation."
+
+---
+
+## Structure
+
+### Headers
+
+```markdown
+# Document Title (H1 - once)
+
+## Major Section (H2)
+
+### Subsection (H3)
+
+#### 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
+# [Title]
+
+**Goal:** One-line purpose
+
+## Architecture
+
+[Diagram + explanation]
+
+## Key Functions
+
+[Signatures and contracts]
+
+## State
+
+[Persistence shapes]
+
+## Files
+
+[Source file list]
+```
+
+### File References
+
+Always end with:
+
+```markdown
+## Files
+
+- `src/path/main.js` - Core logic
+- `src/path/hooks.js` - React hooks
+```
+
+---
+
+## Summary
+
+| Aspect     | Rule                            |
+| ---------- | ------------------------------- |
+| Functions  | Always include signatures       |
+| Parameters | Type + purpose                  |
+| Returns    | Type + shape                    |
+| State      | Persistence points only         |
+| Diagrams   | ASCII for all flows — docs only, never instruction files |
+| Code       | Under 15 lines, contracts only  |
+| Voice      | Imperative/active               |
+| Mechanics  | Inline-code identifiers; bold-assertion bullets |
+| Length     | Concise, one line when possible |