@esneiderbravo/speclaw 0.1.14 → 0.2.0

package/dist/cli/commands/lawbook.js

@@ -40,17 +40,22 @@ export async function runSpec(flags) {
                     ui.warn(`${r.change} has ${r.issues.length} issue(s):`);
                     r.issues.forEach((i) => ui.info(i));
                 }
+                if (r.warnings.length > 0) {
+                    ui.warn(`${r.warnings.length} advisory warning(s):`);
+                    r.warnings.forEach((w) => ui.info(w));
+                }
                 return;
             }
             case "sync": {
                 const r = specSync(cwd, req(change, "spec sync <change>"));
                 ui.ok(`promoted ${r.promoted.length} spec(s)`);
-                r.promoted.forEach((p) => ui.info(p));
+                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());
                 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}`));
                 return;
             }
             default:

package/dist/cli/commands/version.js

@@ -0,0 +1,31 @@
+import { pkgVersion } from "../../shared/version.js";
+import { checkForUpdates, upgradeNotice } from "../lib/update-check.js";
+/**
+ * Print the locally installed speclaw version and, when a newer version is
+ * published on npm, a clickable suggestion to upgrade.
+ *
+ * The installed version (from the package's own `package.json`) always goes to
+ * **stdout** as a bare line, so it stays script- and pipe-friendly
+ * (`v=$(speclaw --version)`). The upgrade suggestion — which requires a network
+ * lookup — goes to **stderr** and only when stderr is an interactive TTY and
+ * the notifier is not disabled, so scripts and CI pay no network cost and get
+ * clean output. The lookup is forced (bypasses the daily cache) so an explicit
+ * version query reflects npm right now, and every failure is swallowed: a
+ * flaky or offline registry must never break `--version`.
+ */
+export async function runVersion() {
+    console.log(pkgVersion());
+    if (process.env.NO_UPDATE_NOTIFIER || process.env.SPECLAW_NO_UPDATE_NOTIFIER)
+        return;
+    if (!process.stderr.isTTY)
+        return;
+    try {
+        const { current, latest, updateAvailable } = await checkForUpdates({ force: true });
+        if (updateAvailable && latest) {
+            process.stderr.write("\n" + upgradeNotice(current, latest) + "\n\n");
+        }
+    }
+    catch {
+        /* the update check is best-effort — never let it break `--version` */
+    }
+}

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { parseFlags } from "./lib/args.js";
-import { ui } from "./lib/ui.js";
+import { ui, header } from "./lib/ui.js";
 import { maybeNotifyUpdate } from "./lib/update-check.js";
 const HELP = `speclaw — spec-driven, agent-ready projects (foundation + Compass + Lawbook)
 
@@ -36,7 +36,40 @@ Other
   doctor                   Verify the installation
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
+  --version                Print the installed speclaw version
 `;
+// Commands that open with the one-line branded header. These are the
+// 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`, machine-consumed
+// output), `mcp` (a long-running stdio server), and `init` (already opens with
+// the fuller `banner()`).
+const HEADER_COMMANDS = new Set([
+    undefined,
+    "help",
+    "--help",
+    "-h",
+    "update",
+    "agent",
+    "doctor",
+    "index",
+    "watch",
+    "lawbook",
+]);
+/**
+ * Print the branded header once, ahead of a command's output, when it is a
+ * 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.
+ */
+function maybeHeader(cmd) {
+    if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
+        return;
+    if (!HEADER_COMMANDS.has(cmd))
+        return;
+    header();
+}
 /** Run the handler for a single command. Returns when the command completes. */
 async function dispatch(cmd, flags) {
     switch (cmd) {
@@ -46,6 +79,10 @@ async function dispatch(cmd, flags) {
         case "-h":
             console.log(HELP);
             return;
+        case "version":
+        case "--version":
+        case "-v":
+            return (await import("./commands/version.js")).runVersion();
         case "mcp": {
             const { startMcpServer } = await import("../server.js");
             await startMcpServer();
@@ -83,6 +120,7 @@ async function dispatch(cmd, flags) {
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
+    maybeHeader(cmd);
     await dispatch(cmd, flags);
     await maybeNotifyUpdate(cmd);
 }

package/dist/cli/lib/ui.js

@@ -2,6 +2,7 @@
 // = the "law", cream text, muted gray, green/amber for status) rendered as
 // 24-bit truecolor ANSI — no dependency needed. Colors auto-disable when the
 // output is not a TTY or NO_COLOR is set.
+import { pkgVersion } from "../../shared/version.js";
 const PALETTE = {
     cyan: [46, 230, 230], // #2EE6E6 — the accent / "law"
     cyanDim: [23, 193, 193], // #17C1C1
@@ -12,6 +13,44 @@ const PALETTE = {
     red: [235, 90, 90],
 };
 const colorOn = (Boolean(process.stdout.isTTY) || process.env.FORCE_COLOR === "1") && !process.env.NO_COLOR;
+// Whether the terminal reliably renders the unicode box/block glyphs the brand
+// output uses. Non-Windows terminals are assumed capable; a Windows console is
+// trusted only under a modern-terminal signal (Windows Terminal, an embedding
+// program like VS Code, or CI) — a legacy conhost with a non-UTF-8 code page
+// would otherwise show mojibake. No dependency; the check runs once at load.
+const unicodeOn = process.platform !== "win32" ||
+    Boolean(process.env.WT_SESSION || process.env.TERM_PROGRAM || process.env.CI);
+// The brand glyph set, resolved once against terminal capability. Every branded
+// renderer (header, banner, box, progress) draws from this so unicode and ASCII
+// terminals degrade together instead of one surface emitting unrenderable
+// glyphs. The ASCII fallbacks are chosen to preserve each drawing's shape.
+const G = unicodeOn
+    ? {
+        diamond: "◈",
+        dot: "·",
+        boxTL: "╭",
+        boxTR: "╮",
+        boxBL: "╰",
+        boxBR: "╯",
+        boxV: "│",
+        boxH: "─",
+        bar: "▇",
+        fill: "█",
+        track: "░",
+    }
+    : {
+        diamond: ">",
+        dot: "-",
+        boxTL: "+",
+        boxTR: "+",
+        boxBL: "+",
+        boxBR: "+",
+        boxV: "|",
+        boxH: "-",
+        bar: "#",
+        fill: "#",
+        track: "-",
+    };
 function paint(rgb, s) {
     if (!colorOn)
         return s;
@@ -20,6 +59,22 @@ function paint(rgb, s) {
 function bold(s) {
     return colorOn ? `\x1b[1m${s}\x1b[0m` : s;
 }
+/**
+ * Wrap `label` in an OSC 8 terminal hyperlink pointing at `url`, so a
+ * capable terminal renders it as a clickable link. Terminals that don't
+ * support OSC 8 simply ignore the escapes and show the label. Falls back to a
+ * plain `label (url)` when rich output is off (non-TTY / NO_COLOR) so piped and
+ * dumb-terminal output stays legible.
+ *
+ * @param label - The visible, clickable text.
+ * @param url - The target the terminal opens on click.
+ * @returns The label wrapped as a hyperlink, or `label (url)` when off.
+ */
+export function link(label, url) {
+    if (!colorOn)
+        return `${label} (${url})`;
+    return `\x1b]8;;${url}\x1b\\${label}\x1b]8;;\x1b\\`;
+}
 /** Brand color helpers for composing styled strings. */
 export const c = {
     cyan: (s) => paint(PALETTE.cyan, s),
@@ -42,21 +97,43 @@ export const ui = {
     plain: (s = "") => console.log(s),
     code: (s) => c.cyan(s),
 };
+/**
+ * A single-line branded header — mark · name · installed version · tagline —
+ * printed once at the top of interactive commands (see `src/cli/index.ts`). The
+ * version comes from the cached {@link pkgVersion}. Glyphs degrade to ASCII on
+ * terminals without reliable unicode, and the styling no-ops to plain text when
+ * color is off, so the line stays legible everywhere.
+ *
+ * Example: `◈ speclaw  v0.1.15 · where specs become law`
+ */
+export function header() {
+    const mark = c.cyan(G.diamond);
+    const name = bold(c.cream("speclaw"));
+    const ver = c.muted("v" + pkgVersion());
+    const tag = c.muted(G.dot + " where specs become law");
+    console.log(`${mark} ${name}  ${ver} ${tag}`);
+}
 /**
  * The speclaw wordmark + logo mark (a document whose bottom line — the law — is
  * highlighted in cyan). Printed at the top of `speclaw init`.
  */
 export function banner() {
-    const bar = c.cyan("▇▇▇▇▇▇");
-    const line = c.muted("──────");
+    const H = G.boxH;
+    const bar = c.cyan(G.bar.repeat(6));
+    const line = c.muted(H.repeat(6));
     const edge = c.muted;
     console.log();
-    console.log("  " + edge("╭────────╮"));
-    console.log("  " + edge("│ ") + line + edge(" │") + "   " + bold(c.cream("s p e c l a w")));
-    console.log("  " + edge("│ ") + c.muted("────  ") + edge(" │") + "   " + c.muted("where specs become law"));
-    console.log("  " + edge("│ ") + c.muted("─────") + " " + edge(" │"));
-    console.log("  " + edge("│ ") + bar + edge(" │"));
-    console.log("  " + edge("╰────────╯"));
+    console.log("  " + edge(G.boxTL + H.repeat(8) + G.boxTR));
+    console.log("  " + edge(G.boxV + " ") + line + edge(" " + G.boxV) + "   " + bold(c.cream("s p e c l a w")));
+    console.log("  " +
+        edge(G.boxV + " ") +
+        c.muted(H.repeat(4) + "  ") +
+        edge(" " + G.boxV) +
+        "   " +
+        c.muted("where specs become law"));
+    console.log("  " + edge(G.boxV + " ") + c.muted(H.repeat(5)) + " " + edge(" " + G.boxV));
+    console.log("  " + edge(G.boxV + " ") + bar + edge(" " + G.boxV));
+    console.log("  " + edge(G.boxBL + H.repeat(8) + G.boxBR));
     console.log();
 }
 /** Render a single-line progress bar on stderr (so stdout stays clean). */
@@ -66,7 +143,7 @@ export function renderProgress(done, total, label) {
     const width = 26;
     const ratio = total > 0 ? done / total : 1;
     const filled = Math.round(ratio * width);
-    const bar = c.cyan("█".repeat(filled)) + c.muted("░".repeat(width - filled));
+    const bar = c.cyan(G.fill.repeat(filled)) + c.muted(G.track.repeat(width - filled));
     const pct = c.cyanDim(String(Math.round(ratio * 100)).padStart(3) + "%");
     const shortLabel = label.length > 38 ? "…" + label.slice(-37) : label;
     process.stderr.write(`\r  ${bar} ${pct}  ${c.muted(shortLabel.padEnd(38))}`);
@@ -78,11 +155,12 @@ export function clearProgress() {
 /** Draw a cyan-bordered block (used for the copy-paste agent prompt). */
 export function box(lines, title) {
     const width = Math.min(72, Math.max(...lines.map((l) => l.length), title?.length ?? 0) + 2);
+    const H = G.boxH;
     const top = title
-        ? "╭─ " + c.cyanDim(title) + " " + "─".repeat(Math.max(0, width - title.length - 3))
-        : "╭" + "─".repeat(width);
-    console.log("  " + c.muted(top) + c.muted("╮"));
+        ? G.boxTL + H + " " + c.cyanDim(title) + " " + H.repeat(Math.max(0, width - title.length - 3))
+        : G.boxTL + H.repeat(width);
+    console.log("  " + c.muted(top) + c.muted(G.boxTR));
     for (const l of lines)
-        console.log("  " + c.muted("│ ") + c.cream(l.padEnd(width - 2)) + c.muted(" │"));
-    console.log("  " + c.muted("╰" + "─".repeat(width) + "╯"));
+        console.log("  " + c.muted(G.boxV + " ") + c.cream(l.padEnd(width - 2)) + c.muted(" " + G.boxV));
+    console.log("  " + c.muted(G.boxBL + H.repeat(width) + G.boxBR));
 }

package/dist/cli/lib/update-check.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pkgName, pkgVersion } from "../../shared/version.js";
-import { c } from "./ui.js";
+import { c, link } from "./ui.js";
 // A lightweight, best-effort update notifier. The registry is queried at most
 // once a day (result cached under ~/.speclaw/), the lookup is time-boxed, and
 // every failure is swallowed — checking for updates must never slow down or
@@ -95,9 +95,36 @@ export async function checkForUpdates(opts = {}) {
     }
     return { current, latest, updateAvailable: !!latest && isNewer(latest, current) };
 }
+/** The public npm page for a package, where an upgrade can be reviewed. */
+export function npmPackageUrl(name) {
+    return `https://www.npmjs.com/package/${name}`;
+}
+/**
+ * Build the two-line "update available" notice. The latest version is rendered
+ * as a clickable link to the package's npm page, so a capable terminal lets the
+ * user open the release with a single click while `speclaw update` remains the
+ * command that performs the upgrade.
+ *
+ * @param current - The installed version.
+ * @param latest - The newest published version.
+ * @returns The formatted, styled notice (no leading/trailing blank lines).
+ */
+export function upgradeNotice(current, latest) {
+    const latestLink = c.cyan(link(latest, npmPackageUrl(pkgName())));
+    return ("  " +
+        c.amber("⬆ speclaw ") +
+        c.muted(current + " → ") +
+        latestLink +
+        c.muted(" available") +
+        "\n" +
+        "  " +
+        c.muted("run ") +
+        c.cyan("speclaw update") +
+        c.muted(" — upgrades and applies only what's new"));
+}
 /**
- * Print a one-line "update available" notice to stderr when a newer version
- * exists. No-op for the `mcp`/`update`/`help` commands, on non-TTY stderr, or
+ * Print the "update available" notice to stderr when a newer version exists.
+ * No-op for the `mcp`/`update`/`help`/`version` commands, on non-TTY stderr, or
  * when NO_UPDATE_NOTIFIER / SPECLAW_NO_UPDATE_NOTIFIER is set. Never throws.
  *
  * @param cmd - The command that just ran (used to skip noisy contexts).
@@ -110,23 +137,13 @@ export async function maybeNotifyUpdate(cmd) {
             return;
         // `init` shows its own prominent up-front warning and ends on the clean
         // copy-paste prompt — don't append a second notice after it.
-        if (!cmd || ["mcp", "update", "init", "help", "--help", "-h"].includes(cmd))
+        if (!cmd ||
+            ["mcp", "update", "init", "help", "--help", "-h", "version", "--version", "-v"].includes(cmd))
             return;
         const { current, latest, updateAvailable } = await checkForUpdates();
         if (!updateAvailable || !latest)
             return;
-        process.stderr.write("\n" +
-            "  " +
-            c.amber("⬆ speclaw ") +
-            c.muted(current + " → ") +
-            c.cyan(latest) +
-            c.muted(" available") +
-            "\n" +
-            "  " +
-            c.muted("run ") +
-            c.cyan("speclaw update") +
-            c.muted(" — upgrades and applies only what's new") +
-            "\n\n");
+        process.stderr.write("\n" + upgradeNotice(current, latest) + "\n\n");
     }
     catch {
         /* the notifier is best-effort — never let it break a command */

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

@@ -15,17 +15,27 @@ If `lawbook/` is missing, run the `lawbook_init` tool once to create it.
 
 ## Step 1 — Understand the request and the code
 
+- **Refresh the index first.** Run `compass_index` before reasoning about the
+  code — it is incremental (unchanged files are skipped by hash), so this is
+  cheap and guarantees your decisions rest on the current graph, not a stale one.
 - 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.
-  If the index is stale or missing, run `compass_index` first.
 - Read the governing standards in `docs/standards/` (architecture, backend,
   frontend, testing) so the change complies with the project's law.
 
-## Step 2 — Pick a change name
+## Step 2 — Pick a change name and its capabilities
 
-Kebab-case, action-oriented (e.g. `add-login`, `fix-shift-overlap`). This is
-the folder under `lawbook/changes/`.
+- **Change name:** kebab-case, action-oriented (e.g. `add-login`,
+  `fix-shift-overlap`). This is the folder under `lawbook/changes/`, and it is
+  per-feature — always distinct.
+- **Capabilities:** run `lawbook_list` to see the canonical capabilities. A
+  capability is the living contract for an area of behavior — it is *not* the
+  change. When your change modifies behavior an existing capability already
+  governs, reuse that capability's **exact** name so `sync` updates its spec.
+  Introduce a new capability only as a deliberate choice for a genuinely distinct
+  area of behavior — never as a near-duplicate (`transfer` next to an existing
+  `transfers`) of one that already exists.
 
 ## Step 3 — Write the artifacts
 
@@ -34,7 +44,12 @@ 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.
-  Use normative language and testable scenarios:
+  `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
+  language and testable scenarios:
   ```markdown
   # <Capability>
 
@@ -63,7 +78,11 @@ Create under `lawbook/changes/<name>/`:
 
 Run the `lawbook_validate` tool for the change and fix every issue it reports
 (missing artifacts, non-normative specs, missing scenarios) before handing off
-to implementation.
+to implementation. Read its advisory **warnings** too: a near-duplicate
+capability name usually means you should reuse the existing capability's exact
+name, and a dropped-requirement warning means the delta should start from the
+canonical. Warnings do not block, but resolve them unless the divergence is
+intentional.
 
 ## Step 5 — Hand off
 

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

@@ -11,9 +11,12 @@ understanding and a recommended direction.
 
 ## How to explore
 
+- **Refresh the index first.** Run `compass_index` before investigating — it is
+  incremental (unchanged files skipped by hash), so it is cheap and keeps your
+  reasoning on the current graph rather than a stale one.
 - **Understand the code first.** Use `compass_recall` to find relevant code by
   meaning and `compass_explore` to read a symbol's source plus its callers and
-  callees — before grep/read. Run `compass_index` if the graph is missing.
+  callees — before grep/read.
 - **Ask sharp questions** to surface hidden assumptions, constraints, and edge
   cases. Confirm scope and non-goals.
 - **Check the law.** Read the relevant `docs/standards/` so any direction you

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

@@ -35,7 +35,11 @@ specs that become canonical describe reality, not just the original draft.
 
 4. Run the `lawbook_sync` tool for the change. It copies each
    `lawbook/changes/<name>/specs/<capability>/spec.md` over the canonical
-   `lawbook/specs/<capability>/spec.md` and reports what it promoted.
+   `lawbook/specs/<capability>/spec.md` and reports what it promoted, flagging
+   each as **created** (new capability) or **updated** (overwrote an existing
+   one). A capability you expected to update showing up as *created* means the
+   delta forked a near-duplicate — fix the name before promoting.
 
 5. Report to the user what you reconciled (or that nothing drifted) and the
-   promoted files. The change stays active — `archive` it when it's fully done.
+   promoted files (created vs updated). The change stays active — `archive` it
+   when it's fully done.

package/dist/modules/lawbook/engine.js

@@ -84,6 +84,47 @@ export function specInit(projectPath) {
     ensure("README.md", README_MD);
     return { created, alreadyExisted };
 }
+/** Names of the canonical capabilities (directories under lawbook/specs/). */
+function canonicalCapabilities(root) {
+    const specsDir = path.join(root, "specs");
+    if (!fs.existsSync(specsDir))
+        return [];
+    return fs
+        .readdirSync(specsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+/** The "### Requirement:" titles declared in a spec markdown document. */
+function requirementHeaders(markdown) {
+    const out = [];
+    for (const m of markdown.matchAll(/^###\s+Requirement:\s*(.+?)\s*$/gm))
+        out.push(m[1]);
+    return out;
+}
+/** Levenshtein edit distance between two strings (small, dependency-free). */
+function editDistance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, j) => j);
+    for (let i = 1; i < rows; i++) {
+        const curr = [i];
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[cols - 1];
+}
+/**
+ * The existing canonical capability that a name is a near-match of (edit
+ * distance ≤ 2 and not equal), or undefined when the name is exact or unrelated.
+ */
+function nearMatchCapability(name, capabilities) {
+    if (capabilities.includes(name))
+        return undefined;
+    return capabilities.find((c) => editDistance(name, c) <= 2);
+}
 /** Recursively collect every .md file under a change's specs/ directory. */
 function deltaSpecFiles(changeDir) {
     const specsDir = path.join(changeDir, "specs");
@@ -120,6 +161,7 @@ export function specValidate(projectPath, change) {
             change,
             valid: false,
             issues: [`change "${change}" not found under lawbook/changes/`],
+            warnings: [],
             deltaSpecs: [],
         };
     }
@@ -131,6 +173,10 @@ export function specValidate(projectPath, change) {
     const deltas = deltaSpecFiles(changeDir);
     if (deltas.length === 0)
         issues.push("no delta specs under specs/ (a change should specify what it changes)");
+    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");
@@ -143,21 +189,46 @@ 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);
+        if (nearMatch) {
+            warnings.push(`${rel}: capability "${capability}" is not canonical but resembles ` +
+                `"${nearMatch}" — did you mean to update it? Reuse the exact name to ` +
+                `update the existing spec instead of forking a near-duplicate.`);
+        }
+        else if (capabilities.includes(capability)) {
+            const canonicalFile = path.join(root, "specs", relFromSpecs);
+            if (fs.existsSync(canonicalFile)) {
+                const deltaReqs = new Set(requirementHeaders(content));
+                const dropped = requirementHeaders(fs.readFileSync(canonicalFile, "utf8")).filter((r) => !deltaReqs.has(r));
+                if (dropped.length > 0) {
+                    warnings.push(`${rel}: delta drops ${dropped.length} requirement(s) present in the ` +
+                        `canonical "${capability}" spec (${dropped.join("; ")}) — start the ` +
+                        `delta from the canonical unless the removal is intentional.`);
+                }
+            }
+        }
     }
     return {
         change,
         valid: issues.length === 0,
         issues,
+        warnings,
         deltaSpecs: deltas.map((f) => path.relative(projectPath, f)),
     };
 }
 /**
  * Promote a change's delta specs into the canonical specs/, overwriting the
- * file for each affected capability.
+ * file for each affected capability. Each promoted path is also classified as
+ * `created` (no canonical file existed) or `updated` (one was overwritten) so an
+ * unintended new capability is visible in the result — a pure path check that
+ * keeps this a deterministic, code-blind copy.
  *
  * @param projectPath - Absolute path to the project root.
  * @param change - Change name (folder under lawbook/changes/).
- * @returns The change name and the list of promoted spec paths.
+ * @returns The change name, the promoted spec paths, and the created/updated split.
  * @throws If the change directory does not exist.
  */
 export function specSync(projectPath, change) {
@@ -167,8 +238,10 @@ export function specSync(projectPath, change) {
         throw new Error(`change "${change}" not found`);
     const changeSpecs = path.join(changeDir, "specs");
     const promoted = [];
+    const created = [];
+    const updated = [];
     if (!fs.existsSync(changeSpecs))
-        return { change, promoted };
+        return { change, promoted, created, updated };
     const walk = (dir) => {
         for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
             const full = path.join(dir, e.name);
@@ -177,14 +250,17 @@ export function specSync(projectPath, change) {
             else if (e.name.endsWith(".md")) {
                 const rel = path.relative(changeSpecs, full);
                 const dest = path.join(root, "specs", rel);
+                const existed = fs.existsSync(dest);
                 fs.mkdirSync(path.dirname(dest), { recursive: true });
                 fs.copyFileSync(full, dest);
-                promoted.push(path.join("lawbook/specs", rel));
+                const promotedPath = path.join("lawbook/specs", rel);
+                promoted.push(promotedPath);
+                (existed ? updated : created).push(promotedPath);
             }
         }
     };
     walk(changeSpecs);
-    return { change, promoted };
+    return { change, promoted, created, updated };
 }
 /**
  * Deterministic completeness checks that gate archiving a change. Returns the
@@ -256,13 +332,13 @@ 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 } = specSync(projectPath, change);
+    const { promoted, created, updated } = specSync(projectPath, change);
     const archiveDir = path.join(root, "changes", "archive", `${date}-${change}`);
     fs.mkdirSync(path.dirname(archiveDir), { recursive: true });
     if (fs.existsSync(archiveDir))
         throw new Error(`archive target already exists: ${archiveDir}`);
     fs.renameSync(changeDir, archiveDir);
-    return { change, promoted, archivedTo: path.relative(projectPath, archiveDir) };
+    return { change, promoted, created, updated, archivedTo: path.relative(projectPath, archiveDir) };
 }
 /**
  * List the spec workspace: active changes, archived changes, and canonical

package/dist/modules/lawbook/register.js

@@ -29,14 +29,14 @@ export function registerSpec(server) {
         inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
     }, async ({ projectPath }) => text(specList(projectPath)));
     server.registerTool("lawbook_validate", {
-        description: "Validate a change's artifacts: proposal.md and tasks.md present, and delta specs use normative language (SHALL/MUST), '### Requirement:' headers, and '#### Scenario:' acceptance criteria. Returns the issues to fix. Used by the draft/build commands before proceeding.",
+        description: "Validate a change's artifacts: proposal.md and tasks.md present, and delta specs use normative language (SHALL/MUST), '### Requirement:' headers, and '#### Scenario:' acceptance criteria. Returns the blocking issues to fix plus advisory (non-blocking) warnings — a capability name that resembles an existing canonical one, or requirements dropped versus the canonical. Used by the draft/build commands before proceeding.",
         inputSchema: {
             projectPath: z.string().describe("Absolute path to the project"),
             change: z.string().describe("Change name (folder under lawbook/changes/)"),
         },
     }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
     server.registerTool("lawbook_sync", {
-        description: "Promote a change's delta specs into the canonical lawbook/specs/ (per capability), without archiving. Backs the `sync` command.",
+        description: "Promote a change's delta specs into the canonical lawbook/specs/ (per capability), without archiving. Reports each promoted spec as created (new capability) or updated (overwrote an existing one). Backs the `sync` command.",
         inputSchema: {
             projectPath: z.string().describe("Absolute path to the project"),
             change: z.string().describe("Change name (folder under lawbook/changes/)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -41,6 +41,8 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "check": "prettier --check . && eslint .",
+    "pretest": "tsc -p tsconfig.test.json && node scripts/prep-test-assets.mjs",
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-exclude='dist-test/test/**' --test-coverage-exclude='dist/**' 'dist-test/test/**/*.test.js'",
     "prepublishOnly": "npm run build"
   },
   "engines": {