@esneiderbravo/speclaw 0.3.3 → 0.3.5

package/dist/modules/foundation/sarif.js

@@ -0,0 +1,96 @@
+import { fingerprint } from "./ci.js";
+/** GitHub Code Scanning rejects a run with more than this many results. */
+export const SARIF_RESULT_CAP = 5000;
+function toSarifLevel(s) {
+    if (s === "error")
+        return "error";
+    if (s === "warn")
+        return "warning";
+    return "note";
+}
+/**
+ * A project-relative POSIX URI. Absolute paths (Unix `/…` or Windows `C:\…`)
+ * make GitHub drop the annotation; never emit them.
+ *
+ * @param file - A finding's `file` field (already project-relative POSIX).
+ */
+export function toRepoRelativeUri(file) {
+    return file
+        .replace(/\\/g, "/")
+        .replace(/^[A-Za-z]:/, "")
+        .replace(/^\/+/, "");
+}
+const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 };
+/**
+ * Project a {@link VerifyReport} to SARIF 2.1.0. One `rule` per loaded law
+ * (so GitHub groups alerts by law id); results truncated to
+ * {@link SARIF_RESULT_CAP} by severity; skipped laws become
+ * `toolExecutionNotifications`.
+ *
+ * @param report - The batch report.
+ * @param ctx - Package version and the laws that were loaded.
+ * @returns A JSON-serialisable SARIF log.
+ */
+export function toSarif(report, ctx) {
+    const sorted = [...report.findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+    const dropped = Math.max(0, sorted.length - SARIF_RESULT_CAP);
+    const kept = dropped > 0 ? sorted.slice(0, SARIF_RESULT_CAP) : sorted;
+    const notifications = report.skipped.map((s) => ({
+        level: "warning",
+        message: {
+            text: `Law ${s.lawId} not evaluated: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`,
+        },
+    }));
+    if (dropped > 0) {
+        notifications.push({
+            level: "warning",
+            message: { text: `Truncated ${dropped} findings (SARIF cap ${SARIF_RESULT_CAP})` },
+        });
+    }
+    return {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "speclaw",
+                        informationUri: "https://github.com/esneiderbravo/speclaw",
+                        semanticVersion: ctx.speclawVersion,
+                        rules: ctx.laws.map((law) => ({
+                            id: law.id,
+                            name: law.id.replace(/~/g, "_"),
+                            shortDescription: { text: law.title },
+                            fullDescription: { text: law.prose },
+                            help: {
+                                text: law.rationale ?? law.prose,
+                                markdown: `**${law.title}**\n\n${law.prose}`,
+                            },
+                            properties: { tags: ["speclaw", law.verification.kind] },
+                        })),
+                    },
+                },
+                results: kept.map((f) => ({
+                    ruleId: f.lawId,
+                    level: toSarifLevel(f.severity),
+                    message: { text: f.detail ? `${f.message} ${f.detail}` : f.message },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: toRepoRelativeUri(f.file) },
+                                region: { startLine: f.line ?? 1 },
+                            },
+                        },
+                    ],
+                    partialFingerprints: { "speclaw/v1": fingerprint(f) },
+                })),
+                invocations: [
+                    {
+                        executionSuccessful: report.summary.failed === 0,
+                        toolExecutionNotifications: notifications,
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/modules/foundation/scaffold.js

@@ -8,7 +8,7 @@ import { installWorkflow } from "../lawbook/register.js";
 import { installPack, loadPacks } from "../tools/packs.js";
 import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
-import { readLawManifest, seedManifest, writeLawManifest } from "./laws.js";
+import { mergeSeedLaws, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
 import { installHooks } from "./hooks.js";
 const ASSETS = assetsDir(import.meta.url);
 // Every {{var}} the foundation templates may reference. Ones the agent didn't
@@ -25,19 +25,38 @@ const FOUNDATION_DEFAULTS = {
     documentation_extra: "",
 };
 /**
- * Ensure the project has a law manifest, seeding it from the package's starter
- * laws when absent. The manifest is a derived artifact under the gitignored
- * `.speclaw/`; seeding only when missing keeps a curated manifest (the MVP's
- * authoring surface until executable-laws) from being overwritten on update.
+ * Ensure the project has a law manifest. Missing → seed. Present → append any
+ * shipped seed law whose `id` is absent (never overwrite a curated entry).
  */
 function ensureLawManifest(projectPath, report) {
     const existing = readLawManifest(projectPath);
-    if (existing)
-        return existing;
-    const seed = seedManifest();
-    writeLawManifest(projectPath, seed);
-    report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
-    return seed;
+    if (!existing) {
+        const seed = seedManifest();
+        writeLawManifest(projectPath, seed);
+        report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
+        return seed;
+    }
+    const { manifest, added } = mergeSeedLaws(existing);
+    if (added.length > 0) {
+        writeLawManifest(projectPath, manifest);
+        report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
+    }
+    return manifest;
+}
+/**
+ * Write `.github/workflows/speclaw.yml` from the shipped template when the
+ * path does not exist. Never overwrite — the user's CI is theirs.
+ */
+function ensureVerifyWorkflow(projectPath, report) {
+    const dest = path.join(projectPath, ".github", "workflows", "speclaw.yml");
+    if (fs.existsSync(dest)) {
+        report.skipped.push(dest);
+        return;
+    }
+    const src = path.join(ASSETS, "workflows", "speclaw.yml");
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    report.written.push(dest);
 }
 /**
  * Render the foundation: walk the module's assets/, mirror its structure into
@@ -131,6 +150,7 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // configured. The seam is the manifest: check-dispatcher enforces `path` laws;
     // executable-laws will extend the same manifest with more backends.
     const lawManifest = ensureLawManifest(projectPath, report);
+    ensureVerifyWorkflow(projectPath, report);
     report.hooks = installHooks(projectPath, agents, lawManifest, report, {
         baselines: managedOpts.baselines,
         backup: managedOpts.backup,
@@ -139,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/foundation/verify-model.js

@@ -0,0 +1,14 @@
+/**
+ * True when `file` (POSIX, project-relative) is at or under one of `paths`.
+ *
+ * @param file - A project-relative POSIX path.
+ * @param paths - Optional path prefixes; omitted or empty matches everything.
+ */
+export function underPaths(file, paths) {
+    if (!paths || paths.length === 0)
+        return true;
+    return paths.some((p) => {
+        const norm = p.replace(/\/+$/, "");
+        return file === norm || file.startsWith(norm + "/");
+    });
+}

package/dist/modules/foundation/verify.js

@@ -1,26 +1,27 @@
 import { performance } from "node:perf_hooks";
 import { openDb, indexExists } from "../compass/db.js";
-import { hasBatchBackend, readLawManifest } from "./laws.js";
+import { hasBatchBackend, loadManifestForVerify } from "./laws.js";
 import { runDepsLaw } from "./deps.js";
 import { runGraphLaw } from "./graph.js";
-/** True when `file` (POSIX, project-relative) is at or under one of `paths`. */
-export function underPaths(file, paths) {
-    if (!paths || paths.length === 0)
-        return true;
-    return paths.some((p) => {
-        const norm = p.replace(/\/+$/, "");
-        return file === norm || file.startsWith(norm + "/");
-    });
-}
+export { underPaths } from "./verify-model.js";
+// The batch verifier behind the `law_verify` tool and the `speclaw laws verify`
+// CLI. It evaluates every law whose backend reads the Compass graph (`deps`,
+// `graph`) without a language model, and reports a result honest enough to
+// trust: it distinguishes passed / failed / skipped / unknown and never counts a
+// skip or an unknown as a pass. It is the single home of graph evaluation; the
+// action-time evaluator (`check.ts`) shares this module's model and scope matcher
+// but never runs these engines, so no index query lands on the keystroke budget.
 /**
  * Verify the project's deterministic `deps`/`graph` laws against the Compass
  * index and return a four-state report.
  *
  * When the project has no index, every selected batch law is reported as
- * `skipped` with reason `no-index` (never silently passed). Each evaluated law
- * lands in exactly one of `passed` / `failed` / `unknown`: it fails when the
- * engine produced a finding, is `unknown` when it produced none but rests on
- * unresolved edges (which could hide a violation), and passes otherwise.
+ * `skipped` with reason `no-index` (never silently passed). When the gitignored
+ * manifest file is missing, the shipped seed is used so a clean clone does not
+ * report an empty pass. Each evaluated law lands in exactly one of `passed` /
+ * `failed` / `unknown`: it fails when the engine produced a finding, is
+ * `unknown` when it produced none but rests on unresolved edges (which could
+ * hide a violation), and passes otherwise.
  *
  * @param args - The project, and optional `paths` / `engines` / `lawIds` filters.
  * @returns The {@link VerifyReport}.
@@ -46,9 +47,7 @@ export function verifyLaws(args) {
         unknown,
         elapsedMs: performance.now() - start,
     });
-    const manifest = readLawManifest(args.projectPath);
-    if (!manifest)
-        return done();
+    const manifest = loadManifestForVerify(args.projectPath);
     const engines = args.engines;
     const selected = manifest.laws.filter((law) => {
         if (!hasBatchBackend(law))

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.