@nurix/etna 0.18.0 → 0.18.2

package/data/harnesses/code-fable/skills/distiller/references/method.md

@@ -1,166 +0,0 @@
-# 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/code-fable/skills/documentation/SKILL.md

@@ -1,125 +0,0 @@
----
-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 ownership frontmatter (`owns`/`touches`/`depends_on`) 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 **`harness-manager` agent** (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 **`harness-manager` agent**, which calls this skill for each template it scaffolds. Reach here to generate *one* doc from a template; reach for `harness-manager` 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 (routing, memory files, frontmatter `depends_on`, cross-doc links) 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.
-
----
-
-## Decision Tree
-
-```
-User request
-    │
-    ├─ "Baseline/reconcile docs" ──────▶ harness-manager agent (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 in `docs/features/`, generate `owns`, `touches`, `depends_on` frontmatter from the source code the doc describes.
-
-### When to run
-
-- **Baseline audit Step 6** — for every feature doc missing frontmatter
-- **New feature doc** — when creating a doc via the Module Documentation template
-- **Doc update** — when updating an existing feature doc and the frontmatter is missing or the documented scope changed
-
-### How to derive values
-
-**1. Identify `owns` patterns**
-
-Read the feature doc's content. Extract every source file path referenced in the doc (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping other features.
-
-| Doc references | `owns` pattern |
-|---|---|
-| 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 |
-
-Verify patterns match real files — glob each pattern against the codebase. Remove any that match nothing.
-
-**2. Identify `touches` patterns**
-
-From the same source files the doc describes, find imports and calls to code outside the `owns` scope. These are files the feature uses but doesn't own.
-
-Common `touches` candidates:
-- Shared Redux slices the feature reads/writes
-- Utility functions from other modules
-- Shared hooks the feature calls
-- API route files the feature's frontend calls
-
-Keep `touches` to direct dependencies only — not transitive ones.
-
-**3. Identify `depends_on` docs**
-
-Check for explicit cross-references to other docs in `docs/features/` or `docs/architecture/`. Also check if the feature's `touches` paths are `owns`-ed by another feature doc — that doc is a dependency.
-
-### Rules
-
-- Every feature doc must have all three fields, even if empty (`depends_on: []`)
-- 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 gets its own frontmatter — don't duplicate ownership across siblings
-- For baseline audits with 10+ files needing frontmatter, use parallel sub-agents to read and analyze the source files
-
----
-
-## 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, frontmatter, 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/code-fable/skills/documentation/references/examples.md

@@ -1,193 +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: 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                 |