@esneiderbravo/speclaw 2.0.22 → 2.0.23

package/dist/modules/compass/register.js

@@ -30,12 +30,21 @@ export function registerCompass(server, opts = {}) {
     };
     add("compass_explore", "Symbol context in one call: source, callers, callees, blast radius, tests. maxDepth>1 returns the whole callee chain with source.", {
         projectPath: z.string(),
-        node: z.string(),
+        node: z.string().optional(),
+        query: z.string().optional(),
         to: z.string().optional(),
         include: includeEnum.optional(),
         mode: z.enum(["brief", "full"]).optional(),
         maxDepth: z.number().int().min(1).max(8).optional(),
-    }, async ({ projectPath, node, to, include, mode, maxDepth }) => {
+    }, async ({ projectPath, node, query, to, include, mode, maxDepth }) => {
+        if (!node) {
+            // Agents send a search phrase here; answer it as a find instead of a
+            // validation error that costs a second call.
+            if (!query)
+                throw new Error("compass_explore requires 'node' (a symbol name)");
+            const found = await findSymbols(projectPath, query, "concept");
+            return text(formatFindResponse(found), { maxTokens: found.cap });
+        }
         const result = await exploreRich({
             projectPath,
             node,

package/dist/modules/cortex/harness.js

@@ -37,7 +37,17 @@ function nowIso() {
 function requireChangeDir(projectPath, change) {
     const resolved = resolveChangeDir(projectPath, change);
     if (!resolved) {
-        throw new Error(`change "${change}" not found under lawbook/changes/`);
+        const changesDir = path.join(specRoot(projectPath), "changes");
+        const active = fs.existsSync(changesDir)
+            ? fs
+                .readdirSync(changesDir, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && e.name !== "archive")
+                .map((e) => e.name)
+            : [];
+        // Name the next step: most misses are a start before the change was drafted.
+        throw new Error(`change "${change}" not found under lawbook/changes/ — draft it first ` +
+            `(lawbook_change action 'draft')` +
+            (active.length ? `; active: ${active.join(", ")}` : ""));
     }
     return resolved;
 }

package/dist/modules/foundation/assets/AGENTS.template.md

@@ -25,7 +25,7 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    sheet: [`docs/compass.md`](docs/compass.md).
 3. **Cortex, always — one brain on the critical path** (*One brain. Many
    agents.*). Branch `<type>/<slug>`, locate with Compass, implement the
-   change and its test yourself, run the tests, finish. The `Stop` hook
+   change and its test yourself, run the tests that cover it, finish. The `Stop` hook
    (`speclaw ship-on-stop`) — or `speclaw ship <change> --summary "<what and
    why>"` as your last step on agents without hooks — sizes the change from
    its diff, names the artifacts that level owes while you edit (the why,
@@ -36,7 +36,10 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    agents only to run three or more large, independent parts in parallel.
    Details: the `cortex` skill and
    [`docs/standards/lawbook.md`](docs/standards/lawbook.md).
-4. **Run the quality gates yourself** before declaring anything done — see
+4. **The quality gates run once** before anything is declared done — by the
+   `Stop` hook where there is one, scoped to the tests the diff reaches (run only
+   those yourself: `speclaw affected-tests --file <path>`; the full suite runs
+   in CI), else by you or `speclaw ship` — see
    [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md):
    - Tests: `{{test_commands}}`
    - Lint / type-check: `{{lint_commands}}`

package/dist/modules/foundation/assets/CLAUDE.template.md

@@ -54,9 +54,11 @@ See [`docs/compass.md`](docs/compass.md).
 
 Every change is built with **Cortex** (*One brain. Many agents.*), and Cortex
 costs no more time than working alone: branch `<type>/<slug>`, locate with
-Compass, implement the change and its test yourself, run the tests, finish.
+Compass, implement the change and its test yourself, run only the tests that
+cover it (`speclaw affected-tests --file <path>` prints the command), finish.
 Then stop: the `Stop` hook (`speclaw ship-on-stop`) sizes the change from its
-diff, runs the gates once, writes the report from their real output, and
+diff, runs the gates once — lint, build and the tests the diff reaches (the
+full suite runs in CI) — writes the report from their real output, and
 archives level-0 work with no agent turns. What the level owes (the why — a
 commit body counts — tasks, delta specs, proposal/design) is named while you
 edit: write it in the same turn. A missing piece or a failing gate comes back
@@ -72,8 +74,10 @@ parallel. Details: the `cortex` skill and
 - Tests: `{{test_commands}}`
 - Lint / type-check: `{{lint_commands}}`
 
-The **tester** role runs them and reports real output. Never claim success you
-did not observe. Full rules:
+With the `Stop` hook they run once, at the stop, scoped to the tests the diff
+reaches — never run the full suite yourself; a failure comes back to you. Without the hook, run them
+yourself (or `speclaw ship`) before declaring anything done. Never claim
+success you did not observe. Full rules:
 [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md).
 
 ## Rule 4 — Conventions

package/dist/modules/foundation/assets/docs/standards/testing-standards.template.md

@@ -1,8 +1,10 @@
 # Testing & Quality Gates — {{project_name}}
 
 The quality law of the project — see [`../../LAWS.md`](../../LAWS.md). These
-gates are non-negotiable: an agent runs them itself and reports real output
-before declaring anything done.
+gates are non-negotiable: they run once, with real output, before anything is
+declared done — by the `Stop` hook where installed (the agent then runs only
+the tests its change touches, never the full suite twice), else by the agent
+itself or `speclaw ship`.
 
 ## Gates
 

package/dist/modules/lawbook/assets/commands/archive.md

@@ -6,5 +6,6 @@ Archive the completed change: $ARGUMENTS
 
 Follow the `archive` skill: confirm every task (or level-0 checklist) is done
 and gates are green, reconcile if the level has delta specs, run
-`lawbook_change` (action: validate), then `lawbook_change` (action: archive) with today's date (YYYY-MM-DD). Sync
-runs only when the ceremony level requires specs. Never move the folder by hand.
+`lawbook_change` (action: validate), then `lawbook_change` (action: archive). Archive dates
+the folder today and syncs the delta specs itself when the level carries them. Never move
+the folder by hand.

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

@@ -1,7 +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 { resolveActiveChange, shipChange } from "./ship.js";
 import { scaffoldBugfix } from "./bugfix.js";
 import { scaffoldFeature } from "./scaffold-change.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
@@ -21,17 +21,27 @@ export const lawbookChangeActions = [
     "harness",
     "ship",
 ];
+// Words agents reach for that name a real action; each one used to cost a failed call.
+const ACTION_SYNONYMS = { create: "draft", new: "draft" };
+/** A list arg sent as one comma- or newline-separated string still means the list. */
+const looseList = z.preprocess((v) => typeof v === "string"
+    ? v
+        .split(/[,\n]/)
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : v, z.array(z.string()));
 export const lawbookChangeSchema = {
     projectPath: z.string(),
-    action: z.enum(lawbookChangeActions),
+    action: z.preprocess((v) => (typeof v === "string" ? (ACTION_SYNONYMS[v] ?? v) : v), z.enum(lawbookChangeActions)),
     change: z.string().optional(),
+    name: z.string().optional(),
     date: z
         .string()
         .regex(/^\d{4}-\d{2}-\d{2}$/)
         .optional(),
     mode: z.enum(["propose", "set", "promote", "explain"]).optional(),
-    paths: z.array(z.string()).optional(),
-    symbols: z.array(z.string()).optional(),
+    paths: looseList.optional(),
+    symbols: looseList.optional(),
     level: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
     reason: z.string().optional(),
     onlyDefects: z.boolean().optional(),
@@ -52,6 +62,21 @@ function requireField(args, field) {
         return v;
     throw new Error(`lawbook_change: action '${args.action}' requires '${String(field)}'`);
 }
+/** The change named by `change` or `name`, else the one the project and branch point at. */
+function targetChange(args) {
+    const named = args.change || args.name;
+    if (named)
+        return named;
+    const inferred = resolveActiveChange(args.projectPath);
+    if (inferred)
+        return inferred;
+    const active = specList(args.projectPath).activeChanges;
+    throw new Error(`lawbook_change: action '${args.action}' requires 'change'` +
+        (active.length ? ` — active: ${active.join(", ")}` : " — no active change; draft one first"));
+}
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
 /**
  * Dispatch `lawbook_change` by action.
  *
@@ -65,7 +90,7 @@ export function handleLawbookChange(args) {
             return specList(args.projectPath);
         case "draft": {
             // Covers: req~feature-draft~1
-            const name = requireField(args, "change");
+            const name = args.change || args.name || requireField(args, "change");
             if (args.bug)
                 return scaffoldBugfix(args.projectPath, name, { level: args.level });
             return scaffoldFeature(args.projectPath, name, {
@@ -75,13 +100,13 @@ export function handleLawbookChange(args) {
             });
         }
         case "validate":
-            return specValidate(args.projectPath, requireField(args, "change"));
+            return specValidate(args.projectPath, targetChange(args));
         case "sync":
-            return specSync(args.projectPath, requireField(args, "change"));
+            return specSync(args.projectPath, targetChange(args));
         case "archive":
-            return specArchive(args.projectPath, requireField(args, "change"), requireField(args, "date"));
+            return specArchive(args.projectPath, targetChange(args), args.date ?? today());
         case "ship":
-            return shipChange(args.projectPath, requireField(args, "change"), {
+            return shipChange(args.projectPath, targetChange(args), {
                 summary: args.note,
                 date: args.date,
             });
@@ -91,7 +116,10 @@ export function handleLawbookChange(args) {
             return handleLevel({
                 projectPath: args.projectPath,
                 mode: args.mode,
-                change: args.change,
+                // `propose` and `explain` only measure; `set` and `promote` act on a change.
+                change: args.mode === "propose" || args.mode === "explain"
+                    ? args.change || args.name
+                    : targetChange(args),
                 paths: args.paths,
                 symbols: args.symbols,
                 level: args.level,
@@ -121,7 +149,7 @@ export function handleLawbookChange(args) {
             }
             const result = handleHarness({
                 projectPath: args.projectPath,
-                change: requireField(args, "change"),
+                change: targetChange(args),
                 harnessOp: args.harnessOp,
                 verdict: args.verdict ?? null,
                 openQuestions: args.openQuestions,

package/dist/modules/lawbook/engine.js

@@ -380,9 +380,11 @@ export function specSync(projectPath, change) {
  *
  * @param projectPath - Absolute path to the project root.
  * @param change - Change name (folder under lawbook/changes/).
+ * @param opts.syncing - The caller promotes the delta specs itself (archive
+ *   does), so an unsynced delta is not a blocker.
  * @returns Human-readable blockers; empty when the change is ready to archive.
  */
-export function specArchivePreconditions(projectPath, change) {
+export function specArchivePreconditions(projectPath, change, opts = {}) {
     const root = specRoot(projectPath);
     const changeDir = path.join(root, "changes", change);
     if (!fs.existsSync(changeDir))
@@ -439,7 +441,7 @@ export function specArchivePreconditions(projectPath, change) {
     const bugNeedsDelta = needs.bugfix &&
         fs.existsSync(bugPath) &&
         preventionRequiresDelta(fs.readFileSync(bugPath, "utf8"));
-    if (needs.deltaSpecs || bugNeedsDelta) {
+    if ((needs.deltaSpecs || bugNeedsDelta) && !opts.syncing) {
         for (const file of deltaSpecFiles(changeDir)) {
             const rel = path.relative(path.join(changeDir, "specs"), file);
             const canonical = path.join(root, "specs", rel);
@@ -474,7 +476,9 @@ export function specArchive(projectPath, change, date) {
     const changeDir = path.join(root, "changes", change);
     if (!fs.existsSync(changeDir))
         throw new Error(`change "${change}" not found`);
-    const blockers = specArchivePreconditions(projectPath, change);
+    // Archive promotes the delta specs below; demanding a manual sync first only
+    // cost agents a failed call and a retry.
+    const blockers = specArchivePreconditions(projectPath, change, { syncing: true });
     if (blockers.length > 0) {
         throw new Error(`cannot archive "${change}" — resolve first:\n${blockers.map((b) => `  - ${b}`).join("\n")}`);
     }

package/dist/modules/lawbook/register.js

@@ -67,13 +67,13 @@ export function registerSpec(server, opts = {}) {
     defineAliasTool(server, {
         name: "lawbook_validate",
         description: "Deprecated alias for lawbook_change action validate.",
-        inputSchema: { projectPath: z.string(), change: z.string() },
+        inputSchema: { projectPath: z.string(), change: z.string().optional() },
         handler: aliasHandler("lawbook_validate", "validate"),
     });
     defineAliasTool(server, {
         name: "lawbook_sync",
         description: "Deprecated alias for lawbook_change action sync.",
-        inputSchema: { projectPath: z.string(), change: z.string() },
+        inputSchema: { projectPath: z.string(), change: z.string().optional() },
         handler: aliasHandler("lawbook_sync", "sync"),
     });
     defineAliasTool(server, {
@@ -81,8 +81,11 @@ export function registerSpec(server, opts = {}) {
         description: "Deprecated alias for lawbook_change action archive.",
         inputSchema: {
             projectPath: z.string(),
-            change: z.string(),
-            date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+            change: z.string().optional(),
+            date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional(),
         },
         handler: aliasHandler("lawbook_archive", "archive"),
     });

package/dist/modules/lawbook/ship.js

@@ -4,9 +4,11 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { changedFiles, isGitRepo, mergeBase, worktreeChangedFiles } from "../../shared/git.js";
+import { isTestPath, loadAffectedConfig, matchesAny } from "../compass/affected-config.js";
+import { affectedTests } from "../compass/affected.js";
 import { COMPASS_DOC, stripCompassMapBlock } from "../../shared/compass-map.js";
 import { handleHarness, readHarness } from "../cortex/harness.js";
-import { deltaSpecFiles, specArchive, specArchivePreconditions } from "./engine.js";
+import { deltaSpecFiles, specArchive, specArchivePreconditions, specList } from "./engine.js";
 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";
@@ -43,6 +45,9 @@ export function readShipConfig(projectPath) {
         const d = /^\s+discipline:\s*["']?([\w-]+)["']?\s*$/.exec(line);
         if (d)
             out.discipline = d[1];
+        const t = /^\s+tests:\s*["']?(affected|full)["']?\s*$/.exec(line);
+        if (t)
+            out.tests = t[1];
     }
     return out;
 }
@@ -66,6 +71,39 @@ export function detectGates(projectPath) {
     const deduped = picked.includes("check") ? picked.filter((s) => s !== "lint") : picked;
     return deduped.map((s) => (s === "test" ? "npm test" : `npm run ${s}`));
 }
+/** The project's whole test suite, as `detectGates` and people write it. */
+const TEST_GATE_RE = /^(npm|pnpm|yarn)( run)? test\s*$/;
+/**
+ * The tests a branch diff reaches, to run at the stop instead of the whole
+ * suite: a one-line fix should not wait on every test in the repo, and the
+ * full suite still runs in CI before merge. Falls back to the full suite when
+ * the selection cannot be trusted — no index, a global file, or source changes
+ * no test reaches.
+ *
+ * @returns The command to run (null: nothing to run) and what it covers.
+ */
+function scopedTestGate(projectPath, fullCommand, files) {
+    const full = (why) => ({ command: fullCommand, scope: `full suite: ${why}` });
+    try {
+        const at = affectedTests(projectPath, { files });
+        if (at.mode === "all")
+            return full(at.reason);
+        if (at.tests.length === 0 || !at.command) {
+            const { thresholds } = loadCeremonyConfig(projectPath);
+            const code = files.filter((f) => !matchesAny(f, thresholds.docGlobs));
+            if (code.length)
+                return full("no test reaches the changed code");
+            return { command: null, scope: "docs only: no test reaches the change" };
+        }
+        return {
+            command: at.command,
+            scope: `${at.tests.length} affected test file(s), ${at.skipped.files} skipped; the full suite runs in CI`,
+        };
+    }
+    catch (e) {
+        return full(e instanceof Error ? e.message : String(e));
+    }
+}
 function runGate(projectPath, command) {
     const start = Date.now();
     const r = spawnSync(command, { cwd: projectPath, shell: true, encoding: "utf8" });
@@ -129,7 +167,7 @@ function secs(ms) {
 }
 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)} |`)
+        .map((g) => `| \`${g.command}\`${g.scope ? ` (${g.scope})` : ""} | ${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\`\`\``)
@@ -228,11 +266,61 @@ function isVersionBump(projectPath, base, file) {
         .filter((l) => /^[+-](?![+-]{2})/.test(l));
     return lines.length > 0 && lines.every((l) => /^[+-]\s*"version"\s*:/.test(l));
 }
+/** Source lines a diff may change, in one source file, and still be a level-0 fix. */
+const SMALL_FIX_LINES = 10;
 /**
  * Propose a ceremony level from the branch diff itself. A release bump of the
- * manifests is not a global change, so it does not raise the level.
+ * manifests is not a global change, so it does not raise the level, and a
+ * 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);
+    if (!proposal.level || proposal.signals.touchesPublicApi || proposal.signals.touchesGlobalFile) {
+        return proposal;
+    }
+    const fix = smallFix(projectPath, files);
+    if (!fix)
+        return proposal;
+    return {
+        ...proposal,
+        level: 0,
+        rationale: `${proposal.rationale}; small fix (${fix.lines} source line(s) in ${fix.files} file) → level 0`,
+    };
+}
+/**
+ * The size of a diff that changes at most one source file (tests and docs
+ * aside) by at most {@link SMALL_FIX_LINES} lines, or null when it is larger.
+ */
+function smallFix(projectPath, files) {
+    const { testGlobs } = loadAffectedConfig(projectPath);
+    const { thresholds } = loadCeremonyConfig(projectPath);
+    const source = files.filter((f) => !isTestPath(f, testGlobs) && !matchesAny(f, thresholds.docGlobs));
+    if (source.length > 1)
+        return null;
+    if (source.length === 0)
+        return { files: 0, lines: 0 };
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    const numstat = base ? git(projectPath, ["diff", "--numstat", base, "--", source[0]]) : "";
+    let lines = numstat
+        .split("\n")
+        .filter(Boolean)
+        .reduce((n, l) => {
+        const [add, del] = l.split("\t");
+        return n + (Number(add) || 0) + (Number(del) || 0);
+    }, 0);
+    if (!numstat.trim()) {
+        // Untracked: every line is new.
+        try {
+            lines = fs.readFileSync(path.join(projectPath, source[0]), "utf8").split("\n").length;
+        }
+        catch {
+            return null;
+        }
+    }
+    return lines <= SMALL_FIX_LINES ? { files: 1, lines } : null;
+}
+function measureDiffSignals(projectPath, files) {
     const cached = cachedMeasure(projectPath, files);
     if (cached)
         return cached;
@@ -524,8 +612,15 @@ export function shipChange(projectPath, name, opts = {}) {
     const commands = opts.gates ?? cfg.gates ?? detectGates(projectPath);
     const gates = [];
     for (const command of commands) {
-        const g = runGate(projectPath, command);
-        gates.push(g);
+        const scoped = cfg.tests !== "full" && TEST_GATE_RE.test(command.trim())
+            ? scopedTestGate(projectPath, command, files)
+            : null;
+        if (scoped && scoped.command === null) {
+            gates.push({ command, exitCode: 0, durationMs: 0, tail: "", scope: scoped.scope });
+            continue;
+        }
+        const g = runGate(projectPath, scoped?.command ?? command);
+        gates.push(scoped ? { ...g, scope: scoped.scope } : g);
         if (g.exitCode !== 0)
             break;
     }
@@ -550,7 +645,7 @@ export function shipChange(projectPath, name, opts = {}) {
     }
     else if (!opts.noArchive) {
         recordGateVerdict(projectPath, name);
-        const pre = specArchivePreconditions(projectPath, name);
+        const pre = specArchivePreconditions(projectPath, name, { syncing: true });
         if (pre.length)
             next.push(...pre);
         else
@@ -711,6 +806,28 @@ export function changeNameForBranch(branch) {
         .replace(/[^a-z0-9-]+/g, "-")
         .replace(/^-+|-+$/g, "") || "change");
 }
+/**
+ * The change an action means when the agent left `change` out: the only
+ * active change, else the one this branch ships (same rule as the stop hook).
+ *
+ * @param projectPath - Project root.
+ * @returns The change name, or null when no single change fits.
+ */
+export function resolveActiveChange(projectPath) {
+    const active = specList(projectPath).activeChanges;
+    if (active.length === 1)
+        return active[0];
+    if (active.length === 0 || !isGitRepo(projectPath))
+        return null;
+    const branch = currentBranch(projectPath);
+    const named = branchChange(projectPath, branch);
+    if (active.includes(named))
+        return named;
+    // `feat/FAR-1360-default-cost-center` ships `default-cost-center` too.
+    const slug = changeNameForBranch(branch);
+    const fits = active.filter((c) => slug.endsWith(`-${c}`) || c.endsWith(`-${slug}`));
+    return fits.length === 1 ? fits[0] : null;
+}
 function git(projectPath, args) {
     const r = spawnSync("git", args, { cwd: projectPath, encoding: "utf8" });
     return r.status === 0 ? r.stdout : "";

package/package.json

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