@nurix/etna 0.18.1 → 0.18.3

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

@@ -1,94 +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,128 +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,162 +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                 |

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

@@ -1,285 +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: 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  |
-```
-
----
-
-## 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 |