@stdd/cli 0.0.1 → 0.0.2

package/README.md

@@ -132,10 +132,14 @@ $ npx @stdd/cli doctor
 Then wire the guards into CI:
 
 ```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # check-pr --base needs history
 - run: npx @stdd/cli check                                # tree invariants
 - env:
     PR_BODY: ${{ github.event.pull_request.body }}
-  run: printf '%s' "$PR_BODY" | npx @stdd/cli check-pr -  # docs evidence line
+  # Evidence line present AND the claimed doc paths really changed in this PR
+  run: printf '%s' "$PR_BODY" | npx @stdd/cli check-pr - --base "origin/${{ github.base_ref }}"
 ```
 
 ## Commands
@@ -145,7 +149,7 @@ Then wire the guards into CI:
 | `stdd init [dir] [--tools claude,codex]` | Install `.stdd/` and compile playbooks per agent |
 | `stdd doctor [dir]` | Adoption health report: setup, canonical docs, misleading artifacts, drift — exits 1 on findings |
 | `stdd check [dir]` | CI guard: no committed working artifacts, no temporal narrative in canonical docs, no stale or hand-edited generated files |
-| `stdd check-pr <file\|->` | CI guard: PR body carries exactly one non-empty docs evidence line |
+| `stdd check-pr <file\|-> [--base <ref>]` | CI guard: PR body carries exactly one non-empty docs evidence line; with `--base`, claimed doc paths are verified against the actual git diff |
 
 All checks are configured in `.stdd/config.json` (glob patterns for
 forbidden artifacts, canonical docs, temporal phrases).
@@ -173,7 +177,8 @@ forbidden artifacts, canonical docs, temporal phrases).
    history → git; deferred designs → dated project-log entries.
 5. **Evidence, not claims.** Every PR states `Docs updated first:` /
    `Docs checked, no change needed:` / `Docs not applicable:` — naming the
-   docs or the reason. CI rejects a missing, duplicated, or bare label.
+   docs or the reason. CI rejects a missing, duplicated, or bare label, and
+   with `--base` verifies the claimed doc paths against the actual diff.
 
 The full contract: [`method/README.md`](method/README.md).
 

package/cli/lib.mjs

@@ -92,6 +92,14 @@ export function mergeConfig(parsed) {
 	return config;
 }
 
+/**
+ * Extract repo-relative markdown paths from an evidence line's content.
+ * Prose (reasons, dashes, backticks) around the paths is ignored.
+ */
+export function extractDocPaths(content) {
+	return content.match(/[A-Za-z0-9_][A-Za-z0-9_./-]*\.md\b/g) ?? [];
+}
+
 /**
  * Build a temporal-phrase matcher. Word-ish boundaries on both sides so
  * hyphenated compounds ("no longer-lived") do not match.

package/cli/stdd.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
 	DEFAULT_CONFIG,
+	extractDocPaths,
 	findEvidenceLines,
 	globToRegExp,
 	mergeConfig,
@@ -295,7 +296,7 @@ function doctor(targetDir) {
 	if (failed) process.exit(1);
 }
 
-function checkPr(prBodyFile) {
+function checkPr(prBodyFile, baseRef) {
 	const body =
 		prBodyFile === "-" || !prBodyFile ? fs.readFileSync(0, "utf8") : fs.readFileSync(prBodyFile, "utf8");
 	const matches = findEvidenceLines(body);
@@ -313,16 +314,52 @@ function checkPr(prBodyFile) {
 	if (matches[0].content === "") {
 		fail(`"${matches[0].label}:" names no evidence — list the docs or the reason after the colon.`);
 	}
+	if (baseRef) verifyEvidenceAgainstDiff(matches[0], baseRef);
 	console.log("stdd check-pr: OK");
 }
 
+/** With --base: the evidence claim must be backed by the actual git diff. */
+function verifyEvidenceAgainstDiff({ label, content }, baseRef) {
+	const paths = extractDocPaths(content);
+	if (label === "Docs updated first") {
+		if (paths.length === 0) {
+			fail(`"Docs updated first:" names no doc paths — list the changed docs.`);
+		}
+		let changed;
+		try {
+			changed = execFileSync("git", ["diff", "--name-only", `${baseRef}...HEAD`], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "pipe"],
+			})
+				.split("\n")
+				.filter(Boolean);
+		} catch (err) {
+			fail(`--base ${baseRef}: git diff failed: ${err.stderr?.toString().trim() || err.message}`);
+		}
+		const missing = paths.filter((p) => !changed.includes(p));
+		if (missing.length > 0) {
+			fail(`claimed as updated but not changed against ${baseRef}: ${missing.join(", ")}`);
+		}
+	} else if (label === "Docs checked, no change needed") {
+		const absent = paths.filter((p) => !fs.existsSync(path.join(process.cwd(), ...p.split("/"))));
+		if (absent.length > 0) {
+			fail(`claimed as checked but does not exist in the tree: ${absent.join(", ")}`);
+		}
+	}
+}
+
 // --- argument parsing (strict: unknown flags are errors) ---
 const [, , command, ...rest] = process.argv;
 let tools = null;
+let baseRefArg = null;
 const positional = [];
 for (let i = 0; i < rest.length; i++) {
 	const arg = rest[i];
-	if (arg === "--tools" || arg.startsWith("--tools=")) {
+	if (arg === "--base" || arg.startsWith("--base=")) {
+		if (command !== "check-pr") fail(`--base is only valid for "stdd check-pr"`);
+		baseRefArg = arg.includes("=") ? arg.slice("--base=".length) : (rest[++i] ?? "");
+		if (!baseRefArg) fail("--base requires a git ref, e.g. --base origin/main");
+	} else if (arg === "--tools" || arg.startsWith("--tools=")) {
 		if (command !== "init") fail(`--tools is only valid for "stdd init"`);
 		const value = arg.includes("=") ? arg.slice("--tools=".length) : (rest[++i] ?? "");
 		tools = value.split(",").filter(Boolean);
@@ -351,13 +388,15 @@ switch (command) {
 		doctor(targetDir);
 		break;
 	case "check-pr":
-		checkPr(positional[0]);
+		checkPr(positional[0], baseRefArg);
 		break;
 	case "--version":
 	case "version":
 		console.log(VERSION);
 		break;
 	default:
-		console.log("Usage: stdd <init|check|check-pr|doctor> [dir|pr-body-file] [--tools claude,codex]");
+		console.log(
+			"Usage: stdd <init|check|check-pr|doctor> [dir|pr-body-file] [--tools claude,codex] [--base <ref>]",
+		);
 		process.exit(command ? 1 : 0);
 }

package/method/README.md

@@ -55,6 +55,12 @@ classify → read docs → docs edit (the spec) → failing test → implement
    starting at the beginning of a line counts (quoted templates and code
    blocks do not).
 
+   With `--base <ref>` the claim is verified against the actual diff:
+   every doc path named after `Docs updated first:` must be a file changed
+   between the base ref and `HEAD` (and at least one path must be named);
+   paths named after `Docs checked, no change needed:` must exist in the
+   tree. Claiming a docs update the diff does not contain fails CI.
+
 ## The frontend exception: design-first
 
 Frontend **visual** work — layout, styling, markup structure, presentation

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@stdd/cli",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Spec + Test Driven Development — a markdown-first methodology kit for teams building software with AI coding agents",
 	"type": "module",
 	"bin": {