@esneiderbravo/speclaw 2.0.3 → 2.0.5

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(),

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

@@ -0,0 +1,238 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gatherSignals, loadCeremonyConfig, proposeLevel, setCeremonyLevel, writeCeremonyRecord, } from "./levels.js";
+// Covers: req~feature-draft~1
+/** Change folder names are kebab-case: lowercase alphanumerics joined by single hyphens. */
+export const CHANGE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Generic change scaffold shared by `quick`, bug drafts, and feature drafts.
+ *
+ * Refuses an existing change directory, proposes a
+ * ceremony level from `targets`, writes the artifacts the caller asks for plus
+ * `reports/README.md`, then records `change.json`. Every refusal happens
+ * before the first write, so a rejected scaffold leaves the tree untouched.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change folder name (kebab-case).
+ * @param opts - Level, change type, and artifact templates.
+ * @throws When the change exists or the level is below the proposal without a
+ *   reason. Name rules belong to the callers (feature drafts enforce kebab-case).
+ */
+export function scaffoldChange(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 = typeof opts.level === "function" ? opts.level(proposal) : opts.level;
+    const stored = opts.recordProposal ? opts.recordProposal(proposal) : proposal;
+    const reason = typeof opts.reason === "function" ? opts.reason(proposal) : opts.reason;
+    // setCeremonyLevel enforces this too, but only after files exist; check first.
+    if (level !== undefined && proposal.level !== null && level < proposal.level && !reason) {
+        throw new Error(`level ${level} is below the proposed level (${proposal.level}); pass a reason to confirm it`);
+    }
+    const files = opts.artifacts({ name, proposal, level });
+    fs.mkdirSync(path.join(changeDir, "reports"), { recursive: true });
+    for (const [rel, content] of Object.entries(files)) {
+        const abs = path.join(changeDir, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+    }
+    fs.writeFileSync(path.join(changeDir, "reports", "README.md"), opts.reportsReadme);
+    let record;
+    if (level === undefined) {
+        record = opts.changeType ? { ...stored, changeType: opts.changeType } : { ...stored };
+        fs.writeFileSync(path.join(changeDir, "change.json"), JSON.stringify(record, null, 2) + "\n");
+    }
+    else {
+        let confirmed = setCeremonyLevel(projectPath, name, {
+            proposal: stored,
+            level,
+            confirmedBy: "human",
+            reason,
+        });
+        if (opts.changeType) {
+            confirmed = { ...confirmed, changeType: opts.changeType };
+            writeCeremonyRecord(projectPath, name, confirmed);
+        }
+        record = confirmed;
+    }
+    return {
+        change: name,
+        proposal,
+        record,
+        dir: changeDir,
+        level: level ?? null,
+        changeType: opts.changeType ?? "feature",
+        files: [...Object.keys(files), "reports/README.md", "change.json"],
+    };
+}
+const featureRecordMd = (name, level, proposal) => `# ${name}
+
+**Level:** ${level} (proposed: ${proposal.level ?? "n/a"}, confirmed by: human)
+**Why:** ${proposal.rationale}
+
+## What changes
+
+<!-- 2–5 lines: what and why. -->
+
+## Steps
+
+- [ ] Make the change
+- [ ] Add or update tests
+- [ ] Record evidence under reports/
+
+## Evidence
+
+- \`reports/\` — add a discipline report before archive
+`;
+const featureTasksMd = (name) => `# Tasks — ${name}
+
+## 0. Branch
+
+- [ ] 0.1 Create or check out the feature branch
+
+## 1. Implementation
+
+- [ ] 1.1 Implement the change
+
+## 2. Verification
+
+- [ ] 2.1 Review and update the affected tests
+- [ ] 2.2 Run the quality gates and verify they pass
+- [ ] 2.3 Write the discipline reports under reports/
+- [ ] 2.4 Archive the change within the same PR
+`;
+const featureProposalMd = (name) => `# ${name}
+
+## Why
+
+<!-- The problem and who it affects. -->
+
+## What changes
+
+<!-- The behavior after this change. -->
+
+## Impact
+
+<!-- Capabilities, modules, and APIs touched. -->
+`;
+const featureDesignMd = (name) => `# Design — ${name}
+
+## Approach
+
+<!-- Module boundaries, data flow, and decisions. -->
+`;
+/**
+ * Marks an unedited delta stub. Validate warns while it is present and sync
+ * refuses to promote it, so a placeholder capability is never synced silently.
+ */
+export const PLACEHOLDER_DELTA_MARKER = "<!-- speclaw:placeholder-delta -->";
+const PLACEHOLDER_LINE_RE = /^<!-- speclaw:placeholder-delta -->[ \t]*$/m;
+/**
+ * True when a delta still carries the placeholder marker on a line of its own.
+ * Prose that quotes the marker inline (e.g. in backticks) does not count, so a
+ * spec documenting the marker is never mistaken for a placeholder.
+ *
+ * @param content - Delta spec text.
+ */
+export function isPlaceholderDelta(content) {
+    return PLACEHOLDER_LINE_RE.test(content);
+}
+/** Starting delta for a capability with no canonical spec yet (a placeholder). */
+const featureDeltaMd = (capability, change) => `# ${capability}
+
+${PLACEHOLDER_DELTA_MARKER}
+<!-- Placeholder delta for change ${change}. Replace it with the capability's
+     full intended spec (sync overwrites the canonical spec with this file) and
+     delete the marker above, or delete this file if the change targets another
+     capability (pass --capability <name> when drafting). -->
+
+### Requirement: ${capability} behavior
+
+The system SHALL provide the behavior described in \`proposal.md\` for ${change}.
+
+#### Scenario: The change's behavior is observable
+- Given the change ${change} is implemented
+- When the behavior is exercised
+- Then the outcome described in \`proposal.md\` is observed
+`;
+/**
+ * Stub artifacts for a feature change at `level` (none when unconfirmed).
+ *
+ * Every level gets what `artifactNeeds` requires, so a fresh draft validates:
+ * level 2 includes a `design.md` stub (rather than a record justification),
+ * and levels 1–3 include a delta under `specs/<capability>/spec.md`.
+ *
+ * @param name - Change name.
+ * @param level - Confirmed level, or `undefined` for no stubs.
+ * @param proposal - Proposal quoted in `record.md`.
+ * @param delta - Capability and starting content for the delta (levels 1–3).
+ */
+export function featureStubs(name, level, proposal, delta = {
+    capability: name,
+    content: featureDeltaMd(name, name),
+}) {
+    const spec = { [`specs/${delta.capability}/spec.md`]: delta.content };
+    switch (level) {
+        case 0:
+            return { "record.md": featureRecordMd(name, 0, proposal) };
+        case 1:
+            return {
+                "record.md": featureRecordMd(name, 1, proposal),
+                "tasks.md": featureTasksMd(name),
+                ...spec,
+            };
+        case 2:
+        case 3:
+            return {
+                "proposal.md": featureProposalMd(name),
+                "design.md": featureDesignMd(name),
+                "tasks.md": featureTasksMd(name),
+                ...spec,
+            };
+        default:
+            return {};
+    }
+}
+/**
+ * Scaffold a feature change (`speclaw lawbook draft <name>` / `lawbook_change` `draft`).
+ *
+ * With `level`, the level is confirmed and its stubs are written; without it,
+ * `change.json` carries only the proposal and `changeType`, so validate applies
+ * level-3 rules until `lawbook level set` confirms one. The delta stub targets
+ * `capability` (default: the change name); when that capability already has a
+ * canonical spec, the delta starts from a copy of it, so an unedited sync
+ * changes nothing.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change folder name (kebab-case).
+ * @param opts - Optional level, override reason, delta capability, and targets.
+ * @throws When `capability` is not kebab-case (plus every `scaffoldChange` refusal).
+ */
+export function scaffoldFeature(projectPath, name, opts = {}) {
+    // Only feature drafts enforce kebab-case: quick and bug drafts keep their
+    // pre-existing (unvalidated) naming so their outputs stay unchanged.
+    if (!CHANGE_NAME_RE.test(name)) {
+        throw new Error(`change name "${name}" must be kebab-case (e.g. add-widget)`);
+    }
+    const capability = opts.capability ?? name;
+    if (!CHANGE_NAME_RE.test(capability)) {
+        throw new Error(`capability "${capability}" must be kebab-case (e.g. widgets)`);
+    }
+    const canonical = path.join(projectPath, "lawbook", "specs", capability, "spec.md");
+    const content = fs.existsSync(canonical)
+        ? fs.readFileSync(canonical, "utf8")
+        : featureDeltaMd(capability, name);
+    return scaffoldChange(projectPath, name, {
+        changeType: "feature",
+        targets: opts.targets,
+        level: opts.level,
+        reason: opts.reason,
+        reportsReadme: `# Reports — ${name}\n\nAdd at least one discipline report before archive.\n`,
+        artifacts: ({ level, proposal }) => featureStubs(name, level, proposal, { capability, content }),
+    });
+}