@open-tomato/rafa 0.9.1 → 0.10.0

package/README.md

@@ -54,6 +54,8 @@ Read this once; rafa also says it the first time you start a run.
   | `rafa skill backfill --propose` | 🪙 one session per batch of skills; without `--propose`, nothing |
   | `rafa next` | 🪙 when the step it runs is one of the above; it asks before each step |
 
+  The same 🪙 marks appear in `rafa --help` at all levels and in `rafa describe` output.
+
   Everything else reads files, git and GitHub and spends nothing,
   `rafa usage` included (it reads `CLAUDE_USAGE_PERCENT` and asks
   nobody). `rafa loop resume` starts no session itself, but it lets a
@@ -330,6 +332,7 @@ built. A box is ticked by the change that finishes the feature.
 - [x] Start a plan from the main branch and rafa makes the branch for you
 - [x] One command takes you to the next step: merge, clean up, plan,
   branch, start
+- [x] Every command that spends Claude usage says so in its help
 - [ ] The right skills reach the right task, chosen when the plan is
   written
 - [ ] Know which skills earn their place and which are ignored

package/dist/SKILL.md

@@ -471,6 +471,27 @@ The report rules in this skill restate `src/report/parse.ts`, which is the autho
 
 ---
 
+## Command-development rule: Claude session declaration
+
+When planning work on rafa commands: every command that can start a Claude
+Code session must declare its `spends` field on its `RafaCommand` definition.
+The field tells the help system, `describe` output, and the spawn guard in
+`src/utils/claude.ts` what Claude usage the command declares. It is optional,
+and takes one of four shapes:
+
+- `{ when: 'always'; what: string }` — the command always starts a session
+- `{ when: 'with'; flag: string; what: string }` — starts a session only when
+  the named flag is passed (flag written as `--resolve`, matched by name)
+- `{ when: 'unless'; flag: string; what: string }` — starts a session unless
+  the named flag is passed
+- `{ when: 'through'; what: string }` — may start a session through a
+  sub-command it calls
+
+The `what` field is a short phrase describing the session (e.g., "one planning
+session"). See `context/cli.md` for the command architecture and examples.
+
+---
+
 ## Examples
 
 Each module task below carries its own unit tests, and each stage closes on a test task over what its modules do together.

package/dist/cli.js

@@ -877,6 +877,47 @@ function resolveScope(start, seams) {
   return { found: true, root: walk.root, home, project: scopeAt(walk.root), user };
 }
 
+// src/cli/spends.ts
+var SPENDS_GLYPH = "\uD83E\uDE99";
+var SPENDS_WHEN = ["always", "with", "unless", "through"];
+var FLAGGED = ["with", "unless"];
+var FLAG_SPELLING = /^--[^\s-]\S*$/;
+function flagProblem(when, flag2) {
+  if (FLAGGED.includes(when)) {
+    return typeof flag2 === "string" && FLAG_SPELLING.test(flag2) ? null : `spends.flag is ${describeValue(flag2)}, expected a flag as typed, starting with --`;
+  }
+  return flag2 === undefined ? null : `spends.flag is ${describeValue(flag2)}, expected absent when spends.when is "${when}"`;
+}
+function spendsProblem(value) {
+  if (value === undefined)
+    return null;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return `spends is ${describeValue(value)}, expected absent or a mapping`;
+  }
+  const { when, what, flag: flag2 } = value;
+  if (!SPENDS_WHEN.includes(when)) {
+    return `spends.when is ${describeValue(when)}, expected one of ${SPENDS_WHEN.join(", ")}`;
+  }
+  if (typeof what !== "string") {
+    return `spends.what is ${describeValue(what)}, expected a string`;
+  }
+  return flagProblem(when, flag2);
+}
+function spendsCondition(spend) {
+  switch (spend.when) {
+    case "with":
+    case "unless":
+      return `${spend.when} ${spend.flag}`;
+    case "always":
+    case "through":
+      return null;
+  }
+}
+function spendsMark(spend) {
+  const condition = spendsCondition(spend);
+  return condition === null ? SPENDS_GLYPH : `${SPENDS_GLYPH} ${condition}`;
+}
+
 // src/cli/command.ts
 var COMMAND_OUTPUTS = ["text", "json", "tui"];
 var MAX_EXIT_CODE = 255;
@@ -955,7 +996,7 @@ function commandProblem(value) {
     return `a command is ${describeValue(value)}, expected a mapping`;
   }
   const fields = value;
-  const problem = fieldProblem(fields);
+  const problem = fieldProblem(fields) ?? spendsProblem(fields.spends);
   if (problem === null)
     return null;
   const named = isRoutingWord(fields.subject) && isRoutingWord(fields.action) ? `command "${commandSpelling(fields)}"` : "a command";
@@ -1532,9 +1573,23 @@ function routeLine(registry, argv) {
   };
 }
 
+// src/cli/running.ts
+var running = null;
+function setRunningCommand(command, flags) {
+  const previous = running;
+  running = Object.freeze({ command, flags: Object.freeze({ ...flags }) });
+  return previous;
+}
+function runningCommand() {
+  return running;
+}
+function restoreRunningCommand(previous) {
+  running = previous;
+}
+
 // package.json
 var name = "@open-tomato/rafa";
-var version = "0.9.1";
+var version = "0.10.0";
 
 // src/cli/version.ts
 var RAFA_VERSION = version;
@@ -1674,6 +1729,7 @@ async function runCommand(route, base, registry, project, settings) {
   const previous = activeOutput();
   const previousMode = activeOutputMode();
   setActiveOutput(guarded.output, base.outputMode);
+  const previousRunning = setRunningCommand(route.command, base.flags);
   try {
     await route.command.run(context);
     return success(guarded.payload());
@@ -1698,6 +1754,7 @@ async function runCommand(route, base, registry, project, settings) {
       stderrLine: error.message === "" ? null : error.message
     };
   } finally {
+    restoreRunningCommand(previousRunning);
     setActiveOutput(previous, previousMode);
   }
 }
@@ -1800,15 +1857,19 @@ var GLOBAL_FLAGS = Object.freeze([
   { spelling: "-v, --verbose", note: "repeat for more, up to 3; --verbose=N (also RAFA_VERBOSITY=N)" },
   { spelling: "--version", note: 'print "rafa <version>" and exit; typed alone, no short form' }
 ]);
+var SPENDS_LEGEND = `${SPENDS_GLYPH}  starts Claude Code sessions, which spend your Claude usage`;
 var INDENT = "  ";
 var NOTE_INDENT = "      ";
 var USAGE_CONTINUATION = "    ";
 var GAP = 3;
 var MIN_TEXT_WIDTH = 20;
-function pack(text2, first, rest) {
+function wordsOf(text2) {
+  return text2.split(/\s+/).filter((part) => part !== "");
+}
+function pack(words, first, rest) {
   const lines = [];
   let line = "";
-  for (const word of text2.split(/\s+/).filter((part) => part !== "")) {
+  for (const word of words) {
     const width = lines.length === 0 ? first : rest;
     if (line === "") {
       line = word;
@@ -1821,17 +1882,38 @@ function pack(text2, first, rest) {
   }
   return line === "" ? lines : [...lines, line];
 }
-function hang(prefix, text2, indent = prefix) {
+function hangWords(prefix, words, indent = prefix) {
   const width = (used) => Math.max(HELP_WIDTH - used.length, MIN_TEXT_WIDTH);
-  return pack(text2, width(prefix), width(indent)).map((line, index) => index === 0 ? `${prefix}${line}` : `${indent}${line}`);
+  return pack(words, width(prefix), width(indent)).map((line, index) => index === 0 ? `${prefix}${line}` : `${indent}${line}`);
+}
+function hang(prefix, text2, indent = prefix) {
+  return hangWords(prefix, wordsOf(text2), indent);
 }
 function columnOf(rows) {
   const lefts = rows.filter(([, right]) => right !== "").map(([left]) => left.length);
   return INDENT.length + Math.max(0, ...lefts) + GAP;
 }
-function row([left, right], column) {
+function row([left, right, mark = null], column) {
   const head = `${INDENT}${left}`;
-  return right === "" ? [head] : hang(head.padEnd(column), right, " ".repeat(column));
+  const words = mark === null ? wordsOf(right) : [...wordsOf(right), mark];
+  return words.length === 0 ? [head] : hangWords(head.padEnd(column), words, " ".repeat(column));
+}
+function markOf(command) {
+  return command.spends === undefined ? null : spendsMark(command.spends);
+}
+function subjectMark(subject, registry) {
+  return registry.actionsOf(subject.name).some((action) => action.spends !== undefined) ? SPENDS_GLYPH : null;
+}
+function commandWord(command) {
+  const mark = markOf(command);
+  return mark === null ? command.subject : `${command.subject} ${mark}`;
+}
+function spendsLines(command) {
+  const { spends } = command;
+  if (spends === undefined)
+    return [];
+  const mark = spendsCondition(spends) === null ? SPENDS_GLYPH : `${spendsMark(spends)}:`;
+  return hangWords(INDENT, [mark, ...wordsOf(spends.what)]);
 }
 function rows(entries) {
   const column = columnOf(entries);
@@ -1879,9 +1961,10 @@ function renderRoot(registry) {
       ["rafa <subject> <action> --help", "arguments, flags, examples"]
     ])),
     block("Quick start", quickStart.map((example) => `${INDENT}${example.cmd}`)),
-    block("Subjects", rows(subjects.map((subject) => [subject.name, subject.summary]))),
-    block("Commands", hang(INDENT, topLevel.map((command) => command.subject).join(", "))),
-    block("Global flags", rows(GLOBAL_FLAGS.map((flag2) => [flag2.spelling, flag2.note])))
+    block("Subjects", rows(subjects.map((subject) => [subject.name, subject.summary, subjectMark(subject, registry)]))),
+    block("Commands", hangWords(INDENT, topLevel.map((command, index) => index === topLevel.length - 1 ? commandWord(command) : `${commandWord(command)},`))),
+    block("Global flags", rows(GLOBAL_FLAGS.map((flag2) => [flag2.spelling, flag2.note]))),
+    registry.commands().some((command) => command.spends !== undefined) ? [SPENDS_LEGEND] : []
   ]);
 }
 function examplesAcross(actions, count) {
@@ -1898,7 +1981,7 @@ function renderSubject(subject, registry) {
       [`${spelling} <action> [args] [flags]`, ""],
       [`${spelling} <action> --help`, "arguments, flags, examples"]
     ])),
-    block("Actions", rows(actions.map((action) => [action.action, action.summary]))),
+    block("Actions", rows(actions.map((action) => [action.action, action.summary, markOf(action)]))),
     block("Examples", examplesAcross(actions, SUBJECT_EXAMPLES).flatMap(exampleLines))
   ]);
 }
@@ -1948,6 +2031,7 @@ function renderAction(request, registry) {
     block("Deprecated", deprecated === undefined ? [] : hang(INDENT, `since ${deprecated.since}; use "rafa ${deprecated.use}"`)),
     block("Usage", hang(INDENT, usage, USAGE_CONTINUATION)),
     block("Description", hang(INDENT, command.description)),
+    block("Spends", spendsLines(command)),
     block("Arguments", table(command.args.map(argRow))),
     block("Flags", table(command.flags.map(flagRow))),
     block("Examples", command.examples.flatMap(exampleLines)),
@@ -3076,7 +3160,7 @@ function typedAlias(alias) {
   return alias.trim().split(/\s+/).join(" ");
 }
 function describeCommand(command, name2, module) {
-  const { deprecated } = command;
+  const { deprecated, spends } = command;
   return {
     name: name2,
     summary: command.summary,
@@ -3087,7 +3171,8 @@ function describeCommand(command, name2, module) {
     outputs: [...command.outputs],
     aliases: module === null ? (command.aliases ?? []).map(typedAlias) : [],
     deprecated: deprecated === undefined ? null : { since: deprecated.since, use: deprecated.use },
-    module
+    module,
+    spends: spends === undefined ? null : { ...spends }
   };
 }
 function mountedThrough(exec, registry) {
@@ -3553,7 +3638,7 @@ function requireIssueNumber(issue) {
   }
   return issue;
 }
-function wordsOf(title2) {
+function wordsOf2(title2) {
   return title2.toLowerCase().replace(NON_WORD, " ").split(" ").filter((word) => word !== "");
 }
 function withoutStopWords(words) {
@@ -3563,8 +3648,8 @@ function withoutStopWords(words) {
 function slugFromTitle(title2) {
   const withoutId = title2.replace(LEADING_ID, "");
   const [firstClause = ""] = withoutId.split(CLAUSE_BREAK);
-  const whole = withoutStopWords(wordsOf(withoutId));
-  const clause = withoutStopWords(wordsOf(firstClause));
+  const whole = withoutStopWords(wordsOf2(withoutId));
+  const clause = withoutStopWords(wordsOf2(firstClause));
   const chosen = clause.length >= MIN_SLUG_WORDS ? clause : whole;
   if (chosen.length === 0)
     return FALLBACK_SLUG;
@@ -8048,7 +8133,7 @@ function payloadProblem(payload) {
 function heldInstinctProblem(value) {
   return fieldsProblem(value, HELD_INSTINCT_CHECKS, "the line") ?? fieldsProblem(value.instinct, INSTINCT_CHECKS, "the instinct");
 }
-function flagProblem(value) {
+function flagProblem2(value) {
   return fieldsProblem(value, FLAG_CHECKS, "the flag");
 }
 function copyInstinct(record) {
@@ -8127,7 +8212,7 @@ function createLocalLearning(options) {
   async function flaggedIds() {
     const lines = numberedLines(await readIfPresent2(flagsPath));
     return new Set(lines.map(([number, line]) => {
-      const reading2 = readLine2(line, flagProblem);
+      const reading2 = readLine2(line, flagProblem2);
       if (reading2.ok)
         return reading2.value.id;
       throw new Error(`${PREFIX7}: line ${number} of ${flagsPath} is not a flag,` + ` and a bundle skipping it could hold an instinct it flags: ${reading2.problem}`);
@@ -8161,7 +8246,7 @@ function createLocalLearning(options) {
     },
     flag: async (id, reason) => {
       const flag2 = { id, reason, flagged_at: now() };
-      const problem = flagProblem(flag2);
+      const problem = flagProblem2(flag2);
       if (problem !== null) {
         throw new TypeError(`${PREFIX7}: refused to write an invalid flag: ${problem}`);
       }
@@ -8394,9 +8479,44 @@ function claudeSessionEnv() {
     CLAUDE_CODE_ENTRYPOINT: "cli"
   };
 }
+
+class UndeclaredSpendError extends Error {
+  name = "UndeclaredSpendError";
+}
+function carriesFlag(flags, flag2) {
+  const name2 = flag2.replace(/^--/, "");
+  const value = flags[name2];
+  if (value !== undefined && value !== false)
+    return true;
+  return name2.startsWith("no-") && flags[name2.slice(3)] === false;
+}
+function spendRefusal(running2) {
+  if (running2 === null)
+    return null;
+  const { command, flags } = running2;
+  const spend = command.spends;
+  const named = `rafa ${commandSpelling(command)}`;
+  const remedy = "declare spends on the command to cover this run";
+  if (spend === undefined) {
+    return `${named} started a Claude session but declares no spends: ${remedy}`;
+  }
+  if (spend.when === "with" && !carriesFlag(flags, spend.flag)) {
+    return `${named} started a Claude session without ${spend.flag}, and its spends covers only a run with ${spend.flag}: ${remedy}`;
+  }
+  if (spend.when === "unless" && carriesFlag(flags, spend.flag)) {
+    return `${named} started a Claude session with ${spend.flag}, and its spends covers no run with ${spend.flag}: ${remedy}`;
+  }
+  return null;
+}
+function guardSpend() {
+  const refusal3 = spendRefusal(runningCommand());
+  if (refusal3 !== null)
+    throw new UndeclaredSpendError(refusal3);
+}
 async function spawnClaude(args, prompt) {
+  guardSpend();
   if (activeOutputMode() === "json") {
-    const { exitCode } = await spawnClaudeCaptured(args, prompt);
+    const { exitCode } = await spawnCaptured(args, prompt);
     return exitCode;
   }
   const proc = Bun.spawn([CLAUDE_BIN, ...args], {
@@ -8448,6 +8568,10 @@ async function teeToOperator(stream) {
   return text2 + tail;
 }
 async function spawnClaudeCaptured(args, prompt) {
+  guardSpend();
+  return spawnCaptured(args, prompt);
+}
+async function spawnCaptured(args, prompt) {
   const proc = Bun.spawn([CLAUDE_BIN, ...args], {
     stdin: new TextEncoder().encode(prompt),
     stdout: "pipe",
@@ -16390,13 +16514,18 @@ function openNextSources(context, seams = DEFAULT_NEXT_SOURCE_SEAMS) {
   const git = (seams.openGit ?? createGitRunner)(project.root);
   const gh = (seams.openGh ?? ((root) => createGhRunner({ cwd: root })))(project.root);
   const loop = resolveLoopSeams({ isAlive: seams.isAlive });
-  return Object.freeze({
+  const board = () => ghNextBoard({ gh, git, configured: config.roadmapIssue });
+  const held = {
     base: config.prBase ?? DEFAULT_BASE_BRANCH,
     plans: plansDirAt(project.root, config.planDir),
     runs: () => readRecords(project.root, loop),
     git,
-    pulls: (seams.pullRequests ?? ghPullRequestsIn)(project.root),
-    board: ghNextBoard({ gh, git, configured: config.roadmapIssue })
+    pulls: (seams.pullRequests ?? ghPullRequestsIn)(project.root)
+  };
+  return Object.freeze({
+    ...held,
+    board: board(),
+    answer: () => Object.freeze({ ...held, board: board() })
   });
 }
 
@@ -18012,16 +18141,16 @@ function conflictLine(repoRoot, conflict) {
 }
 function sessionRefusal(repoRoot, draft, conflicts) {
   const onOtherBranch = conflicts.some((conflict) => conflict.reason === "branch");
-  const running = conflicts.some((conflict) => conflict.reason === "live");
+  const running2 = conflicts.some((conflict) => conflict.reason === "live");
   const why = [
     onOtherBranch ? "it already has a branch" : null,
-    running ? "a session is already running it" : null
+    running2 ? "a session is already running it" : null
   ].filter((reason) => reason !== null);
   return [
     `\u274C Refusing to run plan \`${draft.planStub ?? draft.plan}\` on \`${draft.branch}\`: ${why.join(", and ")}.`,
     ...conflicts.map((conflict) => conflictLine(repoRoot, conflict)),
     ...onOtherBranch ? ["   A plan runs on one branch: check out that branch to run it there, or revise the plan under a new stub."] : [],
-    ...running ? ["   One session runs a plan at a time: let that run end, or interrupt it, then run again."] : [],
+    ...running2 ? ["   One session runs a plan at a time: let that run end, or interrupt it, then run again."] : [],
     NOTHING_DISPATCHED
   ].join(`
 `);
@@ -21099,7 +21228,11 @@ var wrapped = wrapPhaseZeroCommand({
     }
   ],
   aliases: ["start"],
-  outputs: ["text", "json"]
+  outputs: ["text", "json"],
+  spends: {
+    when: "always",
+    what: "one session per task, one for the wrap-up, and repair sessions while CI is red"
+  }
 }, start);
 var loopStart = Object.freeze({
   ...wrapped,
@@ -21507,7 +21640,7 @@ function readProvides(raw, label, declared) {
   }
   return all.length > 0 ? failed2(...all) : passed(Object.freeze(Object.fromEntries(provided)));
 }
-function readRange(raw, label, running) {
+function readRange(raw, label, running2) {
   const read = readText4(raw, label, RANGE_EXPECTED);
   if (read.value === undefined)
     return read;
@@ -21515,7 +21648,7 @@ function readRange(raw, label, running) {
   if (!range.split("||").every((alternative) => ALTERNATIVE_PATTERN.test(alternative))) {
     return failed2(expected(label, raw, RANGE_EXPECTED));
   }
-  return Bun.semver.satisfies(running, range) ? passed(range) : failed2(`${label} is ${JSON.stringify(range)}, which the running rafa ${running} does not satisfy`);
+  return Bun.semver.satisfies(running2, range) ? passed(range) : failed2(`${label} is ${JSON.stringify(range)}, which the running rafa ${running2} does not satisfy`);
 }
 function readPorts(raw, label, declared, served) {
   const versions = new Map(Object.entries(served));
@@ -22130,7 +22263,7 @@ async function runNext(context, seams) {
   const prompter = lazyPrompter(openPrompter);
   try {
     return await runNextChain({
-      read: () => readNextState(sources),
+      read: () => readNextState(sources.answer()),
       run: (state) => runStateAction(context, sources, state),
       ask: prompter.ask,
       handOver: prompter.close,
@@ -22184,6 +22317,7 @@ function createNextCommand(seams = DEFAULT_NEXT_SEAMS) {
       }
     ],
     outputs: ["text", "json"],
+    spends: { when: "through", what: "when the step it runs is one of the above" },
     run: async (context) => {
       const report2 = await runNext(context, seams);
       if (context.outputMode === "json")
@@ -22622,7 +22756,8 @@ var wrapped2 = wrapPhaseZeroCommand({
     }
   ],
   aliases: ["plan"],
-  outputs: ["text", "json"]
+  outputs: ["text", "json"],
+  spends: { when: "always", what: "one planning session" }
 }, plan);
 var create_default2 = endingWith(wrapped2);
 
@@ -24905,9 +25040,9 @@ function alreadyHeadline(at, block2) {
   return `already assessed at ${when}, as ${what}; the head has not moved since`;
 }
 function pendingHeadline(head, rows2, at) {
-  const running = rows2.filter((row2) => row2.outcome === "pending").length;
+  const running2 = rows2.filter((row2) => row2.outcome === "pending").length;
   const when = at ?? "an unrecorded time";
-  return `the head moved to ${shortHead(head)} and ${checkCount2(running)} of ${rows2.length} ` + `still running, so the triage from ${when} stands`;
+  return `the head moved to ${shortHead(head)} and ${checkCount2(running2)} of ${rows2.length} ` + `still running, so the triage from ${when} stands`;
 }
 function assessHeadline(head, verdict, write) {
   const state = verdict === "none" ? "reports no checks at all" : "is not green";
@@ -26293,6 +26428,7 @@ function createPrTriageCommand(seams = DEFAULT_TRIAGE_SEAMS) {
       }
     ],
     outputs: ["text", "json"],
+    spends: { when: "with", flag: "--resolve", what: "runs a small fixed plan through the loop" },
     run: async (context) => {
       const triaged = await runTriage(context, seams);
       if (context.outputMode === "json") {
@@ -28942,6 +29078,7 @@ function createSkillBackfillCommand(seams = DEFAULT_BACKFILL_SEAMS) {
       }
     ],
     outputs: ["text", "json"],
+    spends: { when: "with", flag: "--propose", what: "one session per batch of skills" },
     run: async (context) => {
       await runBackfill(context, seams);
     }

package/dist/effort/store/index.js

@@ -4,7 +4,7 @@ import {
   openNdjsonStore,
   openSqliteStore,
   selectEffortStore
-} from "../../index-eqsm86n7.js";
+} from "../../index-srdtw7w1.js";
 import {
   STORE_BACKENDS
 } from "../../index-96pz9023.js";

package/dist/{index-eqsm86n7.js → index-srdtw7w1.js}

@@ -840,6 +840,33 @@ function parseSpecReview(output) {
   return judged(verdict, readGaps(document, issues), block, issues);
 }
 
+// src/cli/command.ts
+var MAX_EXIT_CODE = 255;
+
+class CommandExit extends Error {
+  exitCode;
+  constructor(exitCode, message = "") {
+    super(message);
+    if (!Number.isInteger(exitCode) || exitCode < 0 || exitCode > MAX_EXIT_CODE) {
+      throw new TypeError(`CommandExit: exit code is ${describeValue(exitCode)}, expected a whole number from 0 to ${MAX_EXIT_CODE}`);
+    }
+    this.name = "CommandExit";
+    this.exitCode = exitCode;
+  }
+}
+function isTopLevel(command) {
+  return command.subject === command.action;
+}
+function commandSpelling(command) {
+  return isTopLevel(command) ? command.subject : `${command.subject} ${command.action}`;
+}
+
+// src/cli/running.ts
+var running = null;
+function runningCommand() {
+  return running;
+}
+
 // src/utils/claude.ts
 async function getClaudeUsagePercent() {
   const envPct = process.env["CLAUDE_USAGE_PERCENT"];
@@ -891,9 +918,44 @@ function claudeSessionEnv() {
     CLAUDE_CODE_ENTRYPOINT: "cli"
   };
 }
+
+class UndeclaredSpendError extends Error {
+  name = "UndeclaredSpendError";
+}
+function carriesFlag(flags, flag) {
+  const name = flag.replace(/^--/, "");
+  const value = flags[name];
+  if (value !== undefined && value !== false)
+    return true;
+  return name.startsWith("no-") && flags[name.slice(3)] === false;
+}
+function spendRefusal(running2) {
+  if (running2 === null)
+    return null;
+  const { command, flags } = running2;
+  const spend = command.spends;
+  const named = `rafa ${commandSpelling(command)}`;
+  const remedy = "declare spends on the command to cover this run";
+  if (spend === undefined) {
+    return `${named} started a Claude session but declares no spends: ${remedy}`;
+  }
+  if (spend.when === "with" && !carriesFlag(flags, spend.flag)) {
+    return `${named} started a Claude session without ${spend.flag}, and its spends covers only a run with ${spend.flag}: ${remedy}`;
+  }
+  if (spend.when === "unless" && carriesFlag(flags, spend.flag)) {
+    return `${named} started a Claude session with ${spend.flag}, and its spends covers no run with ${spend.flag}: ${remedy}`;
+  }
+  return null;
+}
+function guardSpend() {
+  const refusal = spendRefusal(runningCommand());
+  if (refusal !== null)
+    throw new UndeclaredSpendError(refusal);
+}
 async function spawnClaude(args, prompt) {
+  guardSpend();
   if (activeOutputMode() === "json") {
-    const { exitCode } = await spawnClaudeCaptured(args, prompt);
+    const { exitCode } = await spawnCaptured(args, prompt);
     return exitCode;
   }
   const proc = Bun.spawn([CLAUDE_BIN, ...args], {
@@ -945,6 +1007,10 @@ async function teeToOperator(stream) {
   return text + tail;
 }
 async function spawnClaudeCaptured(args, prompt) {
+  guardSpend();
+  return spawnCaptured(args, prompt);
+}
+async function spawnCaptured(args, prompt) {
   const proc = Bun.spawn([CLAUDE_BIN, ...args], {
     stdin: new TextEncoder().encode(prompt),
     stdout: "pipe",
@@ -1771,4 +1837,4 @@ function selectEffortStore(repoRoot, config) {
   return adapter.create({ repoRoot });
 }
 
-export { EFFORT_KEY_PROJECTIONS, openNdjsonStore, sqliteStorePath, LONE_SURROGATE, withSqliteStore, writeSqliteStore, openSqliteStore, getClaudeUsagePercent, checkUsage, interruptClaudeSessions, runClaude, runClaudeCaptured, planFilePath, ClaudePlannerError, createGhRunner, createLocalTracker, PORT_VERSIONS, createAdapterRegistry, CORE_ADAPTER_REGISTRY, selectEffortStore };
+export { EFFORT_KEY_PROJECTIONS, openNdjsonStore, sqliteStorePath, LONE_SURROGATE, withSqliteStore, writeSqliteStore, openSqliteStore, CommandExit, commandSpelling, getClaudeUsagePercent, checkUsage, interruptClaudeSessions, runClaude, runClaudeCaptured, planFilePath, ClaudePlannerError, createGhRunner, createLocalTracker, PORT_VERSIONS, createAdapterRegistry, CORE_ADAPTER_REGISTRY, selectEffortStore };

package/dist/index.js

@@ -30,10 +30,12 @@ import {
 import {
   CORE_ADAPTER_REGISTRY,
   ClaudePlannerError,
+  CommandExit,
   EFFORT_KEY_PROJECTIONS,
   LONE_SURROGATE,
   PORT_VERSIONS,
   checkUsage,
+  commandSpelling,
   createAdapterRegistry,
   createGhRunner,
   createLocalTracker,
@@ -48,7 +50,7 @@ import {
   sqliteStorePath,
   withSqliteStore,
   writeSqliteStore
-} from "./index-eqsm86n7.js";
+} from "./index-srdtw7w1.js";
 import {
   BUDGET_FLAG,
   CLAUDE_SETTING_SOURCES,
@@ -132,27 +134,6 @@ import { existsSync as existsSync2, readdirSync, statSync } from "fs";
 import { homedir } from "os";
 import { join, resolve } from "path";
 
-// src/cli/command.ts
-var MAX_EXIT_CODE = 255;
-
-class CommandExit extends Error {
-  exitCode;
-  constructor(exitCode, message = "") {
-    super(message);
-    if (!Number.isInteger(exitCode) || exitCode < 0 || exitCode > MAX_EXIT_CODE) {
-      throw new TypeError(`CommandExit: exit code is ${describeValue(exitCode)}, expected a whole number from 0 to ${MAX_EXIT_CODE}`);
-    }
-    this.name = "CommandExit";
-    this.exitCode = exitCode;
-  }
-}
-function isTopLevel(command) {
-  return command.subject === command.action;
-}
-function commandSpelling(command) {
-  return isTopLevel(command) ? command.subject : `${command.subject} ${command.action}`;
-}
-
 // src/effort/session-log.ts
 import { createReadStream } from "fs";
 import { basename } from "path";
@@ -1914,7 +1895,7 @@ async function report(args, repoRoot) {
   }
 }
 // package.json
-var version = "0.9.1";
+var version = "0.10.0";
 
 // src/modules/manifest.ts
 var MANIFEST_VERSION = 1;
@@ -6006,13 +5987,18 @@ function openNextSources(context, seams = DEFAULT_NEXT_SOURCE_SEAMS) {
   const git = (seams.openGit ?? createGitRunner)(project.root);
   const gh = (seams.openGh ?? ((root) => createGhRunner({ cwd: root })))(project.root);
   const loop = resolveLoopSeams({ isAlive: seams.isAlive });
-  return Object.freeze({
+  const board = () => ghNextBoard({ gh, git, configured: config.roadmapIssue });
+  const held = {
     base: config.prBase ?? DEFAULT_BASE_BRANCH,
     plans: plansDirAt(project.root, config.planDir),
     runs: () => readRecords(project.root, loop),
     git,
-    pulls: (seams.pullRequests ?? ghPullRequestsIn)(project.root),
-    board: ghNextBoard({ gh, git, configured: config.roadmapIssue })
+    pulls: (seams.pullRequests ?? ghPullRequestsIn)(project.root)
+  };
+  return Object.freeze({
+    ...held,
+    board: board(),
+    answer: () => Object.freeze({ ...held, board: board() })
   });
 }
 

package/dist/plan-prompt.md

@@ -20,6 +20,10 @@ The slug summarizes what the user gets, using two to four words joined by
 hyphens. The order of work lives in ONE place: the pinned "Roadmap" issue
 on the `open-tomato/rafa` board.
 
+* Commands that start Claude sessions must declare `spends` on their
+  `RafaCommand` — see the dev-planner skill's "Command-development rule" for
+  guidance.
+
 * Before planning, review the spec as written, and report that review at the
   END of your final message as a `rafa:spec-review` block carrying
   `verdict: ready` or `verdict: not-ready`, with empty `gaps:` for ready, or a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-tomato/rafa",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Alpha. Runs a plan through the ralph loop: one Claude Code session per task, one commit per task, then a pull request and a CI wait.",
   "private": false,
   "publishConfig": {