@christang/keel 5.7.0 → 5.14.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.7.0 -->
+<!-- keel:start version=5.14.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,42 @@ 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;
+}
+
+function lockedOpenSpecVersion() {
+  try {
+    const lock = JSON.parse(
+      fs.readFileSync(path.join(PACKAGE_ROOT, "package-lock.json"), "utf8")
+    );
+    for (const [name, entry] of Object.entries(lock.packages || {})) {
+      if (name.endsWith("@fission-ai/openspec") && entry && entry.version) {
+        return entry.version;
+      }
+    }
+  } catch {
+    // No lockfile in a published install; there is then nothing to disagree
+    // with, which is not the same as agreement and is reported as such.
+  }
+  return null;
+}
+
 function findOpenSpecCommand() {
   for (const command of openspecCandidates()) {
     const status = runCommand(command, ["--version"], {
@@ -826,10 +854,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 +864,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 +1028,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 +1047,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 +1087,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 +1122,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 +1152,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 +1362,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 +1388,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 +1425,26 @@ function runDoctor(options) {
         stdio: "ignore",
         silentNotFound: true,
       }) === 0;
+    const resolvedVersion = openspecReportedVersion(openspec);
+    const locked = lockedOpenSpecVersion();
+    const mismatched = Boolean(
+      resolvedVersion && locked && resolvedVersion !== locked
+    );
+    const where = bareOpenSpecOnPath
+      ? openspec
+      : `${openspec} is keel-resolvable but bare \`openspec\` is not on PATH — use \`keel openspec\``;
+    const versions = `${resolvedVersion || "version unreadable"}, lockfile ${
+      locked || "unreadable"
+    }`;
     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.14.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.14.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.14.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.`);

package/plugins/keel/skills/keel-review-checklist/SKILL.md

@@ -21,6 +21,8 @@ Read the selected OpenSpec proposal, design, specs, tasks, diff, and command evi
 - Confirm the task's Evidence `Contract` line records the task-start capsule fingerprint and that completion recompiled the same fingerprint; a drift result returns the task to authoring for explicit reauthorization instead of review.
 - A behavioral task's checks must prove observable Acceptance through the public interface, not build-only or shape-only evidence.
 - For a red-green strategy (`vertical-tdd`, `regression-first`), confirm concrete per-label `.red` and `.green` Evidence exists for the same check; evidence-first tasks instead name their observable proof.
+- A failure message must **name the actual cause** of what it reports. Watch for one condition guarding **two distinct failures** — `if result is None or result["status"] != expected` reports the first failure's message when the second one happened, sending the reader to a place with no problem in it. Split the condition. No gate can judge this: deciding whether a sentence misleads needs a model, so it stays here.
+- When two tasks in the change declared the same Touch set under a red-green strategy — `keel gate task-start` warns about this — ask whether they turned out to be **one behavior** split in half. The tell is that the first task's minimal implementation was wrong in the field, or that the second had no honest red left because the first already made its checks pass. The gate can only see the shape; by completion you can see the outcome, which is the only point at which this is answerable.
 - When no trustworthy explicit Git base exists, do not attribute dirty paths automatically. Review scope semantically.
 - For `Coupling: required`, confirm one complete candidate reached its completion gate and generated artifacts are aligned.
 
@@ -31,7 +33,22 @@ Record the current agent's judgment inside the selected task Evidence:
 - `Status`: `pass` only when the task is ready to complete.
 - `Acceptance check`: why the behavior evidence proves the authored Acceptance.
 - `Scope check`: why the actual changes stay within Touch; identify an explicit base if deterministic comparison was used.
-- `Findings`: `none`, or each unresolved finding with a durable OpenSpec task/new change, archive-evidence owner, or explicit discard rationale.
+- `Findings`: `none`, or every finding with the disposition it actually has.
+
+A finding has three, and the criterion is what the task did about it — not
+whichever marker gets past the gate:
+
+- **`Resolved here:`** — found and fixed inside this task. Name what proves it:
+  an `M<n>` check this task declares, or a repo-relative path that exists. If no
+  check covers it, the fix is not proved and the finding is one of the other two.
+- **`Durable owner:`** — real, still open, and someone must do it. Name an
+  absolute `https://…` tracker reference or a repo-relative path that exists.
+  The reference must already carry the content it claims to hold.
+- **`Discard reason:`** — considered, and deliberately not being done. Say why.
+
+Picking the marker that passes rather than the one that is true is how a repair
+gets filed as a dismissal, and the archive then records the opposite of what
+happened.
 
 The Review remains in tasks.md. A user-facing Report summarizes delivery but is not hidden gate state. Do not let Core or this checklist write evidence automatically.
 
@@ -43,6 +60,13 @@ When the change's artifacts or Touch extensions signal a domain, consult the mat
 
 Each related critical expectation needs behavior evidence, a durable follow-up owner, or an explicit discard reason. Relevant `D<n>`, `F<n>`, `A<n>`, and `Q<n>` references in Covers must agree with their OpenSpec basis and resolution owner. Unresolved authority returns to OpenSpec authoring.
 
+A durable owner declared as a URL must **already carry the content** it claims to hold, at the moment
+it is cited. A valid link to an empty issue owns nothing: create the content, then reference it. Check
+this **when it is cited**, not at archive — a check deferred to the close finds the same fact after
+the reauthorization it should have prevented. This is **not a deterministic gate check** and must not
+become one: a gate that fetched a reference would stop being local and offline, which is the property
+its verdict rests on.
+
 `keel/HANDOFF.md` is an optional pointer override and cannot own findings, critical expectation state, evidence details, or follow-ups.
 
 ## Skill change review