@nurix/etna 0.18.16 → 0.18.18

package/data/harnesses/mobile/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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.18.16",
+    "version": "0.18.18",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {