@esneiderbravo/speclaw 0.1.13 → 0.1.15

package/dist/cli/commands/update.js

@@ -43,6 +43,22 @@ const MIGRATIONS = [
             "'test kind does not yet apply' escape hatch. If the section is missing, add it.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.1.14",
+        describe: "Real-data-write stop condition in the constitution (personalized files)",
+        agentPrompt: "- Add a stop condition, at the same tier as deletes/force-push, that verification " +
+            "must NOT create/update/delete the user's real data (a production or development " +
+            "database, or files holding real data) — including setting up or tearing down test " +
+            "data or running raw store commands (e.g. direct SQL) against a live store. " +
+            "Verification runs against an isolated/throwaway store (a temporary copy, an in-memory " +
+            "database, a dedicated test store, or a rolled-back transaction); snapshot-and-restore " +
+            "is not sanctioned. If a real-store write is genuinely unavoidable, stop and get " +
+            "explicit authorization first — a backup is not a substitute.\n" +
+            "- Apply it in CLAUDE.md and AGENTS.md (the Rule 6 / stop-conditions list), in " +
+            "docs/standards/base-standards.md (the 'ask before irreversible actions' bullet), and " +
+            "in docs/standards/testing-standards.md (the 'Manual & end-to-end verification' section).\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/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/foundation/assets/AGENTS.template.md

@@ -35,7 +35,10 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    [`docs/standards/conventions.md`](docs/standards/conventions.md).
 6. **Use the skills.** `ai-specs/` is the canonical home for skills, commands,
    and subagents, mirrored to each IDE directory via symlinks.
-7. **Ask before irreversible or outward-facing actions.**
+7. **Ask before irreversible or outward-facing actions** — destructive commands;
+   writing to a real data store (DB rows or files with real user data, including
+   for tests — verify against an isolated/throwaway store); publishing
+   reviews/tickets/comments.
 
 ## The standards (the law, in detail)
 

package/dist/modules/foundation/assets/CLAUDE.template.md

@@ -81,5 +81,7 @@ task, use it — do not improvise a parallel process.
 ## Rule 6 — Stop conditions
 
 Stop and ask the user before: destructive operations (deletes, force-push,
-schema drops), publishing anything outward-facing (PR reviews, tickets,
-comments), or any action that contradicts a standard.
+schema drops), writing to a real data store (DB rows or files holding real user
+data — including to set up or tear down test data; verification runs against an
+isolated/throwaway store instead), publishing anything outward-facing (PR
+reviews, tickets, comments), or any action that contradicts a standard.

package/dist/modules/foundation/assets/docs/standards/base-standards.template.md

@@ -45,8 +45,9 @@ bodies. Match what the repo does; do not impose a language it doesn't use.
 - Code reads like its neighbors (naming, structure, idioms).
 - Report outcomes faithfully: if a gate fails, say so with the output; never
   claim a success you did not observe.
-- Ask before irreversible or outward-facing actions (destructive commands,
-  publishing reviews/tickets/comments).
+- Ask before irreversible or outward-facing actions (destructive commands;
+  writing to a real data store — DB rows or files holding real user data,
+  including to set up or tear down test data; publishing reviews/tickets/comments).
 
 <!-- speclaw init: add any project-specific base rules the analysis surfaced. -->
 {{base_standards_extra}}

package/dist/modules/foundation/assets/docs/standards/testing-standards.template.md

@@ -29,6 +29,15 @@ suppressing a linter or deleting a test.
 
 - When a change affects runtime behavior and it's feasible, verify it works by
   exercising the endpoint/UI — don't assume green CI covers everything.
+- **Verification never touches real data.** Run it against an isolated store — a
+  temporary copy, an in-memory database, a dedicated test store, or a rolled-back
+  transaction — or against pure logic with fixtures. Never create/update/delete
+  the user's real data (a production or development database, or files holding
+  real data), and never run raw store commands (e.g. direct SQL) against a live
+  store, to prove a change. Snapshot-and-restore is not sanctioned. If a
+  real-store write is genuinely unavoidable, stop and get explicit authorization
+  first — a backup is not a substitute (see the stop conditions in the
+  constitution).
 - The mandatory spec task steps
   ([`lawbook.md`](lawbook.md)) define which manual checks
   the agent must execute itself.

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

@@ -43,6 +43,22 @@ Run them yourself and report real output. A red gate blocks completion.
 Exercise the behavior (endpoint/UI/CLI) yourself where feasible — do not
 delegate manual testing to the user. Record what you verified.
 
+**Verification is isolated by construction — it never touches real data.** Run it
+against an ephemeral or throwaway store: a temporary copy, an in-memory database
+(`:memory:`), a dedicated test store, or inside a transaction that is rolled
+back — best of all, verify pure/domain logic with fixtures and no store at all.
+Do **not** create, update, or delete the user's real data (a production or
+development database, or files holding real data) as a side effect of proving a
+change, and do **not** run raw store commands (e.g. direct SQL) against a live
+store. Snapshot-and-restore is not a sanctioned method — a stray write slips past
+the restore.
+
+If isolation is genuinely impossible and a real-store write is unavoidable,
+**stop and ask first** — state exactly what you will write and to which store —
+and proceed only after explicit authorization. A backup is not a substitute for
+authorization. Record in the report how verification stayed isolated (or the
+authorization you obtained).
+
 ## Step 5 — Write the discipline reports (mandatory)
 
 Record the evidence of testing under `lawbook/changes/<name>/reports/`, one file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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": {