@nurix/etna 0.19.66 → 0.19.67

package/data/harnesses/apollo/skills/documentation/references/style-guide.md

@@ -1,384 +0,0 @@
-# Documentation Style Guide
-
-Writing rules for clear, maintainable documentation.
-
----
-
-## Function Documentation
-
-### Signature Format
-
-```markdown
-### `functionName(param1, param2, options)`
-
-**Goal:** One-line purpose
-
-**Input:**
-
-- `param1` (type) - Description
-- `param2` (type, optional) - Description
-
-**Output:** `{ field1, field2 }`
-
-**Side Effects:** State updates, API calls, etc.
-```
-
-### Parameter Rules
-
-- Name + type + one-line purpose
-- Mark optional params with `(type, optional)`
-- Nest object properties:
-  ```markdown
-  - `options` (object) - Configuration
-    - `options.retry` (boolean) - Enable retries
-    - `options.timeout` (number) - Timeout in ms
-  ```
-
-### Return Values
-
-Always specify:
-
-- Type: `Array<Object>`, `boolean`, `{ merged, changes }`
-- Shape for objects/arrays
-- Meaning: "True if sync successful"
-
----
-
-## State Documentation
-
-### When to Document State
-
-✅ Do:
-
-- Redux persistence (localStorage, IndexedDB)
-- Database schemas
-- API request/response shapes
-
-❌ Don't:
-
-- Component-level state
-- Derived/computed state
-- Temporary UI state
-
-### Format
-
-````markdown
-**Frontend (at persistence):**
-
-```json
-{
-  "activeField": "value"
-  // "deprecated": null  // UNUSED: dead key; kept so old persisted state rehydrates
-}
-```
-
-**Storage:** localStorage key `state_key`
-
-**Backend:**
-
-```ts
-export const table = pgTable('table', {
-  id: text('id').primaryKey(),
-  data: jsonb('data'),
-  // old: text('old'),  // UNUSED: dead column; nothing reads it
-});
-```
-````
-
-### Mark Unused Keys
-
-Always comment deprecated/unused fields. The annotation states why the field is dead _now_ — never where it went, what replaced it, or when it will be removed (no "Remove in v3", no "Migrated to newField"; that is history narration, § The Two Natures below):
-
-```json
-{
-  "active": [],
-  // "legacy": {}  // UNUSED: dead key; kept for rehydrate compatibility
-}
-```
-
----
-
-## ASCII Diagrams
-
-### When to Use
-
-- Data flows
-- System architecture
-- Component interactions
-- Process flows
-
-**Docs only.** Diagrams belong in documents read on demand (feature docs, ADs, operations). Instruction files — `CLAUDE.md`, rules, agent definitions, `SKILL.md` prose — never carry them: they load on every turn or every invocation, and a table or a sentence carries the same information at a fraction of the tokens.
-
-### Pattern
-
-```
-┌─────────────────────────────────────────┐
-│              TITLE                       │
-├─────────────────────────────────────────┤
-│                                          │
-│   ┌──────┐     ┌──────┐     ┌──────┐   │
-│   │  A   │────▶│  B   │────▶│  C   │   │
-│   └──────┘     └──────┘     └──────┘   │
-│        │                          │     │
-│        ▼                          ▼     │
-│    Detail                     Detail    │
-│                                          │
-└─────────────────────────────────────────┘
-```
-
-### Characters
-
-- Boxes: `┌─┐│└┘├┤┬┴┼`
-- Arrows: `───▶` `◀───` `│▼` `│▲`
-- Width: ~70 chars max
-
-### UI Wireframes
-
-For screen layouts (not data flows), use these conventions:
-
-```
-**Route:** `path/:id`
-**Tab:** Tab Name
-
-┌────────────────────────────────────┐
-│ Title   [i]3                [Button]│
-│ [i]Label   [Tag1][Tag2][+Add]       │
-└────────────────────────────────────┘
-```
-
-- `[text]` = clickable button/badge
-- `[i]` = icon (followed by label or count)
-- `v` / `^` = expand/collapse indicator
-- Show each UI state (collapsed/expanded) as separate diagrams
-- Include Route/Tab context above wireframe
-
----
-
-## Mermaid Diagrams
-
-**Structure at rest is ASCII; behaviour over time is mermaid.** A file tree, an on-disk layout, a load-class split, a wireframe — draw with box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow — write mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted.
-
-**Docs only**, on the same reasoning as ASCII: a diagram never enters an instruction file.
-
-### When to Use
-
-| Diagram | Use for |
-| --- | --- |
-| `sequenceDiagram` | Who calls whom in what order — a session turn, a hand-off between components |
-| `stateDiagram-v2` | Modes with transitions — a workflow, a record's lifecycle |
-| `flowchart` | A process with branches, gates, or fan-out |
-| `timeline` | A dated lineage, in records only — never in a truth document |
-
-### Rules
-
-- **At most 7 participants and 15 interactions** per diagram. Past that, split it — an unreadable diagram is worse than the prose it replaced.
-- **Labels under 8 words**, no trailing punctuation.
-- **Declare a direction** on every flowchart (`flowchart TD` / `LR`) so the render is stable.
-- **The diagram never carries a fact the prose omits.** It restates structure for a reader who scans; a reader who greps must still find everything in the text.
-- **No styling directives** — no `style`, no `classDef`, no theme overrides. Rendering is the reader's; the source stays portable across GitHub, Obsidian, and a plain editor.
-
-```
-flowchart LR
-  A[Plan approved] --> B{boundary}
-  B -->|BLOCK| C[Re-plan]
-  B -->|PASS| D[testing plan-gate]
-  D --> E[Implement]
-```
-
----
-
-## Code Examples
-
-### Rules
-
-- Under 15 lines
-- Show contracts, not implementations
-- Use pseudocode for algorithms
-
-✅ Good:
-
-```javascript
-// Critical: Balanced brace matching
-function extract(json) {
-  // Track brace depth
-  // Ignore braces inside strings
-  // Return complete objects only
-}
-```
-
-❌ Bad: Full 50-line implementation
-
-(Worked example: [`examples.md`](examples.md) Example 1.)
-
----
-
-## Writing Style
-
-### Voice
-
-Use imperative/active:
-
-- ✅ "Fetches data from server"
-- ✅ "Returns array of objects"
-- ❌ "This function is used to fetch"
-- ❌ "An array is returned"
-
-### When Prose Adds Value
-
-Prose is valuable for context that contracts can't capture:
-
-| Use Prose For | Example |
-| --- | --- |
-| Section intros | "When the editor mounts, `useAppInit` is called with the `appId` from URL." |
-| Non-obvious behavior | "The hook always fetches fresh data. There is no caching or version checking." |
-| Design rationale | "Why parallel fetches? Each entity type is independent, reducing load time." |
-| Edge cases | "If created then deleted before save, it's removed from `added[]` without adding to `removed[]`." |
-| Limitations, stated as facts | "`useAppInit` is standalone — nothing in the mount path calls it." |
-| Usage context | "Used to show 'Unsaved' badge, warn before navigation, enable save buttons." |
-
-### When to Avoid Prose
-
-- Describing WHAT code does (use signatures instead)
-- Step-by-step flows (use diagrams instead)
-- Structured comparisons (use tables instead)
-
-### Conciseness
-
-One line when possible:
-
-- ✅ "Merge server data with local changes using version-based conflict resolution"
-- ❌ "This function takes the data from the server and also takes the local data..."
-
-### Tables
-
-Use for structured info:
-
-```markdown
-| Parameter | Type   | Description    |
-| --------- | ------ | -------------- |
-| `data`    | object | Fresh from API |
-| `local`   | object | Current state  |
-```
-
----
-
-## 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:
-
-**Truth documents describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Three sanctioned exceptions: `docs/memory/` is the agent's own dated ledger; an AD's **Decision Changelog** tail carries that decision's dated revision history; and `docs/structure.md`'s **Health Log** tail carries the maintenance agent's tooling-stamped audit rows. In both tail bridges the body stays current-truth-only — head is truth, tail is provenance.
-
-**Records are never edited to match the present.** A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
-
-Strip this language from truth documents:
-
-| ❌ Historical narration (belongs in a record) | ✅ Present-tense fact (belongs in the truth doc) |
-| --- | --- |
-| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
-| "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
-| "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
-| "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
-| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record; the doc describes what exists |
-| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — delete or repoint the stale references; state only the present design |
-| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
-
-Rules:
-
-- **No dates and no progress narration in truth documents.** Nothing about _when_ something shipped, was verified, folded, or was removed — and no completion markers either: no "phases 0–4 are complete", no per-item `✅ shipped` / `⏳ pending`. Progress tracking is a **record's** job (the plan, the backlog); a truth document describes what exists, as if it had always been so.
-- **No stale-reference tripwires.** Never write "X is gone — treat references to X as stale"; that is a redirect doc compressed into one sentence. Delete or repoint every stale reference instead (same rule as the **No redirect docs** rule in `SKILL.md` § The Two Natures) and state only the present fact.
-- **No version or phase framing.** A bare `v1`/`v2` as a label, "Phase 1/2", "the old X", "supersedes the earlier" — there is one design; describe it without its predecessors. (A version naming an external present-tense fact stays: a schema literal like `design-tokens/v2`, a dependency pin like `@0.14.0`.)
-- **Temporal hedges are progress markers in prose.** "currently", "not yet", "still", "for now" smuggle a ⏳ into a truth document — state the fact without the hedge ("the hook is standalone; nothing in the mount path calls it") and let the backlog record carry the intention.
-- **A published artifact's own version surface is external fact.** Release notes and upgrade guides for a shipped package may use version framing (`v1 → v2`) — that is the artifact's public contract, not the doc narrating its own past. They live beside the artifact or under `docs/operations/`, never in `docs/features/` or `docs/architecture/`.
-- **Cite the AD for the _why_, never the _when_.** `Provenance: AD-002` is good (it points to the decision rationale). "Decided in AD-002 and shipped 2026-06-13" is not.
-- **Routing/index docs point only to truth documents as a topic's authority.** A row whose "read first" target for a topic is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned: that indexes records, it doesn't route a topic.)
-- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the truth document simply becomes correct in present tense.** Never leave the diff narrated in place.
-- **A decision that moves is an edit, not a new document.** Rewrite the AD's affected sections to the new truth and append the revision to its Decision Changelog — never mint a parallel doc and never leave the old choice narrated in the body.
-
-Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Example 6.
-
----
-
-## Mechanics
-
-- Inline-code every identifier, filename, command, and config key.
-- Bullet rules take the form "**bold assertion** — explanation."
-
----
-
-## Structure
-
-### Headers
-
-```markdown
-# Document Title (H1 - once)
-
-## Major Section (H2)
-
-### Subsection (H3)
-
-#### Detail (H4 - sparingly)
-```
-
-**Headings are retrieval keys.** Search and agents retrieve sections out of context, and a bare `## State` reads identically across every feature doc. In long docs, qualify generic headings with the feature name — `## State — invoice-pdf`, `### Merge rules — data sync` — so a section stands alone when retrieved. Short docs whose H1 disambiguates can keep bare headings.
-
-### Standard Layout
-
-```markdown
-# [Title]
-
-**Goal:** One-line purpose
-
-## Architecture
-
-[Diagram + explanation]
-
-## Key Functions
-
-[Signatures and contracts]
-
-## State
-
-[Persistence shapes]
-
-## Files
-
-[Source file list]
-```
-
-### File References
-
-Always end with:
-
-```markdown
-## Files
-
-- `src/path/main.js` - Core logic
-- `src/path/hooks.js` - React hooks
-```
-
----
-
-## Summary
-
-| Aspect     | Rule                            |
-| ---------- | ------------------------------- |
-| Functions  | Always include signatures       |
-| Parameters | Type + purpose                  |
-| Returns    | Type + shape                    |
-| State      | Persistence points only         |
-| Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
-| Code       | Under 15 lines, contracts only  |
-| Voice      | Imperative/active               |
-| Mechanics  | Inline-code identifiers; bold-assertion bullets |
-| Length     | Concise, one line when possible |

package/data/harnesses/apollo/skills/documentation/references/untemplated.md

@@ -1,38 +0,0 @@
-# Writing an Untemplated Document
-
-Load when: no template in [`templates/`](../templates/Readme.md) matches the document being written — a design note, a comparison, an investigation writeup, an index, a reference sheet, anything the Routing table sends to "no template matches".
-
-A template is a pre-made set of shape decisions. With no template, make the same decisions explicitly, in this order.
-
-## 1. Decide the nature — truth or record
-
-Every document is exactly one (`SKILL.md` § The Two Natures). Ask: *when reality changes, is this file rewritten, or is it frozen?*
-
-- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § Present tense, always.
-- Frozen or append-only → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
-
-When a draft wants to be both — the current state *and* the story of getting there — split it: the state becomes a truth document, the story becomes a record that links to it. Never mix the natures in one body.
-
-## 2. Place and name it
-
-- `docs/structure.md` is the placement authority — match the document's topic to its folder map before inventing a location.
-- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift waiting to happen. Link, don't copy.
-- A new topic *folder* gets a `Readme.md` landing page that introduces and indexes it.
-
-## 3. Shape it
-
-- **Open with the goal.** The first line under the H1 states what the document is for and who reads it — a reader (or agent) landing here cold decides in one sentence whether to keep reading.
-- **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
-- **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
-- **Every section earns its place.** No empty stubs — omit what has nothing real to say; write an explicit "None" only where the absence itself is information.
-- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the files.
-
-## 4. Write it in the house style
-
-`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); imperative/active voice; code examples under 15 lines showing contracts, not implementations; ASCII diagrams in docs only; inline-code every identifier, filename, command, and config key.
-
-## 5. With a human in the loop — the co-authoring workflow
-
-**Stage 1 — context gathering.** Ask: audience? purpose? existing format to match? Have the user dump all the context they hold, then ask 5–10 clarifying questions before proposing anything.
-
-**Stage 2 — structure & draft.** Propose the section structure from §1–3 above, then draft section by section. The user indicates changes — learn their style from their edits; don't silently rewrite them.

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

@@ -1,140 +0,0 @@
-// skills/documentation/scripts/doc-lint.mjs - mechanical checks over markdown docs (tense narration, dates, stubs, redirects)
-// Usage: node doc-lint.mjs <file.md ...> | node doc-lint.mjs --changed   (git-changed + untracked .md)
-// Exit 1 when any block-severity finding survives. Escape hatch: <!-- doc-lint-disable: id[, id] --> (file-wide, or on the offending line).
-
-import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
-import { execSync } from 'node:child_process';
-
-const RULES = [
-  { id: 'stale-tripwire', severity: 'block', scope: 'truth', pattern: /treat (any )?[\w`./-]+ ?(references? )?as stale|superseded (by|the)|\bused to (be|target|live|hold)\b/i, message: 'stale-reference tripwire / supersession talk — fix the references, state the present fact' },
-  { id: 'history-narration', severity: 'block', scope: 'truth', pattern: /\bno longer\b|\bwas (renamed|removed|extracted|folded|migrated|replaced)\b|\bmoved (to|from|into) [\w`./-]+ \(?20\d{2}/i, message: 'history narration — the journey belongs in a dated record' },
-  { id: 'progress-marker', severity: 'block', scope: 'truth', pattern: /\bphases?\s+\d[^.\n]{0,40}\b(complete|done)\b|\b(build|implementation) (is )?(\d+%|partially) (complete|done)\b/i, message: 'progress marker — progress lives in the plan/backlog record' },
-  { id: 'temporal-hedge', severity: 'warn', scope: 'truth', pattern: /\bnot yet\b|\bfor now\b|\bcurrently\b|\bstill (unsupported|missing|pending|unimplemented|in progress)\b/i, message: 'temporal hedge — state the fact without "currently / not yet / for now"' },
-  // "previously-fetched" is a hyphenated adjective naming a thing, not a predecessor design — don't fire on it.
-  { id: 'predecessor-frame', severity: 'warn', scope: 'truth', pattern: /\bpreviously\b(?!-)|\bthe old \w+\b|\blegacy \w+ (was|is)\b/i, message: 'predecessor framing — describe the one current design' },
-  // docs/tests/ behavioral checklists use `- [ ]` as test-step notation (step → **Assert**) and docs/operations/
-  // procedures use it for operator verification steps — neither is progress tracking. Every other truth doc still bans checkboxes.
-  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
-  // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
-  // target or a code span is a path, not narration. Strip those before matching.
-  { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`/g, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — only the AD Decision Changelog and structure.md Health Log tails carry dates' },
-];
-
-// 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 RECORD = /(^|\/)docs\/(history|research|memory)\//;
-
-// Classify a path: skipped genre, record, or truth.
-function scopeOf(path) {
-  if (SKIP.test(path)) return 'skip';
-  return RECORD.test(path) ? 'record' : 'truth';
-}
-
-// Yield prose lines only: frontmatter, fenced code blocks, and bridge sections drop out.
-function proseLines(text) {
-  const lines = text.split('\n');
-  const out = [];
-  let inFence = false;
-  let inFrontmatter = lines[0] === '---';
-  let inBridge = false;
-  let bridgeLevel = 0;
-  for (let i = inFrontmatter ? 1 : 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (inFrontmatter) { if (line === '---') inFrontmatter = false; continue; }
-    if (/^\s*(```|~~~|````)/.test(line)) { inFence = !inFence; continue; }
-    if (inFence) continue;
-    const heading = line.match(/^(#{1,4})\s/);
-    if (heading) {
-      if (inBridge && heading[1].length <= bridgeLevel) inBridge = false;
-      if (BRIDGE_HEADINGS.test(line)) { inBridge = true; bridgeLevel = heading[1].length; }
-    }
-    if (!inBridge) out.push({ n: i + 1, line });
-  }
-  return out;
-}
-
-// Collect file-wide disabled rule ids from <!-- doc-lint-disable: a, b --> comments.
-function fileDisables(text) {
-  const ids = new Set();
-  for (const m of text.matchAll(/<!--\s*doc-lint-disable:\s*([\w-,\s]+?)\s*-->/g))
-    m[1].split(',').forEach((id) => ids.add(id.trim()));
-  return ids;
-}
-
-function lintFile(path, findings) {
-  const scope = scopeOf(path);
-  if (scope === 'skip' || !existsSync(path)) return;
-  const text = readFileSync(path, 'utf8');
-  const disabled = fileDisables(text);
-  const lines = proseLines(text);
-
-  const nonEmpty = text.split('\n').filter((l) => l.trim()).length;
-  if (scope === 'truth' && nonEmpty <= 10 && /\b(moved to|relocated to|see [\w`./-]+ instead)\b/i.test(text) && !disabled.has('redirect-doc'))
-    findings.push({ path, n: 1, severity: 'block', id: 'redirect-doc', message: 'redirect stub — delete the file and repoint every inbound link' });
-
-  for (const rule of RULES) {
-    if (rule.scope !== scope || disabled.has(rule.id)) continue;
-    if (rule.exempt && rule.exempt.test(path)) continue;
-    for (const { n, line } of lines) {
-      const subject = rule.strip ? line.replace(rule.strip, '') : line;
-      if (!rule.pattern.test(subject)) continue;
-      if (line.includes(`doc-lint-disable: ${rule.id}`) || new RegExp(`doc-lint-disable:[^>]*\\b${rule.id}\\b`).test(line)) continue;
-      findings.push({ path, n, severity: rule.severity, id: rule.id, message: rule.message, excerpt: line.trim().slice(0, 90) });
-    }
-  }
-
-  // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
-  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:', 'type:'])
-      if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
-  }
-}
-
-// A changed plan whose committed version is already frozen must not be edited.
-function checkFrozenEdits(paths, findings) {
-  for (const path of paths) {
-    if (!/(^|\/)docs\/history\/(plans|changelog|migrations)\//.test(path)) continue;
-    try {
-      const head = execSync(`git show HEAD:"${path}"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
-      if (/(^|\/)plans\//.test(path) && !/Status:\s*(Complete|Abandoned)/i.test(head)) continue;
-      findings.push({ path, n: 1, severity: 'block', id: 'frozen-record-edit', message: 'frozen record modified — records are never edited; write a new dated record that links back' });
-    } catch { /* new file — creating a record is fine */ }
-  }
-}
-
-const args = process.argv.slice(2);
-let files = args.filter((a) => a !== '--changed');
-const changedMode = args.includes('--changed');
-if (changedMode) {
-  const out = execSync('git diff --name-only HEAD -- "*.md"; git ls-files --others --exclude-standard -- "*.md"', { encoding: 'utf8', shell: '/bin/bash' });
-  files = [...new Set([...files, ...out.split('\n').filter(Boolean)])];
-}
-// Expand any directory argument into the .md files beneath it, so `doc-lint.mjs docs/` works.
-function expandDirs(paths) {
-  const out = [];
-  for (const p of paths) {
-    if (!existsSync(p)) { out.push(p); continue; }
-    if (!statSync(p).isDirectory()) { out.push(p); continue; }
-    for (const e of readdirSync(p, { withFileTypes: true })) {
-      if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
-      out.push(...expandDirs([`${p.replace(/\/$/, '')}/${e.name}`]));
-    }
-  }
-  return out;
-}
-files = expandDirs(files).filter((f) => f.endsWith('.md'));
-if (!files.length) { console.error('usage: node doc-lint.mjs <file.md | dir ...> | --changed'); process.exit(2); }
-
-const findings = [];
-files.forEach((f) => lintFile(f, findings));
-if (changedMode) checkFrozenEdits(files.filter((f) => existsSync(f)), findings);
-
-for (const f of findings.sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'block' ? -1 : 1)))
-  console.log(`${f.path}:${f.n} [${f.severity}] ${f.id} — ${f.message}${f.excerpt ? `: "${f.excerpt}"` : ''}`);
-const blocks = findings.filter((f) => f.severity === 'block').length;
-console.log(`\n${findings.length} finding(s), ${blocks} blocking, ${files.length} file(s) checked.`);
-process.exit(blocks ? 1 : 0);

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

@@ -1,35 +0,0 @@
-# Documentation Templates
-
-One file per template. Every template is either a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — the split is defined in `SKILL.md` § The Two Natures, and each template names its nature in its opening line.
-
-| Template | File | Nature |
-| --- | --- | --- |
-| Feature (LLD) | [feature.md](feature.md) | Truth |
-| Architecture Decision (AD) | [architecture-decision.md](architecture-decision.md) | Truth (Decision Changelog tail sanctioned) |
-| System overview | [system-overview.md](system-overview.md) | Truth |
-| Domain model | [domain-model.md](domain-model.md) | Truth |
-| Glossary | [glossary.md](glossary.md) | Truth |
-| Non-goals | [non-goals.md](non-goals.md) | Truth |
-| API reference | [api-reference.md](api-reference.md) | Truth |
-| Environment registry | [environment-registry.md](environment-registry.md) | Truth |
-| Security overview | [security-overview.md](security-overview.md) | Truth |
-| 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 |
-| docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
-| docs/structure.md (authority map) | [structure.md](structure.md) | Truth (Health Log tail sanctioned) |
-| Plan | [plan.md](plan.md) | Record |
-| Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
-| Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
-| Journal | [journal.md](journal.md) | Record (append-only) |
-| CHANGELOG master index | [changelog-index.md](changelog-index.md) | Record index (append-only) |
-| Backlog | [backlog.md](backlog.md) | Record (append-only) |
-| Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
-
-**Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
-
-**Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.

package/data/harnesses/apollo/skills/documentation/templates/api-reference.md

@@ -1,20 +0,0 @@
-# API Reference (docs/architecture/api.md)
-
-Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **index**: request/response shapes stay in the owning feature docs; this doc answers "what exists and where is it documented." If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
-
-Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.
-
-```
-# API Reference
-
-## Conventions
-
-- Base path: `/api/v{N}` · Auth: {scheme} · Envelope: `{ "status": 1, "message": "...", "data": {...} }`
-- Errors: `{ "status": 0, "message": "...", "data": null }` · Codes: 200/201/400/401/403/404/500
-
-## {Resource group}
-
-| Method | Path | Purpose | Auth | Owning doc |
-| ------ | ---- | ------- | ---- | ---------- |
-| GET | `/api/foo` | {one line} | {role} | [feature](../features/{feature}.md) |
-```