create-cadmo 0.3.0 → 0.4.0

package/index.js

@@ -85,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.3.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",

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/claude-commands/cadmo-done.md

@@ -11,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/spec-drift-workflow.yml

@@ -1,8 +1,8 @@
 # Example workflow — copy to .github/workflows/spec-drift.yml in your project.
 # 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): write "spec-drift: skip -- <reason>" in the
-# latest commit message.
+# 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:
@@ -19,15 +19,24 @@ jobs:
         with:
           node-version: "20"
       - name: specs must change with the code they govern
+        env:
+          # env var, never inline interpolation — a PR body is attacker-controlled text
+          PR_BODY: ${{ github.event.pull_request.body }}
         run: |
-          if git log -1 --format=%B | grep -qi 'spec-drift: skip'; then
-            echo "spec-drift: skip found in commit message — skipping."
-            exit 0
-          fi
           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 }}"
-            git cat-file -e "${BASE}^{commit}" 2>/dev/null || BASE="$(git rev-parse HEAD~1)"
+            # 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

@@ -30,12 +30,17 @@
  * the SINGLE grammar shared by spec-drift, cadmo-score and the plugin hook.
  *
  * Usage:
- *   node spec-drift.mjs [--base origin/main] [--dir .] [--suspect-all]
+ *   node spec-drift.mjs [--base <ref>] [--dir .] [--suspect-all]
  *   node spec-drift.mjs --stamp <spec.md> [--dir .]
  *
+ * 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 commit message 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';
@@ -49,8 +54,27 @@ 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) {
@@ -147,12 +171,19 @@ if (STAMP) {
 }
 
 // --- 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);
 }
 
@@ -160,7 +191,14 @@ const specs = [];
 for (const f of mdFiles(ROOT)) {
   const text = readSpec(f);
   const watches = watchesOf(text);
-  if (watches) specs.push({ spec: path.relative(ROOT, f).split(BS).join('/'), watches, reviewed: reviewedOf(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) {