@christang/keel 5.44.0 → 5.47.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.44.0 -->
+<!-- keel:start version=5.47.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.44.0",
+  "version": "5.47.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,7 +17,9 @@
     "src/core/",
     "assets/",
     "README.md",
-    "plugins/"
+    "plugins/",
+    "!**/__pycache__",
+    "!**/*.pyc"
   ],
   "scripts": {
     "validate": "node scripts/run_python.js scripts/validate_plugin.py",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.44.0",
+  "version": "5.47.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.44.0",
+  "version": "5.47.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.44.0"
-PROTOCOL_VERSION = "5.44.0"
+PACKAGE_VERSION = "5.47.0"
+PROTOCOL_VERSION = "5.47.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
@@ -5052,7 +5052,10 @@ def validate_authoring_surface_owner_and_tags_scenario() -> int:
             return 1
         created = run_openspec(repo, "new", "change", "surface-probe")
         if created is None:
-            report(f"{label} skipped: the openspec CLI is not on PATH.")
+            report(
+                f"{label} skipped: the openspec CLI could not be found. "
+                "Searched " + ", then ".join(OPENSPEC_SEARCH_ORDER) + "."
+            )
             return 3
         if created.returncode != 0:
             report(f"{label} could not scaffold a change to read the instruction.")
@@ -5268,6 +5271,665 @@ def validate_the_spec_names_the_managed_set_scenario() -> int:
     return 0
 
 
+def validate_an_invalidates_phrase_may_wrap_scenario() -> int:
+    """Issue #108: the quoted phrase had to fit on one line.
+
+    An `## Invalidates` entry carries a quotation, a location, and a closure,
+    and wraps as often as it needs to. The phrase test was
+    `/"[^"\\n]{3,}"/`, so a quotation that ran past the end of a line was
+    reported as `names where to look but not what to look for` — when it named
+    exactly that, and the only repair was to reflow the text.
+
+    The corpus looked clean for the wrong reason: 42 of this repository's 194
+    archived entries span more than one line and none carries a wrapped
+    quotation, because the gate refused every one that did. Five entries in a
+    single session were shortened to fit.
+
+    The bound is the entry, set by the section parser, so a quotation cannot
+    reach past its own entry — asserted below by refusing a second, unquoted
+    entry while the wrapped one is accepted.
+    """
+    label = "an-invalidates-phrase-may-wrap"
+
+    with tempfile.TemporaryDirectory(prefix="keel-wrapped-phrase-") as raw:
+        repo = Path(raw) / "repo"
+        repo.mkdir()
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+        write_text(repo / "openspec/changes/demo/proposal.md", "# Proposal\n")
+        write_text(repo / "openspec/changes/demo/design.md", "## Context\n\nfixture\n")
+        write_text(
+            repo / "openspec/changes/demo/specs/demo/spec.md",
+            "## ADDED Requirements\n",
+        )
+
+        def start(section: str) -> dict:
+            write_text(
+                tasks_path,
+                task_contract_fixture().replace(
+                    "## Invalidates\n\n- None.\n\n", section
+                ),
+            )
+            result = run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+                "--json",
+            )
+            return json.loads(result.stdout)
+
+        def problems(payload: dict) -> str:
+            return " ".join(
+                item.get("code", "") + ": " + item.get("message", "")
+                for item in payload.get("problems", [])
+            )
+
+        wrapped = (
+            '## Invalidates\n\n'
+            '- I1: "the wording that is now wrong and runs on\n'
+            '  past the end of this line" — somewhere in the repo.\n'
+            '  Updated by: 1.1\n\n'
+        )
+        payload = start(wrapped)
+        if payload.get("status") != "pass":
+            report(
+                f"{label}: an entry whose quotation wraps was refused. It named "
+                "the wording a reader would search for; what it did not do was "
+                "fit on one line, and reflowing text is not a repair."
+            )
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        # The requirement itself is unchanged: an entry with no quotation
+        # anywhere in its body is still refused.
+        unquoted = (
+            '## Invalidates\n\n'
+            '- I1: the wording that is now wrong and runs on\n'
+            '  past the end of this line — somewhere in the repo.\n'
+            '  Updated by: 1.1\n\n'
+        )
+        payload = start(unquoted)
+        if payload.get("status") == "pass":
+            report(
+                f"{label}: an entry carrying no quotation at all was accepted. "
+                "Reading the phrase across lines must widen where the quotation "
+                "may sit, not remove the requirement to write one."
+            )
+            return 1
+        if "invalidation-phrase" not in problems(payload):
+            report(
+                f"{label}: the unquoted entry was refused for some other reason, "
+                "so this assertion proves nothing about the phrase check. Got: "
+                + problems(payload)
+            )
+            return 1
+
+        # The bound is the entry. A wrapped quotation in I1 must not satisfy an
+        # unquoted I2 sitting below it.
+        mixed = (
+            '## Invalidates\n\n'
+            '- I1: "the wording that is now wrong and runs on\n'
+            '  past the end of this line" — somewhere in the repo.\n'
+            '  Updated by: 1.1\n'
+            '- I2: some other statement — elsewhere in the repo.\n'
+            '  Updated by: 1.1\n\n'
+        )
+        payload = start(mixed)
+        text = problems(payload)
+        if payload.get("status") == "pass":
+            report(
+                f"{label}: an unquoted entry below a wrapped one was accepted. "
+                "The quotation is bounded by its own entry; if it reaches the "
+                "next one, every entry after a quoted one passes for free."
+            )
+            return 1
+        if "I2" not in text:
+            report(
+                f"{label}: the run failed, but not for I2 — so this assertion "
+                "proves nothing about the entry bound. The unquoted entry is "
+                "the one that must be named. Got: " + text
+            )
+            return 1
+        if "I1" in text:
+            report(
+                f"{label}: the wrapped entry was reported alongside the unquoted "
+                "one. It carries its quotation and must not be named."
+            )
+            report(text)
+            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
+
+
+def validate_the_tarball_is_the_repository_scenario() -> int:
+    """Issue #110: what ships depended on the packer's working tree.
+
+    `files` names `scripts/`, and declaring a `files` array means `.gitignore`
+    stops filtering inside it — while `__pycache__` is not on npm's default
+    exclusion list. Packing one commit twice: 41 files on a clean checkout, 43
+    after anyone has run the Python in `scripts/`.
+
+    The assertion is that every packed file is tracked by Git. That states the
+    requirement directly and cannot be satisfied by a machine's leftovers; a
+    recomputed list of expected files would have to reimplement npm's inclusion
+    rules and would drift from them.
+    """
+    label = "the-tarball-is-the-repository"
+
+    npm = shutil.which("npm")
+    if npm is None:
+        report(f"{label} skipped: npm is not on PATH, and it is what packs.")
+        return 3
+
+    # Reproduce the state the issue reports before asserting anything, so the
+    # check runs against a tree that has the residue rather than one that
+    # happens not to.
+    residue = ROOT / "scripts" / "__pycache__" / "keel-pack-probe.pyc"
+    created_dir = not residue.parent.exists()
+    residue.parent.mkdir(parents=True, exist_ok=True)
+    residue.write_bytes(b"probe\n")
+    try:
+        packed = subprocess.run(
+            [npm, "pack", "--dry-run", "--json"],
+            cwd=ROOT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            check=False,
+        )
+        if packed.returncode != 0:
+            report(f"{label}: npm pack --dry-run failed.")
+            report((packed.stderr or packed.stdout).strip())
+            return 1
+        try:
+            files = [item["path"] for item in json.loads(packed.stdout)[0]["files"]]
+        except (ValueError, KeyError, IndexError):
+            report(f"{label}: could not read the file list from npm pack --json.")
+            report((packed.stdout or "").strip()[:400])
+            return 1
+
+        tracked = subprocess.run(
+            ["git", "ls-files", "-z"],
+            cwd=ROOT,
+            capture_output=True,
+            check=False,
+        )
+        if tracked.returncode != 0:
+            report(f"{label}: git ls-files failed, so tracked state is unknown.")
+            return 1
+        known = {
+            name for name in tracked.stdout.decode("utf-8").split("\0") if name
+        }
+
+        untracked = sorted(path for path in files if path not in known)
+        if untracked:
+            report(
+                f"{label}: {len(untracked)} packed file(s) are not tracked by "
+                "Git, so what ships depends on the machine that packs it "
+                "rather than on the repository:"
+            )
+            for path in untracked:
+                report(f"  {path}")
+            return 1
+        if not files:
+            report(f"{label}: npm pack reported no files, so nothing was checked.")
+            return 1
+    finally:
+        residue.unlink(missing_ok=True)
+        if created_dir:
+            try:
+                residue.parent.rmdir()
+            except OSError:
+                pass
+
+    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: {len(files)} packed files, all tracked.")
+    return 0
+
+
+def validate_a_declared_dependency_is_resolved_scenario() -> int:
+    """Issue #105: the suite looked for its own dependency only on PATH.
+
+    `@fission-ai/openspec` is declared in `package.json` and lands at
+    `node_modules/.bin/openspec`. npm scripts see that directory; a Python
+    subprocess started by `node scripts/run_python.js` does not. So on a
+    checkout that had only run `npm install`, `--all` reported
+    `validation --all failed for: compact-task-authoring` while the schema it
+    was said to be unable to resolve resolved perfectly.
+
+    The second half is that scenario's own condition: an unresolvable CLI and a
+    CLI that ran and refused shared one message, so the reader was sent to a
+    subject with nothing wrong with it.
+    """
+    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
+
+    # And it is the declared one, not whatever a host happens to carry.
+    declared = ROOT / "node_modules" / ".bin" / "openspec"
+    if not declared.exists():
+        report(
+            f"{label}: {declared} is absent, so this scenario cannot tell a "
+            "resolved dependency from a lucky PATH entry. Run `npm install`."
+        )
+        return 3
+
+    # The two failures carry their own messages. Asserted on the emitted text
+    # of the scenario that had them fused, not on the source.
+    fused = (ROOT / "scripts" / "validate_plugin.py").read_text(encoding="utf-8")
+    marker = 'label = "compact-task-authoring"'
+    start = fused.find(marker)
+    if start < 0:
+        report(f"{label}: compact-task-authoring is gone, so its branch cannot be read.")
+        return 1
+    body = fused[start : start + 3000]
+    for needle, why in (
+        ("could not be found", "the unresolvable branch must say the tool was not found"),
+        ("searched", "the unresolvable branch must name where it looked"),
+        ("return 3", "an unresolvable tool reports the skip contract, not a failure"),
+    ):
+        if needle not in body:
+            report(f"{label}: {why}; `{needle}` is absent from its branch.")
+            return 1
+    if re.search(r"if which is None or which\.returncode", body):
+        report(
+            f"{label}: compact-task-authoring still guards two distinct "
+            "failures behind one condition. A tool that was never found and a "
+            "tool that ran and refused are different facts, and reporting the "
+            "first message when the second happened names the wrong cause."
+        )
+        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
+
+
+def validate_a_path_is_what_the_value_declares_scenario() -> int:
+    """Issue #113: the extractor answered with a path the value did not declare.
+
+    Two shapes, measured across five consuming repositories — 624 path-shaped
+    declarations, 34 of them extracting something else.
+
+    A sentence supplies no whitespace. `openspec/FOLLOWUP.md。②接着说别的`
+    extracted whole, because the run is bounded by whitespace and Chinese prose
+    puts none after a path. That half refuses loudly, naming a path nobody
+    wrote.
+
+    A citation outranked the declaration. The backtick branch ran first and
+    searched the whole value, so a `Durable owner:` that named its owner and
+    then quoted another file resolved to the quotation. That half is worse: the
+    quoted file usually exists, so the gate accepts and checks a file the
+    author never declared.
+    """
+    label = "a-path-is-what-the-value-declares"
+
+    with tempfile.TemporaryDirectory(prefix="keel-declared-path-") as raw:
+        repo = Path(raw) / "repo"
+        repo.mkdir()
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+        write_text(repo / "openspec/changes/demo/proposal.md", "# Proposal\n")
+        write_text(repo / "openspec/changes/demo/design.md", "## Context\n\nfixture\n")
+        write_text(
+            repo / "openspec/changes/demo/specs/demo/spec.md",
+            "## ADDED Requirements\n",
+        )
+        for name in (
+            "docs/owner.md",
+            "docs/cited.md",
+            "docs/\u7b2c\u4e00\u7ae0/\u603b\u8bba.md",
+            "AGENTS.md",
+        ):
+            write_text(repo / name, "x\n")
+        write_text(repo / "docs/a b.md", "x\n")
+
+        def completion(findings: str) -> dict:
+            write_text(
+                tasks_path,
+                task_contract_fixture(evidence=("M1: check exercised.",))
+                .replace("- [ ] 1.1", "- [x] 1.1")
+                .replace("      - Status: pending\n", "      - Status: pass\n")
+                .replace(
+                    "      - Acceptance check: pending\n",
+                    "      - Acceptance check: behavior proven through the public CLI.\n",
+                )
+                .replace(
+                    "      - Scope check: pending\n",
+                    "      - Scope check: writes stayed inside Touch.\n",
+                )
+                .replace("      - Findings: pending\n", f"      - Findings: {findings}\n")
+            )
+            record_contract_anchor(repo, "demo")
+            result = run_keel(
+                repo, "gate", "task-complete", "--change", "demo", "--task", "1.1",
+                "--json",
+            )
+            return json.loads(result.stdout)
+
+        def messages(payload: dict) -> str:
+            return " ".join(
+                item.get("message", "") for item in payload.get("problems", [])
+            )
+
+        # --- the citation must not outrank the declaration ---------------
+        cited = "\u5224\u636e\u89c1 `docs/cited.md`"
+        payload = completion(f"still open. Durable owner: docs/owner.md\uff0c{cited}")
+        if payload.get("status") != "pass":
+            report(
+                f"{label}: a value naming an existing owner and then citing "
+                "another existing file was refused."
+            )
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        # Proven by removing the declared owner: the refusal must name it, not
+        # the citation. Without this the assertion above passes either way,
+        # because both files exist.
+        (repo / "docs/owner.md").unlink()
+        payload = completion(f"still open. Durable owner: docs/owner.md\uff0c{cited}")
+        if payload.get("status") == "pass":
+            report(
+                f"{label}: with the declared owner deleted the value still "
+                "passed, so the gate checked the cited file instead. A "
+                "citation that outranks the declaration lets a finding be "
+                "owned by a file the author never named."
+            )
+            return 1
+
+        # Which path the gate looked for, asserted through the reader that
+        # names one. `Findings` reports a single owner refusal for every
+        # unusable owner and never names the path, so the naming half is
+        # asserted where it is actually emitted.
+        def invalidates(closure: str) -> dict:
+            write_text(
+                tasks_path,
+                task_contract_fixture().replace(
+                    "## Invalidates\n\n- None.\n\n",
+                    '## Invalidates\n\n- I1: "the wording that is now wrong" '
+                    f"\u2014 somewhere in the repo. {closure}\n\n",
+                ),
+            )
+            result = run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+                "--json",
+            )
+            return json.loads(result.stdout)
+
+        payload = invalidates(f"Durable owner: docs/owner.md\uff0c{cited}")
+        text = messages(payload)
+        if payload.get("status") == "pass":
+            report(
+                f"{label}: an invalidation entry whose declared owner is "
+                "missing passed, so the gate resolved the citation."
+            )
+            return 1
+        if "docs/cited.md" in text or "docs/owner.md" not in text:
+            report(
+                f"{label}: the refusal named the citation rather than the "
+                f"declared path. Got: {text or '(none)'}"
+            )
+            return 1
+        write_text(repo / "docs/owner.md", "x\n")
+
+        payload = invalidates(f"Durable owner: docs/owner.md\uff0c{cited}")
+        if payload.get("status") != "pass":
+            report(
+                f"{label}: with the declared owner restored the invalidation "
+                "entry was still refused."
+            )
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        # --- a bare run ends where the sentence does ---------------------
+        accepted = (
+            (
+                "a path followed by a CJK terminator and more prose",
+                "still open. Durable owner: docs/owner.md\u3002\u2461\u63a5\u7740\u8bf4\u522b\u7684",
+            ),
+            (
+                "a path followed by a CJK comma",
+                "still open. Durable owner: docs/owner.md\uff0c\u968f\u540e\u8bf4\u660e",
+            ),
+            (
+                "a path whose own segments are CJK words",
+                "still open. Durable owner: docs/\u7b2c\u4e00\u7ae0/\u603b\u8bba.md\u3002\u540e\u6587",
+            ),
+            (
+                "a backticked path containing a space, opening the value",
+                "still open. Durable owner: `docs/a b.md` \u8bf4\u660e",
+            ),
+            (
+                "a backticked path with nothing declared before it",
+                "still open. Durable owner: \u89c1 `docs/cited.md`",
+            ),
+            ("a repository-root file", "still open. Durable owner: AGENTS.md"),
+            ("the same file with a leading dot-slash", "still open. Durable owner: ./AGENTS.md"),
+            (
+                "an ASCII path ending a sentence",
+                "still open. Durable owner: docs/owner.md. Then more text",
+            ),
+        )
+        for description, findings in accepted:
+            payload = completion(findings)
+            if payload.get("status") != "pass":
+                report(f"{label}: {description} was refused.")
+                report(json.dumps(payload.get("problems", []), indent=2))
+                return 1
+
+        # --- the boundary: a non-path stays unrecognized ------------------
+        for description, findings in (
+            ("a bare word", "still open. Durable owner: pending"),
+            ("a version string", "still open. Durable owner: 5.44.0"),
+            (
+                "a separator between two adjacent inline code spans",
+                "still open. Durable owner: \u9996\u7248\u53ea\u88c5 `networkx`/`PyYAML`",
+            ),
+        ):
+            payload = completion(findings)
+            text = messages(payload)
+            if payload.get("status") == "pass":
+                report(f"{label}: {description} was accepted as a durable owner.")
+                return 1
+            if "does not exist" in text:
+                report(
+                    f"{label}: {description} was reported as a missing file. "
+                    "Got: " + text
+                )
+                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
+
+
+def validate_a_root_file_is_a_path_scenario() -> int:
+    """Issue #107: a file at the repository root had no separator to find.
+
+    `declaredPath()` located a path by finding a run of non-whitespace holding
+    a path separator. Nine files sit at this repository's root and every one of
+    them is a legitimate owner, so `Durable owner: AGENTS.md` was refused with
+    `it names neither a check nor a path` — for a path whose file exists. The
+    way past it was `./AGENTS.md`, which is a concession to the extractor
+    rather than a path anyone meant.
+
+    The boundary is what keeps this from becoming worse than the defect: a bare
+    word must stay unrecognized, or `Durable owner: pending` would be reported
+    as a file that does not exist and send the author to create one.
+    """
+    label = "a-root-file-is-a-path"
+
+    with tempfile.TemporaryDirectory(prefix="keel-root-file-") as raw:
+        repo = Path(raw) / "repo"
+        repo.mkdir()
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+        write_text(repo / "openspec/changes/demo/proposal.md", "# Proposal\n")
+        write_text(repo / "openspec/changes/demo/design.md", "## Context\n\nfixture\n")
+        write_text(
+            repo / "openspec/changes/demo/specs/demo/spec.md",
+            "## ADDED Requirements\n",
+        )
+        write_text(repo / "AGENTS.md", "# Agents\n")
+
+        def completion(findings: str) -> dict:
+            write_text(
+                tasks_path,
+                task_contract_fixture(evidence=("M1: check exercised.",))
+                .replace("- [ ] 1.1", "- [x] 1.1")
+                .replace("      - Status: pending\n", "      - Status: pass\n")
+                .replace(
+                    "      - Acceptance check: pending\n",
+                    "      - Acceptance check: behavior proven through the public CLI.\n",
+                )
+                .replace(
+                    "      - Scope check: pending\n",
+                    "      - Scope check: writes stayed inside Touch.\n",
+                )
+                .replace("      - Findings: pending\n", f"      - Findings: {findings}\n")
+            )
+            record_contract_anchor(repo, "demo")
+            result = run_keel(
+                repo, "gate", "task-complete", "--change", "demo", "--task", "1.1",
+                "--json",
+            )
+            return json.loads(result.stdout)
+
+        def messages(payload: dict) -> str:
+            return " ".join(
+                item.get("message", "") for item in payload.get("problems", [])
+            )
+
+        accepted = (
+            ("a root file as a durable owner", "still open. Durable owner: AGENTS.md"),
+            ("a root file as resolution evidence", "repaired. Resolved here: AGENTS.md"),
+            ("the same file spelled with ./", "still open. Durable owner: ./AGENTS.md"),
+            (
+                "a root file ending a sentence",
+                "still open. Durable owner: AGENTS.md.",
+            ),
+        )
+        for description, findings in accepted:
+            payload = completion(findings)
+            if payload.get("status") != "pass":
+                report(
+                    f"{label}: {description} was refused. The file exists at the "
+                    "repository root; requiring a separator refuses a path the "
+                    "author may name and leaves them only a notation to change."
+                )
+                report(json.dumps(payload.get("problems", []), indent=2))
+                return 1
+
+        # Existence still decides.
+        payload = completion("still open. Durable owner: NOT-THERE.md")
+        if payload.get("status") == "pass":
+            report(f"{label}: a root file that does not exist was accepted.")
+            return 1
+
+        # And where the gate names a missing path, it names a root file the
+        # same way. `Findings` reports the generic owner refusal for every
+        # unusable owner and always has; `## Invalidates` is the reader that
+        # names the file, so the naming is asserted there rather than claimed
+        # of a reader that never did it.
+        def invalidates(closure: str) -> dict:
+            write_text(
+                tasks_path,
+                task_contract_fixture().replace(
+                    "## Invalidates\n\n- None.\n\n",
+                    '## Invalidates\n\n- I1: "the wording that is now wrong" '
+                    f"— somewhere in the repo. {closure}\n\n",
+                ),
+            )
+            result = run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+                "--json",
+            )
+            return json.loads(result.stdout)
+
+        payload = invalidates("Durable owner: AGENTS.md")
+        if payload.get("status") != "pass":
+            report(
+                f"{label}: a root file was refused as an invalidation owner. "
+                "One extractor serves every reader, so a form accepted in one "
+                "must be accepted in all."
+            )
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        payload = invalidates("Durable owner: NOT-THERE.md")
+        text = messages(payload)
+        if payload.get("status") == "pass":
+            report(f"{label}: a missing root file closed an invalidation entry.")
+            return 1
+        if "NOT-THERE.md" not in text:
+            report(
+                f"{label}: the refusal for a missing root file did not name it. "
+                "A path is the one form a gate can check, and naming what it "
+                f"looked for is what makes the refusal repairable. Got: {text}"
+            )
+            return 1
+
+        # The boundary: a value with no path shape stays unrecognized, so the
+        # author is not sent to create a file named `pending`.
+        for description, findings in (
+            ("a bare word", "still open. Durable owner: pending"),
+            ("a version string", "still open. Durable owner: 5.44.0"),
+        ):
+            payload = completion(findings)
+            text = messages(payload)
+            if payload.get("status") == "pass":
+                report(f"{label}: {description} was accepted as a durable owner.")
+                return 1
+            if "does not exist" in text:
+                report(
+                    f"{label}: {description} was reported as a file that does "
+                    "not exist. It is not a path, and saying it is missing "
+                    "sends the author to create it. Got: " + text
+                )
+                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
+
+
 def validate_an_owner_outlives_the_change_scenario() -> int:
     """Issue #100: the existence check expires at archive.
 
@@ -9355,7 +10017,10 @@ def validate_spec_template_validates_scenario() -> int:
         )
         return 1
     if run_openspec(ROOT, "--version") is None:
-        report("spec-template-validates skipped: the openspec CLI is not on PATH.")
+        report(
+            "spec-template-validates skipped: the openspec CLI could not be "
+            "found. Searched " + ", then ".join(OPENSPEC_SEARCH_ORDER) + "."
+        )
         return 0
 
     filled = fill_template_slots(shipped.read_text(encoding="utf-8"))
@@ -13309,13 +13974,42 @@ SUPPORTED_VERIFICATION_STRATEGIES = (
 )
 
 
-def run_openspec(cwd: Path, *args: str) -> subprocess.CompletedProcess[str] | None:
-    executable = shutil.which("openspec")
+# `@fission-ai/openspec` is this package's own declared dependency, and
+# `npm install` puts an executable at `node_modules/.bin/openspec`. npm scripts
+# see that directory on PATH; a Python subprocess started by
+# `node scripts/run_python.js` does not — so a checkout that had installed
+# everything it declares reported `validation --all failed for:
+# compact-task-authoring` while the schema it could supposedly not resolve
+# resolved perfectly (issue #105).
+#
+# The declared dependency wins over PATH. It is the version this repository is
+# tested against; a global install that happens to be on PATH is a different
+# version answering for it.
+OPENSPEC_SEARCH_ORDER = (
+    "the package's own node_modules/.bin",
+    "PATH",
+)
+
+
+def resolve_openspec(env: dict[str, str] | None = None) -> str | None:
+    local = ROOT / "node_modules" / ".bin" / "openspec"
+    if local.is_file():
+        return str(local)
+    return shutil.which("openspec", path=(env or os.environ).get("PATH"))
+
+
+def run_openspec(
+    cwd: Path,
+    *args: str,
+    env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str] | None:
+    executable = resolve_openspec(env)
     if executable is None:
         return None
     return subprocess.run(
         [executable, *args],
         cwd=cwd,
+        env=env,
         text=True,
         encoding="utf-8",
         errors="replace",
@@ -14812,10 +15506,22 @@ def validate_compact_task_authoring_scenario() -> int:
     local_root = ROOT / "openspec" / "schemas" / OPENSPEC_SCHEMA_NAME
 
     which = run_openspec(ROOT, "schema", "which", OPENSPEC_SCHEMA_NAME, "--json")
-    if which is None or which.returncode != 0:
-        report("compact-task-authoring could not resolve the schema through OpenSpec.")
-        if which is not None:
-            report((which.stderr or which.stdout).strip())
+    # Two distinct facts, kept apart. A CLI that was never found says nothing
+    # about the schema, and reporting the schema as unresolvable sends the
+    # reader to a subject with nothing wrong with it (issue #105).
+    if which is None:
+        report(
+            "compact-task-authoring skipped: the openspec CLI could not be "
+            "found. Searched " + ", then ".join(OPENSPEC_SEARCH_ORDER)
+            + ". Run `npm install` to provide the declared dependency."
+        )
+        return 3
+    if which.returncode != 0:
+        report(
+            "compact-task-authoring could not resolve the schema through "
+            "OpenSpec. The CLI ran and refused:"
+        )
+        report((which.stderr or which.stdout).strip())
         return 1
     which_payload = json.loads(which.stdout[which.stdout.index("{"):])
     resolved = Path(which_payload.get("path", ""))
@@ -24362,6 +25068,23 @@ SCENARIOS: tuple = (
         "an-owner-outlives-the-change",
         validate_an_owner_outlives_the_change_scenario,
     ),
+    ("a-root-file-is-a-path", validate_a_root_file_is_a_path_scenario),
+    (
+        "a-path-is-what-the-value-declares",
+        validate_a_path_is_what_the_value_declares_scenario,
+    ),
+    (
+        "a-declared-dependency-is-resolved",
+        validate_a_declared_dependency_is_resolved_scenario,
+    ),
+    (
+        "the-tarball-is-the-repository",
+        validate_the_tarball_is_the_repository_scenario,
+    ),
+    (
+        "an-invalidates-phrase-may-wrap",
+        validate_an_invalidates_phrase_may_wrap_scenario,
+    ),
     (
         "the-spec-names-the-managed-set",
         validate_the_spec_names_the_managed_set_scenario,

package/src/core/gates.js

@@ -417,26 +417,80 @@ const DURABLE_OWNER_FORMS =
 // swallows it and the gate looks for a file that cannot exist.
 const DECLARED_PATH_TRAILING = /[.,;:!?)\]}"'\u2019\u201d\u3002\uff0c\u3001\uff1b\uff1a\uff01\uff1f\uff09\u3011\u300b\u300d\u300f]+$/;
 
-// A declared path is a run of non-whitespace holding a separator. What ends a
-// path is whitespace; what a path is *made of* is the filesystem's business,
-// and answering the first question with the second is what refused
-// `notes/note-006-转岗最难的不是流程/note.md` by reporting that
-// `notes/note-006-` does not exist — a path nobody wrote (issue #60). It is the
-// same class as #40 on the worktree-reading side, which survived because that
-// fix repaired one reader rather than how paths are extracted; this is the one
-// extractor every gate reader of a declared path now uses.
+// A file at the repository root carries no separator, and nine of them sit at
+// this repository's root — `AGENTS.md`, `README.md`, `package.json` among them
+// — every one a legitimate owner. Requiring a separator refused them with "it
+// names neither a check nor a path", for a path whose file exists, and left
+// the author only `./AGENTS.md`: a concession to this function rather than a
+// path anyone meant (issue #107).
 //
-// The backtick form wins when present. It is the only way to write a path
-// containing whitespace, and `touchEntries` already strips backticks from a
-// Touch entry, so one authorship stops being spelled two ways depending on
-// which reader will read it.
+// The shape is a trailing extension beginning with a letter. That is what
+// keeps a bare word unrecognized — `Durable owner: pending` reported as a
+// missing file would send the author to create one — and what keeps a version
+// string out, since `5.44.0` would otherwise read as `44` with extension `0`,
+// and authors write versions in prose beside an owner.
+const ROOT_FILE_NAME = /^[^\s`]+\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+
+// What ends a path is whitespace — in a script that separates words with it.
+// Chinese prose does not: a path is followed immediately by its terminator, so
+// a run bounded only by whitespace swallowed the rest of the sentence and
+// `openspec/FOLLOWUP.md。②本波两次重录重验` came back as one path (issue #113,
+// 14 instances across five consuming repositories). These characters are
+// already in `DECLARED_PATH_TRAILING`, which strips what *trails* the run and
+// therefore never reached a terminator sitting inside it.
+//
+// ASCII punctuation keeps the other treatment — permitted inside the run and
+// trimmed from its end — because `a.b/c-d.e` and `f(1)/g` are paths and ASCII
+// prose supplies the whitespace that ends them. The asymmetry follows from the
+// writing system rather than from a preference.
+const PATH_TERMINATORS = "。，、；：！？（）【】《》「」〈〉“”‘’";
+const BARE_DECLARED_PATH = new RegExp(
+  `[^\\s\`${PATH_TERMINATORS}]+/[^\\s\`${PATH_TERMINATORS}]+`
+);
+
+// A declared path is a run of non-whitespace. What a path is *made of* is the
+// filesystem's business, and answering that question with the boundary is what
+// refused `notes/note-006-转岗最难的不是流程/note.md` by reporting that
+// `notes/note-006-` does not exist — a path nobody wrote (issue #60). Adding
+// terminators does not narrow the alphabet: a path whose segments are CJK
+// words still extracts in full, and only its punctuation ends it.
+//
+// The declaration is what the value opens with. A leading backticked path wins
+// because that is the only way to write a path containing whitespace, and
+// `touchEntries` already accepts that form. A backticked span *elsewhere* is a
+// citation: `Findings` is free prose where naming the owner and then quoting a
+// file is ordinary, and taking the quotation first answered with a file the
+// author never declared — one that usually exists, so the gate accepted rather
+// than refused (issue #113, 20 instances). It is still read when the value
+// declares nothing else, which keeps `Durable owner: 见 \`docs/a b.md\`` working.
+// A separator with nothing on either side of it is not a path. Two adjacent
+// inline code spans put one there — `networkx`/`PyYAML` closes one span and
+// opens the next, so a backtick-delimited capture spanning the gap is the
+// single character `/`. Measured twice in the consumer corpus, each time
+// reported as a file that does not exist.
+function backtickedPath(match) {
+  if (!match) return null;
+  const candidate = match[1].trim();
+  if (!candidate.split("/").some(Boolean)) return null;
+  return candidate || null;
+}
+
 function declaredPath(value) {
   const text = String(value || "");
-  const quoted = text.match(/`([^`\n]*\/[^`\n]*)`/);
-  if (quoted) return quoted[1].trim() || null;
-  const bare = text.match(/[^\s`]+\/[^\s`]+/);
-  if (!bare) return null;
-  return bare[0].replace(DECLARED_PATH_TRAILING, "") || null;
+  const leading = backtickedPath(text.match(/^\s*`([^`\n]*\/[^`\n]*)`/));
+  if (leading) return leading;
+  const bare = text.match(BARE_DECLARED_PATH);
+  if (bare) return bare[0].replace(DECLARED_PATH_TRAILING, "") || null;
+  const quoted = backtickedPath(text.match(/`([^`\n]*\/[^`\n]*)`/));
+  if (quoted) return quoted;
+  // The separator form is tried first and is unchanged, so nothing that
+  // resolves today resolves differently. The trim runs before the shape is
+  // judged, so a root file ending a sentence is still a root file.
+  for (const token of text.split(/\s+/)) {
+    const trimmed = token.replace(DECLARED_PATH_TRAILING, "");
+    if (trimmed && ROOT_FILE_NAME.test(trimmed)) return trimmed;
+  }
+  return null;
 }
 
 // A path inside the selected change's own directory exists now and cannot
@@ -1225,7 +1279,15 @@ function invalidationProblems(repo, content, tasks, change) {
   const problems = [];
   for (const entry of entries) {
     const [, id, body] = entry;
-    if (!/"[^"\n]{3,}"/.test(body)) {
+    // The quotation is read across the entry, not one line of it. An entry
+    // carries a quotation, a location, and a closure, and wraps as often as it
+    // needs to — 42 of this repository's 194 archived entries span more than
+    // one line. Requiring the quotation to fit on one refused entries that had
+    // named exactly what was asked for, and offered no repair but reflowing
+    // the text (issue #108). The bound is the entry: `entries` above splits on
+    // the next `I<n>`, so a quotation cannot reach past its own. `Findings` in
+    // this same file is already read as wrapping.
+    if (!/"[^"]{3,}"/.test(body)) {
       problems.push(
         problem(
           "invalidation-phrase",