@nurix/etna 0.18.10 → 0.18.12

package/data/harnesses/etna/skills/distiller/references/method.md

@@ -0,0 +1,94 @@
+# Distillation Method — the algorithm spec
+
+The shared knowledge root for the `distiller` skill. Every mode reads this file. It carries the four mechanisms the distiller runs, the fact-card format, and the inbox-consumption protocol.
+
+**These methods are stolen, not invented.** Each is sourced to its primary paper with an arXiv id — provenance matters here of all places. Embed them faithfully; do not paraphrase the retention signal away.
+
+---
+
+## The four methods
+
+### 1. Surprisal filter — _what to keep_ (Nemori, arXiv:2508.03341)
+
+Present the LLM with **(a)** a summary of the _current_ fact-set, and **(b)** the new undigested inbox entries. Keep only what is **surprising** relative to (a) — what the existing knowledge would **not** have predicted. Predictable ⇒ dropped.
+
+No importance scores. No emotional tags. No templates. **Prediction error is the only retention signal.**
+
+> **First run, empty fact-set.** With nothing to predict against, "predictable" = mechanical routine. Keep decisions, reversals, discovered constraints, and failures with a cause worth remembering. Drop the rote. (Inbox entries arrive semi-distilled — the `session-reflect` hook already dropped routine work — so most survive this filter; what it still catches is repetition of what the fact-set already knows.)
+
+**Surprisal sources are not only inbox entries.** The inbox is the _default_ stream, but the retention signal is prediction error wherever it lives. On a project whose inbox is thin or empty, the decision record carries the surprise instead: `docs/architecture/adr/**` (each accepted ADR is, by construction, a decision the prior knowledge would not have predicted) and `docs/memory/brainstorm.md` (reversals, owner pronouncements, discovered constraints). Treat these as input (b) alongside any inbox entries; the filter (keep the surprising, drop the predictable) is unchanged. Provenance then points at the ADR file or brainstorm section rather than a session id.
+
+(Independently corroborated by Honcho's "Dream" — same prediction-error retention, arrived at separately.)
+
+### 2. Fact-card representation — _non-lossy EDUs_ (EMem, arXiv:2511.17208)
+
+Each survivor becomes **ONE atomic, self-contained statement** — an Elementary Discourse Unit (EDU). Entity names normalized; the minimal context needed to stand alone baked into the sentence itself. Each card carries **provenance**: the session ids and/or commits it derives from.
+
+This is **decomposition, not summarization.** No information is destroyed; one survivor may decompose into several cards; everything stays auditable back to the session and commits that produced it.
+
+### 3. Reconciliation — _consistency_ (Mem0, arXiv:2504.19413)
+
+For each candidate card, retrieve the existing facts' **semantic neighbors**, then decide one of:
+
+- **ADD** — genuinely new fact; write a new card.
+- **UPDATE** — refines/extends a known fact; edit the existing card in place, extend its provenance.
+- **SUPERSEDE** — contradicts/replaces a known fact; invalidate the old, write the new (see §4).
+- **NOOP** — already known; write nothing.
+
+Neighbor retrieval: `qmd query --format json -c {repo}-facts "<statement>"` (scope with `-c`, one collection) — **only when the `{repo}-facts` collection exists** (`qmd collection list` shows it). The gate is the collection, not the binary: a present qmd whose facts collection has never been built (first run) returns nothing useful. **Fallback when the collection is missing** — qmd absent, _or_ present but `{repo}-facts` not yet built: filename / grep similarity over `docs/memory/facts/*.md` (slug overlap + entity-name grep), and note in the report that reconciliation ran without semantic retrieval.
+
+### 4. Bi-temporal supersession — _never delete_ (Zep/Graphiti, arXiv:2501.13956)
+
+Superseding **never deletes.** On the **old** card, set `invalid_from:` (the date it stopped being true) and `superseded_by:` (the new fact's id), and **leave the file in place.** Write the **new** card with today's `valid_from:`. The old fact stays queryable as history; nothing vanishes.
+
+This is the _valid-time_ axis of a bi-temporal model — a fact is true within `[valid_from, invalid_from)`; transaction time is the git history of the file.
+
+#### Self-contained reversal — _both cards in one pass_
+
+`SUPERSEDE` (§3) assumes the old fact already lives as a card. But a single input can state a reversal whole — "X was decided, then reversed to Y" in one sentence (e.g. brainstorm.md: _single-tenant → multi-tenant, same session_; or an ADR whose **Options Considered** (the `documentation` §10 ADR template's rejected-alternatives section) names a path "proposed and reversed within the brainstorm"). Here there is no pre-existing X card to invalidate — both X and Y arrive together.
+
+Emit **two cards in one pass**:
+
+1. A **born-invalid historical card for X** — the superseded decision. Write it with `valid_from:` (when X was decided, if known, else the input date), `invalid_from:` (when it was reversed — the same date, for an in-session reversal), and `superseded_by:` pointing at Y's fact-id. It is created already carrying its own death so the reversal stays auditable.
+2. A **live card for Y** — the decision that won. `valid_from:` the reversal date, `invalid_from: null`, `superseded_by: null`.
+
+Both share the input's provenance (the one ADR / brainstorm line). This is the ADD-side mirror of SUPERSEDE: SUPERSEDE invalidates a card that already exists; the self-contained reversal _manufactures_ the invalidated card so the abandoned-X history is recorded rather than silently dropped.
+
+---
+
+## Fact-card format (`docs/memory/facts/{kebab-slug}.md`)
+
+```markdown
+---
+id: fact-{slug}
+valid_from: YYYY-MM-DD
+invalid_from: null # set on supersession — never delete the file
+superseded_by: null # fact-id
+entities: [qmd, anchors, maintenance]
+provenance: [session 28b2cd5e, commit abc123]
+---
+
+One atomic, self-contained statement of the fact, entities normalized.
+```
+
+- `id` — `fact-{slug}`, the slug matching the filename.
+- `valid_from` — the date the fact became true (the entry/commit date, or the distill date if no better signal).
+- `invalid_from` — `null` until superseded; then the date it stopped being true. **Never delete the file** to express invalidity — set this field.
+- `superseded_by` — `null`, or the `fact-id` of the card that replaced it.
+- `entities` — normalized names the fact concerns (used by the grep fallback and by retrieval).
+- `provenance` — the session ids (`session <id>`, as stamped on the inbox entry) and commits this card decomposes from. Inbox entries are consumed after digestion, so the session id + commit hashes ARE the audit trail — commits resolve in git; session ids resolve to transcripts while retained. ADR / brainstorm inputs cite their file or section instead.
+- The body — exactly one atomic, self-contained statement. Entities normalized, context baked in, so the card stands alone.
+
+---
+
+## Inbox-consumption protocol (`docs/memory/inbox/`)
+
+Consumption is what makes the distiller idempotent. The inbox (`docs/memory/inbox/{actor}.md`, one file per actor) is a queue: every entry block present is undigested, by definition. There is no separate high-water mark and no `.digest-state.md`.
+
+**Protocol:**
+
+1. **Collect first.** Read every entry block across `docs/memory/inbox/*.md`. Empty inbox ⇒ fall through to the ADR/brainstorm surprisal sources (§1).
+2. Digest the collected entries (filter → decompose → reconcile → write).
+3. **Consume last** — only after every card is written, delete exactly the entry blocks this run digested (keep each file's header; never touch blocks that arrived mid-run). Last, so a crash mid-run leaves entries queued and the re-run re-digests them — reconciliation NOOPs the already-written cards — rather than silently dropping them.
+
+A second run immediately after a successful one finds an empty inbox and is a clean NOOP. ADR/brainstorm inputs are never consumed — reconciliation alone keeps re-runs over them idempotent.

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

@@ -0,0 +1,124 @@
+---
+name: documentation
+description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module, (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, or (10) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc".
+---
+
+# 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. Breaking changes belong in changelogs only, not module docs.
+
+**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.
+
+**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans, ADRs); `docs/memory/` is the agent's dated log and is likewise exempt. A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
+
+---
+
+## Decision Tree
+
+```
+User request
+    │
+    ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
+    │
+    ├─ "Document feature/module" ──────▶ Module Template
+    │
+    ├─ "Create/update changelog" ──────▶ Changelog Template
+    │
+    ├─ "Document data flow" ───────────▶ Module Template (Architecture section)
+    │
+    ├─ "Document Redux/state" ─────────▶ Module Template (State section)
+    │
+    ├─ "Add to protected files" ───────▶ Protected Files Template
+    │
+    ├─ "Record architecture decision" ─▶ ADR Template
+    │
+    ├─ "Create/update root README" ────▶ Project Root README Template
+    │
+    ├─ "Create/update plan" ───────────▶ Plan Template
+    │
+    ├─ "Update existing doc" ──────────▶ Preserve existing structure
+    │
+    └─ No template matches ────────────▶ Co-Authoring Workflow (below)
+```
+
+---
+
+## Naming & Lifecycle
+
+- Features: `kebab-case.md` — living reference, status `Active`
+- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
+- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
+- Memory: `{agent-name}.md` — agent-maintained
+
+---
+
+## Frontmatter Derivation
+
+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/Module template, 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 launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required).
+
+**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; drop any that match nothing.
+
+**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. Don't list paths that don't exist in the codebase.
+- 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.
+
+---
+
+## Co-Authoring Workflow
+
+For docs that don't match templates:
+
+**Stage 1: Context Gathering**
+
+- Ask: Audience? Purpose? Existing format?
+- Have user dump all context, then ask 5-10 clarifying questions
+
+**Stage 2: Structure & Draft**
+
+- Propose section structure, draft section by section
+- User indicates changes (don't edit directly — learn their style)
+
+---
+
+## Resources
+
+| File | Use For |
+| --- | --- |
+| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, protected files, ADR, project root README templates |
+| `references/style-guide.md` | Writing rules, formatting conventions |
+| `references/examples.md` | Good vs bad documentation examples |

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

@@ -0,0 +1,162 @@
+# 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: Deprecated }
+
+**Storage:** localStorage `app_state`
+
+**Backend:** model Item { id String @id data Json }
+```
+
+---
+
+## 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 }`
+
+### Modified
+
+- `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
+```
+
+---
+
+## 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 |
+| Length     | 100+ lines           | 20-40 lines                 |

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

@@ -0,0 +1,308 @@
+# 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: Remove in v3
+}
+```
+````
+
+**Storage:** localStorage key `state_key`
+
+**Backend:**
+
+```sql
+model Table {
+  id   String @id
+  data Json
+  // old String?  // UNUSED: Legacy
+}
+```
+
+````
+
+### Mark Unused Keys
+
+Always comment deprecated/unused fields:
+```json
+{
+  "active": [],
+  // "legacy": {}  // UNUSED: Migrated to newField
+}
+````
+
+---
+
+## ASCII Diagrams
+
+### When to Use
+
+- Data flows
+- System architecture
+- Component interactions
+- Process flows
+
+### 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
+
+---
+
+## 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
+
+---
+
+## 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[]`." |
+| Current limitations | "This hook is not currently integrated into the main flow." |
+| 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  |
+```
+
+---
+
+## Tense & History
+
+**Active docs 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 historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans, ADRs). (`docs/memory/` is the agent's own dated log and is likewise exempt from this rule.)
+
+Strip this language from active docs:
+
+| ❌ Historical narration (belongs in `docs/history/`) | ✅ Present-tense fact (belongs in the active 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`." |
+| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-SOT>.md`" |
+
+Rules:
+
+- **No dates in active docs** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
+- **Cite the ADR for the _why_, never the _when_.** `Provenance: ADR-002` is good (it points to the decision rationale). "Decided in ADR-002 and shipped 2026-06-13" is not.
+- **Routing/index docs point only to current authority docs.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current SOT doc, or drop the row.
+- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the active doc simply becomes correct in present tense.** Never leave the diff narrated in place.
+
+---
+
+## Structure
+
+### Headers
+
+```markdown
+# Document Title (H1 - once)
+
+## Major Section (H2)
+
+### Subsection (H3)
+
+#### Detail (H4 - sparingly)
+```
+
+### 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 all flows             |
+| Code       | Under 15 lines, contracts only  |
+| Voice      | Imperative/active               |
+| Length     | Concise, one line when possible |