@christang/keel 5.59.0 → 5.61.0

package/README.md

@@ -364,6 +364,27 @@ keel lenses add web         # copy the web template into keel/lenses/web.md, the
 keel lenses add web --force # overwrite an existing lens
 ```
 
+## What a coverage claim is checked against
+
+`## Expectation Coverage` closes each expectation one of three ways, and each is checked. A
+`Durable owner:` must name a path that exists or an `https://…` reference that already carries
+its content. A `Discard reason:` must give a reason. And a `Covered by:` **that cites
+expectation identifiers** is compared against the `Covers:` of the task it names:
+
+```
+- E3: the records land in different flow generations (F4, D3). Covered by: 1.1
+```
+
+`keel gate change-close` checks that task 1.1's `Covers:` actually names `F4` and `D3`. When it
+does not, the refusal says so and says where the identifier *is* — the task of this change whose
+`Covers:` holds it, or that none does.
+
+**Citing identifiers is optional.** An entry that names none is not refused and not reported as
+deficient; plenty of expectations are prose ("documentation and skills follow the behavior
+changes above") and numbering them to satisfy a parser is worse than leaving them. What the check
+holds you to is the claim you chose to make. So that a pass is not read as more than it is, the
+close reports how many entries it compared and how many it did not.
+
 ## Re-recording a contract
 
 Changing a task's contract after work has started moves its fingerprint, and Keel reports that the

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.59.0 -->
+<!-- keel:start version=5.61.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.59.0",
+  "version": "5.61.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.59.0",
+  "version": "5.61.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.59.0",
+  "version": "5.61.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

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import json
 import hashlib
 import os
@@ -37,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.59.0"
-PROTOCOL_VERSION = "5.59.0"
+PACKAGE_VERSION = "5.61.0"
+PROTOCOL_VERSION = "5.61.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
@@ -5521,36 +5522,46 @@ def validate_a_declared_dependency_is_resolved_scenario() -> int:
     """
     label = "a-declared-dependency-is-resolved"
 
-    # `no openspec on PATH`, and nothing else removed. Emptying PATH outright
-    # would also remove `node`, and the openspec shim needs it — the scenario
-    # would then be asserting that a shell without an interpreter fails.
-    without = dict(os.environ)
-    without["PATH"] = os.pathsep.join(
-        entry
-        for entry in os.environ.get("PATH", "").split(os.pathsep)
-        if entry and not (Path(entry) / "openspec").exists()
-    )
-    if shutil.which("openspec", path=without["PATH"]) is not None:
-        report(
-            f"{label}: could not build a PATH without openspec on it, so the "
-            "reproduction cannot be set up."
-        )
-        return 1
-    resolved = run_openspec(ROOT, "--version", env=without)
-    if resolved is None:
-        report(
-            f"{label}: with no `openspec` on PATH the runner resolved nothing, "
-            "but this package declares it as a dependency and installs it at "
-            "node_modules/.bin. A tool the repository ships is not a tool the "
-            "host has to provide."
-        )
-        return 1
-    if resolved.returncode != 0 or not re.search(r"\d+\.\d+\.\d+", resolved.stdout):
-        report(
-            f"{label}: the resolved openspec did not report a version. "
-            f"exit={resolved.returncode} out={(resolved.stdout or '').strip()!r}"
-        )
-        return 1
+    # `no openspec on PATH`, and nothing else removed — by file, not by
+    # directory. Removing the directory would also remove `node`, and the
+    # openspec shim needs it, so the scenario would be asserting that a shell
+    # without an interpreter fails (issue #137).
+    with path_without_openspec() as sanitized:
+        without = dict(os.environ)
+        without["PATH"] = sanitized
+        if shutil.which("openspec", path=without["PATH"]) is not None:
+            report(
+                f"{label}: could not build a PATH without openspec on it, so the "
+                "reproduction cannot be set up."
+            )
+            return 1
+        # The scenario's own precondition, asserted before the behavior. A shim
+        # with no interpreter exits 127, and calling that a fact about openspec
+        # sends the reader to a tool with nothing wrong with it.
+        if shutil.which("node", path=without["PATH"]) is None:
+            return skip_scenario(
+                label,
+                "node does not resolve on the PATH this scenario built, so the "
+                "openspec shim it resolves would have no interpreter. That is a "
+                "broken fixture, not a fact about openspec.",
+            )
+        resolved = run_openspec(ROOT, "--version", env=without)
+        if resolved is None:
+            report(
+                f"{label}: with no `openspec` on PATH the runner resolved "
+                "nothing, but this package declares it as a dependency and "
+                "installs it at node_modules/.bin. A tool the repository ships "
+                "is not a tool the host has to provide."
+            )
+            return 1
+        if resolved.returncode != 0 or not re.search(
+            r"\d+\.\d+\.\d+", resolved.stdout
+        ):
+            report(
+                f"{label}: the resolved openspec did not report a version. "
+                f"exit={resolved.returncode} out={(resolved.stdout or '').strip()!r}"
+            )
+            return 1
 
     # And it is the declared one, not whatever a host happens to carry.
     declared = ROOT / "node_modules" / ".bin" / "openspec"
@@ -14043,6 +14054,60 @@ OPENSPEC_SEARCH_ORDER = (
 )
 
 
+@contextlib.contextmanager
+def path_without_openspec(path: str | None = None):
+    """Yield `path` with every `openspec` executable on it removed, and nothing else.
+
+    Dropping a PATH *directory* because it holds an `openspec` also drops that
+    directory's other contents. On the ordinary Homebrew plus `npm install -g`
+    layout one directory holds both `openspec` and `node`, so the filter took the
+    interpreter the openspec shim needs and the scenario built on it asserted that
+    a shell without an interpreter fails — reported against `openspec`, which was
+    installed and working (issue #137).
+
+    So a directory that holds the tool is replaced in place, at the same index, by
+    a mirror symlinking every one of its entries except the `openspec` ones; a
+    directory that does not hold it is passed through untouched. Exclusion is by
+    stem, so `openspec.cmd` and its siblings cannot survive a filter whose whole
+    purpose is that the name does not resolve.
+
+    The mirrors live for the duration of the context, so callers must hold it open
+    across every child process they run against the PATH, not only across the call
+    that built it.
+    """
+    original = os.environ.get("PATH", "") if path is None else path
+    entries = [entry for entry in original.split(os.pathsep) if entry]
+    with tempfile.TemporaryDirectory(prefix="keel-no-openspec-") as raw:
+        mirrors = Path(raw)
+        rebuilt: list[str] = []
+        for index, entry in enumerate(entries):
+            source = Path(entry)
+            try:
+                contents = sorted(source.iterdir())
+            except OSError:
+                # Unreadable or absent: it carried nothing resolvable either way.
+                rebuilt.append(entry)
+                continue
+            if not any(item.stem == "openspec" for item in contents):
+                rebuilt.append(entry)
+                continue
+            mirror = mirrors / str(index)
+            try:
+                mirror.mkdir()
+                for item in contents:
+                    if item.stem == "openspec":
+                        continue
+                    (mirror / item.name).symlink_to(item)
+            except OSError:
+                # Windows can refuse a symlink without the privilege. Fall back to
+                # dropping the directory, which is what this replaces; the caller's
+                # precondition check then reports the consequence by name instead
+                # of attributing it to the tool.
+                continue
+            rebuilt.append(str(mirror))
+        yield os.pathsep.join(rebuilt)
+
+
 def resolve_openspec(env: dict[str, str] | None = None) -> str | None:
     local = ROOT / "node_modules" / ".bin" / "openspec"
     if local.is_file():
@@ -24659,14 +24724,13 @@ def validate_dependency_resolves_where_npm_put_it_scenario() -> int:
         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.
+    # from the machine running the suite. Removed by file rather than by
+    # directory: one directory holds `openspec` and `node` on the ordinary
+    # Homebrew plus `npm install -g` layout, and the children below are run by
+    # `node` (issue #137).
     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()
-        ]
+        entries = [entry for entry in sanitized_path.split(os.pathsep) if entry]
         if extra_path is not None:
             entries.insert(0, str(extra_path))
         env["PATH"] = os.pathsep.join(entries)
@@ -24696,7 +24760,21 @@ def validate_dependency_resolves_where_npm_put_it_scenario() -> int:
             "",
         )
 
-    with tempfile.TemporaryDirectory(prefix="keel-hoisted-") as raw:
+    # The mirrors live for the duration of the context, so it stays open across
+    # every child process below rather than only across the call that built it.
+    with path_without_openspec() as sanitized_path, tempfile.TemporaryDirectory(
+        prefix="keel-hoisted-"
+    ) as raw:
+        # The scenario's own precondition, asserted before the behavior: every
+        # assertion below runs `node`, so a PATH without one is a broken fixture
+        # and not a fact about where the dependency resolves.
+        if shutil.which("node", path=sanitized_path) is None:
+            return skip_scenario(
+                label,
+                "node does not resolve on the PATH this scenario built, and "
+                "every assertion below runs the installed Keel through it. That "
+                "is a broken fixture, not a fact about openspec.",
+            )
         root = Path(raw)
 
         # The layout npm actually produces: Keel unpacked under the consumer's
@@ -26016,6 +26094,258 @@ def validate_drift_names_where_to_look_scenario() -> int:
 # `M<n>` was reported as naming a check the task does not declare — first, and
 # as somebody else's fault. The reporter calls it the only diagnostic in 149
 # invocations that made them edit the wrong file.
+
+# `## Expectation Coverage` carries the protocol's one global assertion — every
+# expectation has an owner — and 80% of its closures were the single form with
+# nothing behind them. Issue #133 ran the set difference by hand over 24
+# archived changes and found six wrong claims, all of them already past
+# change-close and a semantic Review. The operation that finds them is between
+# two identifier lists the author already declared, in one file.
+def validate_coverage_claim_is_compared_scenario() -> int:
+    label = "a-coverage-claim-is-compared"
+
+    design = (
+        "## Context\n\nfixture\n\n## Decisions\n\n"
+        "- F1 — the first fact the fixture declares.\n"
+        "- F2 — the second fact the fixture declares.\n"
+        "- D1 — the decision no task of the fixture covers.\n"
+    )
+
+    def task(tid: str, covers: str) -> str:
+        return "\n".join((
+            f"- [x] {tid} Coverage probe",
+            "  - Owner: claude",
+            "  - Mode: implementation",
+            "  - Covers:",
+            f"    - {covers}",
+            "  - Read:",
+            "    - README.md",
+            "  - Touch:",
+            "    - src/example.js",
+            "  - Verify:",
+            "    - Strategy: evidence-first",
+            "    - Reason: fixture; nothing here can fail first",
+            "    - M1: the check asserts the public behavior",
+            "  - Autonomy boundary:",
+            "    - Default: hard-stop",
+            "    - Pre-authorized fallback: none",
+            "  - Stop Rules:",
+            "    - Stop if the fixture needs a decision it cannot make.",
+            "  - Evidence:",
+            "    - Contract: pending",
+            "    - M1: pass. ran it.",
+            "    - Review:",
+            "      - Status: pass",
+            "      - Acceptance check: M1 asserts the behavior at its interface.",
+            "      - Scope check: only src/example.js changed.",
+            "      - Findings: none",
+            "    - Blocker: none",
+            "    - Reauthorizations: none",
+            "",
+        ))
+
+    def fixture(root: Path, name: str, coverage: str) -> Path:
+        repo = root / name
+        write_gate_fixture(repo, tasks="", design=design)
+        write_text(
+            repo / "openspec/changes/demo/tasks.md",
+            "# Tasks\n\n"
+            + "## Work\n\n"
+            + task("1.1", "F1")
+            + "\n"
+            + task("2.1", "F2")
+            + "\n## Invalidates\n\n- None.\n\n"
+            + "## Expectation Coverage\n\n"
+            + coverage
+            + "\n",
+        )
+        # Both anchors, in order: `Contract: pending` is replaced once per task,
+        # first occurrence first, and a task's fingerprint covers only its own
+        # authority text, so recording one does not move the other.
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+        for tid in ("1.1", "2.1"):
+            started = run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", tid,
+                "--json", "--no-guard",
+            )
+            try:
+                payload = json.loads(started.stdout)
+            except json.JSONDecodeError:
+                report(
+                    f"{label}: the fixture's task {tid} did not start, so no "
+                    f"anchor could be recorded; "
+                    f"{(started.stderr or started.stdout).strip()[:400]!r}."
+                )
+                raise SystemExit(1)
+            value = (
+                ((payload.get("contract") or {}).get("fingerprint") or {})
+                .get("value") or "0" * 64
+            )
+            tasks_path.write_text(
+                tasks_path.read_text(encoding="utf-8").replace(
+                    "    - Contract: pending",
+                    f"    - Contract: keel-task-capsule/v1 sha256:{value}",
+                    1,
+                ),
+                encoding="utf-8",
+            )
+        return repo
+
+    def close(repo: Path) -> dict:
+        result = run_keel(
+            repo, "gate", "change-close", "--change", "demo", "--action",
+            "archive", "--json",
+        )
+        try:
+            return json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return {"status": "unparsed", "problems": [
+                {"code": "unparsed", "message": result.stdout[:300]}
+            ]}
+
+    def said(payload: dict) -> str:
+        return " ".join(str(x) for x in (payload.get("warnings") or []))
+
+    agree = "- E1: the first expectation (F1). Covered by: 1.1\n" \
+            "- E2: the second expectation (F2). Covered by: 2.1\n"
+    # The identifier is covered — by the other task.
+    mismatch = "- E1: the first expectation (F2). Covered by: 1.1\n" \
+               "- E2: the second expectation. Covered by: 2.1\n"
+    # The identifier is covered by nothing.
+    orphan = "- E1: the first expectation (D1). Covered by: 1.1\n" \
+             "- E2: the second expectation. Covered by: 2.1\n"
+    # Same entry as `mismatch` with the citation removed, and nothing else.
+    prose = "- E1: the first expectation. Covered by: 1.1\n" \
+            "- E2: the second expectation. Covered by: 2.1\n"
+    # Issue #133's contradiction: one identifier claimed covered and deferred.
+    contradiction = "- E1: the first expectation (F2). Covered by: 1.1\n" \
+                    "- E2: the same identifier, deferred (F2). " \
+                    "Durable owner: https://github.com/TanglmChris/keel/issues/133\n"
+
+    with tempfile.TemporaryDirectory(prefix="keel-coverage-claim-") as raw:
+        root = Path(raw)
+
+        # The control comes first: without a fixture that closes, every later
+        # refusal could be something else refusing.
+        settled = close(fixture(root, "agree", agree))
+        if settled.get("status") != "pass":
+            report(
+                f"{label}: the agreeing fixture does not close, so no later "
+                f"refusal can be attributed; {problem_text(settled)!r}."
+            )
+            return 1
+        wrong = close(fixture(root, "mismatch", mismatch))
+        if wrong.get("status") != "fail":
+            report(
+                f"{label}: a claim that task 1.1 covers F2 was accepted while "
+                f"1.1's Covers names only F1; change-close returned "
+                f"Status: {wrong.get('status')}."
+            )
+            return 1
+        text = problem_text(wrong)
+        if "E1" not in text:
+            report(f"{label}: the refusal does not name the entry; {text!r}.")
+            return 1
+        if "F2" not in text:
+            report(
+                f"{label}: the refusal does not name the identifier it could "
+                f"not find; {text!r}."
+            )
+            return 1
+        if "2.1" not in text:
+            report(
+                f"{label}: the refusal does not name the task whose Covers "
+                f"does hold F2, so the author is told the claim is wrong and "
+                f"must re-derive which of three shapes it is; {text!r}."
+            )
+            return 1
+
+        nowhere = close(fixture(root, "orphan", orphan))
+        if nowhere.get("status") != "fail":
+            report(
+                f"{label}: a claim naming an identifier no task covers was "
+                f"accepted; change-close returned Status: {nowhere.get('status')}."
+            )
+            return 1
+        text = problem_text(nowhere)
+        if "D1" not in text:
+            report(
+                f"{label}: the refusal does not name the uncovered identifier; "
+                f"{text!r}."
+            )
+            return 1
+        # The distinction is which of the two halves the refusal chose, not
+        # whether a task id appears at all — the entry's own claim names one.
+        if "is covered by task" in text:
+            report(
+                f"{label}: the refusal points at a task as the place D1 is "
+                f"covered, which sends the author to a capsule with nothing "
+                f"wrong in it; {text!r}."
+            )
+            return 1
+        if "No task of this change covers" not in text:
+            report(
+                f"{label}: the refusal does not say that no task covers it, so "
+                f"the shape issue #133 measured as the serious one is not told "
+                f"apart from a wrong task id; {text!r}."
+            )
+            return 1
+
+        # Citing is optional, and the fixture proving it is the mismatch with
+        # its one citation removed — so a rule that refused prose would have to
+        # refuse this and nothing else about it changed.
+        quiet = close(fixture(root, "prose", prose))
+        if quiet.get("status") != "pass":
+            report(
+                f"{label}: an entry citing no identifier was refused; "
+                f"{problem_text(quiet)!r}."
+            )
+            return 1
+
+        # D3: the report's second suggestion is unnecessary, because the
+        # comparison already refuses the case it was aimed at.
+        both = close(fixture(root, "contradiction", contradiction))
+        if both.get("status") != "fail":
+            report(
+                f"{label}: the same identifier claimed covered by a task that "
+                f"omits it and deferred to a tracker was accepted; "
+                f"change-close returned Status: {both.get('status')}."
+            )
+            return 1
+        text = problem_text(both)
+        if "F2" not in text:
+            report(
+                f"{label}: the contradiction was refused for something other "
+                f"than the identifier it is about; {text!r}."
+            )
+            return 1
+
+        # How far the comparison reached, read off the control run above.
+        spoken = said(settled)
+        if "Expectation Coverage" not in spoken:
+            report(
+                f"{label}: the close does not report how much of the section "
+                f"it compared, so a pass reads as a warrant it does not carry; "
+                f"{spoken!r}."
+            )
+            return 1
+        if "2" not in spoken:
+            report(
+                f"{label}: the report does not carry the compared count; "
+                f"{spoken!r}."
+            )
+            return 1
+        if "0" not in spoken:
+            report(
+                f"{label}: the report is suppressed when every entry was "
+                f"compared, which teaches a reader that its absence means full "
+                f"coverage; {spoken!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
 def validate_reference_outlives_its_declaration_scenario() -> int:
     label = "a-reference-outlives-its-declaration"
 
@@ -27193,6 +27523,109 @@ def validate_authored_scenario_names_scenario() -> int:
     return 0
 
 
+def validate_a_filter_drops_only_what_it_named_scenario() -> int:
+    """Issue #137: a PATH built to exclude one tool removed a whole directory.
+
+    Both scenarios that need "no openspec on PATH" dropped every directory that
+    held an `openspec`. On the ordinary Homebrew plus `npm install -g` layout one
+    directory holds `openspec` and `node`, so the filter took the interpreter the
+    openspec shim needs, and the diagnostic named `openspec` — a tool that was
+    installed and working.
+
+    The defect is a layout, so the fixture builds the layout instead of relying on
+    this host having it: a directory carrying both binaries, on a PATH between two
+    that carry neither. Asserted from both sides — that the runtime survived is the
+    regression guard, that the tool is gone is the positive control, because a
+    mirror that produced an empty directory would satisfy the second alone.
+    """
+    label = "a-filter-drops-only-what-it-named"
+
+    def write_executable(path: Path, body: str) -> None:
+        path.write_text(body, encoding="utf-8")
+        path.chmod(0o755)
+
+    with tempfile.TemporaryDirectory(prefix="keel-shared-bin-") as raw:
+        root = Path(raw)
+        before = root / "before"
+        shared = root / "shared"
+        after = root / "after"
+        for directory in (before, shared, after):
+            directory.mkdir()
+        write_executable(before / "tool-a", "#!/bin/sh\necho a\n")
+        write_executable(after / "tool-b", "#!/bin/sh\necho b\n")
+        # The layout under test: the interpreter and the tool in one directory,
+        # plus a neighbour that belongs to neither and must survive with it.
+        write_executable(shared / "node", "#!/bin/sh\necho node\n")
+        write_executable(shared / "openspec", "#!/bin/sh\necho 1.12.0\n")
+        write_executable(shared / "openspec.cmd", "#!/bin/sh\necho 1.12.0\n")
+        write_executable(shared / "unrelated", "#!/bin/sh\necho unrelated\n")
+
+        source = os.pathsep.join(str(entry) for entry in (before, shared, after))
+        with path_without_openspec(source) as sanitized:
+            entries = sanitized.split(os.pathsep)
+
+            # Behavior before shape: what the defect destroys is the ability to
+            # run the interpreter, and an entry count is only its symptom.
+            node = shutil.which("node", path=sanitized)
+            if node is None:
+                report(
+                    f"{label}: node did not survive a filter that was removing "
+                    f"openspec. The interpreter shares a directory with the "
+                    f"tool, and the whole directory went. sanitized PATH "
+                    f"{sanitized!r}"
+                )
+                return 1
+            if shutil.which("unrelated", path=sanitized) is None:
+                report(
+                    f"{label}: an executable unrelated to openspec was removed "
+                    f"along with it."
+                )
+                return 1
+
+            # The positive control. Without it, an empty mirror passes.
+            for name in ("openspec", "openspec.cmd"):
+                found = shutil.which(name, path=sanitized)
+                if found is not None:
+                    report(
+                        f"{label}: {name} still resolves on a PATH built to "
+                        f"exclude it, at {found!r}."
+                    )
+                    return 1
+
+            if len(entries) != 3:
+                report(
+                    f"{label}: the sanitized PATH has {len(entries)} entries, "
+                    f"not the 3 it was given, so search order did not survive. "
+                    f"got {sanitized!r}"
+                )
+                return 1
+            if Path(node).parent != Path(entries[1]):
+                report(
+                    f"{label}: node survived but moved search position; it "
+                    f"resolved from {str(Path(node).parent)!r}, not from PATH "
+                    f"entry 1 {entries[1]!r}."
+                )
+                return 1
+
+            # M2: an entry that does not hold the tool is passed through, not
+            # mirrored — the cost and the blast radius stay on the directories
+            # that carry it.
+            for index, original in ((0, before), (2, after)):
+                if entries[index] != str(original):
+                    report(
+                        f"{label}: a PATH entry holding no openspec was "
+                        f"rewritten; expected {str(original)!r}, got "
+                        f"{entries[index]!r}."
+                    )
+                    return 1
+
+    if label not in {name for name, _ in SCENARIOS}:
+        report(f"{label}: the scenario registry does not include it.")
+        return 1
+    report(f"{label} scenario passed.")
+    return 0
+
+
 SCENARIOS: tuple = (
     ("stateless-continuity", validate_stateless_continuity_scenario),
     ("core-gates", validate_core_gates_scenario),
@@ -27239,6 +27672,7 @@ SCENARIOS: tuple = (
     ("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),
+    ("a-coverage-claim-is-compared", validate_coverage_claim_is_compared_scenario),
     ("a-reference-outlives-its-declaration", validate_reference_outlives_its_declaration_scenario),
     ("the-obligation-is-stated-early", validate_obligation_is_stated_early_scenario),
     ("an-explanation-is-printed-once", validate_explanation_is_printed_once_scenario),
@@ -27534,6 +27968,10 @@ SCENARIOS: tuple = (
         "change-verify-deferred-evidence",
         validate_change_verify_deferred_evidence_scenario,
     ),
+    (
+        "a-filter-drops-only-what-it-named",
+        validate_a_filter_drops_only_what_it_named_scenario,
+    ),
 )
 
 

package/src/core/gates.js

@@ -1536,27 +1536,54 @@ function invalidationProblems(repo, content, tasks, change) {
   return problems;
 }
 
+// `Covered by:` is the closure form with nothing behind it. `Durable owner:`
+// checks that the path or reference exists; `Discard reason:` requires a
+// reason; a coverage claim was checked only for whether the task it named was
+// checked, never for whether that task claimed the same thing back. Issue #133
+// ran the set difference by hand over 24 archived changes: 6 of the 42 citing
+// entries were wrong, all of them already past this gate and a semantic Review.
+// The two lists are declared, structured, and in one file — a reader will not
+// diff them by eye, which is the whole reason it is worth a gate.
+//
+// `I<n>` is deliberately not compared: an `## Invalidates` entry has its own
+// closure check that already requires `Updated by:` to name tasks of this
+// change, so an E entry citing one is a second and weaker claim about
+// something already owned.
+const CRITICAL_ID = /\b([FDAQ]\d+)\b/g;
+
+function coversByIdentifier(tasks) {
+  const index = new Map();
+  for (const task of tasks) {
+    for (const match of field(task, "Covers").matchAll(CRITICAL_ID)) {
+      const list = index.get(match[1]) || [];
+      if (!list.includes(task.id)) list.push(task.id);
+      index.set(match[1], list);
+    }
+  }
+  return index;
+}
+
 function expectationProblems(repo, content, tasks, change) {
   const heading = content.search(/^## Expectation Coverage\s*$/m);
   if (heading < 0) {
-    return [
+    return { problems: [
       problem(
         "expectation-coverage",
         "tasks.md requires a `## Expectation Coverage` section: one "
           + "`- E<n>: <expectation> Covered by: <task ids>` line per "
           + "expectation, or `- None.`."
       ),
-    ];
+    ], report: null };
   }
   const section = sectionBody(content, heading, tasks);
-  if (/^\s*-\s+None\.?\s*$/im.test(section)) return [];
+  if (/^\s*-\s+None\.?\s*$/im.test(section)) return { problems: [], report: null };
   const entries = [
     ...section.matchAll(
       /^\s*-\s+(E\d+)\s*:\s*([\s\S]*?)(?=^\s*-\s+E\d+\s*:|(?![\s\S]))/gm
     ),
   ];
   if (entries.length === 0) {
-    return [
+    return { problems: [
       problem(
         "expectation-coverage",
         "Expectation Coverage must declare each `E<n>` closure — "
@@ -1564,9 +1591,12 @@ function expectationProblems(repo, content, tasks, change) {
           + "path or `https://…` tracker reference, or a `Discard reason:` — "
           + "or `- None.`."
       ),
-    ];
+    ], report: null };
   }
   const problems = [];
+  const coverage = coversByIdentifier(tasks);
+  let compared = 0;
+  let uncited = 0;
   for (const entry of entries) {
     const [, id, body] = entry;
     const covered = body.match(/Covered by:\s*([0-9.,\s-]+)/i);
@@ -1617,9 +1647,52 @@ function expectationProblems(repo, content, tasks, change) {
           );
         }
       }
+      // Read from the entry with its closure clause removed, so a task id in
+      // `Covered by:` can never be mistaken for a statement identifier.
+      const claim = body.replace(/Covered by:[\s\S]*/i, "");
+      const cited = [
+        ...new Set([...claim.matchAll(CRITICAL_ID)].map((match) => match[1])),
+      ];
+      if (cited.length === 0) uncited += 1;
+      else compared += 1;
+      for (const reference of cited) {
+        if (ids.some((taskId) => (coverage.get(reference) || []).includes(taskId))) {
+          continue;
+        }
+        const elsewhere = coverage.get(reference) || [];
+        // Naming where it actually is turns the three shapes issue #133
+        // measured — wrong task, deferred and claimed at once, covered by
+        // nothing — into one edit instead of an investigation. The information
+        // is free: the same parse already holds every task's Covers.
+        problems.push(
+          problem(
+            "expectation-coverage-mismatch",
+            `${id} says ${ids.join(", ")} covers ${reference}, and `
+              + `${ids.length > 1 ? "none of those tasks names" : `task ${ids[0]} does not name`} `
+              + `it in Covers. ${
+                elsewhere.length > 0
+                  ? `${reference} is covered by task ${elsewhere.join(", ")}.`
+                  : `No task of this change covers ${reference}.`
+              } Name the task that covers it, add ${reference} to the Covers `
+              + "of the task named, or drop the citation if the mention is not "
+              + "a coverage claim."
+          )
+        );
+      }
     }
   }
-  return problems;
+  // Stated whatever the numbers are: a line that appears only when something
+  // was skipped teaches the reader that its absence means full coverage, and
+  // in the repository that filed #133 the uncompared share is 58%.
+  const report =
+    compared + uncited > 0
+      ? `Expectation Coverage: compared ${compared} of ${compared + uncited} `
+        + `\`Covered by:\` ${compared + uncited === 1 ? "entry" : "entries"} `
+        + `against the Covers of the task named; ${uncited} cited no `
+        + `expectation identifier and ${uncited === 1 ? "was" : "were"} not `
+        + "compared."
+      : null;
+  return { problems, report };
 }
 
 function hasDeltaSpec(changePath) {
@@ -1708,9 +1781,10 @@ function changeClose(repo, options) {
       )
     );
   }
-  problems.push(
-    ...expectationProblems(repo, selection.content, selection.tasks, selection.change)
+  const expectations = expectationProblems(
+    repo, selection.content, selection.tasks, selection.change
   );
+  problems.push(...expectations.problems);
   problems.push(...changeVerifyProblems(selection.content, selection.tasks));
 
   const changePath = path.dirname(selection.tasksPath);
@@ -1744,7 +1818,7 @@ function changeClose(repo, options) {
     selection.change,
     selection.tasks.map((task) => task.id),
     [...problems, ...reviewProblems],
-    [],
+    expectations.report ? [expectations.report] : [],
     null,
     contracts
   );