@christang/keel 5.46.0 → 5.48.0

package/README.md

@@ -280,8 +280,10 @@ command at the right moment. Three things make that happen.
 - **The hooks.** A SessionStart hook runs the continuity projection the moment a session
   opens; a PreToolUse hook enforces the write guard on every edit. Neither needs prompting.
 
-So in day-to-day use you run two commands: `keel --init` once, and `keel --doctor` when you
-want to check the wiring. Everything below is the vocabulary the agent uses on your behalf.
+So in day-to-day use you run two commands: `keel --doctor` when you want to check the
+wiring, and `keel --init` whenever it tells you the repository is behind its install — the
+protocol version lives in your `AGENTS.md`, and updating the package does not move it.
+Everything below is the vocabulary the agent uses on your behalf.
 
 ## Verification layering
 

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.46.0 -->
+<!-- keel:start version=5.48.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

@@ -983,6 +983,78 @@ function printDoctorLine(name, status, detail = "") {
   process.stdout.write(`${name}: ${status}${detail ? ` - ${detail}` : ""}\n`);
 }
 
+// The `version=` attribute of the managed marker is written by every install
+// and, until this line existed, read back by nothing that runs locally: both
+// marker parsers match `keel:start(?:\s+[^>]*)?` and throw the attributes away.
+// The one reader was the plugin's SessionStart hook, and doctor reports that
+// plugin's activation as manual on every target — so the check might simply not
+// be running, with nothing to distinguish that from agreement. Doctor is the
+// model-free fallback: the declaration comes from the working tree and the
+// running version from this process, so the comparison holds with no plugin at
+// all.
+function declaredProtocolVersion(repo) {
+  const agentsPath = path.join(repo, "AGENTS.md");
+  if (!fs.existsSync(agentsPath)) return null;
+  const match = fs
+    .readFileSync(agentsPath, "utf8")
+    .match(/<!--\s*keel:start\s+version=(\d+\.\d+\.\d+)\s*-->/);
+  return match ? match[1] : null;
+}
+
+// Numeric, not lexical: "5.9.0" precedes "5.10.0" and string order says
+// otherwise. Returns a negative number when `a` is behind `b`.
+function compareVersions(a, b) {
+  const left = a.split(".").map(Number);
+  const right = b.split(".").map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if (left[i] !== right[i]) return left[i] - right[i];
+  }
+  return 0;
+}
+
+// Printed on every run, agreeing or not. A check that is silent when it passes
+// cannot be told apart from a check that did not run, which is the failure this
+// line exists to remove — so silence is never the report.
+function printProtocolVersionDrift(repo, target) {
+  const running = PACKAGE_JSON.version;
+  const declared = declaredProtocolVersion(repo);
+  if (!declared) {
+    printDoctorLine(
+      "protocol",
+      "not comparable",
+      `this CLI is ${running}; the repository declares no protocol version in `
+        + "an AGENTS.md `keel:start` marker — run "
+        + `keel --init --target ${target} to write one`
+    );
+    return;
+  }
+  const order = compareVersions(declared, running);
+  if (order === 0) {
+    printDoctorLine(
+      "protocol",
+      "ok",
+      `repo declares ${declared}, this CLI is ${running}`
+    );
+    return;
+  }
+  // The two directions have different repairs, and the wrong repair is a no-op
+  // that reads as a failure, so the line names the direction rather than the
+  // difference. Drift never reaches the exit code: an out-of-date install is
+  // not a broken one, and a doctor that goes red on release day is a doctor
+  // people switch off.
+  printDoctorLine(
+    "protocol",
+    "warning",
+    order < 0
+      ? `repo declares ${declared}, this CLI is ${running} — the repository is `
+        + `behind its install; run keel --init --target ${target} to bring the `
+        + "protocol forward"
+      : `repo declares ${declared}, this CLI is ${running} — the install is `
+        + "behind the repository, which carries a protocol this CLI cannot "
+        + "enforce; update the Keel package"
+  );
+}
+
 function codexHome() {
   const configured = (process.env.CODEX_HOME || "").trim();
   return path.resolve(configured || path.join(os.homedir(), ".codex"));
@@ -1553,6 +1625,8 @@ function runDoctor(options) {
     );
   }
 
+  printProtocolVersionDrift(repo, options.target);
+
   process.stdout.write("\nProject status:\n");
   const checkStatus = runPython(
     INSTALL_SCRIPT,

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.46.0",
+  "version": "5.48.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.46.0",
+  "version": "5.48.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.46.0",
+  "version": "5.48.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.46.0"
-PROTOCOL_VERSION = "5.46.0"
+PACKAGE_VERSION = "5.48.0"
+PROTOCOL_VERSION = "5.48.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
@@ -5580,6 +5580,205 @@ def validate_a_declared_dependency_is_resolved_scenario() -> int:
     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.
 
@@ -24398,6 +24597,129 @@ def validate_doctor_openspec_honesty_scenario() -> int:
     return 0
 
 
+# The marker's `version=` attribute is written by the installer and, before this
+# scenario, read back by nothing that runs locally: both marker parsers match
+# `keel:start(?:\s+[^>]*)?` and discard the attributes. The only reader was the
+# plugin's SessionStart hook, whose activation doctor itself reports as manual.
+def validate_marker_version_is_read_scenario() -> int:
+    def doctor_protocol_line(repo: Path) -> tuple[str, int]:
+        result = run_keel(repo, "--doctor")
+        line = next(
+            (
+                entry
+                for entry in result.stdout.splitlines()
+                if entry.startswith("protocol:")
+            ),
+            "",
+        )
+        return line, result.returncode
+
+    def write_repo(root: Path, name: str, marker: str | None) -> Path:
+        repo = root / name
+        repo.mkdir()
+        body = "# Agents\n\nSession Start.\n"
+        (repo / "AGENTS.md").write_text(
+            f"{marker}\n{body}" if marker is not None else body,
+            encoding="utf-8",
+        )
+        return repo
+
+    with tempfile.TemporaryDirectory(prefix="keel-marker-version-") as raw:
+        root = Path(raw)
+
+        behind = write_repo(root, "behind", "<!-- keel:start version=5.14.0 -->")
+        line, behind_code = doctor_protocol_line(behind)
+        if not line.startswith("protocol: warning"):
+            report(
+                "the-marker-version-is-read scenario: a repository declaring an "
+                f"older protocol did not warn; got {line!r}."
+            )
+            return 1
+        for needed in ("5.14.0", PACKAGE_VERSION, "keel --init"):
+            if needed not in line:
+                report(
+                    "the-marker-version-is-read scenario: the behind-repository "
+                    f"warning omits {needed!r}; got {line!r}."
+                )
+                return 1
+        if "repository" not in line:
+            report(
+                "the-marker-version-is-read scenario: the warning does not name "
+                f"the repository as the term that is behind; got {line!r}."
+            )
+            return 1
+
+        ahead = write_repo(root, "ahead", "<!-- keel:start version=9.99.0 -->")
+        line, _ = doctor_protocol_line(ahead)
+        if not line.startswith("protocol: warning"):
+            report(
+                "the-marker-version-is-read scenario: a repository declaring a "
+                f"newer protocol did not warn; got {line!r}."
+            )
+            return 1
+        for needed in ("9.99.0", PACKAGE_VERSION, "install"):
+            if needed not in line:
+                report(
+                    "the-marker-version-is-read scenario: the ahead-repository "
+                    f"warning omits {needed!r}; got {line!r}."
+                )
+                return 1
+        if "keel --init" in line:
+            report(
+                "the-marker-version-is-read scenario: a repository ahead of its "
+                f"install was told to re-run keel --init; got {line!r}."
+            )
+            return 1
+
+        agreed = write_repo(
+            root, "agreed", f"<!-- keel:start version={PACKAGE_VERSION} -->"
+        )
+        line, agreed_code = doctor_protocol_line(agreed)
+        if not line.startswith("protocol: ok"):
+            report(
+                "the-marker-version-is-read scenario: agreeing versions did not "
+                f"report ok; got {line!r}."
+            )
+            return 1
+        if line.count(PACKAGE_VERSION) < 2:
+            report(
+                "the-marker-version-is-read scenario: the agreeing line does not "
+                f"print both versions; got {line!r}."
+            )
+            return 1
+
+        # D2: drift is a warning and nothing else. A line that could turn a
+        # pipeline red on release day is a line users switch off.
+        if behind_code != agreed_code:
+            report(
+                "the-marker-version-is-read scenario: drift changed doctor's "
+                f"exit code ({behind_code} vs {agreed_code})."
+            )
+            return 1
+
+        for name, marker in (
+            ("undeclared", None),
+            ("attributeless", "<!-- keel:start -->"),
+        ):
+            repo = write_repo(root, name, marker)
+            line, _ = doctor_protocol_line(repo)
+            if not line.startswith("protocol: not comparable"):
+                report(
+                    f"the-marker-version-is-read scenario: the {name} repository "
+                    f"did not report `not comparable`; got {line!r}."
+                )
+                return 1
+            if "declares" not in line:
+                report(
+                    f"the-marker-version-is-read scenario: the {name} repository "
+                    f"was not told which term is missing; got {line!r}."
+                )
+                return 1
+
+    report("the-marker-version-is-read scenario passed.")
+    return 0
+
+
 # A scenario name, as the registry spells one. Two registered names carry no
 # hyphen — `cli` and `uninstall` — so requiring one would leave exactly those
 # two unchecked, and allowing single words was measured to add no false
@@ -24627,6 +24949,7 @@ SCENARIOS: tuple = (
     ),
     ("cli", validate_cli_scenario),
     ("doctor-openspec-honesty", validate_doctor_openspec_honesty_scenario),
+    ("the-marker-version-is-read", validate_marker_version_is_read_scenario),
     (
         "authored-scenario-names-are-registered",
         validate_authored_scenario_names_scenario,
@@ -24870,6 +25193,10 @@ SCENARIOS: tuple = (
         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,

package/src/core/gates.js

@@ -431,25 +431,58 @@ const DECLARED_PATH_TRAILING = /[.,;:!?)\]}"'\u2019\u201d\u3002\uff0c\u3001\uff1
 // and authors write versions in prose beside an owner.
 const ROOT_FILE_NAME = /^[^\s`]+\.[A-Za-z][A-Za-z0-9]{0,7}$/;
 
-// A declared path is a run of non-whitespace. 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.
+// 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.
 //
-// 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.
+// 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`]+/);
+  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.