@nurix/etna 0.19.66 → 0.19.67

package/data/harnesses/apollo/skills/documentation/templates/architecture-decision.md

@@ -1,121 +0,0 @@
-# Architecture Decision (AD)
-
-Truth document — with the one sanctioned dated tail. Use for: the standing decision on one architectural **subject** — a system shape, a contract, a substrate choice. Lives in `docs/architecture/decisions/`. The body always states the current decision and its current reasoning. When the decision moves, rewrite the affected sections to what is now true, bump `last-updated`, and append the revision to the **Decision Changelog** — the journey lives in that tail, never in the body. Head is truth; tail is provenance.
-
-### One subject per AD
-
-The unit is the subject, not the individual call. "The persistence layer", "auth", "the design-skill architecture" are subjects; every decision, reversal, and re-decision on a subject lands in that subject's one AD, however many times it moves. Write a second AD only when a genuinely separate subject emerges — never to record a revision of an existing one.
-
-### When to write an AD
-
-Write an AD when **all three** apply:
-
-1. The decision is architectural — affects system shape, contracts, or substrate choice, not internal implementation
-2. Alternatives were genuinely considered and rejected
-3. Future maintainers will ask "why is it this way?"
-
-Don't write an AD for:
-
-- Standing principles or style preferences (those are stances, not decisions — put them in `docs/architecture/`)
-- Routine implementation choices with no rejected alternatives
-- Anything you'd be happy reversing without ceremony
-
-### Lifecycle
-
-`Proposed` → `Accepted` → `Deprecated`
-
-Frontmatter `status:` is the single lifecycle source of truth. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
-
-### Naming
-
-`AD-NNN-short-title.md` — three-digit zero-padded number, kebab-case subject. Numbers are assigned sequentially across the project and never reused.
-
-### Structure
-
-Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the AD has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
-
-### Template
-
-```markdown
----
-title: "AD-NNN: Short title in sentence case"
-status: Accepted # Proposed | Accepted | Deprecated
-created: YYYY-MM-DD
-last-updated: YYYY-MM-DD # bump on every revision
-decision-owner: Name
-reviewers: [] # optional
-tags: [ad]
----
-
-# AD-NNN: Short Title
-
-## Decision
-
-[One paragraph, active voice. "We will…" Lead with the answer — the current answer, whatever the journey was.]
-
-## Context
-
-[The forces in play. What is the problem? Why does it need a decision? Technical, political, social, and project-local pressures — stated as present-tense forces, not as a history of the subject.]
-
-## Consequences
-
-**Positive:**
-
-- [What becomes easier]
-
-**Negative:**
-
-- [What becomes harder, what we accept reluctantly]
-
-**Risks:**
-
-- [Second-order effects you can already see, with mitigations if known]
-
-<!-- Optional sections below. Include only when warranted by the decision's weight. -->
-
-## Decision Drivers
-
-[Hard non-negotiables vs. strong levers. Include when alternatives exist and the criteria aren't self-evident from Context.]
-
-## Options Considered
-
-| Option       | Pros | Cons | Outcome               |
-| ------------ | ---- | ---- | --------------------- |
-| **Option A** | …    | …    | **CHOSEN**            |
-| Option B     | …    | …    | Eliminated — [reason] |
-
-## Deep Comparison
-
-[Honest framing of the strongest alternative(s). Include when the table doesn't make the reasoning obvious. State the *real* reason each was rejected — not a strawman.]
-
-## Architecture in Detail
-
-[Diagrams, code shape, layer responsibilities. Include when the decision implies non-trivial structure that readers need to understand alongside the *why*. Execution belongs in a plan doc (`docs/history/plans/`) — link to it, don't embed an implementation plan here.]
-
-## Open Questions
-
-1. **[Question]** — _Default_: [stated default until resolved].
-
-## References
-
-- [External link or cross-reference]
-
-## Decision Changelog
-
-<!-- The provenance tail — append-only, newest first. One entry per revision: what changed, the trigger, the previous choice, and the plan that implemented it. Added on the first revision; the initial acceptance is the last entry. -->
-
-- YYYY-MM-DD — [What changed] because [trigger]. Implemented by [plan link]. (Previously: [old choice].)
-- YYYY-MM-DD — Initial decision accepted. Implemented by [plan link].
-```
-
-### Rules
-
-- **One subject per AD; all its revisions stay inside it.** Two genuinely different subjects means two ADs — a revision of an existing subject never does.
-- **The body is always the current truth.** Rewrite affected sections on every revision; never leave a superseded choice narrated in the body — the Decision Changelog carries the journey, with each entry naming the old choice and the trigger.
-- Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
-- **Consequences lists positives, negatives, AND risks.** Pros-only Consequences is the genre's classic failure — one AD's honest resulting context is the input context for the next.
-- **Options Considered keeps every genuinely rejected alternative with the real reason.** Informed rejections are the most expensive knowledge to lose; a rejection made with strong prior art in view says so explicitly.
-- **Keep it short — one to two pages.** Long decision docs don't get updated. How-it-works detail belongs in the owning feature doc; execution in a plan. Link, don't embed.
-- No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything.
-- Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body.
-- The Decision Changelog is append-only, newest first. Typo and formatting fixes don't get entries.

package/data/harnesses/apollo/skills/documentation/templates/backlog.md

@@ -1,33 +0,0 @@
-# Scaffold: docs/history/backlog.md
-
-Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/backlog.md`.
-
-```
-# Backlog
-
-Tracked work items, technical debt, and planned improvements. Append new items under the appropriate priority.
-
----
-
-## Format
-
-- **[P0]** Description — discovered by [plan-name or agent-name]
-
----
-
-## P0 — Critical
-
-{items here}
-
-## P1 — High
-
-{items here}
-
-## P2 — Medium
-
-{items here}
-
-## P3 — Low
-
-{items here}
-```

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

@@ -1,81 +0,0 @@
-# Behavioral Checklist (docs/tests/{feature}.md)
-
-Truth document. Use for: **how to verify one feature's promised behavior by driving the real product** — the browser, the CLI binary, HTTP against the running service. One file per feature, named for the feature doc that owns the code (`docs/features/auth.md` → `docs/tests/auth.md`). No frontmatter; a checklist owns no code.
-
-**This is the driving script, and it is the source the suite is drawn from.** At the verification gate it does double duty: rung 1 drives the real surface *against these steps*, and rung 2 pins the durable subset *of these assertions* as suite tests. Writing it is therefore not a report written afterwards — it is authored or updated **before** the driving, so the gate has something to execute and the tests have something to be derived from. Which assertions earn a permanent test is decided by `verification.md` § What earns a durable test, and each section records the answer on its `Pinned:` line.
-
-A checklist outlives the tests it seeds. Where a Playwright script breaks on every selector change, a checklist states the behavior and lets the implementation move under it — so it is written in the product's own vocabulary (labels, URLs, rows) and never in the code's (function names, props, internal state).
-
-Required: **Conventions**, at least one numbered behavior section, **Failure Report**. Optional: Test Inputs, Wait Strategy, Driving notes — include only when they carry real content.
-
-## Writing the assertions
-
-- **A section is one behavior, its heading stated as a fact** — `3. A stale pointer falls back to the sole membership`, not `3. Test the resolver`. The heading is the promise; the steps are how you see it.
-- **A step is an action; an `**Assert**` is the observable it must produce.** Interleave them in the order a person meets them, so the file reads as a session rather than a spec.
-- **Assert what is observable, at the altitude a user meets it** — a visible label, a URL, a toast, a row in the database, a response envelope. Never a private function's return value: that is a unit test's job, and stating it here couples the checklist to code that will move.
-- **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.
-
-```
-# {Feature} Test Plan
-
-{What this covers, and what neighbouring checklists cover instead, with links. Close with:}
-Each step is an action; each **Assert** is the observable it must produce.
-
-## Test Inputs
-
-- **URL / entry point** — where the run starts
-- **Identity** — the account or role required, and how it is obtained
-- **State** — the fixture or seeded state the run assumes, stated as counts a reader can check
-
-## Conventions
-
-- {The invariants a reader needs to interpret the assertions — the vocabulary, the scoping rule,
-  the guarantee that makes a surprising assertion correct. Not a restatement of the LLD.}
-
----
-
-### 1. {The behavior, stated as a fact}
-
-- [ ] {action}
-- [ ] **Assert**: {the observable, with exact literals}
-- [ ] **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}
-
-- [ ] {action}
-- [ ] **Assert**: {observable}
-
-> Pinned: {…}
-
----
-
-## Wait Strategy
-
-State-based signals, never fixed sleeps:
-
-- **{Milestone}** — {the signal that proves it, as a selector or an observable}
-
-Timeouts: {operation} **{n}s**.
-
-## Driving notes
-
-- {Hard-won facts about driving this surface that cost someone an hour — an environment trap, a
-  harness quirk, a signal that lies. Not general advice.}
-
-## Failure Report
-
-For each failed step, capture:
-
-- Section and step name, and the expected signal
-- The URL or command at the time of failure
-- The state assertion's actual value, where the step checks one
-- Any visible error, toast, or console exception
-- A screenshot or transcript
-```

package/data/harnesses/apollo/skills/documentation/templates/bookkeeping.md

@@ -1,18 +0,0 @@
-# Bookkeeping ledger (docs/operations/bookkeeping.md)
-
-Truth document with an unusual lifecycle: a **work queue**, not an archive. Rows are appended mechanically by the awareness hook (`auto:`) and deliberately by working sessions (`note:`), drained by the `bookkeeper` agent, and walled at Stop and commit — a commit is possible only when every row is resolved (deleted) or converted to `waived:`. What survives in git — `waived:` and `needs-session:` rows — is exactly what a PR reviewer should see.
-
-The row grammar is machine-read by the hooks and CI; keep it exact. A `waived:` row's `expires=` date is enforced: CI honors the waiver until the date, then fails. `waived:` rows whose finding kind is `dead-glob` double as the dead-glob allowlist.
-
-```
-# Bookkeeping
-
-The shared work queue keeping documentation and code in sync — a queue, never an archive. Rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is either **resolved, which deletes it**, or converted to `waived:`. A drained row leaves no trace here; what it closed is recorded in the doc it corrected, and git history holds the row itself. Row grammar and lifecycle: the `documentation` skill's `templates/bookkeeping.md`. A `waived:` row carries `expires=` and is PR-reviewable history.
-
-- auto: YYYY-MM-DD · {finding-kind} · {description} → {action} | sid={session_id} tp={transcript_path} ts={ISO}
-- note: YYYY-MM-DD · {area} · {one-line context only the session holds} → lands-in: {owning doc | backlog | memory} | sid=… tp=… ts=…
-- needs-session: YYYY-MM-DD · {what the bookkeeper could not ground} → main session resolves | refs={original row ts}
-- waived: YYYY-MM-DD · {what is deferred} · reason: {why} → expires=YYYY-MM-DD
-```
-
-Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `index-row-missing` · `boundary-scan-suggested` · `doc-placement`.

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

@@ -1,57 +0,0 @@
-# Changelog Entry
-
-Record. Use for: the per-unit-of-work journal of what changed and how it was refined — one file per entry under `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, written by whoever does the work and frozen inside the commit it describes. The three words name the work, not the commit. Trigger and lifecycle policy: the `changelog` rule; distillation is the `retro` agent.
-
-An entry is not a summary line. Its value concentrates in the fields a diff cannot reconstruct — the ask in the user's own words, what was rejected, which skills survived or were overridden, what running the thing taught.
-
-## Entry format
-
-```
-# {YYYY-MM-DD} · {surface} — {one-line outcome}
-
-**Plan:** [history/plans/YYYY-MM-DD-slug.md](../plans/YYYY-MM-DD-slug.md)
-**Commits:** {sha}, {sha}
-
-- **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. 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} [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}
-```
-
-`**Plan:**` appears only on plan-linked entries. `**Commits:**` appears only when one entry covers several commits, and lists the predecessors — an entry can never carry its own commit's SHA.
-
-## Lifecycle
-
-| State | Meaning |
-| --- | --- |
-| **Draft** | Created before its commit exists — typically the moment a plan reaches `Status: Complete`. Mutable; fields filled as far as the session can |
-| **Complete** | Missing fields filled in from the diff and the session |
-| **Frozen** | The moment it rides in a commit. Never edited, renumbered, or reconciled |
-
-**Immutability begins at commit, not at creation.** A draft in the working tree is meant to be edited; that is what lets a completed plan capture its context before anything is committed. A committed entry is history — a correction is a new entry that links back. Entries are exempt from doc-health passes by genre: they are history and can never be "wrong".
-
-## Field rules
-
-- **Every field present; "none" stated explicitly.** An absent field is a template violation. Sessions assert success by default — the required `rejected:` and `overridden` entries are the counterweight; an honestly empty failure field is information too.
-- **`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. **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`.
-
-## Granularity
-
-A commit is the smallest unit an entry may describe. Above that the mapping is judgment — four commits may be four entries or one. When the work exceeds what a draft describes, write a **second** entry rather than stretching the first: the plan-linked entry stays an honest account of the plan.
-
-## The index
-
-Every entry appends one row to `docs/history/CHANGELOG.md` — date, link, one-line summary — in the same pass that writes the entry.
-
-## Exemptions (closed list)
-
-No entry for: release and bot commits, harness installs and bumps, lockfile-only changes, pure renames and moves, and changelog housekeeping itself. Everything else gets an entry, however short.

package/data/harnesses/apollo/skills/documentation/templates/changelog-index.md

@@ -1,41 +0,0 @@
-# Scaffold: docs/history/CHANGELOG.md
-
-Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/CHANGELOG.md`.
-
-```
-# Changelog
-
-All notable changes to {Project Name} will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
-
----
-
-## [Unreleased]
-
-{entries added here as work proceeds; promoting them under a release heading is the one sanctioned edit to this index — the dated entry files themselves stay frozen}
-
----
-
-## Links
-
-- [Setup Guide](../operations/setup.md)
-- [Architecture](../architecture/)
-
----
-
-## How to Update This Changelog
-
-1. Create a dated change file in `docs/history/changelog/`:
-   `docs/history/changelog/YYYY-MM-DD-feature-name.md`
-
-2. Update this CHANGELOG.md with a high-level summary linking to the detail file
-
-3. Follow Keep a Changelog categories:
-   - **Added** for new features
-   - **Changed** for changes in existing functionality
-   - **Deprecated** for soon-to-be removed features
-   - **Removed** for now removed features
-   - **Fixed** for bug fixes
-   - **Security** for security improvements
-```

package/data/harnesses/apollo/skills/documentation/templates/docs-readme.md

@@ -1,72 +0,0 @@
-# docs/README.md (Documentation Root)
-
-Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
-
-**Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.
-
-```
-# {Project Name} Documentation
-
-Technical documentation for {project description}.
-
-> For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.
-
----
-
-## Quick Links
-
-| Document                          | Description                          |
-| --------------------------------- | ------------------------------------ |
-| [Structure](structure.md)         | Documentation entry point and rules  |
-| [Setup](operations/setup.md)      | Installation and configuration guide |
-
----
-
-## Architecture
-
-System design, steering docs, and standing decisions — the truth layer.
-
-- [system-design.md](architecture/system-design.md) - System overview: subsystems and key flows
-- [domain-model.md](architecture/domain-model.md) - Entities, relationships, state ownership
-- [glossary.md](architecture/glossary.md) - Project vocabulary
-- [non-goals.md](architecture/non-goals.md) - What this system deliberately does not do
-- [decisions/](architecture/decisions/Readme.md) - Architecture Decisions (ADs)
-{list other architecture docs — api.md, security.md — when present}
-
----
-
-## Features
-
-Living reference docs for implemented features (how things currently work).
-
-- [feature-name.md](features/feature-name.md) - Feature description
-{list all feature docs}
-
----
-
-## Operations
-
-How to run, develop, and deploy.
-
-- [setup.md](operations/setup.md) - Installation and configuration guide
-{list all operations docs — environment.md when present}
-
----
-
-## History
-
-The records — everything dated, frozen, or append-only.
-
-- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
-- [changelog/](history/changelog/) - Individual changelog entries
-- [plans/](history/plans/) - Implementation plans (frozen at completion)
-- [migrations/](history/migrations/) - One-shot migration runbooks (frozen once executed)
-- [research/](history/research/) - Deep-research artifacts (one folder per topic)
-- [backlog.md](history/backlog.md) - Tracked work items and technical debt
-
----
-
-## Contributing
-
-See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
-```

package/data/harnesses/apollo/skills/documentation/templates/domain-model.md

@@ -1,30 +0,0 @@
-# Domain Model (docs/architecture/domain-model.md)
-
-Truth document. Use for: the entities the system is about — what they are, how they relate, and who owns their state. The vocabulary here must match the glossary and the code; when they disagree, fix the disagreement, don't document around it.
-
-Required: **Entities**, **Relationships**. Optional: Lifecycle states, Invariants.
-
-```
-# Domain Model
-
-## Entities
-
-| Entity | What it is | State lives in |
-| ------ | ---------- | -------------- |
-| {Entity} | {one line} | {table / slice / service} |
-
-## Relationships
-
-- {EntityA} 1—N {EntityB} — {the meaning of the link}
-- {EntityB} N—N {EntityC} via {join} — {meaning}
-
-## Lifecycle states
-
-{Only for entities with real state machines.}
-
-- **{Entity}**: draft → active → archived — {what moves it between states}
-
-## Invariants
-
-- {A relationship or state rule that must always hold, stated as a constraint}
-```

package/data/harnesses/apollo/skills/documentation/templates/environment-registry.md

@@ -1,15 +0,0 @@
-# Environment Registry (docs/operations/environment.md)
-
-Truth document. Use for: the config surface — every variable the code reads, in one table. `.env.example` mirrors this doc's variable list.
-
-**Placeholders only, never real values.** A real-looking password, account ID, or personal profile name in a doc is a leak, and one developer's local setup written as the canonical value is a trap for everyone else. Values in this doc are `{placeholder}` descriptions.
-
-```
-# Environment Registry
-
-Every variable the code reads. `.env.example` mirrors this list.
-
-| Variable | Purpose | Required | Where set | Secret |
-| -------- | ------- | -------- | --------- | ------ |
-| `DATABASE_URL` | {one line} | yes / default: `{value}` | local `.env` / CI / prod | yes |
-```

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

@@ -1,150 +0,0 @@
-# Feature Documentation — the LLD (docs/features/{feature}.md)
-
-Truth document. Use for: every feature in `docs/features/`. The feature doc is the feature's **LLD (low-level design)**: the same file persists from design (Status: Draft, written in LLD Mode) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap. The body always describes the feature as it currently is; the journey lives in the linked plan and changelog entries.
-
-**Required vs optional.** Required in every feature doc: the frontmatter, **Goal**, and **Background** — plus **Files** once implementation exists (a Draft for unbuilt code has no real paths to list) and **Current Behavior** once research or implementation exists (at Draft it's the pre-feature baseline; at Active it's how the feature works today). Every other section is optional: include it only when the feature has something real to put in it (no Redux → no Redux section; no risks worth naming → no Risks section). A **minimal form** is sanctioned for small features: frontmatter + Goal + a short how-it-works section + Files. A two-screen doc that is accurate beats a full-template doc with empty sections.
-
-The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to the `lld-mode` agent's return shape. The orchestrator drops its findings into those slots without restructuring.
-
-```yaml
----
-owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs this doc owns (the only ownership key)
-module: billing                                  # optional — single bounded-context label; omit if cross-cutting
-keywords: [invoice, pdf]                         # required — discovery terms
-status: active                                   # required — active | draft | deprecated
-last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
-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
----
-```
-
-> Declare the code paths it owns in its `owns:` frontmatter — projected at Draft, confirmed against real code at Active.
-
-```
-# {Feature Name}
-
-<!-- Lifecycle lives in the frontmatter `status:` key (active | draft | deprecated) — the single source of truth. Don't restate it in the body. -->
-**Plan:** [history/plans/YYYY-MM-DD-feature-name.md](../history/plans/YYYY-MM-DD-feature-name.md)   <!-- added once a plan exists -->
-
-## Goal
-
-One sentence. What this feature accomplishes, in user-facing terms.
-
-## Goals & Non-Goals
-
-**In scope**
-- Bullet 1
-- Bullet 2
-
-**Out of scope**
-- Bullet 1
-
-## Background
-
-Why this feature exists. The user need, the business trigger, the constraint that pushed it above the line. One paragraph.
-
-(For Product-level work, also include: problem statement, key hypotheses, open questions.)
-
-## Approach
-
-High-level shape of the solution. ASCII diagram if it helps. Implementation specifics belong in the plan.
-
-## Affected Modules
-
-(From lld-mode research) Files, routes, components, slices this feature involves. Group by module.
-
-| Module | Path | Role in this feature |
-|--------|------|----------------------|
-
-## Conventions to Follow
-
-(From lld-mode research) Naming patterns, structural patterns, doc-fit heuristics confirmed for the area being touched. Cite the source file(s) where the convention is established.
-
-## Current Behavior
-
-(From lld-mode research) How the relevant part of the system works *today*, before this feature lands. Without this baseline the design intent is hard to evaluate.
-
-## Ownership Conflicts
-
-(From lld-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
-
-| Conflicting doc | Overlapping path(s) | Resolution |
-|-----------------|---------------------|------------|
-
-## Architecture
-
-[ASCII diagram. Fill once implementation lands. See style-guide.md for box-drawing patterns.]
-
-## Key Functions
-
-### `functionName(param1, param2)`
-**Goal:** What it accomplishes
-**Input:**
-- `param1` (type) - Description
-- `param2` (type) - Description
-**Output:** Return type and shape
-**Side Effects:** DB writes, API calls, state updates
-
-### `hookName(config)`
-**Goal:** What it provides
-**Returns:** `{ data, loading, error }`
-**Triggers:** On mount, on change, manual
-
-## State
-
-**Frontend (at persistence):**
-{
-  "data": [],
-  "changes": { "added": [], "updated": [], "removed": [] }
-  // "cache": {}  // UNUSED: dead key; kept so old persisted state rehydrates
-}
-
-**Storage:** localStorage `app_state`
-
-**Backend:**
-export const resources = pgTable('resources', {
-  id: text('id').primaryKey(),
-  data: jsonb('data'),
-  // oldField: text('old_field'),  // UNUSED: dead column; nothing reads it
-});
-
-**API Shape:**
-{ "status": 1, "data": {...} }
-
-## Redux (if applicable)
-
-**Slice:** `sliceName`
-
-**Actions:**
-- `setData(payload)` - Replace all data
-- `upsertItem(item)` - Add or update single item
-
-**Selectors:**
-- `selectAll(state)` → `Array<Item>`
-- `selectById(state, id)` → `Item | undefined`
-
-## Files
-
-- `src/path/to/main.js` - Core logic
-- `src/path/to/hooks.js` - React hooks
-
-## Open Questions
-
-- Question — who decides, by when
-- (Resolved questions: fold the resolution into Background.)
-
-## Risks
-
-- Risk — likelihood / impact / mitigation
-```
-
-### Section evolution
-
-Sections fill in across the feature's lifecycle. No template swap — they accumulate in place.
-
-| When | Sections written | Source |
-| --- | --- | --- |
-| Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
-| Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | lld-mode agent |
-| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `owns:` globs confirmed against real code | Main agent (from actual code) |
-
-Resolved Open Questions can be summarized into Background; unresolved ones stay visible.

package/data/harnesses/apollo/skills/documentation/templates/glossary.md

@@ -1,11 +0,0 @@
-# Glossary (docs/architecture/glossary.md)
-
-Truth document. Use for: the project's vocabulary — one name per concept, one line per name. Alphabetical. When the code uses a different name than the docs, record it in **In code** so readers can bridge; one concept never gets two doc names.
-
-```
-# Glossary
-
-| Term | Meaning | In code |
-| ---- | ------- | ------- |
-| {Term} | {one-line definition} | `{identifier}` |
-```