@christang/keel 5.56.0 → 5.57.0

package/README.md

@@ -313,6 +313,37 @@ keel --uninstall                  # reverts core.hooksPath when Keel set it
 `--with-git-hooks` is opt-in: a plain `keel --install` never touches git config, and the override
 is repo-local and reversible.
 
+## Declaring what a red proves
+
+Red-green discipline makes you write a check that fails before the implementation exists, and
+`keel gate task-complete` refuses a task whose `M<n>.red` Evidence is missing. What it could not
+check was *why* the red failed — a red that fails because a fixture is empty, or because `PATH` was
+never cleared, is shape-perfect.
+
+A check may close by declaring the failure its red must show:
+
+```
+- M1: `npm test -- --scenario widget` asserts the widget renders. Fails with: `widget is undefined`
+```
+
+Completion then requires that literal in the check's `.red` Evidence:
+
+```
+- M1.red: fail, for the right reason. The scenario reported `widget is undefined`.
+```
+
+The clause lives inside the check text, so it is inside the contract fingerprint. That is the point:
+a signature cannot be added or rewritten after the red was observed without the anchor moving, which
+is what separates a prediction from a transcription. Keel does not judge whether the signature is a
+good one — you can declare a string that any failure prints — it holds only that you wrote it first
+and that review can see it.
+
+The clause is optional; a check without one behaves exactly as before. A declaration on a check that
+can have no red — one tagged `(regression)`, or any check under a strategy outside the red-green
+set — fails `task-start` by name rather than sitting in the contract doing nothing. So does a
+`Fails with:` marker that names no literal. To *write about* the marker in a check without declaring
+one, put it in inline code.
+
 ## Domain lenses
 
 Keel's core is pure process; it ships no domain knowledge and no decisions of its own. Alongside

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.56.0 -->
+<!-- keel:start version=5.57.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.56.0",
+  "version": "5.57.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.56.0",
+  "version": "5.57.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.56.0",
+  "version": "5.57.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.56.0"
-PROTOCOL_VERSION = "5.56.0"
+PACKAGE_VERSION = "5.57.0"
+PROTOCOL_VERSION = "5.57.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
@@ -25020,6 +25020,306 @@ def problem_codes(payload: dict) -> list[str]:
     return [str(entry.get("code", "")) for entry in (payload.get("problems") or [])]
 
 
+
+# Red-green forces the expensive half — a check that fails before the
+# implementation exists — and enforces that a `.red` line is present. Nothing
+# checked that the red failed *because of the thing under test*. Issue #116
+# measured two reds in one session that were shape-perfect and failed for an
+# unrelated reason: one where the fixture had not cleared PATH so the check
+# passed, one where the fixture contained no wording the checker would refuse.
+# The declaration is what a gate can hold: written into the check, so it is in
+# the fingerprint, and therefore written before the run rather than after it.
+def validate_red_declares_what_it_proves_scenario() -> int:
+    label = "a-red-declares-what-it-proves"
+    signature = "openspec: not found"
+    declared = (
+        f"M1: node test.js asserts the public behavior. Fails with: `{signature}`",
+    )
+    plain = ("M1: node test.js asserts the public behavior",)
+    with tempfile.TemporaryDirectory(prefix="keel-failswith-") as raw:
+        root = Path(raw)
+
+        def start(name: str, **kwargs) -> dict:
+            return strategy_probe_start(
+                root, name, strategy_probe_task(**kwargs)
+            )
+
+        def commands_of(payload: dict) -> list[dict]:
+            contract = payload.get("contract") or {}
+            capsule = contract.get("capsule") or {}
+            return ((capsule.get("verification") or {}).get("commands") or [])
+
+        def fingerprint_of(payload: dict) -> str:
+            return str((payload.get("contract") or {}).get("fingerprint") or "")
+
+        # A declared signature compiles and is carried as its own field, so the
+        # gate can read it without re-parsing the author's prose.
+        with_signature = start(
+            "declared", strategy="vertical-tdd", commands=declared
+        )
+        if with_signature.get("status") != "pass":
+            report(
+                f"{label}: a check declaring a failure signature was refused; "
+                f"got {with_signature.get('status')!r} "
+                f"{problem_text(with_signature)!r}."
+            )
+            return 1
+        compiled = commands_of(with_signature)
+        if len(compiled) != 1 or compiled[0].get("failsWith") != signature:
+            report(
+                f"{label}: the compiled check does not carry the declared "
+                f"failure signature; got {compiled!r}."
+            )
+            return 1
+        # The clause is part of the check the author wrote, so it stays in
+        # `check` as well; the field is what the gate reads, not a replacement
+        # for the text.
+        if "Fails with:" not in str(compiled[0].get("check", "")):
+            report(
+                f"{label}: compiling the signature stripped it out of the "
+                f"check text the author wrote; got {compiled[0]!r}."
+            )
+            return 1
+
+        # In the fingerprint for free, which is what makes the declaration a
+        # prediction rather than a transcription: it cannot be retrofitted to
+        # whatever the run happened to print without the anchor moving.
+        edited = start(
+            "edited",
+            strategy="vertical-tdd",
+            commands=(
+                "M1: node test.js asserts the public behavior. "
+                "Fails with: `a different failure entirely`",
+            ),
+        )
+        without = start("without", strategy="vertical-tdd", commands=plain)
+        prints = {
+            "declared": fingerprint_of(with_signature),
+            "edited": fingerprint_of(edited),
+            "without": fingerprint_of(without),
+        }
+        if not all(prints.values()):
+            report(f"{label}: a probe reported no fingerprint; got {prints!r}.")
+            return 1
+        if prints["declared"] == prints["edited"]:
+            report(
+                f"{label}: editing only the declared failure signature left "
+                f"the fingerprint unmoved at {prints['declared']!r}, so a "
+                "signature could be rewritten after the red was recorded."
+            )
+            return 1
+        if prints["declared"] == prints["without"]:
+            report(
+                f"{label}: declaring a signature left the fingerprint "
+                f"unmoved at {prints['without']!r}."
+            )
+            return 1
+
+        # A declaration that can produce no red is refused rather than left to
+        # sit in the contract doing nothing, which reads to its author as a
+        # check being enforced.
+        for name, kwargs in (
+            (
+                "regression",
+                dict(
+                    strategy="vertical-tdd",
+                    commands=(
+                        "M1: node test.js asserts the public behavior",
+                        "M2 (regression): the suite stays green. "
+                        f"Fails with: `{signature}`",
+                    ),
+                ),
+            ),
+            (
+                "no-red-strategy",
+                dict(
+                    strategy="evidence-first",
+                    reason="the artifact is inspected after it is written.",
+                    commands=declared,
+                ),
+            ),
+        ):
+            payload = start(name, **kwargs)
+            if payload.get("status") != "fail":
+                report(
+                    f"{label}: a failure signature on a check with no red "
+                    f"({name}) was accepted; got {payload.get('status')!r}."
+                )
+                return 1
+            text = problem_text(payload)
+            expected_label = "M2" if name == "regression" else "M1"
+            if expected_label not in text or "red" not in text:
+                report(
+                    f"{label}: the refusal for {name} does not name the check "
+                    f"and say it records no red; got {text!r}."
+                )
+                return 1
+            if "signature-without-red" not in problem_codes(payload):
+                report(
+                    f"{label}: the refusal for {name} carries no "
+                    f"signature-without-red code; got "
+                    f"{problem_codes(payload)!r}."
+                )
+                return 1
+
+        # A marker that names no literal is the shape of a typo. Ignoring it
+        # leaves the author believing a signature is enforced when none parsed.
+        for name, check in (
+            ("bare", "M1: node test.js asserts the behavior. Fails with:"),
+            (
+                "unquoted",
+                "M1: node test.js asserts the behavior. Fails with: not found",
+            ),
+            (
+                "not-closing",
+                "M1: node test.js asserts it. Fails with: `not found` "
+                "and then keeps going.",
+            ),
+        ):
+            payload = start(name, strategy="vertical-tdd", commands=(check,))
+            if payload.get("status") != "fail":
+                report(
+                    f"{label}: a malformed signature marker ({name}) compiled "
+                    f"as if nothing were declared; got "
+                    f"{payload.get('status')!r}."
+                )
+                return 1
+            if "malformed-failure-signature" not in problem_codes(payload):
+                report(
+                    f"{label}: the refusal for {name} carries no "
+                    f"malformed-failure-signature code; got "
+                    f"{problem_codes(payload)!r}."
+                )
+                return 1
+
+        # The escape is the one this repository already established for quoted
+        # material: a check that describes this rule has to be able to name it.
+        quoted = start(
+            "quoted",
+            strategy="vertical-tdd",
+            commands=(
+                "M1: a `Fails with:` marker with no literal is refused by name",
+            ),
+        )
+        if quoted.get("status") != "pass":
+            report(
+                f"{label}: a marker written inside inline code was read as a "
+                f"declaration; got {quoted.get('status')!r} "
+                f"{problem_text(quoted)!r}."
+            )
+            return 1
+        if commands_of(quoted)[0].get("failsWith") is not None:
+            report(
+                f"{label}: a marker inside inline code compiled to a failure "
+                f"signature; got {commands_of(quoted)!r}."
+            )
+            return 1
+
+        # The obligation is stated where the author is deciding — before the
+        # failing check is written — rather than discovered once it has run.
+        warnings = " ".join(str(w) for w in (with_signature.get("warnings") or []))
+        if signature not in warnings or "M1" not in warnings:
+            report(
+                f"{label}: the task-start obligation does not name which "
+                f"checks declared a failure signature; got {warnings!r}."
+            )
+            return 1
+        undeclared = " ".join(str(w) for w in (without.get("warnings") or []))
+        if "declared no failure signature" not in undeclared:
+            report(
+                f"{label}: the obligation does not say that a check owing a "
+                f"red declared no signature; got {undeclared!r}."
+            )
+            return 1
+
+        # Completion is where the declaration becomes a criterion.
+        repo = root / "completion"
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+
+        def complete(check: str, red: str) -> dict:
+            write_gate_fixture(
+                repo,
+                tasks=strategy_probe_task(
+                    strategy="vertical-tdd", commands=(check,)
+                ).replace(
+                    "    - M1: pending\n",
+                    f"    - M1: the check ran.\n"
+                    f"    - M1.red: {red}\n"
+                    "    - M1.green: it passed after the implementation.\n",
+                ),
+            )
+            record_contract_anchor(repo, "demo")
+            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]}],
+                }
+
+        declared_check = declared[0]
+        mismatched = complete(
+            declared_check, "it failed before the implementation existed."
+        )
+        if mismatched.get("status") != "fail":
+            report(
+                f"{label}: task-complete accepted a red that does not show "
+                f"the declared failure; got {mismatched.get('status')!r}."
+            )
+            return 1
+        text = problem_text(mismatched)
+        if "M1" not in text or signature not in text:
+            report(
+                f"{label}: the refusal names neither the check nor the string "
+                f"it did not find; got {text!r}."
+            )
+            return 1
+        if "red-missing-declared-failure" not in problem_codes(mismatched):
+            report(
+                f"{label}: the refusal carries no "
+                f"red-missing-declared-failure code; got "
+                f"{problem_codes(mismatched)!r}."
+            )
+            return 1
+
+        matched = complete(
+            declared_check,
+            f"it failed with `{signature}` before the implementation existed.",
+        )
+        if matched.get("status") != "pass":
+            report(
+                f"{label}: a red showing the declared failure was refused; "
+                f"got {matched.get('status')!r} {problem_text(matched)!r}."
+            )
+            return 1
+
+        # D3: the undeclared case is unchanged, asserted against the same
+        # fixture with the clause removed and the same weak red that the
+        # declared check was refused for.
+        undeclared_task = complete(
+            plain[0], "it failed before the implementation existed."
+        )
+        if undeclared_task.get("status") != "pass":
+            report(
+                f"{label}: a red-green task declaring no signature stopped "
+                f"completing; got {undeclared_task.get('status')!r} "
+                f"{problem_text(undeclared_task)!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
 # The strategy was the one capsule field the compiler supplied from a value no
 # spec documents as a default — and it supplied the weakest of the six, so
 # omitting the line was how a task opted out of red-green.
@@ -26542,6 +26842,7 @@ SCENARIOS: tuple = (
     ("the-marker-version-is-read", validate_marker_version_is_read_scenario),
     ("output-survives-the-pipe", validate_output_survives_the_pipe_scenario),
     ("a-strategy-is-declared", validate_strategy_is_declared_scenario),
+    ("a-red-declares-what-it-proves", validate_red_declares_what_it_proves_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),

package/src/core/gates.js

@@ -232,9 +232,24 @@ function redGreenObligation(compiled) {
   const strategy = compiled.capsule.verification.strategy.toLowerCase();
   if (!RED_GREEN_VERIFICATION_STRATEGIES.has(strategy)) return [];
   const commands = compiled.capsule.verification.commands;
-  const owing = commands.filter((item) => !item.regression).map((item) => item.label);
+  const owingChecks = commands.filter((item) => !item.regression);
+  const owing = owingChecks.map((item) => item.label);
   const exempt = commands.filter((item) => item.regression).map((item) => item.label);
   if (owing.length === 0) return [];
+  // What a red proves is only checkable if it was written down before the red
+  // was run, so the moment to say so is here — the author is about to write the
+  // failing check — and not at completion, where any signature is a
+  // transcription of whatever already failed (issue #116).
+  const signed = owingChecks.filter((item) => item.failsWith);
+  const unsigned = owingChecks.filter((item) => !item.failsWith).map((item) => item.label);
+  const signatures = signed.length > 0
+    ? ` ${signed.map((item) => `${item.label} must fail with \`${item.failsWith}\``).join("; ")}.`
+      + (unsigned.length > 0
+        ? ` ${unsigned.join(", ")} declared no failure signature.`
+        : "")
+    : ` ${owing.join(", ")} declared no failure signature — close the check with `
+      + "`Fails with:` and the literal its red should print, and the red that "
+      + "gets recorded has to be the one you predicted.";
   return [
     `${strategy} will require concrete .red and .green Evidence at completion `
       + `for ${owing.join(", ")}`
@@ -244,7 +259,8 @@ function redGreenObligation(compiled) {
         : "")
       + ". Tag a check `(regression)` now if it asserts that something already "
       + "green stays green, rather than discovering the obligation once the "
-      + "checks have been run.",
+      + "checks have been run."
+      + signatures,
   ];
 }
 
@@ -1011,8 +1027,34 @@ function completionChecks(repo, task, contract = null, changeVerify = null, chan
         .filter((entry) => entry.regression)
         .map((entry) => entry.label)
     );
+    // A check may declare the failure its red must show. Enforced against the
+    // recorded `.red`, which is where the shape check stopped: a red that
+    // failed for an unrelated reason satisfied the presence check exactly as
+    // well as one that failed for the right reason (issue #116). Keel does not
+    // judge whether the declared string is a good one — what it holds is that
+    // the string is in the contract, so it was written before the run.
+    const declaredFailure = new Map(
+      (contract ? contract.capsule.verification.commands : [])
+        .filter((entry) => entry.failsWith)
+        .map((entry) => [entry.label, entry.failsWith])
+    );
     for (const label of commands) {
       if (exempt.has(label)) continue;
+      const expected = declaredFailure.get(label);
+      const recorded = evidenceValue(task, `${label}.red`);
+      if (expected && isConcrete(recorded) && !String(recorded).includes(expected)) {
+        problems.push(
+          problem(
+            "red-missing-declared-failure",
+            `${label} declares that its red fails with \`${expected}\`, and `
+              + `the recorded ${label}.red Evidence does not contain that `
+              + "string. Record the failure output the red actually printed, "
+              + "or correct the declaration — which moves the contract "
+              + "fingerprint, because a signature edited after the red was "
+              + "observed is a transcription of it.",
+          )
+        );
+      }
       for (const phase of ["red", "green"]) {
         if (!isConcrete(evidenceValue(task, `${label}.${phase}`))) {
           problems.push(

package/src/core/task-contract.js

@@ -153,6 +153,31 @@ const RED_GREEN_VERIFICATION_STRATEGIES = new Set([
 // Tags an M<n> check may carry after its label, as a comma-separated set.
 const COMMAND_TAGS = new Set(["fast", "full", "regression"]);
 
+// A check may end by declaring the failure its red is expected to show, so that
+// what the red proves is written down before the red is run. The clause closes
+// the check: `Fails with:` followed by one inline-code literal and nothing more.
+// End-anchored on purpose — a check that describes this rule mentions the marker
+// mid-sentence, and a mention is not a declaration.
+const FAILURE_SIGNATURE = /\bFails with:[ \t]*`([^`\n]+)`[ \t]*$/i;
+const FAILURE_MARKER = /\bFails with:/i;
+
+// Classify a check's `Fails with:` marker. `signature` is the declared literal;
+// `malformed` marks a marker that is present and is not a closing clause — a
+// typo shape, and ignoring it would leave the author believing a signature is
+// enforced when none was parsed. A marker written inside inline code is quoted
+// material rather than a declaration, the meaning inline code already carries
+// here, which is what lets this file's own tasks name the marker.
+function failureSignature(check) {
+  const text = String(check || "");
+  const match = text.match(FAILURE_SIGNATURE);
+  if (match) return { signature: match[1].trim(), malformed: false };
+  const remainder = withoutInlineCode(text);
+  return {
+    signature: null,
+    malformed: FAILURE_MARKER.test(remainder),
+  };
+}
+
 // Single source of truth for the accepted completion Review `Status`
 // vocabulary. Consumed by both the completion gate (src/core/gates.js) and the
 // context "already reviewed" probe (src/core/context.js) so the two never
@@ -193,19 +218,39 @@ function verification(task) {
     // therefore exempt from the red-green evidence requirement. A check may
     // carry both, so the tag is a comma-separated set rather than one word.
     const match = entry.match(/^(M[1-9]\d*)(?:\s*\(([^)\n]*)\))?:\s*(.*)$/);
-    if (!match) return { label: null, layer: "full", regression: false, check: entry };
+    if (!match) {
+      return {
+        label: null,
+        layer: "full",
+        regression: false,
+        check: entry,
+        failsWith: null,
+        malformedSignature: false,
+      };
+    }
     const tags = (match[2] || "")
       .split(",")
       .map((tag) => tag.trim().toLowerCase())
       .filter(Boolean);
     if (tags.some((tag) => !COMMAND_TAGS.has(tag))) {
-      return { label: null, layer: "full", regression: false, check: entry };
+      return {
+        label: null,
+        layer: "full",
+        regression: false,
+        check: entry,
+        failsWith: null,
+        malformedSignature: false,
+      };
     }
+    const check = normalizeText(match[3]);
+    const failure = failureSignature(check);
     return {
       label: match[1],
       layer: tags.includes("fast") ? "fast" : "full",
       regression: tags.includes("regression"),
-      check: normalizeText(match[3]),
+      check,
+      failsWith: failure.signature,
+      malformedSignature: failure.malformed,
     };
   });
   return {
@@ -367,7 +412,60 @@ function taskStartContractProblems(task) {
       ...regressionOnlyProblems(task),
     ];
   }
-  return [...commandLabelProblems(task), ...regressionOnlyProblems(task)];
+  return [
+    ...commandLabelProblems(task),
+    ...regressionOnlyProblems(task),
+    ...failureSignatureProblems(task),
+  ];
+}
+
+// A declared failure signature describes the check's red. A `(regression)` check
+// is exempt from red-green and a strategy outside the red-green set records no
+// `.red` at all, so in both cases the declaration describes evidence that will
+// never exist. Refused rather than left sitting in the contract: a declaration
+// doing nothing reads to its author as a check being enforced.
+function failureSignatureProblems(task) {
+  const parsed = verification(task);
+  const strategy = parsed.strategy.toLowerCase();
+  const redGreen = RED_GREEN_VERIFICATION_STRATEGIES.has(strategy);
+  const problems = [];
+  for (const entry of parsed.commands) {
+    if (!entry.label) continue;
+    if (entry.malformedSignature) {
+      problems.push({
+        code: "malformed-failure-signature",
+        message:
+          `${entry.label} carries a \`Fails with:\` marker that does not close `
+          + "the check with a literal. Write the failure signature as one "
+          + "inline-code literal at the end of the check, or fence the marker "
+          + "in inline code when the check is describing it rather than "
+          + "declaring one.",
+      });
+      continue;
+    }
+    if (!entry.failsWith) continue;
+    if (!redGreen) {
+      problems.push({
+        code: "signature-without-red",
+        message:
+          `${entry.label} declares the failure its red must show, but `
+          + `\`${parsed.strategy}\` records no red for the signature to `
+          + "describe. Name a red-green strategy, or drop the clause.",
+      });
+      continue;
+    }
+    if (entry.regression) {
+      problems.push({
+        code: "signature-without-red",
+        message:
+          `${entry.label} declares the failure its red must show, but it is `
+          + "tagged `(regression)` and so records no red for the signature to "
+          + "describe. Untag the check if it proves new behavior, or drop the "
+          + "clause.",
+      });
+    }
+  }
+  return problems;
 }
 
 // A red-green strategy whose every check is exempt from red-green is that
@@ -1127,6 +1225,10 @@ function compileTaskContract(repo, change, task) {
           const emitted = { label: entry.label, check: entry.check };
           if (entry.layer && entry.layer !== "full") emitted.layer = entry.layer;
           if (entry.regression) emitted.regression = true;
+          // The clause stays in `check` — it is text the author wrote — and the
+          // field is what the gate reads. Emitted only when declared, so every
+          // check without one keeps the capsule shape and fingerprint it had.
+          if (entry.failsWith) emitted.failsWith = entry.failsWith;
           return emitted;
         }),
     },