@christang/keel 5.7.0 → 5.16.0

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

@@ -21,7 +21,9 @@ 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.
-- When no trustworthy explicit Git base exists, do not attribute dirty paths automatically. Review scope semantically.
+- 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.
+- Scope attribution is now the gate's job by default: `keel gate task-complete` compares the worktree against the dirty set `task-start` recorded and refuses a path outside Touch, so a `pass` is evidence about scope rather than silence about it. Two cases still need you. When the gate reports paths as *unattributed* — no recorded set, because the manifest predates the field or the guard was cleared — nothing was checked and the review is the only scope evidence. And a path already dirty when the task started is never attributed even if the task changed it again, so read the gate's silence about such a path as absence of a check rather than absence of a write.
 - For `Coupling: required`, confirm one complete candidate reached its completion gate and generated artifacts are aligned.
 
 ## Semantic Review
@@ -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());
+}