@nurix/etna 0.19.66 → 0.19.68

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

@@ -1,135 +0,0 @@
----
-name: documentation
-description: "Use when creating or substantively editing ANY markdown doc — invoke BEFORE writing. Templates + style authority for technical docs: LLDs, ADs, plans, changelogs, READMEs, runbooks. Owns the tense rule: truth docs state the present; history only in dated records. Baselining is the maintenance agent."
----
-
-# Technical Documentation Skill
-
-**This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
-
-Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
-
----
-
-## Present tense, always
-
-**A document states what is — never how it got there, and never how far along it is.** Write as if the current design had always been the plan. This is the most-violated rule in the skill, so it sits at the top; it applies to every document written or edited through this skill, whatever the template.
-
-| ❌ Strip this | ✅ Write this |
-| --- | --- |
-| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record |
-| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — fix the references; state only the present design |
-| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
-| "was X, now Y", "the old worker", "Phase 2 softened this", "v1 → v2" | The current fact, with no predecessor named |
-
-The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
-
-The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch.
-
----
-
-## The Two Natures
-
-Every document is exactly one of two things. Decide which before writing a word — every rule in this skill derives from the split.
-
-| | **Truth document** | **Record** |
-| --- | --- | --- |
-| States | Absolutes — how the system is, **now** | What happened — a dated account of activity |
-| Named by | Topic: `auth.md`, `AD-003-persistence.md` | Date: `YYYY-MM-DD-slug.md` (or append position) |
-| On change | Body rewritten in place the moment reality changes | Never edited — frozen at completion or append-only |
-| Read to | Act correctly today | Trace provenance, diagnose, audit |
-| Lives in | `docs/features/`, `docs/architecture/`, `docs/operations/`, `docs/tests/`, READMEs | `docs/history/` (plans, changelog, brainstorms, research, migrations), `docs/research/`, `docs/memory/` |
-
-The two guarantees are complementary and both break on mixing: a reader holding a **truth document** must never need history to interpret it; a reader holding a **record** must be able to trust it was never rewritten. So the natures never share a document body.
-
-- **Truth documents never narrate history** — the § Present tense, always rule above, applied to this nature. When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
-- **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
-- **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and `docs/structure.md` ends with the maintenance agent's **Health Log** (tooling-stamped audit rows, the structural cousin of `last-reviewed:`). In both, the body stays current-truth-only; the tail carries the dates. No other truth document carries dated history.
-- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
-
-**No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
-
-**No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
-
----
-
-## Routing
-
-| Request | Route |
-| --- | --- |
-| Baseline / reconcile docs | `maintenance` agent (baseline mode) — it calls this skill per template |
-| Document feature/module (LLD) | [`templates/feature.md`](templates/feature.md) |
-| Document data flow / state / Redux | [`templates/feature.md`](templates/feature.md) — they are sections of the feature doc |
-| Create/update changelog entry | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record — one per unit of work; carries the refinement fields, frozen inside its commit, distilled by the `retro` agent) |
-| Create/update plan | [`templates/plan.md`](templates/plan.md) (record) |
-| Record/revise architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md) — one AD per subject; revisions update it in place |
-| System at a glance | [`templates/system-overview.md`](templates/system-overview.md) |
-| Domain model | [`templates/domain-model.md`](templates/domain-model.md) |
-| Glossary | [`templates/glossary.md`](templates/glossary.md) |
-| Non-goals | [`templates/non-goals.md`](templates/non-goals.md) |
-| Catalog the API surface | [`templates/api-reference.md`](templates/api-reference.md) |
-| Document env vars / config | [`templates/environment-registry.md`](templates/environment-registry.md) |
-| Security / threat model | [`templates/security-overview.md`](templates/security-overview.md) |
-| 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) |
-| Add to protected files | [`templates/protected-files.md`](templates/protected-files.md) |
-| Create/update root README | [`templates/root-readme.md`](templates/root-readme.md) |
-| Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
-| Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
-| Update existing doc | § Editing an existing doc (below) |
-| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md) — not these templates; every-load prose stays lean, and the present-tense rule still applies |
-| Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/architecture/skills/playbook/`, chapters `00`–`10`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
-| **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
-
----
-
-## Editing an existing doc
-
-"Substantive" = anything beyond typo, link, or formatting fixes. On a substantive edit:
-
-1. **Determine the nature first.** A frozen record (a `Status: Complete`/`Abandoned` plan, a changelog entry, an executed runbook) is never edited — write a new dated record that links back.
-2. **Preserve structure, not violations.** Keep the doc's existing section shape, but every section touched sheds history narration, progress markers, and stale tripwires on the way through (§ Present tense, always).
-3. **Stamp and re-derive.** A substantive feature-doc update bumps `last-reviewed:`; if the documented scope moved, update `owns:` ([`references/frontmatter.md`](references/frontmatter.md)).
-
----
-
-## Naming & Lifecycle
-
-| Document | Nature | Name | Lifecycle |
-| --- | --- | --- | --- |
-| Feature (LLD) | Truth | `kebab-case.md` | Living; `status:` `draft` → `active` → `deprecated` |
-| Architecture Decision | Truth | `AD-NNN-kebab-case.md` | Living; `Proposed` → `Accepted` → `Deprecated`; revisions rewrite the body + append to its Decision Changelog |
-| Steering docs (overview, domain model, glossary, non-goals, security, testing strategy) | Truth | fixed names | Living |
-| API reference / environment registry | Truth | fixed names | Living |
-| Operations procedure | Truth | `kebab-case.md` | Living |
-| Protected files | Truth | `protected-files.md` | Living |
-| Plan | Record | `YYYY-MM-DD-kebab-case.md` | Freezes at `Complete` / `Abandoned` |
-| Changelog entry | Record | `YYYY-MM-DD-kebab-case.md` | Frozen; master index append-only |
-| Migration runbook | Record | `YYYY-MM-DD-kebab-case.md` | Freezes once executed, outcome stamped |
-| Research | Record | `history/research/{topic}/` | Frozen snapshot |
-| Memory | Record | `{agent-name}.md` | Append-only dated ledger |
-
----
-
-## Frontmatter Derivation
-
-A feature doc carries ownership frontmatter — `owns:` (required), `module:` (optional), `keywords:` (required), `status:` (required), optional `last-reviewed:`. Deriving it from code and keeping it accurate is [`references/frontmatter.md`](references/frontmatter.md) — every feature-doc create or update, and the `maintenance` agent's baseline pass, route there.
-
----
-
-## Resources
-
-| File | Use For |
-| --- | --- |
-| `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
-| `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
-| `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
-| `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
-| `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
-| `references/examples.md` | Good vs bad documentation examples |
-| `scripts/doc-lint.mjs` | Mechanical checks over written docs (tense narration, dates, stubs, redirects) — run over changed docs before finishing |

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

@@ -1,279 +0,0 @@
-# Documentation Examples
-
-Good vs bad examples showing the key differences.
-
----
-
-## Example 1: Function Documentation
-
-### ❌ Bad: Full Implementation
-
-```markdown
-### mergeData
-
-function mergeData(server, local, changes) { const result = {}; const serverMap = new Map(server.map((i) => [i.id, i])); // ... 30 more lines return result; }
-```
-
-**Problems:** Will become obsolete, focuses on HOW not WHAT.
-
-### ✅ Good: Contract Only
-
-```markdown
-### `mergeData(serverData, localData, changes)`
-
-**Goal:** Merge server data with local changes
-
-**Input:**
-
-- `serverData` (array) - Fresh from API
-- `localData` (array) - Current state
-- `changes` (object) - `{ added, updated, removed }`
-
-**Output:** `{ merged: array, conflicts: array }`
-
-**Merge Rules:**
-
-- Server wins for conflicts
-- Local additions preserved
-- Local removals marked as intent
-```
-
----
-
-## Example 2: State Documentation
-
-### ❌ Bad: State Everywhere
-
-```markdown
-## Component State
-
-const [items, setItems] = useState([]);
-
-## Hook State
-
-{ data: items, isLoading: loading, error: null }
-
-## Redux State
-
-{ items: [], loading: false, error: null }
-```
-
-**Problems:** Documents transient state, repeats shapes.
-
-### ✅ Good: Persistence Points Only
-
-```markdown
-## 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 items = pgTable('items', {
-  id: text('id').primaryKey(),
-  data: jsonb('data'),
-});
-```
-
----
-
-## Example 3: Changelog
-
-### ❌ Bad: Vague
-
-```markdown
-# 2025-01-05 - Updates
-
-## Changes
-
-- Updated editor
-- Fixed bugs
-- Improved performance
-
-## Files
-
-- Various files in src/
-```
-
-### ✅ Good: Function-Level Detail
-
-```markdown
-# 2025-01-05 - Version-Based Merge
-
-## Summary
-
-Replaced change-tracking merge with version-based conflict resolution.
-
-## Changes
-
-### Added
-
-- `mergeAndDerive(server, local, versionsMatch, type)` in `src/utils/merge.js`
-  - Purpose: Single-pass merge with change detection
-  - Returns: `{ merged, changes }`
-
-### Changed
-
-- `useDataSync()` in `src/hooks/useDataSync.js`
-  - Changed: Now compares versions before merge
-
-### Removed
-
-- `deriveChanges()` from `src/utils/derive.js`
-  - Replaced by: Logic in `mergeAndDerive()`
-
-## Breaking Changes
-
-⚠️ **Merge behavior changed**
-
-- Old: Local changes always preserved
-- New: Local preserved only if versions match
-
-## Files Changed
-
-- `src/hooks/useDataSync.js`
-- `src/utils/merge.js`
-- `src/utils/derive.js` (deleted)
-```
-
----
-
-## Example 4: Data Flow
-
-### ❌ Bad: Prose Description
-
-```markdown
-When the page loads, the useAppInit hook calls the syncData function. This function first fetches data from the server using the API. Then it gets the local data from Redux. After that, it compares versions...
-```
-
-### ✅ Good: Diagram + Key Points
-
-```markdown
-## Data Flow
-
-┌─────────────────────────────────────────┐
-│               DATA SYNC                 │
-├─────────────────────────────────────────┤
-│                                         │
-│   ┌──────┐     ┌──────┐     ┌──────┐    │
-│   │Server│────▶│Merge │────▶│Redux │    │
-│   │ API  │     │      │     │Store │    │
-│   └──────┘     └──────┘     └──────┘    │
-│        │                                │
-│        ▼                                │
-│   Version Check                         │
-│                                         │
-└─────────────────────────────────────────┘
-
-**Trigger:** `useAppInit()` on page load
-
-**Version Rule:** Match → local wins, Mismatch → server wins
-```
-
----
-
-## Example 5: Architecture Decision revision
-
-### ❌ Bad: Supersession chain
-
-```
-docs/architecture/decisions/
-├── AD-002-auth-keycloak.md        (status: Superseded)
-├── AD-006-auth-better-auth.md     (status: Superseded, "supersedes AD-002")
-└── AD-011-auth-better-auth-v2.md  (status: Accepted, "supersedes AD-006")
-```
-
-**Problems:** Three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
-
-### ✅ Good: One subject, updated in place
-
-```
-docs/architecture/decisions/
-└── AD-002-auth.md                 (status: Accepted, last-updated bumped)
-```
-
-```markdown
-## Decision
-
-We use Better Auth with one-shot credential issuance…   ← current truth, no journey
-
-…
-
-## Decision Changelog
-
-- 2026-05-02 — Moved issuance to one-shot tokens because refresh-token theft
-  surfaced in review. Implemented by [plan](…). (Previously: long-lived refresh tokens.)
-- 2026-03-18 — Replaced Keycloak with Better Auth because self-hosting cost
-  outweighed SSO needs. Implemented by [plan](…). (Previously: Keycloak.)
-- 2026-01-10 — Initial decision accepted. Implemented by [plan](…).
-```
-
-**Why it works:** The body answers "how does auth work and why" without archaeology; the tail preserves every reversal with its trigger; the rejected alternatives stay findable in the one file a reader actually opens.
-
----
-
-## Example 6: Stripping history from a truth doc
-
-The move agents fumble: deleting narration is only half the job — the story must land in a record.
-
-### ❌ Bad: The journey narrated in place
-
-```markdown
-## Export Pipeline
-
-The exporter was extracted from the legacy `reports` worker (2026-06-02) and
-now lives in `src/export/`. Phases 0–2 of the rewrite are complete; streaming
-output is not yet implemented. Treat any reference to `reports/export.js` as
-stale — it was superseded by `src/export/run.js`.
-```
-
-### ✅ Good: Present-tense truth doc + a dated record carrying the story
-
-The feature doc states only what is:
-
-```markdown
-## Export Pipeline
-
-`src/export/run.js` renders every export format from one job queue. Output is
-buffered per job (streaming is out of scope — see `docs/history/backlog.md`).
-```
-
-And the change-story goes to `docs/history/changelog/2026-06-02-export-extraction.md`:
-
-```markdown
-# 2026-06-02 — Export pipeline extracted
-
-## Summary
-
-Extracted export logic from the `reports` worker into `src/export/`.
-
-## Changes
-
-### Removed
-
-- `reports/export.js` — replaced by `src/export/run.js`; all callers repointed.
-```
-
-**Why it works:** the truth doc needs no archaeology to act on; the dates, the predecessor, and the supersession live in a frozen record; the unbuilt part is a backlog pointer, not a "not yet" hedge; and no stale-reference tripwire survives because the references themselves were fixed.
-
----
-
-## Quick Comparison
-
-| Aspect     | Bad                  | Good                        |
-| ---------- | -------------------- | --------------------------- |
-| Code       | Full implementations | Signatures + contracts      |
-| State      | Every occurrence     | Persistence points only     |
-| Flows      | Prose paragraphs     | ASCII diagrams              |
-| Changelogs | "Updated X"          | Function names + migrations |
-| Decisions  | New doc per revision | One AD per subject, updated in place |
-| History    | Narrated in the doc  | Present-tense doc + dated record |
-| Length     | 100+ lines           | 20-40 lines                 |

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

@@ -1,44 +0,0 @@
-# Frontmatter Derivation — feature-doc ownership
-
-Load when: creating a feature doc, updating one whose documented scope moved, or running a baseline/reconcile pass over many docs.
-
-When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
-
-## When to run
-
-- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New feature doc** — when creating a doc via the [Feature template](../templates/feature.md), project its `owns:` globs
-- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
-
-## 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. `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)
-
-Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
-
-| Doc references                       | Glob                      |
-| ------------------------------------ | ------------------------- |
-| Multiple files under one directory   | `src/feature/**`          |
-| Specific files in a shared directory | List each file explicitly |
-| A single entry-point file            | The exact file path       |
-
-Glob each pattern against the codebase. At `status: active`, drop any that match nothing; at `status: draft`, projected globs may match nothing yet — confirm them against real code when the doc flips to `active`.
-
-**2. `module:`**
-
-The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
-
-**3. `keywords:` & `status:`**
-
-`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
-
-A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
-
-## Rules
-
-- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
-- Use glob patterns for directories, explicit paths for individual files. At `active`, never list paths that don't exist in the codebase; a `draft`'s projected paths are confirmed at `active`.
-- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
-- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.

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

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