@nurix/etna 0.18.16 → 0.18.18

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

@@ -4,7 +4,7 @@ Templates for all documentation needs.
 
 ---
 
-## 1. docs/README.md (Documentation Root)
+## docs/README.md (Documentation Root)
 
 Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
@@ -72,7 +72,7 @@ See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
 
 ---
 
-## 2. docs/structure.md (Authority Map)
+## docs/structure.md (Authority Map)
 
 Use for: defining which folder owns which topic and how docs are maintained.
 
@@ -131,13 +131,13 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 
 ---
 
-## 3. Code-Path Ownership
+## Code-Path Ownership
 
 **Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See **Frontmatter Derivation** in `SKILL.md` for turning code into `owns:` globs.
 
 ---
 
-## 4. Scaffold Files (create if missing)
+## Scaffold Files (create if missing)
 
 These standard files must exist after every baseline. Create them with these scaffolds if the repo doesn't already have them.
 
@@ -261,10 +261,12 @@ Memory file initialized during documentation baseline.
 
 ---
 
-## 5. Feature Documentation — the LLD (docs/features/{feature}.md)
+## Feature Documentation — the LLD (docs/features/{feature}.md)
 
 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.
 
+**Required vs optional.** Four things are required in every feature doc: the frontmatter, **Goal**, **Background**, and **Files** — plus **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
@@ -273,6 +275,7 @@ owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs t
 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)
 ---
 ```
 
@@ -410,10 +413,12 @@ Resolved Open Questions can be summarized into Background; unresolved ones stay
 
 ---
 
-## 6. Changelog
+## Changelog
 
 Use for: recording code changes with function-level detail.
 
+Change categories follow the Keep a Changelog vocabulary — **Added / Changed / Deprecated / Removed / Fixed / Security** — the same six the master `CHANGELOG.md` scaffold instructs. Include only the categories that apply; all six share the same bullet shape (function/file, then detail lines).
+
 ```
 # YYYY-MM-DD - [Title]
 
@@ -428,7 +433,7 @@ Brief description of what changed and why.
   - Purpose: What it does
   - Used by: Where it's called
 
-### Modified
+### Changed
 - `existingFunction()` in `path/to/file.js`
   - Changed: What's different
   - Reason: Why it changed
@@ -438,6 +443,13 @@ Brief description of what changed and why.
 - `oldFunction()` from `path/to/file.js`
   - Replaced by: `newFunction()`
 
+### Fixed
+- `buggyFunction()` in `path/to/file.js`
+  - Bug: What was wrong, when it manifested
+  - Fix: What changed
+
+(Deprecated / Security follow the same shape.)
+
 ## Breaking Changes
 
 ⚠️ **[Change description]**
@@ -451,6 +463,11 @@ Brief description of what changed and why.
 - [ ] Step 1
 - [ ] Step 2
 
+## Verified
+
+- What was exercised end-to-end and the observed result — real runs, real fixtures, measured timings
+- A future agent diagnosing a regression starts from this evidence
+
 ## Files Changed
 
 - `src/path/file1.js` - Core changes
@@ -459,7 +476,7 @@ Brief description of what changed and why.
 
 ---
 
-## 7. Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
+## Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
 
 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.
 
@@ -526,10 +543,49 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 ---
 
-## 8. Protected Files
+## Operations Procedure (docs/operations/{procedure}.md)
+
+Use for: any doc in `docs/operations/` — setup, development, deployment, maintenance procedures. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative.
+
+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
+```
+
+---
+
+## Protected Files
 
 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
 
@@ -551,29 +607,22 @@ path/to/another/file.js
 | Category 1 | Specific impact |
 | Category 2 | Specific impact |
 
-## Critical Logic
+## Why Protected
 
 ### Category 1: [Name]
 
-**Purpose:** What these files do
-
-**Key Functions:**
-
-| Function   | Input | Output | Purpose        |
-|------------|-------|--------|----------------|
-| `func1()`  | Type  | Type   | What it does   |
-| `func2()`  | Type  | Type   | What it does   |
-
-**Critical Behavior:**
-- Important point 1
+**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
 ```
 
 ---
 
-## 9. Architecture Decision Record (ADR)
+## Architecture Decision Record (ADR)
 
-Use for: capturing a single, point-in-time architectural decision with its context, alternatives considered, and consequences. Lives in `docs/architecture/adr/` — co-located with the architecture it decides. An ADR is **immutable** once shipped: it records the decision as made, not the deployed-design source of truth (the living prose in `docs/architecture/`). When the design later changes, update `docs/architecture/` and write a new superseding ADR; never rewrite a shipped ADR.
+Use for: capturing a single architectural decision with its context, alternatives considered, and consequences. Lives in `docs/architecture/adr/` — co-located with the architecture it decides. An ADR is the **source of truth for its decision**: the body always states the current truth. When the decision is revisited, update the ADR in place — rewrite the affected sections to what is now true, bump `last-updated`, and record the revision in the **Decision Changelog**. Readers get the current decision from the body; the journey lives only in the changelog section.
 
 ### When to write an ADR
 
@@ -591,9 +640,9 @@ Don't write an ADR for:
 
 ### Lifecycle
 
-`Proposed` → `Accepted` → `Deprecated` → `Superseded by ADR-NNN`
+`Proposed` → `Accepted` → `Deprecated`
 
-ADRs are **immutable after acceptance**. If the decision changes, write a new ADR that supersedes it. Update only the old ADR's `status` frontmatter field — never its body.
+An ADR stays `Accepted` for as long as its question is live — revisions update it in place. Set `Deprecated` only when the decision's question itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
 
 ### Naming
 
@@ -601,18 +650,18 @@ ADRs are **immutable after acceptance**. If the decision changes, write a new AD
 
 ### Structure
 
-Three sections are required: **Decision**, **Context**, **Consequences**. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
+Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the ADR has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
 
 ### Template
 
 ```markdown
 ---
 title: "ADR-NNN: Short title in sentence case"
-status: Accepted # Proposed | Accepted | Deprecated | Superseded by ADR-NNN
-date: YYYY-MM-DD
+status: Accepted # Proposed | Accepted | Deprecated
+created: YYYY-MM-DD
+last-updated: YYYY-MM-DD # bump on every revision
 decision-owner: Name
 reviewers: [] # optional
-supersedes: # optional, e.g., ADR-005
 tags: [adr]
 ---
 
@@ -659,13 +708,7 @@ tags: [adr]
 
 ## Architecture in Detail
 
-[Diagrams, code shape, layer responsibilities. Include when the decision implies non-trivial structure that readers need to understand alongside the *why*.]
-
-## Implementation Plan
-
-| Phase | Scope | Duration |
-| ----- | ----- | -------- |
-| 1     | …     | …        |
+[Diagrams, code shape, layer responsibilities. Include when the decision implies non-trivial structure that readers need to understand alongside the *why*. Execution belongs in a plan doc (`docs/history/plans/`) — link to it, don't embed an implementation plan here.]
 
 ## Open Questions
 
@@ -678,6 +721,13 @@ tags: [adr]
 ## References
 
 - [External link or cross-reference]
+
+## Decision Changelog
+
+<!-- Append-only, newest first. One entry per revision: what changed in the decision, the trigger, and the previous choice. Added on the first revision; the initial acceptance is the first entry. -->
+
+- YYYY-MM-DD — [What changed] because [trigger]. (Previously: [old choice].)
+- YYYY-MM-DD — Initial decision accepted.
 ```
 
 ### Rules
@@ -686,14 +736,15 @@ tags: [adr]
 - Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
 - No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything.
 - Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body.
-- When superseding, set the old ADR's `status: "Superseded by ADR-NNN"` and the new ADR's `supersedes: ADR-OLD`.
-- The body is frozen at `Accepted`. Corrections to facts that were wrong at the time get a new ADR; typos and formatting fixes are fine.
+- **Revisions update the body in place.** Rewrite the affected sections to the current truth, bump `last-updated`, and append a Decision Changelog entry naming the old choice and the trigger. Never leave the superseded decision narrated in the body — the changelog carries the journey.
+- The **Decision Changelog** is the one sanctioned dated-history section in an active doc: append-only, newest first. Typo and formatting fixes don't get entries.
+- Execution detail lives in a plan doc, not the ADR — link, don't embed.
 
 ---
 
-## 10. Project Root README
+## Project Root README
 
-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 §1). The two coexist; don't merge them.
+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
 

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

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

package/data/harnesses/mobile/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "mobile",
   "name": "mobile",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "11aacc0c5291"
+  "digest": "bc67c99bb1c5"
 }

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

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

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

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

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

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