@christang/keel 5.50.0 → 5.52.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.50.0 -->
+<!-- keel:start version=5.52.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/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.50.0",
+  "version": "5.52.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.50.0",
+  "version": "5.52.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.50.0",
+  "version": "5.52.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.50.0"
-PROTOCOL_VERSION = "5.50.0"
+PACKAGE_VERSION = "5.52.0"
+PROTOCOL_VERSION = "5.52.0"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 # Mirrors KEEL_PACKAGE_NAME in scripts/install_to_repo.py, one of the two
@@ -25222,6 +25222,300 @@ def validate_weakest_strategy_states_its_reason_scenario() -> int:
     return 0
 
 
+# A completed task fixture whose Review Findings the caller writes. Everything
+# else is the shape `task-complete` needs so that the only thing under test is
+# the Findings block.
+def findings_fixture_repo(root: Path, name: str, findings: str) -> Path:
+    repo = root / name
+    task = strategy_probe_task(strategy="vertical-tdd")
+    task = task.replace("- [ ] 1.1", "- [x] 1.1")
+    task = task.replace(
+        "    - M1: pending",
+        "    - M1: pass. node test.js reported 3 passing.\n"
+        "    - M1.red: fail, for the right reason. the assertion was absent.\n"
+        "    - M1.green: pass. node test.js reported 3 passing.",
+    )
+    task = task.replace("      - Findings: none", f"      - Findings: {findings}")
+    write_gate_fixture(repo, tasks=task)
+    started = run_keel(
+        repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+    )
+    fingerprint = json.loads(started.stdout)["contract"]["fingerprint"]["value"]
+    tasks_path = repo / "openspec/changes/demo/tasks.md"
+    tasks_path.write_text(
+        tasks_path.read_text(encoding="utf-8").replace(
+            "    - Contract: pending",
+            f"    - Contract: keel-task-capsule/v1 sha256:{fingerprint}",
+        ),
+        encoding="utf-8",
+    )
+    return repo
+
+
+def findings_completion(root: Path, name: str, findings: str) -> dict:
+    repo = findings_fixture_repo(root, name, findings)
+    result = run_keel(
+        repo, "gate", "task-complete", "--change", "demo", "--task", "1.1", "--json"
+    )
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return {"status": "unparsed", "problems": [{"message": result.stdout[:400]}]}
+
+
+# `Findings` is free prose by design, and in a repository whose subject is the
+# protocol that prose names the markers themselves. A quoted marker was read as
+# a disposition — and because the resolution scan is global and stops at the
+# first claim it cannot resolve, one mention eclipsed every real disposition
+# beside it. 5.42.0 already decided that an inline-code span holds quoted
+# material rather than an assertion; the rule had not reached this scan.
+def validate_quoted_marker_is_not_a_disposition_scenario() -> int:
+    label = "a-quoted-marker-is-not-a-disposition"
+    tracker = "https://github.com/TanglmChris/keel/issues/114"
+    with tempfile.TemporaryDirectory(prefix="keel-quoted-marker-") as raw:
+        root = Path(raw)
+
+        owned = findings_completion(
+            root,
+            "owned",
+            "one, still open. The `Resolved here:` grammar is what this finding "
+            f"is about. Durable owner: {tracker}",
+        )
+        if owned.get("status") != "pass":
+            report(
+                f"{label}: a quoted marker eclipsed a genuine tracker owner; "
+                f"{problem_codes(owned)!r} {problem_text(owned)!r}."
+            )
+            return 1
+
+        resolved = findings_completion(
+            root,
+            "resolved",
+            "one, fixed here. The `Durable owner:` form is what this finding is "
+            "about. Resolved here: M1",
+        )
+        if resolved.get("status") != "pass":
+            report(
+                f"{label}: a quoted marker eclipsed a genuine resolution; "
+                f"{problem_codes(resolved)!r} {problem_text(resolved)!r}."
+            )
+            return 1
+
+        # Every marker, not only the one that fired.
+        for index, marker in enumerate(
+            ("Resolved here:", "Durable owner:", "Discard reason:", "Discard rationale:")
+        ):
+            only = findings_completion(
+                root,
+                f"only-{index}",
+                f"one. The `{marker}` marker is the topic of this finding, and "
+                "nothing here disposes of it.",
+            )
+            codes = problem_codes(only)
+            if only.get("status") != "fail":
+                report(
+                    f"{label}: a block whose only {marker!r} is quoted was "
+                    "accepted, so the quotation created a disposition."
+                )
+                return 1
+            if "finding-resolution-evidence" in codes:
+                report(
+                    f"{label}: a block whose only {marker!r} is quoted was "
+                    "refused as a resolution with unusable evidence; it carries "
+                    f"no disposition at all. Codes {codes!r}."
+                )
+                return 1
+            if "finding-owner" not in codes:
+                report(
+                    f"{label}: a block whose only {marker!r} is quoted did not "
+                    f"report the missing-disposition problem. Codes {codes!r}."
+                )
+                return 1
+
+        # D5: the refusal names what it read.
+        misread = findings_completion(
+            root, "misread", "one. Resolved here: thoroughly, by rewriting it."
+        )
+        if misread.get("status") != "fail":
+            report(f"{label}: a resolution naming no evidence was accepted.")
+            return 1
+        if "thoroughly" not in problem_text(misread):
+            report(
+                f"{label}: the refusal does not name the text it read as "
+                f"evidence; got {problem_text(misread)!r}."
+            )
+            return 1
+
+        # The verdicts that must not move.
+        plain = findings_completion(root, "plain", "one, fixed. Resolved here: M1")
+        if plain.get("status") != "pass":
+            report(
+                f"{label}: an ordinary resolution was refused; "
+                f"{problem_text(plain)!r}."
+            )
+            return 1
+        undeclared = findings_completion(
+            root, "undeclared", "one, fixed. Resolved here: M9"
+        )
+        if undeclared.get("status") != "fail":
+            report(
+                f"{label}: a resolution naming a check the task does not "
+                "declare was accepted."
+            )
+            return 1
+        missing_path = findings_completion(
+            root, "missing-path", "one, open. Durable owner: docs/nowhere.md"
+        )
+        if missing_path.get("status") != "fail":
+            report(
+                f"{label}: an owner naming a path that does not exist was "
+                "accepted."
+            )
+            return 1
+
+        # A disposition may legitimately wrap its value in backticks. The first
+        # draft of the blanking removed whole code spans and destroyed exactly
+        # these two forms; nothing in the suite noticed, which is why they are
+        # asserted here rather than left to the reader who happens to ask.
+        for name, findings in (
+            ("backticked-owner", "one, open. Durable owner: `keel/archive/note.md`"),
+            ("backticked-resolution", "one, fixed. Resolved here: `src/example.js`"),
+        ):
+            repo = findings_fixture_repo(root, name, findings)
+            write_text(repo / "keel/archive/note.md", "note\n")
+            write_text(repo / "src/example.js", "//\n")
+            result = run_keel(
+                repo, "gate", "task-complete", "--change", "demo", "--task",
+                "1.1", "--json",
+            )
+            payload = json.loads(result.stdout)
+            if payload.get("status") != "pass":
+                report(
+                    f"{label}: a disposition whose value is wrapped in "
+                    f"backticks was refused ({name}); "
+                    f"{problem_codes(payload)!r} {problem_text(payload)!r}."
+                )
+                return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+# A drift is a hard stop, so whatever the message says is what the author acts
+# on. Saying only that a value moved produced a wrong record in this repository:
+# the cause was recorded as a Review edit, which is measurably not covered by
+# the fingerprint at all.
+def validate_drift_names_where_to_look_scenario() -> int:
+    label = "drift-names-where-to-look"
+
+    def fixture(root: Path, name: str, anchor_value: str) -> Path:
+        repo = root / name
+        task = strategy_probe_task(strategy="vertical-tdd")
+        # Cite a design statement so the capsule holds two distinct sources.
+        task = task.replace(
+            "    - E1: the task proves its own behavior",
+            "    - E1: the task proves its own behavior\n    - D1",
+        )
+        task = task.replace(
+            "    - Contract: pending",
+            f"    - Contract: keel-task-capsule/v1 sha256:{anchor_value}",
+        )
+        write_gate_fixture(
+            repo,
+            tasks=task,
+            design=(
+                "## Context\n\nfixture\n\n## Decisions\n\n"
+                "- D1 — the public behavior is proven through the CLI. "
+                "Basis: fixture.\n"
+            ),
+        )
+        return repo
+
+    with tempfile.TemporaryDirectory(prefix="keel-drift-") as raw:
+        root = Path(raw)
+
+        # The true anchor, so the matching case can be compared against it.
+        settled = fixture(root, "settled", "0" * 64)
+        started = run_keel(
+            settled, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--json", "--no-guard",
+        )
+        true_value = json.loads(started.stdout)["contract"]["fingerprint"]["value"]
+
+        drifted = fixture(root, "drifted", "0" * 64)
+        result = run_keel(drifted, "context", "--change", "demo", "--json")
+        payload = json.loads(result.stdout)
+        if payload.get("status") != "blocked":
+            report(
+                f"{label}: a task whose anchor does not match was not blocked; "
+                f"status {payload.get('status')!r}."
+            )
+            return 1
+        reason = " ".join(str(x) for x in (payload.get("reasons") or []))
+
+        for needed in ("0" * 8, true_value[:8]):
+            if needed not in reason:
+                report(
+                    f"{label}: the drift reason no longer reports both "
+                    f"fingerprints; {reason!r}."
+                )
+                return 1
+        for source in (
+            "openspec/changes/demo/tasks.md",
+            "openspec/changes/demo/design.md",
+        ):
+            if source not in reason:
+                report(
+                    f"{label}: the drift reason does not name the authority "
+                    f"source {source!r}; {reason!r}."
+                )
+                return 1
+        # The list is the authority set, not the change directory.
+        if "proposal.md" in reason:
+            report(
+                f"{label}: the drift reason names a file the capsule resolved "
+                f"no authority text from; {reason!r}."
+            )
+            return 1
+        lowered = reason.lower()
+        for word in ("evidence", "review", "checkbox"):
+            if word not in lowered:
+                report(
+                    f"{label}: the drift reason does not say that {word} is "
+                    f"outside the fingerprint; {reason!r}."
+                )
+                return 1
+        # D3: it names a search set, never a culprit.
+        for guess in ("changed field", "the field that changed", "caused by"):
+            if guess in lowered:
+                report(
+                    f"{label}: the drift reason claims which field moved, which "
+                    f"it cannot know; {reason!r}."
+                )
+                return 1
+
+        matching = fixture(root, "matching", true_value)
+        ok = json.loads(
+            run_keel(matching, "context", "--change", "demo", "--json").stdout
+        )
+        if ok.get("status") != "ready":
+            report(
+                f"{label}: a task whose anchor matches was not ready; "
+                f"{ok.get('status')!r} {ok.get('reasons')!r}."
+            )
+            return 1
+        ok_reason = " ".join(str(x) for x in (ok.get("reasons") or []))
+        if "fingerprint" in ok_reason.lower():
+            report(
+                f"{label}: a matching anchor now reports drift wording; "
+                f"{ok_reason!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
 # A scenario name, as the registry spells one. Two registered names carry no
 # hyphen — `cli` and `uninstall` — so requiring one would leave exactly those
 # two unchecked, and allowing single words was measured to add no false
@@ -25455,6 +25749,8 @@ SCENARIOS: tuple = (
     ("output-survives-the-pipe", validate_output_survives_the_pipe_scenario),
     ("a-strategy-is-declared", validate_strategy_is_declared_scenario),
     ("the-weakest-strategy-states-its-reason", validate_weakest_strategy_states_its_reason_scenario),
+    ("a-quoted-marker-is-not-a-disposition", validate_quoted_marker_is_not_a_disposition_scenario),
+    ("drift-names-where-to-look", validate_drift_names_where_to_look_scenario),
     (
         "authored-scenario-names-are-registered",
         validate_authored_scenario_names_scenario,

package/src/core/context.js

@@ -85,6 +85,32 @@ function taskHasCompletionEvidence(record, contract) {
   );
 }
 
+// Two hashes and nothing to search was the whole message, and it produced a
+// wrong record here: an anchor that moved was written up as a Review edit,
+// which is measurably not covered at all. The capsule already knows the answer
+// — every authority entry carries the source its text was resolved from — so
+// the search set is free. What is not free is the field that moved: only the
+// previous fingerprint is retained, not the capsule behind it, so this names
+// where to look and never what changed.
+function driftSearchSet(contract) {
+  const sources = [
+    ...new Set(
+      (contract.capsule.authority || [])
+        .map((entry) => String(entry.source || "").split("#")[0])
+        .filter(Boolean)
+    ),
+  ];
+  const where = sources.length > 0
+    ? `The fingerprint covers text resolved from: ${sources.join(", ")}.`
+    : "The fingerprint covers this task's own resolved authority text.";
+  return (
+    `${where} Evidence, Review, and the task checkbox are not covered — `
+    + "editing them does not move it. Reauthorize by re-running "
+    + "`keel gate task-start` and recording the new anchor, after confirming "
+    + "the change to the authority above was intended."
+  );
+}
+
 function taskSelection(repo, change, record, source, requestedAction = null) {
   const tasksPath = path.join(repo, "openspec", "changes", change, "tasks.md");
   const contract = compileTaskContract(repo, change, record);
@@ -100,7 +126,8 @@ function taskSelection(repo, change, record, source, requestedAction = null) {
   if (anchor && anchor !== contract.fingerprint.value) {
     return blocked(
       `Task contract fingerprint drift for ${change}#${record.id}: recorded `
-        + `sha256:${anchor}, current sha256:${contract.fingerprint.value}.`,
+        + `sha256:${anchor}, current sha256:${contract.fingerprint.value}. `
+        + `${driftSearchSet(contract)}`,
       [relativePath(repo, tasksPath)]
     );
   }

package/src/core/gates.js

@@ -582,7 +582,7 @@ function resolutionEvidenceVerdict(repo, value, commands, change) {
     return { ok: false, reason: "unknown-check", label: cited[0] };
   }
   const candidate = declaredPath(evidence);
-  if (!candidate) return { ok: false, reason: "unrecognized" };
+  if (!candidate) return { ok: false, reason: "unrecognized", token: evidence };
   // Resolution evidence is a file like any other and moves with the directory
   // holding it, so it earns the same verdict rather than a second answer to
   // the same question.
@@ -593,6 +593,30 @@ function resolutionEvidenceVerdict(repo, value, commands, change) {
   return { ok: false, reason: "missing", path: candidate };
 }
 
+// `Findings` is free prose, and in a repository whose subject is the protocol
+// that prose names the markers themselves. A quoted marker is a quotation, not
+// a disposition — the rule 5.42.0 established for the tasks.md checker and the
+// unfilled-slot scan, arriving here. Each span becomes an equal run of spaces
+// rather than being removed, because every rule downstream reads positionally:
+// `Durable owner:` captures to end of line and `Resolved here:` captures the
+// next token, so a shortened text would move what they read. The original is
+// kept for anything reported back, since a diagnostic quoting the blanked copy
+// would show the author a sentence with holes in it.
+const DISPOSITION_MARKER =
+  /\b(?:resolved here|durable owner|discard (?:reason|rationale))\s*:/gi;
+
+function withoutQuotedMarkers(text) {
+  return String(text || "").replace(/`[^`\n]*`/g, (span) =>
+    // Only the marker vocabulary is removed, not the span. A disposition may
+    // legitimately wrap its value in backticks — `Durable owner:
+    // \`keel/archive/note.md\`` is a supported form — so blanking the whole
+    // span would destroy the very path the rule exists to read. Measured: the
+    // first draft of this function did exactly that, and both the backticked
+    // owner path and the backticked resolution path started failing.
+    span.replace(DISPOSITION_MARKER, (marker) => " ".repeat(marker.length))
+  );
+}
+
 function resolutionEvidenceMessage(verdict) {
   const lead = "Review Findings records a finding as resolved here, but its "
     + "evidence is not usable — ";
@@ -615,7 +639,13 @@ function resolutionEvidenceMessage(verdict) {
   if (verdict.reason === "missing") {
     return `${lead}\`${verdict.path}\` does not exist.${tail}`;
   }
-  return `${lead}it names neither a check nor a path.${tail}`;
+  // Naming the token turns an argument into an observation: the author
+  // believes they named a check or a path, and this is what the gate read
+  // instead.
+  return verdict.token
+    ? `${lead}it read \`${verdict.token}\`, which names neither a check nor a `
+      + `path.${tail}`
+    : `${lead}it names neither a check nor a path.${tail}`;
 }
 
 function findingOwnerIsDurable(repo, findings, change) {
@@ -1011,7 +1041,8 @@ function completionChecks(repo, task, contract = null, changeVerify = null, chan
     // pass as a tracker owner, which is the one reading this disposition must
     // not have: a link to work someone else will do is not evidence that this
     // task did it.
-    const resolved = [...reviewFields.Findings.matchAll(RESOLVED_HERE)];
+    const scannable = withoutQuotedMarkers(reviewFields.Findings);
+    const resolved = [...scannable.matchAll(RESOLVED_HERE)];
     if (resolved.length > 0) {
       for (const claim of resolved) {
         const verdict = resolutionEvidenceVerdict(repo, claim[1], commands, change);
@@ -1021,7 +1052,7 @@ function completionChecks(repo, task, contract = null, changeVerify = null, chan
         );
         break;
       }
-    } else if (!findingOwnerIsDurable(repo, reviewFields.Findings, change)) {
+    } else if (!findingOwnerIsDurable(repo, scannable, change)) {
       problems.push(
         problem(
           "finding-owner",