npm - @nurix/etna - Versions diffs - 0.19.35 → 0.19.36 - Mend

@nurix/etna 0.19.35 → 0.19.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/data/harness-index.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "22a721cdaeb5",
+    "fingerprint": "088c311840d2",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Agent Instructions
-This file defines how AI coding agents — any vendor, any runtime — should work on this project. Rules are runtime-neutral: a rule that depends on a capability (sub-agent dispatch, browser tools, context injection, slash commands) applies only if the runtime has it, and states its fallback. Rules marked **[override]** deliberately replace a default the runtime may have built in — in a conflict, the rule here wins.
+How AI coding agents — any vendor, any runtime — work on this project. Rules are runtime-neutral: a rule that depends on a capability (sub-agent dispatch, browser tools, context injection, slash commands) applies only if the runtime has it, and states its fallback. Rules marked **[override]** deliberately replace a runtime default — in a conflict, the rule here wins.
 ---
@@ -21,23 +21,22 @@ Invoke the `maintenance` agent whenever the docs look like they need it — not
 ## Workflows
-Three peer modes plus Verification and Completion — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here.
+Three peer modes, then a verification gate and a Completion step — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here.
 | Mode | Enter when | Implemented by | Exits to |
 | --- | --- | --- | --- |
 | **Brainstorming** | explicit ask (`/brainstorm start`); or offer a session — never auto-enter — when the user brings a large piece of work (name what makes it big) or an utterance contradicts a recorded pillar (name the principle) | `brainstorm` agent + skill | LLD, Plan, or close + harvest |
 | **LLD** (low-level design) | new feature work | `lld-mode` agent + `documentation` skill | Plan |
-| **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
+| **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Verification gate → Completion |
 > Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a bug fix, one button) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: in-progress sessions live under `docs/research/`, harvested ones under `docs/history/brainstorms/`, harvested doctrine under `docs/architecture/`. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
 **On Plan Completion:**
-1. **The verification gate passes first** — discharge every row of the plan's Test Obligations, driving the real surface before pinning tests (see Verification). A plan with outstanding obligations does not reach `Status: Complete`, whatever the code does.
+1. **The verification gate passes first** — user-triggered: when implementation completes, report it and offer the gate; never run it unbidden. It requires the plan's Test Obligations ledger to exist (proof the plan gates ran) and discharges every row, driving the real surface before pinning tests — `.claude/rules/verification.md`. A plan with outstanding obligations stays open, whatever the code does.
 2. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
 3. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual code.
-4. The `boundary` and `test-plan` skills must already have gated this plan before its first implementation step — see Ownership, Boundaries, Verification & Documentation.
-5. Derive/update the behavioral checklist at `docs/tests/{feature}.md` via the `documentation` skill (a truth document — present-tense, referencing the LLD's promises, restating no intent), and record the gate's results in the changelog entry.
+4. Derive/update the behavioral checklist at `docs/tests/{feature}.md` via the `documentation` skill (a truth document — present-tense, referencing the LLD's promises, restating no intent), and record the gate's results in the changelog entry.
 **On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, then a uselessness test; conclusions disperse by scope (architecture docs, decision records, backlog), the record moves from `docs/research/{topic}-brainstorm/` to `docs/history/brainstorms/{topic}/`, and the user decides whether the moved folder is deleted or committed.
@@ -49,14 +48,14 @@ These four mechanisms work in tandem to keep the repo self-updating and to preve
 ### Ownership — route before editing
-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. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures.
+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. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and own no files; operations docs describe procedures.
 Before modifying code in an unfamiliar area:
 1. Consult the **injected ownership index** (`glob → doc · module · keywords · status`). Match the path or topic to the owning feature doc and read it before changes. (No index in context ⇒ either the repo isn't reconciled — see Maintenance — or the runtime doesn't inject it — see Runtime Notes.)
 2. If a `docs/memory/` file exists for the domain, read it for domain knowledge and failure modes.
-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.
+The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. Resolve them in the LLD before proceeding.
 ### Boundaries — check while changing
@@ -66,15 +65,15 @@ Boundaries are **diagnosed, not documented** — the `boundary` skill derives th
 ### Test obligations — specify before implementing
-**After `boundary` passes and its amendments are folded, invoke the `test-plan` skill** — same plan gate, ordered second. It derives the tests the plan owes from its Proposed Changes and the owning LLD, and writes a **Test Obligations** section into the plan (one row per promised behavior: layer · target file · oracle · fixtures). It writes no test files — the tests land at the verification gate, and the manifest is the ledger that gate discharges. This makes obligations survive dispatch to an executor that sees only the plan file, and lets a later doc-health pass prove the tests match the promises. On a boundary **BLOCK** it does not run — re-plan first. The three-moment split (gate → verification → Completion checklist), the layer rules, and the e2e altitude gate live in the skill.
+**After `boundary` passes and its amendments are folded, invoke the `test-plan` skill** — same plan gate, ordered second. It derives the tests the plan owes from its Proposed Changes and the owning LLD, and writes the **Test Obligations** ledger into the plan (one row per promised behavior: layer · target file · oracle · fixtures). It writes no test files — the ledger is what the verification gate discharges, and because it lives in the plan file it survives dispatch to an executor that sees only the plan. On a boundary **BLOCK** it does not run — re-plan first. Layer rules and the e2e altitude gate live in the skill.
 ### Verification — prove before completing
-**Deferring tests is what keeps the build loop fast, and the ledger is what makes deferring safe.** A plan-driven build writes no test files while the code is taking shape; the obligations accumulate in the plan and are discharged in one pass at the **verification gate** — triggered when the user says the work is ready to verify, and mandatory before a plan reaches `Status: Complete`. The gate, the two regimes, the mechanism ladder, and what earns a durable test are `.claude/rules/verification.md`.
+**Deferring tests is what keeps the build loop fast, and the ledger is what makes deferring safe.** A plan-driven build writes no new test files while the code is taking shape; obligations accumulate in the plan and are discharged in one pass at the **verification gate** — user-triggered, offered when implementation completes, mandatory before `Status: Complete`. The gate, the two regimes, the mid-loop rules, and what earns a durable test are `.claude/rules/verification.md`.
-- **Only a plan may defer.** A bug fix and any ad-hoc change ship their test immediately — deferral needs a ledger and a gate, and non-plan work has neither.
+- **Only a plan may defer.** A bug fix in shipped behavior and any ad-hoc change ship their test immediately — deferral needs a ledger and a gate, and non-plan work has neither.
 - **Drive the real surface before pinning tests.** Browser automation for web UI, the real CLI, HTTP against the running worker; the suite pins what must not regress afterward.
-- **The gate runs in the main session.** Verification is never delegated — see the Browser Automation guardrail and Runtime Notes.
+- **The gate's verdict is never delegated** — a sub-agent's summary is not verifiable ground truth (the Fan-out guardrail), and browser work is main-session-only where Runtime Notes say so.
 ### Documentation — close the loop
@@ -104,7 +103,7 @@ When recording a learning, ask: _is this true of this project, or true of this u
 ## Changelog
-A commit marks the user's behavioral verification of the work, and the working session is the last holder of the refinement context that produced it — asks, iterations, rejections, skill outcomes, discoveries. That context is captured in the changelog and distilled on demand. The `changelog` rule carries the trigger and the lifecycle; this is the policy:
+The working session is the last holder of the refinement context that produced a change — asks, iterations, rejections, skill outcomes, discoveries. The changelog captures it; the `retro` agent distills it on demand. A commit marks the user's acceptance of the work it carries — for plan work, behavioral verification is the gate's job, and a mid-plan commit is a checkpoint (the `verification` rule). The `changelog` rule carries the trigger and the lifecycle; this is the policy:
 - **Every non-mechanical commit is covered by an entry** at `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, staged inside the commit it describes — whatever tool or session performs the commit — plus a row in `docs/history/CHANGELOG.md`. Format, required fields, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; the failure fields (rejected attempts, overridden skill output) and verbatim taste quotes are required, not optional — the entry's value concentrates there.
 - **An entry may exist before its commit.** A plan reaching `Status: Complete` writes its entry as a **draft** immediately, while the context is fresh; the commit fills what the draft left open. **Immutability begins at commit, not creation** — a draft is mutable, a committed entry never is, and a correction is a new entry that links back. Doc-health passes skip the genre.
@@ -117,7 +116,7 @@ A commit marks the user's behavioral verification of the work, and the working s
 ## Out-of-Scope Discovery
-When a plan's implementation surfaces work that is important but outside the plan's scope:
+When a plan's implementation surfaces work that is important but outside the plan's scope and is not being done now (a pre-existing bug being fixed on the spot is the bug-fix regime — the `verification` rule — not a backlog item):
 - Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
 - Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
@@ -129,10 +128,10 @@ When a plan's implementation surfaces work that is important but outside the pla
 Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise; ✅ and ⚠️ items are standing policy:
-- ✅ **Verification — batched at a gate, not continuous.** A plan-driven build loop ships code without accompanying test files; the tests and the driven checks land together at the **verification gate**, which the user triggers and which is mandatory before a plan reaches `Status: Complete`. The gate, the mechanism ladder, and what earns a durable test are `.claude/rules/verification.md`; framework, test-tree placement, and shared fixtures stay `.claude/rules/testing.md` — the repo's existing runner and layout always win.
-  - **Only a plan defers**: a bug fix and any ad-hoc change ship their test immediately — a regression test that fails before the change and passes after. Deferral needs the Test Obligations ledger and the gate that discharges it, and non-plan work has neither.
+- ✅ **Verification — batched at a gate, not continuous.** A plan-driven build loop ships code without new test files; the tests and the driven checks land together at the **verification gate** — user-triggered, offered when implementation completes, mandatory before a plan reaches `Status: Complete`. The gate, the regimes, and the mechanism ladder are `.claude/rules/verification.md`; framework, test-tree placement, and shared fixtures are `.claude/rules/testing.md` — the repo's existing runner and layout always win.
+  - **Only a plan defers**: a bug fix in shipped behavior and any ad-hoc change ship their test immediately — a regression test that fails before the change and passes after.
   - **Drive before pinning**: prove the change in the real product first — browser automation for web UI, the real CLI, HTTP against the running worker — then pin as suite tests only the behaviors that must not regress.
-  - **Discipline**: run the affected part of the suite at the gate and report results honestly. When an LLD or plan intentionally changes behavior, updating the affected tests to the new contract is part of the change — the ban is on weakening, skipping, or deleting a test to mask an unexplained failure.
+  - **Discipline**: run the affected part of the suite at the gate and report results honestly. Never weaken, skip, or delete a test to mask an unexplained failure — when a plan or LLD intentionally changes behavior, updating the affected tests to the new contract is part of the change.
   - **Throwaway checks are not tests**: temporary verification scripts go to scratch space and are deleted, never committed into the test tree.
 - ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies.
 - ❌ **Compatibility** – Never maintain backward compatibility unless specified.
@@ -140,7 +139,7 @@ Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise;
 - ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself.
 - ✅ **Browser Automation** – If the runtime provides browser automation, use it freely; no need to ask first. If it doesn't — or the executing agent can't hold the browser connection (see Runtime Notes) — return a browser-verification checklist (URLs, actions, expected outcomes) for the orchestrating session or the user to run.
 - ✅ **Fan-out is a tool, not a default** — the main session does the work and its own reasoning; a delegated result comes back as a summary, not verifiable ground truth. Delegate **only when** the work is large, independent, or repetitive enough that a self-contained hand-off (the sub-agent sees none of the conversation) costs less than the work — broad research, wide sweeps, audits — and run independent delegations in parallel. **Never delegate judgment by reflex**: a second opinion is for a high-stakes call or an explicit request. No dispatch mechanism ⇒ inline.
-- ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.
+- ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. Abandoning a plan whose code was committed first converts its undischarged Test Obligations into backlog items (the `verification` rule). If scope changes after completion, write a new dated plan that links back to the old one.
 - ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
 ---

package/data/harnesses/code/harness.json CHANGED Viewed

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "f909d2dbf258"
+  "digest": "500726b483fd"
 }

package/data/harnesses/code/rules/verification.md CHANGED Viewed

@@ -8,19 +8,31 @@
 | Regime | During the work | Proven |
 | --- | --- | --- |
-| **Plan-driven build** | No test files. Code only — the loop stays fast | At the verification gate, before `Status: Complete` |
-| **Bug fix** | The regression test ships with the fix | Immediately — it fails before the change, passes after |
+| **Plan-driven build** | No new test files. Code only — the loop stays fast | At the verification gate, before `Status: Complete` |
+| **Bug fix** — a defect in shipped behavior | The regression test ships with the fix | Immediately — it fails before the change, passes after |
 | **Ad-hoc / non-plan change** | The test ships with the change | Immediately, same discipline as a bug fix |
-- **A bug fix cannot defer, because its central property is only observable at fix time** — "fails before, passes after" is unprovable once the fix is already in the tree.
-- **Ad-hoc work cannot defer, because there is no ledger to defer into.** An obligation recorded nowhere is an obligation forgotten; the plan file is the only durable home, so work without a plan pays as it goes.
+- **A bug fix cannot defer, because "fails before, passes after" is provable afterward only by reverting to the pre-fix ref** — a cost nobody pays, so the property is captured at fix time or lost.
+- **Ad-hoc work cannot defer, because there is no ledger to defer into.** An obligation recorded nowhere is an obligation forgotten. A non-plan change that alters no promised behavior — a pure refactor, a rename — owes no test: the implementer applies § What earns a durable test directly.
+## During the loop
+Rules for the plan regime between the plan gate and the verification gate:
+- **No new test files** — obligations wait in the ledger.
+- **Existing tests broken by the plan's intended behavior change are updated to the new contract before any mid-plan commit** — the shared branch never carries a red suite, and an update is never a weakening (§ What earns a durable test).
+- **A defect in the plan's own in-flux code is the loop iterating** — no test, no ledger row; the behavior it belongs to is already in the ledger. **A pre-existing bug in shipped behavior is the bug-fix regime even mid-plan**: fix it with its regression test now — deferring it to the gate loses "fails before", the property the regime exists to capture — or, when not fixing it now, send it to the backlog via Out-of-Scope Discovery. Never fix silently.
+- **The ledger is amendable while the plan is open** — a boundary finding or a newly promised behavior appends a row; the gate discharges whatever the ledger holds at gate time.
+- **A mid-plan commit is a checkpoint, not a verification claim.** It may ship deliberately unverified code; the gate, not the commit, is the verification event for plan work.
 ## The gate
-**The gate is a discrete step, not a background habit** — it runs when the user says the work is ready to verify, or when a plan's implementation is complete. It is **mandatory before a plan reaches `Status: Complete`**: a plan with outstanding obligations is not complete, whatever the code does.
+**The gate is a discrete, user-triggered step.** When implementation is complete, report it and offer the gate — never run it unbidden, and never flip `Status: Complete` without it. A plan with outstanding obligations stays open, whatever the code does.
-- **The gate runs in the main session, never delegated.** A sub-agent cannot hold a browser connection (`CLAUDE.md` § Runtime Notes), so a delegated gate silently degrades from *driving the product* to *describing how someone else could*. Fan-out may prepare fixtures or draft test bodies; the driving and the verdict stay inline.
-- **The plan's Test Obligations table is the checklist.** Every row is discharged — satisfied, or restated with the reason it owes nothing after all. A row left unexamined blocks the gate.
+- **Precondition: the ledger exists.** A plan with no Test Obligations section is blocked at the gate — run the `test-plan` skill on it first. Without this check an empty ledger passes vacuously and the gap surfaces only after the file is frozen.
+- **Every row is discharged into exactly one outcome**: **satisfied** (the test exists and is green, or the driven check passed), **owes nothing** (with the reason — compiler-guarded, covered elsewhere), or **blocked** (the missing infrastructure named, the row converted to a backlog item so the debt outlives the frozen plan). A row left unexamined blocks the gate.
+- **The gate's verdict is never delegated.** A sub-agent's summary is not verifiable ground truth, and where browser work is main-session-only (the root `CLAUDE.md` § Runtime Notes), the driving is too. Fan-out may prepare fixtures or draft test bodies; the driving and the verdict stay inline.
+- **Abandonment does not erase debt.** Before `Status: Abandoned` freezes a plan whose code was committed, convert its undischarged rows into backlog items; uncommitted code owes nothing.
 - **Report what happened, including failures.** A gate that reports green while a suite is red is worse than no gate; state the failing test and its output.
 ## The mechanism ladder
@@ -31,9 +43,10 @@
 | --- | --- | --- |
 | 1 | **Drive the real surface** — browser automation for web UI, the actual CLI binary, HTTP against the running worker | The change works in the product, against real wiring |
 | 2 | **Pin the durable behaviors** as suite tests per [`testing.md`](testing.md) | The behavior survives the next change |
-| 3 | **Run the affected suite + the project's e2e smoke gate** | Nothing else broke |
+| 3 | **Run the affected suite**, plus the project's e2e smoke gate where one is wired | Nothing else broke |
-- **Browser automation is the default for a web surface, and needs no permission to use** — a rendered page driven through real interaction is the only oracle that catches wiring, styling, and state defects together. Where the runtime offers none, the gate emits a browser-verification checklist (URLs, actions, expected outcomes) for the user to run, and says so rather than claiming verification.
+- **Browser automation is the default for a web surface, and needs no permission to use** — a rendered page driven through real interaction is the only oracle that catches wiring, styling, and state defects together.
+- **Where the runtime offers no browser automation**, rung 1's verdict belongs to the user: emit a browser-verification checklist (URLs, actions, expected outcomes), the user runs it and reports, the result lands in the changelog entry — and `Status: Complete` waits for it.
 - **A driven check is evidence, not an artifact.** It proves the change works today; it leaves nothing behind. That is why rung 2 exists.
 ## What earns a durable test

package/data/harnesses/code/skills/documentation/SKILL.md CHANGED Viewed

@@ -78,7 +78,8 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
 | Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
 | Update existing doc | § Editing an existing doc (below) |
-| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | Not these templates — every-load prose stays lean: assertion—reason bullets, tables over diagrams, no ASCII; the present-tense rule still applies |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md) — not these templates; every-load prose stays lean, and the present-tense rule still applies |
+| Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/architecture/skills/playbook/`, chapters `00`–`10`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
 | **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
 ---
@@ -123,6 +124,7 @@ A feature doc carries ownership frontmatter — `owns:` (required), `module:` (o
 | --- | --- |
 | `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
 | `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
 | `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/code/skills/documentation/references/instruction-style.md ADDED Viewed

@@ -0,0 +1,49 @@
+# Instruction-File Style
+The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an agent definition, skill prose. Prose style only: frontmatter is metadata, not style. Docs-tree documents follow the skill's templates and [`style-guide.md`](style-guide.md) instead.
+## The test for every line
+An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and rules load on **every turn of every session** — the most expensive prose in a repo per word; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
+**Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
+## Coherence
+A rewrite is not only a trim — read the file as one artifact and fix what disagrees or is missing:
+- **Two statements of one fact agree, or become one.** A defaults block vs. the worked example beside it, a table row vs. a bullet — reconcile against the code the rule governs and keep one canonical statement; a silent disagreement is worse than either version alone, because each reader picks a different one.
+- **Every cross-reference resolves** — the cited `§`, sibling file, or command exists and still says what the citation claims. Section numbers are a public surface other files cite: append, never reshuffle.
+- **The body delivers what the scope line promises, and nothing it disclaims.** A topic named then left to guesswork is a hole; material the scope routes elsewhere is a leak.
+- **Report what you cannot fix.** A defect outside the file — a stale sibling, an unshipped copy — is named in the handback, never fixed by widening the edit.
+## Two genres, one style
+Policy files (`CLAUDE.md`, rules) are declarative — assertion bullets and tables, no second person. Agent and skill bodies are procedures — second person, numbered steps, one observable action per step. The genre sets the shape; everything below applies to both.
+## Routing
+- **Link, don't copy — one canonical source per topic.** `CLAUDE.md` is a **router, not a manual**: per workflow, when to enter, what to dispatch, where the output lands — mechanics live in the agent or skill file, which loads only when it runs.
+- **Cut generic engineering advice.** Agents already know how to code; keep only what is true of *this* stack and not derivable by looking at it.
+- **Keep load-bearing rules even when project-specific.** Genericizing is for reference material, not guardrails — deleting a hard rule removes a constraint the agent will otherwise violate.
+## Voice
+- **Assertion — reason, in one breath.** "**Never name a deployed-value file `.env`** — the dev server auto-loads a root `.env` as local vars, so a prod-valued `.env` silently becomes the local environment." The reason is the rule's armor: an agent that knows the failure mode won't "improve" the rule away; a bare imperative invites second-guessing.
+- **A reason appears once — at the rule it armors.** "One breath" caps a reason's length, not its multiplicity: the same rationale in the scope line, a section intro, and a bullet is the restatement trimming exists to remove. A convention whose only reason is consistency states that once, in the scope line.
+- **One example, carrying every point it can — never a second example of the same point.** An example calibrates a rule an agent would otherwise read loosely; a second one demonstrating the same rule is restatement in costume. Prefer one worked case rich enough for several rules to cite over a fresh citation per bullet.
+- **Grade the bindingness with words.** Bold **never / always / only / must** for hard constraints; "prefer", "default", "acceptable when" for defaults — and every escape hatch states its trigger and its price.
+- **Absolute present tense.** Describe the current design as if it had always been the plan — no "previously", no version narration, no stale-reference tripwires, no progress markers. When something moves or is removed, fix every reference and state only the present fact; the journey lives in git history and `docs/history/`. (Docs-tree tense rules: [`style-guide.md`](style-guide.md) § The Two Natures.)
+## Negative space
+- **Name the rejected alternative.** A package table carries a **Don't use** column because an agent that knows the popular alternative reaches for it unless the file closes the door by name.
+- **Pre-empt the workaround.** Where a failure predictably triggers improvisation, spell out the forbidden moves and the exact stop-and-report. The umbrella: **no silent fallback** — fail loudly rather than route around.
+## Material & mechanics
+- **Tables for enumerable facts, prose for judgment.** One row per item kills the urge to explain; anything that needs a *because* lives in prose around the table, never inside a cell.
+- **No ASCII diagrams.** A box-and-arrow diagram costs many tokens for what a sentence or a small table carries.
+- Inline-code every identifier, filename, command, and config key.
+- ❌ / ✅ only inside banned/blessed lists, not as general decoration.
+- `>` blockquotes set off interruptions — cross-pointers, callouts, agent guards — not the main line.

package/data/harnesses/code/skills/documentation/references/style-guide.md CHANGED Viewed

@@ -229,6 +229,17 @@ Use for structured info:
 ---
+## Self-Contained Documents & References
+Two verbosity regimes, split by who pays for the words. **Instruction files** (`CLAUDE.md`, rules, agents, skill prose) load into an agent's context on every turn or invocation — they stay lean, per [`instruction-style.md`](instruction-style.md). **Documents** are read on demand, by humans and agents alike — they are written **verbose and self-contained**, and the cost of a reader hopping files exceeds the cost of extra words on the page.
+- **The body reads whole without opening another file.** Restate the one or two sentences of context a borrowed concept needs, right where it's used — a reader forced mid-paragraph into a second document loses the thread of the first.
+- **Restate for readability, cite for authority — never fork the fact.** A changing detail (a version, a count, a path list) keeps one canonical home; the restatement carries what the page needs to be understood and points at the authority for the rest. Link-don't-copy governs where a fact is *owned*, not how readable the page that uses it must be.
+- **Inline links are the minimum that action requires.** Link mid-prose only where the reader must go there to act on this page. Every other sister document — everything the topic touches — belongs in one **Related** (or **References**) section at the document's end.
+- **The Related tail is the document's entire link surface.** Deep relative paths (`../../../../…`) are fragile — a folder move breaks every one — so they are confined to that one block, where a path change touches one place; body mentions use the plain name (`the boundary skill`, `structure.md`) instead of a link.
+---
 ## 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:

package/data/harnesses/code/skills/documentation/templates/changelog-entry.md CHANGED Viewed

@@ -15,7 +15,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **Ask:** {what the user asked, compressed — taste and preference statements quoted verbatim}
 - **Iterations:** {N} · rejected: {what was rejected and why} | none
 - **Skills:** {skill}@{version} — survived | partially survived | overridden ({why, briefly}) | none used
-- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second}
+- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second. Plan-linked entries also carry the verification gate's results here: rows discharged, suite outcome, anything blocked}
 - **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} | none
 - **Class:** {one or more keywords — suggestive vocabulary, not a closed enum; see Field rules}
 - **Pin:** {enforced artifact written in this entry's commit: test / token / guardrail / schema} | none — candidate: {what should hold it}

package/data/harnesses/code/skills/documentation/templates/plan.md CHANGED Viewed

@@ -1,8 +1,8 @@
 # Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
-Record. 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. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
+Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; after approval the plan gates (`boundary`, then `test-plan`) run against the still-`Draft` file, the status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
-The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
+The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `test-plan` skill writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 ```
 # {Feature Name}
@@ -47,11 +47,18 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 2. Each step ends with something verifiable
 3. ...
+## Test Obligations
+<!-- Written by the `test-plan` skill at the plan gate (after `boundary`). One row per
+     promised behavior: layer · target file · oracle · fixtures. Amendable while the
+     plan is open; discharged at the verification gate. Do not hand-author. -->
 ## Done Criteria
-- [ ] Implementation complete and verified
+- [ ] Implementation complete
+- [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
 - [ ] Affected docs updated (use the injected ownership index to find them)
-- [ ] Changelog entry created in `docs/history/changelog/`
+- [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 ## Open Questions

package/data/harnesses/code/skills/test-plan/SKILL.md CHANGED Viewed

@@ -5,7 +5,7 @@ description: "Use when deriving the tests a plan owes. Test-obligation diagnosti
 # Test-Obligation Diagnostic
-You derive the tests an implementation plan owes, and pin them into the plan as an explicit, reviewable manifest — at the same gate `boundary` runs, ordered second. You never write a test file; you make the standing "tests ship with the change" guardrail *concrete* for this plan, so the implementer satisfies a checklist instead of a vibe, and so a later doc-health pass can prove the tests match the promises.
+You derive the tests an implementation plan owes, and pin them into the plan as an explicit, reviewable manifest — at the same gate `boundary` runs, ordered second. You never write a test file; you write the **ledger the verification gate discharges** (`.claude/rules/verification.md`), so the gate proves a checklist instead of a vibe, and so a later doc-health pass can prove the tests match the promises.
 **The litmus is "which promise, at which altitude, proven by what?"** A plan promises behavior (an LLD's `owns:` surface does X); each promise earns exactly one test at the cheapest layer that can actually prove it. Spend your reading deciding the *layer* and the *oracle*, not on prose.
@@ -34,7 +34,7 @@ Assign each behavior the **cheapest layer that can prove it**, then name the ora
 - **unit** — a pure function / reducer / validator. Oracle: return value, thrown error.
 - **component** — a UI unit's behavior in isolation (a widget, form, panel). Oracle: rendered role/text, emitted event. Runner: the stack's component runner per `testing.md`.
-- **integration** — a route/handler against a real in-memory datastore via the app instance (not a mock of what you own). Oracle: response envelope shape, status code, the row actually written. **This is the default for server behavior** — most obligations land here, and this layer is the one the unit gate (`test` script / CI) runs.
+- **integration** — a route/handler against a real in-memory datastore via the app instance (not a mock of what you own). Oracle: response envelope shape, status code, the row actually written. **This is the default for server behavior** — most obligations land here, and this layer is the one the `test` script / CI runs.
 - **e2e** — see the altitude gate below.
 Error paths, races, and idempotency are obligations too, and they belong at **integration** with injected faults (network mock, the runner's fake timers, a forced constraint) — a process driving a live product cannot reliably *produce* them, so they are never an e2e obligation.
@@ -48,7 +48,7 @@ An e2e obligation (a scenario in the project's e2e tree per `testing.md`) is ear
 ## Run
-**Input:** a plan path (given, or the newest in `docs/history/plans/`), already boundary-checked with amendments folded. For a non-plan diff in test-worthy code, the hunks stand in for Proposed Changes.
+**Input:** a plan path (given, or the newest in `docs/history/plans/`), already boundary-checked with amendments folded. For a non-plan diff in test-worthy code, the hunks stand in for Proposed Changes — but the derived obligations are paid **immediately**, not deferred: only a plan has a ledger and a gate, so for a diff your output is the checklist the implementer satisfies now.
 1. **Build the behavior list.** From the plan's Proposed Changes + the owning LLD's promised behavior, list the behaviors this plan introduces or changes. Fold in each HIGH/CRITICAL boundary finding as a regression obligation. Note behaviors a type or the compiler already guards — those owe **no** test (the boundary litmus, inverted: if it can't ship green-but-broken, it needs no test).
@@ -74,7 +74,7 @@ An e2e obligation (a scenario in the project's e2e tree per `testing.md`) is ear
 ## Rules
-- **Manifest only.** You write the Test Obligations section into the plan and a chat summary. You write **no** test files and **no** `docs/tests/` checklist — those are implementation-time and Completion-time, owned by others.
+- **Manifest only.** You write the Test Obligations section into the plan and a chat summary. You write **no** test files and **no** `docs/tests/` checklist — those are verification-gate-time and Completion-time, owned by others.
 - **Every obligation names its LLD promise.** No promise, no obligation source — trace it or drop it. This is the anti-drift pin.
 - **Cheapest proving layer wins.** Do not obligate an e2e scenario for what an integration test proves, or an integration test for what a unit test proves.
 - **e2e only above the cross-process bar, and only while the smoke gate runs.** Otherwise the obligation is a blocked row naming the missing gate.

package/data/harnesses/delivery/harness.json CHANGED Viewed

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "e56f5cf91025"
+  "digest": "386f83082c31"
 }

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

@@ -78,7 +78,8 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
 | Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
 | Update existing doc | § Editing an existing doc (below) |
-| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | Not these templates — every-load prose stays lean: assertion—reason bullets, tables over diagrams, no ASCII; the present-tense rule still applies |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md) — not these templates; every-load prose stays lean, and the present-tense rule still applies |
+| Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/architecture/skills/playbook/`, chapters `00`–`10`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
 | **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
 ---
@@ -123,6 +124,7 @@ A feature doc carries ownership frontmatter — `owns:` (required), `module:` (o
 | --- | --- |
 | `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
 | `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
 | `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/delivery/skills/documentation/references/instruction-style.md ADDED Viewed

@@ -0,0 +1,49 @@
+# Instruction-File Style
+The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an agent definition, skill prose. Prose style only: frontmatter is metadata, not style. Docs-tree documents follow the skill's templates and [`style-guide.md`](style-guide.md) instead.
+## The test for every line
+An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and rules load on **every turn of every session** — the most expensive prose in a repo per word; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
+**Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
+## Coherence
+A rewrite is not only a trim — read the file as one artifact and fix what disagrees or is missing:
+- **Two statements of one fact agree, or become one.** A defaults block vs. the worked example beside it, a table row vs. a bullet — reconcile against the code the rule governs and keep one canonical statement; a silent disagreement is worse than either version alone, because each reader picks a different one.
+- **Every cross-reference resolves** — the cited `§`, sibling file, or command exists and still says what the citation claims. Section numbers are a public surface other files cite: append, never reshuffle.
+- **The body delivers what the scope line promises, and nothing it disclaims.** A topic named then left to guesswork is a hole; material the scope routes elsewhere is a leak.
+- **Report what you cannot fix.** A defect outside the file — a stale sibling, an unshipped copy — is named in the handback, never fixed by widening the edit.
+## Two genres, one style
+Policy files (`CLAUDE.md`, rules) are declarative — assertion bullets and tables, no second person. Agent and skill bodies are procedures — second person, numbered steps, one observable action per step. The genre sets the shape; everything below applies to both.
+## Routing
+- **Link, don't copy — one canonical source per topic.** `CLAUDE.md` is a **router, not a manual**: per workflow, when to enter, what to dispatch, where the output lands — mechanics live in the agent or skill file, which loads only when it runs.
+- **Cut generic engineering advice.** Agents already know how to code; keep only what is true of *this* stack and not derivable by looking at it.
+- **Keep load-bearing rules even when project-specific.** Genericizing is for reference material, not guardrails — deleting a hard rule removes a constraint the agent will otherwise violate.
+## Voice
+- **Assertion — reason, in one breath.** "**Never name a deployed-value file `.env`** — the dev server auto-loads a root `.env` as local vars, so a prod-valued `.env` silently becomes the local environment." The reason is the rule's armor: an agent that knows the failure mode won't "improve" the rule away; a bare imperative invites second-guessing.
+- **A reason appears once — at the rule it armors.** "One breath" caps a reason's length, not its multiplicity: the same rationale in the scope line, a section intro, and a bullet is the restatement trimming exists to remove. A convention whose only reason is consistency states that once, in the scope line.
+- **One example, carrying every point it can — never a second example of the same point.** An example calibrates a rule an agent would otherwise read loosely; a second one demonstrating the same rule is restatement in costume. Prefer one worked case rich enough for several rules to cite over a fresh citation per bullet.
+- **Grade the bindingness with words.** Bold **never / always / only / must** for hard constraints; "prefer", "default", "acceptable when" for defaults — and every escape hatch states its trigger and its price.
+- **Absolute present tense.** Describe the current design as if it had always been the plan — no "previously", no version narration, no stale-reference tripwires, no progress markers. When something moves or is removed, fix every reference and state only the present fact; the journey lives in git history and `docs/history/`. (Docs-tree tense rules: [`style-guide.md`](style-guide.md) § The Two Natures.)
+## Negative space
+- **Name the rejected alternative.** A package table carries a **Don't use** column because an agent that knows the popular alternative reaches for it unless the file closes the door by name.
+- **Pre-empt the workaround.** Where a failure predictably triggers improvisation, spell out the forbidden moves and the exact stop-and-report. The umbrella: **no silent fallback** — fail loudly rather than route around.
+## Material & mechanics
+- **Tables for enumerable facts, prose for judgment.** One row per item kills the urge to explain; anything that needs a *because* lives in prose around the table, never inside a cell.
+- **No ASCII diagrams.** A box-and-arrow diagram costs many tokens for what a sentence or a small table carries.
+- Inline-code every identifier, filename, command, and config key.
+- ❌ / ✅ only inside banned/blessed lists, not as general decoration.
+- `>` blockquotes set off interruptions — cross-pointers, callouts, agent guards — not the main line.

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

@@ -229,6 +229,17 @@ Use for structured info:
 ---
+## Self-Contained Documents & References
+Two verbosity regimes, split by who pays for the words. **Instruction files** (`CLAUDE.md`, rules, agents, skill prose) load into an agent's context on every turn or invocation — they stay lean, per [`instruction-style.md`](instruction-style.md). **Documents** are read on demand, by humans and agents alike — they are written **verbose and self-contained**, and the cost of a reader hopping files exceeds the cost of extra words on the page.
+- **The body reads whole without opening another file.** Restate the one or two sentences of context a borrowed concept needs, right where it's used — a reader forced mid-paragraph into a second document loses the thread of the first.
+- **Restate for readability, cite for authority — never fork the fact.** A changing detail (a version, a count, a path list) keeps one canonical home; the restatement carries what the page needs to be understood and points at the authority for the rest. Link-don't-copy governs where a fact is *owned*, not how readable the page that uses it must be.
+- **Inline links are the minimum that action requires.** Link mid-prose only where the reader must go there to act on this page. Every other sister document — everything the topic touches — belongs in one **Related** (or **References**) section at the document's end.
+- **The Related tail is the document's entire link surface.** Deep relative paths (`../../../../…`) are fragile — a folder move breaks every one — so they are confined to that one block, where a path change touches one place; body mentions use the plain name (`the boundary skill`, `structure.md`) instead of a link.
+---
 ## 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:

package/data/harnesses/delivery/skills/documentation/templates/changelog-entry.md CHANGED Viewed

@@ -15,7 +15,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **Ask:** {what the user asked, compressed — taste and preference statements quoted verbatim}
 - **Iterations:** {N} · rejected: {what was rejected and why} | none
 - **Skills:** {skill}@{version} — survived | partially survived | overridden ({why, briefly}) | none used
-- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second}
+- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second. Plan-linked entries also carry the verification gate's results here: rows discharged, suite outcome, anything blocked}
 - **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} | none
 - **Class:** {one or more keywords — suggestive vocabulary, not a closed enum; see Field rules}
 - **Pin:** {enforced artifact written in this entry's commit: test / token / guardrail / schema} | none — candidate: {what should hold it}

package/data/harnesses/delivery/skills/documentation/templates/plan.md CHANGED Viewed

@@ -1,8 +1,8 @@
 # Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
-Record. 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. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
+Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; after approval the plan gates (`boundary`, then `test-plan`) run against the still-`Draft` file, the status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
-The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
+The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `test-plan` skill writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 ```
 # {Feature Name}
@@ -47,11 +47,18 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 2. Each step ends with something verifiable
 3. ...
+## Test Obligations
+<!-- Written by the `test-plan` skill at the plan gate (after `boundary`). One row per
+     promised behavior: layer · target file · oracle · fixtures. Amendable while the
+     plan is open; discharged at the verification gate. Do not hand-author. -->
 ## Done Criteria
-- [ ] Implementation complete and verified
+- [ ] Implementation complete
+- [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
 - [ ] Affected docs updated (use the injected ownership index to find them)
-- [ ] Changelog entry created in `docs/history/changelog/`
+- [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 ## Open Questions

package/data/harnesses/etna/CLAUDE.md CHANGED Viewed

@@ -101,7 +101,7 @@ Invoke the `boundary` skill after a plan is approved and before its first implem
 ### Documentation — close the loop
-- **Every markdown document goes through the `documentation` skill.** Before creating or substantively editing any `.md` document — a doc, a README, an index, a record — invoke the `documentation` skill and apply its templates and `references/style-guide.md` (truth documents present-tense; history only in records). Instruction files — `CLAUDE.md`, rules, agents, skills — follow [`docs/architecture/writing-style.md`](docs/architecture/writing-style.md) instead.
+- **Every markdown document goes through the `documentation` skill.** Before creating or substantively editing any `.md` document — a doc, a README, an index, a record — invoke the `documentation` skill and apply its templates and `references/style-guide.md` (truth documents present-tense; history only in records). Instruction files — `CLAUDE.md`, rules, agents, skills — follow the skill's [`references/instruction-style.md`](skills/documentation/references/instruction-style.md) instead.
 - **[override]** Keep `docs/` updated when a change alters documented behaviour — creating and updating docs is part of the work.
 - After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed — and append its `docs/history/CHANGELOG.md` row; the commit fills what the draft left open and freezes it. Non-plan work needs no separate prompt: every non-exempt commit carries its own entry (the `changelog` rule).
 - When moving or renaming a component: update the `owns:` globs of the feature doc that owns it so the ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter.

package/data/harnesses/etna/harness.json CHANGED Viewed

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "4a94c1c4b34c"
+  "digest": "a8993d8c2d44"
 }

package/data/harnesses/etna/skills/documentation/SKILL.md CHANGED Viewed

@@ -78,7 +78,8 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
 | Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
 | Update existing doc | § Editing an existing doc (below) |
-| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | Not these templates — every-load prose stays lean: assertion—reason bullets, tables over diagrams, no ASCII; the present-tense rule still applies |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md) — not these templates; every-load prose stays lean, and the present-tense rule still applies |
+| Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/architecture/skills/playbook/`, chapters `00`–`10`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
 | **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
 ---
@@ -123,6 +124,7 @@ A feature doc carries ownership frontmatter — `owns:` (required), `module:` (o
 | --- | --- |
 | `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
 | `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
 | `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/etna/skills/documentation/references/instruction-style.md ADDED Viewed

@@ -0,0 +1,49 @@
+# Instruction-File Style
+The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an agent definition, skill prose. Prose style only: frontmatter is metadata, not style. Docs-tree documents follow the skill's templates and [`style-guide.md`](style-guide.md) instead.
+## The test for every line
+An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and rules load on **every turn of every session** — the most expensive prose in a repo per word; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
+**Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
+## Coherence
+A rewrite is not only a trim — read the file as one artifact and fix what disagrees or is missing:
+- **Two statements of one fact agree, or become one.** A defaults block vs. the worked example beside it, a table row vs. a bullet — reconcile against the code the rule governs and keep one canonical statement; a silent disagreement is worse than either version alone, because each reader picks a different one.
+- **Every cross-reference resolves** — the cited `§`, sibling file, or command exists and still says what the citation claims. Section numbers are a public surface other files cite: append, never reshuffle.
+- **The body delivers what the scope line promises, and nothing it disclaims.** A topic named then left to guesswork is a hole; material the scope routes elsewhere is a leak.
+- **Report what you cannot fix.** A defect outside the file — a stale sibling, an unshipped copy — is named in the handback, never fixed by widening the edit.
+## Two genres, one style
+Policy files (`CLAUDE.md`, rules) are declarative — assertion bullets and tables, no second person. Agent and skill bodies are procedures — second person, numbered steps, one observable action per step. The genre sets the shape; everything below applies to both.
+## Routing
+- **Link, don't copy — one canonical source per topic.** `CLAUDE.md` is a **router, not a manual**: per workflow, when to enter, what to dispatch, where the output lands — mechanics live in the agent or skill file, which loads only when it runs.
+- **Cut generic engineering advice.** Agents already know how to code; keep only what is true of *this* stack and not derivable by looking at it.
+- **Keep load-bearing rules even when project-specific.** Genericizing is for reference material, not guardrails — deleting a hard rule removes a constraint the agent will otherwise violate.
+## Voice
+- **Assertion — reason, in one breath.** "**Never name a deployed-value file `.env`** — the dev server auto-loads a root `.env` as local vars, so a prod-valued `.env` silently becomes the local environment." The reason is the rule's armor: an agent that knows the failure mode won't "improve" the rule away; a bare imperative invites second-guessing.
+- **A reason appears once — at the rule it armors.** "One breath" caps a reason's length, not its multiplicity: the same rationale in the scope line, a section intro, and a bullet is the restatement trimming exists to remove. A convention whose only reason is consistency states that once, in the scope line.
+- **One example, carrying every point it can — never a second example of the same point.** An example calibrates a rule an agent would otherwise read loosely; a second one demonstrating the same rule is restatement in costume. Prefer one worked case rich enough for several rules to cite over a fresh citation per bullet.
+- **Grade the bindingness with words.** Bold **never / always / only / must** for hard constraints; "prefer", "default", "acceptable when" for defaults — and every escape hatch states its trigger and its price.
+- **Absolute present tense.** Describe the current design as if it had always been the plan — no "previously", no version narration, no stale-reference tripwires, no progress markers. When something moves or is removed, fix every reference and state only the present fact; the journey lives in git history and `docs/history/`. (Docs-tree tense rules: [`style-guide.md`](style-guide.md) § The Two Natures.)
+## Negative space
+- **Name the rejected alternative.** A package table carries a **Don't use** column because an agent that knows the popular alternative reaches for it unless the file closes the door by name.
+- **Pre-empt the workaround.** Where a failure predictably triggers improvisation, spell out the forbidden moves and the exact stop-and-report. The umbrella: **no silent fallback** — fail loudly rather than route around.
+## Material & mechanics
+- **Tables for enumerable facts, prose for judgment.** One row per item kills the urge to explain; anything that needs a *because* lives in prose around the table, never inside a cell.
+- **No ASCII diagrams.** A box-and-arrow diagram costs many tokens for what a sentence or a small table carries.
+- Inline-code every identifier, filename, command, and config key.
+- ❌ / ✅ only inside banned/blessed lists, not as general decoration.
+- `>` blockquotes set off interruptions — cross-pointers, callouts, agent guards — not the main line.

package/data/harnesses/etna/skills/documentation/references/style-guide.md CHANGED Viewed

@@ -229,6 +229,17 @@ Use for structured info:
 ---
+## Self-Contained Documents & References
+Two verbosity regimes, split by who pays for the words. **Instruction files** (`CLAUDE.md`, rules, agents, skill prose) load into an agent's context on every turn or invocation — they stay lean, per [`instruction-style.md`](instruction-style.md). **Documents** are read on demand, by humans and agents alike — they are written **verbose and self-contained**, and the cost of a reader hopping files exceeds the cost of extra words on the page.
+- **The body reads whole without opening another file.** Restate the one or two sentences of context a borrowed concept needs, right where it's used — a reader forced mid-paragraph into a second document loses the thread of the first.
+- **Restate for readability, cite for authority — never fork the fact.** A changing detail (a version, a count, a path list) keeps one canonical home; the restatement carries what the page needs to be understood and points at the authority for the rest. Link-don't-copy governs where a fact is *owned*, not how readable the page that uses it must be.
+- **Inline links are the minimum that action requires.** Link mid-prose only where the reader must go there to act on this page. Every other sister document — everything the topic touches — belongs in one **Related** (or **References**) section at the document's end.
+- **The Related tail is the document's entire link surface.** Deep relative paths (`../../../../…`) are fragile — a folder move breaks every one — so they are confined to that one block, where a path change touches one place; body mentions use the plain name (`the boundary skill`, `structure.md`) instead of a link.
+---
 ## 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:

package/data/harnesses/etna/skills/documentation/templates/changelog-entry.md CHANGED Viewed

@@ -15,7 +15,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **Ask:** {what the user asked, compressed — taste and preference statements quoted verbatim}
 - **Iterations:** {N} · rejected: {what was rejected and why} | none
 - **Skills:** {skill}@{version} — survived | partially survived | overridden ({why, briefly}) | none used
-- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second}
+- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second. Plan-linked entries also carry the verification gate's results here: rows discharged, suite outcome, anything blocked}
 - **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} | none
 - **Class:** {one or more keywords — suggestive vocabulary, not a closed enum; see Field rules}
 - **Pin:** {enforced artifact written in this entry's commit: test / token / guardrail / schema} | none — candidate: {what should hold it}

package/data/harnesses/etna/skills/documentation/templates/plan.md CHANGED Viewed

@@ -1,8 +1,8 @@
 # Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
-Record. 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. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
+Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; after approval the plan gates (`boundary`, then `test-plan`) run against the still-`Draft` file, the status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
-The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
+The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `test-plan` skill writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 ```
 # {Feature Name}
@@ -47,11 +47,18 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 2. Each step ends with something verifiable
 3. ...
+## Test Obligations
+<!-- Written by the `test-plan` skill at the plan gate (after `boundary`). One row per
+     promised behavior: layer · target file · oracle · fixtures. Amendable while the
+     plan is open; discharged at the verification gate. Do not hand-author. -->
 ## Done Criteria
-- [ ] Implementation complete and verified
+- [ ] Implementation complete
+- [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
 - [ ] Affected docs updated (use the injected ownership index to find them)
-- [ ] Changelog entry created in `docs/history/changelog/`
+- [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 ## Open Questions

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.35",
+    "version": "0.19.36",
     "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": {