@rafinery/cli 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.11.0 — schema-aware reconciliation (the 4-case ladder)
+
+Distillation is where knowledge from two lineages meets — so it is now also
+where brain SCHEMA VERSIONS meet. Before any claim-level judging, the
+reconciler resolves target (the org brain) vs source (the branch's candidates)
+vs the runner's own latest schema:
+
+1. **target < source** → full target-brain rewrite onto the newer schema,
+   riding the same run's gates + push (one migration+reconcile commit).
+2. **target > source** → incoming old-schema candidates lift into the
+   target's schema before judging.
+3. **target == source, both < latest** → the merged target rewrites onto the
+   runner's latest.
+4. **target == source == latest** → plain diff reconcile — the happy flow,
+   exactly as before.
+
+Either side NEWER than the runner aborts loudly — 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 version line; derived/generated files regenerate
+at the new schema, they never migrate); a missing step or class fails
+loudly — the ladder never guesses a schema. v1 is the only schema in existence, so today
+every reconcile is case 4; this ships the SEAM (fully tested) that turns a
+future v2 into a one-entry registry change instead of a migration crisis.
+
+**Descriptive commits (owner 2026-07-26).** Reconciliation commits now SAY
+what the run did: the headless distiller composes
+`reconcile(<branch>): N banked · M refuted · K adjudication — <ids…>` and
+passes it via the new `rafa push --message=` override (the brain-for trailer
+is untouched — provenance consumers keep their key); the session SOP carries
+the same rule. And the commit contract (rafa-commit) now REQUIRES an
+agent-readable body on dev commits: what concretely changed, the why the diff
+can't show, brain-note join keys, no session deixis — the next reader of a
+commit is usually an agent.
+
+**The configurable prod branch reaches the CLI.** `trunkBranchOf` resolves
+the stamped `rafa.json → prodBranch` → git's origin/HEAD → "main"; the
+checkpoint trunk guard and the CI distill target use it (with prodBranch set,
+"main" can be a plain feature-carrying branch). The platform side shipped the
+`repos.prodBranch` setting + repo-page card in the same arc.
+
+Also in this release (landed after 0.10.0's publish): distill-refutation loop
+events carry the required actor envelope + a dedupeKey (a retried distill
+counts each resolution once); `cliActorMeta` honors `RAFA_ACTOR_RUNNER` for
+sandbox/CI attribution; and dependsOn invalidation is documented as NOT
+transitive, with breadth-of-declaration taught as the conservative pattern at
+`rafa facts add`, the CLI help, and prism's citation rule (pinned by test).
+
 ## 0.10.0 — wave 6: the capability arc (skill dependencies + agent upgrades)
 
 rafa's agents get materially better at engineering — and the mechanism is the

package/blueprint/.claude/rafa/contract.md

@@ -455,6 +455,23 @@ imported comments are never scraped into decisions.
   fields do NOT bump it** — e.g. the note size stamps (`bodyTokens`,
   `cites[].targetTokens`, §1): ingest tolerates their absence, so a legacy manifest
   without them stays valid at the same `schemaVersion`.
+- **The reconciliation schema ladder (0.11.0 — owner's 4-case doctrine).** When a
+  version bump DOES ship, distillation is the upgrade moment — the reconciler
+  resolves target-vs-source-vs-runner before judging: target below source → full
+  target rewrite onto the newer schema; source below target → incoming candidates
+  lift before judging; both equal-but-old → the merged target rewrites onto the
+  runner's latest; both current → plain diff (today). Either side newer than the
+  runner → **abort loudly** (update the runner; knowledge is never downgraded).
+  Transforms are registered per step AND per OKF type in the CLI
+  (`lib/distiller/schema-ladder.mjs`): each step declares rule · playbook · improvement
+  explicitly — a function, or the EXPLICIT `"unchanged"` (still re-stamps the note's
+  `schemaVersion:`); an unregistered step or class fails loudly — the ladder never
+  guesses a schema. Class resolves by CHAIN: the governed directory first (inside the
+  transport the path IS identity — the CAS row key), then the portable filename suffix
+  (`.rule.md` · `.playbook.md` · `.improvement.md`) for files travelling outside the
+  canonical tree; a contradiction between the two is a loud error. Only durable
+  knowledge migrates; derived/generated files
+  (coverage · checklist · ledger · reports · the manifest) regenerate at the new schema.
 - **Validate-and-correct:** `rafa compile` validates every file. On failure it emits
   a structured error — `path · field · rule` — to the **authoring agent** (atlas for
   notes, bloom for improvements/ledger, prism for checklist). The agent edits the

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

@@ -36,6 +36,28 @@ description: "rafa SOP — generate the commit message with the id join-key: the
    outcome one-line ("Done-check: prism PASS") — the receipt travels with the
    code.
 
+## The body is REQUIRED and written for an AGENT reader (owner 2026-07-26)
+
+A subject-only commit is a broken contract here. The next reader of this
+message is most often an AGENT — ours (atlas recalling why a line exists, the
+distiller judging a claim against this change, sage reading shapes) or a
+foreign one — so the body must be SELF-CONTAINED and joinable:
+
+- **What, concretely** — the surfaces/behaviors that changed, named (not
+  "various fixes"); a reader must know the blast radius without the diff.
+- **Why — the intent** — the one thing the diff cannot show. State the
+  problem/decision that made this change necessary; paraphrase the pivotal
+  choice if one was made (it should also be a `log_decision`).
+- **Join keys** — mention the brain notes this change follows or invalidates
+  (`per rule <id>` / `staleness: touches <id>`), so the cite-graph and the
+  dirty queue read straight out of the log.
+- **No session deixis** — never "as discussed", "per the above", "the same
+  fix as before": the message must stand alone in `git log` a year later,
+  with zero conversation context.
+
+TDD-default red commits keep their fixed form (`[<task-id>] test: red —
+<seam>`) — the seam IS the body's content there.
+
 ## Why this exists (don't skip the bracket)
 
 The brain-commit hook captures every subject into `intent/<sha>.md`;

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

@@ -39,6 +39,28 @@ code it describes.
 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
@@ -51,7 +73,13 @@ code it describes.
    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`. Only now has anything entered the org brain. A failed gate
+   `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) —
@@ -61,9 +89,14 @@ code it describes.
    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>)`** — 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). Checkpoint-adjacent, monotonic, never a session-end sweep.
+   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.
 

package/lib/checkpoint.mjs

@@ -108,11 +108,20 @@ export default async function checkpoint() {
 
   // The working set is BRANCH state. On the trunk, knowledge changes go
   // through scan → compile → rafa push (the org brain's one writer surface).
-  if (branch === "main" || branch === "master") {
-    console.log(
-      `• on ${branch} — the working set is branch-scoped; org-brain changes on the trunk go through /rafa scan + rafa push. Nothing to checkpoint.`,
-    );
-    return;
+  // The trunk is RESOLVED, never hardcoded (owner 2026-07-26): the stamped
+  // prodBranch → origin/HEAD → "main"; the main|master pair stays as a belt
+  // ONLY for unconfigured repos (with prodBranch set, "main" can be a plain
+  // feature-carrying branch and its working set checkpoints normally).
+  {
+    const { trunkBranchOf, readStamp } = await import("./stamp.mjs");
+    const trunk = trunkBranchOf(ROOT);
+    const configured = typeof readStamp(ROOT).prodBranch === "string";
+    if (branch === trunk || (!configured && (branch === "main" || branch === "master"))) {
+      console.log(
+        `• on ${branch} (the trunk) — the working set is branch-scoped; org-brain changes on the trunk go through /rafa scan + rafa push. Nothing to checkpoint.`,
+      );
+      return;
+    }
   }
 
   // The commit this capture is grounded against (contract: capturedAtSha —

package/lib/distill.mjs

@@ -40,8 +40,17 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { callTool } from "./mcp-client.mjs";
-import { runCompile } from "./gate/compile.mjs";
+import { trunkBranchOf } from "./stamp.mjs";
+import { runCompile, SCHEMA_VERSION } from "./gate/compile.mjs";
 import { runVerifyCitations } from "./gate/verify-citations.mjs";
+import {
+  applyLadder,
+  brainSchemaVersion,
+  classOf,
+  resolveSchemaPlan,
+  sourceSchemaVersion,
+  walkBrainNotes,
+} from "./distiller/schema-ladder.mjs";
 import pull from "./pull.mjs";
 import push from "./push.mjs";
 
@@ -192,7 +201,7 @@ export default async function distill(args = []) {
     try {
       await callTool(ROOT, "report_distill_run", {
         branch,
-        toBranch: process.env.RAFA_TARGET_BRANCH || "main",
+        toBranch: process.env.RAFA_TARGET_BRANCH || trunkBranchOf(ROOT),
         mergeCommitSha: mergeSha,
         status,
         note: summary,
@@ -371,6 +380,35 @@ export default async function distill(args = []) {
   await pull(["--full"]);
   console.log(`  ⏱ brain mirror: ${secs(tPull)}s`);
 
+  // 2b · SCHEMA LADDER (0.11.0 — the owner's 4-case doctrine): resolve the
+  // version lattice BEFORE any claim-level judging, so knowledge from two
+  // lineages always meets on ONE schema — the newest this runner understands.
+  // Lifted target notes ride THIS run's gates + push (one migration+reconcile
+  // commit); an unknown future schema aborts loudly, never downgrades.
+  {
+    const target = brainSchemaVersion(join(ROOT, ".rafa"));
+    const source = sourceSchemaVersion(active.map((f) => f.content));
+    const plan = resolveSchemaPlan({ target, source, latest: SCHEMA_VERSION });
+    console.log(
+      `• schema ladder: target v${target} · source v${source} · runner v${SCHEMA_VERSION} → ${plan.mode}`,
+    );
+    if (plan.mode === "abort-newer-than-runner") die(plan.reason);
+    if (plan.mode !== "diff") console.log(`  ${plan.reason}`);
+    // Per-OKF-type lifts (class derives from the PATH — typed-candidates
+    // doctrine); non-laddered paths (intent records …) pass through untouched.
+    if (plan.upgradeSource)
+      for (const f of active) {
+        const cls = classOf(f.path);
+        if (cls) f.content = applyLadder(f.content, plan.toVersion, cls);
+      }
+    if (plan.rewriteTarget)
+      for (const noteFile of walkBrainNotes(join(ROOT, ".rafa"))) {
+        const cls = classOf(noteFile);
+        if (cls)
+          writeFileSync(noteFile, applyLadder(readFileSync(noteFile, "utf8"), plan.toVersion, cls));
+      }
+  }
+
   // 3 · stage the incoming working set for the agent (gitignored inside .rafa).
   const stagingRoot = join(ROOT, ".rafa", "distill-incoming");
   rmSync(stagingRoot, { recursive: true, force: true });
@@ -554,7 +592,22 @@ ${fileList}`;
     (f) => byPath.get(f.path).verdict === "distilled",
   ).length;
   if (distilledCount > 0) {
-    await push(["--verb=distill"]);
+    // Descriptive reconciliation commit (owner 2026-07-26): the subject says
+    // WHAT this run did — branch, per-verdict counts, the banked ids — so any
+    // agent (ours or a foreign OKF reader) walking the brain log understands
+    // the commit without opening it. brain-for trailer untouched (push owns it).
+    {
+      const counts = { distilled: 0, refuted: 0, "needs-adjudication": 0 };
+      for (const v of verdicts) counts[v.verdict] = (counts[v.verdict] ?? 0) + 1;
+      const banked = verdicts
+        .filter((v) => v.verdict === "distilled")
+        .map((v) => String(v.path).split("/").pop().replace(/\.md$/, ""));
+      const idList = banked.slice(0, 4).join(", ") + (banked.length > 4 ? " …" : "");
+      await push([
+        "--verb=distill",
+        `--message=reconcile(${branch}): ${counts.distilled} banked · ${counts.refuted} refuted · ${counts["needs-adjudication"]} adjudication${banked.length ? ` — ${idList}` : ""}`,
+      ]);
+    }
   } else {
     console.log("• no survivors — nothing to push to the brain repo");
   }

package/lib/distiller/schema-ladder.mjs

@@ -0,0 +1,186 @@
+// The schema ladder (0.11.0 — schema-aware reconciliation, owner's 4-case
+// doctrine, 2026-07-25). Distillation is where knowledge from two lineages
+// meets, so it is ALSO where brain schema versions meet — the reconciler
+// resolves the version lattice BEFORE any claim-level judging, and the merged
+// result always lands on the newest schema the RUNNER understands:
+//
+//   1. target < source            → REWRITE-TARGET: the whole target brain
+//      lifts to the newer schema (the incoming side already speaks it).
+//   2. target > source            → UPGRADE-SOURCE: incoming old-schema
+//      candidates lift into the target's newer schema before judging.
+//   3. target == source < latest  → REWRITE-MERGED: both sides lift; the
+//      merged target is a full rewrite onto the latest schema.
+//   4. target == source == latest → DIFF: the happy flow, exactly today.
+//   ∅. either side > latest       → ABORT LOUDLY: a newer CLI authored this;
+//      this runner cannot judge a schema it does not know — update the
+//      runner, NEVER downgrade knowledge.
+//
+// Every non-abort mode converges in ONE pass: toVersion is always the
+// runner's latest (which case 1/2's higher side already equals or precedes —
+// the runner can never know less than what it authored). Transforms are
+// REGISTERED per step (v(N-1)→vN) in LADDER below; a missing step throws —
+// the ladder never guesses a schema (no assumed values). v1 is the baseline
+// and the only schema in existence today, so the registry ships empty: this
+// module is the SEAM, proven by tests, that makes a future v2 a one-entry
+// change instead of a migration crisis.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// Per-step, PER-OKF-TYPE transforms (owner 2026-07-26: each file class has its
+// own shape in the contract's type registry, so each ladder step declares each
+// class EXPLICITLY):
+//
+//   LADDER[2] = {
+//     describe: "what v2 changes",
+//     rule: (content) => content2,     // a real shape change for rules
+//     playbook: "unchanged",           // EXPLICIT identity — visible, auditable
+//     improvement: (content) => …,
+//   }
+//
+// Only the three DURABLE knowledge classes ladder (rule · playbook ·
+// improvement — the classes distillation judges and the brain keeps). Derived/
+// generated files (coverage, checklist, ledger, reconciliation reports,
+// manifest) are NEVER migrated — their producers regenerate them at the new
+// schema. A step missing a class entry is a LOUD error, not implicit identity:
+// "unchanged" must be declared, never assumed. Every applied step (identity
+// included) re-stamps the note's own `schemaVersion:` line.
+export const LADDER = {};
+
+export const LADDER_CLASSES = ["rule", "playbook", "improvement"];
+
+// Class resolution chain (owner 2026-07-26): DIRECTORY first — inside rafa's
+// transport the path is governed identity (the CAS row key, the registry
+// glob, the hydrate target; it cannot drift without becoming a different
+// row) — then the PORTABLE filename suffix (`.rule.md` · `.playbook.md` ·
+// `.improvement.md`), which travels WITH a file that leaves the canonical
+// tree (foreign OKF bundles, out-of-context shares) while staying outside
+// the corruptible content. When BOTH are present they must AGREE — a
+// contradiction throws loudly, never a guess. Returns null for non-laddered
+// paths (intent records, reports, …) — those pass through untouched.
+const SUFFIX_CLASS = {
+  ".rule.md": "rule",
+  ".playbook.md": "playbook",
+  ".improvement.md": "improvement",
+};
+export function classOf(path) {
+  const p = String(path).replace(/\\/g, "/");
+  const byDir = p.includes("brain/rules/")
+    ? "rule"
+    : p.includes("brain/playbooks/")
+      ? "playbook"
+      : p.includes("improve/improvements/")
+        ? "improvement"
+        : null;
+  const bySuffix =
+    Object.entries(SUFFIX_CLASS).find(([s]) => p.endsWith(s))?.[1] ?? null;
+  if (byDir && bySuffix && byDir !== bySuffix)
+    throw new Error(
+      `schema ladder: directory class "${byDir}" contradicts filename class "${bySuffix}" (${p}) — ` +
+        "fix the file's home or its name; the ladder never guesses",
+    );
+  return byDir ?? bySuffix;
+}
+
+// A note's OWN declared schema (first-fence `schemaVersion:`). Default 1 — the
+// founding schema, same convention as stampedVersions defaulting to the first
+// release (a pre-stamp file predates versioning, it isn't unversioned).
+export function noteSchemaVersion(content) {
+  if (typeof content !== "string" || !content.startsWith("---")) return 1;
+  const end = content.indexOf("\n---", 3);
+  const fm = end === -1 ? content : content.slice(0, end);
+  const m = fm.match(/^schemaVersion:\s*(\d+)\s*$/m);
+  return m ? Number(m[1]) : 1;
+}
+
+const NOTE_DIRS = ["brain/rules", "brain/playbooks", "improve/improvements"];
+
+export function walkBrainNotes(rafaDir) {
+  const out = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (e.endsWith(".md") && !e.startsWith("_") && !e.endsWith(".theirs.md"))
+        out.push(p);
+    }
+  };
+  for (const d of NOTE_DIRS) walk(join(rafaDir, d));
+  return out;
+}
+
+// The TARGET brain's schema: manifest.json first (the compiled truth), else
+// the max over its notes' own declarations, else the founding schema.
+export function brainSchemaVersion(rafaDir) {
+  try {
+    const m = JSON.parse(readFileSync(join(rafaDir, "manifest.json"), "utf8"));
+    if (Number.isInteger(m.schemaVersion)) return m.schemaVersion;
+  } catch {
+    /* no manifest — fall through to the notes */
+  }
+  const versions = walkBrainNotes(rafaDir).map((f) =>
+    noteSchemaVersion(readFileSync(f, "utf8")),
+  );
+  return versions.length ? Math.max(...versions) : 1;
+}
+
+// The SOURCE side's schema: the max over the incoming candidates' own
+// declarations (a working set may be mixed if it straddled an upgrade).
+export function sourceSchemaVersion(contents) {
+  const versions = (contents ?? []).map(noteSchemaVersion);
+  return versions.length ? Math.max(...versions) : 1;
+}
+
+// The lattice. Returns {mode, toVersion, rewriteTarget, upgradeSource, reason}.
+export function resolveSchemaPlan({ target, source, latest }) {
+  if (target > latest || source > latest)
+    return {
+      mode: "abort-newer-than-runner",
+      toVersion: null,
+      rewriteTarget: false,
+      upgradeSource: false,
+      reason:
+        `brain schema v${Math.max(target, source)} is NEWER than this runner's v${latest} — ` +
+        "a newer CLI authored it. Update @rafinery/cli and re-run; knowledge is never downgraded.",
+    };
+  const base = { toVersion: latest, rewriteTarget: target < latest, upgradeSource: source < latest };
+  if (target < source)
+    return { mode: "rewrite-target", ...base, reason: `target v${target} < source v${source} — full target rewrite onto v${latest}` };
+  if (source < target)
+    return { mode: "upgrade-source", ...base, reason: `source v${source} < target v${target} — incoming candidates lift into v${latest}` };
+  if (target < latest)
+    return { mode: "rewrite-merged", ...base, reason: `both sides v${target} < runner v${latest} — merged result rewrites onto v${latest}` };
+  return { mode: "diff", ...base, reason: `both sides already v${latest} — plain diff reconcile` };
+}
+
+const stampVersion = (content, v) =>
+  content.replace(/^schemaVersion:\s*\d+\s*$/m, `schemaVersion: ${v}`);
+
+// Lift ONE note of ONE class from its own declared version to `to`, one
+// registered step at a time. A missing step OR a missing class entry within a
+// step is a loud error, never a guess; the explicit "unchanged" is the only
+// legal identity, and even it re-stamps the note's schemaVersion line.
+export function applyLadder(content, to, cls) {
+  if (!LADDER_CLASSES.includes(cls))
+    throw new Error(
+      `schema ladder: "${cls}" is not a laddered class (${LADDER_CLASSES.join("|")}) — ` +
+        "derived/generated files regenerate at the new schema, they never migrate",
+    );
+  let from = noteSchemaVersion(content);
+  let out = content;
+  while (from < to) {
+    const step = LADDER[from + 1];
+    const t = step?.[cls];
+    if (t === undefined)
+      throw new Error(
+        `schema ladder: no registered ${cls} transform v${from}→v${from + 1} — every step ` +
+          'declares every class (a function, or the EXPLICIT "unchanged"); ' +
+          "update @rafinery/cli to a release that ships it (the ladder never guesses a schema)",
+      );
+    out = t === "unchanged" ? out : t(out);
+    out = stampVersion(out, from + 1);
+    from += 1;
+  }
+  return out;
+}

package/lib/mcp-client.mjs

@@ -18,12 +18,19 @@ import { CLI_VERSION } from "./releases.mjs";
 
 // The CLI's own actor envelope for state-plane writes (wave 5: REQUIRED on every
 // loop event — strict, no legacy path). model is the explicit "mechanical"
-// sentinel: no LLM ruled here, and the split stays grep-able for sage.
+// sentinel: no LLM ruled here, and the split stays grep-able for sage. The
+// runner honors RAFA_ACTOR_RUNNER first (the platform's sandbox distiller and
+// other tiers export it — sandbox|ci|session), else CI env, else session.
 export function cliActorMeta() {
+  const declared = process.env.RAFA_ACTOR_RUNNER;
   return {
     model: "mechanical",
     agent: `cli@${CLI_VERSION}`,
-    runner: process.env.CI ? "ci" : "session",
+    runner: ["sandbox", "ci", "session"].includes(declared)
+      ? declared
+      : process.env.CI
+        ? "ci"
+        : "session",
   };
 }
 

package/lib/push.mjs

@@ -189,6 +189,11 @@ export default async function push(args = []) {
   // on it.
   const verbArg = args.find((a) => a.startsWith("--verb="));
   const verb = verbArg ? verbArg.slice("--verb=".length) : "update";
+  // Custom subject (owner 2026-07-26: reconciliation commits are DESCRIPTIVE):
+  // --message="…" replaces the generic manifest-derived subject; the brain-for
+  // trailer machinery below is untouched — provenance consumers keep their key.
+  const msgArg = args.find((a) => a.startsWith("--message="));
+  const customSubject = msgArg ? msgArg.slice("--message=".length).trim().replace(/"/g, "'") : null;
   const subjectParts = [];
   try {
     const m = JSON.parse(readFileSync(join(rafaDir, "manifest.json"), "utf8"));
@@ -214,9 +219,10 @@ export default async function push(args = []) {
   } catch {
     /* stat is garnish */
   }
-  const subject = `brain(${verb}): ${
-    subjectParts.length ? subjectParts.join(" · ") : "state sync"
-  } · brain-for: ${codeSha}`.replace(/"/g, "'");
+  const subject = (
+    customSubject ??
+    `brain(${verb}): ${subjectParts.length ? subjectParts.join(" · ") : "state sync"} · brain-for: ${codeSha}`
+  ).replace(/"/g, "'");
   try {
     inRafa(
       `git commit -m "${subject}" -m "brain-for: ${codeSha}${stagedStat ? ` · ${stagedStat}` : ""} · cli: ${CLI_VERSION}"`,

package/lib/releases.mjs

@@ -382,6 +382,33 @@ export const RELEASES = [
       "--json` carries the harness-neutral agentSkills + skillDeps blocks; " +
       "doctor gains a capabilities section.",
   },
+  {
+    version: "0.11.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "SCHEMA-AWARE RECONCILIATION (owner's 4-case doctrine): distillation " +
+      "resolves the version lattice BEFORE judging — target below source → " +
+      "full target rewrite onto the newer schema (rides the run's gates + " +
+      "push); source below target → incoming candidates lift before judging; " +
+      "equal-but-old → the merged target rewrites onto the runner's latest; " +
+      "equal-and-current → plain diff (today). Either side newer than the " +
+      "runner aborts LOUDLY (update the runner; knowledge is never " +
+      "downgraded); transforms are registered per step and a missing step " +
+      "fails loudly — the ladder never guesses a schema. Also in this " +
+      "release (missed 0.10.0's publish): distill-refutation emits carry the " +
+      "required actor envelope + dedupeKey (a re-run counts once); " +
+      "cliActorMeta honors RAFA_ACTOR_RUNNER (sandbox|ci|session); dependsOn " +
+      "invalidation documented NOT transitive with breadth-as-conservative " +
+      "taught at facts add/help/prism's card (pinned by test). DESCRIPTIVE " +
+      "COMMITS: reconciliation pushes compose reconcile(<branch>): N banked " +
+      "· M refuted · K adjudication (rafa push --message= override); the " +
+      "commit contract requires an agent-readable body on dev commits. The " +
+      "configurable prod branch reaches the CLI: trunkBranchOf (stamp → " +
+      "origin/HEAD → main) drives the checkpoint trunk guard + CI distill " +
+      "target.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/stamp.mjs

@@ -3,6 +3,7 @@
 // stamp against what the running CLI ships to know what changed and what to migrate FROM.
 // (Also holds platform identity fields when the repo was provisioned via a setup URL.)
 
+import { execSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { CURRENT, CLI_VERSION, RELEASES } from "./releases.mjs";
@@ -34,6 +35,29 @@ export function writeStamp(cwd, patch = {}) {
   return next;
 }
 
+// The code repo's canonical (prod) branch (owner 2026-07-26: configurable,
+// never hardcoded). Resolution chain: the rafa.json stamp's `prodBranch`
+// (mirrors the platform's per-repo setting — carried down so the CLI's trunk
+// guards agree with the platform's routing) → git's own origin/HEAD symref
+// (the repo's actual default) → "main".
+export function trunkBranchOf(cwd) {
+  const s = readStamp(cwd);
+  if (typeof s.prodBranch === "string" && s.prodBranch.trim() !== "")
+    return s.prodBranch.trim();
+  try {
+    const out = execSync("git symbolic-ref refs/remotes/origin/HEAD", {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const m = out.match(/refs\/remotes\/origin\/(.+)$/);
+    if (m) return m[1];
+  } catch {
+    /* no remote / no symref — fall through */
+  }
+  return "main";
+}
+
 // The versions this repo was last stamped at. Un-stamped repos predate the stamp (added in
 // 0.2.0), so default to the FIRST release's schema — never raise a false migration alarm.
 export function stampedVersions(cwd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.10.0",
+  "version": "0.11.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-25T18:10:32.629Z",
+  "generatedAt": "2026-07-25T21:14:46.864Z",
   "skills": {
     "tdd": {
       "version": "1.0.0",