@christang/keel 5.6.0 → 5.14.0

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-align-expectations/SKILL.md

@@ -71,6 +71,27 @@ Three rules govern use:
 A precedent informs a decision and never substitutes for a proof: gates, evidence, Review, and the
 write guard are untouched by anything in the store.
 
+## Unattended runs
+
+Work enters an unattended run only by the repository's declared triage policy — an issue carrying a
+label listed under `triage:` in `keel/config.yaml`, evaluated with `keel triage --labels <labels>`.
+Pass what `gh` returned; Keel never fetches the issue. Admission comes from that declaration and
+never from a precedent, however much triage history the store accumulates: whether an issue becomes
+work is a materiality decision, and a precedent may not move one out of that list.
+
+Admission answers "may this begin" and decides nothing after it. Alignment still escalates material
+choices, the gates still run, and the write guard still binds.
+
+An unattended run may triage, author, implement, verify, push where `authorize:` permits, and
+**open a pull request**. It **may not merge** one — merging is where an unreviewed decision becomes
+the project's history, and no declaration in Keel authorizes it.
+
+Stopping at a decision the user must make is the **designed boundary rather than a failure**.
+Report where the run stopped and why. Do not widen the triage policy to stop it happening.
+
+**Keel schedules nothing.** `/loop`, cron, and CI triggers belong to the host runtime; Keel's part
+is making each step decidable with authority.
+
 ## Domain lenses
 
 When the change signals a specific domain, look in `keel/lenses/` for a lens whose `Applies when:` header matches, and read only that lens before asking domain questions; do not load unrelated lenses. When no lens matches, or the repo defines none, proceed on the domain-agnostic path. Lenses are user-authored; scaffold the bundled starting points with `keel lenses add` (web, hardware, hardware-dsl).

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

package/plugins/keel/skills/keel-run-single-task-goal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keel-run-single-task-goal
-description: Use when the user explicitly authorizes automatic execution or resume of exactly one OpenSpec task on Codex or Claude. Drives the single-task native goal lifecycle through Keel gates, keeps the current agent the sole writer, and stops at the task boundary. Never activate for ordinary apply, proposal work, ambiguous or multiple tasks, or OpenCode.
+description: Use when the user explicitly authorizes automatic execution or resume of exactly one OpenSpec task on Codex or Claude. Drives the single-task native goal lifecycle through Keel gates, keeps the current agent the sole holder of write authority, and stops at the task boundary. Never activate for ordinary apply, proposal work, ambiguous or multiple tasks, or OpenCode.
 license: UNLICENSED
 metadata:
   keel-role: single-task-goal-activation
@@ -11,7 +11,7 @@ metadata:
 
 ## Purpose
 
-Activate a native goal or subagent runtime to execute exactly one authorized OpenSpec task end to end, while OpenSpec, Git, the task-capsule fingerprint, and deterministic Keel gates stay the only durable authority. The current agent remains the sole writer and owns Review, gate invocation, the task checkbox, and completion. A native evaluator declaring success never marks or reports the task complete.
+Activate a native goal or subagent runtime to execute exactly one authorized OpenSpec task end to end, while OpenSpec, Git, the task-capsule fingerprint, and deterministic Keel gates stay the only durable authority. The current agent remains the sole holder of write authority and owns Review, gate invocation, the task checkbox, and completion. Where delegation is declared, an authorized delegate may write inside the `Touch` boundary that authority already defined and acquires none of those decisions; the current agent re-runs each `M<n>` check itself before recording Evidence, because a delegate's reported result is a claim and the byte-identity check that validates a read-only helper cannot apply to a writer. A native evaluator declaring success never marks or reports the task complete.
 
 ## Authoritative sources and provenance
 
@@ -37,7 +37,7 @@ Activate only on an explicit, unambiguous request to automatically execute or re
 - Proposal, design, or spec authoring before tasks are final.
 - Ambiguous selection, multiple tasks, or a whole task group or change backlog.
 - An unrelated native `/goal` use that is not a Keel OpenSpec task.
-- Unrequested helpers or any request to delegate implementation to another agent.
+- Unrequested helpers, or an undeclared delegation of implementation to another agent.
 - OpenCode, which stays manual compatibility only with no v4 native activation.
 
 If any of these hold, stop and use the normal manual Keel loop.

package/scripts/run_python.js

@@ -3,32 +3,108 @@
 
 const { spawnSync } = require("child_process");
 
+// The suite calls `tempfile.TemporaryDirectory(ignore_cleanup_errors=…)`,
+// added in 3.10. Accepting any interpreter whose `--version` exits zero meant
+// macOS system Python 3.9 ran the suite and failed ten scenarios with messages
+// naming ten unrelated features — the reader is then debugging the suite
+// instead of installing an interpreter.
+//
+// This is the one definition. `bin/keel.js` 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 this file refuses — two Keel surfaces
+// answering one question with opposite verdicts, and the one a person runs
+// deliberately to check their environment was the wrong one.
+const MINIMUM_PYTHON = [3, 10];
+
+// The newest minor worth looking for under a versioned name. Names are
+// generated from MINIMUM_PYTHON up to this, newest first, so raising the
+// minimum drops the names below it with no second edit; only this bound moves
+// when a new Python is released.
+const NEWEST_KNOWN_PYTHON_MINOR = 13;
+
+// Versioned names matter because the unversioned one is often not the usable
+// one. On macOS `python3` is the system 3.9 while Homebrew installs
+// `python3.11` beside it, so a search that stops at `python3` refuses with
+// "install a newer Python" addressed to someone who already did.
+function versionedPythonNames() {
+  const names = [];
+  for (let minor = NEWEST_KNOWN_PYTHON_MINOR; minor >= MINIMUM_PYTHON[1]; minor -= 1) {
+    names.push({ command: `python${MINIMUM_PYTHON[0]}.${minor}`, prefixArgs: [] });
+  }
+  return names;
+}
+
 function pythonCandidates() {
+  // An explicit choice is not overridden by discovery.
   if (process.env.KEEL_PYTHON) {
     return [{ command: process.env.KEEL_PYTHON, prefixArgs: [] }];
   }
 
+  // Unversioned names first, so a machine where the default interpreter
+  // already satisfies the minimum behaves exactly as it did before.
   if (process.platform === "win32") {
     return [
       { command: "py", prefixArgs: ["-3"] },
       { command: "python", prefixArgs: [] },
       { command: "python3", prefixArgs: [] },
+      ...versionedPythonNames(),
     ];
   }
 
   return [
     { command: "python3", prefixArgs: [] },
     { command: "python", prefixArgs: [] },
+    ...versionedPythonNames(),
   ];
 }
 
-function commandExists(candidate) {
+function label(candidate) {
+  return [candidate.command, ...candidate.prefixArgs].join(" ");
+}
+
+function reportedVersion(candidate) {
   const result = spawnSync(
     candidate.command,
     [...candidate.prefixArgs, "--version"],
     { encoding: "utf8" }
   );
-  return !result.error && result.status === 0;
+  if (result.error || result.status !== 0) return null;
+  // Python 2 wrote `--version` to stderr, so read both streams: an old
+  // interpreter should be reported by its version rather than dismissed as
+  // unreadable.
+  const match = `${result.stdout || ""}${result.stderr || ""}`.match(
+    /(\d+)\.(\d+)(?:\.(\d+))?/
+  );
+  return match ? match[0] : null;
+}
+
+function meetsMinimum(version) {
+  const parts = String(version || "").split(".").map(Number);
+  const [major, minor] = parts;
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) return false;
+  if (major !== MINIMUM_PYTHON[0]) return major > MINIMUM_PYTHON[0];
+  return minor >= MINIMUM_PYTHON[1];
+}
+
+// Resolve the interpreter both surfaces should agree about. Returns the chosen
+// candidate and every candidate tried with the version it reported, so the
+// caller can either run it or report why there is nothing to run.
+function resolveInterpreter() {
+  const tried = [];
+  for (const option of pythonCandidates()) {
+    const version = reportedVersion(option);
+    tried.push({ label: label(option), version });
+    if (version && meetsMinimum(version)) {
+      return { candidate: option, version, tried };
+    }
+  }
+  return { candidate: null, version: null, tried };
+}
+
+function describeTried(tried) {
+  return tried
+    .map((entry) => `${entry.label} (${entry.version || "not runnable"})`)
+    .join(", ");
 }
 
 function main() {
@@ -38,10 +114,15 @@ function main() {
     return 2;
   }
 
-  const candidate = pythonCandidates().find(commandExists);
+  const { candidate, tried } = resolveInterpreter();
   if (!candidate) {
+    const minimum = MINIMUM_PYTHON.join(".");
     process.stderr.write(
-      "run_python: could not find Python. Install python3/python or set KEEL_PYTHON.\n"
+      `run_python: no Python ${minimum} or newer was found, and the suite `
+        + `needs one — tempfile.TemporaryDirectory(ignore_cleanup_errors=…) `
+        + `was added in ${minimum}.\n`
+        + `run_python: tried ${describeTried(tried) || "nothing"}.\n`
+        + "run_python: install a newer Python, or point KEEL_PYTHON at one.\n"
     );
     return 127;
   }
@@ -60,4 +141,19 @@ function main() {
   return result.status ?? 1;
 }
 
-process.exit(main());
+// `bin/keel.js` requires this file for the definitions above, so the script
+// only runs when it is the entry point. Two copies of the interpreter rule is
+// what this change exists to remove; importing is what keeps it at one.
+module.exports = {
+  MINIMUM_PYTHON,
+  pythonCandidates,
+  versionedPythonNames,
+  reportedVersion,
+  meetsMinimum,
+  resolveInterpreter,
+  describeTried,
+};
+
+if (require.main === module) {
+  process.exit(main());
+}