@rafinery/cli 0.1.0

package/blueprint/.rafa/contract.md

@@ -0,0 +1,303 @@
+# rafa brain contract — v1
+
+The strict protocol every brain file obeys, and the `manifest.json` the platform
+ingests. This is the **single source of truth** shared by the writers (atlas, bloom,
+prism) and the reader (the platform ingest). If a file violates this, the compile
+step **fails loudly** and the authoring agent must correct it — the platform never
+guesses, never assumes a value.
+
+Pipeline:
+
+```
+agents write .md (frontmatter per this contract)
+  → rafa compile   (deterministic: parse frontmatter, VALIDATE, fail loudly)
+       ├ FAIL → structured error (file · field · rule) → author agent fixes → retry
+       └ PASS → emit manifest.json
+  → git push → webhook → INGEST = JSON.parse(manifest) + shape-check → Convex
+  → query APIs (per repo+branch) → platform renders
+```
+
+Two enforcement points: **compile-time** (structure — this contract) and **prism**
+(semantics — truth of the content). Structure is validated *before* semantics.
+
+---
+
+## File-type registry — every `.rafa` file has a declared class
+
+No consumer ever guesses. **Every** file type is classified here; a `structured` type has
+a schema (parse it), a `verbatim` type is prose (display it, never parse for data), a
+`generated` type is machine-written by a named tool. If a file matching a `structured` path
+doesn't validate, compile fails.
+
+| Type | Path glob | Class | Schema | Author |
+|---|---|---|---|---|
+| rule | `brain/rules/*.md` | **structured** | §2 | atlas |
+| playbook | `brain/playbooks/*.md` | **structured** | §2 | atlas |
+| health | `brain/checklist.md` | **structured** | §4 | prism |
+| coverage | `brain/coverage.md` | **structured** | §6 | atlas |
+| improvement | `improve/improvements/*.md` | **structured** | §3 | bloom |
+| ledger | `improve/ledger.md` | **structured** | §5 | bloom |
+| plan | `plans/**/*.md` | **structured** | §7 *(wired: Slice 4)* | plan/build |
+| log | `brain/log.md` | **verbatim** | — (prose trail) | conductor |
+| citation-check | `**/citation-check.md` | **generated** | — (by `verify-citations`) | tool |
+| active pointer | `active.md` | **generated** | — (`# <plan-id>` or "No active plan") | conductor |
+| blueprint | `capabilities/*`, `bin/*`, `contract.md` | **verbatim** | — (shipped SOPs/tools) | rafa |
+
+`structured` types are compiled into `manifest.json` (§1) — that JSON is the ONLY thing the
+platform ingests. `verbatim`/`generated` files are shown as-is in the file browser (fetched
+lazily), never parsed. A file under a `structured` path that isn't in this table → compile
+error (no rogue unschema'd data files).
+
+---
+
+## 0. Global rules
+
+- **Frontmatter is the only machine-read surface.** The markdown **body is prose**
+  and is NEVER parsed for data. Every value the platform shows comes from frontmatter
+  (via the compiled manifest), or from the body rendered *verbatim* (never scraped).
+- **`schemaVersion` is required** on every file and in the manifest. Unknown version
+  → ingest reports an error, does not guess.
+- **`id` is required and stable.** It MUST equal the filename stem (`foo.md` → `foo`).
+  Renames are safe because rows are keyed by `id`, not path.
+- **Required fields are required.** Missing/empty required field = compile failure.
+  The validator **never fills a default for a required field** — that would be
+  assuming. Optional fields have documented defaults.
+- **Enums are closed.** A value outside the enum = compile failure (not coerced).
+
+### Frontmatter grammar (strict subset — the only shapes allowed)
+
+Frontmatter is a leading `---` … `---` block. Within it, only these forms are legal;
+anything else is a compile error:
+
+```yaml
+key: scalar                       # string | number | true | false
+key: "quoted string"              # quotes stripped
+key: [a, b, c]                    # flow list of scalars
+key: { a: x, b: y }               # flow map of scalars
+key:                              # block list …
+  - item
+  - item
+```
+
+No nested block maps, no multiline scalars, no anchors. Deterministic to parse.
+
+### cites DSL
+
+Each cite is one string: `` `<path>:<line> :: <token>` ``
+
+- split on the **first** ` :: ` → (`left`, `token`)
+- in `left`, split on the **last** `:` → (`path`, `line`)
+- `line` is digits (`"42"`) or a range (`"14-18"`)
+
+Compile parses each into `{ file, line, token }`. A cite that doesn't match → error.
+
+---
+
+## 1. manifest.json — the ingestion contract
+
+Machine-generated by `rafa compile`, committed to the brain repo, read by ingest as
+JSON. This is the exact shape the platform binds to.
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-07-03T10:00:00Z",   // ISO-8601, stamped by compile
+  "repo": "owner/repo",                     // CODE repo full_name (identity)
+  "branch": "main",                         // code branch this brain reflects
+  "codeSha": "abc123…",                     // code commit the brain was built for
+
+  "health": {                               // from brain/checklist.md — or null
+    "verdict": "PASS",                      // "PASS" | "ITERATE"
+    "score": 95,                            // 0–100
+    "gates": { "fidelity": "pass", "coverage": "pass" },
+    "counts": { "blockers": 0, "majors": 0, "minors": 2 }
+  },
+
+  "ledger": {                               // from improve/ledger.md — or null
+    "open": 7,
+    "debtScore": 13,
+    "byPriority": { "P0": 0, "P1": 1, "P2": 3, "P3": 3 }
+  },
+
+  "coverage": {                             // from brain/coverage.md — or null
+    "domains": [                            // one row per domain, its scan status
+      { "domain": "design-system", "status": "mapped" },
+      { "domain": "external-integrations", "status": "thin" }
+    ]
+  },
+
+  "notes": [
+    {
+      "id": "agent-name-contract",
+      "kind": "rule",                       // "rule" | "playbook" (from directory)
+      "type": "contract",                   // contract | convention | flow | how-to
+      "domain": "web-agent-bridge",
+      "title": "…",
+      "summary": "…",
+      "links": ["other-note-id"],           // [] if none
+      "failure": "silent",                  // "silent" | "loud" | omitted
+      "cites": [{ "file": "src/x.tsx", "line": "42", "token": "research_agent" }],
+      "path": "brain/rules/agent-name-contract.md"  // prose body (lazy fetch)
+    }
+  ],
+
+  "improvements": [
+    {
+      "id": "dead-model-options-google-crewai",
+      "priority": "P1",                     // P0 | P1 | P2 | P3
+      "lens": "product",                    // security|correctness|performance|architecture|product|ops
+      "status": "open",                     // open | backlog | fixed | wontfix
+      "title": "…",
+      "summary": "…",
+      "fix": "…",
+      "leverage": { "impact": "high", "effort": "low" },   // impact/effort ∈ low|medium|high
+      "blastRadius": ["web-agent-bridge"],  // [] if none
+      "cites": [{ "file": "…", "line": "25", "token": "…" }],
+      "path": "improve/improvements/dead-model-options-google-crewai.md"
+    }
+  ],
+
+  "plans": []                               // v1: may be empty; shape in §6
+}
+```
+
+Ingest is `JSON.parse` + a shape-check against this schema. Any mismatch (missing
+key, wrong enum, wrong type, unknown `schemaVersion`) → a **surfaced ingest error**
+on the platform, never a guessed value.
+
+---
+
+## 2. Note files — `brain/rules/*.md`, `brain/playbooks/*.md`
+
+`kind` is derived from the directory (`rules/` → `rule`, `playbooks/` → `playbook`).
+
+```yaml
+---
+schemaVersion: 1
+id: agent-name-contract          # required · == filename stem
+type: contract                   # required · contract | convention | flow | how-to
+domain: web-agent-bridge         # required · non-empty
+title: The agent name is a cross-process contract   # required
+summary: Only "research_agent" is fully wired end to end   # required
+links: [copilotkit-runtime-route-convention]   # optional · default []
+failure: silent                  # optional · silent | loud
+cites:                           # required · ≥ 1
+  - src/lib/model-selector-provider.tsx:42 :: research_agent
+  - agents/python/main.py:20 :: research_agent
+---
+（prose body — rendered verbatim, never parsed）
+```
+
+---
+
+## 3. Improvement files — `improve/improvements/*.md`
+
+```yaml
+---
+schemaVersion: 1
+id: dead-model-options-google-crewai   # required · == filename stem
+priority: P1                     # required · P0 | P1 | P2 | P3
+lens: product                    # required · security|correctness|performance|architecture|product|ops
+status: open                     # required · open | backlog | fixed | wontfix
+title: Two of the four model options are dead and fail silently   # required
+summary: google_genai and crewai route to unwired agents   # required
+fix: Wire both agents in main.py, or remove them from the picker   # required
+leverage: { impact: high, effort: low }   # required · impact/effort ∈ low|medium|high
+blast_radius: [web-agent-bridge, external-integrations]   # optional · default []
+cites:                           # required · ≥ 1
+  - src/components/ModelSelector.tsx:25 :: google_genai
+found: 2026-07-02               # optional · ISO date
+---
+（prose body）
+```
+
+Note: `title`, `summary`, `fix` are now **required frontmatter** — previously scraped
+from prose. That scraping is gone; these are authored values.
+
+---
+
+## 4. Health file — `brain/checklist.md`
+
+```yaml
+---
+schemaVersion: 1
+verdict: PASS                    # required · PASS | ITERATE
+score: 95                        # required · 0–100
+gates: { fidelity: pass, coverage: pass }   # required · each pass | fail
+counts: { blockers: 0, majors: 0, minors: 2 }   # required · non-negative ints
+---
+（prism report body）
+```
+
+---
+
+## 5. Ledger file — `improve/ledger.md`
+
+The debt figure is **authored in frontmatter** (bloom's number), not parsed from a
+table. `open`/`by_priority` are cross-checked against the improvement rows at ingest.
+Flat keys only — no nesting (compile maps `debt_score`→`debtScore`, `by_priority`→`byPriority`).
+
+```yaml
+---
+schemaVersion: 1
+open: 7
+debt_score: 13
+by_priority: { P0: 0, P1: 1, P2: 3, P3: 3 }
+---
+（human-readable trend/tables in the body）
+```
+
+---
+
+## 6. Coverage file — `brain/coverage.md`
+
+The scan's breadth report. `domains` is a **flow map** of `domain: status`, one entry per
+domain found (compile emits it as `[{ domain, status }]` in the manifest). Status enum:
+`mapped | thin | stubbed | empty`. The body holds the human per-criterion PASS/FAIL narrative.
+
+```yaml
+---
+schemaVersion: 1
+domains: { design-system: mapped, components: mapped, api: thin, external-integrations: empty }
+---
+（per-criterion PASS/FAIL narrative in the body）
+```
+
+---
+
+## 7. Plan files — `plans/**/*.md` (Slice 4)
+
+Each child owns exactly one file (so merges never conflict; parent progress is
+derived by counting).
+
+```yaml
+---
+schemaVersion: 1
+id: c1-schema                    # required · == filename stem
+plan: multitenant                # required · the parent plan id
+parent: null                     # required · parent plan id, or null for the root
+kind: parent | child             # required
+title: …                         # required
+status: todo | in-progress | done | blocked   # required (child); parent may omit
+branch: feat/mt-c1               # optional · the branch this executes on
+baseSha: abc123                  # optional · commit it was cut from
+---
+```
+
+Parent progress is `count(children where status == done) / count(children)` —
+derived, never stored.
+
+---
+
+## 8. Versioning & the validate-and-correct loop
+
+- **`schemaVersion`** bumps when this contract changes incompatibly. Ingest refuses
+  an unknown version (surfaced error) rather than mis-reading it.
+- **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
+  file and compile re-runs. Bounded retries; if it can't converge, a **hard failure**
+  blocks the push (better than a silently-wrong brain).
+- The validator **reports, never auto-fills** a required value.
+
+This contract is the thing to test against.

package/lib/blueprint.mjs

@@ -0,0 +1,86 @@
+// The blueprint — the exact set of files rafa vendors into a repo (shadcn-style:
+// the client OWNS these copies). This one list is the source of truth for both
+// `bundle-blueprint` (monorepo root → package/blueprint) and `init`/`update`
+// (package/blueprint → your repo).
+
+import {
+  existsSync,
+  mkdirSync,
+  cpSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Files a client owns + tunes (agents, SOPs). Tools + contract move in lockstep.
+export const BLUEPRINT = {
+  files: [
+    ".claude/agents/atlas.md",
+    ".claude/agents/prism.md",
+    ".claude/agents/bloom.md",
+    ".claude/commands/rafa.md",
+    ".rafa/contract.md",
+    ".rafa/bin/verify-citations.mjs",
+    ".rafa/bin/rafa-compile.mjs",
+    ".rafa/bin/rafa-push.mjs",
+  ],
+  dirs: [".rafa/capabilities"],
+};
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // …/packages/cli/lib
+
+// Walk up to the monorepo root (the dir that holds the source `.rafa/contract.md`).
+function findRepoRoot() {
+  let d = HERE;
+  for (let i = 0; i < 8; i++) {
+    d = join(d, "..");
+    if (existsSync(join(d, ".rafa", "contract.md"))) return d;
+  }
+  return null;
+}
+
+// Where the blueprint is read FROM when vendoring into a repo:
+//  - published package → <package>/blueprint (bundled by `prepare`)
+//  - dev in the monorepo → the repo root itself
+export function blueprintSource() {
+  const bundled = join(HERE, "..", "blueprint");
+  if (existsSync(join(bundled, ".rafa", "contract.md"))) return bundled;
+  const root = findRepoRoot();
+  if (root) return root;
+  throw new Error(
+    "blueprint not found — run `npm run bundle` in packages/cli, or reinstall.",
+  );
+}
+
+// The monorepo root, for `bundle-blueprint` (copies root → package/blueprint).
+export function repoRoot() {
+  const root = findRepoRoot();
+  if (!root) throw new Error("could not locate the monorepo root");
+  return root;
+}
+
+// Copy every blueprint file/dir from `from` into `to`. Returns the relative paths written.
+export function copyBlueprint(from, to) {
+  const written = [];
+  for (const rel of BLUEPRINT.files) {
+    const src = join(from, rel);
+    if (!existsSync(src)) continue;
+    const dst = join(to, rel);
+    mkdirSync(dirname(dst), { recursive: true });
+    cpSync(src, dst);
+    written.push(rel);
+  }
+  for (const rel of BLUEPRINT.dirs) {
+    const src = join(from, rel);
+    if (!existsSync(src)) continue;
+    const dst = join(to, rel);
+    mkdirSync(dst, { recursive: true });
+    cpSync(src, dst, { recursive: true });
+    // list the .md files copied, for a useful summary
+    for (const e of readdirSync(src)) {
+      if (statSync(join(src, e)).isFile()) written.push(join(rel, e));
+    }
+  }
+  return written;
+}

package/lib/compile.mjs

@@ -0,0 +1,24 @@
+// rafa compile — run the vendored contract gate on this repo's brain. Thin wrapper
+// over .rafa/bin/rafa-compile.mjs (the client's own copy = its contract version).
+
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join } from "node:path";
+
+export default async function compile(args) {
+  const script = join(process.cwd(), ".rafa", "bin", "rafa-compile.mjs");
+  if (!existsSync(script)) {
+    console.error(
+      "✗ .rafa/bin/rafa-compile.mjs not found — run `rafa init` (or `rafa update`) first.",
+    );
+    process.exit(1);
+  }
+  try {
+    execSync(`node ${JSON.stringify(script)} ${args.join(" ")}`.trim(), {
+      stdio: "inherit",
+      cwd: process.cwd(),
+    });
+  } catch {
+    process.exit(1); // compile already printed its path·field·rule errors
+  }
+}

package/lib/init.mjs

@@ -0,0 +1,91 @@
+// rafa init — provision a repo: vendor the blueprint, and (with a platform setup
+// URL) wire the brain remote. Run inside your code repo's root.
+
+import {
+  existsSync,
+  writeFileSync,
+  readFileSync,
+  appendFileSync,
+} from "node:fs";
+import { execSync } from "node:child_process";
+import { join } from "node:path";
+import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+const run = (cmd, cwd) =>
+  execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }).trim();
+
+export default async function init(args) {
+  const url = args.find((a) => !a.startsWith("-"));
+  const TARGET = process.cwd();
+  if (!existsSync(join(TARGET, ".git")))
+    die("Not a git repo — run this inside your code repo's root.");
+
+  // Optional platform setup (short-code URL → non-secret provisioning payload).
+  let p = null;
+  if (url) {
+    try {
+      const res = await fetch(url);
+      p = await res.json();
+      if (!res.ok || p?.error)
+        die(`Couldn't fetch setup: ${p?.error ?? res.status} (setup URLs expire in 15 min).`);
+    } catch (e) {
+      die(`Couldn't reach the setup URL: ${e instanceof Error ? e.message : e}`);
+    }
+    if (!p?.repoId || !p?.brainRepoUrl) die("Setup is missing repo/brain details.");
+    console.log(`rafa init → ${p.repoName} (${p.repoId})`);
+    console.log(`  brain remote: ${p.brainRepoUrl}`);
+  } else {
+    console.log("rafa init — vendoring the blueprint (no setup URL)");
+  }
+
+  // Vendor the blueprint into .claude/ + .rafa/ (you own these copies).
+  const written = copyBlueprint(blueprintSource(), TARGET);
+  if (!existsSync(join(TARGET, ".rafa", "active.md")))
+    writeFileSync(join(TARGET, ".rafa", "active.md"), "# No active plan\n");
+  console.log(`  ✓ vendored ${written.length} blueprint files → .claude/ + .rafa/`);
+
+  // Keep the brain out of the code repo's diffs.
+  const gi = join(TARGET, ".gitignore");
+  const body = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (!/^\.rafa\/?\s*$/m.test(body)) {
+    appendFileSync(gi, `${body.endsWith("\n") || body === "" ? "" : "\n"}.rafa/\n`);
+    console.log("  ✓ .rafa/ → .gitignore");
+  }
+
+  if (p) {
+    writeFileSync(
+      join(TARGET, "rafa.json"),
+      JSON.stringify(
+        {
+          name: p.repoName,
+          repoId: p.repoId,
+          codeRepo: p.codeRepoUrl ?? null,
+          brainRepo: p.brainRepoUrl,
+          provisionedFor: p.owner ?? null,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    const rafaDir = join(TARGET, ".rafa");
+    if (!existsSync(join(rafaDir, ".git"))) run("git init -b main", rafaDir);
+    try {
+      run("git remote get-url origin", rafaDir);
+      run(`git remote set-url origin ${p.brainRepoUrl}`, rafaDir);
+    } catch {
+      run(`git remote add origin ${p.brainRepoUrl}`, rafaDir);
+    }
+    console.log("  ✓ .rafa/ is its own git repo → origin = brain remote");
+  }
+
+  console.log(
+    `\n✓ Provisioned.\n\nNext steps:\n` +
+      "  1. Restart Claude Code in this repo (reload the /rafa command + agents).\n" +
+      "  2. Run  /rafa scan  — build + validate the brain, then  rafa push  to sync it.\n" +
+      "  3. Open the repo on the rafinery platform — its Overview shows the brain once pushed.",
+  );
+}

package/lib/push.mjs

@@ -0,0 +1,24 @@
+// rafa push — compile (contract gate) then push .rafa/ to the brain remote. Thin
+// wrapper over the vendored .rafa/bin/rafa-push.mjs (which runs compile itself).
+
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join } from "node:path";
+
+export default async function push(args) {
+  const script = join(process.cwd(), ".rafa", "bin", "rafa-push.mjs");
+  if (!existsSync(script)) {
+    console.error(
+      "✗ .rafa/bin/rafa-push.mjs not found — run `rafa init` (or `rafa update`) first.",
+    );
+    process.exit(1);
+  }
+  try {
+    execSync(`node ${JSON.stringify(script)} ${args.join(" ")}`.trim(), {
+      stdio: "inherit",
+      cwd: process.cwd(),
+    });
+  } catch {
+    process.exit(1);
+  }
+}

package/lib/update.mjs

@@ -0,0 +1,22 @@
+// rafa update — re-sync the blueprint into this repo. shadcn-style: you own your
+// copies, so this is an opt-in refresh (run it to pull the latest agents,
+// capabilities, contract, and gates after upgrading the CLI).
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
+
+export default async function update() {
+  const TARGET = process.cwd();
+  if (!existsSync(join(TARGET, ".rafa")) && !existsSync(join(TARGET, ".claude"))) {
+    console.error("✗ This repo isn't provisioned yet — run `rafa init` first.");
+    process.exit(1);
+  }
+  const written = copyBlueprint(blueprintSource(), TARGET);
+  console.log(`✓ rafa update — synced ${written.length} blueprint files:`);
+  for (const f of written) console.log(`    ${f}`);
+  console.log(
+    "\n  Your brain data (.rafa/brain, .rafa/improve) was untouched. " +
+      "Restart Claude Code to reload the agents.",
+  );
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@rafinery/cli",
+  "version": "0.1.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": {
+    "rafa": "bin/rafa.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "blueprint"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "bundle": "node scripts/bundle-blueprint.mjs",
+    "prepare": "node scripts/bundle-blueprint.mjs"
+  },
+  "keywords": [
+    "rafa",
+    "rafinery",
+    "ai",
+    "codebase",
+    "brain",
+    "agent",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafinery-ai/rafinery.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/rafinery-ai/rafinery/tree/main/packages/cli"
+}