@christang/keel 5.3.8 → 5.3.9

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.3.8 -->
+<!-- keel:start version=5.3.9 -->
 ## 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.3.8",
+  "version": "5.3.9",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.3.8",
+  "version": "5.3.9",
   "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.3.8",
+  "version": "5.3.9",
   "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/scripts/pretooluse-guard.js

@@ -5,8 +5,10 @@
 // file edits while an explicit keel/guard.json manifest is active. Absence of
 // the manifest allows everything silently; a present-but-untrusted manifest
 // fails closed. The hook never writes state, never spawns the keel CLI, and
-// always exits 0 — denial is expressed only through hook output. Paths that
-// resolve outside the repository root are not product writes and pass through.
+// always exits 0 — denial is expressed only through hook output. The
+// repository is the guard's scope: a path resolving outside it is not a product
+// write and passes through, decided before the manifest is read so that no
+// manifest state can reach it.
 
 const crypto = require("crypto");
 const fs = require("fs");
@@ -116,12 +118,27 @@ function main() {
   }
   const repo =
     typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
-  const manifestPath = path.join(repo, "keel", "guard.json");
-  if (!fs.existsSync(manifestPath)) return 0;
 
   const pathField = FILE_EDIT_TOOLS.get(event.tool_name);
   if (!pathField) return 0;
 
+  // The repository is the guard's scope, so this boundary is settled before the
+  // manifest is read at all. It needs only the event's cwd and target, so no
+  // manifest state — absent, invalid, drifted, or completed — has anything to
+  // say about a path outside it. Deciding it here rather than further down is
+  // what stops a branch added to the manifest section from denying a file the
+  // guard never protected; that ordering has already failed twice.
+  const target = event.tool_input ? event.tool_input[pathField] : null;
+  if (typeof target !== "string" || !target) return 0;
+  const relative = path.relative(repo, path.resolve(repo, target));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return 0;
+  }
+  const candidate = relative.replace(/\\/g, "/");
+
+  const manifestPath = path.join(repo, "keel", "guard.json");
+  if (!fs.existsSync(manifestPath)) return 0;
+
   let manifest = null;
   try {
     manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
@@ -144,14 +161,6 @@ function main() {
   // stop the one thing the completion gate is waiting for. Derived from the
   // manifest's existing `change` field, so no manifest shape changes.
   const recordPrefix = `openspec/changes/${manifest.change}/`;
-
-  const target = event.tool_input ? event.tool_input[pathField] : null;
-  if (typeof target !== "string" || !target) return 0;
-  const relative = path.relative(repo, path.resolve(repo, target));
-  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-    return 0;
-  }
-  const candidate = relative.replace(/\\/g, "/");
   if (candidate.startsWith(recordPrefix)) return 0;
 
   for (const entry of manifest.authority) {

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.3.8"
-PROTOCOL_VERSION = "5.3.8"
+PACKAGE_VERSION = "5.3.9"
+PROTOCOL_VERSION = "5.3.9"
 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
@@ -5132,6 +5132,164 @@ def fill_template_slots(text: str, comments: str = "strip") -> str:
         text = collapsed
 
 
+def validate_guard_scope_is_the_repository_scenario() -> int:
+    """Issue #31: a decision needing no manifest sat downstream of reading one.
+
+    Whether a target lies outside the repository is computable from the event's
+    cwd and target path alone, but the invalid-manifest denial ran first, so a
+    corrupt `keel/guard.json` denied writes to files the guard never protected.
+    The precedence is what is asserted here, not the passthrough: a scenario
+    checking only that an out-of-repo path passes under a valid manifest would
+    have passed before this change too.
+    """
+    hook = ROOT / "plugins/keel/scripts/pretooluse-guard.js"
+    if not hook.is_file():
+        report(f"guard-scope-is-the-repository: missing hook {hook}.")
+        return 1
+
+    with tempfile.TemporaryDirectory(prefix="keel-guard-scope-") as raw:
+        root = Path(raw)
+        repo = root / "repo"
+        outside = root / "scratch"
+        outside.mkdir(parents=True)
+        write_text(repo / "src/feature.js", "// product\n")
+        # A live spec, so the Covers source lands outside the record layer and
+        # authority drift can actually fire. Drifting the change's own tasks.md
+        # produces no drift at all, because the record layer exempts it.
+        live = repo / "openspec/specs/demo-cap/spec.md"
+        write_text(
+            live,
+            "# demo-cap\n\n## Purpose\n\nFixture.\n\n"
+            "### Requirement: The system emits a feed status\n"
+            "The system SHALL emit the recorded feed status.\n\n"
+            "#### Scenario: A status is emitted\n"
+            "- **WHEN** the feed runs\n- **THEN** the status is recorded\n",
+        )
+        write_text(
+            repo / "openspec/changes/demo/tasks.md",
+            "# Tasks\n\n## Invalidates\n\n- None.\n\n"
+            "- [ ] 1.1 Exercise the guard\n"
+            "  - Covers:\n    - demo-cap / The system emits a feed status\n"
+            "  - Touch:\n    - src/feature.js\n"
+            "  - Verify:\n    - Strategy: evidence-first\n    - M1: node test.js\n"
+            "  - Evidence:\n    - Contract: pending\n    - M1: pending\n"
+            "    - Review:\n      - Status: pending\n"
+            "      - Acceptance check: pending\n      - Scope check: pending\n"
+            "      - Findings: pending\n    - Blocker: none\n",
+        )
+        started = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--record", "--json",
+        )
+        if started.returncode != 0:
+            report("guard-scope-is-the-repository: the fixture did not start.")
+            report((started.stdout or started.stderr).strip())
+            return 1
+        manifest_path = repo / "keel/guard.json"
+        manifest_text = manifest_path.read_text(encoding="utf-8")
+        hashed = [
+            item["path"] for item in json.loads(manifest_text).get("authority", [])
+        ]
+        if "openspec/specs/demo-cap/spec.md" not in hashed:
+            report(
+                "guard-scope-is-the-repository: the fixture hashed no authority "
+                f"outside the change directory, so drift cannot fire: {hashed}."
+            )
+            return 1
+
+        def decide(target: Path) -> str:
+            event = json.dumps({
+                "cwd": str(repo),
+                "tool_name": "Edit",
+                "tool_input": {"file_path": str(target)},
+            })
+            result = subprocess.run(
+                ["node", str(hook)],
+                input=event,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                check=False,
+            )
+            out = (result.stdout or "").strip()
+            if not out:
+                return "allow"
+            payload = json.loads(out)["hookSpecificOutput"]
+            return payload.get("permissionDecisionReason", "deny")
+
+        def expect(label: str, target: Path, allow: bool, needle: str = "") -> bool:
+            verdict = decide(target)
+            if allow:
+                if verdict != "allow":
+                    report(f"guard-scope-is-the-repository: {label} was denied.")
+                    report(f"  {verdict}")
+                    return False
+                return True
+            if verdict == "allow":
+                report(f"guard-scope-is-the-repository: {label} was allowed.")
+                return False
+            if needle and needle not in verdict:
+                report(
+                    f"guard-scope-is-the-repository: {label} was denied for the "
+                    f"wrong reason; expected {needle!r}."
+                )
+                report(f"  {verdict}")
+                return False
+            return True
+
+        scratch = outside / "notes.md"
+        # M2 — the in-repository denials must survive the reordering.
+        checks = [
+            expect("an in-Touch write", repo / "src/feature.js", True),
+            expect(
+                "an in-repository path outside Touch",
+                repo / "other.js",
+                False,
+                "outside Touch",
+            ),
+            expect(
+                "the guarded change's own records",
+                repo / "openspec/changes/demo/notes.md",
+                True,
+            ),
+            expect("an out-of-repository write", scratch, True),
+        ]
+
+        # M1, first half — genuine authority drift.
+        write_text(live, live.read_text(encoding="utf-8") + "\nDRIFTED\n")
+        checks.append(
+            expect("an in-Touch write under drift", repo / "src/feature.js", False, "drift")
+        )
+        checks.append(
+            expect("an out-of-repository write under drift", scratch, True)
+        )
+
+        # M1, second half — the corrupt manifest, which is the reported defect.
+        manifest_path.write_text("{ not json", encoding="utf-8")
+        checks.append(
+            expect("an out-of-repository write under a corrupt manifest", scratch, True)
+        )
+        checks.append(
+            expect(
+                "an in-repository write under a corrupt manifest",
+                repo / "src/feature.js",
+                False,
+                "invalid",
+            )
+        )
+        if not all(checks):
+            return 1
+    if "guard-scope-is-the-repository" not in {name for name, _ in SCENARIOS}:
+        report(
+            "guard-scope-is-the-repository: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("guard-scope-is-the-repository scenario passed.")
+    return 0
+
+
 def validate_completion_requires_a_recorded_anchor_scenario() -> int:
     """Issue #30: an unrecorded anchor made the drift guarantee conditional.
 
@@ -14145,6 +14303,10 @@ SCENARIOS: tuple = (
         "completion-requires-a-recorded-anchor",
         validate_completion_requires_a_recorded_anchor_scenario,
     ),
+    (
+        "guard-scope-is-the-repository",
+        validate_guard_scope_is_the_repository_scenario,
+    ),
     ("spec-template-validates", validate_spec_template_validates_scenario),
     (
         "tasks-template-red-green-example",