@esneiderbravo/speclaw 0.3.10 → 0.3.12

package/dist/modules/compass/indexer.js

@@ -214,6 +214,7 @@ export async function buildIndex(projectPath, onProgress) {
     const delCoverage = db.prepare("DELETE FROM coverage_links WHERE file_path = ?");
     const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insMetrics = db.prepare(`INSERT INTO node_metrics(node_id, loc, max_nesting, branches) VALUES (?, ?, ?, ?)`);
     const insEdge = db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line) VALUES (?, ?, ?, ?, ?)`);
     const insCoverage = db.prepare(`INSERT OR REPLACE INTO coverage_links(
        artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
@@ -265,6 +266,7 @@ export async function buildIndex(projectPath, onProgress) {
                 const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
                 const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash).lastInsertRowid);
                 nodeIds.push(id);
+                insMetrics.run(id, s.loc, s.maxNesting, s.branches);
                 // embed the node from its name + signature (cheap, meaningful text)
                 const vec = await embedder.embed(`${s.kind} ${s.name} ${s.signature ?? ""}`);
                 insEmbed.run(id, embedder.dim, embedder.id, toBlob(vec));

package/dist/modules/compass/languages.js

@@ -17,6 +17,19 @@ export const LANGUAGES = [
         callNode: "call",
         callField: "function",
         importNodes: ["import_statement", "import_from_statement"],
+        nestingNodes: ["block", "suite"],
+        branchNodes: [
+            "if_statement",
+            "elif_clause",
+            "for_statement",
+            "while_statement",
+            "match_statement",
+            "case_clause",
+            "conditional_expression",
+            "except_clause",
+            "with_statement",
+            "boolean_operator",
+        ],
     },
     {
         id: "javascript",
@@ -30,6 +43,19 @@ export const LANGUAGES = [
         callNode: "call_expression",
         callField: "function",
         importNodes: ["import_statement"],
+        nestingNodes: ["statement_block", "class_body"],
+        branchNodes: [
+            "if_statement",
+            "else_clause",
+            "for_statement",
+            "for_in_statement",
+            "while_statement",
+            "do_statement",
+            "switch_case",
+            "switch_default",
+            "catch_clause",
+            "ternary_expression",
+        ],
     },
     {
         id: "typescript",
@@ -46,6 +72,19 @@ export const LANGUAGES = [
         callNode: "call_expression",
         callField: "function",
         importNodes: ["import_statement"],
+        nestingNodes: ["statement_block", "class_body"],
+        branchNodes: [
+            "if_statement",
+            "else_clause",
+            "for_statement",
+            "for_in_statement",
+            "while_statement",
+            "do_statement",
+            "switch_case",
+            "switch_default",
+            "catch_clause",
+            "ternary_expression",
+        ],
     },
 ];
 const BY_EXT = new Map();

package/dist/modules/compass/register.js

@@ -4,6 +4,7 @@ import { shouldExpose } from "../../shared/exposure.js";
 import { buildIndex } from "./indexer.js";
 import { explore, search, recall, impact, trace } from "./query.js";
 import { affectedTests } from "./affected.js";
+import { hotspots, coupling } from "./hotspots.js";
 import { startWatch, stopWatch, watchStatus } from "./watcher.js";
 import { visualize } from "./visualize.js";
 // ─── Compass: speclaw's own code-intelligence engine (no external deps) ───
@@ -55,6 +56,22 @@ export function registerCompass(server, opts = {}) {
         fromDiff: z.string().optional(),
         maxDepth: z.number().int().min(1).max(12).optional(),
     }, async ({ projectPath, files, symbols, fromDiff, maxDepth }) => text(affectedTests(projectPath, { files, symbols, fromDiff, maxDepth })));
+    add("compass_hotspots", "Rank files by recent churn and AST complexity; two axes, no magic score.", {
+        projectPath: z.string(),
+        days: z.number().int().min(1).max(3650).optional(),
+        since: z.string().optional(),
+        sortBy: z.enum(["churn", "complexity", "combined"]).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
+    }, async ({ projectPath, days, since, sortBy, limit }) => text(hotspots(projectPath, { days, since, sortBy, limit })));
+    add("compass_coupling", "Files that co-change with a target; strength, graph edge, and test-pair facts.", {
+        projectPath: z.string(),
+        file: z.string(),
+        days: z.number().int().min(1).max(3650).optional(),
+        since: z.string().optional(),
+        minShared: z.number().int().min(1).optional(),
+        maxFilesPerCommit: z.number().int().min(2).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
+    }, async ({ projectPath, file, days, since, minShared, maxFilesPerCommit, limit }) => text(coupling(projectPath, file, { days, since, minShared, maxFilesPerCommit, limit })));
     add("compass_trace", "Find a call path between two symbols within a depth limit.", {
         projectPath: z.string(),
         from: z.string(),

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.