@esneiderbravo/speclaw 0.3.4 → 0.3.7

package/dist/modules/foundation/graph.js

@@ -1,14 +1,17 @@
 import { underPaths } from "./verify-model.js";
 /** Build the cross-file dependency graph, restricted to `paths` when given. */
-function buildGraph(db, paths) {
+function buildGraph(db, paths, edgeKinds) {
+    const kindFilter = edgeKinds && edgeKinds.length > 0
+        ? ` AND e.kind IN (${edgeKinds.map(() => "?").join(", ")})`
+        : "";
     const rows = db
         .prepare(`SELECT DISTINCT sf.path AS src, df.path AS dst
        FROM edges e
        JOIN files sf ON sf.id = e.src_file_id
        JOIN nodes dn ON dn.id = e.dst_node_id
        JOIN files df ON df.id = dn.file_id
-       WHERE e.dst_node_id IS NOT NULL AND sf.path <> df.path`)
-        .all();
+       WHERE e.dst_node_id IS NOT NULL AND sf.path <> df.path${kindFilter}`)
+        .all(...(edgeKinds && edgeKinds.length > 0 ? edgeKinds : []));
     const adj = new Map();
     for (const { src, dst } of rows) {
         if (!underPaths(src, paths) || !underPaths(dst, paths))
@@ -203,7 +206,7 @@ function reachableFindings(law, rule, adj) {
  */
 export function runGraphLaw(db, law, paths) {
     const rule = law.verification.rule;
-    const adj = buildGraph(db, paths);
+    const adj = buildGraph(db, paths, rule.edgeKinds);
     const findings = [];
     const wantReachable = rule.reachable === true && rule.from != null && rule.to != null;
     const wantCircular = rule.circular === true || (!rule.circular && !wantReachable);

package/dist/modules/foundation/hooks.js

@@ -3,12 +3,24 @@ import path from "node:path";
 import { agentById } from "../../shared/agents.js";
 import { sha256 } from "../../shared/install.js";
 import { globError, hasBackend } from "./laws.js";
+/** Claude Code `${path}` templates — see https://code.claude.com/docs/en/hooks */
+const SPECLAW_HOOK_INPUT = {
+    projectPath: "${cwd}",
+    event: "${hook_event_name}",
+    toolName: "${tool_name}",
+    payload: {
+        hook_event_name: "${hook_event_name}",
+        tool_name: "${tool_name}",
+        tool_input: { file_path: "${tool_input.file_path}" },
+    },
+};
 /** The speclaw hook object — its `{type, server}` pair is the merge identity. */
 const SPECLAW_HOOK = {
     type: "mcp_tool",
     server: "speclaw",
     tool: "speclaw_check",
     timeout: 5,
+    input: SPECLAW_HOOK_INPUT,
 };
 /** Tool-name matcher for the file-mutating tools the `path` backend can evaluate. */
 const MUTATION_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";

package/dist/modules/foundation/laws.js

@@ -22,6 +22,7 @@ const graphRuleSchema = z.object({
     reachable: z.boolean().optional(),
     from: z.string().optional(),
     to: z.string().optional(),
+    edgeKinds: z.array(z.string()).optional(),
 });
 const verificationSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("path") }),

package/dist/modules/foundation/register-core.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
+import { scaffold } from "./scaffold.js";
+import { checkAction } from "./check.js";
+import { verifyLaws } from "./verify.js";
+import { loadPacks } from "../tools/packs.js";
+import { AGENTS, configureAgent } from "../../shared/agents.js";
+import { emptyReport } from "../../shared/install.js";
+/** Human help text for init_project's questionnaire (not embedded in MCP schemas). */
+const profileFieldHelp = {
+    project_name: "Short project name, e.g. the repo name",
+    project_description: "One-line description of what the project does",
+    organization: "Company/team name",
+    stack_summary: "e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'",
+    architecture: "e.g. 'hexagonal architecture with bounded contexts'",
+    test_commands: "Real commands, e.g. 'pytest backend/tests && npm run test'",
+    lint_commands: "Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'",
+    branch_pattern: "e.g. 'feature/<ticket-id>-<slug>'",
+    commit_style: "e.g. 'conventional commits, imperative, English'",
+    custom_laws: "Extra markdown for LAWS.md — project-specific binding rules",
+    compass_hints: "Markdown bullets with real entrypoints for docs/compass.md",
+    base_standards_extra: "Extra cross-cutting rules for base-standards.md",
+    modules_table: "Markdown table of modules/bounded contexts",
+    layering_rules: "Layers and allowed dependencies for architecture.md",
+    backend_layers: "Backend layer table for backend-standards.md",
+    frontend_layers: "Frontend layer table for frontend-standards.md",
+    versioning_rules: "Versioning/release convention for conventions.md",
+    documentation_extra: "Repo-specific docstring notes for documentation.md",
+};
+/** Lean Zod shape for scaffold — no .describe() text (that cost rides in every request). */
+const profileShape = {
+    project_name: z.string(),
+    project_description: z.string().optional(),
+    organization: z.string().optional(),
+    stack_summary: z.string().optional(),
+    architecture: z.string().optional(),
+    test_commands: z.string().optional(),
+    lint_commands: z.string().optional(),
+    branch_pattern: z.string().optional(),
+    commit_style: z.string().optional(),
+    custom_laws: z.string().optional(),
+    compass_hints: z.string().optional(),
+    base_standards_extra: z.string().optional(),
+    modules_table: z.string().optional(),
+    layering_rules: z.string().optional(),
+    backend_layers: z.string().optional(),
+    frontend_layers: z.string().optional(),
+    versioning_rules: z.string().optional(),
+    documentation_extra: z.string().optional(),
+};
+function makeAdd(server, minimal) {
+    return (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+}
+/**
+ * Foundation tools except `doctor`. Lives in a separate file so budget/doctor
+ * measurement can import it without forming a file-level SCC through
+ * `register.ts` → `doctor.ts` → `context-budget.ts`.
+ */
+export function registerFoundationCore(server, opts = {}) {
+    const add = makeAdd(server, Boolean(opts.minimal));
+    add("init_project", "Start here to initialize speclaw: returns the analysis questionnaire and packs.", { projectPath: z.string() }, async () => {
+        const packs = loadPacks();
+        return text({
+            instructions: [
+                "1. Analyze the repository at projectPath and fill in every profile field below with REAL values from the codebase (read package.json / pyproject.toml / CI configs / README — do not invent).",
+                "2. The foundation is a set of GRANULAR standards under docs/standards/ (base, architecture, backend, frontend, testing, conventions, lawbook), bound by LAWS.md and referenced from CLAUDE.md/AGENTS.md. Fill their structured fields from the real repo: modules_table and layering_rules (architecture), backend_layers, frontend_layers, versioning_rules, and any base_standards_extra. Omit a field only when that standard genuinely doesn't apply to this stack.",
+                "3. Suggest packs: add stack packs whose 'detect' hints match dependencies you found; offer the rest. Ask the user which packs to install (the lawbook workflow is always installed).",
+                "4. Infer the working language and the branch/commit/tracker conventions from the repo itself — the language already used in docstrings, commit messages, branch names, and PR/ticket bodies. Do NOT ask the user or assume English; match what the repo does, and set branch_pattern/commit_style accordingly. speclaw does not prescribe a ticket tool — leave tracker linkage to the team's own convention.",
+                "5. Draft any custom_laws (extra binding rules for LAWS.md) from conventions you observed that the standard set doesn't cover.",
+                "6. Call the 'scaffold' tool with { projectPath, profile, packs }.",
+                "7. Follow the nextSteps returned by scaffold: complete the HTML-comment sections still left in docs/standards/*, then run the lawbook_init and compass_index tools (both built into speclaw — no external installs).",
+            ],
+            profileFields: profileFieldHelp,
+            packs,
+        });
+    });
+    add("scaffold", "Write foundation, lawbook workflow, packs, IDE symlinks, and .mcp.json. Never overwrites.", {
+        projectPath: z.string(),
+        profile: z.object(profileShape),
+        packs: z.array(z.string()),
+        agents: z.array(z.string()).optional(),
+    }, async ({ projectPath, profile, packs, agents }) => text(scaffold(projectPath, profile, packs, agents ?? [])));
+    add("configure_agent", "Add one agent's IDE symlinks and MCP config to an already-scaffolded project.", {
+        projectPath: z.string(),
+        agent: z.enum(AGENTS.map((a) => a.id)),
+    }, async ({ projectPath, agent }) => {
+        const report = emptyReport();
+        configureAgent(projectPath, agent, report);
+        return text(report);
+    });
+    add("speclaw_check", "Invoked by speclaw's hooks to enforce laws — do not call directly.", {
+        projectPath: z.string(),
+        event: z.enum(["PreToolUse", "PostToolUse", "Stop", "InstructionsLoaded"]),
+        toolName: z.string().optional(),
+        payload: z.record(z.unknown()),
+    }, async ({ projectPath, event, toolName, payload }) => text(checkAction({ projectPath, event: event, toolName, payload })));
+    add("law_verify", "Verify deterministic deps/graph laws and return violations by file.", {
+        projectPath: z.string(),
+        paths: z.array(z.string()).optional(),
+        engines: z.array(z.enum(["deps", "graph"])).optional(),
+        lawIds: z.array(z.string()).optional(),
+    }, async ({ projectPath, paths, engines, lawIds }) => text(verifyLaws({ projectPath, paths, engines: engines, lawIds })));
+}

package/dist/modules/foundation/register.js

@@ -1,163 +1,26 @@
 import { z } from "zod";
-import { text } from "../../shared/mcp.js";
-import { scaffold } from "./scaffold.js";
-import { doctor } from "./doctor.js";
-import { checkAction } from "./check.js";
-import { verifyLaws } from "./verify.js";
-import { loadPacks } from "../tools/packs.js";
-import { AGENTS, configureAgent } from "../../shared/agents.js";
-import { emptyReport } from "../../shared/install.js";
-const profileShape = {
-    project_name: z.string().describe("Short project name, e.g. the repo name"),
-    project_description: z
-        .string()
-        .optional()
-        .describe("One-line description of what the project does"),
-    organization: z.string().optional().describe("Company/team name"),
-    stack_summary: z
-        .string()
-        .optional()
-        .describe("e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'"),
-    architecture: z
-        .string()
-        .optional()
-        .describe("e.g. 'hexagonal architecture with bounded contexts'"),
-    test_commands: z
-        .string()
-        .optional()
-        .describe("Real commands, e.g. 'pytest backend/tests && npm run test'"),
-    lint_commands: z
-        .string()
-        .optional()
-        .describe("Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'"),
-    branch_pattern: z.string().optional().describe("e.g. 'feature/<ticket-id>-<slug>'"),
-    commit_style: z.string().optional().describe("e.g. 'conventional commits, imperative, English'"),
-    custom_laws: z
-        .string()
-        .optional()
-        .describe("Extra markdown appended to LAWS.md — project-specific binding rules the analysis surfaced"),
-    compass_hints: z
-        .string()
-        .optional()
-        .describe("Markdown bullets with the repo's real entrypoints and common traces, inserted into docs/compass.md"),
-    base_standards_extra: z
-        .string()
-        .optional()
-        .describe("Markdown with any project-specific cross-cutting rules, appended to docs/standards/base-standards.md"),
-    modules_table: z
-        .string()
-        .optional()
-        .describe("Markdown table of the repo's real modules/bounded contexts + one-line responsibility, for docs/standards/architecture.md"),
-    layering_rules: z
-        .string()
-        .optional()
-        .describe("Markdown describing the layers and their allowed dependencies, for docs/standards/architecture.md"),
-    backend_layers: z
-        .string()
-        .optional()
-        .describe("Markdown layer table (Layer | File | Responsibility) from the real backend, for docs/standards/backend-standards.md"),
-    frontend_layers: z
-        .string()
-        .optional()
-        .describe("Markdown layer table from the real frontend, for docs/standards/frontend-standards.md"),
-    versioning_rules: z
-        .string()
-        .optional()
-        .describe("The repo's versioning/release convention, for docs/standards/conventions.md"),
-    documentation_extra: z
-        .string()
-        .optional()
-        .describe("Repo-specific docstring notes (keep only the languages used, the enforced linter), appended to docs/standards/documentation.md"),
-};
-// ─── The foundation module: analyze the repo, then write the constitution ───
-/** Register the foundation MCP tools (init_project, scaffold, configure_agent, doctor). */
-export function registerFoundation(server) {
-    server.registerTool("init_project", {
-        description: "START HERE to initialize speclaw in a project. Returns the analysis questionnaire the agent must answer by reading the target repo, plus the available skill packs. Do NOT guess answers — investigate the codebase (package.json, pyproject.toml, CI config, existing docs) and confirm the pack selection with the user before calling scaffold.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project to initialize"),
-        },
-    }, async () => {
-        const packs = loadPacks();
-        return text({
-            instructions: [
-                "1. Analyze the repository at projectPath and fill in every profile field below with REAL values from the codebase (read package.json / pyproject.toml / CI configs / README — do not invent).",
-                "2. The foundation is a set of GRANULAR standards under docs/standards/ (base, architecture, backend, frontend, testing, conventions, lawbook), bound by LAWS.md and referenced from CLAUDE.md/AGENTS.md. Fill their structured fields from the real repo: modules_table and layering_rules (architecture), backend_layers, frontend_layers, versioning_rules, and any base_standards_extra. Omit a field only when that standard genuinely doesn't apply to this stack.",
-                "3. Suggest packs: add stack packs whose 'detect' hints match dependencies you found; offer the rest. Ask the user which packs to install (the lawbook workflow is always installed).",
-                "4. Infer the working language and the branch/commit/tracker conventions from the repo itself — the language already used in docstrings, commit messages, branch names, and PR/ticket bodies. Do NOT ask the user or assume English; match what the repo does, and set branch_pattern/commit_style accordingly. speclaw does not prescribe a ticket tool — leave tracker linkage to the team's own convention.",
-                "5. Draft any custom_laws (extra binding rules for LAWS.md) from conventions you observed that the standard set doesn't cover.",
-                "6. Call the 'scaffold' tool with { projectPath, profile, packs }.",
-                "7. Follow the nextSteps returned by scaffold: complete the HTML-comment sections still left in docs/standards/*, then run the lawbook_init and compass_index tools (both built into speclaw — no external installs).",
-            ],
-            profileFields: Object.fromEntries(Object.entries(profileShape).map(([key, schema]) => [key, schema.description ?? ""])),
-            packs,
-        });
-    });
-    server.registerTool("scaffold", {
-        description: "Write the speclaw setup into a project: the foundation (LAWS.md constitution + granular docs/standards/* + CLAUDE.md + AGENTS.md + docs/compass.md), the lawbook workflow (always), the selected tool packs, multi-IDE symlinks (.claude/.cursor/.codex/.agents), .mcp.json wiring for speclaw, and .gitignore for .speclaw/. Never overwrites existing files. Call init_project first.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            profile: z.object(profileShape).describe("Project profile gathered by analyzing the repo"),
-            packs: z.array(z.string()).describe("Optional tool pack names (quality, workflow, agents)"),
-            agents: z
-                .array(z.string())
-                .optional()
-                .describe(`Agent ids to configure (symlinks + MCP): ${AGENTS.map((a) => a.id).join(", ")}. Usually the CLI handles this; omit to write content only.`),
-        },
-    }, async ({ projectPath, profile, packs, agents }) => text(scaffold(projectPath, profile, packs, agents ?? [])));
-    server.registerTool("configure_agent", {
-        description: "Configure one agent's integration in an already-scaffolded project: create its IDE symlinks into ai-specs and register the speclaw MCP server in its config. Re-runnable; add agents one at a time.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            agent: z
-                .enum(AGENTS.map((a) => a.id))
-                .describe("Agent id to configure"),
-        },
-    }, async ({ projectPath, agent }) => {
-        const report = emptyReport();
-        configureAgent(projectPath, agent, report);
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
+import { registerFoundationCore } from "./register-core.js";
+export { registerFoundationCore } from "./register-core.js";
+const DOCTOR_DESCRIPTION = "Verify the speclaw install; returns a versioned DoctorReport (schemaVersion 1).";
+/** Register foundation MCP tools (core + doctor). */
+export function registerFoundation(server, opts = {}) {
+    registerFoundationCore(server, opts);
+    const minimal = Boolean(opts.minimal);
+    if (!shouldExpose("doctor", minimal))
+        return;
+    const inputSchema = { projectPath: z.string() };
+    const handler = async ({ projectPath }) => {
+        // Lazy load: register.ts must stay out of the context-budget → doctor SCC.
+        const { doctor } = await import("./doctor.js");
+        const report = await doctor(projectPath, { redact: true });
         return text(report);
-    });
-    server.registerTool("speclaw_check", {
-        // ≤12 words: this is invoked by speclaw's hooks, never called directly.
-        description: "Invoked by speclaw's hooks to enforce laws — do not call directly.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            event: z
-                .enum(["PreToolUse", "PostToolUse", "Stop", "InstructionsLoaded"])
-                .describe("The hook event that fired"),
-            toolName: z.string().optional().describe("The tool the agent is invoking, when relevant"),
-            payload: z.record(z.unknown()).describe("The raw hook event payload from the agent"),
-        },
-    }, async ({ projectPath, event, toolName, payload }) => text(checkAction({ projectPath, event: event, toolName, payload })));
-    server.registerTool("law_verify", {
-        // ≤30 words: the batch counterpart to speclaw_check, for the Stop hook and CI.
-        description: "Verify the project's deterministic laws (dependency and graph rules) and return violations by file. Run before claiming an architecture task done.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            paths: z
-                .array(z.string())
-                .optional()
-                .describe("Restrict to source files under these project-relative paths"),
-            engines: z
-                .array(z.enum(["deps", "graph"]))
-                .optional()
-                .describe("Which batch engines to run; omit for all"),
-            lawIds: z.array(z.string()).optional().describe("Restrict to these law ids"),
-        },
-    }, async ({ projectPath, paths, engines, lawIds }) => text(verifyLaws({ projectPath, paths, engines: engines, lawIds })));
-    server.registerTool("doctor", {
-        description: "Verify a speclaw installation: ai-specs presence, the foundation (LAWS.md + standards + agent contracts), IDE symlinks health, the lawbook/ workflow, the Compass index, and .mcp.json wiring. Returns a checklist with remediation hints.",
-        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
-    }, async ({ projectPath }) => {
-        const checks = doctor(projectPath);
-        const failed = checks.filter((c) => !c.ok);
-        return text({
-            healthy: failed.length === 0,
-            checks,
-            summary: failed.length === 0
-                ? "Everything is within the law."
-                : `${failed.length} check(s) failed — see details.`,
-        });
+    };
+    defineTool(server, {
+        name: "doctor",
+        description: DOCTOR_DESCRIPTION,
+        inputSchema,
+        handler,
     });
 }

package/dist/modules/foundation/scaffold.js

@@ -159,7 +159,7 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // Record what was installed so `speclaw update` can re-apply these packs and
     // gate feature migrations by version, plus the managed-file baselines that let
     // a later update tell user edits from stale files.
-    writeManifest(projectPath, pkgVersion(), packNames, record);
+    writeManifest(projectPath, pkgVersion(), packNames, record, opts.minimal !== undefined ? { minimal: opts.minimal } : {});
     report.nextSteps = [
         "Run the `lawbook_init` tool to set up the spec-driven workflow (creates lawbook/). No external CLI needed — it's built into speclaw.",
         "Run the `compass_index` tool to build the local code graph (.speclaw/). No install, no LLM — it's built into speclaw. Re-run it after significant edits.",

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

@@ -14,34 +14,4 @@ reason) while any task is unchecked, while `reports/` holds no discipline report
 or while the delta specs are not yet synced into the canonical specs. So archive
 is the last step of a completed change: reconcile, sync, then archive.
 
-## Steps
-
-1. Confirm the change is truly done: every task in `tasks.md` checked, quality
-   gates green, behavior verified, and the discipline reports written under
-   `reports/`.
-
-2. **Reconciliation review (agent-executed).** Run the reconciliation from the
-   `sync` skill: reconstruct what was built (branch diff since draft +
-   `compass_explore` / `compass_impact`) and compare it to the change's delta
-   specs.
-   - **If the code drifted past the contracts:** show short insights — a tight
-     bullet list of what was built outside the delta specs and why it matters
-     (e.g. "DB path renamed to `data/app.db` + auto-migration — infra behavior
-     absent from the spec") — and reconcile the delta specs (write the drift
-     in). Drift left unreconciled cannot be archived: the specs-synced gate will
-     block it.
-   - **If nothing drifted:** say so and continue.
-
-3. Run `lawbook_validate`, then `lawbook_sync` to promote the delta specs into
-   `lawbook/specs/`. This is required, not optional: `lawbook_archive` refuses
-   unless the canonical specs already match the delta specs.
-
-4. Run the `lawbook_archive` tool with the change name and today's date
-   (`YYYY-MM-DD`). It re-checks the gate deterministically and, if it passes,
-   moves `lawbook/changes/<name>/` to `lawbook/changes/archive/<date>-<name>/`.
-   If it refuses, resolve the reported blockers (unchecked tasks, missing
-   reports, unsynced specs) and retry.
-
-5. Report the archive path, what you reconciled (or that nothing drifted), and
-   the promoted specs. Never move the folder by hand — a manual `mv` skips the
-   gate and hides an incomplete change.
+Read `steps/01-confirm-done.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/archive/steps/01-confirm-done.md

@@ -0,0 +1,7 @@
+# Confirm the change is done
+
+Confirm the change is truly done: every task in `tasks.md` checked, quality
+gates green, behavior verified, and the discipline reports written under
+`reports/`.
+
+Next: read `steps/02-reconcile.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/archive/steps/02-reconcile.md

@@ -0,0 +1,15 @@
+# Reconciliation review (agent-executed)
+
+Run the reconciliation from the `sync` skill: reconstruct what was built
+(branch diff since draft + `compass_explore` / `compass_impact`) and compare it
+to the change's delta specs.
+
+- **If the code drifted past the contracts:** show short insights — a tight
+  bullet list of what was built outside the delta specs and why it matters
+  (e.g. "DB path renamed to `data/app.db` + auto-migration — infra behavior
+  absent from the spec") — and reconcile the delta specs (write the drift
+  in). Drift left unreconciled cannot be archived: the specs-synced gate will
+  block it.
+- **If nothing drifted:** say so and continue.
+
+Next: read `steps/03-validate-and-sync.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/archive/steps/03-validate-and-sync.md

@@ -0,0 +1,7 @@
+# Validate and sync
+
+Run `lawbook_validate`, then `lawbook_sync` to promote the delta specs into
+`lawbook/specs/`. This is required, not optional: `lawbook_archive` refuses
+unless the canonical specs already match the delta specs.
+
+Next: read `steps/04-archive.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/archive/steps/04-archive.md

@@ -0,0 +1,9 @@
+# Archive
+
+Run the `lawbook_archive` tool with the change name and today's date
+(`YYYY-MM-DD`). It re-checks the gate deterministically and, if it passes,
+moves `lawbook/changes/<name>/` to `lawbook/changes/archive/<date>-<name>/`.
+If it refuses, resolve the reported blockers (unchecked tasks, missing
+reports, unsynced specs) and retry.
+
+Next: read `steps/05-report.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/archive/steps/05-report.md

@@ -0,0 +1,7 @@
+# Report
+
+Report the archive path, what you reconciled (or that nothing drifted), and
+the promoted specs. Never move the folder by hand — a manual `mv` skips the
+gate and hides an incomplete change.
+
+No further steps remain — archive workflow complete.

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

@@ -8,104 +8,6 @@ description: Implement the tasks of a drafted change, following its spec and the
 Work through a change's `tasks.md` in order, keeping code, spec, and standards
 in lockstep.
 
-## Step 0 — Load the change
+Use when the user wants to start or continue implementing a drafted change.
 
-- Read `lawbook/changes/<name>/proposal.md`, `tasks.md`, and the delta specs under
-  `specs/`. If unsure which change, run `lawbook_list`.
-- Read the governing standards in `docs/standards/` for the areas you'll touch.
-
-## Step 1 — Branch first
-
-Create the feature branch (the mandatory Step 0 in `tasks.md`), following the
-repo's branch pattern `{{branch_pattern}}`.
-
-## Step 2 — Implement task by task
-
-- Use `compass_explore` before editing to see a symbol's callers/callees and
-  blast radius; re-run `compass_index` after significant edits to keep the
-  graph fresh.
-- Make the smallest correct change; match the surrounding code.
-- The code must satisfy the delta spec exactly. If reality diverges from the
-  spec, update the spec in the change (not silently) — the two must agree.
-- Check off each task in `tasks.md` as you complete it.
-
-## Step 3 — Quality gates (mandatory)
-
-Run the repo's gates from `docs/standards/testing-standards.md`:
-
-- Tests: `{{test_commands}}`
-- Lint / type-check: `{{lint_commands}}`
-
-Run them yourself and report real output. A red gate blocks completion.
-
-## Step 4 — Manual verification (mandatory, agent executes)
-
-Exercise the behavior (endpoint/UI/CLI) yourself where feasible — do not
-delegate manual testing to the user. Record what you verified.
-
-**Verification is isolated by construction — it never touches real data.** Run it
-against an ephemeral or throwaway store: a temporary copy, an in-memory database
-(`:memory:`), a dedicated test store, or inside a transaction that is rolled
-back — best of all, verify pure/domain logic with fixtures and no store at all.
-Do **not** create, update, or delete the user's real data (a production or
-development database, or files holding real data) as a side effect of proving a
-change, and do **not** run raw store commands (e.g. direct SQL) against a live
-store. Snapshot-and-restore is not a sanctioned method — a stray write slips past
-the restore.
-
-If isolation is genuinely impossible and a real-store write is unavoidable,
-**stop and ask first** — state exactly what you will write and to which store —
-and proceed only after explicit authorization. A backup is not a substitute for
-authorization. Record in the report how verification stayed isolated (or the
-authorization you obtained).
-
-## Step 5 — Write the discipline reports (mandatory)
-
-Record the evidence of testing under `lawbook/changes/<name>/reports/`, one file
-per discipline the change touched, named for that discipline. The set is **open,
-not a fixed list** — `backend.md`, `frontend.md`, and `api.md` are the common
-ones, but write `database.md`, `infra.md`, `security.md`, `performance.md`,
-`e2e.md`, etc. when the change exercises those concerns, and coin a clear
-`<discipline>.md` for anything none of them fit. Omit disciplines the change did
-not touch; the archive is blocked until at least one discipline report exists.
-
-**`api.md` is mandatory whenever the change touches an API surface** — a new or
-modified endpoint, its request/response contract, its status codes, or its
-auth/permission or ordering guarantees. A `backend.md` unit report does not
-substitute for it: the contract is a distinct concern. In `api.md` document the
-method and path, the auth/permissions, the response shape and every status code
-the change governs (e.g. `200`/`401`/`403`/`404`), any ordering guarantee, and
-how the contract was exercised (test client and/or `curl`) — kept isolated from
-any live data store per Step 4.
-
-Each report MUST follow this structure, in order — the fixed shape is what makes
-the evidence trustworthy and reproducible, rather than left to improvisation:
-
-1. **Title + header** — `# <Discipline> checks — <change> (<date>)`, then a line
-   `Date · Branch · Environment/cwd` naming where the commands ran.
-2. **Gates & results** — a `| Check | Command | Result |` table: each gate, the
-   exact command, and its real result with pass/fail counts (e.g. "62 files, 434
-   passed") and ✅/⚠️/❌. Quote real output — never paraphrase a green you did
-   not see.
-3. **Tests added / updated** — each new or changed test and what it asserts; note
-   TDD evidence ("failed before the fix, passes after") where it applies.
-4. **Spec-scenario coverage** — a table mapping each `#### Scenario` in this
-   change's delta specs to how it was verified (a test id, a gate, or a manual
-   step). Every scenario must appear.
-5. **Pre-existing / unrelated failures** — any failing check not caused by this
-   change, with proof it is pre-existing (e.g. it reproduces with the change
-   stashed) — or state "none".
-6. **Pending manual steps** — anything not automated, stated plainly — or "none".
-7. **Verdict** — one line.
-
-If a test kind does not yet apply (e.g. no unit runner), the report says so in
-place of that evidence and records the gates and manual verification that stood
-in.
-
-## Step 6 — Hand off
-
-When every task is checked and gates are green, tell the user the change is
-ready to `sync` and `archive`. Keep the delta specs current as you build, but
-know that `sync` formally reconciles the delta specs against what was actually
-built — so behavior that drifted past the original spec is caught there, not
-left to chance.
+Read `steps/01-load-change.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/build/steps/01-load-change.md

@@ -0,0 +1,7 @@
+# Load the change
+
+- Read `lawbook/changes/<name>/proposal.md`, `tasks.md`, and the delta specs under
+  `specs/`. If unsure which change, run `lawbook_list`.
+- Read the governing standards in `docs/standards/` for the areas you'll touch.
+
+Next: read `steps/02-branch.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/build/steps/02-branch.md

@@ -0,0 +1,6 @@
+# Branch first
+
+Create the feature branch (the mandatory Step 0 in `tasks.md`), following the
+repo's branch pattern `{{branch_pattern}}`.
+
+Next: read `steps/03-implement.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/build/steps/03-implement.md

@@ -0,0 +1,11 @@
+# Implement task by task
+
+- Use `compass_explore` before editing to see a symbol's callers/callees and
+  blast radius; re-run `compass_index` after significant edits to keep the
+  graph fresh.
+- Make the smallest correct change; match the surrounding code.
+- The code must satisfy the delta spec exactly. If reality diverges from the
+  spec, update the spec in the change (not silently) — the two must agree.
+- Check off each task in `tasks.md` as you complete it.
+
+Next: read `steps/04-quality-gates.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/build/steps/04-quality-gates.md

@@ -0,0 +1,10 @@
+# Quality gates (mandatory)
+
+Run the repo's gates from `docs/standards/testing-standards.md`:
+
+- Tests: `{{test_commands}}`
+- Lint / type-check: `{{lint_commands}}`
+
+Run them yourself and report real output. A red gate blocks completion.
+
+Next: read `steps/05-manual-verification.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/build/steps/05-manual-verification.md

@@ -0,0 +1,22 @@
+# Manual verification (mandatory, agent executes)
+
+Exercise the behavior (endpoint/UI/CLI) yourself where feasible — do not
+delegate manual testing to the user. Record what you verified.
+
+**Verification is isolated by construction — it never touches real data.** Run it
+against an ephemeral or throwaway store: a temporary copy, an in-memory database
+(`:memory:`), a dedicated test store, or inside a transaction that is rolled
+back — best of all, verify pure/domain logic with fixtures and no store at all.
+Do **not** create, update, or delete the user's real data (a production or
+development database, or files holding real data) as a side effect of proving a
+change, and do **not** run raw store commands (e.g. direct SQL) against a live
+store. Snapshot-and-restore is not a sanctioned method — a stray write slips past
+the restore.
+
+If isolation is genuinely impossible and a real-store write is unavoidable,
+**stop and ask first** — state exactly what you will write and to which store —
+and proceed only after explicit authorization. A backup is not a substitute for
+authorization. Record in the report how verification stayed isolated (or the
+authorization you obtained).
+
+Next: read `steps/06-discipline-reports.md` and do only what it says.