@esneiderbravo/speclaw 0.3.7 → 0.3.8

package/README.md

@@ -129,6 +129,8 @@ tokenizer on this corpus — not a BPE dependency):
 ```bash
 speclaw budget          # human table
 speclaw budget --json   # machine-readable; used by the suite gate
+speclaw coverage        # requirement → impl → test coverage (TAP / table)
+speclaw coverage --json # machine-readable coverage report
 speclaw init --minimal  # omit setup/lifecycle MCP tools from registration
 ```
 

package/dist/cli/commands/coverage.js

@@ -0,0 +1,49 @@
+import { ui } from "../lib/ui.js";
+import { applyAdopt, buildCoverageReport, coverageExitCode, loadCoverageConfig, proposeAdopt, renderCoverageAgent, renderCoverageTable, renderCoverageTap, } from "../../modules/lawbook/coverage.js";
+/**
+ * Report requirement → impl → test coverage, or propose/apply id adoption.
+ *
+ * Flags: `--json`, `--tap`, `--adopt`, `--write`, `--change <name>`.
+ * Exit codes: 0 clean / no ids, 1 gated defects, 2 invocation error.
+ */
+export async function runCoverage(flags) {
+    const cwd = process.cwd();
+    if (flags.adopt) {
+        const proposals = proposeAdopt(cwd);
+        if (proposals.length === 0) {
+            ui.ok("Every requirement already has an identifier.");
+            return;
+        }
+        if (flags.write) {
+            const result = applyAdopt(cwd, proposals, { write: true });
+            ui.ok(`Wrote identifiers into ${result.written.length} file(s) (.bak backups kept).`);
+            for (const p of proposals) {
+                ui.plain(`  ${p.specPath}:${p.line}  ${p.title} → ${p.proposedId}${p.collision ? " (disambiguated)" : ""}`);
+            }
+            return;
+        }
+        ui.heading("coverage --adopt (dry run)");
+        for (const p of proposals) {
+            ui.plain(`  ${p.specPath}:${p.line}  ${p.title} → ${p.proposedId}${p.collision ? " (disambiguated)" : ""}`);
+        }
+        ui.plain();
+        ui.info(`Re-run with ${ui.code("--adopt --write")} to apply (backs up to .bak).`);
+        return;
+    }
+    const change = typeof flags.change === "string" ? flags.change : undefined;
+    const cfg = loadCoverageConfig(cwd);
+    const report = buildCoverageReport(cwd, { change, cfg });
+    if (flags.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else if (flags.tap || !process.stdout.isTTY) {
+        process.stdout.write(renderCoverageTap(report) + "\n");
+    }
+    else {
+        ui.heading("speclaw coverage");
+        console.log(renderCoverageTable(report));
+        ui.plain();
+        console.log(renderCoverageAgent(report, true));
+    }
+    process.exitCode = coverageExitCode(report, cfg);
+}

package/dist/cli/commands/update.js

@@ -92,6 +92,14 @@ const MIGRATIONS = [
         // scaffold → installHooks already rewrites .claude/settings.json when the
         // compiled hook shape changes; no extra run() step.
     },
+    {
+        version: "0.3.8",
+        describe: "Requirement coverage: speclaw coverage + lawbook_coverage + schema 5",
+        agentPrompt: "- Mention `speclaw coverage` / `lawbook_coverage` for requirement → impl → test coverage " +
+            "(ids like `req~name~1`, `// Covers:` comments). Compass schema is now 5 — reindex with " +
+            "`speclaw index`. Optionally add coverage.gateArchive / defaultNeeds under lawbook/config.yaml.\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

@@ -37,6 +37,7 @@ Lawbook (spec-driven workflow)
 Other
   doctor                   Verify the installation (--json, --offline, --strict)
   budget                   Measure always-on context cost (tools, skills, instructions)
+  coverage                 Requirement → impl → test coverage (--json, --tap, --adopt, --write)
   telemetry status         Confirm speclaw ships no telemetry
   check                    Evaluate an action against the laws (hooks call this; --dry-run to preview)
   laws verify              Verify the deterministic dependency/graph laws against the index
@@ -60,6 +61,7 @@ const HEADER_COMMANDS = new Set([
     "agent",
     "doctor",
     "budget",
+    "coverage",
     "telemetry",
     "index",
     "watch",
@@ -70,8 +72,9 @@ const HEADER_COMMANDS = new Set([
  * header-eligible command AND stdout is an interactive terminal (so pipes,
  * redirection, and CI stay clean — mirroring the color gate in `ui.ts`). A
  * forced-color signal counts as interactive so the header is exercisable in a
- * child process. `budget --json` and `doctor --json` are machine-consumed and
- * suppress the header.
+ * child process. `budget --json`, `doctor --json`, and `coverage` when emitting
+ * TAP/JSON (or when stdout is not a TTY) are machine-consumed and suppress the
+ * header.
  */
 function maybeHeader(cmd, flags) {
     if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
@@ -82,6 +85,8 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "doctor" && flags.json)
         return;
+    if (cmd === "coverage" && (flags.json || flags.tap))
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -126,6 +131,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/doctor.js")).runDoctor(flags);
         case "budget":
             return (await import("./commands/budget.js")).runBudget(flags);
+        case "coverage":
+            return (await import("./commands/coverage.js")).runCoverage(flags);
         case "telemetry":
             return (await import("./commands/telemetry.js")).runTelemetry(flags);
         case "check":

package/dist/cli/lib/untrack.js

@@ -12,6 +12,7 @@ import { listTrackedPaths } from "../../shared/git.js";
  *
  * @param projectPath - Project root to inspect and address.
  */
+// Covers: req~agent-ide-committable~1, req~ai-specs-untrack-hint~1
 export function reportTrackedLocalContent(projectPath) {
     const tracked = listTrackedPaths(projectPath, ["ai-specs"]);
     if (!tracked.length)

package/dist/modules/compass/db.js

@@ -55,9 +55,27 @@ CREATE TABLE IF NOT EXISTS git_history_cache (
   payload TEXT NOT NULL,
   computed_at INTEGER NOT NULL
 );
+-- coverage_links: derived requirement-coverage directives from comment nodes.
+-- Spec items themselves are NOT persisted — always reparsed from disk.
+CREATE TABLE IF NOT EXISTS coverage_links (
+  id INTEGER PRIMARY KEY,
+  artifact_type TEXT NOT NULL,
+  name TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  line INTEGER NOT NULL,
+  node_id INTEGER REFERENCES nodes(id) ON DELETE CASCADE,
+  source_type TEXT NOT NULL,
+  origin TEXT NOT NULL,
+  UNIQUE (artifact_type, name, revision, kind, file_path, line)
+);
+CREATE INDEX IF NOT EXISTS idx_cov_target ON coverage_links(artifact_type, name, revision);
+CREATE INDEX IF NOT EXISTS idx_cov_file ON coverage_links(file_path);
+CREATE INDEX IF NOT EXISTS idx_cov_node ON coverage_links(node_id);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "4";
+export const SCHEMA_VERSION = "5";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -89,6 +107,7 @@ function isStale(db) {
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP TABLE IF EXISTS coverage_links;
     DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
     DROP TABLE IF EXISTS edges;

package/dist/modules/compass/extract.js

@@ -1,4 +1,9 @@
 import { parse } from "./parser.js";
+const COMMENT_TYPES = new Set(["comment", "line_comment", "block_comment"]);
+/** `Covers:` / `Needs:` / `@covers` at the start of a comment line. */
+const RE_DIRECTIVE = /(?:^|\s|\*)\s*(?:@)?(covers|needs)\s*:?\s+([^\n*]+)/i;
+/** One OFT-shaped id: type~name~revision. */
+const RE_ID = /\b([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)\b/g;
 const DEF_LOOKUP = new WeakMap();
 function defKindMap(lang) {
     let m = DEF_LOOKUP.get(lang);
@@ -31,14 +36,59 @@ function calleeName(node, lang) {
 function signatureOf(node) {
     return node.text.split("\n")[0].trim().slice(0, 200);
 }
+/** Parse Covers:/Needs: directives from a comment node's text. */
+function parseCoverageComment(node, ownerIndex) {
+    const text = node.text;
+    const dir = RE_DIRECTIVE.exec(text);
+    if (!dir)
+        return [];
+    const kind = dir[1].toLowerCase();
+    const out = [];
+    for (const m of dir[2].matchAll(RE_ID)) {
+        out.push({
+            kind,
+            artifactType: m[1],
+            name: m[2],
+            revision: Number(m[3]),
+            line: node.startPosition.row + 1,
+            startByte: node.startIndex,
+            endByte: node.endIndex,
+            endLine: node.endPosition.row + 1,
+        });
+    }
+    // silence unused until attribution; ownerIndex filled by attachCoverage
+    void ownerIndex;
+    return out;
+}
+/**
+ * Attribute a coverage comment to a symbol: next def within 2 lines, else
+ * innermost containing symbol, else file-level (null).
+ */
+function attachCoverage(raw, symbols) {
+    return raw.map((c) => {
+        const next = symbols.find((s) => s.startByte >= c.endByte);
+        if (next && next.startLine - c.endLine <= 2) {
+            return { ...c, ownerIndex: symbols.indexOf(next) };
+        }
+        const containing = symbols
+            .map((s, i) => ({ s, i }))
+            .filter(({ s }) => s.startByte <= c.startByte && c.endByte <= s.endByte)
+            .sort((a, b) => a.s.endByte - a.s.startByte - (b.s.endByte - b.s.startByte));
+        if (containing.length > 0) {
+            return { ...c, ownerIndex: containing[0].i };
+        }
+        return { ...c, ownerIndex: null };
+    });
+}
 /**
- * Walk a parsed tree extracting definitions (with nesting) and the call/import
- * references each definition contains. Single traversal, O(nodes).
+ * Walk a parsed tree extracting definitions (with nesting), call/import
+ * references, and requirement-coverage directives from comment nodes. Single
+ * traversal, O(nodes).
  *
  * @param source - The full source text of the file.
  * @param lang - Language configuration describing definition/call/import nodes.
- * @returns The extracted symbols and references; `parentIndex`/`ownerIndex`
- * fields index back into the `symbols` array to express nesting and ownership.
+ * @returns The extracted symbols, references, and coverage directives;
+ * `parentIndex`/`ownerIndex` fields index back into the `symbols` array.
  * @throws If the source cannot be parsed for the given language.
  */
 export async function extract(source, lang) {
@@ -47,6 +97,7 @@ export async function extract(source, lang) {
     const importSet = new Set(lang.importNodes);
     const symbols = [];
     const refs = [];
+    const rawCoverage = [];
     const walk = (node, ownerIndex) => {
         let nextOwner = ownerIndex;
         if (kinds.has(node.type)) {
@@ -79,6 +130,9 @@ export async function extract(source, lang) {
                 ownerIndex,
             });
         }
+        else if (COMMENT_TYPES.has(node.type)) {
+            rawCoverage.push(...parseCoverageComment(node, ownerIndex));
+        }
         for (let i = 0; i < node.childCount; i++) {
             const child = node.child(i);
             if (child)
@@ -87,5 +141,5 @@ export async function extract(source, lang) {
     };
     walk(tree.rootNode, null);
     tree.delete();
-    return { symbols, refs };
+    return { symbols, refs, coverage: attachCoverage(rawCoverage, symbols) };
 }

package/dist/modules/compass/indexer.js

@@ -29,6 +29,24 @@ const MAX_FILE_BYTES = 1_500_000;
 function hashOf(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+/**
+ * Infer a covering artifact's type from its project-relative path.
+ * Full glob config lives in lawbook; this is the indexer default so links are
+ * typed even before a coverage report runs.
+ */
+function inferSourceType(relPath) {
+    const p = relPath.split("\\").join("/");
+    if (/(^|\/)test\/integration\//.test(p) || /(^|\/)tests\/integration\//.test(p))
+        return "itest";
+    if (/(^|\/)test\/unit\//.test(p) ||
+        /(^|\/)tests\/unit\//.test(p) ||
+        /\.test\.[cm]?[jt]sx?$/.test(p) ||
+        /\.spec\.[cm]?[jt]sx?$/.test(p) ||
+        /(^|\/)test\//.test(p)) {
+        return "utest";
+    }
+    return "impl";
+}
 function* walkFiles(root) {
     const stack = [root];
     while (stack.length) {
@@ -89,9 +107,13 @@ export async function buildIndex(projectPath, onProgress) {
     const updFile = db.prepare("UPDATE files SET hash = ?, lang = ? WHERE id = ?");
     const delNodes = db.prepare("DELETE FROM nodes WHERE file_id = ?");
     const delEdges = db.prepare("DELETE FROM edges WHERE src_file_id = ?");
+    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)
      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
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const insEmbed = db.prepare(`INSERT OR REPLACE INTO node_embeddings(node_id, dim, model, vec) VALUES (?, ?, ?, ?)`);
     const allFiles = [...walkFiles(projectPath)];
     db.exec("BEGIN");
@@ -125,12 +147,13 @@ export async function buildIndex(projectPath, onProgress) {
                 updFile.run(hash, lang.id, prior.id);
                 delNodes.run(prior.id);
                 delEdges.run(prior.id);
+                delCoverage.run(rel);
                 fileId = prior.id;
             }
             else {
                 fileId = Number(insFile.run(rel, hash, lang.id).lastInsertRowid);
             }
-            const { symbols, refs } = await extract(content, lang);
+            const { symbols, refs, coverage } = await extract(content, lang);
             const nodeIds = [];
             for (const s of symbols) {
                 const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
@@ -146,6 +169,11 @@ export async function buildIndex(projectPath, onProgress) {
                 insEdge.run(srcId, fileId, r.name, r.kind, r.line);
                 stats.edges++;
             }
+            const sourceType = inferSourceType(rel);
+            for (const c of coverage) {
+                const nodeId = c.ownerIndex !== null ? nodeIds[c.ownerIndex] : null;
+                insCoverage.run(c.artifactType, c.name, c.revision, c.kind, rel, c.line, nodeId, sourceType, "comment");
+            }
             stats.files++;
             stats.nodes += symbols.length;
         }

package/dist/modules/lawbook/coverage.js

@@ -0,0 +1,479 @@
+import fs from "node:fs";
+import path from "node:path";
+import { openDb, indexExists } from "../compass/db.js";
+import { formatItemId, loadSpecItems, parseItemId, parseSpecItems, } from "./spec-items.js";
+export const DEFAULT_COVERAGE_CONFIG = {
+    defaultNeeds: ["impl", "utest"],
+    gateStatuses: ["approved"],
+    gateArchive: true,
+    sources: {
+        impl: ["src/**"],
+        utest: ["test/unit/**", "test/**/*.test.ts", "test/**/*.test.js"],
+        itest: ["test/integration/**"],
+    },
+    exclude: ["**/node_modules/**", "**/dist/**", "**/.speclaw/**"],
+};
+/**
+ * Load coverage config from lawbook/config.yaml when present; otherwise defaults.
+ * Parses only a small line-oriented subset (no YAML dependency).
+ */
+export function loadCoverageConfig(projectPath) {
+    const cfg = structuredClone(DEFAULT_COVERAGE_CONFIG);
+    const cfgPath = path.join(projectPath, "lawbook", "config.yaml");
+    if (!fs.existsSync(cfgPath))
+        return cfg;
+    const text = fs.readFileSync(cfgPath, "utf8");
+    const gate = /^\s*gateArchive\s*:\s*(true|false)\s*$/im.exec(text);
+    if (gate)
+        cfg.gateArchive = gate[1].toLowerCase() === "true";
+    const needs = /^\s*defaultNeeds\s*:\s*\[([^\]]*)\]\s*$/im.exec(text);
+    if (needs) {
+        cfg.defaultNeeds = needs[1]
+            .split(",")
+            .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+            .filter(Boolean);
+    }
+    const statuses = /^\s*gateStatuses\s*:\s*\[([^\]]*)\]\s*$/im.exec(text);
+    if (statuses) {
+        cfg.gateStatuses = statuses[1]
+            .split(",")
+            .map((s) => s
+            .trim()
+            .replace(/^["']|["']$/g, "")
+            .toLowerCase())
+            .filter(Boolean);
+    }
+    return cfg;
+}
+/** Glob match supporting `**`, `*`, and path separators. */
+export function matchGlob(relPath, pattern) {
+    const norm = relPath.split("\\").join("/");
+    // Expand globs before escaping regex metacharacters so `*` is not double-escaped.
+    let i = 0;
+    let re = "^";
+    const p = pattern.split("\\").join("/");
+    while (i < p.length) {
+        if (p.startsWith("**/", i) || (p.startsWith("**", i) && i + 2 === p.length)) {
+            re += ".*";
+            i += p.startsWith("**/", i) ? 3 : 2;
+            continue;
+        }
+        if (p[i] === "*") {
+            re += "[^/]*";
+            i++;
+            continue;
+        }
+        const ch = p[i];
+        if (/[.+^${}()|[\]\\]/.test(ch))
+            re += `\\${ch}`;
+        else
+            re += ch;
+        i++;
+    }
+    re += "$";
+    return new RegExp(re).test(norm);
+}
+/** Infer artifact type from path using configured source globs. */
+export function inferArtifactType(relPath, cfg) {
+    const norm = relPath.split("\\").join("/");
+    if (cfg.exclude.some((g) => matchGlob(norm, g)))
+        return null;
+    for (const type of ["itest", "utest", "impl"]) {
+        const globs = cfg.sources[type] ?? [];
+        if (globs.some((g) => matchGlob(norm, g)))
+            return type;
+    }
+    return null;
+}
+function readIndexLinks(projectPath) {
+    if (!indexExists(projectPath))
+        return [];
+    const db = openDb(projectPath);
+    try {
+        const rows = db
+            .prepare(`SELECT artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
+         FROM coverage_links`)
+            .all();
+        return rows.map((r) => ({
+            artifactType: r.artifact_type,
+            name: r.name,
+            revision: r.revision,
+            kind: r.kind,
+            filePath: r.file_path,
+            line: r.line,
+            nodeId: r.node_id,
+            sourceType: r.source_type,
+            origin: r.origin,
+        }));
+    }
+    finally {
+        db.close();
+    }
+}
+function inlineLinksAsRaw(projectPath, items, cfg) {
+    const out = [];
+    for (const item of items) {
+        if (!item.id)
+            continue;
+        for (const inl of item.inlineLinks) {
+            const abs = path.join(projectPath, inl.targetPath);
+            const exists = fs.existsSync(abs);
+            const inferred = inferArtifactType(inl.targetPath, cfg) ?? (inl.kind === "test" ? "utest" : "impl");
+            out.push({
+                artifactType: item.id.artifactType,
+                name: item.id.name,
+                revision: item.id.revision,
+                kind: "covers",
+                filePath: inl.targetPath,
+                line: inl.line,
+                nodeId: null,
+                sourceType: inferred,
+                origin: "inline-test-link",
+                missingFile: !exists,
+            });
+        }
+    }
+    return out;
+}
+function classifyLink(link, item, idCounts, cfg) {
+    const base = {
+        artifactType: link.artifactType,
+        name: link.name,
+        revision: link.revision,
+        kind: link.kind,
+        filePath: link.filePath,
+        line: link.line,
+        nodeId: link.nodeId,
+        sourceType: link.sourceType,
+        origin: link.origin,
+        status: "Covers",
+    };
+    if (link.missingFile) {
+        return { ...base, status: "Orphaned", reason: "missing-file" };
+    }
+    if (cfg.exclude.some((g) => matchGlob(link.filePath, g))) {
+        return { ...base, status: "Orphaned", reason: "excluded-path" };
+    }
+    if (!item || !item.id) {
+        return { ...base, status: "Orphaned", reason: "unknown-item" };
+    }
+    if ((idCounts.get(item.idText) ?? 0) > 1) {
+        return { ...base, status: "Ambiguous", reason: "duplicate-id" };
+    }
+    if (item.status === "rejected") {
+        return { ...base, status: "Unwanted", reason: "item-rejected" };
+    }
+    if (link.revision < item.id.revision) {
+        return { ...base, status: "Outdated", reason: "revision-behind" };
+    }
+    if (link.revision > item.id.revision) {
+        return { ...base, status: "Predated", reason: "revision-ahead" };
+    }
+    const inferred = inferArtifactType(link.filePath, cfg);
+    if (inferred)
+        base.sourceType = inferred;
+    return base;
+}
+/**
+ * Build a full coverage report for a project (canonical specs by default).
+ *
+ * @param projectPath - Absolute project root.
+ * @param opts.change - Limit items to a change's delta specs (archive gate).
+ * @param opts.cfg - Optional preloaded config.
+ * @param opts.now - Optional fixed timestamp for deterministic JSON.
+ */
+export function buildCoverageReport(projectPath, opts = {}) {
+    const cfg = opts.cfg ?? loadCoverageConfig(projectPath);
+    const items = loadSpecItems(projectPath, { change: opts.change });
+    const identified = items.filter((i) => i.id !== null);
+    const idCounts = new Map();
+    for (const it of identified) {
+        idCounts.set(it.idText, (idCounts.get(it.idText) ?? 0) + 1);
+    }
+    const rawLinks = [
+        ...readIndexLinks(projectPath),
+        ...inlineLinksAsRaw(projectPath, identified, cfg),
+    ];
+    const results = [];
+    const matchedKeys = new Set();
+    for (const item of identified) {
+        const idText = item.idText;
+        const needs = item.needs.length > 0 ? item.needs : [...cfg.defaultNeeds];
+        const itemLinks = rawLinks
+            .filter((l) => l.artifactType === item.id.artifactType && l.name === item.id.name)
+            .map((l) => {
+            matchedKeys.add(`${l.filePath}:${l.line}:${l.revision}:${l.kind}`);
+            return classifyLink(l, item, idCounts, cfg);
+        });
+        const covering = itemLinks.filter((l) => l.status === "Covers");
+        const coveredTypes = [...new Set(covering.map((l) => l.sourceType))];
+        const uncoveredTypes = needs.filter((n) => !coveredTypes.includes(n));
+        const shallow = uncoveredTypes.length === 0 && (idCounts.get(idText) ?? 0) === 1;
+        const directDefects = [];
+        if ((idCounts.get(idText) ?? 0) > 1) {
+            directDefects.push(`duplicate id ${idText} at ${item.specPath}:${item.line}`);
+        }
+        for (const t of uncoveredTypes) {
+            directDefects.push(`missing ${t} for ${idText} at ${item.specPath}:${item.line}`);
+        }
+        for (const l of itemLinks) {
+            if (l.status === "Outdated" ||
+                l.status === "Orphaned" ||
+                l.status === "Ambiguous" ||
+                l.status === "Unwanted") {
+                directDefects.push(`${l.status} link ${l.filePath}:${l.line} → ${idText}` +
+                    (l.reason ? ` (${l.reason})` : ""));
+            }
+        }
+        results.push({
+            id: idText,
+            title: item.title,
+            status: item.status,
+            needs,
+            tags: item.tags,
+            depends: item.depends,
+            covers: item.covers,
+            specPath: item.specPath,
+            line: item.line,
+            coveredTypes,
+            uncoveredTypes,
+            shallow,
+            deep: shallow,
+            links: itemLinks,
+            directDefects,
+            transitiveDefects: [],
+        });
+    }
+    const byId = new Map(results.map((r) => [r.id, r]));
+    const visiting = new Set();
+    const visited = new Set();
+    const isDeep = (id, stack) => {
+        const r = byId.get(id);
+        if (!r)
+            return false;
+        if (!r.shallow) {
+            r.deep = false;
+            return false;
+        }
+        if (visited.has(id))
+            return r.deep;
+        if (visiting.has(id)) {
+            r.transitiveDefects.push(`cycle involving ${[...stack, id].join(" → ")}`);
+            r.deep = false;
+            return false;
+        }
+        visiting.add(id);
+        let deep = true;
+        for (const dep of [...r.depends, ...r.covers]) {
+            if (!byId.has(dep))
+                continue;
+            if (!isDeep(dep, [...stack, id]))
+                deep = false;
+        }
+        visiting.delete(id);
+        visited.add(id);
+        r.deep = deep && r.shallow;
+        return r.deep;
+    };
+    for (const r of results)
+        isDeep(r.id, []);
+    const orphans = [];
+    for (const l of rawLinks) {
+        const key = `${l.filePath}:${l.line}:${l.revision}:${l.kind}`;
+        if (matchedKeys.has(key))
+            continue;
+        orphans.push(classifyLink(l, undefined, idCounts, cfg));
+    }
+    const gated = results.filter((r) => cfg.gateStatuses.includes(r.status));
+    const directDefects = gated.reduce((n, r) => n + r.directDefects.length, 0);
+    const transitiveDefects = results.reduce((n, r) => n + r.transitiveDefects.length, 0);
+    return {
+        schemaVersion: 1,
+        generatedAt: opts.now ?? new Date().toISOString(),
+        summary: {
+            items: items.length,
+            identified: identified.length,
+            shallowCovered: results.filter((r) => r.shallow).length,
+            deepCovered: results.filter((r) => r.deep).length,
+            directDefects,
+            transitiveDefects,
+        },
+        items: results,
+        orphans,
+    };
+}
+/** Exit code for a report (0 clean / no ids, 1 gated direct defects). */
+export function coverageExitCode(report, cfg) {
+    if (report.summary.identified === 0)
+        return 0;
+    const gated = report.items.filter((i) => cfg.gateStatuses.includes(i.status));
+    const defects = gated.reduce((n, i) => n + i.directDefects.length, 0);
+    return defects > 0 ? 1 : 0;
+}
+/** TAP-compatible summary (non-TTY / --tap). */
+export function renderCoverageTap(report) {
+    if (report.summary.identified === 0) {
+        return [
+            "1..0",
+            "# no identified requirements — run: speclaw coverage --adopt",
+            "ok - 0 total",
+        ].join("\n");
+    }
+    const lines = [`1..${report.items.length}`];
+    let n = 0;
+    for (const item of report.items) {
+        n++;
+        const defects = [...item.directDefects, ...item.transitiveDefects];
+        if (defects.length === 0 && item.shallow) {
+            lines.push(`ok ${n} - ${item.id} (${item.coveredTypes.join(", ") || "covered"})`);
+        }
+        else {
+            lines.push(`not ok ${n} - ${item.id}`);
+            for (const d of defects)
+                lines.push(`  # ${d}`);
+            for (const t of item.uncoveredTypes)
+                lines.push(`  # uncovered: ${t}`);
+        }
+    }
+    const { directDefects, transitiveDefects } = report.summary;
+    if (directDefects === 0 && transitiveDefects === 0) {
+        lines.push(`ok - ${report.items.length} total`);
+    }
+    else {
+        lines.push(`not ok - ${report.items.length} total, ${directDefects} direct, ${transitiveDefects} transitive defects`);
+    }
+    return lines.join("\n");
+}
+/** Human table for TTY. */
+export function renderCoverageTable(report) {
+    if (report.summary.identified === 0) {
+        return "No identified requirements. Run `speclaw coverage --adopt` to propose ids.";
+    }
+    const rows = report.items.map((i) => {
+        const mark = i.shallow ? (i.deep ? "ok" : "shallow") : "MISS";
+        return `${mark.padEnd(8)} ${i.id.padEnd(36)} ${(i.coveredTypes.join(",") || "-").padEnd(16)} ${i.specPath}:${i.line}`;
+    });
+    const s = report.summary;
+    rows.push("");
+    rows.push(`identified ${s.identified} · shallow ${s.shallowCovered} · deep ${s.deepCovered} · direct defects ${s.directDefects} · transitive ${s.transitiveDefects}`);
+    return rows.join("\n");
+}
+/** Defect-first agent text, capped (~600 tokens ≈ 2400 chars). */
+export function renderCoverageAgent(report, onlyDefects = true) {
+    if (report.summary.identified === 0) {
+        return "No identified requirements. Next: run `speclaw coverage --adopt` then add `// Covers: req~…~1` above impl/tests.";
+    }
+    const items = onlyDefects
+        ? report.items.filter((i) => i.directDefects.length > 0 || !i.shallow)
+        : report.items;
+    if (items.length === 0) {
+        return `Coverage clean: ${report.summary.shallowCovered}/${report.summary.identified} shallow, ${report.summary.deepCovered} deep. Next: archive when tasks and reports are done.`;
+    }
+    const lines = [
+        `Coverage defects: ${report.summary.directDefects} direct, ${report.summary.transitiveDefects} transitive.`,
+    ];
+    for (const i of items.slice(0, 12)) {
+        lines.push(`- ${i.id} @ ${i.specPath}:${i.line}`);
+        for (const d of i.directDefects.slice(0, 3))
+            lines.push(`    ${d}`);
+        if (i.uncoveredTypes.length) {
+            lines.push(`    add Covers for: ${i.uncoveredTypes.join(", ")}`);
+        }
+    }
+    if (items.length > 12)
+        lines.push(`…and ${items.length - 12} more`);
+    lines.push("Next: add `// Covers: <id>` above the impl/test, reindex, re-run coverage.");
+    let text = lines.join("\n");
+    if (text.length > 2400)
+        text = text.slice(0, 2397) + "...";
+    return text;
+}
+/**
+ * Archive-gate reasons for direct defects on gated statuses.
+ * Opt-in: contributes nothing when the change's delta specs have zero ids.
+ */
+export function coverageArchiveBlockers(projectPath, change) {
+    const cfg = loadCoverageConfig(projectPath);
+    if (!cfg.gateArchive)
+        return [];
+    const report = buildCoverageReport(projectPath, { change, cfg });
+    if (report.summary.identified === 0)
+        return [];
+    const blockers = [];
+    for (const item of report.items) {
+        if (!cfg.gateStatuses.includes(item.status))
+            continue;
+        for (const d of item.directDefects)
+            blockers.push(`coverage: ${d}`);
+    }
+    return blockers;
+}
+/** Propose `req~slug~1` ids for requirements that lack them. */
+export function proposeAdopt(projectPath) {
+    const items = loadSpecItems(projectPath);
+    const used = new Set(items.filter((i) => i.idText).map((i) => i.idText));
+    const proposals = [];
+    for (const item of items) {
+        if (item.id)
+            continue;
+        const base = slugify(item.title) || "item";
+        let name = base;
+        let n = 2;
+        let id = `req~${name}~1`;
+        let collision = false;
+        while (used.has(id)) {
+            collision = true;
+            name = `${base}-${n++}`;
+            id = `req~${name}~1`;
+        }
+        used.add(id);
+        proposals.push({
+            specPath: item.specPath,
+            line: item.line,
+            title: item.title,
+            proposedId: id,
+            collision,
+        });
+    }
+    return proposals;
+}
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+}
+/**
+ * Apply adopt proposals. Writes only when `write` is true; backs up to
+ * `<file>.bak` before mutating.
+ */
+export function applyAdopt(projectPath, proposals, opts = {}) {
+    if (!opts.write)
+        return { written: [], dryRun: true };
+    const byFile = new Map();
+    for (const p of proposals) {
+        const list = byFile.get(p.specPath) ?? [];
+        list.push(p);
+        byFile.set(p.specPath, list);
+    }
+    const written = [];
+    for (const [rel, props] of byFile) {
+        const abs = path.join(projectPath, rel);
+        const original = fs.readFileSync(abs, "utf8");
+        const lines = original.split(/\r?\n/);
+        const ordered = [...props].sort((a, b) => b.line - a.line);
+        for (const p of ordered) {
+            const idx = p.line - 1;
+            const line = lines[idx];
+            if (!line || line.includes("`req~"))
+                continue;
+            lines[idx] = line.replace(/^(###\s+Requirement:\s*)(.+)$/, `$1${p.title} \`${p.proposedId}\``);
+        }
+        fs.copyFileSync(abs, abs + ".bak");
+        fs.writeFileSync(abs, lines.join("\n"));
+        written.push(rel);
+    }
+    return { written, dryRun: false };
+}
+export { parseSpecItems, parseItemId, formatItemId };

package/dist/modules/lawbook/engine.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { coverageArchiveBlockers } from "./coverage.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
@@ -310,6 +311,8 @@ export function specArchivePreconditions(projectPath, change) {
             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.
+    blockers.push(...coverageArchiveBlockers(projectPath, change));
     return blockers;
 }
 /**

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 { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 const ASSETS = assetsDir(import.meta.url);
 /**
  * Install the spec module's workflow interface into a project's ai-specs/:
@@ -34,4 +35,16 @@ export function registerSpec(server, opts = {}) {
         change: z.string(),
         date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
     }, async ({ projectPath, change, date }) => text(specArchive(projectPath, change, date)));
+    add("lawbook_coverage", "Report which requirements lack impl/test coverage before declaring work done.", {
+        projectPath: z.string(),
+        change: z.string().optional(),
+        onlyDefects: z.boolean().optional(),
+        json: z.boolean().optional(),
+    }, async ({ projectPath, change, onlyDefects, json }) => {
+        const cfg = loadCoverageConfig(projectPath);
+        const report = buildCoverageReport(projectPath, { change, cfg });
+        if (json)
+            return text(JSON.stringify(report));
+        return text(renderCoverageAgent(report, onlyDefects !== false));
+    });
 }

package/dist/modules/lawbook/spec-items.js

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+const RE_REQUIREMENT = /^###\s+Requirement:\s*(.+?)\s*$/;
+const RE_ID = /`([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)`/;
+const RE_KEYWORD = /^(Status|Needs|Tags|Depends|Covers)\s*:\s*(.+?)\s*$/i;
+const RE_INLINE = /\[@(test|impl)\s+([^\]]+)\]/gi;
+const RE_ID_LOOSE = /\b([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)\b/g;
+/** Format a SpecItemId as `type~name~rev`. */
+export function formatItemId(id) {
+    return `${id.artifactType}~${id.name}~${id.revision}`;
+}
+/** Parse a single `type~name~rev` token, or null if malformed. */
+export function parseItemId(text) {
+    const m = /^([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)$/.exec(text.trim());
+    if (!m)
+        return null;
+    return { artifactType: m[1], name: m[2], revision: Number(m[3]) };
+}
+function splitList(value) {
+    return value
+        .split(/[, ]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function parseIdList(value) {
+    const out = [];
+    for (const m of value.matchAll(RE_ID_LOOSE)) {
+        out.push(`${m[1]}~${m[2]}~${m[3]}`);
+    }
+    return out;
+}
+/**
+ * Parse one markdown spec file into requirement items. Headings without an
+ * inline-code identifier are returned with `id: null` (ignored by coverage).
+ *
+ * @param specPath - Project-relative path of the spec (for reporting).
+ * @param content - Full markdown source.
+ */
+export function parseSpecItems(specPath, content) {
+    const lines = content.split(/\r?\n/);
+    const items = [];
+    let current = null;
+    const flush = () => {
+        if (current)
+            items.push(current);
+        current = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const req = RE_REQUIREMENT.exec(line);
+        if (req) {
+            flush();
+            const rest = req[1];
+            const idMatch = RE_ID.exec(rest);
+            let title = rest;
+            let id = null;
+            let idText = null;
+            if (idMatch) {
+                id = {
+                    artifactType: idMatch[1],
+                    name: idMatch[2],
+                    revision: Number(idMatch[3]),
+                };
+                idText = formatItemId(id);
+                title = rest.replace(idMatch[0], "").replace(/\s+/g, " ").trim();
+                // Common forms: "Title `id`" or "`id` Title"
+                title = title.replace(/^[\s—–-]+|[\s—–-]+$/g, "").trim();
+            }
+            current = {
+                id,
+                idText,
+                title,
+                status: "approved",
+                needs: [],
+                tags: [],
+                depends: [],
+                covers: [],
+                inlineLinks: [],
+                specPath,
+                line: i + 1,
+            };
+            continue;
+        }
+        if (!current)
+            continue;
+        // Next ### Requirement: or # heading ends the item body for keyword purposes,
+        // but #### Scenario lines may still carry inline links.
+        if (/^###?\s+/.test(line) && !/^####\s+/.test(line)) {
+            flush();
+            // Re-process this line as a potential new requirement on next iteration
+            // by rewinding — simpler: only #### and body lines belong to current.
+            i--;
+            continue;
+        }
+        const kw = RE_KEYWORD.exec(line);
+        if (kw) {
+            const key = kw[1].toLowerCase();
+            const value = kw[2];
+            if (key === "status")
+                current.status = value.trim().toLowerCase();
+            else if (key === "needs")
+                current.needs = splitList(value).map((s) => s.toLowerCase());
+            else if (key === "tags")
+                current.tags = splitList(value);
+            else if (key === "depends")
+                current.depends = parseIdList(value);
+            else if (key === "covers")
+                current.covers = parseIdList(value);
+            continue;
+        }
+        for (const m of line.matchAll(RE_INLINE)) {
+            current.inlineLinks.push({
+                kind: m[1].toLowerCase(),
+                targetPath: m[2].trim(),
+                line: i + 1,
+            });
+        }
+    }
+    flush();
+    return items;
+}
+/**
+ * Walk `lawbook/specs/**\/spec.md` (and optionally a change's delta specs) and
+ * parse every requirement item.
+ *
+ * @param projectPath - Absolute project root.
+ * @param opts.change - When set, parse only that change's delta specs.
+ */
+export function loadSpecItems(projectPath, opts = {}) {
+    const roots = [];
+    if (opts.change) {
+        roots.push(path.join(projectPath, "lawbook", "changes", opts.change, "specs"));
+    }
+    else {
+        roots.push(path.join(projectPath, "lawbook", "specs"));
+    }
+    const items = [];
+    for (const root of roots) {
+        if (!fs.existsSync(root))
+            continue;
+        for (const file of walkSpecFiles(root)) {
+            const rel = path.relative(projectPath, file).split(path.sep).join("/");
+            const content = fs.readFileSync(file, "utf8");
+            items.push(...parseSpecItems(rel, content));
+        }
+    }
+    return items;
+}
+function* walkSpecFiles(dir) {
+    const stack = [dir];
+    while (stack.length) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(cur, e.name);
+            if (e.isDirectory())
+                stack.push(full);
+            else if (e.isFile() && e.name === "spec.md")
+                yield full;
+        }
+    }
+}

package/dist/shared/exposure.js

@@ -5,7 +5,7 @@ import { readManifest } from "./manifest.js";
 /**
  * Tools omitted when the exposure profile is `minimal`. Kept tools are the
  * discovery + law loop: compass_explore/search/recall, lawbook_validate/sync,
- * law_verify, speclaw_check.
+ * lawbook_coverage, law_verify, speclaw_check.
  */
 export const MINIMAL_OMIT = new Set([
     "compass_index",

package/dist/shared/install.js

@@ -94,6 +94,7 @@ export function copyRendered(srcDir, destDir, vars, report, opts) {
  * @param comment - Comment line written above the entry when it is added.
  * @param report - Report mutated in place; the appended entry is recorded under `written`.
  */
+// Covers: req~ai-specs-gitignore~1
 export function ensureGitignore(projectPath, entry, comment, report) {
     const gitignorePath = path.join(projectPath, ".gitignore");
     let content = "";

package/package.json

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