cleargate 0.5.0 → 0.6.1

package/dist/cli.js

@@ -14,7 +14,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "cleargate",
-  version: "0.5.0",
+  version: "0.6.1",
   private: false,
   type: "module",
   description: "Planning framework for Claude Code agents \u2014 sprint/epic/story protocol, four-agent loop (architect/developer/qa/reporter), Karpathy-style awareness wiki.",
@@ -1275,10 +1275,16 @@ async function stampHandler(file, opts, cli) {
 import * as fs13 from "fs";
 import * as path13 from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
+import { spawnSync as spawnSync3 } from "child_process";
 
 // src/init/copy-payload.ts
 import * as fs5 from "fs";
 import * as path4 from "path";
+var PIN_PLACEHOLDER = "__CLEARGATE_VERSION__";
+var HOOK_FILES_WITH_PIN = /* @__PURE__ */ new Set([
+  ".claude/hooks/stamp-and-gate.sh",
+  ".claude/hooks/session-start.sh"
+]);
 function listFilesRecursive(dir) {
   const results = [];
   function walk(current, rel) {
@@ -1306,10 +1312,15 @@ function copyPayload(payloadDir, targetCwd, opts) {
     const srcPath = path4.join(payloadDir, relPath);
     const dstPath = path4.join(targetCwd, relPath);
     fs5.mkdirSync(path4.dirname(dstPath), { recursive: true });
-    const srcContent = fs5.readFileSync(srcPath);
+    let srcContent = fs5.readFileSync(srcPath);
+    if (opts.pinVersion && HOOK_FILES_WITH_PIN.has(relPath)) {
+      const text = srcContent.toString("utf8").replaceAll(PIN_PLACEHOLDER, opts.pinVersion);
+      srcContent = text;
+    }
+    const srcBuffer = typeof srcContent === "string" ? Buffer.from(srcContent, "utf8") : srcContent;
     if (fs5.existsSync(dstPath)) {
       const dstContent = fs5.readFileSync(dstPath);
-      if (srcContent.equals(dstContent)) {
+      if (srcBuffer.equals(dstContent)) {
         report.skipped++;
         report.actions.push({ action: "skipped", relPath });
         continue;
@@ -1319,11 +1330,11 @@ function copyPayload(payloadDir, targetCwd, opts) {
         report.actions.push({ action: "skipped", relPath });
         continue;
       }
-      fs5.writeFileSync(dstPath, srcContent);
+      fs5.writeFileSync(dstPath, srcBuffer);
       report.overwritten++;
       report.actions.push({ action: "overwritten", relPath });
     } else {
-      fs5.writeFileSync(dstPath, srcContent);
+      fs5.writeFileSync(dstPath, srcBuffer);
       report.created++;
       report.actions.push({ action: "created", relPath });
     }
@@ -2156,7 +2167,7 @@ async function readDriftState(projectRoot) {
 import * as readline3 from "readline";
 async function promptYesNo(question, defaultYes, opts) {
   const stdoutFn = opts?.stdout ?? ((s) => process.stdout.write(s));
-  stdoutFn(question + "\n");
+  stdoutFn(question + " ");
   const inputStream = opts?.stdin ?? process.stdin;
   return new Promise((resolve14) => {
     const rl = readline3.createInterface({
@@ -2187,7 +2198,7 @@ async function promptYesNo(question, defaultYes, opts) {
 }
 async function promptEmail(question, defaultValue, opts) {
   const stdoutFn = opts?.stdout ?? ((s) => process.stdout.write(s));
-  stdoutFn(question + "\n");
+  stdoutFn(question + " ");
   const inputStream = opts?.stdin ?? process.stdin;
   return new Promise((resolve14) => {
     const rl = readline3.createInterface({
@@ -2279,6 +2290,17 @@ function resolveIdentity(projectRoot, opts = {}) {
 // src/commands/init.ts
 var HOOK_ADDITION = {
   hooks: {
+    PreToolUse: [
+      {
+        matcher: "Edit|Write",
+        hooks: [
+          {
+            type: "command",
+            command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-edit-gate.sh"
+          }
+        ]
+      }
+    ],
     PostToolUse: [
       {
         matcher: "Edit|Write",
@@ -2315,6 +2337,17 @@ function writeAtomic(filePath, content) {
   fs13.writeFileSync(tmpPath, content, "utf8");
   fs13.renameSync(tmpPath, filePath);
 }
+function readPackageVersion(packageJsonPath) {
+  try {
+    const raw = fs13.readFileSync(packageJsonPath, "utf8");
+    const pkg = JSON.parse(raw);
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return null;
+}
 async function initHandler(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const force = opts.force ?? false;
@@ -2325,6 +2358,7 @@ async function initHandler(opts = {}) {
   const runWikiBuild = opts.runWikiBuild ?? wikiBuildHandler;
   const promptYesNoFn = opts.promptYesNo ?? promptYesNo;
   const promptEmailFn = opts.promptEmail ?? promptEmail;
+  const spawnSyncFn = opts.spawnSyncFn ?? spawnSync3;
   if (!fs13.existsSync(cwd)) {
     stderr(`[cleargate init] ERROR: target directory does not exist: ${cwd}
 `);
@@ -2386,7 +2420,14 @@ async function initHandler(opts = {}) {
       }
     }
   }
-  const copyReport = copyPayload(payloadDir, cwd, { force });
+  let pinVersion;
+  if (opts.pin) {
+    pinVersion = opts.pin;
+  } else {
+    const payloadParent = path13.resolve(payloadDir, "..", "..");
+    pinVersion = readPackageVersion(path13.join(payloadParent, "package.json")) ?? readPackageVersion(path13.join(path13.dirname(fileURLToPath5(import.meta.url)), "..", "package.json")) ?? "latest";
+  }
+  const copyReport = copyPayload(payloadDir, cwd, { force, pinVersion });
   for (const action of copyReport.actions) {
     const verb = action.action === "created" ? "Created" : action.action === "overwritten" ? "Overwritten" : "Skipped (exists)";
     stdout(`[cleargate init] ${verb} ${action.relPath}
@@ -2467,6 +2508,46 @@ async function initHandler(opts = {}) {
 `);
     }
   }
+  {
+    const distCliPath = path13.join(cwd, "cleargate-cli", "dist", "cli.js");
+    let branch = null;
+    let branchLabel = "";
+    if (fs13.existsSync(distCliPath)) {
+      branch = { cmd: "node", args: [distCliPath, "--version"] };
+      branchLabel = `local dist (${distCliPath})`;
+    } else {
+      const whichResult = spawnSyncFn("command", ["-v", "cleargate"], {
+        shell: true,
+        encoding: "utf8",
+        timeout: 3e3
+      });
+      if (whichResult.status === 0) {
+        branch = { cmd: "cleargate", args: ["--version"] };
+        branchLabel = "PATH (global install)";
+      } else {
+        branch = { cmd: "npx", args: ["-y", `cleargate@${pinVersion}`, "--version"] };
+        branchLabel = `npx cleargate@${pinVersion} (cold-start ~600ms first call)`;
+      }
+    }
+    if (branch !== null) {
+      const probeResult = spawnSyncFn(branch.cmd, branch.args, {
+        encoding: "utf8",
+        timeout: 15e3
+      });
+      if (probeResult.status === 0) {
+        stdout(`[cleargate init] \u{1F7E2} cleargate CLI resolved via ${branchLabel}
+`);
+      } else {
+        stdout(
+          `[cleargate init] \u{1F7E1} cleargate CLI: not resolvable in this environment.
+[cleargate init]   Attempted: ${branchLabel}
+[cleargate init]   This is a warning, not a fatal error. Hooks will no-op until resolved.
+[cleargate init]   Fix: npm i -g cleargate@${pinVersion}  or  npx cleargate@${pinVersion} doctor
+`
+        );
+      }
+    }
+  }
   const existingParticipant = readParticipant(cwd);
   if (existingParticipant === null) {
     const identityOpts = opts.identityOpts ?? {};
@@ -2484,8 +2565,10 @@ async function initHandler(opts = {}) {
       stdout(`[cleargate init] Participant identity: ${finalEmail} (inferred)
 `);
     } else {
-      const defaultEmail = gitEmail ?? "user@localhost";
-      const question = `[cleargate init] Participant email [${defaultEmail}]:`;
+      const isNoreply = gitEmail !== null && /@users\.noreply\.github\.com$/i.test(gitEmail);
+      const defaultEmail = gitEmail !== null && !isNoreply ? gitEmail : "user@localhost";
+      stdout("\n");
+      const question = `Participant email (press Enter for default) [${defaultEmail}]:`;
       const answer = await promptEmailFn(question, defaultEmail);
       await writeParticipant(cwd, answer, "prompted", now);
       stdout(`[cleargate init] Participant identity: ${answer} (prompted)
@@ -2502,7 +2585,7 @@ async function initHandler(opts = {}) {
 // src/commands/wiki-ingest.ts
 import * as fs14 from "fs";
 import * as path14 from "path";
-import { spawnSync as spawnSync3 } from "child_process";
+import { spawnSync as spawnSync4 } from "child_process";
 var EXCLUDED_SUFFIXES2 = [
   ".cleargate/knowledge/",
   ".cleargate/templates/",
@@ -2654,7 +2737,7 @@ function checkContentUnchanged(absRawPath, sha, relRawPath, gitRunner) {
   }
 }
 function defaultGitRunner(cmd, args) {
-  const result = spawnSync3(cmd, args, { encoding: "utf8" });
+  const result = spawnSync4(cmd, args, { encoding: "utf8" });
   if (result.status !== 0) return "\0__NONZERO__";
   return result.stdout ?? "";
 }
@@ -2903,7 +2986,7 @@ function loadWikiPages(wikiRoot) {
 // src/wiki/lint-checks.ts
 import * as fs16 from "fs";
 import * as path16 from "path";
-import { spawnSync as spawnSync4 } from "child_process";
+import { spawnSync as spawnSync5 } from "child_process";
 import yaml3 from "js-yaml";
 
 // src/lib/work-item-type.ts
@@ -2998,7 +3081,7 @@ function checkStaleCommit(page, repoRoot, gitRunner) {
   if (gitRunner) {
     currentSha = gitRunner("git", ["log", "-1", "--format=%H", "--", rawPath]).trim();
   } else {
-    const result = spawnSync4("git", ["log", "-1", "--format=%H", "--", rawPath], {
+    const result = spawnSync5("git", ["log", "-1", "--format=%H", "--", rawPath], {
       encoding: "utf8",
       cwd: repoRoot
     });
@@ -3739,6 +3822,7 @@ function applyStatusFix(rawText, newStatus) {
 // src/commands/doctor.ts
 import * as fs20 from "fs";
 import * as path21 from "path";
+import { spawnSync as spawnSync6 } from "child_process";
 
 // src/lib/pricing.ts
 var PRICING_TABLE = {
@@ -3787,6 +3871,7 @@ function selectMode(flags) {
   if (flags.checkScaffold) modes.push("check-scaffold");
   if (flags.sessionStart) modes.push("session-start");
   if (flags.pricing) modes.push("pricing");
+  if (flags.canEdit) modes.push("can-edit");
   if (modes.length > 1) {
     throw new Error(
       `cleargate doctor: mutually exclusive flags set: ${modes.join(", ")}. Use only one mode flag at a time.`
@@ -3811,7 +3896,18 @@ function parseHookLogLine(line) {
     file: m[5].trim()
   };
 }
-function runHookHealth(stdout, cwd, now) {
+function runHookHealth(stdout, cwd, now, outcome) {
+  const cleargateDir = path21.join(cwd, ".cleargate");
+  if (!fs20.existsSync(cleargateDir)) {
+    stdout("cleargate misconfigured: no .cleargate/ found. Run: cleargate init");
+    if (outcome) outcome.configError = true;
+    return;
+  }
+  const manifestPath = path21.join(cwd, "cleargate-planning", "MANIFEST.json");
+  if (!fs20.existsSync(manifestPath)) {
+    stdout(`cleargate misconfigured: cleargate-planning/MANIFEST.json not found. Run: cleargate init`);
+    if (outcome) outcome.configError = true;
+  }
   const settingsPath = path21.join(cwd, ".claude", "settings.json");
   if (!fs20.existsSync(settingsPath)) {
     stdout("[doctor] No .claude/settings.json found \u2014 hook config unavailable.");
@@ -3948,7 +4044,57 @@ function parseCachedGateResult2(raw) {
     failing_criteria: parsed.failing_criteria ?? []
   };
 }
-async function runSessionStart(cwd, stdout) {
+function emitResolverStatusLine(cwd, stdout) {
+  const distCliPath = path21.join(cwd, "cleargate-cli", "dist", "cli.js");
+  if (fs20.existsSync(distCliPath)) {
+    stdout(`cleargate CLI: local dist \u2014 ${distCliPath}`);
+    return;
+  }
+  const whichResult = spawnSync6("command", ["-v", "cleargate"], {
+    shell: true,
+    encoding: "utf8",
+    timeout: 3e3
+  });
+  if (whichResult.status === 0) {
+    stdout("cleargate CLI: PATH (global install) \u2014 cleargate");
+    return;
+  }
+  let pinVersion = "unknown";
+  const hookPath = path21.join(cwd, ".claude", "hooks", "stamp-and-gate.sh");
+  if (fs20.existsSync(hookPath)) {
+    try {
+      const hookContent = fs20.readFileSync(hookPath, "utf-8");
+      const pinMatch = hookContent.match(/^#\s*cleargate-pin:\s*(\S+)\s*$/m);
+      if (pinMatch?.[1]) {
+        pinVersion = pinMatch[1];
+      } else {
+        const npxMatch = hookContent.match(/@cleargate\/cli@([^\s"']+)/);
+        if (npxMatch?.[1]) pinVersion = npxMatch[1];
+      }
+    } catch {
+    }
+  }
+  if (pinVersion === "unknown") {
+    stdout("cleargate CLI: \u{1F534} not resolvable \u2014 hooks will no-op. Fix: npm i -g cleargate or npx cleargate doctor");
+  } else {
+    stdout(`cleargate CLI: npx @cleargate/cli@${pinVersion} (cold-start ~600ms first call)`);
+  }
+}
+var PLANNING_FIRST_REMINDER = `Triage first, draft second:
+Before any Edit/Write that creates user-facing code, you must:
+  (1) classify the request (Epic / Story / CR / Bug),
+  (2) draft a work item under .cleargate/delivery/pending-sync/ from .cleargate/templates/,
+  (3) halt at Gate 1 (Proposal approval) for human sign-off.
+Bypass this only if the user has explicitly waived planning in this conversation.`;
+async function runSessionStart(cwd, stdout, outcome) {
+  const resolverLines = [];
+  emitResolverStatusLine(cwd, (line) => {
+    stdout(line);
+    resolverLines.push(line);
+  });
+  if (outcome && resolverLines.some((l) => l.includes("\u{1F534}"))) {
+    outcome.configError = true;
+  }
   const pendingSyncDir = path21.join(cwd, ".cleargate", "delivery", "pending-sync");
   let files;
   try {
@@ -3957,6 +4103,7 @@ async function runSessionStart(cwd, stdout) {
     return;
   }
   const blocked = [];
+  let hasApprovedStory = false;
   for (const filePath of files) {
     let raw;
     try {
@@ -3971,6 +4118,9 @@ async function runSessionStart(cwd, stdout) {
     } catch {
       continue;
     }
+    if (fm["approved"] === true) {
+      hasApprovedStory = true;
+    }
     const gate2 = parseCachedGateResult2(fm["cached_gate_result"]);
     if (!gate2 || gate2.pass !== false) continue;
     const idKeys = ["story_id", "epic_id", "proposal_id", "cr_id", "bug_id", "sprint_id"];
@@ -3988,9 +4138,19 @@ async function runSessionStart(cwd, stdout) {
     const firstCriterionId = gate2.failing_criteria.length > 0 ? gate2.failing_criteria[0]?.id ?? "" : "";
     blocked.push({ id: itemId, firstCriterionId });
   }
+  const activesentinel = path21.join(cwd, ".cleargate", "sprint-runs", ".active");
+  const sprintActive = fs20.existsSync(activesentinel);
+  const shouldRemind = !hasApprovedStory && !sprintActive;
+  if (shouldRemind) {
+    stdout(PLANNING_FIRST_REMINDER);
+    if (blocked.length > 0) {
+      stdout("");
+    }
+  }
   if (blocked.length === 0) {
     return;
   }
+  if (outcome) outcome.blocker = true;
   const overflow = blocked.length > SESSION_START_MAX_ITEMS ? blocked.length - SESSION_START_MAX_ITEMS : 0;
   const visible = blocked.slice(0, SESSION_START_MAX_ITEMS);
   const lines = [`${blocked.length} items blocked:`];
@@ -4007,10 +4167,11 @@ async function runSessionStart(cwd, stdout) {
   }
   stdout(output);
 }
-async function runPricing(filePath, cwd, stdout, stderr, exit) {
+async function runPricing(filePath, cwd, stdout, stderr, exit, outcome) {
   if (!filePath) {
     stderr("cleargate doctor --pricing: missing <file> argument");
-    exit(1);
+    if (outcome) outcome.configError = true;
+    exit(2);
     return;
   }
   const absPath = path21.isAbsolute(filePath) ? filePath : path21.resolve(cwd, filePath);
@@ -4019,12 +4180,14 @@ async function runPricing(filePath, cwd, stdout, stderr, exit) {
     raw = fs20.readFileSync(absPath, "utf-8");
   } catch {
     stderr(`cleargate doctor --pricing: cannot read file: ${absPath}`);
-    exit(1);
+    if (outcome) outcome.configError = true;
+    exit(2);
     return;
   }
   if (!raw.trimStart().startsWith("---")) {
     stderr(`cleargate doctor --pricing: file has no frontmatter: ${absPath}`);
-    exit(1);
+    if (outcome) outcome.configError = true;
+    exit(2);
     return;
   }
   let fm;
@@ -4032,12 +4195,14 @@ async function runPricing(filePath, cwd, stdout, stderr, exit) {
     fm = parseFrontmatter(raw).fm;
   } catch {
     stderr(`cleargate doctor --pricing: cannot parse frontmatter in: ${absPath}`);
-    exit(1);
+    if (outcome) outcome.configError = true;
+    exit(2);
     return;
   }
   const draftTokensRaw = fm["draft_tokens"];
   if (!draftTokensRaw) {
     stdout("draft_tokens unpopulated \u2014 run cleargate stamp-tokens first");
+    if (outcome) outcome.blocker = true;
     exit(1);
     return;
   }
@@ -4049,16 +4214,19 @@ async function runPricing(filePath, cwd, stdout, stderr, exit) {
       draftTokens = JSON.parse(draftTokensRaw);
     } catch {
       stdout("draft_tokens unpopulated \u2014 run cleargate stamp-tokens first");
+      if (outcome) outcome.blocker = true;
       exit(1);
       return;
     }
   } else {
     stdout("draft_tokens unpopulated \u2014 run cleargate stamp-tokens first");
+    if (outcome) outcome.blocker = true;
     exit(1);
     return;
   }
   if (draftTokens.input === null && draftTokens.output === null && draftTokens.cache_read === null && draftTokens.cache_creation === null) {
     stdout("draft_tokens unpopulated \u2014 run cleargate stamp-tokens first");
+    if (outcome) outcome.blocker = true;
     exit(1);
     return;
   }
@@ -4076,18 +4244,95 @@ async function runPricing(filePath, cwd, stdout, stderr, exit) {
     `${fileName}: ${model} \u2014 input:${input} output:${output} cache_read:${cacheRead} cache_creation:${cacheCreation} \u2248 $${usd.toFixed(4)}`
   );
 }
+function globMatch(pattern, filePath) {
+  const normalPattern = pattern.replace(/\\/g, "/");
+  const normalFile = filePath.replace(/\\/g, "/");
+  const regexStr = normalPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(//g, ".*");
+  const re = new RegExp(`^${regexStr}$`);
+  return re.test(normalFile);
+}
+async function runCanEdit(filePath, cwd, stdout, exit, outcome) {
+  const activeSentinel = path21.join(cwd, ".cleargate", "sprint-runs", ".active");
+  if (fs20.existsSync(activeSentinel)) {
+    stdout("allowed: sprint active");
+    return;
+  }
+  const pendingSyncDir = path21.join(cwd, ".cleargate", "delivery", "pending-sync");
+  let files;
+  try {
+    files = fs20.readdirSync(pendingSyncDir).filter((f) => f.endsWith(".md")).map((f) => path21.join(pendingSyncDir, f));
+  } catch {
+    stdout("blocked: no_approved_stories");
+    if (outcome) outcome.blocker = true;
+    exit(1);
+    return;
+  }
+  let hasApprovedStory = false;
+  let coveredByStory = false;
+  for (const storyPath of files) {
+    let raw;
+    try {
+      raw = fs20.readFileSync(storyPath, "utf-8");
+    } catch {
+      continue;
+    }
+    if (!raw.trimStart().startsWith("---")) continue;
+    let fm;
+    try {
+      fm = parseFrontmatter(raw).fm;
+    } catch {
+      continue;
+    }
+    if (fm["approved"] !== true) continue;
+    hasApprovedStory = true;
+    const implFilesRaw = fm["implementation_files"];
+    if (implFilesRaw === void 0 || implFilesRaw === null) {
+      coveredByStory = true;
+      break;
+    }
+    if (Array.isArray(implFilesRaw)) {
+      for (const pattern of implFilesRaw) {
+        if (typeof pattern !== "string") continue;
+        if (globMatch(pattern, filePath)) {
+          coveredByStory = true;
+          break;
+        }
+      }
+    }
+    if (coveredByStory) break;
+  }
+  if (!hasApprovedStory) {
+    stdout("blocked: no_approved_stories");
+    if (outcome) outcome.blocker = true;
+    exit(1);
+    return;
+  }
+  if (!coveredByStory) {
+    stdout("blocked: file_not_in_implementation_files");
+    if (outcome) outcome.blocker = true;
+    exit(1);
+    return;
+  }
+  stdout("allowed");
+}
 async function doctorHandler(flags, cli) {
   const cwd = cli?.cwd ?? process.cwd();
   const now = cli?.now ? cli.now() : /* @__PURE__ */ new Date();
   const stdout = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderr = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exit = cli?.exit ?? ((code) => process.exit(code));
+  const outcome = { configError: false, blocker: false };
+  let exitedEarly = false;
+  const wrappedExit = (code) => {
+    exitedEarly = true;
+    return exit(code);
+  };
   let mode;
   try {
     mode = selectMode(flags);
   } catch (err) {
     stderr(err.message);
-    exit(1);
+    exit(2);
     return;
   }
   switch (mode) {
@@ -4095,26 +4340,38 @@ async function doctorHandler(flags, cli) {
       await runCheckScaffold(flags, cli ?? {}, cwd, now, stdout, stderr);
       break;
     case "hook-health":
-      runHookHealth(stdout, cwd, now);
+      runHookHealth(stdout, cwd, now, outcome);
       break;
     case "session-start":
-      await runSessionStart(cwd, stdout);
+      await runSessionStart(cwd, stdout, outcome);
       break;
     case "pricing":
-      await runPricing(flags.pricingFile ?? "", cwd, stdout, stderr, exit);
+      await runPricing(flags.pricingFile ?? "", cwd, stdout, stderr, wrappedExit, outcome);
+      break;
+    case "can-edit":
+      await runCanEdit(flags.canEditFile ?? "", cwd, stdout, wrappedExit, outcome);
       break;
     default: {
       const exhaustiveCheck = mode;
       stderr(`cleargate doctor: unknown mode '${String(exhaustiveCheck)}'`);
-      exit(1);
+      exit(2);
+      return;
     }
   }
+  if (exitedEarly) return;
+  if (outcome.configError) {
+    exit(2);
+  } else if (outcome.blocker) {
+    exit(1);
+  } else {
+    exit(0);
+  }
 }
 
 // src/commands/gate.ts
 import * as fs24 from "fs";
 import * as path24 from "path";
-import { spawnSync as spawnSync5 } from "child_process";
+import { spawnSync as spawnSync7 } from "child_process";
 
 // src/commands/execution-mode.ts
 import * as fs21 from "fs";
@@ -4221,6 +4478,14 @@ function parsePredicate(src) {
     const value = parseValue(rawVal);
     return { kind: "frontmatter", ref, field, op, value };
   }
+  const markerNotMatch = s.match(/^body does not contain marker ['"]([A-Z]+)['"]$/);
+  if (markerNotMatch) {
+    const marker = markerNotMatch[1];
+    if (marker !== "TBD" && marker !== "TODO" && marker !== "FIXME") {
+      throw new Error(`unsupported predicate shape: ${src}`);
+    }
+    return { kind: "marker-absence", marker };
+  }
   const bodyNotMatch = s.match(/^body does not contain ['"](.+)['"]$/);
   if (bodyNotMatch) {
     return { kind: "body-contains", needle: bodyNotMatch[1], negated: true };
@@ -4276,6 +4541,8 @@ function evaluate(predicate, doc, opts) {
       return evalFrontmatter(parsed, doc, projectRoot);
     case "body-contains":
       return evalBodyContains(parsed, doc);
+    case "marker-absence":
+      return evalMarkerAbsence(parsed, doc);
     case "section":
       return evalSection(parsed, doc);
     case "file-exists":
@@ -4298,6 +4565,26 @@ function evalFrontmatter(parsed, doc, projectRoot) {
         detail: `frontmatter key '${parsed.ref}' is missing or null in ${doc.absPath}`
       };
     }
+    const refStr = String(refVal);
+    const looksLikeProse = refStr.length > 200 || /[ —–:()\n]/.test(refStr);
+    if (looksLikeProse) {
+      const waiver = doc.fm["proposal_gate_waiver"];
+      const hasExplicitWaiver = waiver !== null && waiver !== void 0 && waiver !== false && String(waiver).trim() !== "" && String(waiver).trim() !== "false";
+      const approvedBy = doc.fm["approved_by"];
+      const approvedAt = doc.fm["approved_at"];
+      const hasApprovalFields = approvedBy !== null && approvedBy !== void 0 && String(approvedBy).trim() !== "" && approvedAt !== null && approvedAt !== void 0 && String(approvedAt).trim() !== "";
+      const hasWaiver = hasExplicitWaiver || hasApprovalFields;
+      if (hasWaiver) {
+        return {
+          pass: true,
+          detail: `context_source is prose; proposal-gate waiver per frontmatter approved_by/approved_at`
+        };
+      }
+      return {
+        pass: false,
+        detail: `context_source is prose but no proposal_gate_waiver (approved_by + approved_at) found in frontmatter`
+      };
+    }
     const linkedPath = resolveLinkedPath(String(refVal), doc.absPath, projectRoot);
     if (!linkedPath) {
       return {
@@ -4422,6 +4709,38 @@ function evalBodyContains(parsed, doc) {
     return { pass: false, detail: `'${needle}' not found in body` };
   }
 }
+function evalMarkerAbsence(parsed, doc) {
+  const { marker } = parsed;
+  const lines = doc.body.split("\n");
+  const templateSelfRefRe = /^\s*-\s*\[[x ]\]\s*0\s*"TBDs?"\s*exist/i;
+  const markerRe = new RegExp(
+    `(?:^|(?<=\\())${marker}(?=:)|\\(${marker}\\)|\\[${marker}\\]|(?<=//\\s*)${marker}(?!\\w)|(?<=#\\s*)${marker}(?!\\w)`,
+    // # MARKER (comment)
+    "g"
+  );
+  const bareLineRe = new RegExp(`^${marker}$`);
+  const violations = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (templateSelfRefRe.test(line)) continue;
+    const trimmed = line.trim();
+    if (bareLineRe.test(trimmed)) {
+      violations.push(i + 1);
+      continue;
+    }
+    markerRe.lastIndex = 0;
+    if (markerRe.test(line)) {
+      violations.push(i + 1);
+    }
+  }
+  if (violations.length > 0) {
+    return {
+      pass: false,
+      detail: `${violations.length} marker occurrence${violations.length === 1 ? "" : "s"} of '${marker}' at line${violations.length === 1 ? "" : "s"} ${violations.join(", ")}`
+    };
+  }
+  return { pass: true, detail: `no '${marker}' markers found in body` };
+}
 function evalSection(parsed, doc) {
   const body = doc.body;
   const rawParts = body.split(/^(?=## )/m);
@@ -4789,7 +5108,7 @@ function gateQaHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? ((code2) => process.exit(code2));
-  const spawnFn = cli?.spawnFn ?? spawnSync5;
+  const spawnFn = cli?.spawnFn ?? spawnSync7;
   const sprintId = cli?.sprintId ?? "SPRINT-UNKNOWN";
   const mode = readSprintExecutionMode(sprintId, {
     sprintFilePath: cli?.sprintFilePath,
@@ -4815,7 +5134,7 @@ function gateArchHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? ((code2) => process.exit(code2));
-  const spawnFn = cli?.spawnFn ?? spawnSync5;
+  const spawnFn = cli?.spawnFn ?? spawnSync7;
   const sprintId = cli?.sprintId ?? "SPRINT-UNKNOWN";
   const mode = readSprintExecutionMode(sprintId, {
     sprintFilePath: cli?.sprintFilePath,
@@ -4839,13 +5158,13 @@ function gateArchHandler(opts, cli) {
 }
 
 // src/commands/gate-run.ts
-import { spawnSync as spawnSync6 } from "child_process";
+import { spawnSync as spawnSync8 } from "child_process";
 var KNOWN_GATES = ["precommit", "test", "typecheck", "lint"];
 function gateRunHandler(name, opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? ((code) => process.exit(code));
-  const spawnFn = cli?.spawnFn ?? spawnSync6;
+  const spawnFn = cli?.spawnFn ?? spawnSync8;
   const cwd = cli?.cwd ?? process.cwd();
   const configLoaderFn = cli?.configLoader ?? loadWikiConfig;
   if (!KNOWN_GATES.includes(name)) {
@@ -4877,7 +5196,7 @@ function gateRunHandler(name, opts, cli) {
 // src/commands/sprint.ts
 import * as fs25 from "fs";
 import * as path25 from "path";
-import { spawnSync as spawnSync7 } from "child_process";
+import { spawnSync as spawnSync9 } from "child_process";
 import yaml7 from "js-yaml";
 var TERMINAL_STATUSES2 = /* @__PURE__ */ new Set(["Completed", "Done", "Abandoned", "Closed", "Resolved"]);
 function resolveRunScript(opts) {
@@ -4892,7 +5211,7 @@ function sprintInitHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? defaultExit;
-  const spawnFn = cli?.spawnFn ?? spawnSync7;
+  const spawnFn = cli?.spawnFn ?? spawnSync9;
   const mode = readSprintExecutionMode(opts.sprintId, {
     sprintFilePath: cli?.sprintFilePath,
     cwd: cli?.cwd
@@ -4914,7 +5233,7 @@ function sprintCloseHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? defaultExit;
-  const spawnFn = cli?.spawnFn ?? spawnSync7;
+  const spawnFn = cli?.spawnFn ?? spawnSync9;
   const mode = readSprintExecutionMode(opts.sprintId, {
     sprintFilePath: cli?.sprintFilePath,
     cwd: cli?.cwd
@@ -5019,7 +5338,7 @@ async function sprintArchiveHandler(opts, cli) {
     const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
     const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
     const exitFn = cli?.exit ?? defaultExit;
-    const spawnFn = cli?.spawnFn ?? spawnSync7;
+    const spawnFn = cli?.spawnFn ?? spawnSync9;
     const cwd = cli?.cwd ?? process.cwd();
     const wikiBuildFn = cli?.wikiBuildFn ?? (async (wCwd, wStdout) => {
       const fakeExit = (code) => {
@@ -5243,7 +5562,7 @@ async function sprintArchiveHandler(opts, cli) {
 // src/commands/story.ts
 import * as fs26 from "fs";
 import * as path26 from "path";
-import { spawnSync as spawnSync8 } from "child_process";
+import { spawnSync as spawnSync10 } from "child_process";
 function defaultExit2(code) {
   return process.exit(code);
 }
@@ -5269,7 +5588,7 @@ function storyStartHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? defaultExit2;
-  const spawnFn = cli?.spawnFn ?? spawnSync8;
+  const spawnFn = cli?.spawnFn ?? spawnSync10;
   const cwd = cli?.cwd ?? process.cwd();
   const sprintId = cli?.sprintId ?? resolveSprintIdFromSentinel(cwd) ?? "SPRINT-UNKNOWN";
   const mode = readSprintExecutionMode(sprintId, {
@@ -5347,7 +5666,7 @@ function storyCompleteHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? defaultExit2;
-  const spawnFn = cli?.spawnFn ?? spawnSync8;
+  const spawnFn = cli?.spawnFn ?? spawnSync10;
   const cwd = cli?.cwd ?? process.cwd();
   const sprintId = cli?.sprintId ?? resolveSprintIdFromSentinel(cwd) ?? "SPRINT-UNKNOWN";
   const mode = readSprintExecutionMode(sprintId, {
@@ -5457,7 +5776,7 @@ function storyCompleteHandler(opts, cli) {
 
 // src/commands/state.ts
 import * as path27 from "path";
-import { spawnSync as spawnSync9 } from "child_process";
+import { spawnSync as spawnSync11 } from "child_process";
 function defaultExit3(code) {
   return process.exit(code);
 }
@@ -5470,7 +5789,7 @@ function stateUpdateHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? defaultExit3;
-  const spawnFn = cli?.spawnFn ?? spawnSync9;
+  const spawnFn = cli?.spawnFn ?? spawnSync11;
   const cwd = cli?.cwd;
   const sprintId = cli?.sprintId ?? resolveSprintIdFromSentinel(cwd) ?? "SPRINT-UNKNOWN";
   const mode = readSprintExecutionMode(sprintId, {
@@ -5497,7 +5816,7 @@ function stateValidateHandler(opts, cli) {
   const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
   const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
   const exitFn = cli?.exit ?? defaultExit3;
-  const spawnFn = cli?.spawnFn ?? spawnSync9;
+  const spawnFn = cli?.spawnFn ?? spawnSync11;
   const mode = readSprintExecutionMode(opts.sprintId, {
     sprintFilePath: cli?.sprintFilePath,
     cwd: cli?.cwd
@@ -8471,6 +8790,108 @@ async function adminLoginHandler(opts = {}) {
   stdout(`Credentials saved to ${authFilePath} (chmod 600).`);
 }
 
+// src/commands/hotfix.ts
+import * as fs34 from "fs";
+import * as path44 from "path";
+function defaultExit4(code) {
+  return process.exit(code);
+}
+var SLUG_RE = /^[a-z0-9-]+$/;
+var HOTFIX_FILE_RE = /^HOTFIX-(\d+)_.*\.md$/;
+function maxHotfixId(pendingDir) {
+  let max = 0;
+  let entries;
+  try {
+    entries = fs34.readdirSync(pendingDir);
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const m = HOTFIX_FILE_RE.exec(entry);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return max;
+}
+function countActiveHotfixes(repoRoot) {
+  const pendingDir = path44.join(repoRoot, ".cleargate", "delivery", "pending-sync");
+  const archiveDir = path44.join(repoRoot, ".cleargate", "delivery", "archive");
+  const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1e3;
+  let count = 0;
+  let pendingEntries = [];
+  try {
+    pendingEntries = fs34.readdirSync(pendingDir);
+  } catch {
+  }
+  for (const entry of pendingEntries) {
+    if (entry.startsWith("HOTFIX-") && entry.endsWith(".md")) count++;
+  }
+  let archiveEntries = [];
+  try {
+    archiveEntries = fs34.readdirSync(archiveDir);
+  } catch {
+  }
+  for (const entry of archiveEntries) {
+    if (entry.startsWith("HOTFIX-") && entry.endsWith(".md")) {
+      try {
+        const stat = fs34.statSync(path44.join(archiveDir, entry));
+        if (stat.mtimeMs >= sevenDaysAgo) count++;
+      } catch {
+      }
+    }
+  }
+  return count;
+}
+function resolveTemplatePath(repoRoot) {
+  return path44.join(repoRoot, ".cleargate", "templates", "hotfix.md");
+}
+function hotfixNewHandler(opts, cli) {
+  const stdoutFn = cli?.stdout ?? ((s) => process.stdout.write(s + "\n"));
+  const stderrFn = cli?.stderr ?? ((s) => process.stderr.write(s + "\n"));
+  const exitFn = cli?.exit ?? defaultExit4;
+  const repoRoot = cli?.cwd ?? process.cwd();
+  const now = cli?.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  if (!SLUG_RE.test(opts.slug)) {
+    stderrFn(`[cleargate hotfix new] slug must match ^[a-z0-9-]+$ (got: "${opts.slug}")`);
+    return exitFn(1);
+  }
+  const activeCount = countActiveHotfixes(repoRoot);
+  if (activeCount >= 3) {
+    stderrFn(
+      `Hotfix cap: \u22643 per rolling 7-day window. Currently ${activeCount} active. Bundle into a sprint or downgrade one to a CR.`
+    );
+    return exitFn(1);
+  }
+  const pendingDir = path44.join(repoRoot, ".cleargate", "delivery", "pending-sync");
+  const maxId = maxHotfixId(pendingDir);
+  const nextId = maxId + 1;
+  const idStr = `HOTFIX-${String(nextId).padStart(3, "0")}`;
+  const templatePath = resolveTemplatePath(repoRoot);
+  let templateContent;
+  try {
+    templateContent = fs34.readFileSync(templatePath, "utf8");
+  } catch {
+    stderrFn(`[cleargate hotfix new] template not found: ${templatePath}`);
+    return exitFn(2);
+  }
+  const content = templateContent.replace(/\{ID\}/g, idStr).replace(/\{SLUG\}/g, opts.slug).replace(/\{ISO\}/g, now);
+  const fileSlug = opts.slug.replace(/-/g, "_");
+  const fileName = `${idStr}_${fileSlug}.md`;
+  const outPath = path44.join(pendingDir, fileName);
+  try {
+    fs34.mkdirSync(pendingDir, { recursive: true });
+    fs34.writeFileSync(outPath, content, "utf8");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    stderrFn(`[cleargate hotfix new] write failed: ${msg}`);
+    return exitFn(1);
+  }
+  stdoutFn(`[cleargate hotfix new] created: ${outPath}`);
+  return exitFn(0);
+}
+
 // src/cli.ts
 var program = new Command();
 program.name("cleargate").description("ClearGate CLI \u2014 connects AI agent teams to the ClearGate MCP server").version(package_default.version, "-V, --version").option("--profile <name>", "configuration profile to use", "default").option("--mcp-url <url>", "MCP server URL (overrides config file and env)").showHelpAfterError("(use `cleargate --help`)");
@@ -8487,8 +8908,8 @@ program.command("join <invite-url>").description("join a ClearGate workspace usi
     ...cmdOpts.code !== void 0 ? { code: cmdOpts.code } : {}
   });
 });
-program.command("init").description("initialise a repo with ClearGate scaffold (CLAUDE.md block, hook config, agents, templates)").option("--force", "overwrite existing files that differ from the bundled payload").option("--yes", "non-interactive: accept all defaults without prompting").action(async (opts) => {
-  await initHandler({ force: opts.force ?? false, yes: opts.yes ?? false });
+program.command("init").description("initialise a repo with ClearGate scaffold (CLAUDE.md block, hook config, agents, templates)").option("--force", "overwrite existing files that differ from the bundled payload").option("--yes", "non-interactive: accept all defaults without prompting").option("--pin <ver>", "CR-009: pin hook resolver to a specific cleargate CLI version (default: package version)").action(async (opts) => {
+  await initHandler({ force: opts.force ?? false, yes: opts.yes ?? false, pin: opts.pin });
 });
 program.command("whoami").description("print the currently authenticated agent identity").action(async () => {
   const { whoamiHandler } = await import("./whoami-CX7CXJD5.js");
@@ -8610,14 +9031,20 @@ admin.command("bootstrap-root <handle>").description("seed the first root admin
   const { bootstrapRootHandler } = await import("./bootstrap-root-FGWDICDT.js");
   await bootstrapRootHandler({ handle, databaseUrl: opts.databaseUrl, force: opts.force ?? false });
 });
-program.command("doctor").description("diagnose scaffold drift, hook health, blocked items, and token cost").option("--check-scaffold", "check scaffold files for drift against install snapshot").option("--session-start-mode", "hidden: enables daily throttle (used by session-start hook)", false).option("--session-start", "emit blocked pending-sync items summary (used by SessionStart hook)").option("--pricing <file>", "compute USD cost estimate from a work item's draft_tokens").option("-v, --verbose", "show per-file drift detail").addHelpText("after", [
+program.command("doctor").description("diagnose scaffold drift, hook health, blocked items, and token cost").option("--check-scaffold", "check scaffold files for drift against install snapshot").option("--session-start-mode", "hidden: enables daily throttle (used by session-start hook)", false).option("--session-start", "emit blocked pending-sync items summary (used by SessionStart hook)").option("--pricing <file>", "compute USD cost estimate from a work item's draft_tokens").option("--can-edit <file>", "CR-008: exit 0 if editing file is allowed, exit 1 if planning required").option("--cwd <dir>", "working directory for the doctor check (default: process.cwd())").option("-v, --verbose", "show per-file drift detail").addHelpText("after", [
   "",
   "Modes (mutually exclusive):",
   "  --check-scaffold    Compute drift for all tracked scaffold files.",
   "                      Writes .cleargate/.drift-state.json.",
   "  --session-start     List blocked pending-sync items (\u226410, \u2264100 tokens).",
   "  --pricing <file>    Compute USD estimate from a work item's draft_tokens.",
-  "  (default)           Print a minimal hook-config health report."
+  "  --can-edit <file>   Check if editing a file requires a planning work item.",
+  "  (default)           Print a minimal hook-config health report.",
+  "",
+  "Exit codes:",
+  "  0  Clean \u2014 no blockers, no config errors.",
+  "  1  Blocked items or advisory issues \u2014 see stdout.",
+  "  2  ClearGate misconfigured or partially installed \u2014 see stdout for remediation."
 ].join("\n")).action(async (opts) => {
   await doctorHandler({
     checkScaffold: opts.checkScaffold,
@@ -8625,8 +9052,10 @@ program.command("doctor").description("diagnose scaffold drift, hook health, blo
     sessionStart: opts.sessionStart,
     pricing: !!opts.pricing,
     pricingFile: opts.pricing,
+    canEdit: !!opts.canEdit,
+    canEditFile: opts.canEdit,
     verbose: opts.verbose
-  });
+  }, opts.cwd ? { cwd: opts.cwd } : void 0);
 });
 program.command("upgrade").description("three-way merge scaffold files with upstream changes").option("--dry-run", "print plan without making any changes").option("--yes", 'auto-accept "take theirs" for all merge-3way files (non-interactive)').option("--only <tier>", "restrict to a specific scaffold tier (protocol/template/agent/hook/skill/cli-config)").addHelpText("after", [
   "",
@@ -8648,7 +9077,7 @@ program.command("uninstall").description("remove ClearGate scaffold from a proje
   "",
   "Always removed (no prompt): .claude/agents/*.md, ClearGate hooks,",
   "  .claude/skills/flashcard/, CLAUDE.md CLEARGATE block,",
-  "  @cleargate/cli from package.json, .install-manifest.json, .drift-state.json.",
+  "  `cleargate` from package.json, .install-manifest.json, .drift-state.json.",
   "",
   "Non-git targets: uncommitted-changes check is skipped silently."
 ].join("\n")).action(async (opts) => {
@@ -8701,5 +9130,9 @@ program.command("sync-log").description("filter and print sync-log entries").opt
     limit: opts.limit !== void 0 ? parseInt(opts.limit, 10) : 50
   });
 });
+var hotfix = program.command("hotfix").description("hotfix lane commands (off-sprint trivial fix scaffolding)");
+hotfix.command("new <slug>").description("scaffold a new HOTFIX-NNN_<slug>.md in pending-sync/").action((slug) => {
+  hotfixNewHandler({ slug });
+});
 void program.parseAsync(process.argv);
 //# sourceMappingURL=cli.js.map