@rafinery/cli 0.13.0 → 0.14.0

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",

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/releases.mjs

@@ -456,6 +456,35 @@ 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.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.13.0",
+  "version": "0.14.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-26T21:22:28.352Z",
   "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.

package/lib/ci-setup.mjs

@@ -1,172 +0,0 @@
-// rafa ci-setup — install the reconciliation workflow (working-set
-// architecture, ratified 2026-07-10, rules 6–7): the org's own CI folds
-// branch→branch merges mechanically and DISTILLS merge-to-main with the org's
-// own LLM key. Writes .github/workflows/rafa-reconcile.yml and names the
-// secrets to configure — it configures nothing itself (secrets are the org's;
-// nothing sensitive ever transits rafinery).
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-const WORKFLOW_PATH = ".github/workflows/rafa-reconcile.yml";
-
-const WORKFLOW = `# rafa reconcile — knowledge propagates exactly like the code it describes.
-#
-#   branch → parent branch merge   = MECHANICAL FOLD (no LLM, no prism)
-#   branch → default branch merge  = DISTILLATION (prism-validated vs merged main,
-#                                    compile-gated, pushed to the brain repo)
-#
-# Secrets (Settings → Secrets and variables → Actions):
-#   RAFA_MCP_KEY        an agent key for this repo (platform → repo → Agent access)
-#   ANTHROPIC_API_KEY   the ORG'S OWN LLM key — used only inside this CI for
-#                       distillation; never stored on the rafinery platform
-#   RAFA_BRAIN_TOKEN    a token with push access to the BRAIN repo (distill only)
-#
-# Fires on the merge EVENT itself (PR closed+merged), so squash/rebase merges are
-# detected correctly. The distill job ALSO runs an ancestry sweep: any still-active
-# working-set row (any branch) whose capturedAtSha is reachable from merged main is
-# provably-merged backlog — an earlier merge whose distill never ran, or a direct
-# push — and folds into the same run. The sweep needs full history (fetch-depth: 0).
-# If distillation cannot run (missing secret, failed gate) it fails LOUD and the
-# branch's working set stays intact — the next dev session gets the standard
-# distill offer (fallback chain).
-
-name: rafa reconcile
-
-on:
-  pull_request:
-    types: [closed]
-
-jobs:
-  fold:
-    name: fold working set (branch → parent)
-    if: github.event.pull_request.merged == true && github.event.pull_request.base.ref != github.event.repository.default_branch
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - name: Mechanical fold (no LLM — rigor lives at main)
-        env:
-          RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
-          RAFA_MCP_URL: \${{ secrets.RAFA_MCP_URL }} # deployed platform /api/mcp — localhost never works from CI
-          RAFA_HOOKS_DISABLED: "1" # headless — the M5 sensors are session instruments
-        run: npx -y @rafinery/cli fold --from "\${{ github.event.pull_request.head.ref }}" --to "\${{ github.event.pull_request.base.ref }}"
-
-  distill:
-    name: distill working set (merge to main)
-    if: github.event.pull_request.merged == true && github.event.pull_request.base.ref == github.event.repository.default_branch
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: \${{ github.event.repository.default_branch }} # merged main = the validation target
-          fetch-depth: 0 # full history — the ancestry sweep proves prior merges
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      # ISOLATED install — never \`npm i\` inside the client checkout: a pnpm
-      # workspace repo has "workspace:*" deps npm cannot parse (EUNSUPPORTEDPROTOCOL).
-      - name: Install the Agent SDK (isolated dir; runs on the org's own key)
-        run: |
-          mkdir -p "\$RUNNER_TEMP/rafa-sdk" && cd "\$RUNNER_TEMP/rafa-sdk"
-          npm init -y > /dev/null
-          npm i @anthropic-ai/claude-agent-sdk
-      - name: Distill into the org brain (prism-validated, compile-gated)
-        env:
-          ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
-          RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
-          RAFA_MCP_URL: \${{ secrets.RAFA_MCP_URL }} # deployed platform /api/mcp — localhost never works from CI
-          RAFA_BRAIN_TOKEN: \${{ secrets.RAFA_BRAIN_TOKEN }}
-          RAFA_AGENT_SDK_DIR: \${{ runner.temp }}/rafa-sdk
-          RAFA_HOOKS_DISABLED: "1" # headless — the M5 sensors are session instruments
-          RAFA_MERGE_SHA: \${{ github.event.pull_request.merge_commit_sha }} # keys the run record
-          RAFA_TARGET_BRANCH: \${{ github.event.pull_request.base.ref }}
-        run: npx -y @rafinery/cli distill --headless "\${{ github.event.pull_request.head.ref }}"
-`;
-
-// Pristine-detection for upgrades: a byte-diff alone cannot tell "user tuned
-// this" from "our template moved on" — and mislabeling a stale pristine
-// install as tuned strands it on old behavior forever (the ancestry sweep is
-// inert without fetch-depth: 0). Comparison ignores comments/blank lines;
-// PREVIOUS_NORMALIZED holds every historical pristine body, so a file that
-// matches one is upgraded in place and only a genuinely tuned file is left
-// alone. (Comment-only tuning is knowingly not preserved.)
-const normalize = (s) =>
-  s
-    .split("\n")
-    .map((l) => l.trimEnd())
-    .filter((l) => {
-      const t = l.trim();
-      return t !== "" && !t.startsWith("#");
-    })
-    .join("\n");
-const PREVIOUS_NORMALIZED = [
-  // v1 (pre ancestry-sweep, pre run-record): identical body minus the lines
-  // those two features added. Derived, not duplicated — v1 never shipped a
-  // byte that differs otherwise.
-  normalize(WORKFLOW)
-    .split("\n")
-    .filter(
-      (l) =>
-        !l.includes("fetch-depth: 0") &&
-        !l.includes("RAFA_MERGE_SHA") &&
-        !l.includes("RAFA_TARGET_BRANCH"),
-    )
-    .join("\n"),
-];
-
-export default async function ciSetup(args = []) {
-  const ROOT = process.cwd();
-  const target = join(ROOT, WORKFLOW_PATH);
-
-  console.log(
-    "OPTIONAL — the platform reconciles merges automatically (no CI, no repo secrets).\n" +
-      "This wires the org-CI ADAPTER instead: reconciliation compute runs in YOUR\n" +
-      "GitHub Actions on YOUR secrets. Most teams should skip this.\n",
-  );
-
-  if (existsSync(target)) {
-    const current = readFileSync(target, "utf8");
-    if (current === WORKFLOW) {
-      console.log(`✓ ${WORKFLOW_PATH} is already current`);
-    } else if (args.includes("--overwrite")) {
-      writeFileSync(target, WORKFLOW);
-      console.log(`✓ ${WORKFLOW_PATH} updated (--overwrite)`);
-    } else if (PREVIOUS_NORMALIZED.includes(normalize(current))) {
-      writeFileSync(target, WORKFLOW);
-      console.log(
-        `✓ ${WORKFLOW_PATH} upgraded from an older pristine template (no local tuning detected)`,
-      );
-    } else {
-      console.log(
-        `! ${WORKFLOW_PATH} exists and differs — left untouched (yours may be tuned).\n` +
-          "  Re-run with --overwrite to replace it.",
-      );
-    }
-  } else {
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, WORKFLOW);
-    console.log(`✓ wrote ${WORKFLOW_PATH}`);
-  }
-
-  console.log(`
-Next steps (repo Settings → Secrets and variables → Actions):
-  1. RAFA_MCP_KEY       — mint on the platform (repo → Agent access); scope: this repo.
-  2. RAFA_MCP_URL       — your DEPLOYED platform's MCP endpoint (https://<host>/api/mcp).
-                          A localhost dev URL can never work from a CI runner.
-  3. ANTHROPIC_API_KEY  — the ORG'S OWN LLM key. Used only inside YOUR CI for
-                          merge-to-main distillation; never stored on the rafinery
-                          platform (hard rule).
-  4. RAFA_BRAIN_TOKEN   — a token with push access to the BRAIN repo (the distill
-                          job pushes validated knowledge there).
-  5. Commit the workflow via your normal MR flow.
-  6. Verify the whole capture chain:  npx @rafinery/cli doctor  (sensors, scripts,
-     platform round-trip — exit 1 names any fix).
-
-The rigor gradient this wires: dev↔dev = CAS + session prompt · branch↔branch =
-free mechanical fold · branch→main = full distillation + gates. Cost tracks
-consequence. Without CI, nothing is lost — the next dev session's bootstrap
-digest offers the same reconciliation (/rafa distill).`);
-}