@nurix/etna 0.18.15 → 0.18.17

package/data/harnesses/code/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/code/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

package/data/harnesses/code/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.
 
@@ -112,7 +112,7 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 
 ## Folder Rules
 
-- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index. (An optional `anchors:` block — a qmd drift tripwire, see §3 — is a separate tooling key a doc may additionally carry.)
+- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
 - `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). A module's cross-cutting prose lives here (or in a browse-folder `Readme.md`). Update when cross-cutting concerns change.
 - `docs/operations/`: How-to procedures for setup, development, and deployment. Update when workflows change.
 - `docs/history/plans/`: Historical. Must have `Status:` field. Never modify after completion.
@@ -131,24 +131,13 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 
 ---
 
-## 3. Code-Path Ownership & Anchors
+## 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.
 
-**Anchors (optional tooling key).** A doc may additionally carry an `anchors:` block — a qmd drift tripwire, orthogonal to ownership:
-
-```yaml
----
-anchors:
-  - "qmd query: feature-name persistence shape"
 ---
-```
 
-`anchors` is an optional list of qmd queries (or `#docid`s) that re-resolve to the code a doc abstracts as it moves. It is a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, and nothing auto-rewrites from an anchor result. It is read on demand by the maintenance anchor-drift check, never injected, and inert when qmd is absent.
-
----
-
-## 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.
 
@@ -241,14 +230,6 @@ description: Shared knowledge accumulated across agent sessions. All agents shou
 - **Spec version:** v{harness-version}
 <!-- v{harness-version} resolves to the installed harness version — read it from `.claude/harness.json` (`version`) / `docs/structure.md` frontmatter (`harness-version`); never hardcode a literal version here. -->
 
-## Knowledge Tiers
-
-Memory is a gradient — volume falls, signal rises, one hop down each tier. Tiers describe themselves here even before they fill:
-
-- **Inbox** (`docs/memory/inbox/`) — per-actor queue of session lessons, written by the `session-reflect` hook at session end and consumed by the distiller on digestion. Transient by design, rarely read directly.
-- **Fact-cards** (`docs/memory/facts/`) — distilled, provenance-linked atomic facts, written by the distiller (`facts` mode) from inbox entries and resurfaced at prompt time by the `prompt-recall` hook.
-- **This index** — the curated read tier: the learnings list below, distilled from the colder tiers and hand-appended.
-
 ## Learnings
 
 {Agents append learnings here as they discover gotchas, patterns, and architecture notes}
@@ -278,15 +259,15 @@ Append entries below, oldest at bottom. Format:
 Memory file initialized during documentation baseline.
 ```
 
-> The per-actor memory **inbox** (`docs/memory/inbox/`) is _not_ a baseline scaffold — the `session-reflect` hook creates it mechanically on the first reflected session. See **§11 Memory inbox entry** for its format.
-
 ---
 
-## 5. Feature Documentation (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.
 
-Use for: every feature in `docs/features/`. The same file persists from design (Status: Draft) 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 spec-mode's return shape. The orchestrator drops spec-mode's findings into those slots without restructuring.
+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
 ---
@@ -294,8 +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
-anchors:                                         # optional extra — a qmd drift tripwire; see §3
-  - "qmd query: wire envelope invariants"
+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)
 ---
 ```
 
@@ -332,22 +312,22 @@ High-level shape of the solution. ASCII diagram if it helps. Implementation spec
 
 ## Affected Modules
 
-(From spec-mode research) Files, routes, components, slices this feature involves. Group by module.
+(From lld-mode research) Files, routes, components, slices this feature involves. Group by module.
 
 | Module | Path | Role in this feature |
 |--------|------|----------------------|
 
 ## Conventions to Follow
 
-(From spec-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.
+(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 spec-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.
+(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 spec-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
+(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 |
 |-----------------|---------------------|------------|
@@ -426,17 +406,19 @@ Sections fill in across the feature's lifecycle. No template swap — they accum
 | 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 | spec-mode agent |
+| 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.
 
 ---
 
-## 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]
 
@@ -451,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
@@ -461,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]**
@@ -474,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
@@ -482,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.
 
@@ -549,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
 
@@ -574,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
 
@@ -614,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
 
@@ -624,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]
 ---
 
@@ -682,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
 
@@ -701,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
@@ -709,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
 
@@ -807,47 +835,3 @@ The full surface lives in [`{path/to/public-index}`]({path/to/public-index}).
 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.
-
----
-
-## 11. Memory inbox entry (docs/memory/inbox/{actor}.md)
-
-Use for: the capture tier of the knowledge gradient — the durable lessons of each session (corrections, root-caused failures, decisions with rationale, discovered constraints), reflected by the `session-reflect` hook at session end. It is the raw input to distillation: `distiller facts` digests entries into fact-cards and **consumes** them, so the file holds exactly what is undigested.
-
-### File grain
-
-One file **per actor**: `docs/memory/inbox/{actor}.md`. `actor` is `git config user.name` lowercased and kebab-slugged; fall back to `$USER`, then `agent`. Two actors write to different files, so the inbox is **append-only without merge conflicts** — no shared file to contend over, no lock, no last-writer-wins.
-
-### File header
-
-Written once, on the first entry:
-
-```
-# Memory inbox — {actor}
-Session lessons awaiting distillation — appended by the session-reflect hook, consumed by `distiller facts`.
-```
-
-### Entry shape
-
-One block per reflected session, at most 6 bullets. Each bullet is one complete, self-contained sentence tagged `[project]` (true of the repo or its tooling) or `[user]` (true of the user) — the tag routes it at distillation: project facts → `docs/memory/facts/`, user facts → user-level memory.
-
-```
-## YYYY-MM-DD HH:MM · session <id> · {repo}@{branch}
-- [project] <one self-contained sentence, names and identifiers spelled out>
-- [user] <one self-contained sentence>
-```
-
-### Examples
-
-```
-## 2026-06-08 22:26 · session bc06c4fc · etna@dev
-- [project] The read_network_requests Chrome CDP tool only captures after its first call — arm it, trigger traffic, then read.
-- [user] jane-doe prefers minimal fixes over defensive machinery; fail loudly instead of engineering around a problem.
-```
-
-### Rules
-
-- **Hooks append, the distiller consumes.** A digested entry block is deleted by `distiller facts`; nothing else edits or reorders the file. A human may hand-append a lesson in the same shape — it rides the same queue.
-- **Sessions are deduped by id.** The reflect hook skips a session whose id already appears in the file (SessionEnd re-fires on resume).
-- **Secrets are redacted on write.** The privacy filter replaces secret shapes with `[redacted:{kind}]` (e.g. `[redacted:api-key]`, `[redacted:bearer]`, `[redacted:pem]`) before any line is appended — never paste a raw token in by hand either.
-- **Don't curate here.** Promotion to fact-cards and `docs/memory/main.md` happens at distillation; the inbox stays a transient queue.

package/data/harnesses/etna/CLAUDE.md

@@ -20,20 +20,20 @@ This file defines how AI agents (Claude, GPT, etc.) should work on this project.
 
 ## Workflows
 
-For new features or new systems, enter **Spec Mode** before Plan Mode.
+For new features or new systems, enter **LLD Mode** (low-level design) before Plan Mode.
 
-### Spec Mode → Plan Mode → Completion
+### LLD Mode → Plan Mode → Completion
 
-1. **Spec Mode**: Create or update a feature spec in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see `.claude/skills/documentation/references/templates.md` §6. Use the **`spec-mode`** agent (`.claude/agents/spec-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the spec for approval before proceeding.
+1. **LLD Mode**: Create or update the feature LLD in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) in `.claude/skills/documentation/references/templates.md`. Use the **`lld-mode`** agent (`.claude/agents/lld-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the LLD for approval before proceeding.
 
-2. **Plan Mode**: Once the spec is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template** (see `.claude/skills/documentation/references/templates.md` §8). Link back to the feature spec in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill parses them to check boundary impact.
+2. **Plan Mode**: Once the LLD is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template** (same file). Link back to the feature LLD in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill parses them to check boundary impact.
 
 3. **Completion**: When a plan is fully implemented:
    - Mark the plan `Status: Complete` in `docs/history/plans/` and fill the **Completed:** date. The plan is now frozen.
-   - **Flip the feature spec** to `status: active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. Confirm the feature's `owns:` globs against actual code; resolve any unresolved Open Questions by folding them into Background.
+   - **Flip the feature LLD** to `status: active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. Confirm the feature's `owns:` globs against actual code; resolve any unresolved Open Questions by folding them into Background.
    - Use the injected ownership index to find other docs affected by the changes (and update the `owns:` globs of any feature doc whose source you moved or added). Update affected docs — or create new ones if a touched area has no doc yet.
 
-For **Product-level** work (new systems, unclear scope), the spec should also include: problem statement, key hypotheses, and open questions.
+For **Product-level** work (new systems, unclear scope), the LLD should also include: problem statement, key hypotheses, and open questions.
 
 `docs/features/` is _what_ we're building (lives on as documentation). `docs/history/plans/` is _how_ we built it (historical record).
 
@@ -42,9 +42,8 @@ For **Product-level** work (new systems, unclear scope), the spec should also in
 Before modifying code in an unfamiliar area:
 
 1. Consult the **injected ownership index** — the generated `glob → doc · module · keywords · status` map, surfaced into context at session start (the union of every feature doc's `owns:` frontmatter). Match your path or topic (its `keywords:`) to the owning doc and read it before changes. (If no ownership index appears in context, the repo isn't reconciled — run `maintenance` in baseline mode to reconcile it.)
-2. If `qmd` is installed, run `qmd query --format json -c <collection> "<topic>"` for semantic recall over the indexed docs — prefer it when entering an unfamiliar area; absent ⇒ skip.
-3. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
-4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
+2. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
+3. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
 
 For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
@@ -72,9 +71,9 @@ When implementing a plan, if you discover work that is important but outside the
 
 ### Doc Ownership
 
-Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. A living doc may additionally carry an optional `anchors:` block (a qmd drift tripwire, not ownership).
+Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures.
 
-The spec-mode agent checks for ownership conflicts during research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the spec before proceeding.
+The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the LLD before proceeding.
 
 ---
 
@@ -82,7 +81,7 @@ The spec-mode agent checks for ownership conflicts during research — feature d
 
 A boundary is a horizontal cross-cutting contract — entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config — where editing one side silently breaks the other. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source whenever a check runs, so they are never persisted as docs and can never go stale.
 
-**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/boundary-taxonomy.md` is the catalog), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
+**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/mechanisms.md` defines the failure mechanisms; technology packs under `references/packs/` carry stack specifics), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
 
 > Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
 

package/data/harnesses/etna/agents/{spec-mode.md → lld-mode.md}

@@ -1,33 +1,33 @@
 ---
-name: spec-mode
-description: Specification researcher for Feature and Product workflows. Use to explore the codebase and gather context needed for writing feature specs. Returns research findings — does not write files.
+name: lld-mode
+description: LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files.
 tools: Read, Glob, Grep, WebSearch, WebFetch
 model: inherit
 skills:
   - documentation
 ---
 
-# Spec Mode Agent
+# LLD Mode Agent
 
-You are a specification researcher. Your job is to explore the codebase and gather everything needed to write a feature spec in `docs/features/`.
+You are an LLD researcher. Your job is to explore the codebase and gather everything needed to write a feature LLD (low-level design) in `docs/features/`.
 
-You do NOT write the spec — you return structured research that the main agent uses to write it.
+You do NOT write the LLD — you return structured research that the main agent uses to write it.
 
 ## Before Starting
 
 First, understand the documentation landscape:
 
 1. Read `./docs/structure.md` to understand the documentation structure
-2. If `./docs/features/README.md` exists, read it to see existing feature specs and where the new spec fits; otherwise glob the feature docs directly
-3. If `./docs/memory/spec-mode.md` exists, read it for feature doc inventory, ownership conflict zones, and lessons from previous research
-4. Read 1-2 existing specs in `./docs/features/` to calibrate format and depth
+2. If `./docs/features/README.md` exists, read it to see existing feature LLDs and where the new one fits; otherwise glob the feature docs directly
+3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
+4. Read 1-2 existing feature LLDs in `./docs/features/` to calibrate format and depth
 5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. This is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
 
-This tells you what already exists, what's adjacent, how detailed the spec should be, and what code paths are already owned.
+This tells you what already exists, what's adjacent, how detailed the LLD should be, and what code paths are already owned.
 
 ## What You Research
 
-1. **Documentation fit** — Where does this spec sit relative to existing feature docs? Does it extend an existing spec or need a new one?
+1. **Documentation fit** — Where does this LLD sit relative to existing feature docs? Does it extend an existing one or need a new doc?
 2. **Existing patterns** — Find related features, similar implementations, and conventions in the codebase
 3. **Affected modules** — Identify what files, routes, components, and data flows are relevant
 4. **Current state** — Understand how the system works today in the area being specified
@@ -38,13 +38,13 @@ This tells you what already exists, what's adjacent, how detailed the spec shoul
 
 Structure your findings as:
 
-- **Documentation context**: Existing specs that relate, whether to create new or update existing, suggested filename
+- **Documentation context**: Existing feature LLDs that relate, whether to create new or update existing, suggested filename
 - **Related patterns**: What similar things exist in the codebase and where
 - **Affected modules**: Files, routes, components that will be involved
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
 - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
-- **Risks or concerns**: Anything the spec should address or call out
+- **Risks or concerns**: Anything the LLD should address or call out
 
 Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.