@esneiderbravo/speclaw 2.0.2 → 2.0.4

package/dist/modules/lawbook/assets/rules/spec-tasks-mandatory-steps.md

@@ -27,8 +27,8 @@ steps, branch convention, and testing/documentation requirements.
   see the `spec-reports-disciplines` rule) with the unit/integration/e2e results
   for what the feature touched.
 - Update the technical documentation the change touches.
-- Archive the change within the same PR (the `archive` command / `lawbook_archive`
-  tool) after Cortex review/test PASS.
+- Archive the change within the same PR (the `archive` command / `lawbook_change`
+  action `archive`) after Cortex review/test PASS.
 
 ## 3. Manual verification — the tester must execute it
 
@@ -38,10 +38,10 @@ requires verification is not complete until the tester has verified it.
 
 ## 4. Archiving is part of the change
 
-A change is not done until it is archived with `lawbook_archive` (never a manual
+A change is not done until it is archived with `lawbook_change` action `archive` (never a manual
 `mv`). The archive lands in the same PR that implements the change.
 
-`lawbook_archive` is gated: it refuses to archive while any task is unchecked,
+Archive (`lawbook_change` action `archive`) is gated: it refuses to archive while any task is unchecked,
 while `reports/` has no discipline report, while the delta specs are not yet
 synced into the canonical specs, or while harness review/test verdicts are not
 PASS. Resolve those first — the gate is enforced in the engine, so a manual `mv`

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

@@ -1,7 +1,7 @@
 # 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
+(branch diff since draft + `compass_explore` with include `blast_radius`) and compare it
 to the change's delta specs.
 
 - **If the code drifted past the contracts:** show short insights — a tight

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

@@ -1,7 +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`.
+  `specs/`. If unsure which change, run `lawbook_change` (action: 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/cortex/steps/02-dispatch-loop.md

@@ -3,10 +3,26 @@
 For the current Cortex stage (`cortex` action `brief` or `status`):
 
 1. Dispatch (spawn or adopt) the matching role with a clear handoff brief.
-   When the role is the planner, paste the explorer brief into the prompt
-   unchanged: symbols with files, callers and callees, blast radius, standards
-   already read, recommended approach, open questions, and gaps.
-2. On role completion, call the matching Cortex op:
+   - **Explorer template.** Give the intent (what the change should achieve),
+     the symbols or concepts to locate, and the questions to answer. Do not
+     list file paths for the explorer to read — it locates code through
+     Compass (`compass_find` / `compass_explore`) and reports
+     `Compass calls made: N`.
+   - When the role is the planner, paste the explorer brief into the prompt
+     unchanged: symbols with files, callers and callees, blast radius,
+     standards already read, recommended approach, open questions, and gaps.
+2. **Single question round** (after the explorer, before the planner drafts):
+   1. Propose a level with `lawbook_change` action `level`, mode `propose`,
+      passing the paths and symbols from the brief.
+   2. Dispatch the planner for questions only (no artifacts yet).
+   3. Merge the explorer open questions, the planner questions, and the level
+      confirmation into **one** `advance` with `pauseForQuestions` +
+      `openQuestions`. Ask the human once; never open a second round for the
+      level.
+   4. After the answers, record the level with `lawbook_change` action
+      `level`, mode `set` (evidence and answers in `reason`), then redispatch
+      the planner to draft.
+3. On role completion, call the matching Cortex op:
    - exploring → `advance`
    - planning with questions → `advance` + `pauseForQuestions` + `openQuestions`
    - questions after human answers → `advance` (back to planning)
@@ -15,8 +31,8 @@ For the current Cortex stage (`cortex` action `brief` or `status`):
    - reviewing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
    - testing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
    - archiving success → `advance` (to done)
-3. Max rework is 3; if the engine rejects further rework, **ask the human**.
-4. Coordinator never edits `src/`, never archives, never pushes, never runs
+4. Max rework is 3; if the engine rejects further rework, **ask the human**.
+5. Coordinator never edits `src/`, never archives, never pushes, never runs
    `laws accept`.
 
 Next: read `steps/03-complete.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/01-ensure-workspace.md

@@ -1,5 +1,5 @@
 # Ensure the workspace exists
 
-If `lawbook/` is missing, run the `lawbook_init` tool once to create it.
+If `lawbook/` is missing, run `lawbook_change` (action: init) once to create it.
 
 Next: read `steps/02-understand.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/02-understand.md

@@ -10,9 +10,12 @@
   concept) before grep/read to locate the code and its blast radius. Read the
   governing standards in `docs/standards/`.
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
-- **Propose a ceremony level** with `lawbook_level` (mode `propose`) using the
-  paths and symbols from the brief or from that locate pass; **confirm with the
-  human** (mode `set`) before writing artifacts. For an obvious one-liner,
-  offer `speclaw quick` instead.
+- When `change.json` already has a `confirmedLevel` (the coordinator recorded
+  it in the single question round), use that level and skip the separate level
+  confirmation.
+- Otherwise **propose a ceremony level** with `lawbook_change` action `level`
+  (mode `propose`) using the paths and symbols from the brief or from that
+  locate pass; **confirm with the human** (mode `set`) before writing
+  artifacts. For an obvious one-liner, offer `speclaw quick` instead.
 
 Next: read `steps/03-name-capabilities.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/03-name-capabilities.md

@@ -3,12 +3,14 @@
 - **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
+- **Capabilities:** run `lawbook_change` (action: 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.
+- Pass that exact capability name to the scaffold (`--capability` /
+  `capability`), so the delta stub lands in the right capability.
 
 Next: read `steps/04-write-artifacts.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/04-write-artifacts.md

@@ -1,8 +1,18 @@
 # Write the artifacts
 
 Artifact volume follows the **confirmed ceremony level** in `change.json`
-(propose + confirm with `lawbook_level` / the human **before** scaffolding).
-Missing `change.json` means level 3.
+(propose + confirm with `lawbook_change` action `level` / the human **before**
+scaffolding). Missing `change.json` means level 3.
+
+Scaffold with `speclaw lawbook draft <name> --level N --capability <capability>`
+(or `lawbook_change` action `draft` with `change`, `level`, and `capability`),
+passing the exact capability name chosen in the previous step. It creates
+`change.json`, `reports/README.md`, and the level's stub artifacts; fill them
+in. When the capability is new, the delta stub is a marked placeholder:
+replace it with the real spec and remove the
+`<!-- speclaw:placeholder-delta -->` marker (validate warns and sync refuses
+while it remains). For each further capability, add its delta by hand, and
+delete any stub delta the change does not use.
 
 Create under `lawbook/changes/<name>/` only what the level needs:
 

package/dist/modules/lawbook/assets/skills/explore/steps/01-investigate.md

@@ -1,11 +1,20 @@
 # Investigate
 
-- **Refresh the index first.** Run `compass_index` before investigating — it is
-  incremental (unchanged files skipped by hash), so it is cheap and keeps your
-  reasoning on the current graph rather than a stale one.
-- **Understand the code first.** Use `compass_find` (mode: concept) to find relevant code by
-  meaning and `compass_explore` to read a symbol's source plus its callers and
-  callees — before grep/read.
+- **Locate through Compass first.** Your first code-locating call is
+  `compass_find` (mode: concept for an idea, exact for a name) or
+  `compass_explore <symbol>` to read a symbol's source plus its callers and
+  callees. Use `compass_diff_context` when the question is about a diff.
+- **Index only when needed.** Run `compass_index` only when `compass_find`
+  returns nothing or reports a missing or stale index, then retry the find. It
+  is incremental (unchanged files skipped by hash).
+- **Read/Grep code only with a named reason.** Before any Read/Grep/Glob of
+  indexed source code, name which Rule 1 fallback holds: (1) a Compass call ran
+  and returned nothing useful for the query, (2) the graph is missing and
+  `compass_index` cannot build it, or (3) the target is not indexed code
+  (markdown, JSON/config, stylesheets, logs, generated files, lockfiles).
+  "I know which file it is" is not a reason — `compass_explore` takes a path.
+- **Count your Compass calls.** Keep a tally of `compass_explore`,
+  `compass_find`, and `compass_diff_context` calls for the brief.
 - **Ask sharp questions** to surface hidden assumptions, constraints, and edge
   cases. Confirm scope and non-goals.
 - **Check the law.** Read the relevant `docs/standards/` so any direction you

package/dist/modules/lawbook/assets/skills/explore/steps/02-summarize.md

@@ -9,6 +9,8 @@ Produce a brief the planner can use as the code map. Include only these fields:
 - recommended approach
 - open questions
 - gaps: the phrase "nothing unresolved", or each symbol that is still unresolved
+- `Compass calls made: N` — the count of `compass_explore`, `compass_find`, and
+  `compass_diff_context` calls (and their aliases) you made
 
 When the direction is clear, offer to `draft` the change.
 

package/dist/modules/lawbook/assets/skills/investigate/steps/02-hand-off.md

@@ -1,6 +1,6 @@
 # Hand off to draft
 
-- **`compass_impact`** on the confirmed root cause for blast radius.
+- **`compass_explore`** (include `blast_radius`) on the confirmed root cause.
 - **`speclaw lawbook draft --bug <name>`** — pre-seed only; fill repro, fix, regression test, prevention.
 
 Treat the ranking as **evidence**, not a verdict. No further steps remain — investigate workflow complete.

package/dist/modules/lawbook/assets/skills/quick/steps/02-implement.md

@@ -2,6 +2,6 @@
 
 Make the fix, tick every `- [ ]` in `record.md`, and write at least one
 discipline report under `reports/`. Archive with `lawbook_change` (action: archive) (no sync at
-level 0). Promote via `lawbook_level` if scope grew.
+level 0). Promote via `lawbook_change` (action: level, mode: promote) if scope grew.
 
 No further steps — workflow complete.

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

@@ -1,5 +1,5 @@
 # Confirm which change to sync
 
-Confirm which change to sync (run `lawbook_list` if unsure).
+Confirm which change to sync (run `lawbook_change` (action: list) if unsure).
 
 Next: read `steps/02-reconcile.md` and do only what it says.

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

@@ -3,7 +3,7 @@
 Before promoting, compare what was built against the change's delta specs:
 
 - Reconstruct what shipped: `git diff <branch-point>...HEAD` for the change's
-  branch, then `compass_explore` / `compass_impact` on the touched symbols to
+  branch, then `compass_explore` (include `blast_radius`) on the touched symbols to
   understand behavior, not just changed lines.
 - Diff intent vs reality: list behavior that is implemented but missing from,
   or contradicted by, `lawbook/changes/<name>/specs/**`.

package/dist/modules/lawbook/bugfix.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { gatherSignals, loadCeremonyConfig, proposeLevel, setCeremonyLevel, writeCeremonyRecord, } from "./levels.js";
+import { scaffoldChange } from "./scaffold-change.js";
 export const BUGFIX_HEADINGS = [
     "1. Observed symptom",
     "2. Minimal reproduction",
@@ -153,32 +153,28 @@ ${blast}
  * Scaffold a bug change: `bugfix.md`, `change.json`, and `reports/`.
  */
 export function scaffoldBugfix(projectPath, name, opts = {}) {
-    const changeDir = path.join(projectPath, "lawbook", "changes", name);
-    if (fs.existsSync(changeDir)) {
-        throw new Error(`change "${name}" already exists under lawbook/changes/`);
-    }
-    const targets = opts.targets ?? { paths: [], symbols: [] };
-    const { thresholds } = loadCeremonyConfig(projectPath);
-    const signals = gatherSignals(projectPath, targets, thresholds);
-    const proposal = proposeLevel(signals, thresholds);
-    const level = opts.level ?? (proposal.level !== null && proposal.level <= 1 ? proposal.level : 1);
-    fs.mkdirSync(path.join(changeDir, "reports"), { recursive: true });
-    fs.writeFileSync(path.join(changeDir, "bugfix.md"), bugfixTemplate(name, level, opts.seed));
-    fs.writeFileSync(path.join(changeDir, "reports", "README.md"), `# Reports — ${name}\n\nBug reports MUST include the regression test **failing before the fix**.\n`);
-    if (level >= 1) {
-        fs.writeFileSync(path.join(changeDir, "tasks.md"), `- [ ] Reproduce and confirm root cause\n- [ ] Implement fix\n- [ ] Add regression test (red before, green after)\n- [ ] Complete prevention §7\n- [ ] Write discipline report under reports/\n`);
-    }
-    if (level >= 2) {
-        fs.writeFileSync(path.join(changeDir, "design.md"), `# Design — ${name}\n\n## Approach\n\n(structural bugfix — document the fix architecture)\n`);
-    }
-    const record = setCeremonyLevel(projectPath, name, {
-        proposal,
-        level,
-        confirmedBy: "human",
+    const r = scaffoldChange(projectPath, name, {
+        changeType: "bug",
+        targets: opts.targets,
+        level: (proposal) => opts.level ?? (proposal.level !== null && proposal.level <= 1 ? proposal.level : 1),
+        reportsReadme: `# Reports — ${name}\n\nBug reports MUST include the regression test **failing before the fix**.\n`,
+        artifacts: ({ level }) => {
+            const lvl = level ?? 1;
+            const files = {
+                "bugfix.md": bugfixTemplate(name, lvl, opts.seed),
+            };
+            if (lvl >= 1) {
+                files["tasks.md"] =
+                    `- [ ] Reproduce and confirm root cause\n- [ ] Implement fix\n- [ ] Add regression test (red before, green after)\n- [ ] Complete prevention §7\n- [ ] Write discipline report under reports/\n`;
+            }
+            if (lvl >= 2) {
+                files["design.md"] =
+                    `# Design — ${name}\n\n## Approach\n\n(structural bugfix — document the fix architecture)\n`;
+            }
+            return files;
+        },
     });
-    const updated = { ...record, changeType: "bug" };
-    writeCeremonyRecord(projectPath, name, updated);
-    return { change: name, proposal, record: updated, dir: changeDir };
+    return { change: r.change, proposal: r.proposal, record: r.record, dir: r.dir };
 }
 /** Read change type from an archived folder path. */
 export function readChangeTypeFromDir(changeDir) {

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

@@ -1,12 +1,15 @@
 import { z } from "zod";
 import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
 import { handleLevel } from "./quick.js";
+import { scaffoldBugfix } from "./bugfix.js";
+import { scaffoldFeature } from "./scaffold-change.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
 import { handleHarness, harnessOps } from "../cortex/harness.js";
 export const lawbookChangeActions = [
     "init",
     "list",
+    "draft",
     "validate",
     "sync",
     "archive",
@@ -38,6 +41,7 @@ export const lawbookChangeSchema = {
     openQuestions: z.array(z.string()).optional(),
     pauseForQuestions: z.boolean().optional(),
     note: z.string().optional(),
+    bug: z.boolean().optional(),
 };
 function requireField(args, field) {
     const v = args[field];
@@ -56,6 +60,17 @@ export function handleLawbookChange(args) {
             return specInit(args.projectPath);
         case "list":
             return specList(args.projectPath);
+        case "draft": {
+            // Covers: req~feature-draft~1
+            const name = requireField(args, "change");
+            if (args.bug)
+                return scaffoldBugfix(args.projectPath, name, { level: args.level });
+            return scaffoldFeature(args.projectPath, name, {
+                level: args.level,
+                reason: args.reason,
+                capability: args.capability,
+            });
+        }
         case "validate":
             return specValidate(args.projectPath, requireField(args, "change"));
         case "sync":

package/dist/modules/lawbook/engine.js

@@ -5,6 +5,7 @@ import { sealCapability } from "./anchors.js";
 import { classifyEars, diagnoseEars, extractNormativeBody, loadEarsConfig, splitRequirementBlocks, } from "./ears.js";
 import { artifactNeeds, confirmedLevel, countUncheckedTasks, gatherSignals, hasDisciplineReport, loadCeremonyConfig, proposeLevel, readChangeType, readCeremonyRecord, } from "./levels.js";
 import { inferBugResolution, preventionRequiresDelta, validateBugfixContent } from "./bugfix.js";
+import { isPlaceholderDelta } from "./scaffold-change.js";
 import { harnessArchiveBlockers } from "../cortex/harness.js";
 // speclaw's own spec-driven workflow engine. Inspired by OpenSpec's model
 // (proposals, delta specs, changes, archive) but implemented from scratch and
@@ -251,6 +252,9 @@ export function specValidate(projectPath, change, remeasure) {
     for (const file of deltas) {
         const rel = path.relative(changeDir, file);
         const content = fs.readFileSync(file, "utf8");
+        if (isPlaceholderDelta(content)) {
+            warnings.push(`${rel}: placeholder delta from \`lawbook draft\` — replace it (and remove the marker) or delete it; sync refuses placeholders`);
+        }
         if (!/\b(SHALL|MUST)\b/.test(content)) {
             issues.push(`${rel}: no normative requirement (use SHALL/MUST)`);
         }
@@ -328,6 +332,13 @@ export function specSync(projectPath, change) {
     const updated = [];
     if (!fs.existsSync(changeSpecs))
         return { change, promoted, created, updated };
+    // Refuse before copying anything, so a placeholder never becomes canonical.
+    const placeholders = deltaSpecFiles(changeDir)
+        .filter((f) => isPlaceholderDelta(fs.readFileSync(f, "utf8")))
+        .map((f) => path.relative(changeDir, f));
+    if (placeholders.length > 0) {
+        throw new Error(`refusing to sync placeholder delta(s): ${placeholders.join(", ")} — fill them in and remove the marker, or delete them`);
+    }
     const walk = (dir) => {
         for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
             const full = path.join(dir, e.name);

package/dist/modules/lawbook/levels.js

@@ -385,6 +385,8 @@ export function setCeremonyLevel(projectPath, change, opts) {
         confirmedAt: new Date().toISOString(),
         overrideReason: opts.reason,
         promotions: prev?.promotions ?? [],
+        // A drafted change keeps its type when its level is confirmed later.
+        ...(prev?.changeType ? { changeType: prev.changeType } : {}),
     };
     writeCeremonyRecord(projectPath, change, record);
     return record;

package/dist/modules/lawbook/quick.js

@@ -1,6 +1,5 @@
-import fs from "node:fs";
-import path from "node:path";
 import { gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, setCeremonyLevel, } from "./levels.js";
+import { scaffoldChange } from "./scaffold-change.js";
 /**
  * Scaffold a level-0 change: `record.md`, `change.json`, and `reports/`.
  *
@@ -9,25 +8,23 @@ import { gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel,
  * @param targets - Optional paths/symbols used to propose the level (default empty → score 0).
  */
 export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols: [] }) {
-    const changeDir = path.join(projectPath, "lawbook", "changes", name);
-    if (fs.existsSync(changeDir)) {
-        throw new Error(`change "${name}" already exists under lawbook/changes/`);
-    }
-    const { thresholds } = loadCeremonyConfig(projectPath);
-    const signals = gatherSignals(projectPath, targets, thresholds);
-    const proposal = proposeLevel(signals, thresholds);
     // quick always records level 0; if measurement says higher, still allow but note it.
-    const level = 0;
-    fs.mkdirSync(path.join(changeDir, "reports"), { recursive: true });
-    const rationale = proposal.level === null
+    const quickRationale = (proposal) => proposal.level === null
         ? proposal.rationale
         : proposal.level > 0
             ? `${proposal.rationale} — quick forced level 0; promote if scope grows`
             : proposal.rationale;
-    const recordMd = `# ${name}
+    const r = scaffoldChange(projectPath, name, {
+        targets,
+        level: 0,
+        recordProposal: (proposal) => ({ ...proposal, rationale: quickRationale(proposal) }),
+        reason: (proposal) => proposal.level !== null && proposal.level > 0 ? "speclaw quick" : undefined,
+        reportsReadme: `# Reports — ${name}\n\nAdd at least one discipline report before archive.\n`,
+        artifacts: ({ proposal }) => ({
+            "record.md": `# ${name}
 
 **Level:** 0 (proposed: ${proposal.level ?? "n/a"}, confirmed by: human)
-**Why:** ${rationale}
+**Why:** ${quickRationale(proposal)}
 
 ## What changes
 
@@ -42,16 +39,10 @@ export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols:
 ## Evidence
 
 - \`reports/\` — add a discipline report before archive
-`;
-    fs.writeFileSync(path.join(changeDir, "record.md"), recordMd);
-    fs.writeFileSync(path.join(changeDir, "reports", "README.md"), `# Reports — ${name}\n\nAdd at least one discipline report before archive.\n`);
-    const record = setCeremonyLevel(projectPath, name, {
-        proposal: { ...proposal, rationale },
-        level,
-        confirmedBy: "human",
-        reason: proposal.level !== null && proposal.level > 0 ? "speclaw quick" : undefined,
+`,
+        }),
     });
-    return { change: name, proposal, record, dir: changeDir };
+    return { change: r.change, proposal: r.proposal, record: r.record, dir: r.dir };
 }
 /**
  * Handle `lawbook_level` modes: propose / set / promote / explain.

package/dist/modules/lawbook/register.js

@@ -33,7 +33,7 @@ export function registerSpec(server, opts = {}) {
             return;
         defineTool(server, { name, description, inputSchema, handler });
     };
-    add("lawbook_change", "Lawbook lifecycle: init, list, validate, sync, archive, level, coverage, drift.", lawbookChangeSchema, async (args) => text(handleLawbookChange(args)));
+    add("lawbook_change", "Lawbook lifecycle: init, list, draft, validate, sync, archive, level, coverage, drift.", lawbookChangeSchema, async (args) => text(handleLawbookChange(args)));
     add("lawbook_investigate", "Rank bug origins from the graph. Pass stackTrace or symptom — evidence, not verdict.", {
         projectPath: z.string(),
         stackTrace: z.string().optional(),