@esneiderbravo/speclaw 0.3.4 → 0.3.5

package/dist/modules/foundation/register.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { text } from "../../shared/mcp.js";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
 import { scaffold } from "./scaffold.js";
 import { doctor } from "./doctor.js";
 import { checkAction } from "./check.js";
@@ -7,77 +8,57 @@ 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().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"),
+    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(),
 };
-// ─── 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 () => {
+/** Register foundation MCP tools. */
+export function registerFoundation(server, opts = {}) {
+    const minimal = Boolean(opts.minimal);
+    const add = (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+    add("init_project", "Start here to initialize speclaw: returns the analysis questionnaire and packs.", { projectPath: z.string() }, async () => {
         const packs = loadPacks();
         return text({
             instructions: [
@@ -89,67 +70,37 @@ export function registerFoundation(server) {
                 "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 ?? ""])),
+            profileFields: profileFieldHelp,
             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.`),
-        },
+    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 ?? [])));
-    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"),
-        },
+    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);
     });
-    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"),
-        },
+    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 })));
-    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"),
-        },
+    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 })));
-    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 }) => {
+    add("doctor", "Verify the speclaw install: foundation, symlinks, lawbook, Compass, and MCP wiring.", { projectPath: z.string() }, async ({ projectPath }) => {
         const checks = doctor(projectPath);
         const failed = checks.filter((c) => !c.ok);
         return text({

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.

package/dist/modules/lawbook/assets/skills/build/steps/06-discipline-reports.md

@@ -0,0 +1,44 @@
+# 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 the manual-verification step.
+
+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.
+
+Next: read `steps/07-hand-off.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/build/steps/07-hand-off.md

@@ -0,0 +1,9 @@
+# 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.
+
+No further steps remain — build workflow complete.

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

@@ -9,84 +9,7 @@ Turn a request into a complete, reviewable change under `lawbook/changes/<name>/
 before any implementation. This is speclaw's own spec-driven workflow — no
 external CLI; the mechanical steps are speclaw MCP tools.
 
-## Step 0 — Ensure the workspace exists
+Use when the user wants to start, plan, or propose a new feature, fix, or
+refactor.
 
-If `lawbook/` is missing, run the `lawbook_init` tool once to create it.
-
-## Step 1 — Understand the request and the code
-
-- **Refresh the index first.** Run `compass_index` before reasoning about the
-  code — it is incremental (unchanged files are skipped by hash), so this is
-  cheap and guarantees your decisions rest on the current graph, not a stale one.
-- Clarify what the user wants (feature / fix / refactor) and confirm scope.
-- Use `compass_explore` and `compass_recall` (speclaw's code index) BEFORE
-  grep/read to locate the real code the change touches and its blast radius.
-- Read the governing standards in `docs/standards/` (architecture, backend,
-  frontend, testing) so the change complies with the project's law.
-
-## Step 2 — Pick a change name and its capabilities
-
-- **Change name:** kebab-case, action-oriented (e.g. `add-login`,
-  `fix-shift-overlap`). This is the folder under `lawbook/changes/`, and it is
-  per-feature — always distinct.
-- **Capabilities:** run `lawbook_list` to see the canonical capabilities. A
-  capability is the living contract for an area of behavior — it is *not* the
-  change. When your change modifies behavior an existing capability already
-  governs, reuse that capability's **exact** name so `sync` updates its spec.
-  Introduce a new capability only as a deliberate choice for a genuinely distinct
-  area of behavior — never as a near-duplicate (`transfer` next to an existing
-  `transfers`) of one that already exists.
-
-## Step 3 — Write the artifacts
-
-Create under `lawbook/changes/<name>/`:
-
-- **proposal.md** — the why, the what, non-goals, and whether migrations are
-  needed. Reference the team's tracker ticket if there is one.
-- **specs/<capability>/spec.md** — the delta spec for each affected capability.
-  `sync` promotes this by overwriting the whole canonical file, so the delta must
-  carry the capability's **full** intended spec. When you are updating an existing
-  capability, **start from the current `lawbook/specs/<capability>/spec.md`** and
-  edit on top of it, so its existing requirements are carried forward — do not
-  author it from scratch, or promotion will silently drop them. Use normative
-  language and testable scenarios:
-  ```markdown
-  # <Capability>
-
-  ### Requirement: <name>
-  The system SHALL <requirement>.
-
-  #### Scenario: <name>
-  - Given <context>
-  - When <action>
-  - Then <observable outcome>
-  ```
-- **design.md** — always: approach, alternatives weighed, and the trade-offs
-  behind the decision. For a small change, keep it short — but write it.
-- **tasks.md** — ordered, checkable steps. MUST include the mandatory steps
-  from `lawbook/config.yaml` (feature branch first; tests reviewed and run;
-  manual verification executed by the agent; discipline reports produced; docs
-  updated; archive within the PR).
-- **reports/** — create the folder with a short `reports/README.md` naming the
-  discipline reports the change will need — one per discipline it touches, from an
-  open set (`backend.md`, `frontend.md`, `api.md`, `database.md`, `infra.md`,
-  `security.md`, … — and `api.md` is required when the change touches any API
-  surface) that `build` will fill, following the required report structure
-  (header · gates table ·
-  tests added · spec-scenario coverage · pre-existing failures · pending manual ·
-  verdict — see the `build` skill, Step 5). Every change ships this folder;
-  archive is blocked until it holds at least one discipline report.
-
-## Step 4 — Validate
-
-Run the `lawbook_validate` tool for the change and fix every issue it reports
-(missing artifacts, non-normative specs, missing scenarios) before handing off
-to implementation. Read its advisory **warnings** too: a near-duplicate
-capability name usually means you should reuse the existing capability's exact
-name, and a dropped-requirement warning means the delta should start from the
-canonical. Warnings do not block, but resolve them unless the divergence is
-intentional.
-
-## Step 5 — Hand off
-
-Summarize the change and tell the user it's ready to `build`.
+Read `steps/01-ensure-workspace.md` and do only what it says.