create-cadmo 0.2.0 → 0.4.0

package/README.md

@@ -14,6 +14,6 @@ Drops into the current directory, never overwriting anything:
 - `cadmo/plan.md` — the internal route: tasks, constraints, how to validate
 - `cadmo/decision.md` — architecture decisions with a "when to reconsider" trigger
 - `cadmo/spec-drift.mjs` + a ready CI workflow — **specs must change with the code they watch** (the drift guard)
-- `.claude/commands/cadmo-*.md` — `/cadmo-gate`, `/cadmo-spec`, `/cadmo-done` slash commands (when Claude Code is detected, or `--claude`)
+- `.claude/commands/cadmo-*.md` — `/cadmo-gate`, `/cadmo-spec`, `/cadmo-done` slash commands (when Claude Code is detected, or `--claude`). **Pick one source for the commands:** if you install the [Cadmo plugin](https://github.com/tiagotorres91/cadmo) (`/plugin install cadmo@cadmo`, which provides `/cadmo:gate` etc.), run the scaffolder with `--no-claude` — otherwise you'll have both spellings.
 
 The method, docs and protocols: **https://github.com/tiagotorres91/cadmo**

package/index.js

@@ -29,6 +29,7 @@ if (args.includes('--help') || args.includes('-h')) {
     cadmo/plan.md                   the internal route: tasks, constraints, validation
     cadmo/decision.md               ADR with a "when to reconsider" trigger
     cadmo/spec-drift.mjs            the drift guard: specs must change with the code they watch
+    cadmo/cadmo-grammar.mjs         the shared front-matter/glob grammar the guard imports
     cadmo/spec-drift-workflow.yml   ready CI workflow (move into .github/workflows/)
     .claude/commands/cadmo-*.md     (when Claude Code is detected, or --claude)
 
@@ -46,6 +47,7 @@ const FILES = [
   ['spec.md', path.join('cadmo', 'spec.md')],
   ['plan.md', path.join('cadmo', 'plan.md')],
   ['decision.md', path.join('cadmo', 'decision.md')],
+  ['cadmo-grammar.mjs', path.join('cadmo', 'cadmo-grammar.mjs')],
   ['spec-drift.mjs', path.join('cadmo', 'spec-drift.mjs')],
   ['spec-drift-workflow.yml', path.join('cadmo', 'spec-drift-workflow.yml')],
 ];
@@ -83,7 +85,7 @@ for (const [src, dest] of plan) {
 
 console.log(`\n  ${placed} file(s) ${DRY ? 'would be created' : 'created'}, ${skipped} kept.\n`);
 if (!hasClaude && !NO_CLAUDE) {
-  console.log('  (No CLAUDE.md/.claude detected — run with --claude to also install /cadmo-* slash commands.)');
+  console.log('  (No CLAUDE.md/.claude folder detected — run: npm create cadmo -- --claude   (the -- matters: npm swallows flags without it) to also install the /cadmo-* slash commands.)');
 }
 console.log('  Next steps:');
 console.log('  1. Fill in AGENTS.md — the local map your AI pair reads first');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cadmo",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Scaffold the Cadmo method into your project \u2014 a right-sized method for building software with AI as your pair.",
   "keywords": [
     "cadmo",
@@ -29,7 +29,7 @@
     "create-cadmo": "index.js"
   },
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "scripts": {
     "test": "node --test"

package/templates/AGENTS.md

@@ -15,17 +15,18 @@
 ## Where things live
 - Specs / decisions: <path>
 - Plans: <path>
-- Demands / task board: <where>
+- Demands / task board: <where — GitHub issues works; "none yet" is honest>
 
 ## How to verify (the harness — run before saying "done")
 - Build/type-check: `<command>`
 - Tests: `<command>`
 - End-to-end / smoke: `<command>`
-- Staging URL: <url>  ·  Production: <url>
+- Staging URL: <url — or "none: ships as a package / binary / store build">  ·  Production: <url or delivery channel>
 
 ## Gates
 - Plan approved before building; production ships only with explicit human approval.
 - <any project-specific rule or gotcha>
 
 ## The method
-Opening choreography, definition of done, the layers — see the Cadmo method (link).
+Opening choreography, definition of done, the layers — see the Cadmo method:
+https://github.com/tiagotorres91/cadmo/blob/main/docs/method.md

package/templates/cadmo-grammar.mjs

@@ -0,0 +1,88 @@
+// cadmo-grammar — THE single grammar for Cadmo front matter and watch-globs.
+// Every consumer (spec-drift, cadmo-score, the plugin's Stop hook, the scaffolded
+// copy) uses THIS logic; the copies are byte-identical and guarded by
+// scripts/check-template-sync.sh. Round-4 review found three divergent
+// reimplementations (one carrying an already-fixed globstar bug) — hence this file.
+//
+// Accepted `watches:` forms (all equivalent):
+//   watches:            |  watches:          |  watches: [a/**, b.py]  |  watches: a/**
+//     - a/**            |  - a/**            |
+//     - b.py            |  - b.py            |
+// (indented block, unindented block, inline array, single inline value)
+
+export function frontMatter(text) {
+  if (!text.startsWith('---')) return null;
+  const end = text.indexOf('\n---', 3);
+  if (end < 0) return null;
+  return { fm: text.slice(3, end), end };
+}
+
+function unquote(s) {
+  return s.trim().replace(/^["']|["']$/g, '');
+}
+
+export function parseWatches(text) {
+  const parsed = frontMatter(text);
+  if (!parsed) return null;
+  const lines = parsed.fm.split(/\r?\n/);
+  const watches = [];
+  let inWatches = false;
+  for (const line of lines) {
+    const head = line.match(/^watches:\s*(.*)$/);
+    if (head) {
+      inWatches = true;
+      const inline = head[1].trim();
+      if (inline.startsWith('[')) {
+        for (const part of inline.replace(/^\[|\]\s*$/g, '').split(',')) {
+          const v = unquote(part);
+          if (v) watches.push(v);
+        }
+        inWatches = false; // inline array is complete on this line
+      } else if (inline) {
+        watches.push(unquote(inline)); // single inline value
+        inWatches = false;
+      }
+      continue;
+    }
+    if (inWatches) {
+      const item = line.match(/^\s*-\s+(.+?)\s*$/); // indented OR unindented list item
+      if (item) watches.push(unquote(item[1]));
+      else if (line.trim() !== '') inWatches = false; // next key ends the block
+    }
+  }
+  return watches.length ? watches : null;
+}
+
+export function parseReviewed(text) {
+  const parsed = frontMatter(text);
+  if (!parsed) return null;
+  for (const line of parsed.fm.split(/\r?\n/)) {
+    const m = line.match(/^reviewed:\s*(\S+)\s*$/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// Glob -> RegExp. `*` matches within one path segment; `**` matches zero or more
+// segments (gitignore semantics: src/**/auth.js matches src/auth.js).
+// Zero-backslash implementation (escaping via char classes / fromCharCode).
+const BS = String.fromCharCode(92);
+export function globToRegex(glob) {
+  let esc = '';
+  for (const ch of glob) {
+    if (ch === '*' || ch === '/') esc += ch;
+    else if ('.+^$(){}|[]?'.includes(ch) || ch === BS) esc += BS + ch;
+    else esc += ch;
+  }
+  esc = esc.split('**').join('__DSTAR__');
+  esc = esc.split('*').join('[^/]*');
+  esc = esc.split('/__DSTAR__/').join('/(?:.*/)?'); // a/**/b -> a/b and a/x/y/b
+  esc = esc.split('__DSTAR__/').join('(?:.*/)?');   // **/b  -> b and x/b
+  esc = esc.split('/__DSTAR__').join('(?:/.*)?');   // a/**  -> a and a/x
+  esc = esc.split('__DSTAR__').join('.*');          // bare **
+  return new RegExp('^' + esc + '$');
+}
+
+export function anyMatch(watches, file) {
+  return watches.some((w) => globToRegex(w).test(file));
+}

package/templates/claude-commands/cadmo-done.md

@@ -1,3 +1,6 @@
+---
+description: Run the definition of done honestly — checked against evidence (run the commands), not memory
+---
 # /cadmo-done — the definition of done, checked honestly
 
 Run the definition of done for: **$ARGUMENTS** (or the work we just finished).
@@ -8,7 +11,7 @@ Check each item **against evidence, not memory** — run the commands, don't ass
 - [ ] **Tested functionally** — the real flow (browser, curl, CLI run), not just linters
 - [ ] Validated in staging before production (when there is one)
 - [ ] Acceptance criteria from the spec/plan — checked one by one, quoted
-- [ ] Spec updated if a rule changed (same commit) — run `node cadmo/spec-drift.mjs --base origin/main` if present
+- [ ] Spec updated if a rule changed (same commit) — run `node cadmo/spec-drift.mjs` if present (no --base needed: it auto-resolves, remote or not)
 - [ ] Anything untested? Say it explicitly: "I didn't test X"
 - [ ] Touched auth/input/data/secrets? → flag that an adversarial security pass is due before shipping
 

package/templates/claude-commands/cadmo-gate.md

@@ -1,3 +1,6 @@
+---
+description: Open a value gate — is this worth building? (a 5-line business case before any spec)
+---
 # /cadmo-gate — open a value gate
 
 Open a value gate for: **$ARGUMENTS**

package/templates/claude-commands/cadmo-spec.md

@@ -1,3 +1,6 @@
+---
+description: Write the spec — acceptance criteria first, for the client to validate before any code
+---
 # /cadmo-spec — write the spec, criteria first
 
 Write the spec for: **$ARGUMENTS**

package/templates/plan.md

@@ -1,21 +1,26 @@
-# <Demand name> — plan (internal)
-
-Pairs with `spec.md` (acceptance criteria live there — don't repeat them).
-
-## Objective
-What changes in the world when this is done (1–3 lines).
-
-## Investigation (optional)
-What was tried/considered before and why it was discarded (3–6 lines) — avoids re-investigating dead ends.
-
-## Context & constraints
-Current state, decisions already made, what NOT to change.
-
-## Technical plan
-Files/tables/endpoints touched; approach; alternatives discarded.
-
-## Tasks
-- [ ] Small, verifiable (status kept here — any session resumes without getting lost)
-
-## How to validate
-Commands/flows that prove the acceptance criteria (build, tests, e2e, real manual flow).
+# <Demand name> — plan (internal)
+
+For new-and-relevant work this pairs with `spec.md`; for a standard 3+ step fix it stands alone.
+
+## Objective
+What changes in the world when this is done (1–3 lines).
+
+## Acceptance criteria
+- [ ] Observable and specific ("login returns a 24h JWT", not "user logs in")
+- [ ] If there IS a separate `spec.md`, the criteria live THERE — don't duplicate; delete this section.
+      If this plan stands alone (no spec), this is their home — criteria before code, always.
+
+## Investigation (optional)
+What was tried/considered before and why it was discarded (3–6 lines) — avoids re-investigating dead ends.
+
+## Context & constraints
+Current state, decisions already made, what NOT to change.
+
+## Technical plan
+Files/tables/endpoints touched; approach; alternatives discarded.
+
+## Tasks
+- [ ] Small, verifiable (status kept here — any session resumes without getting lost)
+
+## How to validate
+Commands/flows that prove the acceptance criteria (build, tests, e2e, real manual flow).

package/templates/spec-drift-workflow.yml

@@ -1,12 +1,15 @@
 # Example workflow — copy to .github/workflows/spec-drift.yml in your project.
-# Fails a PR when a file watched by a spec changes and the spec doesn't change with it.
-# Escape hatch (audited, never silent): write "spec-drift: skip — <reason>" in the PR body.
+# Fails when a file watched by a spec changes and the spec doesn't change with it.
+# Works on pull_request AND on push (so it fires even if you ship straight to main).
+# Audited escape hatch (never silent): "spec-drift: skip -- <reason>" in the PR body
+# (pull_request runs) or in the latest commit message (push runs).
 name: spec-drift
 on:
   pull_request:
+  push:
+    branches: [main]
 jobs:
   drift:
-    if: "${{ !contains(github.event.pull_request.body, 'spec-drift: skip') }}"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -16,4 +19,24 @@ jobs:
         with:
           node-version: "20"
       - name: specs must change with the code they govern
-        run: node cadmo/spec-drift.mjs --base origin/${{ github.base_ref }}
+        env:
+          # env var, never inline interpolation — a PR body is attacker-controlled text
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            if printf '%s' "$PR_BODY" | grep -qi 'spec-drift: skip'; then
+              echo "spec-drift: skip found in the PR body — skipping."
+              exit 0
+            fi
+            BASE="origin/${{ github.base_ref }}"
+          else
+            if git log -1 --format=%B | grep -qi 'spec-drift: skip'; then
+              echo "spec-drift: skip found in commit message — skipping."
+              exit 0
+            fi
+            BASE="${{ github.event.before }}"
+            # first push of a branch/repo: event.before is all-zeros -> last commit -> empty tree
+            git cat-file -e "${BASE}^{commit}" 2>/dev/null \
+              || BASE="$(git rev-parse HEAD~1 2>/dev/null || echo 4b825dc642cb6eb9a060e54bf8d69288fbee4904)"
+          fi
+          node cadmo/spec-drift.mjs --base "$BASE"

package/templates/spec-drift.mjs

@@ -1,39 +1,86 @@
 #!/usr/bin/env node
 /*
- * spec-drift — the rule that keeps documentation honest:
- * a spec declares which files implement it; if those files change and the spec
- * doesn't change in the same diff, the check fails.
+ * spec-drift — the rule that keeps documentation honest.
  *
- * No dependencies. How it works:
- *   1. Scans the repo for .md files with a `watches:` list in their front matter.
- *   2. Diffs the current branch against --base (default: origin/main).
- *   3. For each spec: if a watched file changed and the spec didn't → DRIFT.
+ * Two layers, both zero-dependency:
+ *
+ *   DRIFT (v1): a spec declares which files implement it (`watches:`); if those
+ *   files change in the diff and the spec doesn't change in the same diff → DRIFT.
+ *   Cheap, but shallow: co-change in a diff proves the spec was TOUCHED, not that
+ *   its content is still TRUE.
+ *
+ *   SUSPECT (v2, opt-in): a "reviewed-state" layer. `--stamp <spec>` records a
+ *   sha256 over the current content of the spec's watched files as `reviewed: <hash>`
+ *   — a human affirming "I re-read this code and this spec is still true." The check
+ *   recomputes that hash; a mismatch reports SUSPECT even if the spec was edited.
+ *   Honesty note: the hash proves bytes unchanged, not semantic truth — a human
+ *   still has to actually re-read before re-stamping. The full-length sha256 is
+ *   an honesty marker, not an adversarial control: for adversarial assurance use
+ *   signed tags / Sigstore (see cadmo-validate's N2/N3 levels).
+ *
+ * SUSPECT scoping ("checks activate by surface touched"): by default, SUSPECT only
+ * fires for specs whose WATCHED SET intersects the current diff — an innocent
+ * README-only PR must not fail CI for a stamp a previous merge skipped. Use
+ * `--suspect-all` for the full repo-state check (push-to-main / scheduled runs).
+ *
+ * A spec WITHOUT a `reviewed:` key gets the DRIFT check only — SUSPECT is opt-in
+ * (right-sizing: pay the re-read discipline only where it earns its keep).
+ *
+ * Grammar (front matter forms, glob semantics) lives in ./cadmo-grammar.mjs —
+ * the SINGLE grammar shared by spec-drift, cadmo-score and the plugin hook.
  *
  * Usage:
- *   node spec-drift.mjs [--base origin/main] [--dir .]
+ *   node spec-drift.mjs [--base <ref>] [--dir .] [--suspect-all]
+ *   node spec-drift.mjs --stamp <spec.md> [--dir .]
  *
- * Spec front matter example:
- *   ---
- *   watches:
- *     - src/billing/**
- *     - api/invoices.py
- *   ---
+ * With no --base, the first existing ref wins: origin/main → main (when you're
+ * on a different branch) → HEAD~1 → the empty tree (single-commit repo: the
+ * whole initial commit is the diff). A solo repo with no remote just works.
  *
  * Escape hatch (audited, not silent): if a change genuinely doesn't alter any
- * documented rule, say so where reviewers can see it — e.g. run the CI step
- * only when the PR body does NOT contain "spec-drift: skip — <reason>".
+ * documented rule, say so where reviewers can see it — the shipped workflow
+ * honors "spec-drift: skip — <reason>" in the PR body (pull_request runs) or
+ * in the latest commit message (push runs).
  */
 import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { frontMatter, parseWatches as watchesOf, parseReviewed as reviewedOf, globToRegex } from './cadmo-grammar.mjs';
 
+const BS = String.fromCharCode(92);
 const args = process.argv.slice(2);
 function opt(name, fallback) {
   const i = args.indexOf(name);
   return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
 }
-const BASE = opt('--base', 'origin/main');
 const ROOT = path.resolve(opt('--dir', '.'));
+// sha of git's empty tree — diffing against it means "everything is new"
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+function refExists(ref) {
+  try {
+    execFileSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { cwd: ROOT, stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch { return false; }
+}
+function resolveBase() {
+  if (refExists('origin/main')) return 'origin/main';
+  let branch = '';
+  try {
+    branch = execFileSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { /* detached HEAD */ }
+  if (branch !== 'main' && refExists('main')) return 'main';
+  if (refExists('HEAD~1')) return 'HEAD~1';
+  return EMPTY_TREE;
+}
+const BASE_GIVEN = opt('--base', null);
+const BASE = BASE_GIVEN || resolveBase();
+const STAMP = opt('--stamp', null);
+const SUSPECT_ALL = args.includes('--suspect-all');
+if (args.includes('--stamp') && !STAMP) {
+  console.error('spec-drift --stamp: missing <spec.md> argument.');
+  process.exit(2);
+}
 
 // --- collect specs that declare `watches:` in front matter ---
 function* mdFiles(dir) {
@@ -45,56 +92,113 @@ function* mdFiles(dir) {
   }
 }
 
-function parseWatches(file) {
-  const text = fs.readFileSync(file, 'utf8');
-  if (!text.startsWith('---')) return null;
-  const end = text.indexOf('\n---', 3);
-  if (end < 0) return null;
-  const fm = text.slice(3, end);
-  const lines = fm.split('\n');
-  const watches = [];
-  let inWatches = false;
-  for (const line of lines) {
-    if (/^watches:\s*$/.test(line)) { inWatches = true; continue; }
-    if (inWatches) {
-      const m = line.match(/^\s+-\s+(.+?)\s*$/);
-      if (m) watches.push(m[1].replace(/^["']|["']$/g, ''));
-      else if (!/^\s/.test(line)) inWatches = false;
-    }
+const readSpec = (file) => fs.readFileSync(file, 'utf8');
+
+// Add or update a top-level `reviewed:` key, preserving everything else
+// (including the file's EOL style — a CRLF file must not gain a lone LF line).
+function setReviewed(text, hash) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const parsed = frontMatter(text);
+  const rest = text.slice(parsed.end); // '\n---' … onwards
+  let lines = parsed.fm.split(/\r?\n/);
+  let found = false;
+  lines = lines.map((l) => {
+    if (/^reviewed:\s*/.test(l)) { found = true; return `reviewed: ${hash}`; }
+    return l;
+  });
+  if (!found) {
+    if (lines.length && lines[lines.length - 1] === '') lines[lines.length - 1] = `reviewed: ${hash}`;
+    else lines.push(`reviewed: ${hash}`);
   }
-  return watches.length ? watches : null;
+  return '---' + lines.join(eol) + rest;
 }
 
-// --- minimal glob → regex (supports ** and *) ---
-function globToRegex(glob) {
-  // zero-backslash implementation: escape specials via char classes, never via backslash
-  const BS = String.fromCharCode(92);
-  let esc = '';
-  for (const ch of glob) {
-    if (ch === '*' || ch === '/') esc += ch;
-    else if ('.+^$(){}|[]?'.includes(ch) || ch === BS) esc += BS + ch;
-    else esc += ch;
+// --- reviewed-state hashing ---
+// Line endings are normalized so a CRLF working tree (git autocrlf) and the
+// LF-stored HEAD blob hash identically. Watched files are text source.
+function norm(buf) {
+  return buf.toString('utf8').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+function matched(watches, files) {
+  const regexes = watches.map(globToRegex);
+  return files.filter((f) => regexes.some((r) => r.test(f))).sort();
+}
+
+function hashWatchedDisk(watches) {
+  const tracked = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8' }).split('\n').filter(Boolean);
+  const h = crypto.createHash('sha256');
+  for (const f of matched(watches, tracked)) {
+    h.update(f); h.update('\n');
+    h.update(norm(fs.readFileSync(path.join(ROOT, f))));
+  }
+  return h.digest('hex');
+}
+
+function hashWatchedHead(watches) {
+  const tracked = execFileSync('git', ['ls-tree', '-r', 'HEAD', '--name-only'], { cwd: ROOT, encoding: 'utf8' }).split('\n').filter(Boolean);
+  const h = crypto.createHash('sha256');
+  for (const f of matched(watches, tracked)) {
+    h.update(f); h.update('\n');
+    h.update(norm(execFileSync('git', ['show', `HEAD:${f}`], { cwd: ROOT })));
+  }
+  return h.digest('hex');
+}
+
+// --- --stamp mode: re-affirm a spec after re-reading its watched files ---
+if (STAMP) {
+  const specPath = path.resolve(ROOT, STAMP);
+  if (!fs.existsSync(specPath)) {
+    console.error(`spec-drift --stamp: no such spec: ${STAMP}`);
+    process.exit(2);
   }
-  esc = esc.split('**').join('__DSTAR__');
-  esc = esc.split('*').join('[^/]*');
-  esc = esc.split('__DSTAR__').join('.*');
-  return new RegExp('^' + esc + '$');
+  const watches = watchesOf(readSpec(specPath));
+  if (!watches) {
+    console.error(`spec-drift --stamp: ${STAMP} has no \`watches:\` front matter — nothing to stamp.`);
+    process.exit(2);
+  }
+  const hash = hashWatchedDisk(watches);
+  // Footgun guard: stamping uncommitted content records a hash HEAD can never match.
+  try {
+    const head = hashWatchedHead(watches);
+    if (head !== hash) {
+      console.error('spec-drift --stamp: WARNING — watched files differ between working tree and HEAD; you are stamping UNCOMMITTED content. Commit the watched changes (or stamp after committing) or the check will report SUSPECT.');
+    }
+  } catch { /* no HEAD yet (fresh repo) — nothing to compare */ }
+  fs.writeFileSync(specPath, setReviewed(readSpec(specPath), hash));
+  console.log(`spec-drift: stamped ${STAMP} — reviewed: ${hash}`);
+  process.exit(0);
 }
 
 // --- changed files vs base ---
+// The empty tree has no merge base, so it gets a two-dot diff; refs get three-dot.
+const RANGE = BASE === EMPTY_TREE ? [BASE, 'HEAD'] : [`${BASE}...HEAD`];
 let changed;
 try {
-  changed = execFileSync('git', ['diff', '--name-only', `${BASE}...HEAD`], { cwd: ROOT, encoding: 'utf8' })
+  changed = execFileSync('git', ['diff', '--name-only', ...RANGE], { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
     .split('\n').filter(Boolean);
+  if (!BASE_GIVEN) {
+    console.log(`spec-drift: no --base given — diffing against ${BASE === EMPTY_TREE ? 'the empty tree (single-commit repo: the whole initial commit)' : BASE}.`);
+  }
 } catch (e) {
-  console.error(`spec-drift: cannot diff against ${BASE} — ${e.message}`);
+  const detail = (e.stderr ? e.stderr.toString() : e.message).split(/\r?\n/).find(Boolean) || '';
+  console.error(`spec-drift: cannot diff against ${BASE} — ${detail}`);
+  console.error('spec-drift: is this a git repository with at least one commit? Pass --base <ref> to pick the comparison point explicitly.');
   process.exit(2);
 }
 
 const specs = [];
 for (const f of mdFiles(ROOT)) {
-  const watches = parseWatches(f);
-  if (watches) specs.push({ spec: path.relative(ROOT, f).split(String.fromCharCode(92)).join('/'), watches });
+  const text = readSpec(f);
+  const watches = watchesOf(text);
+  const rel = path.relative(ROOT, f).split(BS).join('/');
+  if (watches) {
+    specs.push({ spec: rel, watches, reviewed: reviewedOf(text) });
+  } else if (text.startsWith('<!--') && /^watches:/m.test(text)) {
+    // the template ships with a leading HTML comment; front matter placed after
+    // it is invisible to the grammar — a spec that LOOKS guarded but isn't.
+    console.error(`WARNING: ${rel} has a watches: line but does not start with --- (front matter must be the very first bytes — delete the leading comment). This spec is NOT being checked.`);
+  }
 }
 
 if (!specs.length) {
@@ -104,17 +208,30 @@ if (!specs.length) {
 
 const changedSet = new Set(changed);
 let drift = 0;
-for (const { spec, watches } of specs) {
+let suspect = 0;
+for (const { spec, watches, reviewed } of specs) {
   const regexes = watches.map(globToRegex);
-  const hits = changed.filter(c => regexes.some(r => r.test(c)));
+  const hits = changed.filter((c) => regexes.some((r) => r.test(c)));
   if (hits.length && !changedSet.has(spec)) {
     drift++;
     console.error(`DRIFT: ${hits.join(', ')} changed, but ${spec} (which watches ${watches.join(', ')}) did not change in this diff.`);
   }
+  // SUSPECT: opt-in via `reviewed:`, and diff-scoped unless --suspect-all —
+  // only a diff that touches this spec's watched surface puts it on trial here.
+  if (reviewed && (SUSPECT_ALL || hits.length)) {
+    const now = hashWatchedHead(watches);
+    if (now !== reviewed) {
+      suspect++;
+      console.error(`SUSPECT: ${spec} was reviewed at ${reviewed.slice(0, 12)}… but its watched files hash ${now.slice(0, 12)}… at HEAD — the code changed since the last review. Re-read the watched files, then re-run: node spec-drift.mjs --stamp ${spec}`);
+    }
+  }
 }
 
-if (drift) {
-  console.error(`\nspec-drift: ${drift} spec(s) out of sync. Update the spec in the same change — or state why no documented rule changed (visibly, where reviewers can see it).`);
+if (drift || suspect) {
+  const parts = [];
+  if (drift) parts.push(`${drift} drifting`);
+  if (suspect) parts.push(`${suspect} suspect`);
+  console.error(`\nspec-drift: ${parts.join(', ')}. Update the spec in the same change (or state why no documented rule changed, visibly); re-stamp any SUSPECT spec after actually re-reading its watched files — the hash matches bytes, only you can vouch for the meaning.`);
   process.exit(1);
 }
 console.log(`spec-drift: ${specs.length} spec(s) checked against ${changed.length} changed file(s) — in sync ✓`);

package/templates/spec.md

@@ -1,24 +1,38 @@
-# Spec — <name>
-
-**Status:** draft — awaiting validation (<who>)  ·  **Demand:** <link/id>
-
-## Goal & context
-The business problem and what changes in the world (2–5 lines, in the client's language).
-(Relevant work already passed the value gate — its success metric becomes an acceptance criterion here.)
-
-## Acceptance criteria
-- [ ] Simple ones in free form
-- [ ] Critical ones (money / data / integration / security) in EARS:
-      WHEN <trigger>, THE SYSTEM SHALL <behavior>
-
-## Data (AI features only)
-Source, owner, access, quality/bias, corpus refresh plan.
-
-## Risks (critical or AI demands only)
-Risk → response. For AI: corpus drift, provider API change, cost, regulation.
-
-## Out of scope
-What this delivery does NOT cover (controlled expectations).
-
-## Impact on stable specs
-Which sections of the system/domain specs will be updated on delivery (the absorption).
+<!-- To enforce this spec against code, add real YAML front matter as the VERY FIRST lines:
+---
+watches:
+  - src/the-area-this-governs/**
+  - api/the-endpoint.py
+---
+Then spec-drift fails any change to those files that doesn't update this spec. -->
+
+# Spec — <name>
+
+**Status:** draft — awaiting validation (<who>)  ·  **Demand:** <link/id>
+
+## Goal & context
+The business problem and what changes in the world (2–5 lines, in the client's language).
+(Relevant work already passed the value gate — its success metric becomes an acceptance criterion here.)
+
+## Acceptance criteria
+- [ ] Simple ones in free form
+- [ ] Critical ones (money / data / integration / security) in EARS:
+      WHEN <trigger>, THE SYSTEM SHALL <behavior>
+
+## Data (AI features only)
+Source, owner, access, quality/bias, corpus refresh plan.
+
+## Risks (critical or AI demands only)
+Risk → response. For AI: corpus drift, provider API change, cost, regulation.
+
+## Out of scope
+What this delivery does NOT cover (controlled expectations).
+
+## Impact on stable specs
+Which sections of the system/domain specs will be updated on delivery (the absorption).
+
+## Impact on existing data (only if this touches persisted state)
+Does this change data that already exists — a DB schema/migration, saved user records, files a
+prior version produced? Name what existing data is affected and the migration/backfill plan (or
+"none — new data only"). A rule that changes *how* something is computed does not retroactively
+fix rows already written; say how the old ones are handled.