demiurge-chiron 0.2.0

package/CLAUDE.md

@@ -0,0 +1,34 @@
+# CHIRON companion guide (for AI agents helping a human set up or use CHIRON)
+
+You are reading this because a human opened their agent in the CHIRON repo and asked for help. Walk them through ONE step at a time. Explain before doing. Never pressure an optional step.
+
+## What CHIRON is (tell them in one line)
+
+Every correction they make to an agent becomes a permanent rule, compiled into every agent's memory file, so the same mistake never happens twice.
+
+## Setup, conversationally
+
+1. **Check state first:** run `chiron setup` in their project and read the output to them in plain language. It detects what is done and what is missing and changes nothing.
+2. **If no ledger:** explain that the ledger (`.chiron/ledger.md`) is where rules live, git-diffable. Then run `chiron init`.
+3. **First rule:** ask if there is a correction they keep repeating to their agents. Distill it with them into Mistake / Rule / Apply (one sentence each), then run `chiron add`. If the CLI reports a duplicate or contradiction, show them what it said; the gates exist to keep their rule set clean.
+4. **Compile:** explain that rules only work when agents read them at session start. Show the dry-run first (`chiron compile`), let them see the plan, then `chiron compile --apply`. Their own file content outside the managed markers is never touched.
+5. **Optional, live hook:** explain honestly: it reads each prompt locally and adds one line of context nudging the agent to capture a rule in two cases, when the prompt looks like a correction, or when HORKOS (if installed) caught a false-completion or evidence gap this session (its `caught` counter grew). It fires once per new catch, never blocks, and sends nothing anywhere. If they want it, add to `~/.claude/settings.json` under `hooks.UserPromptSubmit`: `node <repo>/hooks/chiron-hook.js`. If they decline, they lose nothing except automation; `/chiron capture` and `chiron mine` still work.
+6. **Optional, mine history:** `chiron mine` sweeps their past transcripts read-only for corrections they already paid for and never captured. Offer to review the candidates with them (skill Mode B). Expect false positives; discard freely.
+7. **Skill install (if not done):** copy `skill/` to `~/.claude/skills/chiron` so capture works conversationally.
+
+## Story, not setup
+
+The author wires CHIRON into a broader discipline stack (HORKOS audits actions, HYPNOS consolidates memory). That is how WE use it; none of it is required. CHIRON alone is complete.
+
+## Day-to-day use (tell them once)
+
+- They correct their agent -> agent offers to capture (hook) or they say "capture that" (skill).
+- `chiron check` any time: health, duplicates, contradictions, drift.
+- `chiron promote` when a rule proves itself across projects.
+- Retire with `chiron archive <id>`; nothing is ever deleted, `chiron restore` brings rules back.
+
+<!-- chiron:begin (managed by CHIRON, do not edit inside) -->
+## Rules learned from corrections (CHIRON)
+
+- **CHI-R001:** When writing a banned-character lint, spell the banned characters as backslash-u escape sequences in the lint source so it never matches itself
+<!-- chiron:end -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Jun Ying
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+<div align="center">
+
+![Chiron the centaur teaching a rule](assets/hero.png)
+
+# CHIRON: Corrections Harvested Into Rules, Obeyed Next-session
+
+*You corrected your AI agent Tuesday. It forgot by Thursday. I make the correction stick, in Claude Code, Cursor, and every agent at once.*
+
+**The self-improving loop for AI agents. Correct once, never twice.**
+
+![license](https://img.shields.io/badge/license-MIT-E8A23D)
+![node](https://img.shields.io/badge/node-%E2%89%A518-2C7A7B)
+![benchmarks](https://img.shields.io/badge/benchmarks-35%2F35-E8A23D)
+![zero deps](https://img.shields.io/badge/dependencies-0-2C7A7B)
+![cross-agent](https://img.shields.io/badge/cross--agent-yes-D64933)
+
+</div>
+
+**I am Chiron. I trained Achilles.** Also Asclepius, who became medicine, and Jason, who sailed for the Fleece. I never once swung a sword for them. My work was quieter and it lasted longer: a hero learns a thing wrong, I correct it, and the hero never gets it wrong again. That is the whole art of teaching, and it is exactly what your agent lacks. Your agent is bright and it is tireless and it has no memory of yesterday's lesson. So you teach it the same thing Tuesday, Thursday, and again next month in a different editor. I am here to end that. Correct me once. I will not make you do it twice.
+
+**One correction becomes a permanent rule, compiled into every agent's memory.** Deterministic gates, zero LLM in the capture path, 35 benchmarks you can rerun in seconds.
+
+## Before / after
+
+**Without CHIRON** (every AI agent user, every week):
+
+> Tuesday: "no, use `py` not `python` on Windows." Agent: "You're right, my mistake."
+> Thursday, new session: agent runs `python`. It has no idea Tuesday happened.
+> Next month, in Cursor: same mistake. Different agent, same you, same correction, third time.
+
+**With CHIRON:**
+
+```
+> chiron add --mistake "ran python on Windows, hit the Store stub" \
+    --rule "Use py, not python or python3, on Windows" \
+    --how "py -c ... for inline, py script.py for files"
+Captured CHI-R007. Compile it into your agents: chiron compile --apply
+
+> chiron compile --apply
+WROTE claude:   CLAUDE.md
+WROTE agentsmd: AGENTS.md
+WROTE cursor:   .cursor/rules/chiron.mdc
+WROTE windsurf: .windsurf/rules/chiron.md
+```
+
+One correction. Four agents. Every future session. The ledger is git-diffable markdown; run `git diff` and watch the rule land everywhere at once.
+
+## Why the incumbents miss it
+
+| | Claude auto-memory | Cursor Rules / Windsurf Memories | CHIRON |
+|---|---|---|---|
+| Captures corrections | automatically, invisibly, unreviewed | manually, per editor | as three-line rules you approve, gated by dedup and contradiction checks |
+| Reach | Claude only | that one editor only | compiled into Claude Code, Cursor, Windsurf, and AGENTS.md at once |
+| Your past sessions | forgotten | forgotten | mined: `chiron mine` recovers corrections you already paid for |
+
+A lesson that lives in one editor is a lesson you get to teach again in the next one. I do not train a hero to fight only on Tuesdays.
+
+## Not for you if
+
+- You work in exactly one agent and its native rules file is enough. CHIRON earns its keep at two agents and up.
+- You want fully automatic memory with no review step. Claude auto-memory does that; you just never get to see what it learned.
+- You expect semantic "these two rules mean the same thing" merging. CHIRON's gates are deterministic on purpose; the judgment calls stay yours.
+
+## How it works
+
+1. **Capture.** A correction becomes a three-line rule (Mistake / Rule / Apply), but only once its cause is verified, never from a first-guess diagnosis, because a rule outlives the mistake that spawned it; a repeated lesson bumps a counter instead of duplicating. Attach a multi-line `--detail` note for the full technical story, and tag a discovery you hit yourself (not a user correction) with `--type gotcha`. A failure-class tag in `--source` (scope, evidence, adversarial, verify, report) turns the ledger into a defect map: the class that accumulates the most rules is the discipline to harden next.
+2. **Compile.** Active corrections land inside managed markers in CLAUDE.md, AGENTS.md, `.cursor/rules/*.mdc`, and Windsurf rules. Your own content is never touched; dry-run by default. `gotcha` entries stay in the ledger as a searchable, deduped, git-diffable technical journal (the role a hand-kept lessons file used to fill) and never bloat the agent files.
+3. **Mine.** `chiron mine` sweeps your past Claude Code and Codex transcripts for corrections you never captured. Read-only, zero LLM.
+4. **Govern.** Duplicates surfaced, contradictions ASKED (never auto-resolved), cross-project rules proposed for your global ledger, health score 0 to 100.
+5. **Archive, never delete.** Retired rules get a dated archive and an append-only changelog; `chiron restore` brings any rule back, forever.
+
+Optional live hook (ships dormant): a one-line nudge to capture a rule the moment you type a correction, or the moment HORKOS (if installed) catches a false-completion this session.
+
+## Install for your agent
+
+> **From npm:** `npm install -g demiurge-chiron`, then `chiron init` and `chiron compile --apply` — or `npx demiurge-chiron init` with no install. (The capture skill still ships in the repo; clone to copy it.) Source build below.
+
+CHIRON compiles rules into the files each agent already reads at session start. Install the CLI once, then compile wherever you work.
+
+**Windows PowerShell:**
+```powershell
+git clone https://github.com/eragonlonelyboy-lab/chiron.git; cd chiron; npm link
+Copy-Item -Recurse skill "$env:USERPROFILE\.claude\skills\chiron"
+```
+
+**macOS / Linux:**
+```bash
+git clone https://github.com/eragonlonelyboy-lab/chiron.git && cd chiron && npm link
+cp -r skill ~/.claude/skills/chiron
+```
+
+Node 18+, zero dependencies. Then in any project: `chiron init` creates the ledger, `chiron compile --apply` writes the rules into your agents.
+
+**Where the rules land, honestly.** `chiron compile` writes to the instruction files each agent reads natively:
+
+| Agent | File CHIRON writes | Note |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | managed markers, your content untouched |
+| Codex, Copilot, OpenCode, Amp, Devin, Cursor, Kiro, Cline, and ~7 more | `AGENTS.md` | read natively by ~15 agents; one file, most reach |
+| Cursor | `.cursor/rules/*.mdc` | `.mdc` frontmatter emitted correctly |
+| Windsurf | `.windsurf/rules/` | respects the 12k workspace / 6k global caps; fails loud if a rule set overflows |
+| Cline | `.clinerules/` | rules file, cross-platform |
+| Kiro | `.kiro/steering/` | steering doc |
+
+The root `AGENTS.md` anchor is the big lever: one file, read natively by about fifteen agents (add a one-line `@AGENTS.md` import for Claude Code, a `context.fileName` line for Gemini CLI, and the reach widens further). The **capture skill** (`/chiron capture`, "capture that") runs on skill-capable hosts: Claude Code, Codex, Cursor, OpenCode, Kiro, Cline, and the rest of the skill roster. Everywhere else, the CLI captures and compiles just the same.
+
+## Benchmarks
+
+Reproducible, seeded, no network: `node benchmarks/run.js`
+
+| Suite | Result |
+|---|---|
+| Ledger round-trip, dedup, contradiction (zero auto-fix asserted) | pass |
+| Compiler: surgical markers, idempotent, .mdc frontmatter, Windsurf cap fails loud | pass |
+| Mining: planted-correction detection | 6/6 detected, 0 noise hits |
+| Promote-to-global: cross-project proposed, single-project not, idempotent | pass |
+| Archive/restore round-trip + changelog | pass |
+| Hook: nudge on correction, silent on normal prompts, survives garbage stdin | pass |
+| **Total** | **35/35** |
+
+Honest limits, measured and admitted: [docs/HONEST-NUMBERS.md](docs/HONEST-NUMBERS.md). And do not take my word for the table: `npm test` reruns all 35 checks on your machine in seconds. A teacher who cannot show the work is just a man with opinions.
+
+## CLI
+
+```
+chiron init                        # create the ledger (.chiron/ledger.md)
+chiron add --mistake .. --rule .. --how ..   # capture one correction as a rule
+chiron compile                     # dry-run: show what would be written where
+chiron compile --apply             # write rules into every agent's memory file
+chiron mine                        # sweep past transcripts for uncaptured corrections
+chiron check                       # health score, duplicates, contradictions, drift
+chiron promote <id>                # raise a rule that proved itself to your global ledger
+chiron archive <id>                # retire a rule (restore brings it back, forever)
+chiron setup                       # state-aware guided walkthrough (changes nothing)
+```
+
+Zero config works: `init`, `add`, `compile` need nothing else. Everything that writes defaults to dry-run; `--apply` is always explicit.
+
+## FAQ
+
+**Will you scold my agent every time it slips?**
+I have never once scolded a student, and I trained the ones the poets remember. Scolding teaches nothing. A rule teaches. You give me the correction; I turn it into a line every future session reads before it starts.
+
+**I have made the same correction for a year. Is it too late?**
+It is never too late to stop repeating yourself. Run `chiron mine`; it walks back through your old transcripts and hands you the corrections you already paid for, still uncaptured. A year of tuition, refunded as rules.
+
+**Do you read my code with some AI, or send it somewhere?**
+No. The capture path is deterministic: no model, no network in the gates that dedupe and check contradictions. A lesson you cannot inspect is not a lesson, it is a rumor. Your rules stay in git-diffable markdown you can read.
+
+**What if two of my rules disagree?**
+Then I stop and ask you, and I do not guess. I trained a healer and a warrior from the same cave; I know two right answers can look like a contradiction. The judgment stays yours. I only make sure you never lose the question.
+
+**You wrote a rule I do not want anymore.**
+Archive it. `chiron archive <id>` retires it with a dated record and an append-only changelog, and it is never deleted. Change your mind next spring? `chiron restore` brings it back. I keep every lesson a hero ever outgrew.
+
+## From the same forge
+
+CHIRON is a [Demiurge](https://github.com/eragonlonelyboy-lab/demiurge) product. Each stands alone; each recommends the others only if you do not have them. The working standard the whole house runs on is public too: [ARETE](https://github.com/eragonlonelyboy-lab/arete), five discipline gates any model can run; CHIRON is its correction-to-permanent-rule loop shipped as a product, and `arete panel` reads this ledger's failure-class tags to name the gate that leaks most.
+
+| Product | Job |
+|---|---|
+| **HORKOS** | Evidence-audit loop: no receipts, no "done" |
+| **VERITAS** | Slop-free prose that audits its own output |
+| **MONETA** | Token discipline with honest accounting |
+| **HYPNOS** | Memory consolidation in your agents' sleep: every change a diff, nothing deleted |
+| **ATHENA** | Decision trials with verdicts on the record |
+| **CALLIOPE** | A full design agency in the terminal, gated by a QA lead who does not accept "looks fine" |
+| **MAAT** | Multi-agent attention terminal: receipts across every session |
+| **ZOILUS** | The merciless critic: a rejection-class it names once becomes a CHIRON rule |
+| **PEITHO** | Go-to-market: positioning, angles and offers that refuse to sound generic |
+| **PYRRHO** | The skeptic: suspends judgment until the data earns it |
+
+**Pair CHIRON with [HORKOS](../horkos).** HORKOS catches the failure this time; CHIRON makes sure there is no next time. He audits the action NOW; I learn from the correction FOREVER. The mistake he catches once, I make sure never happens again.
+
+## The fair trade
+
+If CHIRON saves you from typing the same correction one more time, the star costs you nothing. ⭐
+
+[![Star History Chart](https://api.star-history.com/svg?repos=eragonlonelyboy-lab/chiron&type=Date)](https://star-history.com/#eragonlonelyboy-lab/chiron&Date)
+
+MIT: see [LICENSE](LICENSE). Free, the way good teaching should be.

package/bin/chiron.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// CHIRON: Corrections Harvested Into Rules, Obeyed Next-session.
+// The centaur who trained the heroes now trains your agents.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const ledger = require('../lib/ledger');
+const governance = require('../lib/governance');
+const compiler = require('../lib/compiler');
+const archive = require('../lib/archive');
+const miner = require('../lib/mine');
+const siblings = require('../lib/siblings');
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flags = new Set(argv.filter(a => a.startsWith('--')));
+const root = process.cwd();
+const APPLY = flags.has('--apply');
+
+function out(s) { process.stdout.write(s + '\n'); }
+function json(o) { out(JSON.stringify(o, null, 2)); }
+function arg(name, fallback) {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] ? argv[i + 1] : fallback;
+}
+function ledgerPathFor() {
+  return flags.has('--global') ? ledger.globalLedgerPath() : ledger.projectLedgerPath(root);
+}
+
+const commands = {
+  init() {
+    const p = ledger.projectLedgerPath(root);
+    if (fs.existsSync(p)) { out(`ledger already exists: ${p}`); return; }
+    ledger.save(p, []);
+    ledger.registerProject(root);
+    out(`CHIRON ledger created: ${p}`);
+    out('Next: capture your first rule with "chiron add", or sweep history with "chiron mine".');
+  },
+
+  // Deterministic add (the skill calls this after distilling a correction).
+  add() {
+    const p = ledgerPathFor();
+    const rules = ledger.load(p);
+    const rule = {
+      id: ledger.nextId(rules),
+      status: 'active',
+      created: new Date().toISOString().slice(0, 10),
+      mistake: arg('--mistake', ''),
+      rule: arg('--rule', ''),
+      apply: arg('--how', ''),
+      detail: arg('--detail', ''),
+      type: ['gotcha', 'dissent'].includes(arg('--type', 'correction')) ? arg('--type', 'correction') : 'correction',
+      source: arg('--source', 'manual'),
+      projects: [path.basename(root)],
+      occurrences: 1,
+      updated: new Date().toISOString().slice(0, 10),
+    };
+    if (!rule.rule) { out('ERROR: --rule is required (the durable rule text).'); process.exit(1); }
+    // dedup gate: refuse silently duplicating; surface the match instead
+    const dupe = rules.find(r => r.status === 'active' && ledger.isDuplicate(r, rule));
+    if (dupe && !flags.has('--force')) {
+      out(`DUPLICATE of ${dupe.id}: "${dupe.rule}"`);
+      out(`If it truly is the same lesson, bump it instead: chiron bump ${dupe.id}. Use --force to add anyway.`);
+      process.exit(2);
+    }
+    const contra = governance.findContradictions([...rules, rule]).filter(c => c.a === rule.id || c.b === rule.id);
+    if (contra.length && !flags.has('--force')) {
+      out(`CONTRADICTION with ${contra.map(c => c.a === rule.id ? c.b : c.a).join(', ')}. CHIRON never picks a winner.`);
+      out('Reconcile the rules, archive the outdated one, or re-run with --force if they truly coexist.');
+      process.exit(3);
+    }
+    rules.push(rule);
+    ledger.save(p, rules);
+    ledger.registerProject(root);
+    archive.logChange(path.dirname(p), `added ${rule.id}: ${rule.rule}`);
+    out(`Captured ${rule.id}. Compile it into your agents: chiron compile --apply`);
+  },
+
+  bump() {
+    const id = argv[1];
+    const p = ledgerPathFor();
+    const rules = ledger.load(p);
+    const r = rules.find(x => x.id === id);
+    if (!r) { out(`rule ${id} not found`); process.exit(1); }
+    r.occurrences++;
+    r.updated = new Date().toISOString().slice(0, 10);
+    const proj = path.basename(root);
+    if (!r.projects.includes(proj)) r.projects.push(proj);
+    ledger.save(p, rules);
+    out(`${id} occurrences -> ${r.occurrences}`);
+  },
+
+  list() {
+    const rules = ledger.load(ledgerPathFor());
+    if (!rules.length) { out('ledger empty. capture with "chiron add" or sweep history with "chiron mine".'); return; }
+    for (const r of rules) out(`${r.id} [${r.status}${r.type === 'gotcha' ? '/gotcha' : ''}] (${r.occurrences}x)${r.detail ? ' +detail' : ''} ${r.rule}`);
+  },
+
+  compile() {
+    const rules = ledger.load(ledger.projectLedgerPath(root));
+    const globalRules = ledger.load(ledger.globalLedgerPath());
+    const all = [...globalRules, ...rules];
+    const plan = compiler.compile(root, all, { apply: APPLY });
+    for (const p of plan) {
+      if (p.error) out(`FAIL ${p.target}: ${p.error}`);
+      else out(`${APPLY && p.changed ? 'WROTE' : p.changed ? 'WOULD WRITE (dry-run)' : 'up-to-date'} ${p.target}: ${p.file}`);
+    }
+    if (!APPLY && plan.some(p => p.changed)) out('\nDry-run. Re-run with --apply to write.');
+    if (APPLY) archive.logChange(ledger.projectDir(root), `compiled ${all.filter(r => r.status === 'active').length} rules -> ${plan.filter(p => p.changed).map(p => p.target).join(', ') || 'no changes'}`);
+  },
+
+  mine() {
+    const storesArg = arg('--store');
+    const res = miner.mine({
+      stores: storesArg ? [storesArg] : undefined,
+      limit: parseInt(arg('--limit', '40'), 10),
+    });
+    out(`Scanned ${res.filesScanned} transcripts across ${res.stores.length} store(s). Read-only, nothing written.`);
+    if (!res.candidates.length) { out('No correction candidates found.'); return; }
+    out(`\n${res.candidates.length} candidate correction(s). These are heuristic hits, NOT rules; distill the real ones with /chiron capture:\n`);
+    for (const c of res.candidates) {
+      out(`[${c.confidence}] (${c.tag}) ${c.excerpt}`);
+      out(`    at ${c.file}:${c.line}\n`);
+    }
+    const outFile = arg('--out');
+    if (outFile) { fs.writeFileSync(outFile, JSON.stringify(res, null, 2), 'utf8'); out(`Saved: ${outFile}`); }
+  },
+
+  check() {
+    const rules = ledger.load(ledgerPathFor());
+    const drift = compiler.verify(root, [...ledger.load(ledger.globalLedgerPath()), ...ledger.load(ledger.projectLedgerPath(root))]);
+    const h = governance.health(rules, { compileDrift: drift.length > 0 });
+    out(`CHIRON health: ${h.score}/100 (${h.active} active rules)`);
+    if (h.duplicates.length) out(`duplicates: ${h.duplicates.map(d => `${d.a}~${d.b}(${d.similarity})`).join(', ')}`);
+    if (h.contradictions.length) for (const c of h.contradictions) out(`CONTRADICTION ${c.a} vs ${c.b}: ${c.note}`);
+    if (h.stale.length) out(`stale (>180d): ${h.stale.join(', ')}`);
+    if (h.compileDrift) out(`compile drift: targets out of date -> chiron compile --apply (${drift.join(', ')})`);
+    if (flags.has('--json')) json(h);
+  },
+
+  promote() {
+    const candidates = governance.findPromotions(parseInt(arg('--min', '2'), 10));
+    if (!candidates.length) { out('No promotion candidates (no rule appears in 2+ project ledgers yet).'); return; }
+    for (const c of candidates) {
+      out(`PROPOSE global: "${c.rule.rule}" (seen in: ${c.projects.join(', ')})`);
+      if (APPLY) {
+        const promoted = governance.applyPromotion(c);
+        archive.logChange(ledger.globalDir(), `promoted ${promoted.id} from ${c.projects.join(', ')}`);
+        out(`  -> promoted as ${promoted.id} in the global ledger`);
+      }
+    }
+    if (!APPLY) out('\nDry-run. Re-run with --apply to promote.');
+  },
+
+  archive() {
+    const id = argv[1];
+    if (!id) { out('usage: chiron archive <rule-id> [--reason "..."] '); process.exit(1); }
+    const res = archive.archiveRule(ledgerPathFor(), id, arg('--reason', 'user request'));
+    out(res.ok ? `archived ${id} -> ${res.archive} (restore any time: chiron restore ${id})` : `ERROR: ${res.error}`);
+  },
+
+  restore() {
+    const q = argv.slice(1).filter(a => !a.startsWith('--')).join(' ');
+    if (!q) { out('usage: chiron restore <rule-id or search text>'); process.exit(1); }
+    const res = archive.restoreRule(ledgerPathFor(), q);
+    out(res.ok ? `restored ${res.rule.id} from ${res.from}` : `ERROR: ${res.error}`);
+  },
+
+  setup() {
+    out('CHIRON setup: state readout. This command changes nothing; every step is optional and explained.\n');
+    const steps = [];
+    const lp = ledger.projectLedgerPath(root);
+    steps.push({
+      name: 'Project ledger', done: fs.existsSync(lp),
+      why: 'the canonical store your rules live in. Without it, corrections stay trapped in chat history.',
+      next: 'chiron init'
+    });
+    const targets = compiler.detectTargets(root);
+    const drift = fs.existsSync(lp) ? compiler.verify(root, [...ledger.load(ledger.globalLedgerPath()), ...ledger.load(lp)]) : targets;
+    steps.push({
+      name: `Agent files compiled (${targets.join(', ')})`, done: fs.existsSync(lp) && drift.length === 0,
+      why: 'rules only work if the agent reads them at session start. Compile projects your ledger into each agent\'s memory file inside managed markers; your own content is never touched.',
+      next: 'chiron compile --apply'
+    });
+    const hookHint = path.join(require('os').homedir(), '.claude', 'settings.json');
+    let hookRegistered = false;
+    try { hookRegistered = (fs.readFileSync(hookHint, 'utf8')).includes('chiron-hook'); } catch {}
+    steps.push({
+      name: 'Live correction hook (optional)', done: hookRegistered,
+      why: 'nudges the agent to capture a rule the moment you correct it, so nothing is lost. Without it, you rely on remembering to run /chiron capture or on periodic mining. It reads your prompt locally, adds one line of context, never blocks.',
+      next: `add to ${hookHint} under hooks.UserPromptSubmit: node ${path.resolve(__dirname, '..', 'hooks', 'chiron-hook.js')}`
+    });
+    steps.push({
+      name: 'History mined at least once (optional)', done: fs.existsSync(path.join(ledger.projectDir(root), 'mine-report.json')),
+      why: 'your past sessions already contain corrections you paid for. Mining sweeps them read-only and lists candidates worth turning into rules.',
+      next: `chiron mine --out ${path.join(ledger.projectDir(root), 'mine-report.json')}`
+    });
+    for (const s of steps) {
+      out(`${s.done ? '[done]   ' : '[missing]'} ${s.name}`);
+      out(`         why: ${s.why}`);
+      if (!s.done) out(`         next: ${s.next}`);
+      out('');
+    }
+    const missing = siblings.recommendMissing();
+    if (missing.length) {
+      out('Demiurge siblings you do not have yet (recommendations only, nothing auto-installs):');
+      for (const m of missing) out(`  - ${m.name}: ${m.why}`);
+    }
+    const first = steps.find(s => !s.done);
+    out(first ? `\nExact next action: ${first.next}` : '\nEverything is set. Correct your agent once; CHIRON keeps it corrected.');
+  },
+
+  status() { commands.check(); },
+
+  help() {
+    out(`CHIRON: Corrections Harvested Into Rules, Obeyed Next-session.
+
+Chiron trained the heroes. CHIRON trains your agents: every correction you
+make becomes a permanent rule, compiled into every agent's memory.
+
+usage: chiron <command> [flags]
+
+  init                       create the project ledger (.chiron/ledger.md)
+  add --rule "..."           capture a rule (--mistake, --how, --detail, --type gotcha, --source; dedup + contradiction gated)
+  bump <id>                  same lesson happened again: count it
+  list                       show the ledger
+  compile [--apply]          project rules into CLAUDE.md / AGENTS.md / .cursor / .windsurf (dry-run default)
+  mine [--limit N] [--out f] sweep past transcripts for uncaptured corrections (read-only)
+  check [--json]             health: duplicates, contradictions, stale rules, compile drift
+  promote [--apply]          propose project rules seen in 2+ projects for the global ledger
+  archive <id>               retire a rule (never deleted; dated archive + changelog)
+  restore <id|text>          bring an archived rule back
+  setup                      state-aware guided setup (reads, explains, changes nothing)
+
+  --global                   operate on the global ledger (~/.chiron/global)
+  --apply                    apply changes (everything defaults to dry-run)
+`);
+  }
+};
+
+(commands[cmd] || commands.help)();

package/docs/HONEST-NUMBERS.md

@@ -0,0 +1,25 @@
+# HONEST-NUMBERS: when CHIRON loses
+
+Every Demiurge product tells you where it does NOT win. Here is CHIRON's list.
+
+## Mining is heuristic, and we measured it
+
+`chiron mine` finds corrections with deterministic text patterns, zero LLM. On the seeded benchmark corpus (6 planted corrections + 4 noise turns, in `benchmarks/run.js`, reproducible): 6/6 planted detected, 0 noise hits. Real transcripts are messier than any fixture: expect FALSE POSITIVES (a "no," that opens a clarification, not a correction) and misses (corrections phrased gently). That is why mine outputs candidates for review, never auto-rules. Run it expecting to discard some of what it finds.
+
+## Distillation is judgment, not measurement
+
+Turning a correction into a well-worded rule is LLM work (the skill layer). No benchmark can bless judgment; what IS checkable are the receipts: every capture shows the rule id and the exact files compiled, the ledger is git-diffable markdown, and every change lands in an append-only changelog. Trust the trail, not the claim.
+
+## If you live in one agent and never leave, you get less
+
+The headline is cross-agent: one correction compiled into CLAUDE.md, AGENTS.md, Cursor, and Windsurf at once. If you use Claude Code only, Anthropic's native auto-memory already captures casual corrections for you, and CHIRON's remaining value narrows to governance: dedup, contradiction surfacing, promote-to-global, archive-not-delete, and the mining sweep. Real, but a smaller win.
+
+## Rules compete for context
+
+Every compiled rule costs context tokens in every future session. A 200-rule ledger is a liability, not an asset. CHIRON's health check flags staleness and duplicates, and the Windsurf compiler enforces the platform's hard caps loudly, but the discipline of keeping rules FEW and SHARP is yours. Archive freely; nothing is ever lost.
+
+## What CHIRON does not do
+
+- It does not stop the mistake happening the FIRST time. That is HORKOS's job (evidence-audit of every action). CHIRON stops the second time.
+- It does not consolidate or reorganize your broader memory files. That is HYPNOS's job. CHIRON owns one pipeline: correction to rule.
+- It does not sync rules across machines or teams. v1 is local-first, single user.

package/hooks/chiron-hook.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// CHIRON live hook (UserPromptSubmit). Two triggers, both add a one-line capture
+// nudge and never block:
+//   1. the user's message looks like a correction (scanText), or
+//   2. HORKOS caught a false-completion or evidence gap this session: its monotonic
+//      `caught` counter grew. Auditor catches are prime rule material, and this fires
+//      even when the catch was resolved before the user's next message.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { scanText } = require('../lib/mine');
+
+function readJSON(p, fallback) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8').replace(/^/, '')); } catch { return fallback; }
+}
+
+// Nudge once per NEW HORKOS catch this session. HORKOS bumps `caught` on every
+// Stop-hook block; a per-session marker records the count we last nudged at, so a
+// fresh catch (counter grew) fires exactly once and a resolved-and-quiet session
+// stays silent. Baseline is set on first sight so prior-session catches never fire.
+function detectHorkosCatch(sessionId) {
+  if (!sessionId) return null;
+  try {
+    const horkosHome = process.env.HORKOS_HOME || path.join(os.homedir(), '.horkos');
+    const stats = readJSON(path.join(horkosHome, 'stats.json'), null);
+    if (!stats || typeof stats.caught !== 'number') return null;
+    const caught = stats.caught;
+
+    const chironHome = process.env.CHIRON_HOME || path.join(os.homedir(), '.chiron');
+    const markerPath = path.join(chironHome, 'horkos-watch', String(sessionId) + '.json');
+    const marker = readJSON(markerPath, null);
+    if (!marker) {
+      fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+      fs.writeFileSync(markerPath, JSON.stringify({ baseline: caught, nudgedCaught: caught }), 'utf8');
+      return null;
+    }
+    if (caught > marker.nudgedCaught) {
+      marker.nudgedCaught = caught;
+      fs.writeFileSync(markerPath, JSON.stringify(marker), 'utf8');
+      const audit = readJSON(path.join(horkosHome, 'sessions', String(sessionId), 'audit.json'), null);
+      const s = audit && audit.summary;
+      if (s) {
+        const bits = [];
+        if (s.phantom_claims) bits.push(s.phantom_claims + ' phantom claim(s)');
+        if (s.fail) bits.push(s.fail + ' failed verification(s)');
+        if (s.silent_failures) bits.push(s.silent_failures + ' silent failure(s)');
+        if (bits.length) return ' (' + bits.join(', ') + ')';
+      }
+      return '';
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+let input = '';
+process.stdin.on('data', d => { input += d; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(input);
+    const prompt = payload.prompt || payload.user_prompt || '';
+    const sessionId = payload.session_id || payload.sessionId || '';
+    const parts = [];
+    const tag = scanText(String(prompt));
+    if (tag) parts.push(`this message looks like a correction (${tag})`);
+    const horkos = detectHorkosCatch(sessionId);
+    if (horkos !== null) parts.push(`HORKOS caught a false-completion or evidence gap this session${horkos}`);
+    if (parts.length) {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: `CHIRON: ${parts.join('; and ')}. Once resolved, capture the durable lesson as a permanent rule with /chiron capture so the class of mistake never repeats.`
+        }
+      }));
+    }
+  } catch {
+    // Garbage stdin must never break the user's session. Exit clean, say nothing.
+  }
+  process.exit(0);
+});

package/lib/archive.js

@@ -0,0 +1,61 @@
+// CHIRON archive: nothing is ever deleted. Retired rules land in a dated
+// archive file and can be restored. Every applied change is logged.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const ledger = require('./ledger');
+
+function archiveDir(chironDir) { return path.join(chironDir, 'archive'); }
+function changelogPath(chironDir) { return path.join(chironDir, 'CHANGELOG.md'); }
+
+function today() { return new Date().toISOString().slice(0, 10); }
+
+function logChange(chironDir, line) {
+  const p = changelogPath(chironDir);
+  const stamp = new Date().toISOString();
+  const entry = `- ${stamp} | ${line}\n`;
+  fs.mkdirSync(chironDir, { recursive: true });
+  fs.appendFileSync(p, entry, 'utf8');
+}
+
+// Archive a rule: move it out of the ledger into archive/YYYY-MM-DD.md
+function archiveRule(ledgerPath, ruleId, reason) {
+  const chironDir = path.dirname(ledgerPath);
+  const rules = ledger.load(ledgerPath);
+  const idx = rules.findIndex(r => r.id === ruleId);
+  if (idx === -1) return { ok: false, error: `rule ${ruleId} not found` };
+  const [rule] = rules.splice(idx, 1);
+  rule.status = 'archived';
+  const archPath = path.join(archiveDir(chironDir), `${today()}.md`);
+  fs.mkdirSync(archiveDir(chironDir), { recursive: true });
+  const block = `<!-- archived from ${path.basename(ledgerPath)} | reason: ${reason || 'unspecified'} -->\n## ${rule.id} | archived | ${rule.created}\n**Mistake:** ${rule.mistake}\n**Rule:** ${rule.rule}\n**Apply:** ${rule.apply}\n- source: ${rule.source}\n- projects: ${rule.projects.join(', ')}\n- occurrences: ${rule.occurrences}\n- updated: ${rule.updated}\n\n`;
+  fs.appendFileSync(archPath, block, 'utf8');
+  ledger.save(ledgerPath, rules);
+  logChange(chironDir, `archived ${ruleId} (${reason || 'unspecified'}) -> archive/${today()}.md`);
+  return { ok: true, rule, archive: archPath };
+}
+
+// Restore: search archive files for a rule id or a query string, put it back.
+function restoreRule(ledgerPath, query) {
+  const chironDir = path.dirname(ledgerPath);
+  const dir = archiveDir(chironDir);
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(f => f.endsWith('.md')); } catch { return { ok: false, error: 'no archive' }; }
+  for (const f of files.sort().reverse()) {
+    const content = fs.readFileSync(path.join(dir, f), 'utf8');
+    const rules = ledger.parse(content);
+    const hit = rules.find(r => r.id === query || (r.rule || '').toLowerCase().includes(query.toLowerCase()));
+    if (hit) {
+      const live = ledger.load(ledgerPath);
+      hit.status = 'active';
+      if (live.some(r => r.id === hit.id)) hit.id = ledger.nextId(live);
+      live.push(hit);
+      ledger.save(ledgerPath, live);
+      logChange(chironDir, `restored ${hit.id} from archive/${f}`);
+      return { ok: true, rule: hit, from: f };
+    }
+  }
+  return { ok: false, error: `no archived rule matches "${query}"` };
+}
+
+module.exports = { archiveDir, changelogPath, logChange, archiveRule, restoreRule };

package/lib/compiler.js

@@ -0,0 +1,117 @@
+// CHIRON cross-agent compiler: projects active rules into each agent's memory
+// layer inside managed markers. Surgical: content outside markers is never
+// touched. Per-target quirks follow the verified HYPNOS table.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const ledger = require('./ledger');
+
+const BEGIN = '<!-- chiron:begin (managed by CHIRON, do not edit inside) -->';
+const END = '<!-- chiron:end -->';
+const WINDSURF_CAP = 12000; // hard per-workspace-file cap, fail loud
+
+function ruleLines(rules, opts = {}) {
+  // Only enforceable corrections are projected into agent memory files, keeping
+  // them terse. type: gotcha entries stay in the ledger as the technical journal
+  // (the role lessons.md used to fill) and never bloat CLAUDE.md.
+  const active = rules.filter(r => r.status === 'active' && (r.type || 'correction') === 'correction');
+  const lines = ['## Rules learned from corrections (CHIRON)', ''];
+  for (const r of active) {
+    lines.push(`- **${r.id}:** ${r.rule}${opts.withApply && r.apply ? ` (apply: ${r.apply})` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+function injectBlock(existing, block) {
+  const body = `${BEGIN}\n${block}\n${END}`;
+  if (existing === null || existing === undefined) return body + '\n';
+  const bi = existing.indexOf(BEGIN), ei = existing.indexOf(END);
+  if (bi !== -1 && ei !== -1 && ei > bi) {
+    return existing.slice(0, bi) + body + existing.slice(ei + END.length);
+  }
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  return existing + sep + body + '\n';
+}
+
+// Target definitions. Each returns { path, content } or an error.
+const TARGETS = {
+  claude: {
+    file: root => path.join(root, 'CLAUDE.md'),
+    render: rules => injectBlockInto(rules, {}),
+  },
+  agentsmd: {
+    file: root => path.join(root, 'AGENTS.md'),
+    render: rules => injectBlockInto(rules, {}), // plain markdown only (frontmatter spec not merged)
+  },
+  cursor: {
+    file: root => path.join(root, '.cursor', 'rules', 'chiron.mdc'),
+    render: rules => ({
+      full: [
+        '---',
+        'description: Rules learned from user corrections, compiled by CHIRON',
+        'alwaysApply: true',
+        '---',
+        '',
+        ruleLines(rules)
+      ].join('\n') + '\n',
+      replaceWhole: true // .mdc is CHIRON-owned, whole-file write is safe
+    }),
+  },
+  windsurf: {
+    file: root => path.join(root, '.windsurf', 'rules', 'chiron.md'),
+    render: rules => {
+      const content = ruleLines(rules) + '\n';
+      if (content.length > WINDSURF_CAP) {
+        return { error: `windsurf output ${content.length} chars exceeds hard cap ${WINDSURF_CAP}. Archive or tighten rules first.` };
+      }
+      return { full: content, replaceWhole: true };
+    },
+  },
+};
+
+function injectBlockInto(rules) {
+  return { block: ruleLines(rules) };
+}
+
+// Detect which targets exist in this project (zero tokens, local checks only).
+function detectTargets(root) {
+  const found = [];
+  if (fs.existsSync(path.join(root, 'CLAUDE.md'))) found.push('claude');
+  if (fs.existsSync(path.join(root, 'AGENTS.md'))) found.push('agentsmd');
+  if (fs.existsSync(path.join(root, '.cursor'))) found.push('cursor');
+  if (fs.existsSync(path.join(root, '.windsurf'))) found.push('windsurf');
+  if (found.length === 0) found.push('claude'); // sensible default: create CLAUDE.md block
+  return found;
+}
+
+// Compile: dry-run by default. Returns per-target planned writes as diffs.
+function compile(root, rules, opts = {}) {
+  const targets = opts.targets || detectTargets(root);
+  const plan = [];
+  for (const name of targets) {
+    const t = TARGETS[name];
+    if (!t) { plan.push({ target: name, error: 'unknown target' }); continue; }
+    const filePath = t.file(root);
+    const rendered = t.render(rules);
+    if (rendered.error) { plan.push({ target: name, file: filePath, error: rendered.error }); continue; }
+    const existing = ledger.readFileSafe(filePath);
+    const next = rendered.replaceWhole ? rendered.full : injectBlock(existing, rendered.block);
+    const changed = existing !== next;
+    plan.push({ target: name, file: filePath, changed, before: existing, after: next });
+  }
+  if (opts.apply) {
+    for (const p of plan) {
+      if (p.error || !p.changed) continue;
+      ledger.writeFileUtf8(p.file, p.after);
+    }
+  }
+  return plan;
+}
+
+// Verify: does each compiled block match the current ledger? (compile drift check)
+function verify(root, rules, opts = {}) {
+  const plan = compile(root, rules, Object.assign({}, opts, { apply: false }));
+  return plan.filter(p => !p.error && p.changed).map(p => p.target);
+}
+
+module.exports = { BEGIN, END, WINDSURF_CAP, ruleLines, injectBlock, detectTargets, compile, verify };

package/lib/governance.js

@@ -0,0 +1,129 @@
+// CHIRON governance: dedup, contradiction surfacing, promote-to-global, health.
+// All deterministic. CHIRON surfaces and proposes; it never auto-resolves.
+'use strict';
+const path = require('path');
+const ledger = require('./ledger');
+
+// --- Dedup -----------------------------------------------------------------
+function findDuplicates(rules, threshold = 0.6) {
+  const dupes = [];
+  for (let i = 0; i < rules.length; i++) {
+    for (let j = i + 1; j < rules.length; j++) {
+      if (rules[i].status !== 'active' || rules[j].status !== 'active') continue;
+      const sim = ledger.jaccard(ledger.fingerprint(rules[i]), ledger.fingerprint(rules[j]));
+      if (sim >= threshold) dupes.push({ a: rules[i].id, b: rules[j].id, similarity: +sim.toFixed(2) });
+    }
+  }
+  return dupes;
+}
+
+// --- Contradiction ----------------------------------------------------------
+// Heuristic polarity detection: two rules sharing a token core but pulling in
+// opposite directions (always vs never, use vs avoid, do vs do not).
+const POS = /\b(always|must|use|do|prefer|require)\b/i;
+const NEG = /\b(never|don'?t|do not|avoid|ban|forbid|stop)\b/i;
+function polarity(text) {
+  // Negation dominates: "never use X" is a negative directive even though it
+  // contains a positive verb.
+  if (NEG.test(text)) return -1;
+  if (POS.test(text)) return 1;
+  return 0;
+}
+function findContradictions(rules, coreOverlap = 0.5) {
+  const hits = [];
+  const active = rules.filter(r => r.status === 'active');
+  for (let i = 0; i < active.length; i++) {
+    for (let j = i + 1; j < active.length; j++) {
+      const pi = polarity(active[i].rule), pj = polarity(active[j].rule);
+      if (pi === 0 || pj === 0 || pi === pj) continue;
+      const sim = ledger.jaccard(ledger.fingerprint(active[i]), ledger.fingerprint(active[j]));
+      if (sim >= coreOverlap) {
+        hits.push({
+          a: active[i].id, b: active[j].id, similarity: +sim.toFixed(2),
+          note: 'opposite polarity on a shared core. CHIRON does not pick a winner: review and archive one, or reconcile.'
+        });
+      }
+    }
+  }
+  return hits;
+}
+
+// --- Promote-to-global -------------------------------------------------------
+// A rule whose fingerprint appears in >= minProjects project ledgers is proposed
+// for the global ledger. Proposal only; apply is explicit.
+function findPromotions(minProjects = 2) {
+  const reg = ledger.loadRegistry();
+  const globalRules = ledger.load(ledger.globalLedgerPath());
+  const seen = []; // { rule, roots: [] }
+  for (const root of reg.projects) {
+    const rules = ledger.load(ledger.projectLedgerPath(root));
+    for (const r of rules) {
+      if (r.status !== 'active') continue;
+      const match = seen.find(s => ledger.isDuplicate(s.rule, r));
+      if (match) { if (!match.roots.includes(root)) match.roots.push(root); }
+      else seen.push({ rule: r, roots: [root] });
+    }
+  }
+  return seen
+    .filter(s => s.roots.length >= minProjects)
+    .filter(s => !globalRules.some(g => g.status === 'active' && ledger.isDuplicate(g, s.rule)))
+    .map(s => ({
+      rule: s.rule,
+      projects: s.roots.map(r => path.basename(r)),
+      proposal: `seen in ${s.roots.length} projects: promote to global ledger`
+    }));
+}
+
+function applyPromotion(candidate) {
+  const globalPath = ledger.globalLedgerPath();
+  const globalRules = ledger.load(globalPath);
+  const promoted = Object.assign({}, candidate.rule, {
+    id: ledger.nextId(globalRules),
+    projects: candidate.projects,
+    source: `promoted from ${candidate.projects.join(', ')} (origin ${candidate.rule.id})`
+  });
+  globalRules.push(promoted);
+  ledger.save(globalPath, globalRules);
+  return promoted;
+}
+
+// Parked dissent never compiles into agent rules. When a later incident shares
+// its concrete vocabulary, resurface it for human review without changing policy.
+function resurfaceDissent(rules, incident, threshold = 0.2) {
+  const probe = { rule: String(incident || '') };
+  return rules
+    .filter(r => r.type === 'dissent' && ['active', 'parked'].includes(r.status))
+    .map(r => ({ rule: r, similarity: ledger.jaccard(ledger.fingerprint(r), ledger.fingerprint(probe)) }))
+    .filter(x => x.similarity >= threshold)
+    .sort((a, b) => b.similarity - a.similarity)
+    .map(x => ({ id: x.rule.id, rule: x.rule.rule, source: x.rule.source, similarity: +x.similarity.toFixed(2), action: 'review only; do not auto-change policy' }));
+}
+
+// --- Health ------------------------------------------------------------------
+// 0-100, deterministic. Deductions: duplicates, contradictions, stale actives,
+// compile drift (checked by caller via compiler.verify and passed in).
+function health(rules, opts = {}) {
+  const active = rules.filter(r => r.status === 'active');
+  const dupes = findDuplicates(rules);
+  const contras = findContradictions(rules);
+  const now = opts.now ? new Date(opts.now) : new Date();
+  const stale = active.filter(r => {
+    const d = new Date(r.updated || r.created);
+    return !isNaN(d) && (now - d) / 86400000 > (opts.staleDays || 180);
+  });
+  let score = 100;
+  score -= Math.min(30, dupes.length * 10);
+  score -= Math.min(40, contras.length * 20);
+  score -= Math.min(20, stale.length * 2);
+  if (opts.compileDrift) score -= 10;
+  return {
+    score: Math.max(0, score),
+    active: active.length,
+    duplicates: dupes,
+    contradictions: contras,
+    stale: stale.map(r => r.id),
+    compileDrift: !!opts.compileDrift
+  };
+}
+
+module.exports = { findDuplicates, findContradictions, polarity, findPromotions, applyPromotion, resurfaceDissent, health };

package/lib/ledger.js

@@ -0,0 +1,156 @@
+// CHIRON ledger: the canonical rule store. Git-diffable markdown, strict structure.
+// Rule format is Eragon's proven lessons discipline: Mistake / Rule / Apply + metadata.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const LEDGER_NAME = 'ledger.md';
+const HEADER = '# CHIRON Ledger\n\nRules distilled from corrections. Managed by CHIRON; edit by hand only if you keep the structure.\n';
+
+function projectDir(root) { return path.join(root, '.chiron'); }
+function projectLedgerPath(root) { return path.join(projectDir(root), LEDGER_NAME); }
+function globalDir() { return path.join(os.homedir(), '.chiron', 'global'); }
+function globalLedgerPath() { return path.join(globalDir(), LEDGER_NAME); }
+function registryPath() { return path.join(os.homedir(), '.chiron', 'registry.json'); }
+
+function readFileSafe(p) {
+  try { return fs.readFileSync(p, 'utf8').replace(/^/, ''); } catch { return null; }
+}
+function writeFileUtf8(p, content) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content, 'utf8'); // Node writes BOM-less UTF-8
+}
+
+// Parse a ledger file into rule objects.
+// Rule block shape:
+// ## CHI-R003 | active | 2026-07-05
+// **Mistake:** ...
+// **Rule:** ...
+// **Apply:** ...
+// - source: ...
+// - projects: a, b
+// - occurrences: 2
+// - updated: 2026-07-05
+function parse(content) {
+  if (!content) return [];
+  const rules = [];
+  const blocks = content.split(/^## /m).slice(1);
+  for (const block of blocks) {
+    const lines = block.split(/\r?\n/);
+    const head = lines[0].split('|').map(s => s.trim());
+    const rule = {
+      id: head[0] || '',
+      status: head[1] || 'active',
+      created: head[2] || '',
+      mistake: '', rule: '', apply: '', detail: '', type: 'correction',
+      source: '', projects: [], occurrences: 1, updated: head[2] || ''
+    };
+    const body = lines.slice(1);
+    // meta keys are a fixed set; a "- " line is meta ONLY if it names one of them,
+    // so bullet lists inside a multi-line Detail block are never mistaken for meta.
+    const metaRe = /^- (source|type|projects|occurrences|updated):\s*(.*)$/;
+    for (let li = 0; li < body.length; li++) {
+      const line = body[li];
+      const m = line.match(/^\*\*(Mistake|Rule|Apply):\*\*\s*(.*)$/);
+      if (m) { rule[m[1].toLowerCase()] = m[2].trim(); continue; }
+      const dm = line.match(/^\*\*Detail:\*\*\s*(.*)$/);
+      if (dm) {
+        const buf = [];
+        if (dm[1]) buf.push(dm[1]);
+        while (li + 1 < body.length && !metaRe.test(body[li + 1])) { li++; buf.push(body[li]); }
+        rule.detail = buf.join('\n').replace(/\s+$/, '');
+        continue;
+      }
+      const meta = line.match(metaRe);
+      if (meta) {
+        if (meta[1] === 'projects') rule.projects = meta[2].split(',').map(s => s.trim()).filter(Boolean);
+        else if (meta[1] === 'occurrences') rule.occurrences = parseInt(meta[2], 10) || 1;
+        else rule[meta[1]] = meta[2].trim();
+      }
+    }
+    if (rule.id) rules.push(rule);
+  }
+  return rules;
+}
+
+function serializeRule(r) {
+  const lines = [
+    `## ${r.id} | ${r.status} | ${r.created}`,
+    `**Mistake:** ${r.mistake}`,
+    `**Rule:** ${r.rule}`,
+    `**Apply:** ${r.apply}`,
+  ];
+  if (r.detail && r.detail.trim()) {
+    // Strip leading markdown heading markers so a Detail line can never start
+    // with "## " and get mis-split as a new rule block on the next parse.
+    lines.push('**Detail:**');
+    lines.push(r.detail.replace(/^\s*#{1,6}\s+/gm, '').replace(/\s+$/, ''));
+  }
+  lines.push(`- source: ${r.source || 'manual'}`);
+  lines.push(`- type: ${r.type || 'correction'}`);
+  lines.push(`- projects: ${(r.projects || []).join(', ')}`);
+  lines.push(`- occurrences: ${r.occurrences || 1}`);
+  lines.push(`- updated: ${r.updated || r.created}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function serialize(rules) {
+  return HEADER + '\n' + rules.map(serializeRule).join('\n');
+}
+
+function load(ledgerPath) { return parse(readFileSafe(ledgerPath)); }
+
+function save(ledgerPath, rules) { writeFileUtf8(ledgerPath, serialize(rules)); }
+
+function nextId(rules) {
+  let max = 0;
+  for (const r of rules) {
+    const m = r.id.match(/^CHI-R(\d+)$/);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  return `CHI-R${String(max + 1).padStart(3, '0')}`;
+}
+
+// Fingerprint: normalized token set of the Rule line. Deterministic, zero-LLM.
+const STOP = new Set(['a','an','the','to','of','in','on','for','and','or','is','are','be','it','this','that','with','at','by','as','do','not','dont','never','always','before','after','when','use','must']);
+function tokens(text) {
+  return (text || '').toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/)
+    .filter(t => t.length > 2 && !STOP.has(t));
+}
+function fingerprint(rule) { return [...new Set(tokens(rule.rule))].sort(); }
+function jaccard(aSet, bSet) {
+  const a = new Set(aSet), b = new Set(bSet);
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter++;
+  return inter / (a.size + b.size - inter);
+}
+// Duplicate when rule-line token overlap is high.
+function isDuplicate(r1, r2, threshold = 0.6) {
+  return jaccard(fingerprint(r1), fingerprint(r2)) >= threshold;
+}
+
+// Registry of project ledgers (for promote-to-global scanning).
+function loadRegistry() {
+  const raw = readFileSafe(registryPath());
+  if (!raw) return { projects: [] };
+  try { return JSON.parse(raw); } catch { return { projects: [] }; }
+}
+function registerProject(root) {
+  const reg = loadRegistry();
+  const abs = path.resolve(root);
+  if (!reg.projects.includes(abs)) {
+    reg.projects.push(abs);
+    writeFileUtf8(registryPath(), JSON.stringify(reg, null, 2));
+  }
+  return reg;
+}
+
+module.exports = {
+  projectDir, projectLedgerPath, globalDir, globalLedgerPath, registryPath,
+  parse, serialize, serializeRule, load, save, nextId,
+  tokens, fingerprint, jaccard, isDuplicate,
+  loadRegistry, registerProject, readFileSafe, writeFileUtf8
+};

package/lib/mine.js

@@ -0,0 +1,122 @@
+// CHIRON retro transcript mining: sweep past session transcripts for user
+// corrections that were never captured as rules. Deterministic heuristics,
+// zero LLM, read-only. Output = CANDIDATES with pointers, never auto-rules.
+// Honesty rule: heuristics have false positives; the skill distills, a human gates.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// User-turn correction signals. Anchored to reduce noise.
+const USER_PATTERNS = [
+  { re: /^no[,.]?\s/i, tag: 'flat-no' },
+  { re: /\bthat'?s (wrong|not right|incorrect|not what i)/i, tag: 'wrong' },
+  { re: /\byou (didn'?t|did not|forgot|missed|ignored)/i, tag: 'omission' },
+  { re: /\bi (said|told you|asked for|meant)\b/i, tag: 'restate' },
+  { re: /\bwhy (did|are) you\b/i, tag: 'challenge' },
+  { re: /\b(don'?t|do not|stop|never) (do|use|write|add|delete|touch)\b/i, tag: 'prohibit' },
+  { re: /\bagain\b.*\b(wrong|same|mistake|error)\b/i, tag: 'repeat-offense' },
+  { re: /\bshould (be|have been|not)\b/i, tag: 'should' },
+  { re: /\bwrong (file|folder|branch|name|path|format|place)\b/i, tag: 'wrong-target' },
+];
+// Assistant-turn acknowledgement markers (strong confirmation the prior user turn was a correction).
+const ACK_PATTERNS = [
+  /\byou'?re right\b/i,
+  /\bmy (mistake|error|bad)\b/i,
+  /\bi (apologize|misread|misunderstood|shouldn'?t have)\b/i,
+  /\bcorrecting (that|this|now)\b/i,
+];
+
+function extractText(message) {
+  if (!message) return '';
+  const c = message.content;
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) return c.filter(b => b && b.type === 'text').map(b => b.text || '').join('\n');
+  return '';
+}
+
+function scanText(text) {
+  if (!text) return null;
+  // skip pasted logs / tool noise: correction signals live in short human turns
+  const head = text.slice(0, 600);
+  for (const p of USER_PATTERNS) {
+    if (p.re.test(head)) return p.tag;
+  }
+  return null;
+}
+
+function hasAck(text) { return ACK_PATTERNS.some(re => re.test(text.slice(0, 800))); }
+
+// Scan one JSONL transcript. Returns candidate corrections with line pointers.
+function scanTranscript(filePath) {
+  let raw;
+  try { raw = fs.readFileSync(filePath, 'utf8'); } catch { return []; }
+  const lines = raw.split('\n');
+  const candidates = [];
+  let prev = null; // { tag, lineNo, excerpt }
+  for (let i = 0; i < lines.length; i++) {
+    let obj;
+    try { obj = JSON.parse(lines[i]); } catch { continue; }
+    const type = obj.type || (obj.message && obj.message.role);
+    if (type === 'user') {
+      const text = extractText(obj.message || obj);
+      // system-injected content is not a human correction
+      if (text.includes('<system-reminder>') || text.includes('tool_result')) { prev = null; continue; }
+      const tag = scanText(text);
+      prev = tag ? { tag, lineNo: i + 1, excerpt: text.slice(0, 200).replace(/\s+/g, ' ').trim() } : null;
+    } else if (type === 'assistant' && prev) {
+      const text = extractText(obj.message || obj);
+      const confirmed = hasAck(text);
+      candidates.push({
+        file: filePath, line: prev.lineNo, tag: prev.tag,
+        confidence: confirmed ? 'high' : 'medium',
+        excerpt: prev.excerpt
+      });
+      prev = null;
+    }
+  }
+  return candidates;
+}
+
+// Default transcript stores (Claude Code + Codex), overridable.
+function defaultStores() {
+  return [
+    path.join(os.homedir(), '.claude', 'projects'),
+    path.join(os.homedir(), '.codex', 'sessions'),
+  ].filter(p => fs.existsSync(p));
+}
+
+function listTranscripts(storeDir, maxFiles = 500) {
+  const out = [];
+  function walk(dir, depth) {
+    if (depth > 4 || out.length >= maxFiles) return;
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (out.length >= maxFiles) return;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p, depth + 1);
+      else if (e.name.endsWith('.jsonl')) out.push(p);
+    }
+  }
+  walk(storeDir, 0);
+  return out;
+}
+
+function mine(opts = {}) {
+  const stores = opts.stores || defaultStores();
+  const results = { stores, filesScanned: 0, candidates: [] };
+  for (const store of stores) {
+    const files = listTranscripts(store, opts.maxFiles || 500);
+    for (const f of files) {
+      results.filesScanned++;
+      results.candidates.push(...scanTranscript(f));
+    }
+  }
+  // high-confidence first, then by tag specificity
+  results.candidates.sort((a, b) => (a.confidence === b.confidence) ? 0 : (a.confidence === 'high' ? -1 : 1));
+  if (opts.limit) results.candidates = results.candidates.slice(0, opts.limit);
+  return results;
+}
+
+module.exports = { USER_PATTERNS, ACK_PATTERNS, scanText, hasAck, scanTranscript, defaultStores, listTranscripts, mine };

package/lib/siblings.js

@@ -0,0 +1,36 @@
+// Demiurge sibling detection: cheap local checks, zero tokens.
+// House rule 3: detect what is installed, recommend only what is MISSING.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SIBLINGS = [
+  { name: 'HORKOS', why: 'audits every action NOW with evidence; CHIRON learns from every correction FOREVER. Together they are the full discipline loop.', checks: [['skills', 'horkos'], ['bin', 'horkos']] },
+  { name: 'HYPNOS', why: 'consolidates your memory files in their sleep; CHIRON\'s ledger is one more file it keeps healthy.', checks: [['skills', 'hypnos'], ['bin', 'hypnos']] },
+  { name: 'VERITAS', why: 'keeps the prose your agent writes free of AI slop.', checks: [['skills', 'veritas']] },
+  { name: 'MONETA', why: 'keeps your agent honest about token cost.', checks: [['bin', 'moneta']] },
+  { name: 'ZOILUS', why: 'a blind panel judges the craft and rejects on doubt; the rejection-class it names once becomes a CHIRON rule.', checks: [['skills', 'zoilus'], ['bin', 'zoilus']] },
+  { name: 'PEITHO', why: 'writes the go-to-market copy, and refuses to let it sound generic.', checks: [['skills', 'peitho'], ['bin', 'peitho']] },
+  { name: 'PYRRHO', why: 'suspends judgment until the data earns it, so no numeric claim ships unaudited.', checks: [['skills', 'pyrrho'], ['bin', 'pyrrho']] },
+];
+
+function skillInstalled(name) {
+  return fs.existsSync(path.join(os.homedir(), '.claude', 'skills', name));
+}
+function binInstalled(name) {
+  const dirs = (process.env.PATH || '').split(path.delimiter);
+  const exts = process.platform === 'win32' ? ['.cmd', '.ps1', '.exe', ''] : [''];
+  return dirs.some(d => exts.some(x => { try { return fs.existsSync(path.join(d, name + x)); } catch { return false; } }));
+}
+
+function detect() {
+  return SIBLINGS.map(s => ({
+    name: s.name, why: s.why,
+    installed: s.checks.some(([kind, id]) => kind === 'skills' ? skillInstalled(id) : binInstalled(id))
+  }));
+}
+
+function recommendMissing() { return detect().filter(s => !s.installed); }
+
+module.exports = { SIBLINGS, detect, recommendMissing };

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "demiurge-chiron",
+  "version": "0.2.0",
+  "description": "Your agent makes the same mistake every session. CHIRON makes it make each mistake exactly once.",
+  "bin": { "chiron": "bin/chiron.js" },
+  "scripts": {
+    "test": "node benchmarks/run.js",
+    "bench": "node benchmarks/run.js"
+  },
+  "engines": { "node": ">=18" },
+  "keywords": ["claude-code", "agents", "rules", "self-improvement", "corrections", "memory", "cross-agent"],
+  "author": "Eragon Lee (Demiurge)",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/eragonlonelyboy-lab/chiron" },
+  "files": ["bin", "lib", "hooks", "docs", "skill", "CLAUDE.md"]
+}

package/skill/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: chiron
+description: Use when the user corrects the agent (wrong output, wrong approach, "no, I said...", "that's wrong", "you forgot..."), when the user asks to capture a lesson or rule ("/chiron", "capture that", "remember this rule", "never do that again"), when reviewing mined correction candidates from `chiron mine`, or at session end to sweep for uncaptured corrections. CHIRON turns corrections into permanent rules compiled into every agent's memory (CLAUDE.md, AGENTS.md, Cursor, Windsurf) so the same mistake never happens twice.
+argument-hint: "[capture | review-mine | sweep] or just describe the correction"
+---
+
+# CHIRON: Corrections Harvested Into Rules, Obeyed Next-session
+
+Chiron, the immortal centaur, trained Achilles, Asclepius, and Jason. He did not fight for the heroes; he made the heroes better. CHIRON does the same for your agents: every correction becomes a permanent rule, recalled in every future session, in every agent you use.
+
+The cycle: **correction → rule → permanent recall.**
+
+## When you are invoked
+
+**Mode A, capture (default):** a correction just happened, or the user says "capture that."
+**Mode B, review-mine:** the user ran `chiron mine` and wants candidates distilled.
+**Mode C, sweep:** session is ending; check whether any correction this session went uncaptured.
+
+## Mode A: Capture
+
+1. **Identify the correction, then verify the diagnosis before distilling.** What did the agent do, and what did the user actually want? If it is ambiguous which of two things was the mistake, ask one short question, never guess. Then investigate *why* it happened and confirm the real cause before harvesting a rule: a rule distilled from a misdiagnosed or surface-level correction is worse than none, because it becomes permanent. Correction → **verified cause** → rule.
+2. **Distill it into the rule format.** Three parts, each one sentence, durable and general enough to prevent the CLASS of mistake, specific enough to be actionable:
+   - **Mistake:** what went wrong (past tense, factual)
+   - **Rule:** the instruction that would have prevented it (imperative)
+   - **Apply:** how to follow it in practice (the check, the command, the habit)
+   Bad rule: "be more careful with files." Good rule: "Validate canvas JSON with a parser after every write; unescaped quotes break Obsidian."
+   Two optional fields carry the richer context a one-line rule cannot:
+   - **Detail** (`--detail`): a multi-line technical note (the failure scenario, code specifics, the fix). This is what a running lessons journal holds; put it here instead of losing it.
+   - **type** (`--type gotcha`): mark a technical discovery you hit yourself (not a user correction) as a `gotcha`. Corrections (the default) compile into every agent file; `gotcha` entries stay in the ledger as the searchable technical journal and never bloat the agent files. Use `gotcha` for API quirks, environment traps, and hard-won findings; use the default for behavioral rules the agent must obey.
+   - **Failure-class tag** (in `--source`): when the mistake maps to a working-discipline stage, append `class:<scope|evidence|adversarial|verify|report>` to the source string (e.g. `--source "session 2026-07-10 class:verify"`). Counting classes across the ledger turns it into a defect map: the class that accumulates the most rules is the habit to harden next. Tag honestly; skip it when none fits.
+3. **Gate it through the CLI** (dedup + contradiction checks are deterministic, let them run):
+   ```
+   chiron add --mistake "..." --rule "..." --how "..." --detail "..." --type gotcha --source "session YYYY-MM-DD"
+   ```
+   (`--detail` and `--type` are optional; omit them for a plain behavioral correction.)
+   - **Exit 2 (duplicate):** the CLI names the existing rule. Bump it instead: `chiron bump <id>`. A repeated lesson is a signal, not a new rule.
+   - **Exit 3 (contradiction):** the CLI names the conflicting rule. NEVER pick a winner yourself. Show the user both rules and ask which stands; archive the loser with `chiron archive <id> --reason "superseded by <new>"`.
+4. **Compile:** `chiron compile --apply` so every agent file gets the rule now, not someday.
+5. **Confirm with receipts:** show the rule id, and the list of files the compiler wrote.
+
+## Mode B: Review mined candidates
+
+`chiron mine` output is heuristic: candidates, not truth. For each candidate the user wants processed:
+1. Read the excerpt (and the transcript pointer if more context is needed).
+2. Decide honestly: was this a real correction with a durable lesson, or noise (a one-off preference, a misunderstanding, an already-captured rule)? Say which and why in one line.
+3. Real ones go through Mode A steps 2-5. Skip the rest, tell the user what was skipped.
+
+## Mode C: Session sweep
+
+Scan the current session for moments the user corrected you. For each one not yet captured, propose the distilled rule (Mode A format) and ask in ONE batch which to capture. Capture approved ones through Mode A steps 3-5.
+
+## Laws (non-negotiable)
+
+### Project-earned rules and vindicated dissent
+
+- A project template may carry `[RESEED]` rules, but the marker stays until a real incident from that project supplies positive and negative evidence.
+- A rejected or parked reviewer finding is not a correction yet. Store it as dissent linked to the decision and its tripwires, not as an active rule.
+- When a tripwire fires or later evidence vindicates the finding, resurface it for review. Do not silently activate it and do not erase the original rejection reason.
+- Compile only confirmed corrections into agent instructions. Agreement between multiple models is not confirmation.
+
+- **The CLI gates every write.** Never write to the ledger file directly; `chiron add` runs the dedup and contradiction checks you cannot do reliably by eye.
+- **Contradictions are asked, never picked.** CHIRON's trust model is the user's memory stays the user's.
+- **Archive, never delete.** Retiring a rule goes through `chiron archive`; it is restorable forever.
+- **A rule must name the class, not the instance.** "Do not call the API twice on THIS page" is an instance; "Re-fetch before every full-page overwrite" is a class.
+- **Receipts on every capture:** rule id + compiled files, shown to the user.
+- **Sibling note:** if HORKOS is installed, its audit failures are prime capture material; offer to distill repeated audit findings into rules.