@esneiderbravo/speclaw 2.0.23 → 2.0.25

package/dist/cli/commands/ship-on-stop.js

@@ -1,11 +1,12 @@
-import { measureBranchDiff, shipOnStop } from "../../modules/lawbook/ship.js";
+import { measureBranchDiff, shipOnStop, stopSummary } from "../../modules/lawbook/ship.js";
 /**
  * `speclaw ship-on-stop`: the Claude Code `Stop` hook. Ships the branch's
- * change when the work changed since the last ship; prints nothing on stdout.
- * Artifacts the change's level still owes, or a failing gate, go to stderr with
- * exit 2 so the agent sees them and writes or fixes them
- * — once: when the hook already blocked this stop (`stop_hook_active`), it
- * exits 0 so the agent can never loop. Any other failure exits 0.
+ * change when the work changed since the last ship, and prints one JSON line
+ * on stdout whose `systemMessage` tells the user what happened. Artifacts the
+ * change's level still owes, or a failing gate, also set `decision: "block"`
+ * with the `reason` the agent acts on — once: when the hook already blocked
+ * this stop (`stop_hook_active`), it does not block again, so the agent can
+ * never loop. A skipped stop prints nothing. It always exits 0.
  *
  * @param cwd - Project root (defaults to the process working directory).
  */
@@ -14,15 +15,23 @@ export async function runShipOnStop(cwd = process.cwd()) {
     const active = await stopHookActive();
     try {
         const out = shipOnStop(cwd);
-        if (out.skipped === null && out.result.pending.length && !active) {
-            process.stderr.write(`speclaw: ${out.result.next.join("\n- ")}\n`);
-            process.exit(2);
-        }
-        if (out.skipped === null && !out.result.gatesPassed && !active) {
-            const failed = out.result.gates[out.result.gates.length - 1];
-            process.stderr.write(`speclaw: gate failed — ${failed.command} (exit ${failed.exitCode}). Fix it before finishing.\n${failed.tail}\n`);
-            process.exit(2);
-        }
+        if (out.skipped !== null)
+            return;
+        const r = out.result;
+        const block = !active && (r.pending.length > 0 || !r.gatesPassed);
+        // Claude Code reads stdout JSON only on exit 0, so a blocked stop says
+        // `decision: block` there too: the reason goes back to the agent and the
+        // systemMessage reaches the user either way.
+        const failed = r.gates[r.gates.length - 1];
+        const reason = !block
+            ? undefined
+            : r.pending.length
+                ? `speclaw: ${r.next.join("\n- ")}`
+                : `speclaw: gate failed — ${failed.command} (exit ${failed.exitCode}). Fix it before finishing.\n${failed.tail}`;
+        process.stdout.write(JSON.stringify({
+            ...(reason ? { decision: "block", reason } : {}),
+            systemMessage: stopSummary(r, block),
+        }) + "\n");
     }
     catch {
         // A hook must never break the session.

package/dist/modules/compass/map.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { openDb, FILE_NODE_KIND } from "./db.js";
 import { estimateTokens } from "../../shared/tokens.js";
 import { loadDeclaredBudget } from "../../shared/exposure.js";
+import { packageEntries } from "../../shared/package-entries.js";
 export const MAP_START = "<!-- speclaw:map:start -->";
 export const MAP_END = "<!-- speclaw:map:end -->";
 /**
@@ -45,12 +46,15 @@ export function generateCompactMap(projectPath) {
             ? "hubs: (none yet)"
             : `hubs: ${hubs.map((h) => `${h.name} ${h.fan_in}`).join(" · ")}`;
         const dirLine = topDirs.map((d) => `${d.top}/ (${d.c})`).join("  ");
-        let body = [
-            `speclaw · ${fileCount} files · ${nodeCount} nodes`,
-            dirLine,
-            hubLine,
-            "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
-        ].join("\n");
+        // Only what this project's package.json declares; a workspace root or an
+        // app declares no entry, and the map then names none.
+        const entries = packageEntries(projectPath);
+        const entryLine = entries.length
+            ? `entry: ${entries.map((e) => `${e.file} (${e.kind})`).join(" · ")}`
+            : "";
+        let body = [`speclaw · ${fileCount} files · ${nodeCount} nodes`, dirLine, hubLine, entryLine]
+            .filter(Boolean)
+            .join("\n");
         const cap = loadDeclaredBudget().map;
         let omitted = false;
         while (estimateTokens(body) > cap && hubs.length > 3) {
@@ -63,7 +67,7 @@ export function generateCompactMap(projectPath) {
                 `speclaw · ${fileCount} files · ${nodeCount} nodes`,
                 dirLine,
                 shorter,
-                "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+                entryLine,
                 omitted ? "(entries omitted to fit map budget)" : "",
             ]
                 .filter(Boolean)
@@ -72,9 +76,11 @@ export function generateCompactMap(projectPath) {
         if (estimateTokens(body) > cap) {
             body = [
                 `speclaw · ${fileCount} files · ${nodeCount} nodes`,
-                "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+                entryLine,
                 "(entries omitted to fit map budget)",
-            ].join("\n");
+            ]
+                .filter(Boolean)
+                .join("\n");
         }
         return body;
     }

package/dist/modules/foundation/hooks.js

@@ -51,7 +51,8 @@ export const SHIP_ON_STOP_MARKER = "speclaw ship-on-stop";
  * with new changes on a feature branch, speclaw sizes the change from its diff,
  * returns the artifacts that level owes, runs the gates once, writes the report
  * from their real output, and archives level-0 work — with no agent turn. Guarded on `lawbook/` instead of the index. Its
- * stderr is kept so a failing gate reaches the agent (exit 2).
+ * stdout is kept: one JSON line blocks the stop with the reason the agent acts
+ * on (owed artifacts, a failing gate) and tells the user what the stop did.
  */
 export const SHIP_ON_STOP_COMMAND = speclawCommand("ship-on-stop");
 /** Seconds the Stop hook may run: the project's own gates run inside it. */
@@ -72,10 +73,11 @@ export function speclawCommand(sub) {
     const run = `if [ -x node_modules/.bin/speclaw ]; then node_modules/.bin/speclaw ${sub}; ` +
         `elif command -v speclaw >/dev/null 2>&1; then speclaw ${sub}; ` +
         `else npm_config_update_notifier=false npm_config_offline=true npx --no-install @esneiderbravo/speclaw ${sub}; fi; `;
-    // The ship hook keeps its exit code (2 feeds a failing gate back to the
-    // agent) and its stderr; stdout is discarded like the other hooks.
+    // The ship hook keeps its stdout and stderr: the one JSON line it prints
+    // blocks the stop when the agent owes something and tells the user what
+    // the stop did.
     return ship
-        ? 'cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -d lawbook ] && { ' + run + "} >/dev/null"
+        ? 'cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -d lawbook ] && { ' + run + "}"
         : 'cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -f .speclaw/index.db ] && { ' +
             run +
             "} >/dev/null 2>&1 || true";

package/dist/modules/lawbook/api-surface.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { mergeBase } from "../../shared/git.js";
+import { isTestPath, loadAffectedConfig } from "../compass/affected-config.js";
+/**
+ * Lines that declare an HTTP route or a request/response contract, across the
+ * frameworks a repo is likely to use. A diff line matching one of them adds,
+ * changes or removes an endpoint, so the change owes an API report. Lines are
+ * trimmed; decorators must open the line, as they do in code, so a string or a
+ * regex that merely mentions one is not a route.
+ */
+const ROUTE_LINE = [
+    // NestJS controllers and handlers.
+    /^@(Controller|Get|Post|Put|Patch|Delete|Head|Options|All|HttpCode|Header|Redirect|Sse)\s*\(/,
+    // Spring.
+    /^@(RestController|RequestMapping|GetMapping|PostMapping|PutMapping|PatchMapping|DeleteMapping)\b/,
+    // FastAPI, Flask and similar decorator routers.
+    /^@\w+\.(get|post|put|patch|delete|route|api_route|websocket)\s*\(/,
+    // Express, Koa, Fastify, Hono: `router.get("/x", handler)` — a path and a
+    // handler, so a client call (`api.get("/users")`) or `app.get("port")` is not one.
+    /^(\w+\.)?(app|router|server|fastify|routes?)\.(get|post|put|patch|delete|all)\s*\(\s*["'`]\/[^"'`]*["'`]\s*,/,
+    // Go net/http, gin, echo, chi: `r.GET("/x", …)`, `mux.HandleFunc("/x", …)`.
+    /^\w+\.(GET|POST|PUT|PATCH|DELETE|HandleFunc|Handle)\s*\(\s*"\//,
+];
+/** Next.js App Router handlers: an exported HTTP-verb function in a `route.*` file. */
+const NEXT_ROUTE_FILE = /(^|\/)app\/(.+\/)?route\.[cm]?[jt]sx?$/;
+const NEXT_HANDLER = /export\s+(async\s+)?(function|const)\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/;
+/** Files that are the contract themselves: any change to them is an API change. */
+const CONTRACT_FILE = /(^|\/)(openapi|swagger)[^/]*\.(ya?ml|json)$|\.(proto|graphql|gql)$/i;
+/** Request/response shapes: a code (not comment) change in a DTO file. */
+const DTO_FILE = /(^|\/)dtos?\/|\.dto\.[cm]?[jt]s$|(^|\/)schemas?\/.+\.py$/;
+const COMMENT_OR_BLANK = /^\s*(\/\/|\/\*|\*|#|$)/;
+const LINES_PER_FILE = 4;
+/**
+ * The changed files whose diff against the branch base adds, changes or
+ * removes an API surface: a route declaration, a contract file, or a DTO. Test
+ * files never count. Reads one `git diff -U0` for every candidate at once and
+ * untracked files whole; never throws.
+ *
+ * @param projectPath - Project root (a git repository).
+ * @param files - Changed files, relative to the root.
+ * @returns The files that touch the API surface, in the order given.
+ */
+export function apiSurfaceChanges(projectPath, files) {
+    try {
+        const { testGlobs } = loadAffectedConfig(projectPath);
+        const candidates = files.filter((f) => !isTestPath(f, testGlobs));
+        if (candidates.length === 0)
+            return [];
+        const changed = changedLines(projectPath, candidates);
+        const hits = [];
+        for (const file of candidates) {
+            const lines = changed.get(file) ?? [];
+            if (CONTRACT_FILE.test(file)) {
+                hits.push({ file, lines: [] });
+                continue;
+            }
+            const surface = lines.filter((l) => declaresSurface(file, l));
+            if (surface.length)
+                hits.push({ file, lines: surface.slice(0, LINES_PER_FILE) });
+        }
+        return hits;
+    }
+    catch {
+        return [];
+    }
+}
+function declaresSurface(file, line) {
+    if (ROUTE_LINE.some((re) => re.test(line)))
+        return true;
+    if (NEXT_ROUTE_FILE.test(file) && NEXT_HANDLER.test(line))
+        return true;
+    return DTO_FILE.test(file) && !COMMENT_OR_BLANK.test(line);
+}
+/**
+ * Added and removed lines per file against the merge base with `main`/`master`
+ * (working tree included); an untracked file contributes every line.
+ */
+function changedLines(projectPath, files) {
+    const out = new Map();
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    if (base) {
+        const r = spawnSync("git", [
+            "-c",
+            "core.quotePath=false",
+            "diff",
+            "-U0",
+            "--no-color",
+            "--no-ext-diff",
+            "--no-renames",
+            "--src-prefix=a/",
+            "--dst-prefix=b/",
+            base,
+            "--",
+            ...files,
+        ], { cwd: projectPath, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        let current = null;
+        for (const line of (r.status === 0 ? r.stdout : "").split("\n")) {
+            // A path with a space ends its header with a tab.
+            const head = /^(---|\+\+\+) (?:[ab]\/(.+?)|\/dev\/null)\t?$/.exec(line);
+            if (head) {
+                // A deleted file's `+++ /dev/null` keeps the name its `--- a/` line set.
+                if (head[2])
+                    current = head[2];
+                else if (head[1] === "---")
+                    current = null;
+                continue;
+            }
+            if (current && /^[+-](?![+-]{2} )/.test(line)) {
+                out.set(current, [...(out.get(current) ?? []), line.slice(1).trim()]);
+            }
+        }
+    }
+    const untracked = spawnSync("git", ["-c", "core.quotePath=false", "ls-files", "--others", "--exclude-standard", "--", ...files], { cwd: projectPath, encoding: "utf8" });
+    for (const f of (untracked.status === 0 ? untracked.stdout : "").split("\n")) {
+        if (!f || out.has(f))
+            continue;
+        try {
+            out.set(f, fs
+                .readFileSync(path.join(projectPath, f), "utf8")
+                .split("\n")
+                .map((l) => l.trim()));
+        }
+        catch {
+            // Vanished since it was listed: nothing to read.
+        }
+    }
+    return out;
+}

package/dist/modules/lawbook/levels.js

@@ -7,6 +7,8 @@ import { affectedTests } from "../compass/affected.js";
 import { hotspots } from "../compass/hotspots.js";
 import { loadAffectedConfig, matchGlob, matchesAny, inferModule, } from "../compass/affected-config.js";
 import { formatJson } from "../../shared/json.js";
+import { packageEntries } from "../../shared/package-entries.js";
+import { apiSurfaceChanges } from "./api-surface.js";
 /** Default thresholds from the adaptive-ceremony roadmap. */
 export const DEFAULT_THRESHOLDS = {
     filesTouched: [0, 1, 3, 5],
@@ -256,8 +258,15 @@ export function gatherSignals(projectPath, targets, t = DEFAULT_THRESHOLDS) {
     }
     let blastRadiusNodes = 0;
     let affected = 0;
-    let touchesPublicApi = false;
     let maxHotspotScore = 0;
+    // A published entry point (package.json `main`/`bin`) or an HTTP route,
+    // DTO or contract file in the diff: either is a surface other code calls.
+    const entries = packageEntries(projectPath).map((e) => e.file);
+    const apiSurface = pathList.length
+        ? apiSurfaceChanges(projectPath, pathList).map((h) => h.file)
+        : [];
+    const touchesPublicApi = apiSurface.length > 0 ||
+        pathList.some((p) => entries.some((e) => p === e || e.endsWith(`/${p}`) || p.endsWith(`/${e}`)));
     if (indexExists(projectPath) && pathList.length > 0) {
         try {
             const imp = impact(projectPath, { files: pathList, format: "grouped", maxDepth: 4 });
@@ -275,32 +284,6 @@ export function gatherSignals(projectPath, targets, t = DEFAULT_THRESHOLDS) {
         catch {
             /* soft */
         }
-        try {
-            const pkgPath = path.join(projectPath, "package.json");
-            if (fs.existsSync(pkgPath)) {
-                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-                const entries = new Set();
-                if (typeof pkg.main === "string")
-                    entries.add(pkg.main.replace(/^\.\//, ""));
-                if (typeof pkg.bin === "string")
-                    entries.add(pkg.bin.replace(/^\.\//, ""));
-                else if (pkg.bin && typeof pkg.bin === "object") {
-                    for (const v of Object.values(pkg.bin))
-                        entries.add(String(v).replace(/^\.\//, ""));
-                }
-                for (const e of entries) {
-                    if (pathList.some((p) => p === e || e.endsWith(p) || p.endsWith(e))) {
-                        touchesPublicApi = true;
-                    }
-                }
-                if (pathList.some((p) => p === "src/cli/index.ts" || p === "src/server.ts")) {
-                    touchesPublicApi = true;
-                }
-            }
-        }
-        catch {
-            /* soft */
-        }
         try {
             const hs = hotspots(projectPath, { days: 90, sortBy: "combined", limit: 200 });
             // The score is relative to the hottest file, so in a young repo any file
@@ -330,6 +313,7 @@ export function gatherSignals(projectPath, targets, t = DEFAULT_THRESHOLDS) {
         blastRadiusNodes,
         affectedTests: affected,
         touchesPublicApi,
+        ...(apiSurface.length ? { apiSurface } : {}),
         maxHotspotScore,
         touchesGlobalFile,
         onlyDocs,

package/dist/modules/lawbook/ship.js

@@ -12,6 +12,7 @@ import { deltaSpecFiles, specArchive, specArchivePreconditions, specList } from
 import { artifactNeeds, confirmedLevel, gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, readCeremonyRecord, readChangeType, } from "./levels.js";
 import { scaffoldQuick } from "./quick.js";
 import { CHANGE_NAME_RE, isPlaceholderDelta, scaffoldFeature } from "./scaffold-change.js";
+import { apiSurfaceChanges } from "./api-surface.js";
 const GATE_TAIL_LINES = 12;
 /**
  * Read the `ship:` block of lawbook/config.yaml (line-oriented, like the other
@@ -98,6 +99,7 @@ function scopedTestGate(projectPath, fullCommand, files) {
         return {
             command: at.command,
             scope: `${at.tests.length} affected test file(s), ${at.skipped.files} skipped; the full suite runs in CI`,
+            parts: at.commands.map((c) => ({ cwd: c.cwd, command: c.command, tests: c.files.length })),
         };
     }
     catch (e) {
@@ -115,6 +117,18 @@ function runGate(projectPath, command) {
         tail: combined.slice(-GATE_TAIL_LINES).join("\n"),
     };
 }
+/**
+ * What the lawbook writes itself: change folders and reports, the canonical
+ * specs an archive promotes, the anchors it seals, and the local index. None
+ * of it is the agent's work, so none of it may trigger, size or re-run a ship
+ * — archiving used to read as new work and re-run every gate.
+ */
+const OWN_OUTPUT = ["lawbook/changes/", "lawbook/specs/", "lawbook/anchors/", ".speclaw/"];
+function isOwnOutput(file) {
+    return OWN_OUTPUT.some((dir) => file.startsWith(dir));
+}
+/** The same paths as git pathspecs, for commands that list or log the work. */
+const OWN_OUTPUT_EXCLUDES = OWN_OUTPUT.map((dir) => `:(exclude)${dir.replace(/\/$/, "")}`);
 function branchFiles(projectPath) {
     if (!isGitRepo(projectPath))
         return [];
@@ -127,7 +141,7 @@ function branchFiles(projectPath) {
             ...untrackedFiles(projectPath),
         ]),
     ]
-        .filter((f) => !f.startsWith("lawbook/changes/"))
+        .filter((f) => !isOwnOutput(f))
         .filter((f) => f !== COMPASS_DOC || !onlyMapChanged(projectPath, base))
         .sort();
 }
@@ -150,7 +164,7 @@ function onlyMapChanged(projectPath, base) {
         return false;
     }
 }
-/** New files not yet added, outside ship's own output (`lawbook/changes/`, `.speclaw/`). */
+/** New files not yet added, outside the lawbook's own output ({@link OWN_OUTPUT}). */
 function untrackedFiles(projectPath) {
     return git(projectPath, [
         "-c",
@@ -160,12 +174,12 @@ function untrackedFiles(projectPath) {
         "--exclude-standard",
     ])
         .split("\n")
-        .filter((f) => f && !f.startsWith("lawbook/changes/") && !f.startsWith(".speclaw/"));
+        .filter((f) => f && !isOwnOutput(f));
 }
 function secs(ms) {
     return `${(ms / 1000).toFixed(1)} s`;
 }
-function renderReport(change, discipline, files, gates, passed, date) {
+function renderReport(change, discipline, files, gates, passed, date, others = []) {
     const rows = gates
         .map((g) => `| \`${g.command}\`${g.scope ? ` (${g.scope})` : ""} | ${g.exitCode === 0 ? "pass" : `FAIL (exit ${g.exitCode})`} | ${secs(g.durationMs)} |`)
         .join("\n");
@@ -184,7 +198,12 @@ ${rows || "| (no gates configured) | — | — |"}
 
 ## Files changed
 
-${files.length ? files.map((f) => `- \`${f}\``).join("\n") : "- (none detected)"}
+${files.length ? files.map((f) => `- \`${f}\``).join("\n") : "- (none detected)"}${others.length
+        ? `\n\nPlus ${others.length} file(s) outside this discipline's package: ${others
+            .slice(0, 8)
+            .map((f) => `\`${f}\``)
+            .join(", ")}${others.length > 8 ? ", …" : ""}`
+        : ""}
 
 ## Gate output (tail)
 
@@ -203,6 +222,74 @@ None.
 ${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 discipline a package's tests report under, named for the package
+ * directory: `apps/backend` → `backend`, `apps/web` → `frontend`. A generated
+ * report is never `api.md`: that one documents the contract and the agent writes it.
+ *
+ * @param cwd - Package directory relative to the root (`.` for the root).
+ * @param fallback - The discipline for the root package.
+ */
+function disciplineOf(cwd, fallback) {
+    if (cwd === ".")
+        return fallback;
+    const leaf = cwd.split("/").pop().toLowerCase();
+    if (/^(backend|api|server|service|services)$/.test(leaf))
+        return "backend";
+    if (/^(web|frontend|client|ui|app|site|webapp)$/.test(leaf))
+        return "frontend";
+    if (/^(e2e|playwright|cypress|acceptance)$/.test(leaf))
+        return "e2e";
+    if (/^(mobile|ios|android)$/.test(leaf))
+        return "mobile";
+    return leaf.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || fallback;
+}
+/** A path as one shell word. */
+function shellArg(s) {
+    return /^[\w./-]+$/.test(s) ? s : `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Group the gates into reports. Without per-package gates there is one report
+ * with every gate and file. Otherwise each discipline gets its own test gates
+ * plus the repo-wide ones (lint, build), and the files under its packages.
+ */
+function reportGroups(gates, files, fallback, cwds) {
+    if (cwds.size === 0)
+        return [{ discipline: fallback, gates, files, others: [] }];
+    const shared = gates.filter((g) => !g.discipline);
+    const under = (f, cwd) => cwd !== "." && f.startsWith(`${cwd}/`);
+    const claimed = new Set(files.filter((f) => [...cwds.values()].flat().some((c) => under(f, c))));
+    return [...cwds.entries()].map(([d, dirs]) => {
+        const own = dirs.includes(".")
+            ? files.filter((f) => !claimed.has(f) || dirs.some((c) => under(f, c)))
+            : files.filter((f) => dirs.some((c) => under(f, c)));
+        return {
+            discipline: d,
+            gates: [...shared, ...gates.filter((g) => g.discipline === d)],
+            files: own,
+            others: files.filter((f) => !own.includes(f) && !claimed.has(f)),
+        };
+    });
+}
+/** Marks a report ship wrote, so a later ship may replace or remove it. */
+const GENERATED_MARK = "**Generated by:** `speclaw ship`";
+/** Remove reports an earlier ship generated that this ship no longer writes. */
+function dropStaleReports(projectPath, reportsRel, kept) {
+    const dir = path.join(projectPath, reportsRel);
+    for (const f of fs.readdirSync(dir)) {
+        const rel = path.join(reportsRel, f);
+        if (!f.endsWith(".md") || kept.includes(rel))
+            continue;
+        try {
+            if (fs.readFileSync(path.join(dir, f), "utf8").includes(GENERATED_MARK)) {
+                fs.rmSync(path.join(dir, f));
+            }
+        }
+        catch {
+            // A report that cannot be read is left as it is.
+        }
+    }
+}
 /**
  * The archived folder of a change (`lawbook/changes/archive/<date>-<name>`),
  * newest first, or null.
@@ -243,8 +330,7 @@ function commitSummary(projectPath) {
         `${base}..HEAD`,
         "--",
         ".",
-        ":(exclude)lawbook/changes",
-        ":(exclude).speclaw",
+        ...OWN_OUTPUT_EXCLUDES,
     ])
         .split("\n")
         .filter((l) => !/^[\w-]+-by:/i.test(l))
@@ -274,8 +360,8 @@ const SMALL_FIX_LINES = 10;
  * small fix stays at level 0 however central the code it touches: its blast
  * radius is guarded by the gates and its test, which ceremony would not add to.
  */
-function measureDiff(projectPath, files) {
-    const proposal = measureDiffSignals(projectPath, files);
+function measureDiff(projectPath, files, measured) {
+    const proposal = measured ?? measureDiffSignals(projectPath, files);
     if (!proposal.level || proposal.signals.touchesPublicApi || proposal.signals.touchesGlobalFile) {
         return proposal;
     }
@@ -331,7 +417,7 @@ function measureDiffSignals(projectPath, files) {
     try {
         const file = path.join(projectPath, LEVEL_CACHE);
         fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify({ key: fileSetKey(files), proposal }) + "\n");
+        fs.writeFileSync(file, JSON.stringify({ key: fileSetKey(files), files, proposal }) + "\n");
     }
     catch {
         // The cache only saves time; the measurement stands without it.
@@ -357,6 +443,24 @@ function cachedMeasure(projectPath, files) {
         return null;
     }
 }
+/**
+ * The last measurement when the diff has only grown since it was taken: its
+ * level is a floor for the current one, since a measured level only rises. A
+ * large diff takes seconds to measure and an agent at work outdates every
+ * measurement before it lands, so waiting for an exact one never tells it.
+ */
+function grownFromCache(projectPath, files) {
+    try {
+        const c = JSON.parse(fs.readFileSync(path.join(projectPath, LEVEL_CACHE), "utf8"));
+        if (!c.proposal || !Array.isArray(c.files) || c.files.length === 0)
+            return null;
+        const now = new Set(files);
+        return c.files.every((f) => now.has(f)) ? c.proposal : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Measure the branch's current diff into the level cache (`speclaw
  * measure-diff`, the edit hook's detached background job).
@@ -403,11 +507,11 @@ function scaffoldMeasured(projectPath, name, files, measured) {
     }
 }
 /** Raise a measured level when the branch diff has grown past it; a human-set level stands. */
-function remeasure(projectPath, name, files) {
+function remeasure(projectPath, name, files, measured) {
     const rec = readCeremonyRecord(projectPath, name);
     if (rec?.confirmedBy !== "measured")
         return;
-    const proposal = measureDiff(projectPath, files);
+    const proposal = measured ?? measureDiff(projectPath, files);
     if (proposal.level !== null && proposal.level > rec.confirmedLevel) {
         promoteCeremonyLevel(projectPath, name, proposal.level, "the branch diff grew", proposal);
     }
@@ -420,7 +524,7 @@ function remeasure(projectPath, name, files) {
  *
  * @returns Whether the change was reopened.
  */
-function reopenIfGrown(projectPath, name, archivedRel, files) {
+function reopenIfGrown(projectPath, name, archivedRel, files, measured) {
     const archivedDir = path.join(projectPath, archivedRel);
     let rec = {};
     try {
@@ -441,7 +545,7 @@ function reopenIfGrown(projectPath, name, archivedRel, files) {
     });
     if (atBase.status === 0)
         return false;
-    const proposal = measureDiff(projectPath, files);
+    const proposal = measured ?? measureDiff(projectPath, files);
     if (proposal.level === null || proposal.level <= rec.confirmedLevel)
         return false;
     const changeDir = path.join(projectPath, "lawbook", "changes", name);
@@ -475,11 +579,16 @@ const STUBS = {
  * its record falls back to the commits or the file list, so it costs no turn. Bug-shaped changes keep
  * their own checks (`bugfix.md`) and are not judged here.
  *
+ * A change whose diff touches an API surface (a route, a DTO, a contract file)
+ * also owes `reports/api.md`: the contract is evidence no gate output carries.
+ *
  * @param projectPath - Project root with `lawbook/`.
  * @param name - Change name.
+ * @param files - The branch's changed files; when given, the API surface is
+ *   read from their diff, else from the change's recorded signals.
  * @returns One instruction per missing artifact; empty when the change is documented.
  */
-export function pendingArtifacts(projectPath, name) {
+export function pendingArtifacts(projectPath, name, files) {
     const dir = path.join(projectPath, "lawbook", "changes", name);
     if (!fs.existsSync(dir) || readChangeType(projectPath, name) === "bug")
         return [];
@@ -522,6 +631,19 @@ export function pendingArtifacts(projectPath, name) {
             }
         }
     }
+    // A report ship generated (`ship.discipline: api`) is gate output, not the contract.
+    const apiReport = path.join(dir, "reports", "api.md");
+    const apiWritten = fs.existsSync(apiReport) && !fs.readFileSync(apiReport, "utf8").includes(GENERATED_MARK);
+    if (level > 0 && !apiWritten) {
+        const api = files
+            ? apiSurfaceChanges(projectPath, files).map((h) => h.file)
+            : (readCeremonyRecord(projectPath, name)?.signals.apiSurface ?? []);
+        if (api.length) {
+            out.push(`${rel("reports/api.md")}: document the API contract this change touches (${api
+                .slice(0, 4)
+                .join(", ")}${api.length > 4 ? ", …" : ""}) — method and path, auth, response shape, every status code, and how it was exercised (test client or request against an isolated store)`);
+        }
+    }
     return out;
 }
 /**
@@ -582,7 +704,7 @@ export function shipChange(projectPath, name, opts = {}) {
         ? `Changed ${files.length} file(s): ${files.slice(0, 8).join(", ")}${files.length > 8 ? ", …" : ""}`
         : "No file changes detected.";
     fillRecord(path.join(changeDir, "record.md"), opts.summary ?? (commits || (confirmedLevel(projectPath, name) === 0 ? fileList : "")));
-    const pending = pendingArtifacts(projectPath, name);
+    const pending = pendingArtifacts(projectPath, name, files);
     const t1 = Date.now();
     if (pending.length) {
         const level = confirmedLevel(projectPath, name);
@@ -593,6 +715,7 @@ export function shipChange(projectPath, name, opts = {}) {
             gates: [],
             files,
             report: null,
+            reports: [],
             pending,
             archivedTo: null,
             next: [
@@ -610,6 +733,10 @@ export function shipChange(projectPath, name, opts = {}) {
         };
     }
     const commands = opts.gates ?? cfg.gates ?? detectGates(projectPath);
+    // Level 2+ is the spec lane: its evidence is one report per discipline, so
+    // tests that span several packages run (and report) package by package.
+    const split = (confirmedLevel(projectPath, name) ?? 0) >= 2;
+    const cwds = new Map();
     const gates = [];
     for (const command of commands) {
         const scoped = cfg.tests !== "full" && TEST_GATE_RE.test(command.trim())
@@ -619,6 +746,23 @@ export function shipChange(projectPath, name, opts = {}) {
             gates.push({ command, exitCode: 0, durationMs: 0, tail: "", scope: scoped.scope });
             continue;
         }
+        if (split && scoped?.parts && scoped.parts.length > 1) {
+            for (const part of scoped.parts) {
+                const d = disciplineOf(part.cwd, discipline);
+                cwds.set(d, [...(cwds.get(d) ?? []), part.cwd]);
+                const g = runGate(projectPath, part.cwd === "." ? part.command : `cd ${shellArg(part.cwd)} && ${part.command}`);
+                gates.push({
+                    ...g,
+                    scope: `${part.tests} affected test file(s) in ${part.cwd}; the full suite runs in CI`,
+                    discipline: d,
+                });
+                if (g.exitCode !== 0)
+                    break;
+            }
+            if (gates[gates.length - 1].exitCode !== 0)
+                break;
+            continue;
+        }
         const g = runGate(projectPath, scoped?.command ?? command);
         gates.push(scoped ? { ...g, scope: scoped.scope } : g);
         if (g.exitCode !== 0)
@@ -626,9 +770,16 @@ export function shipChange(projectPath, name, opts = {}) {
     }
     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 reportsRel = path.join(archived && !fs.existsSync(changeDir) ? archived : path.join("lawbook", "changes", name), "reports");
+    fs.mkdirSync(path.join(projectPath, reportsRel), { recursive: true });
+    const reports = [];
+    for (const r of reportGroups(gates, files, discipline, cwds)) {
+        const rel = path.join(reportsRel, `${r.discipline}.md`);
+        fs.writeFileSync(path.join(projectPath, rel), renderReport(name, r.discipline, r.files, r.gates, gatesPassed, date, r.others));
+        reports.push(rel);
+    }
+    dropStaleReports(projectPath, reportsRel, reports);
+    const reportRel = reports[0];
     const t3 = Date.now();
     let archivedTo = null;
     const next = [];
@@ -661,6 +812,7 @@ export function shipChange(projectPath, name, opts = {}) {
         gates,
         files,
         report: reportRel,
+        reports,
         pending,
         archivedTo,
         next,
@@ -674,6 +826,40 @@ export function shipChange(projectPath, name, opts = {}) {
         },
     };
 }
+/** A gate's short name for a one-line summary: `lint`, `build`, `tests backend`. */
+function gateLabel(g) {
+    if (g.scope)
+        return g.discipline ? `tests ${g.discipline}` : "tests";
+    const short = g.command.replace(/^(npm|pnpm|yarn)( run)? /, "");
+    return short.length > 40 ? `${short.slice(0, 39)}…` : short;
+}
+/**
+ * The one line the `Stop` hook shows the user after a ship: what ran, how it
+ * went, and what is left — so a stop that blocks nothing is never silent.
+ *
+ * @param r - The ship result.
+ * @param blocked - Whether this stop was sent back to the agent.
+ * @returns The summary, prefixed `speclaw:`.
+ */
+export function stopSummary(r, blocked) {
+    if (r.pending.length) {
+        const owed = [...new Set(r.pending.map((p) => path.basename(p.split(":")[0])))].join(", ");
+        return blocked
+            ? `speclaw: ${/^level \d/.exec(r.next[0] ?? "")?.[0] ?? "the change"} owes ${owed} — sent back to the agent; the gates run once they are written`
+            : `speclaw: still owed after a second stop: ${owed} — the gates did not run`;
+    }
+    const ran = r.gates.map((g) => `${gateLabel(g)} ${secs(g.durationMs)}`).join(" · ");
+    if (!r.gatesPassed) {
+        const failed = r.gates[r.gates.length - 1];
+        return `speclaw: gate FAILED — ${gateLabel(failed)} (exit ${failed.exitCode})${blocked ? " — sent back to the agent" : "; fix it, then stop again"}`;
+    }
+    const where = r.archivedTo
+        ? `archived to ${r.archivedTo}`
+        : r.next.length
+            ? r.next.join("; ")
+            : `report ${r.report}`;
+    return `speclaw: gates PASS${ran ? ` (${ran})` : ""} · ${where}`;
+}
 /** Where {@link docHint} remembers what it last measured and told. */
 const DOC_HINT_STATE = path.join(".speclaw", "doc-hint.json");
 /** The change the hook would ship on this branch: the one last shipped here, else the branch's. */
@@ -712,7 +898,7 @@ export function docHint(projectPath) {
             return null;
         const quick = status
             .split("\n")
-            .filter((l) => !l.includes(" lawbook/changes/") && !l.includes(" .speclaw/"))
+            .filter((l) => !OWN_OUTPUT.some((dir) => l.includes(` ${dir}`)))
             .join("\n");
         const statePath = path.join(projectPath, DOC_HINT_STATE);
         let prev = {};
@@ -741,36 +927,50 @@ export function docHint(projectPath) {
             return null;
         }
         // Measuring a large diff takes seconds — longer than the hook may run —
-        // so it happens in the background and the hint follows on a later call.
-        if (!cachedMeasure(projectPath, files)) {
-            const fresh = prev.pending?.key === key && Date.now() - prev.pending.at < MEASURE_GRACE_MS;
-            if (!fresh)
+        // so it happens in the background, one job at a time; meanwhile a diff
+        // that only grew is told from its last measurement, a floor for its level.
+        let measured = cachedMeasure(projectPath, files);
+        let inFlight;
+        if (!measured) {
+            const running = prev.pending !== undefined &&
+                Date.now() - prev.pending.at < MEASURE_GRACE_MS &&
+                !measuredSince(projectPath, prev.pending.at);
+            if (!running)
                 measureInBackground(projectPath);
-            save({ ...prev, quick, pending: fresh ? prev.pending : { key, at: Date.now() } });
-            return null;
+            inFlight = running ? prev.pending : { key, at: Date.now() };
+            measured = grownFromCache(projectPath, files);
+            if (!measured) {
+                save({ ...prev, quick, pending: inFlight });
+                return null;
+            }
         }
+        const proposal = measureDiff(projectPath, files, measured);
         const change = branchChange(projectPath, branch);
         const changeDir = path.join(projectPath, "lawbook", "changes", change);
         const archived = findArchived(projectPath, change);
         if (fs.existsSync(changeDir))
-            remeasure(projectPath, change, files);
+            remeasure(projectPath, change, files, proposal);
         else if (archived)
-            reopenIfGrown(projectPath, change, archived, files);
-        else {
-            const proposal = measureDiff(projectPath, files);
-            if ((proposal.level ?? 0) > 0)
-                scaffoldMeasured(projectPath, change, files, proposal);
-        }
+            reopenIfGrown(projectPath, change, archived, files, proposal);
+        else if ((proposal.level ?? 0) > 0)
+            scaffoldMeasured(projectPath, change, files, proposal);
         const level = fs.existsSync(changeDir) ? confirmedLevel(projectPath, change) : 0;
-        const pending = level > 0 ? pendingArtifacts(projectPath, change) : [];
-        const told = prev.told?.change === change && prev.told.level === level;
+        const pending = level > 0 ? pendingArtifacts(projectPath, change, files) : [];
+        // Re-told when the change, its level, or the kind of artifact owed changes
+        // (an API report owed later at the same level still has to be said).
+        const owed = [...new Set(pending.map((p) => p.split(":")[0]))].sort().join(",");
+        const told = prev.told?.change === change &&
+            prev.told.level === level &&
+            (prev.told.owed === undefined ||
+                owed.split(",").every((o) => prev.told.owed.split(",").includes(o)));
+        const keep = { quick, key, ...(inFlight ? { pending: inFlight } : {}) };
         if (pending.length === 0 || told) {
-            save({ quick, key, ...(prev.told ? { told: prev.told } : {}) });
+            save({ ...keep, ...(prev.told ? { told: prev.told } : {}) });
             return null;
         }
         // "Told" is recorded only with the hint actually returned, so a level is
         // never marked as told by a call that said nothing.
-        save({ quick, key, told: { change, level } });
+        save({ ...keep, told: { change, level, owed } });
         const why = readCeremonyRecord(projectPath, change)?.rationale ?? "";
         return (`speclaw: this change measures level ${level}${why ? ` (${why})` : ""}. ` +
             `In this same turn, before you stop, write briefly and truthfully:\n- ${pending.join("\n- ")}\n` +
@@ -865,11 +1065,11 @@ function readMarker(projectPath) {
     return { branch: "", change: "", fingerprint: raw };
 }
 /**
- * Fingerprint of the branch's work outside `lawbook/changes/` and `.speclaw/`: every path that
+ * Fingerprint of the branch's work outside the lawbook's own output: every path that
  * differs from the merge base with `main`/`master` or is untracked, with its
  * working-tree contents. A file hashes the same whether it is untracked, staged
  * or committed, so committing work — new files included — is not new work; ship
- * writes under `lawbook/changes/`, so its own output never changes it either.
+ * and archive write only {@link OWN_OUTPUT}, so their output never changes it either.
  * Without a merge base it falls back to the paths changed against HEAD plus HEAD itself.
  */
 function workFingerprint(projectPath) {
@@ -882,8 +1082,7 @@ function workFingerprint(projectPath) {
         base ?? "HEAD",
         "--",
         ".",
-        ":(exclude)lawbook/changes",
-        ":(exclude).speclaw",
+        ...OWN_OUTPUT_EXCLUDES,
     ]).split("\n");
     const hash = createHash("sha256");
     const files = [...new Set([...tracked, ...untrackedFiles(projectPath)])]

package/dist/shared/package-entries.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The entry points the root `package.json` declares in `main` and `bin`. A
+ * built path is mapped back to the source file that produces it when that
+ * file exists, so the entries name code the agent edits. A repo without a
+ * root package, or one that declares neither field (an app or a workspace
+ * root), has none.
+ *
+ * @param projectPath - Project root.
+ * @returns The declared entries, deduplicated by file; empty when none.
+ */
+export function packageEntries(projectPath) {
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(projectPath, "package.json"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const declared = [];
+    if (typeof pkg.main === "string")
+        declared.push({ file: pkg.main, kind: "main" });
+    if (typeof pkg.bin === "string")
+        declared.push({ file: pkg.bin, kind: "bin" });
+    else if (pkg.bin && typeof pkg.bin === "object") {
+        const bins = Object.entries(pkg.bin);
+        for (const [name, file] of bins) {
+            if (typeof file === "string") {
+                declared.push({ file, kind: bins.length > 1 ? `bin ${name}` : "bin" });
+            }
+        }
+    }
+    const seen = new Set();
+    const out = [];
+    for (const e of declared) {
+        const file = sourceOf(projectPath, e.file.replace(/^\.\//, ""));
+        if (seen.has(file))
+            continue;
+        seen.add(file);
+        out.push({ file, kind: e.kind });
+    }
+    return out;
+}
+/** `dist/cli/index.js` → `src/cli/index.ts` when that source exists, else the path unchanged. */
+function sourceOf(projectPath, file) {
+    const m = /^(?:dist|build|lib|out)\/(.+)\.[cm]?js$/.exec(file);
+    if (!m)
+        return file;
+    for (const ext of [".ts", ".tsx", ".mts", ".js", ".mjs"]) {
+        const candidate = `src/${m[1]}${ext}`;
+        if (fs.existsSync(path.join(projectPath, candidate)))
+            return candidate;
+    }
+    return file;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.23",
+  "version": "2.0.25",
   "publishConfig": {
     "access": "public"
   },
@@ -43,8 +43,10 @@
     "check": "prettier --check . && eslint .",
     "budget:calibrate": "node scripts/budget-calibrate.mjs",
     "pretest": "tsc -p tsconfig.test.json && node scripts/prep-test-assets.mjs",
-    "test": "node --test --test-concurrency=1 --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-exclude='dist-test/test/**' --test-coverage-exclude='dist/**' 'dist-test/test/**/*.test.js'",
-    "prepublishOnly": "npm run build"
+    "test": "node --test 'dist-test/test/**/*.test.js'",
+    "prepublishOnly": "npm run build",
+    "test:ci": "node --test --test-concurrency=1 --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-exclude='dist-test/test/**' --test-coverage-exclude='dist/**' 'dist-test/test/**/*.test.js'",
+    "pretest:ci": "npm run pretest"
   },
   "engines": {
     "node": ">=22.16"