@esneiderbravo/speclaw 2.0.11 → 2.0.13

package/dist/modules/lawbook/assets/skills/cortex/SKILL.md

@@ -1,13 +1,25 @@
 ---
 name: cortex
-description: Coordinate Cortex — One brain. Many agents. Spawn or adopt explorer, planner, implementer, reviewer, tester, archiver until archive. Use for non-trivial work: "build X", "implement the change", "run cortex", "orchestrate X".
+description: Cortex — One brain. Many agents. The standard way to build any change, as fast as one agent: Compass + laws as guardrails, evidence shipped by hook, extra agents only in parallel.
 ---
 
 # Cortex — One brain. Many agents.
 
-You are the **coordinator**. Do not implement product code yourself.
+One brain does the critical path; mechanical work costs no agent turns.
 
-Drive state with the `cortex` MCP tool (`status` / `start` / `advance` /
-`rework` / `brief`) or `speclaw cortex …`. Command: `/lawbook/cortex`.
+1. Branch `<type>/<slug>` (the slug is the change name).
+2. Locate with Compass (`compass_find` / `compass_explore`). Do not read
+   LAWS.md, config, standards, or `--help` to learn the process — this is it.
+3. Implement the change and its test yourself; ask the human only when blocked.
+4. Run the tests once.
+5. Stop. In Claude Code the `Stop` hook (`speclaw ship-on-stop`) records the
+   change, runs the gates once, writes the report from real output, and
+   archives level-0 work; a failing gate comes back to you. Do not run ship,
+   check the hook, or edit its output. Agents without hooks run `speclaw ship
+   <change> --summary "<what and why>"` once, last.
 
-Read `steps/01-load-or-start.md` and do only what it says.
+Never drive the harness by hand, write proposal/design/reports for small work,
+or post status updates. Review happens on the PR and never blocks you.
+
+Only when the work splits into three or more large, independent parts, read
+`steps/01-load-or-start.md` (fan-out lane: parallel agents, never a chain).

package/dist/modules/lawbook/bugfix.js

@@ -125,7 +125,7 @@ function bugfixTemplate(name, level, seed) {
         "<Run compass_impact on the confirmed root cause; list modules and call sites.>";
     return `# Bugfix: ${name}
 
-**Level:** ${level} · **Type:** bug · **Severity:** normal
+**Level:** ${level ?? "unconfirmed"} · **Type:** bug · **Severity:** normal
 
 ## 1. Observed symptom
 ${symptom}
@@ -150,18 +150,26 @@ ${blast}
 `;
 }
 /**
- * Scaffold a bug change: `bugfix.md`, `change.json`, and `reports/`.
+ * Scaffold a bug change: `bugfix.md`, `tasks.md` (level ≥ 1 or unconfirmed),
+ * `design.md` (level ≥ 2), `change.json`, and `reports/`.
+ *
+ * A supplied `level` is recorded as the confirmed level. Without one the draft
+ * stays unconfirmed: `change.json` holds the proposal and `changeType` only, so
+ * validate and Cortex treat it as level 3 until a human sets a level.
  */
+// Covers: req~bug-draft-unconfirmed~1
 export function scaffoldBugfix(projectPath, name, opts = {}) {
     const r = scaffoldChange(projectPath, name, {
         changeType: "bug",
         targets: opts.targets,
-        level: (proposal) => opts.level ?? (proposal.level !== null && proposal.level <= 1 ? proposal.level : 1),
+        level: opts.level,
         reportsReadme: `# Reports — ${name}\n\nBug reports MUST include the regression test **failing before the fix**.\n`,
         artifacts: ({ level }) => {
+            // Unconfirmed: the level-1 set (bugfix.md + tasks.md); design.md only
+            // once a level of 2 or more is confirmed.
             const lvl = level ?? 1;
             const files = {
-                "bugfix.md": bugfixTemplate(name, lvl, opts.seed),
+                "bugfix.md": bugfixTemplate(name, level, opts.seed),
             };
             if (lvl >= 1) {
                 files["tasks.md"] =

package/dist/modules/lawbook/change-tool.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
 import { handleLevel } from "./quick.js";
+import { shipChange } from "./ship.js";
 import { scaffoldBugfix } from "./bugfix.js";
 import { scaffoldFeature } from "./scaffold-change.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
@@ -18,6 +19,7 @@ export const lawbookChangeActions = [
     "coverage",
     "drift",
     "harness",
+    "ship",
 ];
 export const lawbookChangeSchema = {
     projectPath: z.string(),
@@ -78,6 +80,11 @@ export function handleLawbookChange(args) {
             return specSync(args.projectPath, requireField(args, "change"));
         case "archive":
             return specArchive(args.projectPath, requireField(args, "change"), requireField(args, "date"));
+        case "ship":
+            return shipChange(args.projectPath, requireField(args, "change"), {
+                summary: args.note,
+                date: args.date,
+            });
         case "level":
             if (!args.mode)
                 throw new Error(`lawbook_change: action 'level' requires 'mode'`);

package/dist/modules/lawbook/engine.js

@@ -484,7 +484,10 @@ export function specArchive(projectPath, change, date) {
         }
     }
     const bugPath = path.join(changeDir, "bugfix.md");
+    // A change that carries delta specs always promotes them; skipping would
+    // archive the change while canonical specs silently stay stale.
     const shouldSync = needs.deltaSpecs ||
+        fs.existsSync(path.join(changeDir, "specs")) ||
         (changeType === "bug" &&
             fs.existsSync(bugPath) &&
             preventionRequiresDelta(fs.readFileSync(bugPath, "utf8")));

package/dist/modules/lawbook/levels.js

@@ -173,7 +173,10 @@ export function explain(s, t, score, level) {
     return `${parts.join(", ")} → score ${score} → level ${lvl} (cuts ${t.cuts.join("/")})`;
 }
 export function proposeLevel(s, t = DEFAULT_THRESHOLDS) {
-    if (s.degraded.includes("no-index") && s.filesTouched === 0 && s.blastRadiusNodes === 0) {
+    // Covers: req~level-proposal-preserved~1
+    // An empty target set measured nothing: never a "small level from ignorance".
+    if (s.degraded.includes("no-targets") ||
+        (s.degraded.includes("no-index") && s.filesTouched === 0 && s.blastRadiusNodes === 0)) {
         return {
             level: null,
             score: 0,
@@ -214,10 +217,13 @@ export function countModules(paths) {
 }
 /**
  * Build signals from an explicit target list. When the Compass index is missing,
- * marks `no-index` and does not invent a small blast radius.
+ * marks `no-index` and does not invent a small blast radius; an empty target
+ * list marks `no-targets` (so {@link proposeLevel} proposes no level).
  */
 export function gatherSignals(projectPath, targets, t = DEFAULT_THRESHOLDS) {
     const degraded = [];
+    if (targets.paths.length === 0 && targets.symbols.length === 0)
+        degraded.push("no-targets");
     const paths = new Set(targets.paths.map((p) => p.replace(/^\.\//, "").split("\\").join("/")));
     if (!indexExists(projectPath)) {
         degraded.push("no-index");
@@ -372,6 +378,22 @@ export function writeCeremonyRecord(projectPath, change, record) {
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, JSON.stringify(record, null, 2) + "\n");
 }
+/**
+ * The proposal fields stored in a change's `change.json`, or null when there
+ * is none (no file, or a record without a proposal).
+ */
+export function readStoredProposal(projectPath, change) {
+    const rec = readCeremonyRecord(projectPath, change);
+    if (!rec || rec.signals === undefined)
+        return null;
+    return {
+        level: rec.level ?? null,
+        score: rec.score ?? 0,
+        signals: rec.signals,
+        rationale: rec.rationale ?? "",
+        degraded: rec.degraded ?? [],
+    };
+}
 export function setCeremonyLevel(projectPath, change, opts) {
     const proposed = opts.proposal.level;
     if (proposed !== null && opts.level < proposed && !opts.reason) {
@@ -391,19 +413,28 @@ export function setCeremonyLevel(projectPath, change, opts) {
     writeCeremonyRecord(projectPath, change, record);
     return record;
 }
-export function promoteCeremonyLevel(projectPath, change, to, reason) {
+/**
+ * Raise a confirmed level, appending a promotion. The stored proposal fields
+ * are kept unless `proposal` (measured from explicit targets) replaces them.
+ */
+// Covers: req~level-proposal-preserved~1
+export function promoteCeremonyLevel(projectPath, change, to, reason, proposal) {
     const prev = readCeremonyRecord(projectPath, change);
     if (!prev)
         throw new Error(`change "${change}" has no change.json to promote`);
+    if (prev.confirmedLevel === undefined) {
+        throw new Error(`change "${change}" has no confirmed level to promote — use mode 'set'`);
+    }
     if (to <= prev.confirmedLevel) {
         throw new Error(`promote requires a higher level than ${prev.confirmedLevel}`);
     }
     const record = {
         ...prev,
+        ...(proposal ?? {}),
         confirmedLevel: to,
         confirmedAt: new Date().toISOString(),
         promotions: [
-            ...prev.promotions,
+            ...(prev.promotions ?? []),
             { from: prev.confirmedLevel, to, at: new Date().toISOString(), reason },
         ],
     };

package/dist/modules/lawbook/quick.js

@@ -1,4 +1,4 @@
-import { gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, setCeremonyLevel, } from "./levels.js";
+import { gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, readStoredProposal, setCeremonyLevel, } from "./levels.js";
 import { scaffoldChange } from "./scaffold-change.js";
 /**
  * Scaffold a level-0 change: `record.md`, `change.json`, and `reports/`.
@@ -46,23 +46,34 @@ export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols:
 }
 /**
  * Handle `lawbook_level` modes: propose / set / promote / explain.
+ *
+ * A proposal is measured only when the call names paths or symbols. Without
+ * targets, `propose`/`explain` return the `no-targets` proposal (level null),
+ * and `set`/`promote` keep the proposal already stored in `change.json`
+ * (`set` falls back to the `no-targets` proposal when none is stored).
  */
+// Covers: req~level-proposal-preserved~1
 export function handleLevel(args) {
     const targets = {
         paths: args.paths ?? [],
         symbols: args.symbols ?? [],
     };
-    const { thresholds } = loadCeremonyConfig(args.projectPath);
-    const signals = gatherSignals(args.projectPath, targets, thresholds);
-    const proposal = proposeLevel(signals, thresholds);
+    const measured = targets.paths.length > 0 || targets.symbols.length > 0;
+    const measure = () => {
+        const { thresholds } = loadCeremonyConfig(args.projectPath);
+        return proposeLevel(gatherSignals(args.projectPath, targets, thresholds), thresholds);
+    };
     if (args.mode === "propose" || args.mode === "explain") {
-        return { mode: args.mode, proposal };
+        return { mode: args.mode, proposal: measure() };
     }
     if (!args.change)
         throw new Error(`mode '${args.mode}' requires 'change'`);
     if (args.mode === "set") {
         if (args.level === undefined)
             throw new Error("mode 'set' requires 'level'");
+        const proposal = measured
+            ? measure()
+            : (readStoredProposal(args.projectPath, args.change) ?? measure());
         return setCeremonyLevel(args.projectPath, args.change, {
             proposal,
             level: args.level,
@@ -73,5 +84,5 @@ export function handleLevel(args) {
     // promote
     if (args.level === undefined)
         throw new Error("mode 'promote' requires 'level'");
-    return promoteCeremonyLevel(args.projectPath, args.change, args.level, args.reason ?? "scope grew");
+    return promoteCeremonyLevel(args.projectPath, args.change, args.level, args.reason ?? "scope grew", measured ? measure() : undefined);
 }

package/dist/modules/lawbook/ship.js

@@ -0,0 +1,325 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { changedFiles, isGitRepo, mergeBase, worktreeChangedFiles } from "../../shared/git.js";
+import { handleHarness, readHarness } from "../cortex/harness.js";
+import { specArchive, specArchivePreconditions } from "./engine.js";
+import { confirmedLevel } from "./levels.js";
+import { scaffoldQuick } from "./quick.js";
+const GATE_TAIL_LINES = 12;
+/**
+ * Read the `ship:` block of lawbook/config.yaml (line-oriented, like the other
+ * config readers): `gates: [...]` and `discipline: <name>`.
+ *
+ * @param projectPath - Project root.
+ * @returns The configured gates and discipline, each undefined when absent.
+ */
+export function readShipConfig(projectPath) {
+    const cfg = path.join(projectPath, "lawbook", "config.yaml");
+    if (!fs.existsSync(cfg))
+        return {};
+    const out = {};
+    let inShip = false;
+    for (const line of fs.readFileSync(cfg, "utf8").split("\n")) {
+        if (/^ship:\s*$/.test(line)) {
+            inShip = true;
+            continue;
+        }
+        if (inShip && /^\S/.test(line))
+            break;
+        if (!inShip)
+            continue;
+        const g = /^\s+gates:\s*\[(.*)\]\s*$/.exec(line);
+        if (g) {
+            out.gates = g[1]
+                .split(",")
+                .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                .filter(Boolean);
+        }
+        const d = /^\s+discipline:\s*["']?([\w-]+)["']?\s*$/.exec(line);
+        if (d)
+            out.discipline = d[1];
+    }
+    return out;
+}
+/**
+ * Default gates: the project's own `check`, `lint`, `build` and `test`
+ * package.json scripts, in that order, when present.
+ *
+ * @param projectPath - Project root.
+ * @returns npm commands for the scripts that exist (empty when none).
+ */
+export function detectGates(projectPath) {
+    const pkg = path.join(projectPath, "package.json");
+    if (!fs.existsSync(pkg))
+        return [];
+    const scripts = JSON.parse(fs.readFileSync(pkg, "utf8"))
+        .scripts;
+    if (!scripts)
+        return [];
+    const picked = ["check", "lint", "build", "test"].filter((s) => s in scripts);
+    // `check` usually already runs lint; avoid running it twice.
+    const deduped = picked.includes("check") ? picked.filter((s) => s !== "lint") : picked;
+    return deduped.map((s) => (s === "test" ? "npm test" : `npm run ${s}`));
+}
+function runGate(projectPath, command) {
+    const start = Date.now();
+    const r = spawnSync(command, { cwd: projectPath, shell: true, encoding: "utf8" });
+    const combined = `${r.stdout ?? ""}${r.stderr ?? ""}`.trimEnd().split("\n");
+    return {
+        command,
+        exitCode: r.status ?? 1,
+        durationMs: Date.now() - start,
+        tail: combined.slice(-GATE_TAIL_LINES).join("\n"),
+    };
+}
+function branchFiles(projectPath) {
+    if (!isGitRepo(projectPath))
+        return [];
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    const committed = base ? changedFiles(projectPath, base) : [];
+    return [...new Set([...committed, ...worktreeChangedFiles(projectPath)])]
+        .filter((f) => !f.startsWith("lawbook/changes/"))
+        .sort();
+}
+function secs(ms) {
+    return `${(ms / 1000).toFixed(1)} s`;
+}
+function renderReport(change, discipline, files, gates, passed, date) {
+    const rows = gates
+        .map((g) => `| \`${g.command}\` | ${g.exitCode === 0 ? "pass" : `FAIL (exit ${g.exitCode})`} | ${secs(g.durationMs)} |`)
+        .join("\n");
+    const outputs = gates
+        .map((g) => `### \`${g.command}\`\n\n\`\`\`text\n${g.tail}\n\`\`\``)
+        .join("\n\n");
+    return `# ${discipline} report — ${change}
+
+**Discipline:** ${discipline} · **Change:** ${change} · **Date:** ${date} · **Generated by:** \`speclaw ship\` from real gate output
+
+## Gates and results
+
+| Check | Result | Time |
+|-------|--------|------|
+${rows || "| (no gates configured) | — | — |"}
+
+## Files changed
+
+${files.length ? files.map((f) => `- \`${f}\``).join("\n") : "- (none detected)"}
+
+## Gate output (tail)
+
+${outputs || "No gate output."}
+
+## Pre-existing failures
+
+None recorded.
+
+## Pending manual steps
+
+None.
+
+## Verdict
+
+${passed ? "**Gates PASS** — every gate exited 0. Review is not decided here: it happens on the PR." : "**Gates FAIL** — at least one gate failed; nothing was archived."}
+`;
+}
+/**
+ * The archived folder of a change (`lawbook/changes/archive/<date>-<name>`),
+ * newest first, or null.
+ */
+function findArchived(projectPath, name) {
+    const dir = path.join(projectPath, "lawbook", "changes", "archive");
+    if (!fs.existsSync(dir))
+        return null;
+    const hit = fs
+        .readdirSync(dir)
+        .filter((d) => /^\d{4}-\d{2}-\d{2}-/.test(d) && d.slice(11) === name)
+        .sort()
+        .pop();
+    return hit ? path.join("lawbook", "changes", "archive", hit) : null;
+}
+function fillRecord(recordPath, summary) {
+    if (!fs.existsSync(recordPath))
+        return;
+    const body = fs
+        .readFileSync(recordPath, "utf8")
+        .replace("<!-- 2–5 lines: what and why. -->", summary)
+        .replace(/^- \[ \] /gm, "- [x] ");
+    fs.writeFileSync(recordPath, body);
+}
+/**
+ * Record the test verdict derived from gate exit codes. Ship never records a
+ * review verdict: review belongs to a reviewer or the PR, never to the tool
+ * that produced the change. Stage moves are plain transitions; the only
+ * verdict written is the one at `testing`, and only from passing gates.
+ */
+function recordGateVerdict(projectPath, change) {
+    if (!readHarness(projectPath, change)) {
+        handleHarness({ projectPath, change, harnessOp: "start" });
+    }
+    for (let i = 0; i < 4; i++) {
+        const state = readHarness(projectPath, change);
+        if (!state ||
+            (state.stage !== "exploring" && state.stage !== "implementing" && state.stage !== "testing")) {
+            return;
+        }
+        handleHarness({
+            projectPath,
+            change,
+            harnessOp: "advance",
+            verdict: state.stage === "testing" ? "PASS" : undefined,
+        });
+    }
+}
+/**
+ * Fast path for finished work, in one call: scaffold a level-0 record when the
+ * change does not exist, run the project's gates once, and write a discipline
+ * report from their real output. At level 0 passing gates are the whole
+ * verification, so the change is archived. At level 1+ ship stops after the
+ * evidence: review is a human (or reviewer-role) decision taken on the PR, and
+ * the archive follows it.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change name (kebab-case).
+ * @param opts - Summary, gates, discipline, date, and `noArchive`.
+ * @returns Gate results, the report path, the archive destination, next steps, and timings.
+ */
+export function shipChange(projectPath, name, opts = {}) {
+    const t0 = Date.now();
+    const cfg = readShipConfig(projectPath);
+    const discipline = opts.discipline ?? cfg.discipline ?? "change";
+    const date = opts.date ?? new Date().toISOString().slice(0, 10);
+    const changeDir = path.join(projectPath, "lawbook", "changes", name);
+    const files = branchFiles(projectPath);
+    const archived = findArchived(projectPath, name);
+    if (!fs.existsSync(changeDir) && !archived) {
+        scaffoldQuick(projectPath, name, { paths: [], symbols: [] });
+    }
+    const summary = opts.summary ??
+        (files.length
+            ? `Changed ${files.length} file(s): ${files.slice(0, 8).join(", ")}${files.length > 8 ? ", …" : ""}`
+            : "No file changes detected.");
+    fillRecord(path.join(changeDir, "record.md"), summary);
+    const t1 = Date.now();
+    const commands = opts.gates ?? cfg.gates ?? detectGates(projectPath);
+    const gates = [];
+    for (const command of commands) {
+        const g = runGate(projectPath, command);
+        gates.push(g);
+        if (g.exitCode !== 0)
+            break;
+    }
+    const gatesPassed = gates.every((g) => g.exitCode === 0);
+    const t2 = Date.now();
+    const reportRel = path.join(archived && !fs.existsSync(changeDir) ? archived : path.join("lawbook", "changes", name), "reports", `${discipline}.md`);
+    fs.mkdirSync(path.dirname(path.join(projectPath, reportRel)), { recursive: true });
+    fs.writeFileSync(path.join(projectPath, reportRel), renderReport(name, discipline, files, gates, gatesPassed, date));
+    const t3 = Date.now();
+    let archivedTo = null;
+    const next = [];
+    const level = confirmedLevel(projectPath, name);
+    if (!gatesPassed) {
+        next.push(`fix the failing gate: ${gates[gates.length - 1].command}`);
+    }
+    else if (archived && !fs.existsSync(changeDir)) {
+        // Already archived on this branch: the refreshed report is the update.
+        archivedTo = archived;
+    }
+    else if (level !== 0) {
+        next.push(`level ${level ?? "unconfirmed"}: open the PR — review happens there; archive after approval`);
+    }
+    else if (!opts.noArchive) {
+        recordGateVerdict(projectPath, name);
+        const pre = specArchivePreconditions(projectPath, name);
+        if (pre.length)
+            next.push(...pre);
+        else
+            archivedTo = specArchive(projectPath, name, date).archivedTo;
+    }
+    if (gatesPassed && isGitRepo(projectPath))
+        markShipped(projectPath);
+    const t4 = Date.now();
+    const gatesMs = t2 - t1;
+    return {
+        change: name,
+        gatesPassed,
+        gates,
+        files,
+        report: reportRel,
+        archivedTo,
+        next,
+        timings: {
+            scaffold: t1 - t0,
+            gates: gatesMs,
+            report: t3 - t2,
+            archive: t4 - t3,
+            overhead: t4 - t0 - gatesMs,
+            total: t4 - t0,
+        },
+    };
+}
+/**
+ * Change name for a branch: the part after the last `/`, kebab-cased
+ * (`fix/compass-query-output` → `compass-query-output`).
+ *
+ * @param branch - Git branch name.
+ * @returns The change name.
+ */
+export function changeNameForBranch(branch) {
+    return (branch
+        .split("/")
+        .pop()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "change");
+}
+function git(projectPath, args) {
+    const r = spawnSync("git", args, { cwd: projectPath, encoding: "utf8" });
+    return r.status === 0 ? r.stdout : "";
+}
+/** Fingerprint of the last shipped work; a manual ship and the hook share it. */
+const SHIP_MARKER = path.join(".speclaw", "ship-last");
+function markShipped(projectPath) {
+    const marker = path.join(projectPath, SHIP_MARKER);
+    fs.mkdirSync(path.dirname(marker), { recursive: true });
+    fs.writeFileSync(marker, workFingerprint(projectPath));
+}
+/**
+ * Fingerprint of the work outside `lawbook/changes/`: the diff against HEAD
+ * plus untracked file names. Ship writes under `lawbook/changes/`, so its own
+ * output never changes the fingerprint.
+ */
+function workFingerprint(projectPath) {
+    const diff = git(projectPath, ["diff", "HEAD", "--", ".", ":(exclude)lawbook/changes"]);
+    const untracked = git(projectPath, ["ls-files", "--others", "--exclude-standard"])
+        .split("\n")
+        .filter((f) => f && !f.startsWith("lawbook/changes/") && !f.startsWith(".speclaw/"))
+        .join("\n");
+    const head = git(projectPath, ["rev-parse", "HEAD"]).trim();
+    return createHash("sha256").update(`${head}\n${diff}\n${untracked}`).digest("hex");
+}
+/**
+ * The `Stop` hook body: when the agent ends a turn on a feature branch with
+ * work that changed since the last ship, run {@link shipChange} for the change
+ * named after the branch. Skips in milliseconds otherwise, so a turn that only
+ * answered a question costs nothing.
+ *
+ * @param projectPath - Project root.
+ * @returns Why it skipped, or the ship result.
+ */
+export function shipOnStop(projectPath) {
+    if (!isGitRepo(projectPath))
+        return { skipped: "not-git" };
+    const branch = git(projectPath, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    if (!branch || ["main", "master", "HEAD"].includes(branch))
+        return { skipped: "base-branch" };
+    if (branchFiles(projectPath).length === 0)
+        return { skipped: "no-changes" };
+    const marker = path.join(projectPath, SHIP_MARKER);
+    if (fs.existsSync(marker) && fs.readFileSync(marker, "utf8") === workFingerprint(projectPath)) {
+        return { skipped: "unchanged-since-last-ship" };
+    }
+    const change = changeNameForBranch(branch);
+    return { skipped: null, change, result: shipChange(projectPath, change) };
+}

package/dist/shared/mcp.js

@@ -3,15 +3,17 @@ import { toolDefinitionTokens } from "./schema-tokens.js";
 import { countWords } from "./tokens.js";
 import { applyTextBudget } from "./output-budget.js";
 /**
- * Wrap a value as an MCP text tool-result, optionally applying an output budget.
+ * Wrap a value as an MCP text tool-result, applying an output budget.
  *
  * @param value - Payload to return; strings are emitted verbatim, other values are pretty-printed as JSON.
- * @param mode - Output mode (`brief` default) for token budgeting.
+ * @param budget - Output mode (`brief` default, unchanged for callers that pass
+ *   none) or an explicit `{ maxTokens }` cap a handler opted into.
  * @returns An MCP result object with a single text content block.
  */
-export function text(value, mode = "brief") {
+// Covers: req~find-response-budget~1
+export function text(value, budget = "brief") {
     const raw = typeof value === "string" ? value : JSON.stringify(value, null, 2);
-    const budgeted = applyTextBudget(raw, mode);
+    const budgeted = applyTextBudget(raw, budget);
     return {
         content: [
             {