@christang/keel 5.56.0 → 5.58.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.58.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/bin/keel.js

@@ -671,16 +671,33 @@ function npmCommand() {
   return process.platform === "win32" ? "npm.cmd" : "npm";
 }
 
+// npm hoists: installed as a dependency, Keel's OpenSpec bin lands in the
+// consumer project's `node_modules/.bin`, and Keel's own package root has no
+// `node_modules` at all. Searching only the package root worked in exactly one
+// layout — a checkout of this repository, where Keel is the direct consumer —
+// which is why every scenario stayed green while `keel openspec` failed on a
+// plain install (issue #129). Walk outward the way Node resolves a module:
+// nearest wins, so a project pinning its own OpenSpec is honored over one
+// further up. The `.bin` entry is the published contract between npm and a
+// consumer; resolving through the dependency's internal bin path instead would
+// bind Keel to a path that belongs to the dependency.
+function openspecBinNames() {
+  return process.platform === "win32"
+    ? ["openspec.cmd", "openspec.exe", "openspec"]
+    : ["openspec"];
+}
+
 function openspecCandidates() {
-  const localBin = path.join(
-    PACKAGE_ROOT,
-    "node_modules",
-    ".bin",
-    process.platform === "win32" ? "openspec.cmd" : "openspec"
-  );
   const candidates = [];
-  if (fs.existsSync(localBin)) {
-    candidates.push(localBin);
+  let directory = PACKAGE_ROOT;
+  for (;;) {
+    for (const name of openspecBinNames()) {
+      const candidate = path.join(directory, "node_modules", ".bin", name);
+      if (fs.existsSync(candidate)) candidates.push(candidate);
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
   }
   candidates.push(process.platform === "win32" ? "openspec.cmd" : "openspec");
   candidates.push("openspec");
@@ -765,6 +782,39 @@ function declaredOpenSpecVersion(repo) {
   return { state: "none", version: null };
 }
 
+// "Not installed" and "installed and Keel cannot reach it" need different
+// advice: reinstalling is the only remedy for the first and cannot help with the
+// second, and issue #129 measured a whole class of installs being sent to it.
+// The package directory is the evidence — it is present whenever npm placed the
+// dependency, whatever happened to its `.bin` entry.
+function installedOpenSpecPackage() {
+  let directory = PACKAGE_ROOT;
+  for (;;) {
+    const candidate = path.join(
+      directory,
+      "node_modules",
+      "@fission-ai",
+      "openspec",
+      "package.json"
+    );
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+// The remedy for an openspec Keel could not run, split by whether npm has
+// already done the thing the other branch would ask for.
+function unresolvedOpenSpecAdvice() {
+  const installed = installedOpenSpecPackage();
+  return installed
+    ? `the OpenSpec dependency is installed at ${path.dirname(installed)} but `
+      + "Keel could not run it — check that its node_modules/.bin entry exists "
+      + "and is executable; reinstalling will not change this"
+    : "reinstall keel so npm installs its OpenSpec dependency";
+}
+
 function findOpenSpecCommand() {
   for (const command of openspecCandidates()) {
     const status = runCommand(command, ["--version"], {
@@ -1606,8 +1656,8 @@ function runDoctor(options) {
   if (!openspec) {
     printDoctorLine(
       "openspec",
-      "missing",
-      "reinstall keel so npm installs its OpenSpec dependency"
+      installedOpenSpecPackage() ? "problem" : "missing",
+      unresolvedOpenSpecAdvice()
     );
   } else {
     const bareOpenSpecOnPath =
@@ -1967,8 +2017,7 @@ function runAction(options) {
     const openspec = findOpenSpecCommand();
     if (!openspec) {
       process.stderr.write(
-        "keel: openspec is not resolvable; reinstall keel so npm installs "
-          + "its OpenSpec dependency\n"
+        `keel: openspec is not resolvable; ${unresolvedOpenSpecAdvice()}\n`
       );
       return 1;
     }

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.58.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.58.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.58.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.58.0"
+PROTOCOL_VERSION = "5.58.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
@@ -24623,6 +24623,186 @@ def validate_validation_runner_scenario() -> int:
 
 # The one ordered scenario registry: --scenario dispatch, the --all runner,
 # and registration assertions all read this list and nothing else.
+
+# 170 scenarios and every release gate ran green while `keel openspec` did not
+# resolve on a plain `npm install` (issue #129). The cause is a layout, not a
+# behavior: npm hoists, so the OpenSpec bin lands in the consumer project's
+# `node_modules/.bin` while the lookup only searched Keel's own package root —
+# which is where it sits in a checkout of this repository, and nowhere else.
+# So the assertion has to build the other layout rather than test harder in this
+# one. Built from the package's own files instead of the registry: what is under
+# test is where a file sits, and a suite that reaches the network fails for
+# reasons that have nothing to do with this code.
+def validate_dependency_resolves_where_npm_put_it_scenario() -> int:
+    label = "the-dependency-resolves-where-npm-put-it"
+
+    def write_openspec_stub(bin_dir: Path, version: str) -> None:
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        if os.name == "nt":
+            (bin_dir / "openspec.cmd").write_text(
+                f"@echo off\necho {version}\n", encoding="utf-8"
+            )
+            return
+        stub = bin_dir / "openspec"
+        stub.write_text(f"#!/bin/sh\necho {version}\n", encoding="utf-8")
+        stub.chmod(0o755)
+
+    def install_keel(package_root: Path) -> None:
+        # The published `files` set, copied rather than packed: the tarball's
+        # contents are what npm unpacks, and `npm pack` would add a network-free
+        # but slow round trip through tar for no additional assertion.
+        package_root.mkdir(parents=True, exist_ok=True)
+        for entry in ("bin", "scripts", "src", "assets", "plugins"):
+            source = ROOT / entry
+            if source.exists():
+                shutil.copytree(source, package_root / entry, dirs_exist_ok=True)
+        shutil.copy2(ROOT / "package.json", package_root / "package.json")
+
+    # PATH without any openspec, so what resolves came from the layout and not
+    # from the machine running the suite.
+    def clean_env(extra_path: Path | None = None) -> dict[str, str]:
+        env = dict(os.environ)
+        entries = [
+            entry
+            for entry in env.get("PATH", "").split(os.pathsep)
+            if entry and not (Path(entry) / "openspec").exists()
+        ]
+        if extra_path is not None:
+            entries.insert(0, str(extra_path))
+        env["PATH"] = os.pathsep.join(entries)
+        return env
+
+    def run_installed(
+        package_root: Path, cwd: Path, *args: str, env: dict[str, str] | None = None
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["node", str(package_root / "bin" / "keel.js"), *args],
+            cwd=cwd,
+            env=env if env is not None else clean_env(),
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            check=False,
+        )
+
+    def doctor_openspec_line(result: subprocess.CompletedProcess[str]) -> str:
+        return next(
+            (
+                line
+                for line in result.stdout.splitlines()
+                if line.startswith("openspec:")
+            ),
+            "",
+        )
+
+    with tempfile.TemporaryDirectory(prefix="keel-hoisted-") as raw:
+        root = Path(raw)
+
+        # The layout npm actually produces: Keel unpacked under the consumer's
+        # node_modules with no node_modules of its own, the dependency's bin
+        # hoisted beside it.
+        project = root / "project"
+        package_root = project / "node_modules/@christang/keel"
+        install_keel(package_root)
+        write_openspec_stub(project / "node_modules/.bin", "1.12.0")
+        if (package_root / "node_modules").exists():
+            report(
+                f"{label}: the fixture gave Keel a node_modules of its own, "
+                "which is the one layout the defect does not appear in."
+            )
+            return 1
+
+        proxied = run_installed(package_root, project, "openspec", "--version")
+        if proxied.returncode != 0:
+            report(
+                f"{label}: `keel openspec` failed against the hoisted "
+                f"dependency; exit {proxied.returncode}, stderr "
+                f"{proxied.stderr.strip()!r}."
+            )
+            return 1
+        if "1.12.0" not in proxied.stdout:
+            report(
+                f"{label}: `keel openspec` exited 0 without running the "
+                f"hoisted dependency; stdout {proxied.stdout.strip()!r}."
+            )
+            return 1
+
+        hoisted_doctor = doctor_openspec_line(
+            run_installed(package_root, project, "--doctor")
+        )
+        if hoisted_doctor.startswith("openspec: missing"):
+            report(
+                f"{label}: doctor reported an installed dependency as missing; "
+                f"got {hoisted_doctor!r}."
+            )
+            return 1
+
+        # Nearest wins, so a project pinning its own OpenSpec is honored over
+        # one further up the tree.
+        nested = root / "outer/project"
+        nested_package = nested / "node_modules/@christang/keel"
+        install_keel(nested_package)
+        write_openspec_stub(root / "outer/node_modules/.bin", "9.9.9")
+        write_openspec_stub(nested / "node_modules/.bin", "1.12.0")
+        nearest = run_installed(nested_package, nested, "openspec", "--version")
+        if "1.12.0" not in nearest.stdout:
+            report(
+                f"{label}: the farther OpenSpec won over the nearer one; got "
+                f"{nearest.stdout.strip()!r}."
+            )
+            return 1
+
+        # The one case where advising a reinstall is correct.
+        bare = root / "bare"
+        bare_package = bare / "node_modules/@christang/keel"
+        install_keel(bare_package)
+        absent = doctor_openspec_line(
+            run_installed(bare_package, bare, "--doctor")
+        )
+        if not absent.startswith("openspec: missing"):
+            report(
+                f"{label}: doctor did not report a genuinely absent dependency "
+                f"as missing; got {absent!r}."
+            )
+            return 1
+        if "reinstall" not in absent:
+            report(
+                f"{label}: doctor stopped advising a reinstall in the one case "
+                f"where it is the right advice; got {absent!r}."
+            )
+            return 1
+
+        # Installed and unreachable: the package is where npm puts it, its bin
+        # entry is not. Sending this reader to reinstall is what issue #129
+        # measured, and it is the one action that cannot help.
+        broken = root / "broken"
+        broken_package = broken / "node_modules/@christang/keel"
+        install_keel(broken_package)
+        write_text(
+            broken / "node_modules/@fission-ai/openspec/package.json",
+            '{"name": "@fission-ai/openspec", "version": "1.12.0"}\n',
+        )
+        unreachable = doctor_openspec_line(
+            run_installed(broken_package, broken, "--doctor")
+        )
+        if "reinstall" in unreachable and "will not change this" not in unreachable:
+            report(
+                f"{label}: doctor advised reinstalling for a dependency that "
+                f"is already installed; got {unreachable!r}."
+            )
+            return 1
+        if "installed" not in unreachable:
+            report(
+                f"{label}: doctor did not distinguish an installed but "
+                f"unreachable dependency from an absent one; got "
+                f"{unreachable!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
 def validate_doctor_openspec_honesty_scenario() -> int:
     cli = (ROOT / "bin/keel.js").read_text(encoding="utf-8")
     if "is not on PATH" not in cli:
@@ -25020,6 +25200,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.
@@ -26539,9 +27019,14 @@ SCENARIOS: tuple = (
     ),
     ("cli", validate_cli_scenario),
     ("doctor-openspec-honesty", validate_doctor_openspec_honesty_scenario),
+    (
+        "the-dependency-resolves-where-npm-put-it",
+        validate_dependency_resolves_where_npm_put_it_scenario,
+    ),
     ("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;
         }),
     },