@christang/keel 5.7.0 → 5.16.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.7.0 -->
+<!-- keel:start version=5.16.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/assets/openspec/schemas/keel-spec-driven/templates/tasks.md

@@ -2,8 +2,10 @@
      Record only task-specific authority. Omitted fields inherit versioned
      defaults: Owner is the current Keel agent, Mode is implementation, Read
      is the change proposal/design/specs/tasks plus discovered repository
-     context, Acceptance derives from Covers, Coupling defaults to none, and
-     helpers stay read-only/evidence-only. Autonomy defaults to hard-stop, and
+     context, Acceptance derives from Covers, Coupling defaults to none,
+     helpers stay read-only/evidence-only, and delegation defaults to none —
+     declare `Delegation: <tier>` only to override what `keel/config.yaml`
+     supplies. Autonomy defaults to hard-stop, and
      commit, push, sync, archive, and cross-task continuation stay unauthorized,
      EXCEPT where `keel/config.yaml` standing-authorizes an action: a task that
      authors no `Autonomy boundary:` inherits that declaration, and the capsule

package/bin/keel.js

@@ -72,7 +72,14 @@ const OPENSPEC_SKILLS = [
   "openspec-sync-specs",
   "openspec-archive-change",
 ];
-const OPENSPEC_OVERLAY_ACTIONS = ["propose", "apply", "archive"];
+// `sync` is here because `AGENTS.md` gates it exactly as it gates archive —
+// `keel gate change-close --action sync|archive` plus `keel-review-checklist`.
+// Archive's surface said so and sync's said nothing, so an agent invoking
+// `/opsx:sync` read generic upstream instructions with no mention of the gate
+// that decides whether the sync may complete. `explore` is deliberately absent:
+// it reads and reports, reaches no gate, and changes no state, so an overlay
+// there would read as governance where there is none.
+const OPENSPEC_OVERLAY_ACTIONS = ["propose", "apply", "archive", "sync"];
 const OPENSPEC_SURFACE_OVERLAY_START =
   `<!-- keel:openspec-surface-overlay version=${PACKAGE_JSON.version} -->`;
 const OPENSPEC_SURFACE_OVERLAY_END =
@@ -614,31 +621,16 @@ function parseArgs(argv) {
   return parsed;
 }
 
-function pythonCandidates() {
-  if (process.env.KEEL_PYTHON) {
-    return [{ command: process.env.KEEL_PYTHON, prefixArgs: [] }];
-  }
-
-  const candidates = [];
-  if (process.platform === "win32") {
-    candidates.push({ command: "py", prefixArgs: ["-3"] });
-    candidates.push({ command: "python", prefixArgs: [] });
-    candidates.push({ command: "python3", prefixArgs: [] });
-  } else {
-    candidates.push({ command: "python3", prefixArgs: [] });
-    candidates.push({ command: "python", prefixArgs: [] });
-  }
-  return candidates;
-}
-
-function commandExists(candidate) {
-  const result = spawnSync(
-    candidate.command,
-    [...candidate.prefixArgs, "--version"],
-    { encoding: "utf8" }
-  );
-  return !result.error && result.status === 0;
-}
+// The interpreter rule lives in `scripts/run_python.js` and is imported rather
+// than restated. This file used to carry its own candidate list that asked only
+// whether a command runs, so `keel --doctor` reported `python3: ok` for the
+// same 3.9.6 the runner refuses — measured 2026-08-02. Two statements of one
+// threshold drift the moment either moves; one statement cannot.
+const {
+  MINIMUM_PYTHON,
+  resolveInterpreter,
+  describeTried,
+} = require(path.join(__dirname, "..", "scripts", "run_python.js"));
 
 function npmCommand() {
   return process.platform === "win32" ? "npm.cmd" : "npm";
@@ -688,6 +680,56 @@ function runCommand(command, args, options = {}) {
   return typeof result.status === "number" ? result.status : 1;
 }
 
+// Which OpenSpec answered is not cosmetic. `openspecCandidates` prefers the
+// installed dependency and otherwise falls back to PATH in silence, so a
+// worktree with no `node_modules` validates against whatever version happens
+// to be installed globally — measured here as 1.4.1 against a lockfile that
+// resolves 1.6.0, which rejects a requirement the shipped template writes.
+// A green pipeline and a red worktree were the same command run against two
+// different programs. Keel states which one; it does not install or select.
+function openspecReportedVersion(command) {
+  const result = spawnSync(command, ["--version"], {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+  });
+  if (result.error || result.status !== 0) return null;
+  const match = `${result.stdout || ""}${result.stderr || ""}`.match(
+    /\d+\.\d+\.\d+/
+  );
+  return match ? match[0] : null;
+}
+
+// The root is the repository under diagnosis, never PACKAGE_ROOT. Rooting this
+// at Keel's own install location made the line a statement about a repository
+// the reader was never shown: a consumer pinning 9.9.9 was told the version
+// Keel's checkout pins, and a global install — which ships no lockfile — was
+// told `unreadable` forever, which is exactly the drift this check was added
+// to expose. There is no fallback to PACKAGE_ROOT on purpose; falling back
+// would reinstate the misattribution and leave the reader unable to tell which
+// case they were in.
+//
+// Three outcomes, not two. A repository with no lockfile and one whose lockfile
+// names no OpenSpec both *declare* nothing, which is the ordinary case for any
+// project that does not depend on OpenSpec directly. A lockfile that exists and
+// cannot be parsed is a read failure. Collapsing them would either warn at
+// everyone or hide a real failure.
+function declaredOpenSpecVersion(repo) {
+  const lockPath = path.join(repo, "package-lock.json");
+  if (!fs.existsSync(lockPath)) return { state: "none", version: null };
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+  } catch {
+    return { state: "unreadable", version: null };
+  }
+  for (const [name, entry] of Object.entries(lock.packages || {})) {
+    if (name.endsWith("@fission-ai/openspec") && entry && entry.version) {
+      return { state: "declared", version: entry.version };
+    }
+  }
+  return { state: "none", version: null };
+}
+
 function findOpenSpecCommand() {
   for (const command of openspecCandidates()) {
     const status = runCommand(command, ["--version"], {
@@ -826,10 +868,8 @@ function runPython(script, args) {
     return 1;
   }
 
-  for (const candidate of pythonCandidates()) {
-    if (!commandExists(candidate)) {
-      continue;
-    }
+  const { candidate, tried } = resolveInterpreter();
+  if (candidate) {
     const result = spawnSync(
       candidate.command,
       [...candidate.prefixArgs, script, ...args],
@@ -838,8 +878,11 @@ function runPython(script, args) {
     return typeof result.status === "number" ? result.status : 1;
   }
 
+  const minimum = MINIMUM_PYTHON.join(".");
   process.stderr.write(
-    "keel: Python 3 is required. Install python3/python, or set KEEL_PYTHON.\n"
+    `keel: Python ${minimum} or newer is required. Tried `
+      + `${describeTried(tried) || "nothing"}. Install one, or set `
+      + "KEEL_PYTHON.\n"
   );
   return 1;
 }
@@ -999,12 +1042,12 @@ function openspecOverlaySurfacesForTarget(target, repo) {
     if (action === "propose" && target === "opencode") {
       return [];
     }
-    const skillName =
-      action === "propose"
-        ? "openspec-propose"
-        : action === "apply"
-          ? "openspec-apply-change"
-          : "openspec-archive-change";
+    const skillName = {
+      propose: "openspec-propose",
+      apply: "openspec-apply-change",
+      archive: "openspec-archive-change",
+      sync: "openspec-sync-specs",
+    }[action];
     return [
       {
         action,
@@ -1018,11 +1061,23 @@ function openspecOverlaySurfacesForTarget(target, repo) {
   });
 }
 
+// Derived from the managed set rather than written beside it. The label was
+// the literal string "apply/archive", which was correct while those were the
+// managed actions and became wrong — silently — the moment a third joined them.
+// `propose` is excluded because its overlay governs authoring rather than a
+// state-changing command, and the doctor line counts the command surfaces.
+function overlayActionLabel() {
+  return OPENSPEC_OVERLAY_ACTIONS.filter((action) => action !== "propose")
+    .join("/");
+}
+
 function overlayTitleForAction(action) {
-  if (action === "propose") return "Keel Authoring Overlay";
-  return action === "apply"
-    ? "Keel Apply Overlay"
-    : "Keel Archive Overlay";
+  return {
+    propose: "Keel Authoring Overlay",
+    apply: "Keel Apply Overlay",
+    archive: "Keel Archive Overlay",
+    sync: "Keel Sync Overlay",
+  }[action];
 }
 
 function keelOpenSpecOverlay(action) {
@@ -1046,6 +1101,33 @@ function keelOpenSpecOverlay(action) {
     ];
     return lines.join("\n");
   }
+  // Sync mirrors archive's structure and not its content: the two are gated and
+  // owned identically, so the ownership, subagent, and delegation-language
+  // rules are the same statements with `sync` in them. What differs is the
+  // artifact consequence — archive warns about re-applying a promoted delta,
+  // and sync is the thing that promotes it, so it says so from its own side. A
+  // reader who only ever sees one of the two surfaces still learns the pairing.
+  const syncBody = [
+    "- The current agent owns the sync decision and must verify task evidence, follow-up ownership, and completion gates before proceeding.",
+    "- Sync completion is gated by `keel gate change-close --action sync` plus `keel-review-checklist`; there is no runtime hook for it, so running the gate is the agent's own step.",
+    "- Before syncing, each related critical expectation must have behavior evidence, a durable follow-up owner, or an explicit discard reason.",
+    "- Target-native subagents may help with bounded assessment or evidence production only; they cannot sync, change acceptance, or bypass completion gates.",
+    "- Do not treat generic OpenSpec sync delegation language as authority to transfer Keel ownership.",
+    "- Invoke OpenSpec through `keel openspec` (for example `keel openspec validate`); a bare `openspec` command may not be on PATH.",
+    "- Syncing promotes the change's spec delta into `openspec/specs/`. A later archive of the same change must use `--skip-specs`, because archive is not idempotent over an already-promoted delta.",
+  ];
+  if (action === "sync") {
+    return [
+      OPENSPEC_SURFACE_OVERLAY_START,
+      `## ${overlayTitleForAction(action)}`,
+      "",
+      "Keel rules below take precedence over conflicting generic OpenSpec instructions in this file.",
+      "",
+      ...syncBody,
+      OPENSPEC_SURFACE_OVERLAY_END,
+      "",
+    ].join("\n");
+  }
   const actionBody =
     action === "apply"
       ? [
@@ -1054,7 +1136,7 @@ function keelOpenSpecOverlay(action) {
           "- Run the Slice Start Gate: selected current slices must name source expectations and include Read, Touch, Acceptance, Commands, and Stop/Autonomy boundaries before implementation.",
           "- Rough future slices may remain drafts, but cannot be selected for implementation or marked complete.",
           "- Obey the selected task contract: Read is required starting context, Touch is the write boundary, Commands prove Acceptance, and the Autonomy boundary controls fallback decisions.",
-          "- Target-native subagents return report/evidence only; they cannot mark tasks complete, update OpenSpec state, commit, sync, archive, or change Acceptance.",
+          "- A target-native helper returns report/evidence only, and a declared delegate may write inside `Touch`; both cannot mark tasks complete, update OpenSpec state, commit, sync, archive, or change Acceptance.",
           "- The current agent reviews all subagent output, command evidence, and diffs before marking any task complete.",
           "- When implementation exposes a material expectation, acceptance boundary, or user-owned decision absent from durable authority, stop before implementing that choice, rerun `keel-align-expectations`, and reauthor the affected proposal/design/spec/task authority first.",
           "- A discovered repository fact that does not change accepted behavior or scope may be recorded and execution continues inside the existing task boundary without a product interview.",
@@ -1084,9 +1166,11 @@ function keelOpenSpecOverlay(action) {
     "### Target-native subagent gate",
     "",
     "- The current agent remains responsible for Keel ownership, task/archive decisions, scope control, and final reporting.",
-    "- Use a target-native subagent only when the current agent decides it is useful for a bounded helper step.",
-    "- Target-native subagents return report/evidence only; the current agent reviews the output before acting.",
-    "- The subagent brief must name the selected change/task, required read context, allowed write boundary or read-only diagnostic scope, expected commands/evidence, and prohibited actions.",
+    "- Use a target-native subagent when the current agent decides it is useful for a bounded helper step, or as a delegate implementing the selected task where `delegation:` is declared in `keel/config.yaml` and a guard manifest is active.",
+    "- Target-native subagents acting as helpers return report/evidence only. A delegate may write, and only inside `Touch`; its reported command results are a claim, and the current agent re-runs each `M<n>` check itself before recording Evidence.",
+    "- Delegation is refused with no active guard manifest, because an absent manifest passes every write through silently and looks identical to a checked one.",
+    "- Neither may mark tasks complete, update OpenSpec state, commit, sync, archive, or change Acceptance; the current agent reviews all output before acting.",
+    "- The subagent brief must name the selected change/task, required read context, allowed write boundary or read-only diagnostic scope, expected commands/evidence, and prohibited actions. Compile it with `keel project --event subagent-start --authorize subagent`; Keel adds no separate carrier because the host already has one.",
     "- Prohibited actions include scope expansion, Acceptance changes, completion marking, sync/archive decisions, commits, handoff changes, and cross-runtime delegation unless the selected task or user explicitly authorizes them.",
     ...actionBody,
     OPENSPEC_SURFACE_OVERLAY_END,
@@ -1292,13 +1376,13 @@ function printTargetSurface(repo, target) {
   const overlayCounts = countOpenSpecOverlays(overlayPaths);
   const overlayDetail =
     surfaceStatus(overlayCounts) === "ok"
-      ? formatCount(overlayCounts, "apply/archive skills and commands")
+      ? formatCount(overlayCounts, `${overlayActionLabel()} skills and commands`)
       : `${formatCount(
           overlayCounts,
-          "apply/archive skills and commands"
+          `${overlayActionLabel()} skills and commands`
         )}; ${overlayRemediation(target)}`;
   printDoctorLine(
-    "Keel apply/archive overlay",
+    `Keel ${overlayActionLabel()} overlay`,
     surfaceStatus(overlayCounts),
     overlayDetail
   );
@@ -1318,12 +1402,28 @@ function runDoctor(options) {
   const repo = path.resolve(options.repo || process.cwd());
   process.stdout.write(`keel doctor for ${repo}\n`);
 
-  const python = pythonCandidates().find(commandExists);
-  printDoctorLine(
-    "python3",
-    python ? "ok" : "missing",
-    python ? formatCommand(python.command, python.prefixArgs) : "set KEEL_PYTHON or install Python 3"
-  );
+  // The version is printed, not just a verdict: `ok` with no number behind it
+  // is a claim the reader cannot check, and it was the wrong claim here for as
+  // long as this line existed.
+  const minimumPython = MINIMUM_PYTHON.join(".");
+  const interpreter = resolveInterpreter();
+  if (interpreter.candidate) {
+    printDoctorLine(
+      "python3",
+      "ok",
+      `${formatCommand(interpreter.candidate.command, interpreter.candidate.prefixArgs)}`
+        + ` (${interpreter.version})`
+    );
+  } else {
+    const runnable = interpreter.tried.filter((entry) => entry.version);
+    printDoctorLine(
+      "python3",
+      runnable.length > 0 ? "problem" : "missing",
+      runnable.length > 0
+        ? `needs ${minimumPython} or newer; found ${describeTried(runnable)}`
+        : `needs ${minimumPython} or newer; set KEEL_PYTHON or install Python 3`
+    );
+  }
 
   const openspec = findOpenSpecCommand();
   if (!openspec) {
@@ -1339,12 +1439,34 @@ function runDoctor(options) {
         stdio: "ignore",
         silentNotFound: true,
       }) === 0;
+    const resolvedVersion = openspecReportedVersion(openspec);
+    const declared = declaredOpenSpecVersion(repo);
+    const mismatched = Boolean(
+      resolvedVersion
+      && declared.state === "declared"
+      && resolvedVersion !== declared.version
+    );
+    const where = bareOpenSpecOnPath
+      ? openspec
+      : `${openspec} is keel-resolvable but bare \`openspec\` is not on PATH — use \`keel openspec\``;
+    // Two versions on one line need two owners. `repo` is the repository named
+    // on doctor's first line; the answering build is attributed by the path
+    // already printed beside it.
+    const declaredText = {
+      declared: `repo pins ${declared.version}`,
+      none: "repo declares no OpenSpec version",
+      unreadable: "repo package-lock.json unreadable",
+    }[declared.state];
+    const versions = `${resolvedVersion || "version unreadable"}, ${declaredText}`;
     printDoctorLine(
       "openspec",
-      bareOpenSpecOnPath ? "ok" : "warning",
-      bareOpenSpecOnPath
-        ? openspec
-        : `${openspec} is keel-resolvable but bare \`openspec\` is not on PATH — use \`keel openspec\``
+      mismatched || !bareOpenSpecOnPath ? "warning" : "ok",
+      mismatched
+        ? `${where} (${versions}) — validation is answering from a different `
+          + "build than this repository pins, which is what a green pipeline "
+          + "and a red worktree look like. Keel reports which one answered "
+          + "and selects none."
+        : `${where} (${versions})`
     );
   }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.7.0",
+  "version": "5.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.7.0",
+  "version": "5.16.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.7.0",
+  "version": "5.16.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/agents/keel-single-task-goal-claude.md

@@ -1,6 +1,6 @@
 ---
 name: keel-single-task-goal-claude
-description: Thin Claude activation adapter for one authorized OpenSpec task; single /goal within the 4,000-character budget with read-only subagent helpers only.
+description: Thin Claude activation adapter for one authorized OpenSpec task; single /goal within the 4,000-character budget; the current agent keeps sole write authority.
 target: claude
 role: single-task-goal-activation
 ---
@@ -11,6 +11,7 @@ Thin Claude adapter for the `keel-run-single-task-goal` skill. It activates one
 
 - Activation: compile the view with `keel project goal --target claude --change C --task T --json`; the goal condition stays within the 4,000-character budget, and Keel refuses activation rather than omit Acceptance, fingerprint, or stop authority.
 - Evidence: Claude's evaluator is transcript-only, so surface every command result and gate outcome before any success claim; only `keel gate task-complete` plus the current agent's durable checkbox complete the task.
-- Helpers: Claude subagents are used only as bounded read-only evidence producers via `keel project helper`; they carry no write, delegation, acceptance, or completion authority, and their returns are accepted only after repository byte identity.
+- Helpers: Claude subagents used as helpers are bounded read-only evidence producers via `keel project helper`; they carry no write, delegation, acceptance, or completion authority, and their returns are accepted only after repository byte identity.
+- Delegates: where `delegation:` is declared and a guard manifest is active, a subagent may implement inside `Touch`. The current agent keeps sole write authority, re-runs each `M<n>` check itself before recording Evidence, and owns Review, gates, the checkbox, and completion.
 - Stop: terminate after one task on completion, drift, blocker, or premature native success; continuing requires a new explicit authorization and start fingerprint.
 - Fallback: with disabled hooks, managed policy, or missing trust, report and run the identical manual Keel loop.

package/plugins/keel/agents/keel-single-task-goal-codex.md

@@ -1,6 +1,6 @@
 ---
 name: keel-single-task-goal-codex
-description: Thin Codex activation adapter for one authorized OpenSpec task; bounded goal execution with read-only subagent helpers only.
+description: Thin Codex activation adapter for one authorized OpenSpec task; bounded goal execution; the current agent keeps sole write authority.
 target: codex
 role: single-task-goal-activation
 ---
@@ -10,7 +10,7 @@ role: single-task-goal-activation
 Thin Codex adapter for the `keel-run-single-task-goal` skill. It activates one bounded goal for exactly one authorized OpenSpec task and never introduces a scheduler, global stop hook, agent team, or cross-task authority.
 
 - Activation: compile the view with `keel project goal --target codex --change C --task T --json`, then follow the single-task goal lifecycle. Where no callable goal surface exists, surface the exact command and treat the capability as advisory.
-- Ownership: the current agent stays the sole writer and owns Review, gates, the checkbox, and completion; a native evaluator success never completes the task.
+- Ownership: the current agent stays the sole holder of write authority and owns Review, gates, the checkbox, and completion; a native evaluator success never completes the task. A declared delegate writes only inside `Touch`, and the current agent re-runs each `M<n>` check before recording Evidence.
 - Helpers: Codex subagents are used only as bounded read-only evidence producers via `keel project helper`; they carry no write, delegation, acceptance, or completion authority, and their returns are accepted only after repository byte identity.
 - Stop: terminate after one task on completion, drift, blocker, or premature native success; continuing requires a new explicit authorization and start fingerprint.
 - Fallback: without a callable Codex surface, run the identical manual Keel loop.

package/plugins/keel/scripts/pretooluse-guard.js

@@ -109,6 +109,41 @@ function taskIsChecked(repo, manifest) {
   return Boolean(match && match[1].toLowerCase() === "x");
 }
 
+// A path is not the file it names. `path.resolve` never follows a symbolic
+// link, while the `cwd` the operating system reports usually already has, so
+// one file could be spelled two ways and get two containment answers: measured
+// as a write denied by its resolved path and allowed through a link to the
+// same directory, which walked straight past the manifest. The guarded target
+// is usually a file about to be created, so what can be resolved is its
+// nearest existing ancestor; when nothing resolves, the unresolved path is
+// what remains, which is exactly the comparison that shipped.
+//
+// `src/core/helper.js` answers the same question and must keep answering it
+// the same way. It is deliberately not shared as an import: this hook is a
+// standalone script the host executes, and depending on `src/core` would make
+// the guard fail wherever the package layout differs from this repository's.
+function realPathOrNearest(target) {
+  let current = path.resolve(target);
+  const trailing = [];
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(current), ...trailing);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return path.resolve(target);
+      trailing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+function repoRelative(repo, target) {
+  return path.relative(
+    realPathOrNearest(repo),
+    realPathOrNearest(path.resolve(repo, target))
+  );
+}
+
 function main() {
   let event = {};
   try {
@@ -130,8 +165,13 @@ function main() {
   // guard never protected; that ordering has already failed twice.
   const target = event.tool_input ? event.tool_input[pathField] : null;
   if (typeof target !== "string" || !target) return 0;
-  const relative = path.relative(repo, path.resolve(repo, target));
-  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+  const relative = repoRelative(repo, target);
+  if (
+    !relative
+    || relative === ".."
+    || relative.startsWith(`..${path.sep}`)
+    || path.isAbsolute(relative)
+  ) {
     return 0;
   }
   const candidate = relative.replace(/\\/g, "/");
@@ -154,6 +194,29 @@ function main() {
     return 0;
   }
   const pointer = `${manifest.change}#${manifest.task}`;
+  // Two states used to arrive at the same place, and they need different
+  // answers. A task id absent from a live `tasks.md` is a parse miss the guard
+  // must not guess about — see `taskIsChecked`. A change directory that is not
+  // there at all is a fact: the manifest points at work that has been archived
+  // or removed, and `keel guard status` already classifies it as drifted.
+  //
+  // Untreated, the archived case was wrong in both directions. A write outside
+  // the stale Touch was denied by a message naming a task in an archived change
+  // and telling the reader to reauthorize it, which cannot be done; a write
+  // *inside* it passed silently, so an archived task went on granting write
+  // authority. Denying here fixes both, and denying rather than allowing is
+  // what stops `openspec archive` from quietly disabling the guard.
+  const changeDir = path.join(repo, "openspec", "changes", manifest.change);
+  if (!fs.existsSync(changeDir)) {
+    deny(
+      `Keel write guard: this manifest is stale — it guards ${pointer}, but `
+        + `openspec/changes/${manifest.change} no longer exists, so the task it `
+        + "names cannot be reauthorized and its Touch list authorizes nothing. "
+        + "File edits fail closed. Run `keel guard clear`, then start the task "
+        + "you are actually working on with `keel gate task-start`."
+    );
+    return 0;
+  }
   // The record layer: the guarded change's own directory holds the records the
   // task produces — its checkbox, Evidence, and Review — not the product it
   // changes. `keel gate task-complete` already refuses to attribute this

package/plugins/keel/scripts/session-start.js

@@ -108,6 +108,88 @@ function precedentPointer(cwd) {
   }
 }
 
+// The remedy is the host's, so it is named rather than run. Only Claude's
+// command is stated outright, because that is the manifest whose host command
+// Keel has verified; an unprobed target gets a description instead of an
+// invented command line.
+const HOST_UPDATE = "your host's own plugin update command";
+
+// The plugin's own manifest sits beside this script, so its version is read
+// from `__dirname` rather than from CLAUDE_PLUGIN_ROOT: the path this file was
+// loaded from is a fact, while an environment variable is a claim the host may
+// not have made. Whichever target's manifest is present is the one that ran.
+function pluginManifest() {
+  const targets = [
+    [".claude-plugin", "`claude plugin update`"],
+    [".codex-plugin", HOST_UPDATE],
+  ];
+  for (const [dir, remedy] of targets) {
+    try {
+      const manifest = path.join(__dirname, "..", dir, "plugin.json");
+      const value = JSON.parse(fs.readFileSync(manifest, "utf8")).version;
+      if (typeof value === "string" && value.trim()) {
+        return { version: value.trim(), remedy };
+      }
+    } catch {
+      // A missing or unreadable manifest is undiscoverable, not drift.
+    }
+  }
+  return { version: null, remedy: HOST_UPDATE };
+}
+
+// The repository states which protocol it runs in the managed block the
+// installer wrote. AGENTS.md is the canonical carrier; CLAUDE.md is read second
+// because a repository may carry only the target-native file.
+function protocolVersion(cwd) {
+  for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+    try {
+      const text = fs.readFileSync(path.join(cwd, name), "utf8");
+      const match = text.match(
+        /<!--\s*keel:start\s+version=(\d+\.\d+\.\d+)\s*-->/
+      );
+      if (match) return match[1];
+    } catch {
+      // Same as above: absent is not mismatched.
+    }
+  }
+  return null;
+}
+
+// Three versions are comparable in any repository: the plugin executing this
+// hook, the CLI it just invoked, and the protocol version the repository
+// stamped into its managed block. Keel reports the disagreement and stops
+// there — installing and updating are the host's, which already has commands
+// for both.
+function versionReport(cwd, cli) {
+  const plugin = pluginManifest();
+  const found = [
+    ["plugin", plugin.version],
+    ["CLI", cli],
+    ["protocol", protocolVersion(cwd)],
+  ];
+  // Missing is not mismatched. A version nobody can discover never produces a
+  // line on its own, or a repository with no managed block would be warned at
+  // every session until its reader stopped looking — and fewer than two
+  // readable versions is not agreement either, it is nothing to compare.
+  const known = found.filter(([, value]) => value);
+  if (known.length < 2) return null;
+  // Silence when they agree. This line exists to be noticed, and one printed
+  // every session stops being read long before the session it mattered in.
+  if (new Set(known.map(([, value]) => value)).size === 1) return null;
+  const named = known.map(([name, value]) => `${name} ${value}`).join(", ");
+  // Naming what was never read is what keeps a partial comparison from being
+  // read as a complete one.
+  const unread = found
+    .filter(([, value]) => !value)
+    .map(([name]) => name)
+    .join(" and ");
+  const missing = unread ? ` (${unread} undiscovered, not compared)` : "";
+  return `runtime versions disagree: ${named}${missing}. A session's hooks are `
+    + "fixed at session start, so an updated plugin applies only after "
+    + `restarting. Updating is ${plugin.remedy}, which Keel names and does `
+    + "not run.";
+}
+
 // The Keel mark. A keel is the carina, the ridge on a bird's sternum, so the
 // animal that literally has one is a bird. Every cell is drawn from
 // U+2580–U+259F — the same block-element family as the host's own startup
@@ -293,6 +375,11 @@ function main() {
         + "does not guess among candidates."
     );
   }
+  const drift = versionReport(cwd, versionMatch[0]);
+  if (drift) {
+    lines.push(`- ${drift}`);
+    human.splice(human.length - 1, 0, drift[0].toUpperCase() + drift.slice(1));
+  }
   const pointer = precedentPointer(cwd);
   if (pointer) lines.push(`- ${pointer}`);
   lines.push(`- report this state ${DISCLOSURE}; it authorizes nothing.`);