@rafinery/cli 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.15.1 — fix `rafa reflex --consume` verdict parsing
+
+A `rafa reflex --consume <id> --reason session-only` silently recorded `banked`
+instead — the parser only accepted a bare positional verdict and rejected
+anything starting with `-`, then fell through to the `banked` default. That's a
+silent wrong value, exactly what the platform forbids.
+
+Now the verdict accepts a flag form (`--verdict=<v>` / `--reason=<v>`, plus the
+bare positional), and an **unrecognized verdict fails loudly** instead of
+defaulting — a session-only correction is recorded session-only, or the consume
+errors. Regression-tested.
+
+## 0.15.0 — learnings are a `.rafa/` sibling
+
+sage's learnings move out of committed `.claude/rafa/learnings/` and become a
+sibling of the improvement ledger: they live in **gitignored `.rafa/learnings/`**,
+stored exactly like improvements — local working copy, durable via the brain-repo
+mirror + the platform DB (`agentLearnings`). Each is an OKF `type: Learning`
+concept, gated by the quartet. No learning files clutter `.claude/` anymore.
+
+`rafa update` runs a **mechanical migration** that relocates a repo's existing
+committed learnings to `.rafa/learnings/` and untracks the old copy — the files
+move, nothing is dropped. Commit the removal of the old `.claude/rafa/learnings/`.
+
 ## 0.14.0 — continuity, tombstones, clean SOPs, distill removed
 
 **Continuity is the product.** Scans and improve passes are refresh-first —

package/blueprint/.claude/agents/sage.md

@@ -61,11 +61,13 @@ the learnings-ledger entry schema, and the procedure. Spawned by the **conductor
 or a boundary offer), context-isolated.
 
 ## Output
-The **learnings ledger** — a committed, human-reviewed governance artifact at
-`.claude/rafa/learnings/` (per the SOP): `learnings/<id>.md` (one proposed card/SOP diff each) +
-`ledger.md` (the index). **Never** a Convex table; **never** inside any customer `.rafa/brain/`
-(learnings are about OUR agents — they never mix with customer knowledge). Every entry cites loop-
-event shapes only and passes the scrub step, or it doesn't ship.
+The **learnings ledger** — a sibling of the improvement ledger (owner 2026-07-27) in gitignored
+`.rafa/learnings/` (per the SOP): `learnings/<id>.md` (one proposed card/SOP diff each, an OKF
+`type: Learning` concept) + `ledger.md` (the index). Storage mirrors improvements — gitignored
+locally, durable via the brain-repo mirror + the platform DB (`agentLearnings`, written with
+`report_learning`). **Never** inside any customer `.rafa/brain/` (learnings are about OUR agents —
+they never mix with customer knowledge). Every entry cites loop-event shapes only and passes the
+scrub step, or it doesn't ship.
 
 ## Style
 Terse, pattern-first, no nagging. Lead with the highest-leverage learning — the one card/SOP change

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

@@ -58,7 +58,7 @@ doesn't validate, compile fails.
 | reflex queue          | `reflex.jsonl`                    | **generated** (local state — transport-excluded, NEVER pushed/ingested; transcript pointers are LOCAL, raw transcripts never ship) | `{id, p, t, tp}` per detected correction + append-only `{id, done, verdict, at}` markers (by the UserPromptSubmit sensor; read by `rafa reflex` + the digest) | tool       |
 | agent                 | `.claude/agents/*.md` (code repo) | **structured** (local gate — NOT in manifest)                                                                                      | §10                                                                                                                                                           | rafa       |
 | skill SOP             | `.claude/skills/rafa-*/SKILL.md` + `.claude/commands/rafa.md` (code repo) | **structured** (local gate — NOT in manifest)                                                                             | frontmatter parses · `name` == skill dir (conductor: semver `version`) · non-empty `description` — a workforce whose procedures don't parse doesn't ship      | rafa       |
-| learning              | `.claude/rafa/learnings/*.md` (code repo) | **structured** (local gate — NOT in manifest)                                                                              | OKF quartet-lite: `id` == stem · non-empty `type`/`title`/`description` (§11 outside the bundle; `learnings/ledger.md` is sage's generated index, skipped)     | sage       |
+| learning              | `.rafa/learnings/*.md` (gitignored `.rafa/` sibling of the improvement ledger; durable via the brain-repo mirror + the platform DB) | **structured** (local gate — NOT in the manifest; stored via `report_learning` → `agentLearnings`) | OKF quartet-lite: `id` == stem · non-empty `type`/`title`/`description` (§11; `learnings/ledger.md` is sage's generated index, skipped)     | sage       |
 | conflict copy         | `**/*.theirs.md`                  | **generated** (transient — a pending HUMAN decision)                                                                               | none — compile FAILS with the typed rule "unresolved checkpoint conflict" while one exists; every walker (emit · checker · validator) skips them              | tool       |
 
 The `agent` type is the one structured type outside `.rafa/`: the shipped agent cards
@@ -618,7 +618,7 @@ state**, marked by `envelope.plane: "state"`:
 | `list_working_sets`                                                                     | branch working set (**READ**)                           | enumerates branches with LIVE candidate rows + counts only (no bodies) — closes the 07-14 sensor gap (`get_working_set` needs a branch arg; nothing listed them); feeds the SessionStart digest pending line                                                                                                                                                         |
 | `report_loop_event`                                                                     | **loopEvents** — the loop-outcome ledger (sage's evidence) | ONE structured outcome per ruling, shapes only (enum category + per-category enum outcome + `subject` shape ref, secret-screened). Wave 5 trust plane, STRICT (no legacy path): **required actor envelope** `{model, agent, runner ∈ sandbox\|ci\|session}` (mechanical CLI emits use `model:"mechanical"`); **required `verification {method: static\|live, tool?, evidence?}`** on `prism-verdict`/`gate-result`/`review-verdict` — the static-vs-executed distinction is structural, never prose; optional `dedupeKey` (≤120) makes the emit **idempotent** (same `(repo, key)` never lands twice — response says `deduped`) and `tier ∈ light\|standard\|full` records the §7 `validation_tier` the ruling ran at |
 | `get_loop_events`                                                                       | loopEvents (**READ**)                                   | newest-first shape read (optional category filter, limit ≤500): category/outcome/subject + actorMeta/verification/dedupeKey/tier + at — no bodies, no code; sage splits miss patterns by verification method, actor, and tier                                                                                                                                          |
-| `report_learning`                                                                       | **agentLearnings** — sage's summary-row mirror          | sage ONLY (wave 4.1): mirrors the SUMMARY ROW of one committed ledger entry (`.claude/rafa/learnings/<id>.md` stays the single truth, MR-gated, never self-applied). Asset-free ENFORCED server-side: enum status/leverage/categories, `.claude/`-only diff target, length caps, code-fence + secret screens; upsert by id                                                                                                          |
+| `report_learning`                                                                       | **agentLearnings** — the learnings STORE                | sage ONLY: stores one learning (local copy in `.rafa/learnings/<id>.md`, the gitignored ledger sibling; the DB row is the durable truth the platform renders). Asset-free ENFORCED server-side: enum status/leverage/categories, `.claude/`-only diff TARGET (the card/SOP a learning proposes to change), length caps, code-fence + secret screens; upsert by id                                                                                                          |
 
 State tools work with or without an ingested brain (a working set can exist —
 and a plan can be pushed — before the first scan) and are exempt from the

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/lib/gate/compile.mjs

@@ -850,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/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/reflex.mjs

@@ -3,7 +3,10 @@
 //
 //   rafa reflex                    list unprocessed corrections
 //   rafa reflex --json             machine shape (bootstrap digest / spawn prompts)
-//   rafa reflex --consume <id> [reason]   mark one processed — AFTER it was banked
+//   rafa reflex --consume <id> [verdict]  mark one processed. verdict ∈
+//       banked | session-only | refuted — a bare word, or --verdict=<v> /
+//       --reason=<v>. Omitted ⇒ banked (the SOP default). An UNRECOGNIZED
+//       verdict fails loudly — never a silent wrong outcome (no assumed values).
 //                                  through the gates, or judged session-only
 //
 // Consume APPENDS a done-marker line ({id, done:true, verdict, at}) — the queue
@@ -50,7 +53,40 @@ export default async function reflex(args = []) {
       console.error(`✗ no unprocessed correction with id ${id} (see \`rafa reflex\`)`);
       process.exit(1);
     }
-    const verdict = args[ci + 2] && !args[ci + 2].startsWith("-") ? args[ci + 2] : "banked";
+    // The verdict — from a bare positional (`--consume <id> session-only`) OR a
+    // flag (`--verdict=X` · `--verdict X` · `--reason=X` · `--reason X`; the
+    // human reaches for `--reason`, so accept it). NO ASSUMED VALUES: default to
+    // `banked` ONLY when no verdict was supplied at all; an unrecognized verdict
+    // — or a flag whose value is unrecognized — fails LOUDLY rather than
+    // silently recording the wrong outcome (the 2026-07-27 mislabel: a
+    // `--reason session-only` fell through to a false `banked`).
+    const VERDICTS = ["banked", "session-only", "refuted"];
+    const rest = args.slice(ci + 2);
+    let verdict = null;
+    let supplied = false;
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      const m = a.match(/^--(?:verdict|reason)(?:=(.+))?$/);
+      if (m) {
+        supplied = true;
+        verdict = m[1] ?? rest[++i] ?? null; // `=value` or the next token
+      } else if (!a.startsWith("-")) {
+        supplied = true;
+        verdict = a; // bare positional verdict
+      } else {
+        continue; // an unrelated flag (e.g. a future --json) — skip, don't consume it as a verdict
+      }
+      break;
+    }
+    if (!supplied) verdict = "banked"; // bare `--consume <id>` — the SOP's default
+    else if (!VERDICTS.includes(verdict)) {
+      console.error(
+        `✗ unrecognized verdict ${verdict === null ? "(none given after the flag)" : `"${verdict}"`} — ` +
+          `expected one of: ${VERDICTS.join(" | ")}.\n` +
+          `  usage: rafa reflex --consume <id> [${VERDICTS.join("|")}]   (bare word, or --verdict=<v> / --reason=<v>)`,
+      );
+      process.exit(1);
+    }
     appendFileSync(
       file,
       JSON.stringify({ id, done: true, verdict, at: new Date().toISOString() }) + "\n",

package/lib/releases.mjs

@@ -485,6 +485,36 @@ export const RELEASES = [
       "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/`.",
+  },
+  {
+    version: "0.15.1",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "FIX `rafa reflex --consume`: the verdict now accepts a flag form " +
+      "(`--verdict=<v>` / `--reason=<v>`, since the human reaches for " +
+      "`--reason`) as well as the bare positional, and an UNRECOGNIZED verdict " +
+      "fails loudly instead of silently defaulting to `banked` (the 2026-07-27 " +
+      "mislabel: `--reason session-only` fell through to a false `banked` in " +
+      "reflex.jsonl + the loop event). No assumed values — a session-only " +
+      "correction is recorded session-only, or the consume errors.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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-26T21:22:28.352Z",
+  "generatedAt": "2026-07-26T22:59:22.774Z",
   "skills": {
     "tdd": {
       "version": "1.0.0",