@afokapu/atdd-bun 0.10.88 → 0.10.90

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.88",
+  "version": "0.10.90",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
@@ -1257,13 +1257,13 @@
     "planner-schemas/wmbt.schema.json": "7a3a5693bfcf01340667c2be4a3c48e74f34b1af7e8dc13372c0de06b7f4fe12",
     "relationships.yaml": "5860a308ebc3ee7fa8172fc2c6633984000ab3003f0ae4b6fa28db48879eda22",
     "src/agent.ts": "6d6c6e75908af8fbab13432f0001b0374bb25cf3dee46ba218dfd67e0090cb56",
-    "src/ci.ts": "2a5e5052c4b99eb5c7282c7db2af3846ad6f3ca7d1eaefe924441116f765f37b",
-    "src/cli.ts": "995e41b3cb44c04f65f4d599f0fc51b93b17b7558b7c7dcfabed64de3d455250",
+    "src/ci.ts": "b5c57dd87fc780b2b272156b68830d14e695a1a28300dec46a06f71864e0c59e",
+    "src/cli.ts": "d93c3aebb78e752fd96347a5b177c0ed0697010c6e2533e116de93e772cd65a8",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
     "src/enforce.ts": "e0c10519aeecd7080f2900ea230fad2f09482af47c1cee885d5de71573e29732",
-    "src/hooks.ts": "e3ef7e17eaec8fe3b646e6b33a4a04c40eb25ac9a2642e68e4401fec973521e2",
+    "src/hooks.ts": "ed1550a02ed9d61828e540ce8d7f1e01d0baea8dcebc74b4ea53d4a49532856b",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
-    "src/integrity.ts": "f5ad22759eec675454df82cdcf791b1f081951f08ca5084ebdcb8cd82aa1ecef",
+    "src/integrity.ts": "19066185f99839c9e95c57f9bfbcd34df58cf8f4c33de86264c89e03b1085abf",
     "src/journey-docs.ts": "994d229376244c84212cff951032823068a76565dd2fd427b9d44e341bd14853",
     "src/planner-kernel.ts": "5d3f5305fb59becb2cc97d8a03aca6b104f385805d91cc0410856e289dd6fbb1",
     "src/planner-schema-validator.ts": "ce529c0936171075e93c7539b3655fe895a98dd2973ebda5775958e6ebc316d9",
@@ -1276,9 +1276,9 @@
     "src/telemetry-plan.ts": "cdb1e8bfff414f3ea81977388973da2cf6d89567d9e060dc9d5989a33600f153",
     "src/topology.ts": "9779ee48e1c453abb76363163d4ab363463fa14e359571139f6d1f1fcc51ae2c",
     "templates/agents/AGENTS.block.md": "84d19dfabedb1e05ccfb7b19a38644e87f193ae2b74755897f75f13971bb687e",
-    "templates/agents/atdd-bun.integrity.test.ts": "dec6f6e5f65a08d9512fc703b367c163f8c9da1f6aa7fd466835c1ec30348a41",
+    "templates/agents/atdd-bun.integrity.test.ts": "76eb5f59c50d2fc3f4835c0adf85db4046597c25b1deb0432e6acb2ee1a617d8",
     "templates/docs/site.css": "482b3427e3a3cb02a85dc85cfbeac80592dfd53abf42fc92d6ea7071f22afc95",
     "templates/github/atdd-bun-release.yml": "d9547e9e6ef3ae010d53d55314f6a54567f88bd900f7e50d994cd308601d2684",
-    "templates/github/atdd-bun.yml": "53d77e2d0dc8fa7f8700ac1d4d5c7522f960b423e894d78e1d8bfc63d68b95c7"
+    "templates/github/atdd-bun.yml": "6b766ae25ac86f3c87c91b31726461d0ba13d3383e55bbc9c9d1fe79ec26fcba"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.88",
+  "version": "0.10.90",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/ci.ts

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { policy } from "./hooks";
+import { enforcementIdentity, policy } from "./hooks";
 
 const root = resolve(import.meta.dir, "..");
 const template = join(root, "templates/github/atdd-bun.yml");
@@ -27,7 +27,8 @@ export async function renderWorkflow(repo = process.cwd()) {
     const config = Bun.YAML.parse(await readFile(configPath, "utf8"));
     rejectNew = Boolean(config && typeof config === "object" && !Array.isArray(config) && (config as { ratchet?: { mode?: unknown } }).ratchet?.mode === "reject-new");
   } catch { /* policy(repo) below gives its existing parse diagnostic */ }
-  return (await readFile(template, "utf8")).replace("{{PLAYWRIGHT}}\n", await usesPlaywright(repo) ? playwrightStep : "").replace("{{VERSION}}", version).replace("{{PROTECTED_BRANCHES}}", (await policy(repo)).protected_branches.map(branch => JSON.stringify(branch)).join(", ")).replace("{{ENFORCEMENT}}", rejectNew ? 'bun run atdd-bun all --ratchet --base "$ATDD_BASE_REF" --ratchet-activate-profiles' : "bun run atdd-bun all");
+  const identity = await enforcementIdentity(repo);
+  return (await readFile(template, "utf8")).replace("{{PLAYWRIGHT}}\n", await usesPlaywright(repo) ? playwrightStep : "").replace("{{VERSION}}", version).replace("{{IDENTITY}}", identity.digest).replace("{{PROTECTED_BRANCHES}}", (await policy(repo)).protected_branches.map(branch => JSON.stringify(branch)).join(", ")).replace("{{ENFORCEMENT}}", rejectNew ? 'bun run atdd-bun all --ratchet --base "$ATDD_BASE_REF" --ratchet-activate-profiles' : "bun run atdd-bun all");
 }
 const githubPackagesRegistry = /^\s*@[\w.-]+:registry\s*=\s*https:\/\/npm\.pkg\.github\.com\/?\s*$/im;
 const githubPackagesAuth = /^\s*\/\/npm\.pkg\.github\.com\/:_authToken\s*=\s*(.*?)\s*$/gim;
@@ -61,4 +62,4 @@ export async function ciInit(repo = process.cwd(), replace = false) {
   await writeFile(output, rendered);
   return { ok: true, message: npmrc.content === undefined ? output : `${output}\n${npmrc.path}` };
 }
-export async function ciStatus(repo = process.cwd()) { const output = join(repo, ".github/workflows/atdd-bun.yml"); return { ok: existsSync(output), message: output }; }
+export async function ciStatus(repo = process.cwd()) { const output = join(repo, ".github/workflows/atdd-bun.yml"); if (!existsSync(output)) return { ok: false, message: `${output} is missing; run: bun run atdd-bun init --replace` }; try { return await readFile(output, "utf8") === await renderWorkflow(repo) ? { ok: true, message: output } : { ok: false, message: `${output} is stale; run: bun run atdd-bun init --replace` }; } catch (error) { return { ok: false, message: `${output} cannot be verified: ${String(error)}; run: bun run atdd-bun init --replace` }; } }

package/src/cli.ts

@@ -8,7 +8,7 @@ import { join, resolve } from "node:path";
 import { finishWorktree, hookEvents, hooksStatus, installHooks, runHook, startWorktree, uninstallHooks, worktreeStatus } from "./hooks";
 import { ciInit, ciStatus } from "./ci";
 import { agentInit, agentStatus } from "./agent";
-import { checkIntegrity, formatIntegrity, integrityInit, integrityStatus } from "./integrity";
+import { checkEnforcementCoherence, checkIntegrity, formatIntegrity, integrityInit, integrityStatus } from "./integrity";
 import { journeyDocs } from "./journey-docs";
 import { adrRegister } from "./docs-capability";
 import { releaseCheck } from "./release";
@@ -54,6 +54,19 @@ function fail(message: string): never {
   process.exit(1);
 }
 
+async function governedRepository(root: string) {
+  const manifest = join(root, "package.json");
+  if (!existsSync(manifest)) return false;
+  const pkg = await Bun.file(manifest).json() as { name?: string; dependencies?: Record<string, unknown>; devDependencies?: Record<string, unknown> };
+  return pkg.name === "@afokapu/atdd-bun" || Object.hasOwn(pkg.dependencies ?? {}, "@afokapu/atdd-bun") || Object.hasOwn(pkg.devDependencies ?? {}, "@afokapu/atdd-bun");
+}
+
+async function requireCoherence(root: string, requireHookBinding: boolean) {
+  if (!await governedRepository(root)) return;
+  const findings = await checkEnforcementCoherence({ root, requireHookBinding });
+  if (findings.length) { console.error(formatIntegrity(findings)); process.exit(1); }
+}
+
 if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
   printHelp();
   process.exit(0);
@@ -68,6 +81,7 @@ if (args[0] === "init") {
 }
 if (args[0] === "hook") {
   if (!hookEvents.includes(args[1] as typeof hookEvents[number])) fail("unknown hook event: " + (args[1] ?? "(missing)"));
+  await requireCoherence(process.cwd(), true);
   const result = await runHook(args[1] as typeof hookEvents[number], process.cwd(), args.slice(2), await new Response(Bun.stdin.stream()).text());
   if (result.message) console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
 }
@@ -142,6 +156,7 @@ const git = async (directory: string, gitArgs: string[]) => {
 const stable = (items: string[]) => [...new Set(items)].sort();
 const profileActivation = args.includes("--ratchet-activate-profiles");
 if (profileActivation && !args.includes("--ratchet")) fail("--ratchet-activate-profiles requires --ratchet");
+await requireCoherence(root, process.env.GITHUB_ACTIONS !== "true");
 if (!args.includes("--ratchet")) {
   const violations = await enforce({ root, profiles: normalizedRequested as Profile[] });
   printViolations(violations);

package/src/hooks.ts

@@ -192,6 +192,40 @@ async function existingBranchProtectedBase(root: string, candidate: string, remo
 /** Ratchet findings depend only on the scanned tree, the toolkit scanning it and the selected profiles, so they are cached
  * under the Git common directory. An entry is advisory: unreadable, malformed or differently keyed means recompute, never clean. */
 const packageRoot = resolve(import.meta.dir, ".."), toolkitInputs = ["package.json", "relationships.yaml", "src", "lib", "detectors", "conventions", "planner-nodes", "planner-schemas"];
+const PACKAGE = "@afokapu/atdd-bun";
+export type LockedToolkit = { version: string; integrity: string };
+export type EnforcementIdentity = LockedToolkit & { installedVersion: string; profiles: string[]; digest: string; sourceCheckout: boolean };
+
+/** The exact registry tuple approved by this repository's Bun lockfile. No registry or network lookup is permitted. */
+export async function lockedToolkit(root: string): Promise<LockedToolkit | null> {
+  const lock = join(root, "bun.lock");
+  if (!existsSync(lock)) return null;
+  const row = (await readFile(lock, "utf8")).split("\n").find(line => line.trimStart().startsWith(`"${PACKAGE}": [`));
+  if (!row) return null;
+  const version = row.match(/"@afokapu\/atdd-bun@(\d+\.\d+\.\d+(?:-[\w.]+)?)",\s*""/)?.[1];
+  const integrity = row.match(/"(sha512-[^"]+)"\s*\],?\s*$/)?.[1];
+  return version && integrity ? { version, integrity } : null;
+}
+
+/** Only the running toolkit's actual repository root receives the source-checkout exception. */
+export async function isToolkitSourceCheckout(root = process.cwd()) {
+  return realpath(resolve(root)).then(repositoryRoot => realpath(packageRoot).then(runningRoot => repositoryRoot === runningRoot)).catch(() => false);
+}
+
+/** One identity binds the approved lock tuple, the package that will execute, and the exact activated config/profile set. */
+export async function enforcementIdentity(root = process.cwd()): Promise<EnforcementIdentity> {
+  const sourceCheckout = await isToolkitSourceCheckout(root);
+  const installedRoot = sourceCheckout ? packageRoot : join(root, "node_modules", PACKAGE);
+  const installedManifest = join(installedRoot, "package.json");
+  const providerVersion = (await Bun.file(join(packageRoot, "package.json")).json() as { version: string }).version;
+  const installedVersion = existsSync(installedManifest) ? (await Bun.file(installedManifest).json() as { version: string }).version : providerVersion;
+  const locked = await lockedToolkit(root) ?? { version: installedVersion, integrity: sourceCheckout ? "source" : "unresolved" };
+  const configPath = join(root, "atdd-bun.yaml"), config = existsSync(configPath) ? (await readFile(configPath, "utf8")).replace(/\r\n/g, "\n") : "";
+  const profiles = stable(await enabledProfiles(root));
+  const digest = new Bun.CryptoHasher("sha256").update(JSON.stringify({ schema: "atdd-bun.enforcement-identity/v1", ...locked, installedVersion, config, profiles })).digest("hex");
+  return { ...locked, installedVersion, profiles, digest, sourceCheckout };
+}
+
 export type ToolkitIdentity = { version: string; digest: string };
 async function toolkitFiles() {
   const found = new Set<string>();
@@ -318,17 +352,32 @@ export async function runHook(event: HookEvent, root = process.cwd(), args: stri
   return { ok: true, message: "ok" };
 }
 
-// Resolve from the checkout at hook time: installed consumers use their local package; source checkouts use src.
-const dispatcher = (event: HookEvent) => `#!/bin/sh\nroot="$(git rev-parse --show-toplevel)" || exit $?\nentry="$root/node_modules/@afokapu/atdd-bun/src/cli.ts"\nif [ ! -f "$entry" ]; then\n  if [ -f "$root/package.json" ] && grep -Eq '"name"[[:space:]]*:[[:space:]]*"@afokapu/atdd-bun"' "$root/package.json" && [ -f "$root/src/cli.ts" ]; then\n    entry="$root/src/cli.ts"\n  else\n    echo "atdd-bun hook: install @afokapu/atdd-bun in this project before running hooks" >&2\n    exit 1\n  fi\nfi\nexec bun "$entry" hook ${event} "$@"\n`;
-export async function installHooks(root = process.cwd(), replace = false) { const current = (await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out || (await git(root, ["config", "--get", "core.hooksPath"])).out; if (current && current !== ".githooks" && !replace) return bad(`core.hooksPath is ${current}; use --replace`); await git(root, ["config", "extensions.worktreeConfig", "true"]); await mkdir(join(root, ".githooks"), { recursive: true }); for (const event of hookEvents) { const file = join(root, ".githooks", event); await writeFile(file, dispatcher(event)); await chmod(file, 0o755); } const result = await git(root, ["config", "--worktree", "core.hooksPath", ".githooks"]); return result.code ? bad(result.err) : { ok: true, message: "hooks installed" }; }
+// Resolve from the checkout at hook time: installed consumers use only their worktree-local package; this package uses its own source checkout.
+const dispatcher = (event: HookEvent, identity: EnforcementIdentity) => {
+  const sourceFallback = identity.sourceCheckout ? `elif [ -f "$root/src/cli.ts" ]; then\n  entry="$root/src/cli.ts"\n` : "";
+  return `#!/bin/sh\n# atdd-bun enforcement identity: ${identity.digest}\nroot="$(git rev-parse --show-toplevel)" || exit $?\nentry="$root/node_modules/@afokapu/atdd-bun/src/cli.ts"\nmanifest="$root/node_modules/@afokapu/atdd-bun/package.json"\nif [ -f "$entry" ] && [ -f "$manifest" ]; then\n  installed="$(grep -m 1 -E '\"version\"[[:space:]]*:' "$manifest" | sed -E 's/.*\"version\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*/\\1/')"\n  if [ "$installed" != "${identity.version}" ]; then\n    echo "atdd-bun hook: installed package $installed does not match exact bun.lock resolution ${identity.version}; run: bun install --frozen-lockfile && bun run atdd-bun init --replace" >&2\n    exit 1\n  fi\n${sourceFallback}else\n  echo "atdd-bun hook: worktree-local @afokapu/atdd-bun is missing; run: bun install --frozen-lockfile && bun run atdd-bun init --replace" >&2\n  exit 1\nfi\nexec bun "$entry" hook ${event} "$@"\n`;
+};
+export async function renderHook(event: HookEvent, root = process.cwd()) { return dispatcher(event, await enforcementIdentity(root)); }
+export async function installHooks(root = process.cwd(), replace = false) { const current = (await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out || (await git(root, ["config", "--get", "core.hooksPath"])).out; if (current && current !== ".githooks" && !replace) return bad(`core.hooksPath is ${current}; use --replace`); const identity = await enforcementIdentity(root); await git(root, ["config", "extensions.worktreeConfig", "true"]); await mkdir(join(root, ".githooks"), { recursive: true }); for (const event of hookEvents) { const file = join(root, ".githooks", event); await writeFile(file, dispatcher(event, identity)); await chmod(file, 0o755); } const result = await git(root, ["config", "--worktree", "core.hooksPath", ".githooks"]); return result.code ? bad(result.err) : { ok: true, message: "hooks installed" }; }
 export async function uninstallHooks(root = process.cwd()) { if ((await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out === ".githooks") await git(root, ["config", "--worktree", "--unset", "core.hooksPath"]); for (const event of hookEvents) await rm(join(root, ".githooks", event), { force: true }); return { ok: true, message: "hooks uninstalled" }; }
-export async function hooksStatus(root = process.cwd()) { const path = (await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out; return { ok: path === ".githooks" && hookEvents.every(event => existsSync(join(root, ".githooks", event))), message: path || "not installed" }; }
+export async function hooksStatus(root = process.cwd()) {
+  const path = (await git(root, ["config", "--worktree", "--get", "core.hooksPath"])).out;
+  if (path !== ".githooks") return bad(`core.hooksPath is ${path || "not set"}; run: bun run atdd-bun init --replace`);
+  try {
+    for (const event of hookEvents) {
+      const file = join(root, ".githooks", event);
+      if (!existsSync(file)) return bad(`${relative(root, file)} is missing; run: bun run atdd-bun init --replace`);
+      if (await readFile(file, "utf8") !== await renderHook(event, root)) return bad(`${relative(root, file)} is stale; run: bun run atdd-bun init --replace`);
+    }
+  } catch (error) { return bad(`generated hooks cannot be verified: ${String(error)}; run: bun run atdd-bun init --replace`); }
+  return { ok: true, message: path };
+}
 
 const branchPath = (branch: string) => branch.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
 export async function startWorktree(root = process.cwd(), branch = "") { const cfg = await policy(root); if (!cfg.worktrees.enabled) return bad("worktree policy is disabled; set worktrees.enabled: true in atdd-bun.yaml"); const state = await layout(root, cfg.worktrees); if ("error" in state) return bad(state.error); if (state.current !== state.primary) return bad(`start must run from the primary checkout ${state.primary}`); if (!branch) return bad("branch is required: atdd-bun worktree start <branch>"); if ((await git(root, ["check-ref-format", "--branch", branch])).code) return bad(`invalid branch name ${JSON.stringify(branch)}`); if (cfg.protected_branches.includes(branch)) return bad(`cannot create a worktree for protected branch ${branch}`); const leaf = branchPath(branch); if (!leaf) return bad(`branch ${JSON.stringify(branch)} cannot form a safe worktree directory`); const target = join(state.worktreeRoot, leaf); if (existsSync(target)) return bad(`worktree path already exists: ${target}`); await mkdir(state.worktreeRoot, { recursive: true }); const created = await git(state.primary, ["worktree", "add", target, "-b", branch]); if (created.code) return bad(created.err || created.out); const hooks = await installHooks(target); if (!hooks.ok) return bad(`created ${target}, but could not install hooks: ${hooks.message}`); return { ok: true, message: `created linked worktree ${target} on ${branch}` }; }
 
 export async function worktreeStatus(root = process.cwd()) { const cfg = await primaryPolicy(root); if (!cfg.worktrees.enabled) return bad("worktree policy is disabled"); const state = await layout(root, cfg.worktrees); if ("error" in state) return bad(state.error); const result = await git(state.primary, ["worktree", "list", "--porcelain"]); return result.code ? bad(result.err) : { ok: true, message: result.out }; }
 
-async function generatedHooksOnly(root: string): Promise<boolean> { const directory = join(root, ".githooks"); if (!existsSync(directory)) return false; const names = (await readdir(directory)).sort(); if (names.join("\n") !== [...hookEvents].sort().join("\n")) return false; return (await Promise.all(hookEvents.map(async event => (await readFile(join(directory, event), "utf8")) === dispatcher(event)))).every(Boolean); }
+async function generatedHooksOnly(root: string): Promise<boolean> { const directory = join(root, ".githooks"); if (!existsSync(directory)) return false; const names = (await readdir(directory)).sort(); if (names.join("\n") !== [...hookEvents].sort().join("\n")) return false; return (await Promise.all(hookEvents.map(async event => (await readFile(join(directory, event), "utf8")) === await renderHook(event, root)))).every(Boolean); }
 
 export async function finishWorktree(root = process.cwd(), deleteBranch = false) { const cfg = await primaryPolicy(root); if (!cfg.worktrees.enabled) return bad("worktree policy is disabled"); const state = await layout(root, cfg.worktrees); if ("error" in state) return bad(state.error); if (state.current === state.primary || !inside(state.worktreeRoot, state.current)) return bad(`finish must run from a linked worktree beneath ${state.worktreeRoot}`); if (!state.branch || cfg.protected_branches.includes(state.branch)) return bad("finish requires a non-protected named branch"); const status = (await git(state.current, ["status", "--porcelain"])).out, generatedHooks = await generatedHooksOnly(state.current), onlyGeneratedHooks = Boolean(status) && status.split("\n").every(line => line.endsWith(" .githooks/") || line.endsWith(" .githooks")); if (status && !onlyGeneratedHooks) return bad("worktree is dirty; commit, stash, or discard changes before finish"); const tip = (await git(state.primary, ["rev-parse", "--verify", `refs/heads/${state.branch}`])).out.trim(); if (!tip || (await git(state.primary, ["merge-base", "--is-ancestor", tip, cfg.worktrees.primary_branch])).code) return bad(`branch ${state.branch} is not merged into ${cfg.worktrees.primary_branch} in the primary checkout`); const removed = await git(state.primary, ["worktree", "remove", ...(onlyGeneratedHooks && generatedHooks ? ["--force"] : []), state.current]); if (removed.code) return bad(removed.err || removed.out); if (deleteBranch) { const now = (await git(state.primary, ["rev-parse", "--verify", `refs/heads/${state.branch}`])).out.trim(); if (now !== tip || (await git(state.primary, ["merge-base", "--is-ancestor", tip, cfg.worktrees.primary_branch])).code) return bad(`worktree removed, but branch ${state.branch} was not deleted: its tip changed or is no longer merged into ${cfg.worktrees.primary_branch}`); const deleted = await git(state.primary, ["branch", "-D", state.branch]); if (deleted.code) return bad(`worktree removed, but branch deletion failed: ${deleted.err || deleted.out}`); } return { ok: true, message: `removed merged worktree ${state.current}${deleteBranch ? ` and branch ${state.branch}` : ""}` }; }

package/src/integrity.ts

@@ -3,7 +3,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { instructionPaths } from "./agent";
 import { renderWorkflow } from "./ci";
-import { defaultHookPolicy, type HookPolicy } from "./hooks";
+import { defaultHookPolicy, enforcementIdentity, hookEvents, hooksStatus, isToolkitSourceCheckout, lockedToolkit, renderHook, type HookPolicy } from "./hooks";
 
 /**
  * Integrity: the files an agent could change to weaken enforcement must stay canonical.
@@ -20,8 +20,9 @@ export const MANIFEST = "integrity.json";
 export const TEST_FILE = "atdd-bun.integrity.test.ts";
 const WORKFLOW = ".github/workflows/atdd-bun.yml";
 const BLOCK = /<!-- atdd-bun:start[\s\S]*?<!-- atdd-bun:end -->/;
-// Generated files carry the version that wrote them; an upgrade must not read as tampering.
+// Agent blocks are guidance rather than enforcement surfaces, so their writer version remains upgrade-tolerant.
 const unstamp = (text: string) => text.replace(/@afokapu\/atdd-bun (?:\d+\.\d+\.\d+(?:-[\w.]+)?|\{\{VERSION\}\})/g, "@afokapu/atdd-bun <version>").replace(/\r\n/g, "\n").trimEnd();
+const canonical = (text: string) => text.replace(/\r\n/g, "\n").trimEnd();
 const sha256 = (data: string | Uint8Array) => new Bun.CryptoHasher("sha256").update(data).digest("hex");
 /** Where `bun test` will find the generated test: the repository's `[test] root` from bunfig.toml, else the repo root. */
 export async function testFilePath(repo: string) {
@@ -69,41 +70,58 @@ export async function checkInstalledPackage(packageRoot = ownRoot): Promise<Inte
   return findings;
 }
 
-/** The repository installs the package from npm, pinned by a registry integrity hash. */
+/** The repository installs the package version approved by its exact npm-registry lock tuple. */
 async function checkDependency(root: string): Promise<IntegrityFinding[]> {
   if (!existsSync(join(root, "package.json"))) return [];
   const pkg = await Bun.file(join(root, "package.json")).json() as { name?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
-  if (pkg.name === PACKAGE) return [];
+  if (await isToolkitSourceCheckout(root)) return [];
   const spec = pkg.devDependencies?.[PACKAGE] ?? pkg.dependencies?.[PACKAGE];
-  if (spec === undefined) return [{ file: "package.json", detail: `${PACKAGE} is not a dependency`, restore: `bun add -d ${PACKAGE}` }];
+  if (spec === undefined) return [{ file: "package.json", detail: `${PACKAGE} is not a dependency`, restore: `bun add -d ${PACKAGE}@<operator-approved-version> --exact` }];
   const findings: IntegrityFinding[] = [];
-  if (!/^[~^]?\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(spec)) findings.push({ file: "package.json", detail: `${PACKAGE} is "${spec}"; it must be an npm version range, not a git, file, or link source`, restore: `bun add -d ${PACKAGE}` });
-  const lock = existsSync(join(root, "bun.lock")) ? await readFile(join(root, "bun.lock"), "utf8") : "";
+  if (!/^[~^]?\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(spec)) findings.push({ file: "package.json", detail: `${PACKAGE} is "${spec}"; it must be an npm version range, not a git, file, or link source`, restore: `bun add -d ${PACKAGE}@<operator-approved-version> --exact` });
+  const locked = await lockedToolkit(root), lock = existsSync(join(root, "bun.lock")) ? await readFile(join(root, "bun.lock"), "utf8") : "";
   const entry = lock.split("\n").find(line => line.trimStart().startsWith(`"${PACKAGE}": [`));
-  if (!entry) findings.push({ file: "bun.lock", detail: `bun.lock does not pin ${PACKAGE}`, restore: "bun install" });
-  else if (!/"@afokapu\/atdd-bun@\d+\.\d+\.\d+[^"]*", ""/.test(entry) || !entry.includes('"sha512-')) findings.push({ file: "bun.lock", detail: `bun.lock does not resolve ${PACKAGE} from the npm registry with an integrity hash`, restore: `bun add -d ${PACKAGE}` });
+  if (!entry) findings.push({ file: "bun.lock", detail: `bun.lock does not pin ${PACKAGE}; select the exact operator-approved version to create the reviewed lock resolution`, restore: `bun add -d ${PACKAGE}@<operator-approved-version> --exact` });
+  else if (!locked) findings.push({ file: "bun.lock", detail: `bun.lock does not resolve ${PACKAGE} from the npm registry with an integrity hash; select the exact operator-approved version to repair the reviewed lock resolution`, restore: `bun add -d ${PACKAGE}@<operator-approved-version> --exact` });
+  const installedManifest = join(root, "node_modules", PACKAGE, "package.json");
+  if (!existsSync(installedManifest)) findings.push({ file: `node_modules/${PACKAGE}/package.json`, detail: "the worktree-local installed package is missing", restore: "bun install --frozen-lockfile" });
+  else if (locked) {
+    const installedVersion = (await Bun.file(installedManifest).json() as { version?: unknown }).version;
+    if (installedVersion !== locked.version) findings.push({ file: `node_modules/${PACKAGE}/package.json`, detail: `installed version ${String(installedVersion)} does not match exact bun.lock resolution ${locked.version}`, restore: "bun install --frozen-lockfile" });
+  }
   return findings;
 }
 
-/** Generated files are byte-identical to what the installed version generates (ignoring its version stamp). */
-async function checkGenerated(root: string, packageRoot: string, skipWorkflow = false): Promise<IntegrityFinding[]> {
-  const findings: IntegrityFinding[] = [];
-  const same = async (file: string, template: string, restore: string) => {
-    const path = join(root, file);
-    if (!existsSync(path)) return findings.push({ file, detail: "is missing", restore });
-    if (unstamp(await readFile(path, "utf8")) !== unstamp(await readFile(join(packageRoot, template), "utf8"))) findings.push({ file, detail: "was edited; it must match what the package generates", restore });
-  };
-  // The workflow is rendered per repository (its protected branches), so it is compared with that rendering.
+async function renderIntegrityTest(root: string, packageRoot: string) {
+  const version = (await Bun.file(join(packageRoot, "package.json")).json() as { version: string }).version;
+  const { digest } = await enforcementIdentity(root);
+  return (await readFile(join(packageRoot, "templates/agents/atdd-bun.integrity.test.ts"), "utf8")).replace("{{VERSION}}", version).replace("{{IDENTITY}}", digest);
+}
+
+/** The generated enforcement surfaces are byte-identical to this exact lock/config/profile identity. */
+async function checkEnforcementGenerated(root: string, packageRoot: string, compare = true): Promise<IntegrityFinding[]> {
+  const findings: IntegrityFinding[] = [], restore = "bun run atdd-bun init --replace";
+  for (const event of hookEvents) {
+    const file = `.githooks/${event}`, path = join(root, file);
+    if (!existsSync(path)) findings.push({ file, detail: "is missing", restore });
+    else if (compare && canonical(await readFile(path, "utf8")) !== canonical(await renderHook(event, root))) findings.push({ file, detail: "is stale; it must match the exact lock/config/profile identity", restore });
+  }
   const workflow = join(root, WORKFLOW);
-  if (skipWorkflow) { /* rendered from atdd-bun.yaml, which does not parse: reported by the caller */ }
-  else if (!existsSync(workflow)) findings.push({ file: WORKFLOW, detail: "is missing", restore: "bun run atdd-bun ci init --replace" });
-  else if (unstamp(await readFile(workflow, "utf8")) !== unstamp(await renderWorkflow(root))) findings.push({ file: WORKFLOW, detail: "was edited; it must match what the package generates (protected_branches decides its push branches)", restore: "bun run atdd-bun ci init --replace" });
-  await same(relative(root, await testFilePath(root)), "templates/agents/atdd-bun.integrity.test.ts", "bun run atdd-bun integrity init --replace");
-  const canonical = (await readFile(join(packageRoot, "templates/agents/AGENTS.block.md"), "utf8")).match(BLOCK)![0];
+  if (!existsSync(workflow)) findings.push({ file: WORKFLOW, detail: "is missing", restore });
+  else if (compare && canonical(await readFile(workflow, "utf8")) !== canonical(await renderWorkflow(root))) findings.push({ file: WORKFLOW, detail: "is stale; it must match the exact lock/config/profile identity", restore });
+  const test = relative(root, await testFilePath(root)), testPath = join(root, test);
+  if (!existsSync(testPath)) findings.push({ file: test, detail: "is missing", restore });
+  else if (compare && canonical(await readFile(testPath, "utf8")) !== canonical(await renderIntegrityTest(root, packageRoot))) findings.push({ file: test, detail: "is stale; it must match the exact lock/config/profile identity", restore });
+  return findings;
+}
+
+async function checkGenerated(root: string, packageRoot: string, skipComparisons = false): Promise<IntegrityFinding[]> {
+  const findings = await checkEnforcementGenerated(root, packageRoot, !skipComparisons);
+  const agentCanonical = (await readFile(join(packageRoot, "templates/agents/AGENTS.block.md"), "utf8")).match(BLOCK)![0];
   for (const file of instructionPaths) {
     const agents = existsSync(join(root, file)) ? await readFile(join(root, file), "utf8") : "", block = agents.match(BLOCK)?.[0];
     if (!block) findings.push({ file, detail: "is missing the atdd-bun block", restore: "bun run atdd-bun agent init --replace" });
-    else if (unstamp(block) !== unstamp(canonical)) findings.push({ file, detail: "atdd-bun block was edited", restore: "bun run atdd-bun agent init --replace" });
+    else if (unstamp(block) !== unstamp(agentCanonical)) findings.push({ file, detail: "atdd-bun block was edited", restore: "bun run atdd-bun agent init --replace" });
   }
   return findings;
 }
@@ -216,6 +234,20 @@ async function checkPolicy(root: string, base?: string, push = process.env.GITHU
   return loosened.length ? [{ file: "atdd-bun.yaml", detail: `loosens the policy of ${against.slice(0, 7)}: ${loosened.join("; ")}`, restore: `git checkout ${against.slice(0, 7)} -- atdd-bun.yaml` }] : [];
 }
 
+export async function checkEnforcementCoherence(options: IntegrityOptions & { requireHookBinding?: boolean } = {}): Promise<IntegrityFinding[]> {
+  const root = resolve(options.root ?? process.cwd()), packageRoot = options.packageRoot ?? ownRoot;
+  try {
+    const findings = [...await checkInstalledPackage(packageRoot), ...await checkDependency(root), ...await checkEnforcementGenerated(root, packageRoot)];
+    if (options.requireHookBinding) {
+      const status = await hooksStatus(root);
+      if (!status.ok) findings.push({ file: ".githooks", detail: status.message, restore: "bun run atdd-bun init --replace" });
+    }
+    return findings;
+  } catch (error) {
+    return [{ file: "atdd-bun.yaml", detail: `the enforcement identity cannot be resolved: ${String(error)}`, restore: "correct atdd-bun.yaml and run: bun run atdd-bun init --replace" }];
+  }
+}
+
 export async function checkIntegrity(options: IntegrityOptions = {}): Promise<IntegrityFinding[]> {
   const root = resolve(options.root ?? process.cwd()), packageRoot = options.packageRoot ?? ownRoot;
   // An unreadable atdd-bun.yaml is a finding, not a crash: the policy and the workflow rendered from it cannot be
@@ -250,9 +282,8 @@ export function formatIntegrity(findings: IntegrityFinding[]): string {
 export async function integrityInit(repo = process.cwd(), replace = false) {
   const output = await testFilePath(repo);
   if (existsSync(output) && !replace) return { ok: false, message: `${output} exists; use --replace` };
-  const version = (await Bun.file(join(ownRoot, "package.json")).json() as { version: string }).version;
   await mkdir(dirname(output), { recursive: true });
-  await writeFile(output, (await readFile(join(ownRoot, "templates/agents/atdd-bun.integrity.test.ts"), "utf8")).replace("{{VERSION}}", version));
+  await writeFile(output, await renderIntegrityTest(repo, ownRoot));
   return { ok: true, message: output };
 }
-export async function integrityStatus(repo = process.cwd()) { const output = await testFilePath(repo); return { ok: existsSync(output), message: output }; }
+export async function integrityStatus(repo = process.cwd()) { const output = await testFilePath(repo); if (!existsSync(output)) return { ok: false, message: `${output} is missing; run: bun run atdd-bun init --replace` }; try { return canonical(await readFile(output, "utf8")) === canonical(await renderIntegrityTest(repo, ownRoot)) ? { ok: true, message: output } : { ok: false, message: `${output} is stale; run: bun run atdd-bun init --replace` }; } catch (error) { return { ok: false, message: `${output} cannot be verified: ${String(error)}; run: bun run atdd-bun init --replace` }; } }

package/templates/agents/atdd-bun.integrity.test.ts

@@ -1,4 +1,5 @@
 // Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun integrity init --replace`.
+// atdd-bun enforcement identity: {{IDENTITY}}
 // Fails loudly when the installed package, its generated files, or atdd-bun.yaml were changed.
 import { registerIntegrityTest } from "@afokapu/atdd-bun/register";
 

package/templates/github/atdd-bun.yml

@@ -1,4 +1,5 @@
 # Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun ci init --replace`.
+# atdd-bun enforcement identity: {{IDENTITY}}
 name: ATdd-Bun
 # The generated gate only needs checkout and package-download access. All other
 # token capabilities are explicitly disabled.