@rafinery/cli 0.13.0 → 0.15.0

package/blueprint/.claude/skills/rafa-plan/SKILL.md

@@ -23,13 +23,13 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
   the tools; the dev never asks for it. Repo not platform-connected (no `rafinery`
   MCP in the session)? Fall back to reading `.rafa/brain/` files directly — same
   knowledge, just unserved.*
-- **bloom pulls** — `list_improvements` in the blast radius (PLUS any open
-  `category: security` P0 regardless of region — the one class that travels;
-  one line, dismissible, never blocking); surface the
+- **bloom pulls** — `list_improvements` in the blast radius, surfacing the
   top-leverage open items as optional *"while-you're-here"* child tasks
-  (leverage-ranked, dismissible, never blocking). **Any improvement the plan
-  ADOPTS (as a task or the plan's very subject) is hydrated NOW** —
-  `rafa hydrate improvement <id>` — so the canonical ledger file is in the
+  (leverage-ranked, dismissible, never blocking). Open `category: security` P0s
+  come along too — the one class that travels regardless of region (contract
+  §12.5), one line, still dismissible, never blocking. **Any improvement the
+  plan ADOPTS** — as a task or as the plan's very subject — **is hydrated NOW**
+  (`rafa hydrate improvement <id>`), so the canonical ledger file is in the
   branch working set from the start and the eventual `status: fixed` edit lands
   on that same file, never a path-drifted twin authored at build's end.
   **Also pull `get_knowledge_gaps`** (the open backlog — what devs asked that
@@ -102,17 +102,17 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
    the pivotal choices are logged as DECISIONS at approval (`log_decision`:
    context · options · decision · rationale; actor = the dev for their calls).
 3. **Ledger pull** (bloom) → optional leverage tasks in the blast radius.
-3b. **Security transparency** (2026-07-26 r2 — "security is not an aftermath").
-   Run `npx @rafinery/cli audit --json` (seconds; reuse a same-session
-   `security-audit.json` if fresh) and present the picture TO THE DEV, verbatim
-   and unburied, before the plan is approved: one line of severity totals +
-   which tiers ran, then any critical/high finding whose package or file sits
-   in THIS plan's blast radius (per [rafa-security](../rafa-security/SKILL.md)'s
-   reachability method). A blast-radius critical/high → propose it as a plan
-   child task (the fix rides the work); open `category: security` P0s surface
-   regardless of region. Transparent means: the dev sees the counts even when
-   everything is clean — "dependency tier clean at <sha>" is one honest line,
-   never silence.
+3b. **Security transparency — integral, never an aftermath** (contract §12.5;
+   owner 2026-07-26). Run `npx @rafinery/cli audit --json` (seconds; reuse a
+   same-session `security-audit.json` if fresh) and put the picture in front of
+   the dev — verbatim and unburied — before the plan is approved: one line of
+   severity totals plus which tiers ran, then any critical/high finding whose
+   package or file sits in THIS plan's blast radius (per
+   [rafa-security](../rafa-security/SKILL.md)'s reachability method). A
+   blast-radius critical/high becomes a plan child task, so the fix rides the
+   work. Transparency is the whole point — the dev sees the counts even when
+   nothing is wrong: *"dependency tier clean at <sha>"* is one honest line,
+   said out loud, never silence.
 4. **Leverage-match** — recommend existing skills/tools/MCP that fit the tasks;
    never plan to hand-roll what a capability already does.
 5. **prism plan-validation** → REJECT/fix loop until clean.

package/blueprint/.claude/skills/rafa-sage/SKILL.md

@@ -102,16 +102,20 @@ human.
 
 ---
 
-## Output — the learnings ledger (to `.claude/rafa/learnings/`)
+## Output — the learnings ledger (to `.rafa/learnings/`)
 
-The ledger is a **committed, human-reviewed governance artifact** — diffs for MR review. It is
-**NOT** a Convex table and **NOT** inside any customer `.rafa/brain/` (asset-free: learnings are
-about OUR agents; they never mix with customer knowledge). It lives beside the contract at
-`.claude/rafa/learnings/` (governance, versioned with the blueprint, MR-reviewed). The platform's
-"agent learnings" card renders a **projection** of it (summary rows via `report_learning`, wave
-4.1, owner-ratified 2026-07-24) — a display overlay, never a second truth and never the store:
+The ledger is a **sibling of the improvement ledger** (owner 2026-07-27): it lives in gitignored
+`.rafa/learnings/` — a `.rafa/` artifact like `.rafa/improve/`, NOT committed under `.claude/`,
+NOT inside any customer `.rafa/brain/` (asset-free: learnings are about OUR agents; they never mix
+with customer knowledge). Storage mirrors improvements exactly: gitignored locally, durable via
+the brain-repo mirror + the platform DB. The DB (`agentLearnings`) is the store; sage writes each
+entry via `report_learning`, and the platform's "agent learnings" card renders it. The local
+`.rafa/learnings/` files are sage's working copy (regenerated per pass, like the brain):
 
 - `learnings/<id>.md` — one file per learning (one proposed card/SOP diff, cited to event shapes).
+  Each is an **OKF concept** (`type: Learning`, self-describing like every `.rafa/` file —
+  contract §11): stable `id` == filename stem, non-empty `type`/`title`/`description`. `rafa
+  compile` gates the quartet from `.rafa/learnings/`.
 - `ledger.md` — generated index: counts by category / target / status, and the top-leverage few.
 
 **Learnings-ledger ENTRY SCHEMA** (defined here; deliberately has no code-content-capable field):

package/blueprint/.claude/skills/rafa-scan/SKILL.md

@@ -201,12 +201,13 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 6. **Flow tracing** [LLM, cited] — from each entry point, hop-by-hop to termination
    (render / DB write / response) → `flow` playbooks. Add `how-to` playbooks for the
    recurring "add X" procedures these flows imply.
-   **One `security-posture` playbook is required** (2026-07-26): the repo's trust
-   boundaries (what's server-exposed vs build-time), auth chokepoints (where
-   authz is enforced — cited), and the secret-handling convention (where env
-   names are read; names only, per the step-4 guardrail). This is durable
-   KNOWLEDGE, not findings — it grounds bloom's security profile
-   ([rafa-security](../rafa-security/SKILL.md)): reachability annotations on
+   **One `security-posture` playbook is required** (owner 2026-07-26): the repo's
+   trust boundaries (what's server-exposed vs build-time), auth chokepoints
+   (where authz is enforced — cited), and the secret-handling convention (where
+   env names are read; names only, per the step-4 guardrail). This is durable
+   KNOWLEDGE, not findings — it is the flow-trace of the repo's trust surface,
+   and it grounds bloom's security profile
+   ([rafa-security](../rafa-security/SKILL.md)): the reachability annotations on
    CVE rows come FROM this note's map.
 
 7. **Verification & synthesis** — apply the 100× filter (a note earns a file only if it
@@ -246,10 +247,38 @@ subagent it calls in step 1/5. **`init`** = ensure structure idempotently (`.raf
 pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS) — skips improve
 + push, a cheap knowledge refresh.
 
-1. **Scan — spawn `atlas`** context-isolated: *"Run the scan per this SOP: comprehensive,
-   breadth-before-depth, cited notes → `.rafa/brain/{rules,playbooks}/` + `coverage.md`. Run
-   `npx @rafinery/cli verify-citations` until it **exits 0**. Return a coverage summary only —
-   not the raw reads."*
+0. **RESOLVE THE REAL BRAIN FIRST — mandatory and mechanical (the canonical
+   continuity law, [contract §12.4](../../rafa/contract.md)).** Before ANY scan
+   step, run `npx @rafinery/cli pull --full` — materialize the org brain into
+   `.rafa/` and confirm it sits at the brain remote's HEAD
+   (`git -C .rafa fetch origin && git -C .rafa status`). A stale local `.rafa`
+   (e.g. parked on an old genesis commit) is exactly how a session scans blind
+   and mints a parallel brain (the incident this step exists to prevent — see
+   the anti-patterns). **Founding is PLATFORM truth, never local emptiness**:
+   founding ⇔ the platform serves zero knowledge
+   (`search_knowledge`/`list_improvements` both empty). If ANY notes exist, this
+   is a **REFRESH**, not a founding scan:
+   - **Ids are stable forever.** One concept = one id. atlas UPDATES the
+     existing file in place (content, cites, links); it NEVER mints a new id
+     for a concept an existing note covers.
+   - **Retirement is a TOMBSTONE, never a deletion** (the §2 lifecycle law): set
+     `status: retired` in the existing file and append a dated `## Retired`
+     body section — why it no longer holds, what supersedes it (linked).
+     The file stays as history (excluded from recall by the platform);
+     a state change is never recorded by removing a file.
+   - New ids are for genuinely new concepts only — and each new note names, in
+     its body, why no existing note covers it.
+   - The founding-scan coach offer (step 9) NEVER fires on a refresh.
+1. **Scan — spawn `atlas`** context-isolated. On a REFRESH, the spawn prompt
+   MUST carry the existing inventory: *"REFRESH mode — the org brain is
+   materialized under `.rafa/brain/` (<N> rules · <M> playbooks · <K>
+   improvements). Update in place: ids are stable; never write a new note for
+   a concept an existing note covers; deletions are explicit. Run the scan per
+   this SOP: comprehensive, breadth-before-depth, cited notes →
+   `.rafa/brain/{rules,playbooks}/` + `coverage.md`. Run
+   `npx @rafinery/cli verify-citations` until it **exits 0**. Return a
+   coverage summary only — not the raw reads."* (Founding keeps the same
+   prompt minus the refresh preamble.)
 2. **Gate 1 — checker (trust-but-verify):** re-run `npx @rafinery/cli verify-citations`
    yourself. Must **exit 0** (else re-spawn atlas to fix). It writes `citation-check.md`.
 3. **Gate 2 — prism:** spawn `prism` **context-isolated**, passing ONLY: *"Validate the scan
@@ -344,6 +373,11 @@ The report must state PASS/FAIL **per criterion** (not a summary verdict), so it
 targets the exact failing box.
 
 ## Anti-patterns (do NOT do)
+- **Scan without pulling the real brain (the parallel-brain incident,
+  2026-07-27).** A blind re-scan mints new ids for concepts that already have
+  notes — 28 duplicates against 14 existing notes, zero continuity. Step 0 is
+  mandatory; the reconciler's duplicate guard will CONTEST parallel notes, but
+  contested duplicates are cleanup, not a workflow.
 - Cherry-pick the flashiest seam — the exact failure this capability prevents.
 - Single-file conventions only — the old scan's shallowness.
 - **Inferred / sampled / from-memory citations** — every `file:line` is grep-or-read

package/blueprint/.claude/skills/rafa-security/SKILL.md

@@ -6,9 +6,10 @@ description: "rafa SOP — the security profile: run the self-contained `rafa au
 # security — the profile  (woven, never a command)
 
 rafa's security posture is **woven into the loop, not a chore**: the dev never
-types a security command. Owner doctrine (2026-07-26 r2): *"security is not an
-aftermath — it is an integral part of the development cycle."* The engine
-fires at every moment of that cycle:
+types a security command. Owner doctrine (owner 2026-07-26, consolidated in
+[contract §12.5](../../rafa/contract.md)): *"security is not an aftermath — it
+is an integral part of the development cycle."* The engine fires at every
+moment of that cycle:
 
 - **plan** — the audit runs before approval and its picture is presented to
   the dev verbatim (rafa-plan §3b): totals + blast-radius criticals; clean is
@@ -28,9 +29,13 @@ the platform's Security tab reads the merge-level rows.
 Run **`npx @rafinery/cli audit --json`** and parse the `rafa.audit/v1`
 envelope. The engine is SELF-CONTAINED — it needs no installs, ever:
 
-- **dependency** — built-in pnpm-lock parser + the OSV.dev advisory API,
-  merged with `pnpm audit`; per finding: package · GHSA/CVE + aliases ·
-  severity + CVSS · direct-vs-transitive chain · fixed-in · dev-only flag.
+- **dependency** — a built-in **multi-manager** lockfile parser (pnpm · npm ·
+  yarn · bun, resolved dynamically richest-first — never a pnpm hardcode) +
+  the keyless OSV.dev advisory API, merged with `pnpm audit` on pnpm repos;
+  per finding: package · GHSA/CVE + aliases · severity + CVSS ·
+  direct-vs-transitive chain (pnpm/npm; yarn/bun are honestly packages-only) ·
+  fixed-in · dev-only flag. No lockfile → the tier is `ran:false` and
+  `rafa doctor` prints the per-manager command to generate one.
 - **secrets** — built-in curated ruleset over tracked files (`.env*` never
   opened; fingerprints, never secret bytes). gitleaks enhances if present.
 - **sast** — semgrep if installed (pinned `p/security-audit`), otherwise the
@@ -59,8 +64,10 @@ Required frontmatter as ever (`title` · `summary` · `fix` · `leverage` ·
 
 **Reconcile like any improvement**: dedupe against existing rows by the stable
 finding id (in the body); auto-close rows whose finding vanished from a fresh
-audit (`status: fixed` — the lockfile bump landed); preserve the dev's triage
-(backlog/wontfix stay).
+audit (`status: fixed` — the lockfile bump landed) **with a dated closure line
+in the body naming the evidence (the new lockfile version / the vanished
+advisory) — a tombstone, never a removal** (the §2/§12.4 lifecycle law);
+preserve the dev's triage (backlog/wontfix stay).
 
 ## Brain-ground the reachability (the judgment part)
 

package/lib/blueprint.mjs

@@ -41,7 +41,6 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-commit",
     ".claude/skills/rafa-review",
     ".claude/skills/rafa-improve",
-    ".claude/skills/rafa-distill",
     ".claude/skills/rafa-insights",
     ".claude/skills/rafa-leverage",
     ".claude/skills/rafa-sage",

package/lib/doctor.mjs

@@ -27,7 +27,7 @@ export async function runDoctor(ROOT = process.cwd()) {
   console.log("rafa doctor — proving the capture machinery\n");
 
   // 1 · provisioning — the same resolution the real tools use, so a doctor
-  // pass here means checkpoint/distill auth will resolve identically.
+  // pass here means checkpoint/reconcile auth will resolve identically.
   console.log("• provisioning");
   let provisioned = false;
   try {

package/lib/gate/compile.mjs

@@ -221,9 +221,15 @@ export function runCompile(argv = []) {
         const t = citeTargetTokens(c.file);
         if (t !== null) c.targetTokens = t;
       }
+      // Lifecycle (r7c, tombstone doctrine): notes are NEVER deleted — a
+      // retired note keeps its file with `status: retired` + a dated body
+      // section explaining why. Optional; absent = active by contract.
+      if ("status" in data && !isEnum(data.status, ["active", "retired"]))
+        fail(path, "status", "optional · active|retired (retirement is a tombstone, never a deletion)");
       notes.push({
         id,
         kind,
+        ...(data.status === "retired" ? { status: "retired" } : {}),
         type: reqEnum(
           data,
           "type",
@@ -844,11 +850,12 @@ export function runCompile(argv = []) {
     return count;
   }
 
-  // sage's learnings (.claude/rafa/learnings/*.md) — the same self-describing
-  // protocol outside the bundle (§11), mechanically gated: OKF quartet + stable
+  // sage's learnings (.rafa/learnings/*.md) — a gitignored `.rafa/` sibling of
+  // the improvement ledger (2026-07-27); durable via the brain-repo mirror + the
+  // platform DB. Self-describing (§11), mechanically gated: OKF quartet + stable
   // id. ledger.md there is sage's generated index (skipped like a listing).
   function compileLearnings() {
-    const dir = join(ROOT, "..", ".claude", "rafa", "learnings");
+    const dir = join(ROOT, "learnings");
     let count = 0;
     for (const path of walk(dir)) {
       const name = path.split("/").pop();

package/lib/gate/verify-citations.mjs

@@ -263,7 +263,14 @@ export function runVerifyCitations(argv = []) {
 
   for (const note of notes) {
     const rel = note.replace(ROOT + "/", "");
-    const lines = readFileSync(note, "utf8").split("\n");
+    const raw = readFileSync(note, "utf8");
+    // TOMBSTONES are history, not claims (r7c): a retired note / closed
+    // improvement keeps its (possibly dead) citations as the record of what it
+    // once claimed — the checker skips them entirely; only LIVE knowledge is
+    // verified. (status: is frontmatter-only, so a body mention can't trip this.)
+    const fm = raw.startsWith("---") ? (raw.split("\n---")[0] ?? "") : "";
+    if (/^status:\s*(retired|fixed|wontfix)\s*$/m.test(fm)) continue;
+    const lines = raw.split("\n");
     const cites = [];
     const anchors = [];
     const absents = [];

package/lib/migrations/index.mjs

@@ -28,7 +28,8 @@
 //     run: (cwd) => backfillPlanField(cwd, "owner", ownerOf(cwd)),
 //   };
 
-import { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { cmpSemver } from "../releases.mjs";
 
@@ -121,7 +122,53 @@ const plans_v1_to_v2 = {
   },
 };
 
-export const MIGRATIONS = [blueprint_split_0_4_0, plans_v1_to_v2];
+// 0.15.0: learnings become a `.rafa/` sibling of the improvement ledger (owner
+// 2026-07-27). They used to be COMMITTED under `.claude/rafa/learnings/` (MR-
+// gated governance); the new model stores them like improvements — gitignored
+// `.rafa/learnings/`, durable via the brain-repo mirror + the platform DB. This
+// relocates a consumer's existing committed learnings and untracks the old copy
+// (git rm --cached; the files themselves MOVE, nothing is dropped).
+const learnings_to_rafa_0_15_0 = {
+  id: "learnings-to-rafa-0.15.0",
+  kind: "config",
+  mode: "mechanical",
+  summary:
+    "learnings move `.claude/rafa/learnings/` → `.rafa/learnings/` (a gitignored " +
+    "sibling of the improvement ledger; durable via the brain repo + the platform DB)",
+  appliesTo: (from, to) =>
+    cmpSemver(from.cli, "0.15.0") < 0 && cmpSemver(to.version, "0.15.0") >= 0,
+  run: (cwd) => {
+    const src = join(cwd, ".claude", "rafa", "learnings");
+    const dst = join(cwd, ".rafa", "learnings");
+    if (!existsSync(src)) return { changed: [], notes: ["no committed learnings — nothing to migrate"] };
+    const changed = [];
+    mkdirSync(dst, { recursive: true });
+    for (const name of readdirSync(src)) {
+      const s = join(src, name);
+      if (!statSync(s).isFile()) continue;
+      const d = join(dst, name);
+      if (!existsSync(d)) writeFileSync(d, readFileSync(s, "utf8")); // MOVE the content, never drop it
+    }
+    // Untrack the old committed copies (best-effort — a non-git checkout still
+    // gets the physical move above) and remove the emptied directory.
+    try {
+      execSync(`git rm -r -q --cached --ignore-unmatch ${JSON.stringify(join(".claude", "rafa", "learnings"))}`, { cwd, stdio: "ignore" });
+    } catch {
+      /* not a git repo / already untracked — the filesystem move is what matters */
+    }
+    rmSync(src, { recursive: true, force: true });
+    changed.push(".claude/rafa/learnings/ → .rafa/learnings/");
+    return {
+      changed,
+      notes: [
+        "learnings are now a gitignored `.rafa/` sibling of the improvement ledger — " +
+          "durable via the brain-repo mirror + the platform DB; commit the removal of the old `.claude/rafa/learnings/`.",
+      ],
+    };
+  },
+};
+
+export const MIGRATIONS = [blueprint_split_0_4_0, plans_v1_to_v2, learnings_to_rafa_0_15_0];
 
 // The migrations that apply to a given move (stamped `from` → shipped `to`), in order.
 export function pendingMigrations(from, to) {

package/lib/releases.mjs

@@ -456,6 +456,51 @@ export const RELEASES = [
       "lockfile and prints the per-manager generate command. review.json " +
       "joins the brain-repo bootstrap ignore.",
   },
+  {
+    version: "0.14.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "CONTINUITY + CLEAN SOP + DISTILL REMOVED (owner 2026-07-27). CONTINUITY " +
+      "IS THE PRODUCT: scans/improves are REFRESH-FIRST — Step 0 `pull --full` " +
+      "+ brain-remote-HEAD check before any pass; founding = PLATFORM truth " +
+      "(zero knowledge served), never local emptiness; ids are STABLE FOREVER, " +
+      "refresh updates in place, triage + debt-trend never reset. The " +
+      "reconciler's PARALLEL-BRAIN GUARD contests a NEW note/improvement that " +
+      "overlaps an existing one (same domain/category + equal title OR ≥50% " +
+      "shared cited files vs the trunk manifest) — fold into the existing id " +
+      "or defend a genuinely new one; duplicates never bank silently. CLOSURES " +
+      "ARE TOMBSTONES, never deletions: notes gain `status: retired` + a dated " +
+      "`## Retired` section, improvements close `status: fixed|wontfix` + a " +
+      "dated evidence line — recall excludes tombstones, verify-citations " +
+      "skips them, the reconciler's prune WRITES the tombstone. The whole " +
+      "capture/continuity/security doctrine is CONSOLIDATED in contract §12 " +
+      "(the guarded loop: moments · signals · gates · lanes) and every " +
+      "agent/skill/reconciler SOP rewritten clean against it. The DISTILL " +
+      "surface is REMOVED (the rafa-distill skill + the `distill`/`ci-setup` " +
+      "commands): reconciliation is SERVER-SIDE only, the reconciler is the " +
+      "org brain's single writer. All guards resolve the trunk DYNAMICALLY " +
+      "(stamped prodBranch → origin/HEAD → main) — the configurable default " +
+      "branch is honored across checkpoint, guard, branch-merge audit, and " +
+      "reconciliation; no path hardcodes main.",
+  },
+  {
+    version: "0.15.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "LEARNINGS ARE A `.rafa/` SIBLING (owner 2026-07-27): sage's learnings " +
+      "move `.claude/rafa/learnings/` → `.rafa/learnings/` — stored like the " +
+      "improvement ledger (gitignored locally, durable via the brain-repo " +
+      "mirror + the platform DB `agentLearnings`), each an OKF `type: Learning` " +
+      "concept gated by the quartet. `rafa update` runs a MECHANICAL migration " +
+      "that relocates a repo's existing committed learnings and untracks the " +
+      "old copy (files MOVE, nothing dropped). The committed-`.claude/`-" +
+      "governance framing is retired; the DB is the store, `.rafa/learnings/` " +
+      "the local working copy — no learning files clutter `.claude/`.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {

package/skills-bundle/skills-manifest.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-26T18:16:15.258Z",
+  "generatedAt": "2026-07-26T22:32:00.748Z",
   "skills": {
     "tdd": {
       "version": "1.0.0",

package/blueprint/.claude/skills/rafa-distill/SKILL.md

@@ -1,126 +0,0 @@
----
-name: rafa-distill
-description: "rafa SOP — merge-time reconciliation: validate a merged branch's WORKING SET against merged MAIN (prism), author survivors into the org brain through verify-citations + compile + push (atlas), refute loudly with citations; contested items flagged needs-adjudication, never guessed. Loaded on /rafa distill or the merge offer; CI runs the same SOP headlessly (rafa distill --headless)."
----
-
-# distill — merge-time reconciliation of a branch working set into the org brain
-
-> Status: **active.** Two runners, ONE SOP: the org's CI (`rafa distill
-> --headless`, installed by `rafa ci-setup`, driven by the ORG'S OWN
-> `ANTHROPIC_API_KEY` — never stored on the platform) and the dev session
-> (offer-driven at bootstrap, or explicit `/rafa distill <branch>`) as the
-> fallback when CI isn't wired or failed. Depends on: brain (#1), the branch
-> working set (synced via `rafa checkpoint`).
-
-The rigor gradient this enforces (ratified 2026-07-10): **dev↔dev = CAS + a
-session prompt · branch↔branch = free mechanical fold (no LLM, no prism) ·
-branch→main = full distillation + gates.** Cost tracks consequence. Working-set
-files are candidate-grade — attributed, loose, never served as org truth. The
-merge to main is the one moment rigor fires: what survives validation against
-merged main enters the org brain through the normal gates; what doesn't is
-refuted loudly back to its author; what can't be decided is flagged
-`needs-adjudication` — NEVER guessed. Knowledge propagates exactly like the
-code it describes.
-
-## Trigger
-
-- **CI (normal path):** the reconcile workflow fires on the PR-merged EVENT
-  (squash/rebase-safe — ancestry is never consulted): merge to the default
-  branch → `rafa distill --headless <branch>` · branch→parent merge →
-  `rafa fold --from <branch> --to <parent>` (mechanical, no LLM).
-- **Offer (session fallback):** at bootstrap the conductor checks
-  `get_working_set` for active files on branches whose code reached main —
-  *"branch <x> merged with N working-set files — distill now?"* Part of the
-  ONE bootstrap digest. Boundary consent; accepted offer = invocation.
-- **Explicit:** `/rafa distill <branch>`.
-
-## Procedure (the trio, distillation roles)
-
-1. **Collect** — `get_working_set(repo, branch, status: active)`. Zero files →
-   nothing to do, say so, stop. Rows already `needs-adjudication` are a HUMAN's
-   to resolve — surface them in the digest, never fold them in silently.
-1b. **Schema ladder (0.11.0 — the owner's 4-case doctrine).** Before ANY
-   claim-level judging, resolve the version lattice: **target** = the org
-   brain's `manifest.json → schemaVersion` (else max over its notes; a
-   pre-manifest brain is the founding v1) · **source** = max over the
-   collected candidates' own `schemaVersion` · **latest** = the running CLI's
-   `SCHEMA_VERSION`. Then: **target < source → REWRITE-TARGET** (every org-
-   brain note lifts to the newer schema and rides THIS run's gates + push —
-   one migration+reconcile commit) · **target > source → UPGRADE-SOURCE**
-   (incoming candidates lift into the target's schema before judging) ·
-   **equal but < latest → REWRITE-MERGED** (both lift; the merged target is a
-   full rewrite onto latest) · **equal and == latest → DIFF** (the happy flow,
-   steps 2–6 exactly as written). **Either side > latest → ABORT LOUDLY** — a
-   newer CLI authored it; update the runner, knowledge is never downgraded.
-   Transforms are REGISTERED per step AND per OKF type
-   (`lib/distiller/schema-ladder.mjs` — each step declares rule · playbook ·
-   improvement explicitly: a function, or the EXPLICIT "unchanged", which
-   still re-stamps the note's schemaVersion line); a missing step OR class is
-   a loud error, never a guess. Only durable knowledge ladders — derived/
-   generated files (coverage · checklist · ledger · reports · manifest)
-   REGENERATE at the new schema; intent records pass through untouched. The
-   headless CLI runs this mechanically; the session path applies the same
-   lattice by hand.
-2. **Validate (prism, context-isolated)** — the target is **merged MAIN as of
-   NOW, never the fork point and never a stale checkout**: `git fetch origin`
-   first; judge every claim against the fetched trunk. Confirm every citation
-   resolves (the cited line contains its token — grep it yourself). A claim
-   that can't be confirmed with a `file:line` is REFUTED (cited reason).
-   Contested/low-confidence → `needs-adjudication`, never a guess. Files about
-   code the merge did NOT touch are judged on their own merits, same bar.
-3. **Author (atlas)** — for each survivor: write/update the org-brain file
-   (contract §2) with real cites into main; `anchor:` on contracts (hydrated
-   files lost it — re-declare); fold into an existing note when one covers the
-   topic (supersede, never duplicate).
-4. **Gate + ship** — `rafa verify-citations` AND `rafa compile` to exit 0 →
-   `rafa push --verb=distill --message="reconcile(<branch>): <N> banked ·
-   <M> refuted · <K> adjudication — <banked ids…>"`. The reconciliation
-   commit is DESCRIPTIVE (owner 2026-07-26): its subject states what THIS run
-   did — branch, per-verdict counts, the banked note ids — so any agent
-   walking the brain log understands the commit without opening it (the
-   headless CLI composes this automatically; the session path passes it
-   explicitly). Only now has anything entered the org brain. A failed gate
-   aborts EVERYTHING: nothing resolved, nothing pushed, working set intact.
-5. **Resolve** — `resolve_working_file(path, distilled)` for survivors — authored
-   per the OKF surface ([rafa-okf](../rafa-okf/SKILL.md); push emits the rest) —
-   CAS: only a live row resolves; a failure means ANOTHER runner already
-   distilled this branch — STOP and reconcile against what it shipped.
-   `resolve_working_file(path, refuted, note)` for failures — TELL the author
-   which files died and why (cited); refutation is feedback, not silence. At
-   that same resolve beat emit **`report_loop_event(category:
-   "distill-refutation", outcome: refuted|distilled, subject: <path or note
-   id>, actorMeta: {model: <the judging model>, agent: "distiller@<ver>" (or
-   "prism@<ver>" on the session path), runner: session|ci|sandbox — the tier
-   this distill runs in}, dedupeKey: "<branch>·<path>·<outcome>")`** — sage's
-   evidence that a claim met the gates or was refuted (shapes only: the
-   outcome + a file/note reference, never the refuted content, never the
-   cited code). Wave 5 is STRICT: an emit without the actor envelope is
-   rejected loudly; the dedupeKey makes a re-run of the same distillation
-   count ONCE. Checkpoint-adjacent, monotonic, never a session-end sweep.
-   `resolve_working_file(path, needs-adjudication, note)` for the undecidable —
-   the next session's digest offers the decision.
-
-## Branch→branch merges (sub-feature → feature): FOLD, don't distill
-
-Distillation targets ONLY the default branch. When a sub-feature merges into
-its parent branch, the working set is **folded forward mechanically** —
-`rafa fold --from <branch> --to <parent>` (or the CI fold job): absent on the
-parent → re-keyed · identical content → merged silently · true same-file
-divergence → `needs-adjudication` on the parent row (incoming preserved,
-attributed). No LLM, no prism — the knowledge keeps riding with the code until
-the code reaches main.
-
-Sub-feature CONTEXT: a branch's working knowledge = org brain (via MCP) + its
-own working set + unmerged ANCESTOR branches' working sets (the conductor
-derives the ancestor chain from git and calls `get_working_set` per ancestor —
-the platform stores no lineage).
-
-## Rules
-
-- Validation target is main at distillation time, never the fork point.
-- An abandoned branch's working set is never distilled — it dies with the
-  branch (propagation mirrors code).
-- No file skips steps 2–4; there is no fast path into the org brain.
-- CI can detect and flag; only a dev session resolves a human's divergence.
-- Dev-level observations found among the files route to `put_dev_insight`
-  (the author's user brain), never to the org brain.