@esneiderbravo/speclaw 2.0.12 → 2.0.13

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: [
             {

package/dist/shared/output-budget.js

@@ -3,26 +3,43 @@ export const OUTPUT_BUDGET = {
     brief: 1500,
     full: 4500,
 };
+/** Brief-mode suffix: the caller can still widen the response with `mode:"full"`. */
 const TRUNCATION_SUFFIX = `\n… [truncated — use mode:"full" or narrow includes]`;
+/** Suffix under the full ceiling or an explicit cap: widening the mode would not help. */
+const FINAL_TRUNCATION_SUFFIX = `\n… [truncated — narrow includes or the query]`;
 /** Stable offline token estimate for budgeting (not a real tokenizer). */
 export function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
 /**
- * Trim `text` to fit `mode` budget; returns the possibly shortened text and
- * whether truncation occurred.
+ * Token ceiling of a {@link TextBudget}.
+ *
+ * @param budget - Output mode or explicit cap.
+ */
+export function budgetTokens(budget) {
+    return typeof budget === "string" ? OUTPUT_BUDGET[budget] : Math.max(1, budget.maxTokens);
+}
+/**
+ * Trim `text` to fit `budget`; returns the possibly shortened text and whether
+ * truncation occurred. Under `brief` the suffix suggests `mode:"full"`; under
+ * `full` or an explicit cap it never does, since that would not widen anything.
+ *
+ * @param text - Text to budget.
+ * @param budget - Output mode (`brief` default) or `{ maxTokens }`.
  */
-export function applyTextBudget(text, mode = "brief") {
-    const budget = OUTPUT_BUDGET[mode];
+// Covers: req~find-response-budget~1
+export function applyTextBudget(text, budget = "brief") {
+    const cap = budgetTokens(budget);
     const tokens = estimateTokens(text);
-    if (tokens <= budget)
+    if (tokens <= cap)
         return { text, truncated: false, omittedChars: 0 };
-    const suffixTokens = estimateTokens(TRUNCATION_SUFFIX);
-    const bodyBudget = Math.max(1, budget - suffixTokens);
+    const suffix = budget === "brief" ? TRUNCATION_SUFFIX : FINAL_TRUNCATION_SUFFIX;
+    const suffixTokens = estimateTokens(suffix);
+    const bodyBudget = Math.max(1, cap - suffixTokens);
     const maxChars = bodyBudget * 4;
     const trimmed = text.slice(0, maxChars);
     return {
-        text: trimmed + TRUNCATION_SUFFIX,
+        text: trimmed + suffix,
         truncated: true,
         omittedChars: text.length - maxChars,
     };
@@ -37,8 +54,11 @@ export function applyTextBudget(text, mode = "brief") {
  * @param truncated - Collector for explicit truncation records.
  */
 export function budgetExploreShape(value, mode, truncated) {
-    const maxCallers = mode === "full" ? 40 : 12;
-    const maxSourceLines = mode === "full" ? 120 : 40;
+    // Full mode sizes source to the full-mode token ceiling (~4500 tokens), so a
+    // typical long function arrives whole; its hints cannot point at mode:"full".
+    const full = mode === "full";
+    const maxCallers = full ? 40 : 12;
+    const maxSourceLines = full ? 400 : 40;
     const symbol = value.symbol;
     if (symbol && typeof symbol.source === "string") {
         const lines = symbol.source.split("\n");
@@ -48,7 +68,9 @@ export function budgetExploreShape(value, mode, truncated) {
             truncated.push({
                 field: "symbol.source",
                 omitted,
-                hint: 'use mode:"full" or omit source from include',
+                hint: full
+                    ? "read the remaining lines from the file by startLine/endLine"
+                    : 'use mode:"full" or omit source from include',
             });
         }
     }
@@ -63,7 +85,9 @@ export function budgetExploreShape(value, mode, truncated) {
             truncated.push({
                 field,
                 omitted,
-                hint: 'use mode:"full" or narrow with include',
+                hint: full
+                    ? "use compass_impact for the full list"
+                    : 'use mode:"full" or narrow with include',
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "publishConfig": {
     "access": "public"
   },