@esneiderbravo/speclaw 2.0.15 → 2.0.17

package/dist/cli/commands/agent.js

@@ -1,8 +1,9 @@
-import { AGENTS, agentById, configureAgent, detectConfiguredAgents } from "../../shared/agents.js";
+import { AGENTS, agentById, detectConfiguredAgents } from "../../shared/agents.js";
+import { addAgent } from "../../modules/foundation/scaffold.js";
 import { emptyReport } from "../../shared/install.js";
 import { ui } from "../lib/ui.js";
 /**
- * List configured agents or configure a new one (symlinks + MCP).
+ * List configured agents or configure a new one (symlinks, MCP, and hooks).
  *
  * @param flags - Parsed flags; `_[0]` is the subcommand (`list`/`add`) and `_[1]` the agent id.
  */
@@ -26,7 +27,7 @@ export async function runAgent(flags) {
             process.exit(1);
         }
         const report = emptyReport();
-        configureAgent(cwd, id, report);
+        addAgent(cwd, id, report);
         ui.ok(`${agentById(id).label} configured`);
         for (const s of report.symlinks)
             ui.info(s);

package/dist/modules/cortex/harness.js

@@ -18,6 +18,7 @@ export { resolveChangeDir } from "./paths.js";
 // Harness types live in the leaf `types.ts` so `compass-gate.ts` can use them
 // without importing this file back (no file-level import cycle).
 export { HARNESS_STAGES, } from "./types.js";
+import { formatJson } from "../../shared/json.js";
 export const harnessOps = ["status", "start", "advance", "rework"];
 const DEFAULT_MAX_REWORK = 3;
 function specRoot(projectPath) {
@@ -69,7 +70,7 @@ export function readHarness(projectPath, change) {
 }
 function writeHarness(projectPath, change, state) {
     const p = harnessPath(projectPath, change);
-    fs.writeFileSync(p, JSON.stringify(state, null, 2) + "\n");
+    fs.writeFileSync(p, formatJson(state));
 }
 function nextAfterExplore(level) {
     return level === 0 ? "implementing" : "planning";
@@ -314,7 +315,7 @@ export function completeHarnessOnArchive(projectPath, change, note) {
             { at: nowIso(), from: "archiving", to: "done", op: "advance", note },
         ],
     };
-    fs.writeFileSync(p, JSON.stringify(next, null, 2) + "\n");
+    fs.writeFileSync(p, formatJson(next));
     return { completed: true, restore: () => fs.writeFileSync(p, original) };
 }
 /**

package/dist/modules/foundation/dialects/agentsmd.js

@@ -1,5 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
 import { commonPrefix, delimit, } from "./types.js";
 const NESTED_THRESHOLD = 3;
+const LAWS_BLOCK_RE = /<!-- speclaw:laws:start -->[\s\S]*?<!-- speclaw:laws:end -->/;
+/**
+ * The agent workflow speclaw relies on (Compass first, Cortex with the Stop
+ * hook), emitted in the generated block only when the hand-written part of
+ * AGENTS.md lacks it.
+ *
+ * @remarks
+ * `update` never edits the personalized AGENTS.md, so a project scaffolded
+ * before Cortex (or one with a hand-written AGENTS.md) never learned to record
+ * its work in the lawbook. The generated block is rewritten on every update,
+ * so it carries the rule there; a file that already states it pays no tokens.
+ *
+ * @param projectPath - Project root holding AGENTS.md.
+ * @returns The section's lines, or none when AGENTS.md already covers it.
+ */
+export function workflowSection(projectPath) {
+    let own = "";
+    try {
+        own = fs.readFileSync(path.join(projectPath, "AGENTS.md"), "utf8").replace(LAWS_BLOCK_RE, "");
+    }
+    catch {
+        // No AGENTS.md yet: the section goes in.
+    }
+    if (/\bCortex\b/.test(own) && /\bcompass_explore\b/.test(own))
+        return [];
+    return [
+        "## speclaw workflow (generated)",
+        "",
+        "- **Compass first.** For any code question call `compass_find` / `compass_explore`",
+        "  before grep or reading files; run `compass_index` first if the graph is missing.",
+        "- **Cortex for every change.** Branch `<type>/<slug>`, locate with Compass, implement",
+        "  the change and its test, run the tests, then stop. In Claude Code the `Stop` hook",
+        "  (`speclaw ship-on-stop`) records the change in `lawbook/` and runs the gates; agents",
+        '  without hooks run `speclaw ship <change> --summary "<what and why>"` once, last.',
+        "  Work that needs a spec goes through the `cortex` skill.",
+        "",
+    ];
+}
 function degradeSection(title, laws) {
     const lines = [`## ${title}`, ""];
     for (const law of laws) {
@@ -35,6 +75,7 @@ export const agentsmdDialect = {
             "_Edit `docs/standards/*.md` or `.speclaw/laws-manifest.json`; do not edit this block._",
             "",
         ];
+        rootParts.push(...workflowSection(ctx.projectPath));
         if (global.length)
             rootParts.push(degradeSection("Global rules", global));
         const nestedMention = [];

package/dist/modules/foundation/scaffold.js

@@ -203,3 +203,34 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     ].filter(Boolean);
     return report;
 }
+/**
+ * Wire one agent into an already-initialized project: its links and MCP entry
+ * (via `configureAgent`) plus, for a hook-capable agent, speclaw's hooks.
+ *
+ * @remarks
+ * `configureAgent` alone left a later-added Claude Code without its
+ * SessionStart / PostToolUse / Stop hooks, so Compass never refreshed and the
+ * Stop hook never shipped the change. The hooks' baseline is recorded in the
+ * manifest when the project has one, so a later `update` treats the file as
+ * speclaw's own rather than a user edit.
+ *
+ * @param projectPath - Project root.
+ * @param agentId - Agent id from `AGENTS` (e.g. `"claude"`).
+ * @param report - Install report mutated in place.
+ * @returns Which agents got hooks, were skipped, and any laws rejected for bad globs.
+ * @throws When `agentId` is not a known agent.
+ */
+export function addAgent(projectPath, agentId, report) {
+    configureAgent(projectPath, agentId, report);
+    const manifest = readManifest(projectPath);
+    const record = {};
+    const lawManifest = readLawManifest(projectPath) ?? { version: 1, laws: [] };
+    const hooks = installHooks(projectPath, [agentId], lawManifest, report, {
+        baselines: manifest?.baselines ?? {},
+        record,
+    });
+    if (manifest && Object.keys(record).length > 0) {
+        writeManifest(projectPath, manifest.version, [], record);
+    }
+    return hooks;
+}

package/dist/modules/foundation/setup-tool.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { loadPacks } from "../tools/packs.js";
-import { AGENTS, configureAgent } from "../../shared/agents.js";
+import { AGENTS } from "../../shared/agents.js";
+import { addAgent } from "./scaffold.js";
 import { emptyReport } from "../../shared/install.js";
 import { refreshAgents } from "../../shared/agents.js";
 import { installPack } from "../tools/packs.js";
@@ -76,7 +77,7 @@ export function handleSpeclawSetup(args) {
             if (!args.agent)
                 throw new Error(`speclaw_setup: action 'configure-agent' requires 'agent'`);
             const report = emptyReport();
-            configureAgent(args.projectPath, args.agent, report);
+            addAgent(args.projectPath, args.agent, report);
             return report;
         }
         case "list-packs":

package/dist/modules/lawbook/anchors.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { openDb, rehydrateAnchors } from "../compass/db.js";
 import { NORMALIZER_VERSION } from "../compass/hash.js";
 import { headSha } from "../../shared/git-history.js";
+import { formatJson } from "../../shared/json.js";
 const STOPWORDS = new Set([
     "SHALL",
     "MUST",
@@ -220,7 +221,7 @@ export function writeAnchorsFile(projectPath, doc) {
     fs.mkdirSync(dir, { recursive: true });
     const sorted = [...doc.anchors].sort((a, b) => `${a.requirementId}\0${a.scenarioId}\0${a.symbolName}`.localeCompare(`${b.requirementId}\0${b.scenarioId}\0${b.symbolName}`));
     const dest = anchorsPath(projectPath, doc.capability);
-    fs.writeFileSync(dest, JSON.stringify({ ...doc, anchors: sorted }, null, 2) + "\n", "utf8");
+    fs.writeFileSync(dest, formatJson({ ...doc, anchors: sorted }), "utf8");
     return dest;
 }
 /** List capability names that already have an anchors file. */

package/dist/modules/lawbook/engine.js

@@ -7,6 +7,7 @@ import { artifactNeeds, confirmedLevel, countUncheckedTasks, gatherSignals, hasD
 import { inferBugResolution, preventionRequiresDelta, validateBugfixContent } from "./bugfix.js";
 import { isPlaceholderDelta } from "./scaffold-change.js";
 import { completeHarnessOnArchive, harnessArchiveBlockers } from "../cortex/harness.js";
+import { formatJson } from "../../shared/json.js";
 // speclaw's own spec-driven workflow engine. Inspired by OpenSpec's model
 // (proposals, delta specs, changes, archive) but implemented from scratch and
 // deliberately simpler: a change's specs/ holds the full intended spec for each
@@ -53,7 +54,17 @@ coverage:
 # EARS requirement linter (strict by default for new projects).
 ears:
   severity: strict
-  vagueWords: [appropriately, properly, as needed, efficiently, user-friendly, robust, adecuadamente, correctamente]
+  vagueWords:
+    [
+      appropriately,
+      properly,
+      as needed,
+      efficiently,
+      user-friendly,
+      robust,
+      adecuadamente,
+      correctamente,
+    ]
   silentCodes: []
 `;
 const README_MD = `# lawbook/ — the spec-driven workflow (speclaw)
@@ -479,7 +490,7 @@ export function specArchive(projectPath, change, date) {
                 rec.changeType = "bug";
                 rec.resolution = inferBugResolution(fs.readFileSync(bugPath, "utf8"));
                 const cj = path.join(changeDir, "change.json");
-                fs.writeFileSync(cj, JSON.stringify(rec, null, 2) + "\n");
+                fs.writeFileSync(cj, formatJson(rec));
             }
         }
     }

package/dist/modules/lawbook/levels.js

@@ -6,6 +6,7 @@ import { impact } from "../compass/query.js";
 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";
 /** Default thresholds from the adaptive-ceremony roadmap. */
 export const DEFAULT_THRESHOLDS = {
     filesTouched: [0, 1, 3, 5],
@@ -376,7 +377,7 @@ export function confirmedLevel(projectPath, change) {
 export function writeCeremonyRecord(projectPath, change, record) {
     const p = changeJsonPath(projectPath, change);
     fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, JSON.stringify(record, null, 2) + "\n");
+    fs.writeFileSync(p, formatJson(record));
 }
 /**
  * The proposal fields stored in a change's `change.json`, or null when there

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

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { gatherSignals, loadCeremonyConfig, proposeLevel, setCeremonyLevel, writeCeremonyRecord, } from "./levels.js";
+import { formatJson } from "../../shared/json.js";
 // Covers: req~feature-draft~1
 /** Change folder names are kebab-case: lowercase alphanumerics joined by single hyphens. */
 export const CHANGE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -45,7 +46,7 @@ export function scaffoldChange(projectPath, name, opts) {
     let record;
     if (level === undefined) {
         record = opts.changeType ? { ...stored, changeType: opts.changeType } : { ...stored };
-        fs.writeFileSync(path.join(changeDir, "change.json"), JSON.stringify(record, null, 2) + "\n");
+        fs.writeFileSync(path.join(changeDir, "change.json"), formatJson(record));
     }
     else {
         let confirmed = setCeremonyLevel(projectPath, name, {

package/dist/modules/lawbook/ship.js

@@ -238,7 +238,7 @@ export function shipChange(projectPath, name, opts = {}) {
             archivedTo = specArchive(projectPath, name, date).archivedTo;
     }
     if (gatesPassed && isGitRepo(projectPath))
-        markShipped(projectPath);
+        markShipped(projectPath, name);
     const t4 = Date.now();
     const gatesMs = t2 - t1;
     return {
@@ -278,32 +278,69 @@ 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. */
+/** The last shipped work; a manual ship and the hook share it. */
 const SHIP_MARKER = path.join(".speclaw", "ship-last");
-function markShipped(projectPath) {
+function currentBranch(projectPath) {
+    return git(projectPath, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+}
+function markShipped(projectPath, change) {
     const marker = path.join(projectPath, SHIP_MARKER);
     fs.mkdirSync(path.dirname(marker), { recursive: true });
-    fs.writeFileSync(marker, workFingerprint(projectPath));
+    const body = {
+        branch: currentBranch(projectPath),
+        change,
+        fingerprint: workFingerprint(projectPath),
+    };
+    fs.writeFileSync(marker, JSON.stringify(body) + "\n");
+}
+/** The last ship marker, or null; a pre-2.0.17 marker (a bare fingerprint) has no change name. */
+function readMarker(projectPath) {
+    const marker = path.join(projectPath, SHIP_MARKER);
+    if (!fs.existsSync(marker))
+        return null;
+    const raw = fs.readFileSync(marker, "utf8").trim();
+    try {
+        const m = JSON.parse(raw);
+        if (typeof m.fingerprint === "string") {
+            return { branch: m.branch ?? "", change: m.change ?? "", fingerprint: m.fingerprint };
+        }
+    }
+    catch {
+        // Legacy marker: the fingerprint alone.
+    }
+    return { branch: "", change: "", fingerprint: raw };
 }
 /**
- * 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.
+ * Fingerprint of the branch's work outside `lawbook/changes/`: the working tree
+ * diffed against the merge base with `main`/`master`, plus untracked files
+ * (names and contents). Committing that work leaves it unchanged — a commit is not new work —
+ * and ship writes under `lawbook/changes/`, so its own output never changes it.
+ * Without a merge base it falls back to the diff against HEAD plus HEAD itself.
  */
 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");
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    const diff = git(projectPath, ["diff", base ?? "HEAD", "--", ".", ":(exclude)lawbook/changes"]);
+    const hash = createHash("sha256");
+    for (const f of git(projectPath, ["ls-files", "--others", "--exclude-standard"]).split("\n")) {
+        if (!f || f.startsWith("lawbook/changes/") || f.startsWith(".speclaw/"))
+            continue;
+        // Contents, not just names: editing a new, not-yet-added file is new work.
+        hash.update(`${f}\n`);
+        try {
+            hash.update(fs.readFileSync(path.join(projectPath, f)));
+        }
+        catch {
+            // Vanished or unreadable since listing: its name stands in.
+        }
+    }
+    const anchor = base ?? git(projectPath, ["rev-parse", "HEAD"]).trim();
+    return hash.update(`\n${anchor}\n${diff}`).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.
+ * last shipped on this branch, else the one 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.
@@ -311,15 +348,19 @@ function workFingerprint(projectPath) {
 export function shipOnStop(projectPath) {
     if (!isGitRepo(projectPath))
         return { skipped: "not-git" };
-    const branch = git(projectPath, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    const branch = currentBranch(projectPath);
     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)) {
+    const marker = readMarker(projectPath);
+    if (marker?.fingerprint === workFingerprint(projectPath)) {
         return { skipped: "unchanged-since-last-ship" };
     }
-    const change = changeNameForBranch(branch);
+    // A change shipped by name on this branch keeps receiving the branch's later
+    // work; the branch name would point at another (possibly archived) change.
+    const change = marker && marker.branch === branch && marker.change
+        ? marker.change
+        : changeNameForBranch(branch);
     return { skipped: null, change, result: shipChange(projectPath, change) };
 }

package/dist/shared/agents.js

@@ -39,6 +39,10 @@ export const AGENTS = [
         label: "Generic (AGENTS.md)",
         ideDir: ".agents",
         linkTargets: ["skills", "commands", "agents", "rules"],
+        // The default agent must still reach Compass and the lawbook tools: without
+        // a server entry the agent contract (Compass first) cannot be followed.
+        // `.mcp.json` is the project-scoped MCP file Claude Code reads.
+        mcpFile: ".mcp.json",
     },
 ];
 /**

package/dist/shared/install.js

@@ -105,7 +105,22 @@ export function ensureGitignore(projectPath, entry, comment, report) {
         if (!content.endsWith("\n"))
             content += "\n";
     }
-    content += `\n# ${comment}\n${entry}\n`;
+    // Entries sharing a comment join its block instead of repeating the comment
+    // once per entry (one agent folder adds several).
+    const lines = content.split("\n");
+    const header = lines.lastIndexOf(`# ${comment}`);
+    if (header !== -1) {
+        let end = header + 1;
+        while (end < lines.length && lines[end].trim() !== "")
+            end++;
+        lines.splice(end, 0, entry);
+        content = lines.join("\n");
+        if (!content.endsWith("\n"))
+            content += "\n";
+    }
+    else {
+        content += `\n# ${comment}\n${entry}\n`;
+    }
     fs.writeFileSync(gitignorePath, content);
     report.written.push(`${gitignorePath} (${entry})`);
 }

package/dist/shared/json.js

@@ -0,0 +1,78 @@
+// JSON that speclaw writes into committed paths (lawbook/) must survive a host
+// repo's `prettier --check .`. Prettier keeps an object expanded when it was
+// written expanded, but collapses an array onto one line whenever it fits the
+// print width — so `JSON.stringify(v, null, 2)` arrays like `["a"]` fail it.
+const PRINT_WIDTH = 100;
+/** True for a non-empty array or object, which Prettier never prints flat inside an array. */
+function isNonEmptyObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && Object.keys(v).length > 0;
+}
+/** Prettier breaks an array of two or more arrays that each hold two or more elements. */
+function mustBreak(arr) {
+    return arr.length > 1 && arr.every((e) => Array.isArray(e) && e.length > 1);
+}
+/** The one-line form of a value, or null when Prettier would never print it flat. */
+function flat(v) {
+    if (Array.isArray(v)) {
+        if (v.length === 0)
+            return "[]";
+        if (mustBreak(v) || v.some(isNonEmptyObject))
+            return null;
+        const parts = v.map(flat);
+        if (parts.some((p) => p === null))
+            return null;
+        return `[${parts.join(", ")}]`;
+    }
+    if (typeof v === "object" && v !== null)
+        return Object.keys(v).length === 0 ? "{}" : null;
+    return JSON.stringify(v);
+}
+function render(v, depth, prefix, comma) {
+    const pad = "  ".repeat(depth);
+    const tail = comma ? "," : "";
+    const one = flat(v);
+    if (one !== null && (!Array.isArray(v) || (pad + prefix + one + tail).length <= PRINT_WIDTH)) {
+        return pad + prefix + one + tail;
+    }
+    if (Array.isArray(v)) {
+        if (v.every((e) => typeof e === "number")) {
+            // Prettier fills number arrays: as many per line as fit.
+            const inner = "  ".repeat(depth + 1);
+            const rows = [];
+            let row = "";
+            v.forEach((n, i) => {
+                const item = JSON.stringify(n) + (i < v.length - 1 ? "," : "");
+                if (row && (inner + row + " " + item).length > PRINT_WIDTH) {
+                    rows.push(inner + row);
+                    row = item;
+                }
+                else
+                    row = row ? `${row} ${item}` : item;
+            });
+            rows.push(inner + row);
+            return `${pad}${prefix}[\n${rows.join("\n")}\n${pad}]${tail}`;
+        }
+        const items = v.map((e, i) => render(e, depth + 1, "", i < v.length - 1));
+        return `${pad}${prefix}[\n${items.join("\n")}\n${pad}]${tail}`;
+    }
+    const entries = Object.entries(v);
+    const props = entries.map(([k, val], i) => render(val, depth + 1, `${JSON.stringify(k)}: `, i < entries.length - 1));
+    return `${pad}${prefix}{\n${props.join("\n")}\n${pad}}${tail}`;
+}
+/**
+ * Serialize a value as 2-space JSON in the layout Prettier gives it, so files
+ * speclaw writes into a host repo stay green under `prettier --check`.
+ *
+ * @remarks
+ * Objects stay expanded (as `JSON.stringify` writes them); arrays go on one
+ * line when they fit in 100 columns and hold no non-empty object. Values are
+ * normalized through `JSON.stringify` first, so `undefined` fields drop out and
+ * `toJSON` applies exactly as before.
+ *
+ * @param value - Any JSON-serializable value.
+ * @returns The formatted JSON text with a trailing newline.
+ */
+export function formatJson(value) {
+    const normalized = JSON.parse(JSON.stringify(value));
+    return render(normalized, 0, "", false) + "\n";
+}

package/package.json

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