@nurix/etna 0.19.65 → 0.19.67

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

@@ -16,7 +16,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **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. 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
+- **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} [source: {tag}] | 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}
 ```
@@ -39,7 +39,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **`surface`** uses the repo's ownership vocabulary — the owning feature doc's topic or an `owns:` path stem — so entries are queryable per surface.
 - **`Ask` quotes taste verbatim.** The user's preference wording is the one thing no skill can infer and no rebuild recovers; the entry is its durable home.
 - **`Skills` records efficacy honestly** — survived / partially survived / overridden with a reason. These verdicts are the raw data the `retro` agent aggregates into skill-evolution findings; sanitizing them into success stories destroys the mechanism's value.
-- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded the same day — this field feeds the pin candidates.
+- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded the same day — this field feeds the pin candidates. **Each finding carries a `source:` tag from a closed list** — `generator` (a generated doc was wrong) · `generator-conflict` (two generated docs disagreed) · `rules-conflict` (a generated doc contradicted standing rules) · `runtime-discovery` (only running revealed it) · `environment` (tooling or harness). Closed deliberately, unlike `Class:` — the consumer is the doc generator's readback grep, not a human. A finding in a repo with no generated docs is almost always `runtime-discovery` or `environment`.
 - **`Class` is a suggestive vocabulary, not a closed enum.** Tag with one or more keywords, preferring an existing term over a synonym so the `retro` agent can cluster; coin a new one when nothing fits — a recurring coinage is itself retro signal that the vocabulary (or the doc set) is missing a category. Suggested keywords: `ux` · `ui` · `visual` · `taste` · `layout` · `motion` · `interaction` · `copy` · `a11y` · `responsiveness` · `navigation` · `state` · `structure` · `architecture` · `seam` · `contract` · `schema` · `data` · `content` · `seed` · `performance` · `caching` · `resilience` · `error-handling` · `security` · `auth` · `observability` · `logging` · `testing` · `tooling` · `dependency` · `ops` · `deploy` · `env` · `ci` · `i18n` · `docs`.
 - **`Pin` closes the loop:** the enforced artifact written in this commit, or the named candidate for the `retro` agent to flag. A taste-verified behavior with `Pin: none` and no candidate is a template smell.
 - **Out-of-session entries** (the writing session did not do the work): fill what the diff and conversation evidence support; mark the rest `unknown — committed out-of-session`.

package/data/harnesses/code/skills/documentation/templates/feature.md

@@ -13,6 +13,7 @@ module: billing                                  # optional — single bounded-c
 keywords: [invoice, pdf]                         # required — discovery terms
 status: active                                   # required — active | draft | deprecated
 last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
+type: feature                                    # required tooling key — genre stamp (generator-written or authored; enum = the template names), read by tooling (UI grouping, protected-file mapping); preserve on edits, never narrate
 ---
 ```
 

package/data/harnesses/code/skills/documentation/templates/implementation-map.md

@@ -0,0 +1,42 @@
+# Implementation Map (docs/operations/implementation-map.md)
+
+Truth document. Use for: **the cold-start execution contract of a project being built from its documented design** — one per repo, at `docs/operations/implementation-map.md`. It is authored by the **executing session at build start**, never generated at design time: build order is derived from the repo's actual feature docs and their stated dependencies, and a design-time prediction of it goes stale the day reality disagrees. It lives in operations because it says *how to proceed*, not *what is true of the design*.
+
+## Writing the map
+
+- **Derive waves from the feature docs** — their stated dependencies plus shared foundations (schema before routes, auth before anything it guards). A wave groups features that can build together; the order reflects foundations, not product importance.
+- **A wave's done criterion is observable** — its plans' verification gates passed, the suite green, a named surface driveable. Never "feels complete".
+- **Authority order names this repo's own docs, most specific wins.** A contradiction between documents is repaired in the owning truth doc *before* code — never reinterpreted while planning.
+- **Plans are records, not an execution queue.** The map points at the active wave's dated plan; historical plans are read only when a truth doc cites them as provenance.
+- **Update in place as waves complete** — the map states the current build position in present tense; the journey lives in the plans and changelog entries.
+
+```
+# {Project} implementation map
+
+## Cold-start contract
+
+{One paragraph: what a fresh session asked to "build this" is expected to do with this
+repository — plan, gate, implement, verify, in what granularity — and the statement that it
+needs nothing outside the repo.}
+
+## Authority order
+
+When documents disagree:
+
+1. {The constitutional docs — guardrails, non-goals, PRD-class documents}
+2. The most specific feature doc under `docs/features/`
+3. {The structural truth docs — domain model, storage schema, API contracts}
+4. The dated plan for the active wave
+5. Owned source files as implementation evidence
+
+## Waves
+
+| Wave | Features | Depends on | Done when |
+| - | - | - | - |
+| 1 | {docs/features/x.md, docs/features/y.md} | — | {observable criterion} |
+| 2 | {…} | 1 | {…} |
+
+## Current position
+
+{One line per wave: complete · in progress ([plan](../history/plans/YYYY-MM-DD-slug.md)) · pending.}
+```

package/data/harnesses/code/skills/testing/SKILL.md

@@ -47,14 +47,14 @@ Assign each behavior the **cheapest layer that can prove it**, then name the ora
    ```
    ## Test Obligations
 
-   | # | Behavior (LLD promise) | Layer | Target file | Oracle | Fixtures / faults |
-   | - | ---------------------- | ----- | ----------- | ------ | ----------------- |
+   | # | Behavior (LLD promise) | Layer | Target file | Oracle | Fixtures / faults | Outcome |
+   | - | ---------------------- | ----- | ----------- | ------ | ----------------- | ------- |
 
    Coverage: {N} behaviors · {N} integration · {N} component · {N} unit · {N} e2e ({N} extend, {N} new)
    Completion checklist: docs/tests/{feature}.md  (derived at the gate, not now)
    ```
 
-   A behavior with no obligation is stated too, with the reason — "none — compiler-guarded" reads as *checked*; an empty cell reads as *not analyzed*. A short manifest is valid — do not pad.
+   A behavior with no obligation is stated too, with the reason — "none — compiler-guarded" reads as *checked*; an empty cell reads as *not analyzed*. A short manifest is valid — do not pad. **`Outcome` is written empty here — it is gate mode's cell**, and the completion walls read it: a plan cannot reach `Status: Complete` while any row's Outcome is empty.
 6. **Record the write in the plan's `Gates:` line**, rewriting only your segment to exactly `Test-plan: written YYYY-MM-DD (N rows)` — the compliance hook greps this exact form. Add the line if the plan predates the format.
 
 ---
@@ -162,5 +162,5 @@ Runs only when the user triggers the verification gate (constraints — precondi
 
    A driven check is evidence, not an artifact — it proves the change works today and leaves nothing behind; that is why this rung exists.
 4. **Run the affected suite**, plus the project's e2e smoke gate where one is wired.
-5. **Discharge every ledger row into exactly one outcome**: **satisfied** (test green, or driven check passed), **owes nothing** (with the reason — compiler-guarded, covered elsewhere), or **blocked** (missing infrastructure named, row converted to a backlog item). A row left unexamined blocks the gate.
-6. **Report results honestly, including failures**; record which test now guards each checklist section (`Pinned:` traces). Completion steps — freezing the plan, the changelog entry — are the root policy file's, not yours.
+5. **Discharge every ledger row into exactly one outcome**: **satisfied** (test green, or driven check passed), **owes nothing** (with the reason — compiler-guarded, covered elsewhere), or **blocked** (missing infrastructure named, row converted to a backlog item). **Open by re-reading the ledger from the plan file on disk, never from conversation memory** — a context-held copy is how rows get missed. **Write each row's outcome into its `Outcome` cell in the plan file** — exactly `satisfied`, `owes nothing — {reason}`, or `blocked → backlog` — because the Stop wall and CI read that cell, and a row left unexamined blocks completion.
+6. **Report results honestly, including failures**; record which test now guards each checklist section (`Pinned:` traces) and each section's `AC:` line where the repo carries a keyed acceptance-criteria source, closing with the coverage count — `AC coverage: {n}/{m}; uncovered: {keys} → backlog`. Completion steps — freezing the plan, the changelog entry — are the root policy file's, not yours.

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

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -62,6 +62,7 @@ For each `owns:` glob across the feature docs:
 
 - Verify the glob matches existing files. Report globs matching nothing, deleted paths, and orphaned docs.
 - Flag **equal-specificity overlaps** — two feature docs whose `owns:` globs claim the same paths at the same specificity (an ambiguous owner). Surface as a question.
+- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`, and so on). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
 
 For each code symbol or path a doc explicitly **names** (function/export/route/type):
 
@@ -185,6 +186,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/delivery/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.2.1",
+  "version": "0.2.5",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "83870917a79b"
+  "digest": "99afecb2c42f"
 }

package/data/harnesses/delivery/rules/changelog.md

@@ -12,6 +12,8 @@ Every unit of work leaves one record — `docs/history/changelog/YYYY-MM-DD-{thr
 
 An entry is owed only by work that changes promised behavior or takes a design decision; mechanical and cosmetic commits — a typo, a copy tweak, a config value, a log line — take only their `docs/history/CHANGELOG.md` row, no entry file. The failure fields (`Ask:`, `Skills:`, `Pin:`) are required only when non-none.
 
+Route the lesson by who pays for losing it: product context — what changed and why — belongs in the entry; anything the **next session would re-pay** — a library's API drifted from what the model expects, a validator's quirk, a tooling workaround — goes to `docs/memory/main.md` as well, because a changelog is read by people tracing history and memory is read by every session before it repeats the mistake.
+
 ## Lifecycle
 
 Draft (created before its commit exists) → complete (missing fields filled from the diff and the session) → frozen the moment it rides in a commit. **Immutability begins at commit, not at creation** — a draft is meant to be edited, which is what lets a completed plan record its context before anything is committed; a committed entry is history, and a correction is a new entry linking back, **never** an edit.

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

@@ -73,6 +73,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Testing strategy | [`templates/testing-strategy.md`](templates/testing-strategy.md) |
 | Behavioral checklist for one feature (`docs/tests/{feature}.md`) | [`templates/behavioral-checklist.md`](templates/behavioral-checklist.md) — the verification gate's driving script, and the source its suite tests are drawn from |
 | Recurring procedure/setup | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
+| Cold-start build order (implementation map) | [`templates/implementation-map.md`](templates/implementation-map.md) — authored by the executing session at build start, updated in place as waves complete |
 | Capture mid-execution knowledge (`docs/history/journal.md`) | [`templates/journal.md`](templates/journal.md) (record — append-only; a row resolves by landing in its owning doc) |
 | Bookkeeping work queue (`docs/operations/bookkeeping.md`) | [`templates/bookkeeping.md`](templates/bookkeeping.md) — machine-read row grammar; appended by hooks and sessions, drained by the `bookkeeper` agent, walled at Stop and commit |
 | One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |

package/data/harnesses/delivery/skills/documentation/references/frontmatter.md

@@ -12,7 +12,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ## How to derive the frontmatter
 
-A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
+A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key.
 
 **1. `owns:`** (the path scope)
 

package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.
@@ -89,7 +89,7 @@ function lintFile(path, findings) {
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
   if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
     const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
-    for (const key of ['owns:', 'keywords:', 'status:'])
+    for (const key of ['owns:', 'keywords:', 'status:', 'type:'])
       if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
   }
 }

package/data/harnesses/delivery/skills/documentation/templates/Readme.md

@@ -16,6 +16,7 @@ One file per template. Every template is either a **truth document** (states cur
 | Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
 | Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | Truth |
 | Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
+| Implementation map | [implementation-map.md](implementation-map.md) | Truth |
 | Bookkeeping ledger | [bookkeeping.md](bookkeeping.md) | Truth (work queue) |
 | Protected files | [protected-files.md](protected-files.md) | Truth |
 | Project root README | [root-readme.md](root-readme.md) | Truth |

package/data/harnesses/delivery/skills/documentation/templates/behavioral-checklist.md

@@ -16,6 +16,7 @@ Required: **Conventions**, at least one numbered behavior section, **Failure Rep
 - **Prefer exact literals** — the real prompt text, the real button label, the real count. A vague assertion passes a broken product.
 - **Assert persistence separately from display.** "It appeared on screen" and "it was written" are two claims; a surface that streams unsaved content satisfies the first while failing the second.
 - **State each section's trace.** `Pinned:` names the suite test that now guards it, or says `driven only` **with the reason** — an unmarked section is indistinguishable from an unexamined one.
+- **State each section's `AC:` keys.** Where the repo carries a keyed acceptance-criteria source, each section names the keys it proves, so the chain from criterion to checklist to suite test survives the last hop; the gate reports coverage and backlogs uncovered keys. `none — not AC-mapped` is the honest line where no keyed source exists.
 - **A known-failing assertion stays written as the contract.** A checklist states what the feature promises; the *run* records the failure and the backlog carries the defect. Never soften an assertion to make a run go green.
 
 ```
@@ -44,6 +45,7 @@ Each step is an action; each **Assert** is the observable it must produce.
 - [ ] **Assert**: {the persistence claim, where the behavior writes something}
 
 > Pinned: `{tests/path/to/file.test.ts}` — or `driven only — {why no durable test is bought}`
+> AC: {the acceptance-criteria keys this section proves} — or `none — not AC-mapped`
 
 ### 2. {The next behavior}
 

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

@@ -16,7 +16,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **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. 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
+- **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} [source: {tag}] | 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}
 ```
@@ -39,7 +39,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **`surface`** uses the repo's ownership vocabulary — the owning feature doc's topic or an `owns:` path stem — so entries are queryable per surface.
 - **`Ask` quotes taste verbatim.** The user's preference wording is the one thing no skill can infer and no rebuild recovers; the entry is its durable home.
 - **`Skills` records efficacy honestly** — survived / partially survived / overridden with a reason. These verdicts are the raw data the `retro` agent aggregates into skill-evolution findings; sanitizing them into success stories destroys the mechanism's value.
-- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded the same day — this field feeds the pin candidates.
+- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded the same day — this field feeds the pin candidates. **Each finding carries a `source:` tag from a closed list** — `generator` (a generated doc was wrong) · `generator-conflict` (two generated docs disagreed) · `rules-conflict` (a generated doc contradicted standing rules) · `runtime-discovery` (only running revealed it) · `environment` (tooling or harness). Closed deliberately, unlike `Class:` — the consumer is the doc generator's readback grep, not a human. A finding in a repo with no generated docs is almost always `runtime-discovery` or `environment`.
 - **`Class` is a suggestive vocabulary, not a closed enum.** Tag with one or more keywords, preferring an existing term over a synonym so the `retro` agent can cluster; coin a new one when nothing fits — a recurring coinage is itself retro signal that the vocabulary (or the doc set) is missing a category. Suggested keywords: `ux` · `ui` · `visual` · `taste` · `layout` · `motion` · `interaction` · `copy` · `a11y` · `responsiveness` · `navigation` · `state` · `structure` · `architecture` · `seam` · `contract` · `schema` · `data` · `content` · `seed` · `performance` · `caching` · `resilience` · `error-handling` · `security` · `auth` · `observability` · `logging` · `testing` · `tooling` · `dependency` · `ops` · `deploy` · `env` · `ci` · `i18n` · `docs`.
 - **`Pin` closes the loop:** the enforced artifact written in this commit, or the named candidate for the `retro` agent to flag. A taste-verified behavior with `Pin: none` and no candidate is a template smell.
 - **Out-of-session entries** (the writing session did not do the work): fill what the diff and conversation evidence support; mark the rest `unknown — committed out-of-session`.

package/data/harnesses/delivery/skills/documentation/templates/feature.md

@@ -13,6 +13,7 @@ module: billing                                  # optional — single bounded-c
 keywords: [invoice, pdf]                         # required — discovery terms
 status: active                                   # required — active | draft | deprecated
 last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
+type: feature                                    # required tooling key — genre stamp (generator-written or authored; enum = the template names), read by tooling (UI grouping, protected-file mapping); preserve on edits, never narrate
 ---
 ```
 

package/data/harnesses/delivery/skills/documentation/templates/implementation-map.md

@@ -0,0 +1,42 @@
+# Implementation Map (docs/operations/implementation-map.md)
+
+Truth document. Use for: **the cold-start execution contract of a project being built from its documented design** — one per repo, at `docs/operations/implementation-map.md`. It is authored by the **executing session at build start**, never generated at design time: build order is derived from the repo's actual feature docs and their stated dependencies, and a design-time prediction of it goes stale the day reality disagrees. It lives in operations because it says *how to proceed*, not *what is true of the design*.
+
+## Writing the map
+
+- **Derive waves from the feature docs** — their stated dependencies plus shared foundations (schema before routes, auth before anything it guards). A wave groups features that can build together; the order reflects foundations, not product importance.
+- **A wave's done criterion is observable** — its plans' verification gates passed, the suite green, a named surface driveable. Never "feels complete".
+- **Authority order names this repo's own docs, most specific wins.** A contradiction between documents is repaired in the owning truth doc *before* code — never reinterpreted while planning.
+- **Plans are records, not an execution queue.** The map points at the active wave's dated plan; historical plans are read only when a truth doc cites them as provenance.
+- **Update in place as waves complete** — the map states the current build position in present tense; the journey lives in the plans and changelog entries.
+
+```
+# {Project} implementation map
+
+## Cold-start contract
+
+{One paragraph: what a fresh session asked to "build this" is expected to do with this
+repository — plan, gate, implement, verify, in what granularity — and the statement that it
+needs nothing outside the repo.}
+
+## Authority order
+
+When documents disagree:
+
+1. {The constitutional docs — guardrails, non-goals, PRD-class documents}
+2. The most specific feature doc under `docs/features/`
+3. {The structural truth docs — domain model, storage schema, API contracts}
+4. The dated plan for the active wave
+5. Owned source files as implementation evidence
+
+## Waves
+
+| Wave | Features | Depends on | Done when |
+| - | - | - | - |
+| 1 | {docs/features/x.md, docs/features/y.md} | — | {observable criterion} |
+| 2 | {…} | 1 | {…} |
+
+## Current position
+
+{One line per wave: complete · in progress ([plan](../history/plans/YYYY-MM-DD-slug.md)) · pending.}
+```

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

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -62,6 +62,7 @@ For each `owns:` glob across the feature docs:
 
 - Verify the glob matches existing files. Report globs matching nothing, deleted paths, and orphaned docs.
 - Flag **equal-specificity overlaps** — two feature docs whose `owns:` globs claim the same paths at the same specificity (an ambiguous owner). Surface as a question.
+- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`, and so on). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
 
 For each code symbol or path a doc explicitly **names** (function/export/route/type):
 
@@ -185,6 +186,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/etna/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.4.1",
+  "version": "1.4.4",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "4d6b33a51517"
+  "digest": "dca4815bd3d5"
 }

package/data/harnesses/etna/rules/changelog.md

@@ -12,6 +12,8 @@ Every unit of work leaves one record — `docs/history/changelog/YYYY-MM-DD-{thr
 
 An entry is owed only by work that changes promised behavior or takes a design decision; mechanical and cosmetic commits — a typo, a copy tweak, a config value, a log line — take only their `docs/history/CHANGELOG.md` row, no entry file. The failure fields (`Ask:`, `Skills:`, `Pin:`) are required only when non-none.
 
+Route the lesson by who pays for losing it: product context — what changed and why — belongs in the entry; anything the **next session would re-pay** — a library's API drifted from what the model expects, a validator's quirk, a tooling workaround — goes to `docs/memory/main.md` as well, because a changelog is read by people tracing history and memory is read by every session before it repeats the mistake.
+
 ## Lifecycle
 
 Draft (created before its commit exists) → complete (missing fields filled from the diff and the session) → frozen the moment it rides in a commit. **Immutability begins at commit, not at creation** — a draft is meant to be edited, which is what lets a completed plan record its context before anything is committed; a committed entry is history, and a correction is a new entry linking back, **never** an edit.

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

@@ -73,6 +73,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Testing strategy | [`templates/testing-strategy.md`](templates/testing-strategy.md) |
 | Behavioral checklist for one feature (`docs/tests/{feature}.md`) | [`templates/behavioral-checklist.md`](templates/behavioral-checklist.md) — the verification gate's driving script, and the source its suite tests are drawn from |
 | Recurring procedure/setup | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
+| Cold-start build order (implementation map) | [`templates/implementation-map.md`](templates/implementation-map.md) — authored by the executing session at build start, updated in place as waves complete |
 | Capture mid-execution knowledge (`docs/history/journal.md`) | [`templates/journal.md`](templates/journal.md) (record — append-only; a row resolves by landing in its owning doc) |
 | Bookkeeping work queue (`docs/operations/bookkeeping.md`) | [`templates/bookkeeping.md`](templates/bookkeeping.md) — machine-read row grammar; appended by hooks and sessions, drained by the `bookkeeper` agent, walled at Stop and commit |
 | One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |

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

@@ -12,7 +12,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ## How to derive the frontmatter
 
-A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
+A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key.
 
 **1. `owns:`** (the path scope)
 

package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.
@@ -89,7 +89,7 @@ function lintFile(path, findings) {
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
   if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
     const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
-    for (const key of ['owns:', 'keywords:', 'status:'])
+    for (const key of ['owns:', 'keywords:', 'status:', 'type:'])
       if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
   }
 }

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

@@ -16,6 +16,7 @@ One file per template. Every template is either a **truth document** (states cur
 | Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
 | Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | Truth |
 | Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
+| Implementation map | [implementation-map.md](implementation-map.md) | Truth |
 | Bookkeeping ledger | [bookkeeping.md](bookkeeping.md) | Truth (work queue) |
 | Protected files | [protected-files.md](protected-files.md) | Truth |
 | Project root README | [root-readme.md](root-readme.md) | Truth |

package/data/harnesses/etna/skills/documentation/templates/behavioral-checklist.md

@@ -16,6 +16,7 @@ Required: **Conventions**, at least one numbered behavior section, **Failure Rep
 - **Prefer exact literals** — the real prompt text, the real button label, the real count. A vague assertion passes a broken product.
 - **Assert persistence separately from display.** "It appeared on screen" and "it was written" are two claims; a surface that streams unsaved content satisfies the first while failing the second.
 - **State each section's trace.** `Pinned:` names the suite test that now guards it, or says `driven only` **with the reason** — an unmarked section is indistinguishable from an unexamined one.
+- **State each section's `AC:` keys.** Where the repo carries a keyed acceptance-criteria source, each section names the keys it proves, so the chain from criterion to checklist to suite test survives the last hop; the gate reports coverage and backlogs uncovered keys. `none — not AC-mapped` is the honest line where no keyed source exists.
 - **A known-failing assertion stays written as the contract.** A checklist states what the feature promises; the *run* records the failure and the backlog carries the defect. Never soften an assertion to make a run go green.
 
 ```
@@ -44,6 +45,7 @@ Each step is an action; each **Assert** is the observable it must produce.
 - [ ] **Assert**: {the persistence claim, where the behavior writes something}
 
 > Pinned: `{tests/path/to/file.test.ts}` — or `driven only — {why no durable test is bought}`
+> AC: {the acceptance-criteria keys this section proves} — or `none — not AC-mapped`
 
 ### 2. {The next behavior}
 

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

@@ -16,7 +16,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **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. 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
+- **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} [source: {tag}] | 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}
 ```
@@ -39,7 +39,7 @@ An entry is not a summary line. Its value concentrates in the fields a diff cann
 - **`surface`** uses the repo's ownership vocabulary — the owning feature doc's topic or an `owns:` path stem — so entries are queryable per surface.
 - **`Ask` quotes taste verbatim.** The user's preference wording is the one thing no skill can infer and no rebuild recovers; the entry is its durable home.
 - **`Skills` records efficacy honestly** — survived / partially survived / overridden with a reason. These verdicts are the raw data the `retro` agent aggregates into skill-evolution findings; sanitizing them into success stories destroys the mechanism's value.
-- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded the same day — this field feeds the pin candidates.
+- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded the same day — this field feeds the pin candidates. **Each finding carries a `source:` tag from a closed list** — `generator` (a generated doc was wrong) · `generator-conflict` (two generated docs disagreed) · `rules-conflict` (a generated doc contradicted standing rules) · `runtime-discovery` (only running revealed it) · `environment` (tooling or harness). Closed deliberately, unlike `Class:` — the consumer is the doc generator's readback grep, not a human. A finding in a repo with no generated docs is almost always `runtime-discovery` or `environment`.
 - **`Class` is a suggestive vocabulary, not a closed enum.** Tag with one or more keywords, preferring an existing term over a synonym so the `retro` agent can cluster; coin a new one when nothing fits — a recurring coinage is itself retro signal that the vocabulary (or the doc set) is missing a category. Suggested keywords: `ux` · `ui` · `visual` · `taste` · `layout` · `motion` · `interaction` · `copy` · `a11y` · `responsiveness` · `navigation` · `state` · `structure` · `architecture` · `seam` · `contract` · `schema` · `data` · `content` · `seed` · `performance` · `caching` · `resilience` · `error-handling` · `security` · `auth` · `observability` · `logging` · `testing` · `tooling` · `dependency` · `ops` · `deploy` · `env` · `ci` · `i18n` · `docs`.
 - **`Pin` closes the loop:** the enforced artifact written in this commit, or the named candidate for the `retro` agent to flag. A taste-verified behavior with `Pin: none` and no candidate is a template smell.
 - **Out-of-session entries** (the writing session did not do the work): fill what the diff and conversation evidence support; mark the rest `unknown — committed out-of-session`.

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

@@ -13,6 +13,7 @@ module: billing                                  # optional — single bounded-c
 keywords: [invoice, pdf]                         # required — discovery terms
 status: active                                   # required — active | draft | deprecated
 last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
+type: feature                                    # required tooling key — genre stamp (generator-written or authored; enum = the template names), read by tooling (UI grouping, protected-file mapping); preserve on edits, never narrate
 ---
 ```
 

package/data/harnesses/etna/skills/documentation/templates/implementation-map.md

@@ -0,0 +1,42 @@
+# Implementation Map (docs/operations/implementation-map.md)
+
+Truth document. Use for: **the cold-start execution contract of a project being built from its documented design** — one per repo, at `docs/operations/implementation-map.md`. It is authored by the **executing session at build start**, never generated at design time: build order is derived from the repo's actual feature docs and their stated dependencies, and a design-time prediction of it goes stale the day reality disagrees. It lives in operations because it says *how to proceed*, not *what is true of the design*.
+
+## Writing the map
+
+- **Derive waves from the feature docs** — their stated dependencies plus shared foundations (schema before routes, auth before anything it guards). A wave groups features that can build together; the order reflects foundations, not product importance.
+- **A wave's done criterion is observable** — its plans' verification gates passed, the suite green, a named surface driveable. Never "feels complete".
+- **Authority order names this repo's own docs, most specific wins.** A contradiction between documents is repaired in the owning truth doc *before* code — never reinterpreted while planning.
+- **Plans are records, not an execution queue.** The map points at the active wave's dated plan; historical plans are read only when a truth doc cites them as provenance.
+- **Update in place as waves complete** — the map states the current build position in present tense; the journey lives in the plans and changelog entries.
+
+```
+# {Project} implementation map
+
+## Cold-start contract
+
+{One paragraph: what a fresh session asked to "build this" is expected to do with this
+repository — plan, gate, implement, verify, in what granularity — and the statement that it
+needs nothing outside the repo.}
+
+## Authority order
+
+When documents disagree:
+
+1. {The constitutional docs — guardrails, non-goals, PRD-class documents}
+2. The most specific feature doc under `docs/features/`
+3. {The structural truth docs — domain model, storage schema, API contracts}
+4. The dated plan for the active wave
+5. Owned source files as implementation evidence
+
+## Waves
+
+| Wave | Features | Depends on | Done when |
+| - | - | - | - |
+| 1 | {docs/features/x.md, docs/features/y.md} | — | {observable criterion} |
+| 2 | {…} | 1 | {…} |
+
+## Current position
+
+{One line per wave: complete · in progress ([plan](../history/plans/YYYY-MM-DD-slug.md)) · pending.}
+```