@esneiderbravo/speclaw 0.3.11 → 0.3.12

package/dist/cli/commands/lawbook.js

@@ -1,11 +1,13 @@
 import { specInit, specValidate, specSync, specArchive, specList, } from "../../modules/lawbook/engine.js";
+import { handleLevel } from "../../modules/lawbook/quick.js";
+import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
     // The MCP path passes the date in; the CLL runs on a real machine, so read it here.
     return new Date().toISOString().slice(0, 10);
 }
 /**
- * Run a spec-workflow subcommand: init, list, validate, sync, or archive.
+ * Run a spec-workflow subcommand: init, list, validate, sync, archive, or level.
  *
  * @param flags - Parsed flags; `_[0]` is the subcommand and `_[1]` the change name where required.
  * @throws Exits the process with code 1 on unknown subcommands, missing arguments, or engine errors.
@@ -27,13 +29,48 @@ export async function runSpec(flags) {
                 if (!r.initialized)
                     return ui.warn("No lawbook/ — run `speclaw lawbook init`.");
                 ui.heading("Lawbook workspace");
-                ui.info(`active changes: ${r.activeChanges.join(", ") || "none"}`);
+                if (r.activeChanges.length === 0)
+                    ui.info("active changes: none");
+                else {
+                    ui.info("active changes:");
+                    for (const name of r.activeChanges) {
+                        const lvl = r.activeLevels[name] ?? 3;
+                        ui.info(`  ${name}  (level ${lvl})`);
+                    }
+                }
                 ui.info(`archived: ${r.archivedChanges.join(", ") || "none"}`);
                 ui.info(`capabilities: ${r.capabilities.join(", ") || "none"}`);
                 return;
             }
+            case "level": {
+                const modeRaw = change ?? "propose";
+                const mode = modeRaw;
+                if (!["propose", "set", "promote", "explain"].includes(mode)) {
+                    ui.err("Usage: speclaw lawbook level <propose|set|promote|explain> [--change <c>] [--path …] [--level N] [--reason …] [--json]");
+                    process.exit(1);
+                }
+                const levelFlag = flags.level;
+                const level = levelFlag === undefined || levelFlag === true
+                    ? undefined
+                    : Number(levelFlag);
+                const result = handleLevel({
+                    projectPath: cwd,
+                    mode,
+                    change: typeof flags.change === "string" ? flags.change : flags._[2],
+                    paths: list(flags.path),
+                    symbols: list(flags.symbol),
+                    level,
+                    reason: typeof flags.reason === "string" ? flags.reason : undefined,
+                });
+                if (flags.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
             case "validate": {
-                const r = specValidate(cwd, req(change, "spec validate <change>"));
+                const r = specValidate(cwd, req(change, "lawbook validate <change>"));
                 if (r.valid)
                     ui.ok(`${r.change} is valid (${r.deltaSpecs.length} delta spec(s))`);
                 else {
@@ -47,13 +84,13 @@ export async function runSpec(flags) {
                 return;
             }
             case "sync": {
-                const r = specSync(cwd, req(change, "spec sync <change>"));
+                const r = specSync(cwd, req(change, "lawbook sync <change>"));
                 ui.ok(`promoted ${r.promoted.length} spec(s)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 return;
             }
             case "archive": {
-                const r = specArchive(cwd, req(change, "spec archive <change>"), today());
+                const r = specArchive(cwd, req(change, "lawbook archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 for (const s of r.seals) {
@@ -66,7 +103,7 @@ export async function runSpec(flags) {
                 return;
             }
             default:
-                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive> [change]");
+                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level> [change]");
                 process.exit(1);
         }
     }

package/dist/cli/commands/quick.js

@@ -0,0 +1,35 @@
+import { list } from "../lib/args.js";
+import { ui } from "../lib/ui.js";
+import { scaffoldQuick } from "../../modules/lawbook/quick.js";
+/**
+ * Scaffold a level-0 change (`speclaw quick <name>`).
+ *
+ * @param flags - `_[0]` is the change name; optional `--path` / `--symbol` / `--json`.
+ */
+export async function runQuick(flags) {
+    const cwd = process.cwd();
+    const name = flags._[0];
+    if (!name || typeof name !== "string") {
+        ui.err("Usage: speclaw quick <name> [--path <file>] [--symbol <sym>] [--json]");
+        process.exit(1);
+    }
+    try {
+        const result = scaffoldQuick(cwd, name, {
+            paths: list(flags.path),
+            symbols: list(flags.symbol),
+        });
+        if (flags.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        ui.ok(`level-0 change ${ui.code(result.change)} at ${result.dir}`);
+        ui.info(result.proposal.rationale);
+        if (result.proposal.level !== null && result.proposal.level > 0) {
+            ui.warn(`measured proposal was level ${result.proposal.level} — promote if the fix grows`);
+        }
+    }
+    catch (err) {
+        ui.err(err.message);
+        process.exit(1);
+    }
+}

package/dist/cli/commands/update.js

@@ -125,6 +125,16 @@ const MIGRATIONS = [
             "(`node_metrics`) — reindex with `speclaw index`. Default history window is 90 days.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.12",
+        describe: "Adaptive ceremony levels 0–3, speclaw quick, lawbook_level",
+        agentPrompt: "- Mention ceremony levels 0–3 (`change.json`), `speclaw quick` for level-0 scaffolds, and " +
+            "`lawbook_level` / `speclaw lawbook level` for propose/set/promote. Artifact volume follows " +
+            "the confirmed level; missing `change.json` still means full ceremony (level 3). Optional " +
+            "`ceremony:` block in `lawbook/config.yaml` (cuts default [3, 8, 15]). Update LAWS / " +
+            "docs/standards/lawbook.md wording if the project still says every change needs all four artifacts.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/index.js

@@ -31,8 +31,10 @@ Compass (code intelligence — the same surface agents use via MCP)
   visualize [node]         Interactive HTML graph → .speclaw/graph.html
 
 Lawbook (spec-driven workflow)
+  quick <name>             Scaffold a level-0 change (record.md + reports)
   lawbook init             Create the lawbook/ workspace
   lawbook list             Active/archived changes and capabilities
+  lawbook level <mode>     Propose/set/promote/explain ceremony level (--json)
   lawbook validate <c>     Validate a change's artifacts
   lawbook sync <c>         Promote delta specs to canonical
   lawbook archive <c>      Finalize and archive a change
@@ -54,7 +56,8 @@ Other
 // interactive, human-facing commands whose stdout is prose. Deliberately
 // excluded: `version`/`--version`/`-v` (bare scriptable value), the Compass
 // query family (`explore`/`search`/`recall`/`impact`/`trace`/`affected-tests`/
-// `hotspots`/`coupling`, machine-consumed output), `mcp` (a long-running stdio
+// `hotspots`/`coupling`, machine-consumed output), `quick` (often --json),
+// `mcp` (a long-running stdio
 // server), and `init` (already opens with the fuller `banner()`).
 const HEADER_COMMANDS = new Set([
     undefined,
@@ -71,6 +74,7 @@ const HEADER_COMMANDS = new Set([
     "index",
     "watch",
     "lawbook",
+    "quick",
 ]);
 /**
  * Print the branded header once, ahead of a command's output, when it is a
@@ -94,6 +98,10 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "drift" && flags.json)
         return;
+    if (cmd === "quick" && flags.json)
+        return;
+    if (cmd === "lawbook" && flags.json && flags._[0] === "level")
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -135,6 +143,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/query.js")).runQuery(cmd, flags);
         case "visualize":
             return (await import("./commands/visualize.js")).runVisualize(flags);
+        case "quick":
+            return (await import("./commands/quick.js")).runQuick(flags);
         case "lawbook":
             return (await import("./commands/lawbook.js")).runSpec(flags);
         case "doctor":

package/dist/modules/foundation/doctor.js

@@ -8,6 +8,7 @@ import { pkgName, pkgVersion } from "../../shared/version.js";
 import { indexExists, openDb } from "../compass/db.js";
 import { specList } from "../lawbook/engine.js";
 import { doctorDriftCheck } from "../lawbook/drift.js";
+import { loadCeremonyConfig } from "../lawbook/levels.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
 import { redactValue } from "../../shared/redact.js";
 const STATUS_RANK = {
@@ -467,6 +468,67 @@ function specsOrphansCheck(projectPath) {
         remedy: `speclaw lawbook archive ${active[0]}`,
     };
 }
+/** Ceremony config validity + archived level histogram. */
+function ceremonyChecks(projectPath) {
+    const out = [];
+    const { invalidCuts } = loadCeremonyConfig(projectPath);
+    if (invalidCuts) {
+        out.push({
+            id: "cfg.ceremony.cuts",
+            title: "ceremony thresholds",
+            status: "warn",
+            detail: "invalid ceremony.cuts — using built-in defaults [3, 8, 15]",
+            remedy: "fix cuts in lawbook/config.yaml so they are strictly increasing, or remove the block",
+        });
+    }
+    else {
+        out.push({
+            id: "cfg.ceremony.cuts",
+            title: "ceremony thresholds",
+            status: "ok",
+            detail: "ceremony cuts valid (or using defaults)",
+        });
+    }
+    const archiveRoot = path.join(projectPath, "lawbook", "changes", "archive");
+    const counts = { "0": 0, "1": 0, "2": 0, "3": 0, missing: 0 };
+    if (fs.existsSync(archiveRoot)) {
+        for (const name of fs.readdirSync(archiveRoot)) {
+            const dir = path.join(archiveRoot, name);
+            if (!fs.statSync(dir).isDirectory())
+                continue;
+            // archived folder is YYYY-MM-DD-name; change.json lives inside
+            const rec = (() => {
+                try {
+                    const p = path.join(dir, "change.json");
+                    if (!fs.existsSync(p))
+                        return null;
+                    return JSON.parse(fs.readFileSync(p, "utf8"));
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (!rec || rec.confirmedLevel === undefined) {
+                counts.missing += 1;
+                counts["3"] += 1;
+            }
+            else {
+                counts[String(rec.confirmedLevel)] = (counts[String(rec.confirmedLevel)] ?? 0) + 1;
+            }
+        }
+    }
+    const total = (counts["0"] ?? 0) + (counts["1"] ?? 0) + (counts["2"] ?? 0) + (counts["3"] ?? 0);
+    out.push({
+        id: "cfg.ceremony.levels",
+        title: "ceremony level distribution",
+        status: "ok",
+        value: JSON.stringify(counts),
+        detail: total === 0
+            ? "no archived changes"
+            : `archived levels: 0=${counts["0"]}, 1=${counts["1"]}, 2=${counts["2"]}, 3=${counts["3"]} (missing change.json=${counts.missing})`,
+    });
+    return out;
+}
 function configurationChecks(projectPath, initialised) {
     if (!initialised) {
         const ids = [
@@ -559,6 +621,7 @@ export async function doctor(projectPath, opts = {}) {
         configuration.push(await budgetCheck(projectPath));
         configuration.push(freshnessCheck(projectPath));
         configuration.push(specsOrphansCheck(projectPath));
+        configuration.push(...ceremonyChecks(projectPath));
         {
             const d = doctorDriftCheck(projectPath);
             addCheck(configuration, {

package/dist/modules/lawbook/assets/commands/archive.md

@@ -1,11 +1,10 @@
 ---
-description: Finalize a completed change — sync specs into canonical, then archive it.
+description: Finalize a completed change — sync specs when needed, then archive it.
 ---
 
 Archive the completed change: $ARGUMENTS
 
-Follow the `archive` skill: confirm every task is done and gates are green, run
-the reconciliation review (recommend a sync with short insights if the code
-drifted past the contracts), run `lawbook_validate`, then `lawbook_archive` with
-today's date (YYYY-MM-DD). It syncs the specs and moves the change to
-`lawbook/changes/archive/`. Never move the folder by hand.
+Follow the `archive` skill: confirm every task (or level-0 checklist) is done
+and gates are green, reconcile if the level has delta specs, run
+`lawbook_validate`, then `lawbook_archive` with today's date (YYYY-MM-DD). Sync
+runs only when the ceremony level requires specs. Never move the folder by hand.

package/dist/modules/lawbook/assets/commands/draft.md

@@ -1,12 +1,11 @@
 ---
-description: Draft a new spec-driven change (proposal, delta specs, tasks) before coding.
+description: Draft a new spec-driven change at the confirmed ceremony level before coding.
 ---
 
 Draft a new change under `lawbook/changes/<name>/` for: $ARGUMENTS
 
-Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_init`), investigate the
-code with `compass_explore`/`compass_recall`, read the governing
-`docs/standards/`, then write `proposal.md`, `specs/<capability>/spec.md`
-(normative `SHALL`/`MUST` + `#### Scenario:`), `design.md`, and
-`tasks.md` (with the mandatory steps from `lawbook/config.yaml`). Finish by
-running `lawbook_validate` and fixing every issue.
+Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_init`), investigate
+with Compass, propose a ceremony level (`lawbook_level` mode `propose`) and
+**confirm** it with the human (`set`), then scaffold only the artifacts that
+level requires. For true one-liners use `speclaw quick` / the `quick` skill
+instead. Finish by running `lawbook_validate` and fixing every issue.

package/dist/modules/lawbook/assets/commands/quick.md

@@ -0,0 +1,14 @@
+---
+description: Scaffold a level-0 lawbook change (record.md + reports) for a tiny fix.
+---
+
+Scaffold a **ceremony level 0** change named `$ARGUMENTS` with `speclaw quick`
+(or the equivalent `scaffoldQuick` path). Do **not** invent `proposal.md` /
+`design.md` / delta specs for a true one-liner.
+
+1. Ensure `lawbook/` exists (`lawbook_init` if needed).
+2. Prefer passing `--path` / `--symbol` so the proposal rationale is measured.
+3. Confirm with the human if the measured proposal is higher than 0 — promote
+   (`lawbook_level` mode `promote`) instead of staying at quick.
+4. Implement, check the checklist in `record.md`, write a discipline report
+   under `reports/`, then archive (no sync required at level 0).

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

@@ -1,7 +1,8 @@
 # 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.
+Run `lawbook_validate`. If the confirmed ceremony level requires delta specs
+(levels 1–3), run `lawbook_sync` to promote them into `lawbook/specs/` —
+`lawbook_archive` refuses unless the canonical specs already match. At **level
+0**, skip sync (there are no deltas).
 
 Next: read `steps/04-archive.md` and do only what it says.

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

@@ -1,6 +1,6 @@
 ---
 name: draft
-description: Draft a new spec-driven change — proposal, delta specs, and tasks — before writing any code. Use when the user wants to start, plan, or propose a new feature, fix, or refactor: "draft a change for X", "propose X", "let's plan X", "spec out X", "new change". Part of speclaw's lawbook module (draft → build → sync → archive).
+description: Draft a new spec-driven change — propose a ceremony level, then write only the artifacts that level needs — before writing any code. Use when the user wants to start, plan, or propose a new feature, fix, or refactor: "draft a change for X", "propose X", "let's plan X", "spec out X", "new change". Part of speclaw's lawbook module (draft → build → sync → archive).
 ---
 
 # draft — Draft a new change

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

@@ -6,6 +6,9 @@
 - 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.
+- **Propose a ceremony level** with `lawbook_level` (mode `propose`) using the
+  paths/symbols you found; **confirm with the human** (mode `set`) before
+  writing artifacts. For an obvious one-liner, offer `speclaw quick` instead.
 - Read the governing standards in `docs/standards/` (architecture, backend,
   frontend, testing) so the change complies with the project's law.
 

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

@@ -1,15 +1,25 @@
 # 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
+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.
+
+Create under `lawbook/changes/<name>/` only what the level needs:
+
+- **Level 0** — prefer `speclaw quick` / the `quick` skill: `record.md`
+  (inline checklist) + `reports/` + `change.json`. No proposal/design/deltas.
+- **Level 1** — `record.md`, `tasks.md`, ≥1 delta under
+  `specs/<capability>/spec.md`, `reports/`, `change.json`.
+- **Level 2** — `proposal.md`, `tasks.md`, delta specs, `reports/`;
+  `design.md` optional only with justification in `record.md`.
+- **Level 3** — `proposal.md`, `design.md`, `tasks.md`, delta specs, `reports/`.
+
+For every level that needs delta specs:
+
+- **specs/<capability>/spec.md** — the delta for each affected capability.
+  `sync` promotes by overwriting the whole canonical file, so the delta must
+  carry the capability's **full** intended spec. When updating an existing
+  capability, **start from** `lawbook/specs/<capability>/spec.md`. Use normative
   language and testable scenarios:
   ```markdown
   # <Capability>
@@ -22,20 +32,13 @@ Create under `lawbook/changes/<name>/`:
   - 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's discipline-reports
-  step). Every change ships this folder; archive is blocked until it holds at
-  least one discipline report.
+
+- **tasks.md** (levels 1–3) — ordered, checkable steps. MUST include the
+  mandatory steps from `lawbook/config.yaml` (feature branch first; tests;
+  manual verification by the agent; discipline reports; docs; archive in PR).
+- **reports/** — always scaffold with `reports/README.md` naming expected
+  disciplines (`backend.md`, `frontend.md`, `api.md`, … — `api.md` when an API
+  surface is touched). Archive is blocked until at least one discipline report
+  exists.
 
 Next: read `steps/05-validate.md` and do only what it says.

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

@@ -0,0 +1,11 @@
+---
+name: quick
+description: Scaffold a level-0 lawbook change (record.md + reports) for a tiny fix. Use when the user wants a one-line fix, typo, or docs-only tweak without full ceremony — "quick change", "speclaw quick", "level 0", "skip proposal".
+---
+
+# quick — Level-0 change
+
+Create `lawbook/changes/<name>/` with `record.md`, `change.json` (confirmed
+level 0), and `reports/`. No proposal, design, or delta specs.
+
+Read `steps/01-scaffold.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/quick/steps/01-scaffold.md

@@ -0,0 +1,6 @@
+# Scaffold the level-0 change
+
+Run `speclaw quick <name>` (or the library scaffold) so `record.md`,
+`change.json`, and `reports/` exist. Pass `--path` / `--symbol` when known.
+
+Next: read `steps/02-implement.md` and do only what it says.

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

@@ -0,0 +1,7 @@
+# Implement and evidence
+
+Make the fix, tick every `- [ ]` in `record.md`, and write at least one
+discipline report under `reports/`. Archive with `lawbook_archive` (no sync at
+level 0). Promote via `lawbook_level` if scope grew.
+
+No further steps — workflow complete.

package/dist/modules/lawbook/engine.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { coverageArchiveBlockers } from "./coverage.js";
 import { sealCapability } from "./anchors.js";
+import { artifactNeeds, confirmedLevel, countUncheckedTasks, gatherSignals, hasDisciplineReport, loadCeremonyConfig, proposeLevel, } from "./levels.js";
 // speclaw's own spec-driven workflow engine. Inspired by OpenSpec's model
 // (proposals, delta specs, changes, archive) but implemented from scratch and
 // deliberately simpler: a change's specs/ holds the full intended spec for each
@@ -33,25 +34,33 @@ mandatory_task_steps:
   - "Archive the change within the same PR (lawbook:archive)."
 
 # A change is required for new behavior, endpoints, schema changes, or UI flows;
-# one-line fixes need not have one.
+# one-line fixes may use ceremony level 0 (\`speclaw quick\`) instead of full artifacts.
+
+# Ceremony levels (adaptive). Defaults match speclaw's built-in thresholds.
+ceremony:
+  cuts: [3, 8, 15]
+  hotspotFloor: 0.7
 `;
 const README_MD = `# lawbook/ — the spec-driven workflow (speclaw)
 
 This directory is managed by speclaw's **lawbook** module.
 
 - \`specs/\` — the canonical specifications (the current source of truth).
-- \`changes/<name>/\` — an in-flight change: \`proposal.md\`, \`tasks.md\`,
-  \`design.md\`, and \`specs/<capability>/spec.md\` delta specs.
+- \`changes/<name>/\` — an in-flight change. Artifact volume follows the
+  confirmed ceremony level in \`change.json\` (0=quick … 3=full). Missing
+  \`change.json\` means level 3 (proposal, design, tasks, delta specs).
 - \`changes/archive/\` — completed, archived changes.
-- \`config.yaml\` — mandatory task steps and workflow rules.
+- \`config.yaml\` — mandatory task steps, coverage, and optional ceremony cuts.
 
 ## Workflow
 
-1. \`lawbook:draft\` — describe the change; generates proposal, delta specs, tasks.
-2. \`lawbook:build\` — implement the tasks.
-3. \`lawbook:sync\` — promote the change's delta specs into \`specs/\`.
-4. \`lawbook:archive\` — sync + move the change to \`changes/archive/\`.
-5. \`lawbook:explore\` — think through an idea before or during a change.
+1. \`lawbook:explore\` — think through an idea before or during a change.
+2. \`lawbook:draft\` / \`speclaw quick\` — propose/confirm a ceremony level, then
+   scaffold only the artifacts that level requires.
+3. \`lawbook:build\` — implement the tasks.
+4. \`lawbook:sync\` — promote the change's delta specs into \`specs/\` (when the
+   level requires specs).
+5. \`lawbook:archive\` — sync (if needed) + move the change to \`changes/archive/\`.
 `;
 /**
  * Initialize the spec/ workspace, creating the specs/, changes/, and archive
@@ -146,18 +155,17 @@ function deltaSpecFiles(changeDir) {
     return out;
 }
 /**
- * Validate a change's artifacts: proposal.md and tasks.md must be present, and
- * each delta spec must use normative language (SHALL/MUST), a "### Requirement:"
- * header, and a "#### Scenario:" acceptance criterion.
+ * Validate a change's artifacts against its confirmed ceremony level
+ * (missing `change.json` ⇒ level 3 / full ceremony).
  *
  * @param projectPath - Absolute path to the project root.
  * @param change - Change name (folder under lawbook/changes/).
- * @returns The validation verdict and the list of issues to fix; never throws
- *   for a missing change — it is reported as an issue with `valid: false`.
+ * @param remeasure - Optional targets to re-score scope growth (paths/symbols).
  */
-export function specValidate(projectPath, change) {
+export function specValidate(projectPath, change, remeasure) {
     const changeDir = path.join(specRoot(projectPath), "changes", change);
     const issues = [];
+    const warnings = [];
     if (!fs.existsSync(changeDir)) {
         return {
             change,
@@ -167,18 +175,43 @@ export function specValidate(projectPath, change) {
             deltaSpecs: [],
         };
     }
-    if (!fs.existsSync(path.join(changeDir, "proposal.md")))
-        issues.push("missing proposal.md");
-    const tasksPath = path.join(changeDir, "tasks.md");
-    if (!fs.existsSync(tasksPath))
-        issues.push("missing tasks.md");
+    const level = confirmedLevel(projectPath, change);
+    const needs = artifactNeeds(level);
+    if (needs.record && !fs.existsSync(path.join(changeDir, "record.md"))) {
+        issues.push(`missing record.md (required at ceremony level ${level})`);
+    }
+    if (needs.proposal && !fs.existsSync(path.join(changeDir, "proposal.md"))) {
+        issues.push(`missing proposal.md (required at ceremony level ${level})`);
+    }
+    if (needs.design && !fs.existsSync(path.join(changeDir, "design.md"))) {
+        issues.push(`missing design.md (required at ceremony level ${level})`);
+    }
+    if (needs.designOptionalWithJustification && !fs.existsSync(path.join(changeDir, "design.md"))) {
+        const record = path.join(changeDir, "record.md");
+        const text = fs.existsSync(record) ? fs.readFileSync(record, "utf8") : "";
+        if (!/design\s*(omitted|skipped|n\/a)/i.test(text) && !/why.*design/i.test(text)) {
+            issues.push(`level ${level}: design.md omitted without justification in record.md`);
+        }
+    }
+    if (needs.tasksFile && !fs.existsSync(path.join(changeDir, "tasks.md"))) {
+        issues.push(`missing tasks.md (required at ceremony level ${level})`);
+    }
     const deltas = deltaSpecFiles(changeDir);
-    if (deltas.length === 0)
-        issues.push("no delta specs under specs/ (a change should specify what it changes)");
+    if (needs.deltaSpecs && deltas.length === 0) {
+        issues.push(`no delta specs under specs/ (required at ceremony level ${level})`);
+    }
+    // Scope-growth: when remeasure targets provided (or change.json has prior signals
+    // with paths we cannot recover), only check if caller passes targets.
+    if (remeasure && (remeasure.paths.length > 0 || remeasure.symbols.length > 0)) {
+        const { thresholds } = loadCeremonyConfig(projectPath);
+        const measured = proposeLevel(gatherSignals(projectPath, remeasure, thresholds), thresholds);
+        if (measured.level !== null && measured.level >= level + 2) {
+            issues.push(`scope grew: measured level ${measured.level}, recorded ${level} — run promote or justify (${measured.rationale})`);
+        }
+    }
     const root = specRoot(projectPath);
     const changeSpecs = path.join(changeDir, "specs");
     const capabilities = canonicalCapabilities(root);
-    const warnings = [];
     for (const file of deltas) {
         const rel = path.relative(changeDir, file);
         const content = fs.readFileSync(file, "utf8");
@@ -191,7 +224,6 @@ export function specValidate(projectPath, change) {
         if (!/^###\s+Requirement:/m.test(content)) {
             issues.push(`${rel}: no "### Requirement:" header`);
         }
-        // Advisory divergence checks against the canonical specs.
         const relFromSpecs = path.relative(changeSpecs, file);
         const capability = relFromSpecs.split(path.sep)[0];
         const nearMatch = nearMatchCapability(capability, capabilities);
@@ -268,10 +300,9 @@ export function specSync(projectPath, change) {
  * Deterministic completeness checks that gate archiving a change. Returns the
  * blocking reasons; an empty array means the change may be archived.
  *
- * A change is blocked when any task is still unchecked, when it has no discipline
- * report under reports/, or when its delta specs are not synced — the canonical
- * spec is missing for, or differs from, a delta (meaning sync was not run after
- * the last spec edit). The reports/README.md scaffold does not count as a report.
+ * Gates respect the confirmed ceremony level (missing `change.json` ⇒ level 3).
+ * Every level still requires checked tasks and a discipline report. Delta-spec
+ * sync is required only when the level demands delta specs.
  *
  * @param projectPath - Absolute path to the project root.
  * @param change - Change name (folder under lawbook/changes/).
@@ -283,33 +314,46 @@ export function specArchivePreconditions(projectPath, change) {
     if (!fs.existsSync(changeDir))
         return [`change "${change}" not found under lawbook/changes/`];
     const blockers = [];
-    // 1. Every task must be checked.
-    const tasksPath = path.join(changeDir, "tasks.md");
-    if (!fs.existsSync(tasksPath)) {
-        blockers.push("missing tasks.md");
+    const level = confirmedLevel(projectPath, change);
+    const needs = artifactNeeds(level);
+    // 1. Every task must be checked (tasks.md, or checklist in record.md at level 0).
+    if (needs.tasksFile) {
+        const tasksPath = path.join(changeDir, "tasks.md");
+        if (!fs.existsSync(tasksPath)) {
+            blockers.push("missing tasks.md");
+        }
+        else {
+            const unchecked = countUncheckedTasks(fs.readFileSync(tasksPath, "utf8"));
+            if (unchecked > 0)
+                blockers.push(`${unchecked} unchecked task(s) in tasks.md`);
+        }
     }
-    else {
-        const unchecked = (fs.readFileSync(tasksPath, "utf8").match(/^\s*[-*]\s+\[ \]/gm) ?? []).length;
-        if (unchecked > 0)
-            blockers.push(`${unchecked} unchecked task(s) in tasks.md`);
+    else if (needs.record) {
+        const recordPath = path.join(changeDir, "record.md");
+        if (!fs.existsSync(recordPath)) {
+            blockers.push("missing record.md");
+        }
+        else {
+            const unchecked = countUncheckedTasks(fs.readFileSync(recordPath, "utf8"));
+            if (unchecked > 0)
+                blockers.push(`${unchecked} unchecked task(s) in record.md`);
+        }
     }
     // 2. At least one discipline report must exist (README.md scaffold aside).
-    const reportsDir = path.join(changeDir, "reports");
-    const reports = fs.existsSync(reportsDir)
-        ? fs.readdirSync(reportsDir).filter((n) => n.endsWith(".md") && n.toLowerCase() !== "readme.md")
-        : [];
-    if (reports.length === 0) {
+    if (!hasDisciplineReport(changeDir)) {
         blockers.push("no discipline report under reports/ (build must record what was tested)");
     }
-    // 3. Delta specs must already be synced into the canonical specs.
-    for (const file of deltaSpecFiles(changeDir)) {
-        const rel = path.relative(path.join(changeDir, "specs"), file);
-        const canonical = path.join(root, "specs", rel);
-        if (!fs.existsSync(canonical)) {
-            blockers.push(`spec not synced: lawbook/specs/${rel} missing (run sync first)`);
-        }
-        else if (fs.readFileSync(file, "utf8") !== fs.readFileSync(canonical, "utf8")) {
-            blockers.push(`spec not synced: lawbook/specs/${rel} differs from the delta (run sync first)`);
+    // 3. Delta specs must already be synced — only when the level requires them.
+    if (needs.deltaSpecs) {
+        for (const file of deltaSpecFiles(changeDir)) {
+            const rel = path.relative(path.join(changeDir, "specs"), file);
+            const canonical = path.join(root, "specs", rel);
+            if (!fs.existsSync(canonical)) {
+                blockers.push(`spec not synced: lawbook/specs/${rel} missing (run sync first)`);
+            }
+            else if (fs.readFileSync(file, "utf8") !== fs.readFileSync(canonical, "utf8")) {
+                blockers.push(`spec not synced: lawbook/specs/${rel} differs from the delta (run sync first)`);
+            }
         }
     }
     // 4. Opt-in coverage gate: only when the change's delta specs declare ids.
@@ -317,8 +361,8 @@ export function specArchivePreconditions(projectPath, change) {
     return blockers;
 }
 /**
- * Finalize a change: promote its delta specs (via {@link specSync}), then move
- * it to changes/archive/<date>-<name>/.
+ * Finalize a change: promote its delta specs (via {@link specSync}) when the
+ * ceremony level requires them, then move it to changes/archive/<date>-<name>/.
  *
  * @param projectPath - Absolute path to the project root.
  * @param change - Change name (folder under lawbook/changes/).
@@ -336,7 +380,11 @@ export function specArchive(projectPath, change, date) {
     if (blockers.length > 0) {
         throw new Error(`cannot archive "${change}" — resolve first:\n${blockers.map((b) => `  - ${b}`).join("\n")}`);
     }
-    const { promoted, created, updated } = specSync(projectPath, change);
+    const level = confirmedLevel(projectPath, change);
+    const sync = artifactNeeds(level).deltaSpecs
+        ? specSync(projectPath, change)
+        : { change, promoted: [], created: [], updated: [] };
+    const { promoted, created, updated } = sync;
     const seals = sealPromotedCapabilities(projectPath, change, [
         ...promoted,
         ...created,
@@ -391,7 +439,13 @@ function sealPromotedCapabilities(projectPath, change, promotedPaths) {
 export function specList(projectPath) {
     const root = specRoot(projectPath);
     if (!fs.existsSync(root)) {
-        return { initialized: false, activeChanges: [], archivedChanges: [], capabilities: [] };
+        return {
+            initialized: false,
+            activeChanges: [],
+            activeLevels: {},
+            archivedChanges: [],
+            capabilities: [],
+        };
     }
     const dirsIn = (rel) => {
         const abs = path.join(root, rel);
@@ -402,9 +456,15 @@ export function specList(projectPath) {
             .filter((e) => e.isDirectory() && e.name !== "archive")
             .map((e) => e.name);
     };
+    const activeChanges = dirsIn("changes");
+    const activeLevels = {};
+    for (const name of activeChanges) {
+        activeLevels[name] = confirmedLevel(projectPath, name);
+    }
     return {
         initialized: true,
-        activeChanges: dirsIn("changes"),
+        activeChanges,
+        activeLevels,
         archivedChanges: dirsIn("changes/archive"),
         capabilities: dirsIn("specs"),
     };

package/dist/modules/lawbook/levels.js

@@ -0,0 +1,421 @@
+import fs from "node:fs";
+import path from "node:path";
+import { indexExists } from "../compass/db.js";
+import { explore } from "../compass/query.js";
+import { impact } from "../compass/query.js";
+import { affectedTests } from "../compass/affected.js";
+import { hotspots } from "../compass/hotspots.js";
+import { loadAffectedConfig, matchGlob, matchesAny, inferModule, } from "../compass/affected-config.js";
+/** Default thresholds from the adaptive-ceremony roadmap. */
+export const DEFAULT_THRESHOLDS = {
+    filesTouched: [0, 1, 3, 5],
+    modulesTouched: [0, 2, 4, 6],
+    affectedTests: [0, 1, 2, 4],
+    blastRadiusNodes: [0, 1, 3, 5],
+    publicApi: 4,
+    globalFile: 5,
+    hotspot: 3,
+    hotspotFloor: 0.7,
+    cuts: [3, 8, 15],
+    globalGlobs: [
+        "package.json",
+        "package-lock.json",
+        "tsconfig*.json",
+        ".github/workflows/**",
+        "src/modules/compass/db.ts",
+        "lawbook/config.yaml",
+    ],
+    docGlobs: ["**/*.md", "docs/**", "assets/**"],
+    moduleRoots: ["src"],
+};
+const BUCKETS = {
+    filesTouched: [1, 3, 10, Infinity],
+    modulesTouched: [1, 2, 4, Infinity],
+    affectedTests: [0, 3, 15, Infinity],
+    blastRadiusNodes: [2, 10, 50, Infinity],
+};
+export function artifactNeeds(level) {
+    switch (level) {
+        case 0:
+            return {
+                record: true,
+                proposal: false,
+                design: false,
+                tasksFile: false,
+                deltaSpecs: false,
+                reports: true,
+                designOptionalWithJustification: false,
+            };
+        case 1:
+            return {
+                record: true,
+                proposal: false,
+                design: false,
+                tasksFile: true,
+                deltaSpecs: true,
+                reports: true,
+                designOptionalWithJustification: false,
+            };
+        case 2:
+            return {
+                record: false,
+                proposal: true,
+                design: false,
+                tasksFile: true,
+                deltaSpecs: true,
+                reports: true,
+                designOptionalWithJustification: true,
+            };
+        case 3:
+            return {
+                record: false,
+                proposal: true,
+                design: true,
+                tasksFile: true,
+                deltaSpecs: true,
+                reports: true,
+                designOptionalWithJustification: false,
+            };
+    }
+}
+function bucketPoints(value, edges, points) {
+    const i = edges.findIndex((max) => value <= max);
+    return points[i < 0 ? 3 : i];
+}
+/** Pure scoring; `onlyDocs` short-circuits to 0. */
+export function scoreSignals(s, t = DEFAULT_THRESHOLDS) {
+    if (s.onlyDocs)
+        return 0;
+    let score = 0;
+    score += bucketPoints(s.filesTouched, BUCKETS.filesTouched, t.filesTouched);
+    score += bucketPoints(s.modulesTouched, BUCKETS.modulesTouched, t.modulesTouched);
+    score += bucketPoints(s.affectedTests, BUCKETS.affectedTests, t.affectedTests);
+    score += bucketPoints(s.blastRadiusNodes, BUCKETS.blastRadiusNodes, t.blastRadiusNodes);
+    if (s.touchesPublicApi)
+        score += t.publicApi;
+    if (s.touchesGlobalFile)
+        score += t.globalFile;
+    if (s.maxHotspotScore >= t.hotspotFloor)
+        score += t.hotspot;
+    return score;
+}
+export function levelFromScore(score, cuts = DEFAULT_THRESHOLDS.cuts) {
+    if (score < cuts[0])
+        return 0;
+    if (score < cuts[1])
+        return 1;
+    if (score < cuts[2])
+        return 2;
+    return 3;
+}
+export function explain(s, t, score, level) {
+    const parts = [
+        `${s.filesTouched} file(s)`,
+        `${s.modulesTouched} module(s)`,
+        `${s.affectedTests} affected test(s)`,
+        `${s.blastRadiusNodes} blast node(s)`,
+        s.touchesPublicApi ? "public API" : "no public API",
+        s.touchesGlobalFile ? "global file" : "no global file",
+        `hotspot=${s.maxHotspotScore.toFixed(2)}`,
+    ];
+    if (s.onlyDocs)
+        parts.push("docs-only");
+    if (s.degraded.length)
+        parts.push(`degraded:[${s.degraded.join(",")}]`);
+    const lvl = level === null ? "none" : String(level);
+    return `${parts.join(", ")} → score ${score} → level ${lvl} (cuts ${t.cuts.join("/")})`;
+}
+export function proposeLevel(s, t = DEFAULT_THRESHOLDS) {
+    if (s.degraded.includes("no-index") && s.filesTouched === 0 && s.blastRadiusNodes === 0) {
+        return {
+            level: null,
+            score: 0,
+            signals: s,
+            rationale: explain(s, t, 0, null),
+            degraded: s.degraded,
+        };
+    }
+    if (s.filesTouched === 0 &&
+        s.blastRadiusNodes === 0 &&
+        s.degraded.includes("unresolved-symbols")) {
+        return {
+            level: null,
+            score: 0,
+            signals: s,
+            rationale: explain(s, t, 0, null),
+            degraded: s.degraded,
+        };
+    }
+    const score = scoreSignals(s, t);
+    const level = levelFromScore(score, t.cuts);
+    return {
+        level,
+        score,
+        signals: s,
+        rationale: explain(s, t, score, level),
+        degraded: s.degraded,
+    };
+}
+function isSpecPath(rel) {
+    const n = rel.split("\\").join("/");
+    return n.startsWith("lawbook/specs/") || n.includes("/lawbook/specs/");
+}
+/** Resolve modules for paths using configured roots / inferModule. */
+export function countModules(paths) {
+    const mods = new Set(paths.map((p) => inferModule(p.split("\\").join("/")) || p.split("/")[0] || p));
+    return mods.size;
+}
+/**
+ * Build signals from an explicit target list. When the Compass index is missing,
+ * marks `no-index` and does not invent a small blast radius.
+ */
+export function gatherSignals(projectPath, targets, t = DEFAULT_THRESHOLDS) {
+    const degraded = [];
+    const paths = new Set(targets.paths.map((p) => p.replace(/^\.\//, "").split("\\").join("/")));
+    if (!indexExists(projectPath)) {
+        degraded.push("no-index");
+    }
+    else {
+        for (const sym of targets.symbols) {
+            const ex = explore(projectPath, sym);
+            if (ex.found && ex.symbol?.file)
+                paths.add(ex.symbol.file.split("\\").join("/"));
+            else
+                degraded.push("unresolved-symbols");
+        }
+    }
+    const pathList = [...paths];
+    const onlyDocs = pathList.length > 0 &&
+        pathList.every((p) => matchesAny(p, t.docGlobs)) &&
+        !pathList.some(isSpecPath);
+    let touchesGlobalFile = pathList.some((p) => matchesAny(p, t.globalGlobs));
+    try {
+        const cfg = loadAffectedConfig(projectPath);
+        if (pathList.some((p) => cfg.globalFiles.some((g) => matchGlob(p, g)))) {
+            touchesGlobalFile = true;
+        }
+    }
+    catch {
+        /* soft */
+    }
+    let blastRadiusNodes = 0;
+    let affected = 0;
+    let touchesPublicApi = false;
+    let maxHotspotScore = 0;
+    if (indexExists(projectPath) && pathList.length > 0) {
+        try {
+            const imp = impact(projectPath, { files: pathList, format: "grouped", maxDepth: 4 });
+            blastRadiusNodes = imp.totals.nodes;
+            if (imp.global)
+                touchesGlobalFile = true;
+        }
+        catch {
+            /* soft */
+        }
+        try {
+            const at = affectedTests(projectPath, { files: pathList });
+            affected = at.mode === "all" ? Math.max(at.tests.length, 50) : at.tests.length;
+        }
+        catch {
+            /* soft */
+        }
+        try {
+            const pkgPath = path.join(projectPath, "package.json");
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+                const entries = new Set();
+                if (typeof pkg.main === "string")
+                    entries.add(pkg.main.replace(/^\.\//, ""));
+                if (typeof pkg.bin === "string")
+                    entries.add(pkg.bin.replace(/^\.\//, ""));
+                else if (pkg.bin && typeof pkg.bin === "object") {
+                    for (const v of Object.values(pkg.bin))
+                        entries.add(String(v).replace(/^\.\//, ""));
+                }
+                for (const e of entries) {
+                    if (pathList.some((p) => p === e || e.endsWith(p) || p.endsWith(e))) {
+                        touchesPublicApi = true;
+                    }
+                }
+                if (pathList.some((p) => p === "src/cli/index.ts" || p === "src/server.ts")) {
+                    touchesPublicApi = true;
+                }
+            }
+        }
+        catch {
+            /* soft */
+        }
+        try {
+            const hs = hotspots(projectPath, { days: 90, sortBy: "combined", limit: 200 });
+            const byFile = new Map(hs.hotspots.map((h) => [h.file, h.combinedScore]));
+            let maxCombined = 0;
+            for (const h of hs.hotspots)
+                maxCombined = Math.max(maxCombined, h.combinedScore);
+            if (maxCombined <= 0)
+                degraded.push("no-hotspots");
+            else {
+                for (const p of pathList) {
+                    const c = byFile.get(p) ?? 0;
+                    maxHotspotScore = Math.max(maxHotspotScore, c / maxCombined);
+                }
+            }
+        }
+        catch {
+            degraded.push("no-hotspots");
+        }
+    }
+    return {
+        filesTouched: pathList.length,
+        modulesTouched: pathList.length ? countModules(pathList) : 0,
+        blastRadiusNodes,
+        affectedTests: affected,
+        touchesPublicApi,
+        maxHotspotScore,
+        touchesGlobalFile,
+        onlyDocs,
+        degraded: [...new Set(degraded)],
+    };
+}
+/** Load ceremony thresholds from lawbook/config.yaml (line-oriented). */
+export function loadCeremonyConfig(projectPath) {
+    const thresholds = structuredClone(DEFAULT_THRESHOLDS);
+    const cfgPath = path.join(projectPath, "lawbook", "config.yaml");
+    if (!fs.existsSync(cfgPath))
+        return { thresholds, invalidCuts: false };
+    const text = fs.readFileSync(cfgPath, "utf8");
+    const cuts = /^\s*cuts\s*:\s*\[([^\]]*)\]\s*$/im.exec(text);
+    let invalidCuts = false;
+    if (cuts) {
+        const nums = cuts[1]
+            .split(",")
+            .map((s) => Number(s.trim()))
+            .filter((n) => Number.isFinite(n));
+        if (nums.length === 3 && nums[0] < nums[1] && nums[1] < nums[2]) {
+            thresholds.cuts = [nums[0], nums[1], nums[2]];
+        }
+        else {
+            invalidCuts = true;
+        }
+    }
+    const floor = /^\s*hotspotFloor\s*:\s*([0-9.]+)\s*$/im.exec(text);
+    if (floor)
+        thresholds.hotspotFloor = Number(floor[1]);
+    return { thresholds, invalidCuts };
+}
+export function changeJsonPath(projectPath, change) {
+    return path.join(projectPath, "lawbook", "changes", change, "change.json");
+}
+export function readCeremonyRecord(projectPath, change) {
+    const p = changeJsonPath(projectPath, change);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Confirmed level, or 3 when change.json is missing. */
+export function confirmedLevel(projectPath, change) {
+    return readCeremonyRecord(projectPath, change)?.confirmedLevel ?? 3;
+}
+export function writeCeremonyRecord(projectPath, change, record) {
+    const p = changeJsonPath(projectPath, change);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(record, null, 2) + "\n");
+}
+export function setCeremonyLevel(projectPath, change, opts) {
+    const proposed = opts.proposal.level;
+    if (proposed !== null && opts.level < proposed && !opts.reason) {
+        throw new Error(`mode 'set' to a lower level than proposed (${proposed}) requires 'reason'`);
+    }
+    const prev = readCeremonyRecord(projectPath, change);
+    const record = {
+        ...opts.proposal,
+        confirmedLevel: opts.level,
+        confirmedBy: opts.confirmedBy,
+        confirmedAt: new Date().toISOString(),
+        overrideReason: opts.reason,
+        promotions: prev?.promotions ?? [],
+    };
+    writeCeremonyRecord(projectPath, change, record);
+    return record;
+}
+export function promoteCeremonyLevel(projectPath, change, to, reason) {
+    const prev = readCeremonyRecord(projectPath, change);
+    if (!prev)
+        throw new Error(`change "${change}" has no change.json to promote`);
+    if (to <= prev.confirmedLevel) {
+        throw new Error(`promote requires a higher level than ${prev.confirmedLevel}`);
+    }
+    const record = {
+        ...prev,
+        confirmedLevel: to,
+        confirmedAt: new Date().toISOString(),
+        promotions: [
+            ...prev.promotions,
+            { from: prev.confirmedLevel, to, at: new Date().toISOString(), reason },
+        ],
+    };
+    writeCeremonyRecord(projectPath, change, record);
+    scaffoldArtifactsForLevel(projectPath, change, to);
+    return record;
+}
+/**
+ * Create missing higher-level artifacts when promoting. Never deletes `record.md`.
+ * Seeds `proposal.md` / `tasks.md` from `record.md` when present.
+ */
+export function scaffoldArtifactsForLevel(projectPath, change, level) {
+    const changeDir = path.join(projectPath, "lawbook", "changes", change);
+    if (!fs.existsSync(changeDir))
+        return;
+    const needs = artifactNeeds(level);
+    const recordPath = path.join(changeDir, "record.md");
+    const recordText = fs.existsSync(recordPath) ? fs.readFileSync(recordPath, "utf8") : "";
+    const ensure = (rel, content) => {
+        const abs = path.join(changeDir, rel);
+        if (!fs.existsSync(abs)) {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, content);
+        }
+    };
+    if (needs.proposal) {
+        ensure("proposal.md", `# ${change}\n\n## Why\n\n${extractWhy(recordText) || "(promoted — fill in why)"}\n\n## What\n\n(promoted from level ${level})\n`);
+    }
+    if (needs.design && !needs.designOptionalWithJustification) {
+        ensure("design.md", `# Design — ${change}\n\n## Approach\n\n(promoted — fill in)\n`);
+    }
+    if (needs.tasksFile) {
+        const steps = extractChecklist(recordText);
+        ensure("tasks.md", steps.length
+            ? steps.map((s) => `- [ ] ${s}`).join("\n") + "\n"
+            : `- [ ] Implement\n- [ ] Add or update tests\n- [ ] Write discipline report under reports/\n`);
+    }
+    ensure("reports/README.md", `# Reports — ${change}\n\nAdd at least one discipline report before archive.\n`);
+}
+function extractWhy(recordMd) {
+    const m = /\*\*Why:\*\*\s*(.+)/i.exec(recordMd);
+    return m?.[1]?.trim() ?? "";
+}
+function extractChecklist(recordMd) {
+    const out = [];
+    for (const line of recordMd.split("\n")) {
+        const m = /^\s*[-*]\s+\[[ xX]\]\s+(.+)$/.exec(line);
+        if (m)
+            out.push(m[1].trim());
+    }
+    return out;
+}
+/** Count unchecked `- [ ]` tasks in markdown (tasks.md or record.md Steps). */
+export function countUncheckedTasks(markdown) {
+    return (markdown.match(/^\s*[-*]\s+\[ \]/gm) ?? []).length;
+}
+export function hasDisciplineReport(changeDir) {
+    const reportsDir = path.join(changeDir, "reports");
+    if (!fs.existsSync(reportsDir))
+        return false;
+    return fs
+        .readdirSync(reportsDir)
+        .some((n) => n.endsWith(".md") && n.toLowerCase() !== "readme.md");
+}

package/dist/modules/lawbook/quick.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, setCeremonyLevel, } from "./levels.js";
+/**
+ * Scaffold a level-0 change: `record.md`, `change.json`, and `reports/`.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change folder name (kebab-case).
+ * @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
+        ? proposal.rationale
+        : proposal.level > 0
+            ? `${proposal.rationale} — quick forced level 0; promote if scope grows`
+            : proposal.rationale;
+    const recordMd = `# ${name}
+
+**Level:** 0 (proposed: ${proposal.level ?? "n/a"}, confirmed by: human)
+**Why:** ${rationale}
+
+## What changes
+
+<!-- 2–5 lines: what and why. -->
+
+## Steps
+
+- [ ] Make the fix
+- [ ] Add or update a regression test
+- [ ] Record evidence under reports/
+
+## 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 };
+}
+/**
+ * Handle `lawbook_level` modes: propose / set / promote / explain.
+ */
+export function handleLevel(args) {
+    const targets = {
+        paths: args.paths ?? [],
+        symbols: args.symbols ?? [],
+    };
+    const { thresholds } = loadCeremonyConfig(args.projectPath);
+    const signals = gatherSignals(args.projectPath, targets, thresholds);
+    const proposal = proposeLevel(signals, thresholds);
+    if (args.mode === "propose" || args.mode === "explain") {
+        return { mode: args.mode, proposal };
+    }
+    if (!args.change)
+        throw new Error(`mode '${args.mode}' requires 'change'`);
+    if (args.mode === "set") {
+        if (args.level === undefined)
+            throw new Error("mode 'set' requires 'level'");
+        return setCeremonyLevel(args.projectPath, args.change, {
+            proposal,
+            level: args.level,
+            confirmedBy: "human",
+            reason: args.reason,
+        });
+    }
+    // promote
+    if (args.level === undefined)
+        throw new Error("mode 'promote' requires 'level'");
+    return promoteCeremonyLevel(args.projectPath, args.change, args.level, args.reason ?? "scope grew");
+}

package/dist/modules/lawbook/register.js

@@ -5,6 +5,7 @@ import { shouldExpose } from "../../shared/exposure.js";
 import { assetsDir } from "../../shared/paths.js";
 import { copyRendered } from "../../shared/install.js";
 import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
+import { handleLevel } from "./quick.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
 const ASSETS = assetsDir(import.meta.url);
@@ -29,6 +30,15 @@ export function registerSpec(server, opts = {}) {
     };
     add("lawbook_init", "Create the lawbook/ workspace (specs, changes, archive, config). Idempotent.", { projectPath: z.string() }, async ({ projectPath }) => text(specInit(projectPath)));
     add("lawbook_list", "List active changes, archives, and canonical capabilities under lawbook/.", { projectPath: z.string() }, async ({ projectPath }) => text(specList(projectPath)));
+    add("lawbook_level", "Propose, set, promote, or explain a change's ceremony level (0–3).", {
+        projectPath: z.string(),
+        mode: z.enum(["propose", "set", "promote", "explain"]),
+        change: z.string().optional(),
+        paths: z.array(z.string()).optional(),
+        symbols: z.array(z.string()).optional(),
+        level: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
+        reason: z.string().optional(),
+    }, async (args) => text(handleLevel(args)));
     add("lawbook_validate", "Validate a change's proposal, tasks, and delta specs before build or sync.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
     add("lawbook_sync", "Promote a change's delta specs into canonical lawbook/specs/ without archiving.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specSync(projectPath, change)));
     add("lawbook_archive", "Sync a change into canonical specs, then move it under changes/archive/.", {

package/dist/shared/exposure.js

@@ -19,6 +19,7 @@ export const MINIMAL_OMIT = new Set([
     "lawbook_init",
     "lawbook_archive",
     "lawbook_list",
+    "lawbook_level",
     "init_project",
     "scaffold",
     "configure_agent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "publishConfig": {
     "access": "public"
   },