@christang/keel 5.2.3 → 5.3.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.2.3 -->
+<!-- keel:start version=5.3.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/assets/openspec/schemas/keel-spec-driven/templates/tasks.md

@@ -40,7 +40,11 @@
     - Blocker: none
 
 <!-- Exceptional boundaries are declared only when they differ from defaults:
-     - Mode: diagnose-only (with `Touch: none`) or plan-first
+     - Mode: diagnose-only or repo-action (both with `Touch: none`), or plan-first.
+       repo-action is for a task whose whole effect is an authorized
+       repository-level action — a commit, a tag — and which writes no worktree
+       file; it is the one mode that may commit, and it still may not push,
+       sync, archive, or mark tasks complete
      - Read: additional required starting context beyond the base set
      - Acceptance: a task-specific observable delta the Covers authority does not express
      - Execution recommendation / Rationale: advisory notes for the current agent

package/bin/keel.js

@@ -1344,10 +1344,28 @@ function runDoctor(options) {
   printTargetSurface(repo, options.target);
   printLensSurface(repo, options.target);
   printFastPrePushSurface(repo);
+  printSourceRepoCliResolution(repo);
 
   return checkStatus;
 }
 
+// Only meaningful in Keel's own repository: a bare `keel` resolves to the
+// installed package, so gate commands verify the released CLI rather than the
+// working tree. The failure mode is a silently stale result, not an error, so
+// it is worth stating rather than leaving to be discovered.
+function printSourceRepoCliResolution(repo) {
+  if (!isKeelSourceRepo(repo)) return;
+  process.stdout.write("\nKeel source repository:\n");
+  printDoctorLine(
+    "gate CLI resolution",
+    "advisory",
+    "a bare `keel` runs the installed package, so gate results will not "
+      + "reflect uncommitted changes to gate, contract, or capability code; "
+      + "run `node bin/keel.js gate <stage> . --change <c> --task <t>` "
+      + "instead — the repository argument is required"
+  );
+}
+
 function readFastCheck(repo) {
   const configPath = path.join(repo, "keel", "config.yaml");
   if (!fs.existsSync(configPath)) return null;

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

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

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

@@ -84,6 +84,29 @@ function pathAllowed(candidate, touch) {
   });
 }
 
+// A checked task keeps its records writable so it can finish the Evidence its
+// completion gate requires, but earns no further product authorization. Byte
+// hashing used to enforce this by accident, since ticking the box changed
+// tasks.md; now it is stated. An unreadable or unmatched tasks.md is not read as
+// checked — every gate that compiles the capsule catches that, and denying
+// product writes on a parse miss would trade a real capability for a guess.
+function taskIsChecked(repo, manifest) {
+  const file = path.join(
+    repo, "openspec", "changes", manifest.change, "tasks.md"
+  );
+  let content = "";
+  try {
+    content = fs.readFileSync(file, "utf8");
+  } catch {
+    return false;
+  }
+  const id = manifest.task.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = content.match(
+    new RegExp(`^\\s*-\\s*\\[([ xX])\\]\\s*${id}(?![0-9.])`, "m")
+  );
+  return Boolean(match && match[1].toLowerCase() === "x");
+}
+
 function main() {
   let event = {};
   try {
@@ -114,8 +137,30 @@ function main() {
     return 0;
   }
   const pointer = `${manifest.change}#${manifest.task}`;
+  // The record layer: the guarded change's own directory holds the records the
+  // task produces — its checkbox, Evidence, and Review — not the product it
+  // changes. `keel gate task-complete` already refuses to attribute this
+  // directory as an outside-Touch failure, so denying it here made the guard
+  // 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) {
+    // Same boundary: bytes under the guarded change's own directory are
+    // records, and the capsule fingerprint — which carries no checkbox state
+    // and no Evidence values — is what separates a record write from a
+    // contract change. `keel guard status` and `keel gate task-complete`
+    // compile the capsule and compare it; this hook cannot, and must not guess.
+    if (entry.path.replace(/\\/g, "/").startsWith(recordPrefix)) continue;
     const file = path.join(repo, entry.path);
     let fresh = null;
     try {
@@ -134,13 +179,17 @@ function main() {
     }
   }
 
-  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)) {
+  if (taskIsChecked(repo, manifest)) {
+    deny(
+      `Keel write guard: ${pointer} is checked complete, so it authorizes no `
+        + `further product writes — ${candidate} is denied. Its own `
+        + `${recordPrefix} records stay writable so the task can finish its `
+        + "Evidence. Run `keel guard clear`, then authorize the next task "
+        + "explicitly with `keel gate task-start`."
+    );
     return 0;
   }
-  const candidate = relative.replace(/\\/g, "/");
+
   if (pathAllowed(candidate, manifest.touch)) return 0;
 
   deny(

package/scripts/install_to_repo.py

@@ -33,6 +33,14 @@ KEEL_CONFIG_TEMPLATE = (
     "# Example:\n"
     "#   fast_check: npm test -- --fast\n"
 )
+KEEL_GITIGNORE_PATH = KEEL_ROOT / ".gitignore"
+KEEL_GITIGNORE_TEMPLATE = (
+    "# Keel local state. keel/ otherwise holds project content that belongs in\n"
+    "# version control (config.yaml, CHANGELOG.md, archive/); the write-guard\n"
+    "# manifest is per-clone session state that a gate run writes and\n"
+    "# `keel guard clear` removes.\n"
+    "guard.json\n"
+)
 GITHOOKS_DIR = ".githooks"
 PRE_PUSH_PATH = Path(GITHOOKS_DIR) / "pre-push"
 OPENSPEC_ROOT = Path("openspec")
@@ -222,6 +230,14 @@ def keel_config_action() -> InstallAction:
     )
 
 
+def keel_gitignore_action() -> InstallAction:
+    return InstallAction(
+        relative_path=KEEL_GITIGNORE_PATH,
+        content=KEEL_GITIGNORE_TEMPLATE,
+        strategy="keel-config-scaffold",
+    )
+
+
 def read_fast_check(repo: Path) -> str | None:
     """Return the project's declared fast inner-loop command, or None.
 
@@ -472,6 +488,7 @@ def collect_actions(repo: Path, target: str) -> list[InstallAction]:
 
     actions.append(openspec_config_action())
     actions.append(keel_config_action())
+    actions.append(keel_gitignore_action())
     actions.extend(openspec_schema_actions())
     return actions
 

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.2.3"
-PROTOCOL_VERSION = "5.2.3"
+PACKAGE_VERSION = "5.3.0"
+PROTOCOL_VERSION = "5.3.0"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 OPENSPEC_CONFIG_PATH = Path("openspec/config.yaml")
@@ -4227,6 +4227,410 @@ def validate_source_repo_bootstrap_skip_scenario() -> int:
     return 0
 
 
+TRACKER_OWNER = "https://github.com/TanglmChris/keel/issues/12"
+
+
+def tracker_owner_tasks(findings: str, closure: str) -> str:
+    """One complete, checked task plus one Expectation Coverage closure line."""
+    return (
+        "# Tasks\n\n"
+        "## Expectation Coverage\n\n"
+        "- E1:\n"
+        f"  - {closure}\n\n"
+        "## 1. Work\n\n"
+        "- [x] 1.1 Complete behavior\n"
+        "  - Owner: keel-agent\n"
+        "  - Mode: implementation\n"
+        "  - Covers:\n"
+        "    - E1: public behavior\n"
+        "  - Read:\n"
+        "    - README.md\n"
+        "  - Touch:\n"
+        "    - src/feature.js\n"
+        "  - Commands:\n"
+        "    - M1: node test.js\n"
+        "  - Acceptance:\n"
+        "    - Public behavior passes.\n"
+        "  - Autonomy boundary:\n"
+        "    - Default: hard-stop\n"
+        "    - Pre-authorized fallback: none\n"
+        "  - Coupling: none\n"
+        "  - Candidate Boundary:\n"
+        "    - One candidate.\n"
+        "  - Stop Rules:\n"
+        "    - Stop on failure.\n"
+        "  - Evidence:\n"
+        "    - M1: passed\n"
+        "    - Review:\n"
+        "      - Status: pass\n"
+        "      - Acceptance check: reviewed\n"
+        "      - Scope check: reviewed\n"
+        f"      - Findings: {findings}\n"
+        "    - Blocker: none\n"
+        "  - Stop if:\n"
+        "    - Scope expands.\n"
+        "  - Report:\n"
+        "    - Summary\n"
+    )
+
+
+def validate_tracker_durable_owner_scenario() -> int:
+    """Issue #12: an issue tracker is a durable follow-up owner.
+
+    The gate enumerated three repository-local forms, so a project whose
+    declared follow-up owner is an issue tracker had to write a local note per
+    finding whose only job was to be a shape the gate recognized. The tracker
+    form is now accepted in both places a durable owner is required, and every
+    previously accepted form still passes.
+    """
+    with tempfile.TemporaryDirectory(prefix="keel-tracker-owner-") as raw:
+        repo = Path(raw)
+        tasks = repo / "openspec/changes/demo/tasks.md"
+        write_text(repo / "openspec/changes/demo/proposal.md", "# Proposal\n")
+        write_text(
+            repo / "openspec/changes/demo/specs/demo/spec.md",
+            "## ADDED Requirements\n",
+        )
+
+        def complete(findings: str, closure: str = "Covered by: 1.1"):
+            write_text(tasks, tracker_owner_tasks(findings, closure))
+            return run_keel(
+                repo, "gate", "task-complete",
+                "--change", "demo", "--task", "1.1", "--json",
+            )
+
+        def close(closure: str):
+            write_text(tasks, tracker_owner_tasks("none", closure))
+            return run_keel(
+                repo, "gate", "change-close",
+                "--change", "demo", "--action", "sync", "--json",
+            )
+
+        tracker = complete(f"stale local note; owner {TRACKER_OWNER}")
+        if tracker.returncode != 0:
+            report(
+                "tracker-durable-owner: a finding owned by an absolute tracker "
+                "reference was still refused."
+            )
+            report((tracker.stderr or tracker.stdout).strip())
+            return 1
+
+        unowned = complete("stale local note that names no owner at all")
+        unowned_payload = json.loads(unowned.stdout) if unowned.stdout else {}
+        message = " ".join(
+            problem.get("message", "")
+            for problem in unowned_payload.get("problems", [])
+            if problem.get("code") == "finding-owner"
+        )
+        if unowned.returncode != 3 or "http" not in message:
+            report(
+                "tracker-durable-owner: an unowned finding must still fail, and "
+                "the error must list the tracker form among the accepted ones."
+            )
+            report((unowned.stderr or unowned.stdout).strip())
+            return 1
+
+        handoff = complete("stale local note; owner keel/HANDOFF.md")
+        if handoff.returncode != 3:
+            report(
+                "tracker-durable-owner: keel/HANDOFF.md must still be refused "
+                "as a finding owner."
+            )
+            report((handoff.stderr or handoff.stdout).strip())
+            return 1
+
+        archived = complete("stale local note; owner keel/archive/follow-ups/x.md")
+        if archived.returncode != 0:
+            report(
+                "tracker-durable-owner: the pre-existing keel/archive owner form "
+                "regressed."
+            )
+            report((archived.stderr or archived.stdout).strip())
+            return 1
+
+        closed_by_tracker = close(f"Durable owner: {TRACKER_OWNER}")
+        if closed_by_tracker.returncode != 0:
+            report(
+                "tracker-durable-owner: change-close refused an Expectation "
+                "Coverage durable owner naming a tracker reference."
+            )
+            report((closed_by_tracker.stderr or closed_by_tracker.stdout).strip())
+            return 1
+
+        closed_by_task = close("Covered by: 1.1")
+        if closed_by_task.returncode != 0:
+            report(
+                "tracker-durable-owner: the pre-existing Covered by closure "
+                "regressed at change-close."
+            )
+            report((closed_by_task.stderr or closed_by_task.stdout).strip())
+            return 1
+
+        closed_unowned = close("pending")
+        if closed_unowned.returncode != 3:
+            report(
+                "tracker-durable-owner: change-close must still reject an E1 "
+                "with no coverage, owner, or discard reason."
+            )
+            report((closed_unowned.stderr or closed_unowned.stdout).strip())
+            return 1
+
+    if "tracker-durable-owner" not in {name for name, _ in SCENARIOS}:
+        report("tracker-durable-owner: the scenario registry does not include it.")
+        return 1
+    report("tracker-durable-owner scenario passed.")
+    return 0
+
+
+def validate_guard_manifest_ignored_scenario() -> int:
+    """Issue #11: the guard manifest was written but declared ignorable nowhere.
+
+    Every gate run left an untracked `keel/guard.json` in the project, and
+    because completion attributes working-tree paths against Touch, that is a
+    permanent exception the author re-adjudicates at every completion.
+    """
+    with tempfile.TemporaryDirectory(prefix="keel-guard-ignore-") as raw:
+        project = Path(raw)
+        init = run_keel(project, "--install", "--target", "claude")
+        if init.returncode != 0:
+            report("guard-manifest-ignored: keel --install failed.")
+            report((init.stderr or init.stdout).strip())
+            return 1
+        ignore_path = project / "keel/.gitignore"
+        if not ignore_path.is_file():
+            report(
+                "guard-manifest-ignored: keel --install did not scaffold "
+                "keel/.gitignore."
+            )
+            return 1
+        declared = ignore_path.read_text(encoding="utf-8")
+        if "guard.json" not in declared:
+            report(
+                "guard-manifest-ignored: the scaffolded keel/.gitignore does "
+                "not declare the guard manifest."
+            )
+            report(declared)
+            return 1
+
+        # git must actually honour the declaration: initialize a repository,
+        # write a manifest through a passing task-start, and confirm the path
+        # never appears in porcelain status.
+        if subprocess.run(
+            ["git", "init", "--quiet"], cwd=project, capture_output=True
+        ).returncode != 0:
+            report("guard-manifest-ignored: git init failed in the fixture.")
+            return 1
+        write_text(
+            project / "openspec/changes/demo/tasks.md",
+            tracker_owner_tasks("none", "Covered by: 1.1").replace(
+                "- [x] 1.1", "- [ ] 1.1"
+            ),
+        )
+        started = run_keel(
+            project, "gate", "task-start",
+            "--change", "demo", "--task", "1.1", "--json",
+        )
+        if started.returncode != 0 or not (project / "keel/guard.json").is_file():
+            report(
+                "guard-manifest-ignored: the fixture did not produce a guard "
+                "manifest to test the declaration against."
+            )
+            report((started.stderr or started.stdout).strip())
+            return 1
+        status = subprocess.run(
+            ["git", "status", "--short", "--untracked-files=all"],
+            cwd=project, capture_output=True, encoding="utf-8",
+        )
+        if "guard.json" in (status.stdout or ""):
+            report(
+                "guard-manifest-ignored: git still reports the guard manifest "
+                "after a gate run, so the declaration does not take effect."
+            )
+            report(status.stdout or "")
+            return 1
+
+        # Scaffold once: a project's own file is never rewritten.
+        own = "# mine\nguard.json\nscratch/\n"
+        write_text(ignore_path, own)
+        again = run_keel(project, "--install", "--target", "claude")
+        if again.returncode != 0 or ignore_path.read_text(encoding="utf-8") != own:
+            report(
+                "guard-manifest-ignored: a second install overwrote the "
+                "project's own keel/.gitignore."
+            )
+            report((again.stderr or again.stdout).strip())
+            return 1
+
+    if not (ROOT / "keel/.gitignore").is_file():
+        report(
+            "guard-manifest-ignored: Keel's own repository does not declare "
+            "the guard manifest ignorable."
+        )
+        return 1
+    if "guard-manifest-ignored" not in {name for name, _ in SCENARIOS}:
+        report("guard-manifest-ignored: the scenario registry does not include it.")
+        return 1
+    report("guard-manifest-ignored scenario passed.")
+    return 0
+
+
+def validate_guard_status_is_not_enforcement_scenario() -> int:
+    """Issue #14: `Guard: started` means the manifest was written.
+
+    Authors read it as "writes are being checked now". The two came apart when a
+    session kept plugin state that predated a marketplace switch: the manifest
+    was valid and keel's PreToolUse hook never ran. Keel cannot observe the hook
+    from the repository, so the result must say so rather than imply otherwise.
+    """
+    needles = ("enforcement", "runtime hook", "cannot observe")
+    # Assertive claims only: the honest sentence legitimately denies that a
+    # written manifest proves anything, so a bare "writes are checked" substring
+    # would match the denial itself.
+    forbidden = (
+        "enforcement is active",
+        "enforcement is live",
+        "writes are guarded",
+    )
+    with tempfile.TemporaryDirectory(prefix="keel-guard-honesty-") as raw:
+        project = Path(raw)
+        write_text(
+            project / "openspec/changes/demo/tasks.md",
+            tracker_owner_tasks("none", "Covered by: 1.1").replace(
+                "- [x] 1.1", "- [ ] 1.1"
+            ),
+        )
+        started = run_keel(
+            project, "guard", "start",
+            "--change", "demo", "--task", "1.1", "--json",
+        )
+        if started.returncode != 0:
+            report("guard-status-is-not-enforcement: keel guard start failed.")
+            report((started.stderr or started.stdout).strip())
+            return 1
+        for label, result in (
+            ("start", started),
+            (
+                "status",
+                run_keel(project, "guard", "status", "--json"),
+            ),
+        ):
+            payload = json.loads(result.stdout) if result.stdout else {}
+            warnings = " ".join(payload.get("warnings", []))
+            missing = [needle for needle in needles if needle not in warnings]
+            if missing:
+                report(
+                    f"guard-status-is-not-enforcement: keel guard {label} does "
+                    "not state that the status describes the manifest and that "
+                    "enforcement depends on a runtime hook Keel cannot observe; "
+                    f"missing {missing}."
+                )
+                report(result.stdout or result.stderr or "")
+                return 1
+            if not payload.get("status"):
+                report(
+                    f"guard-status-is-not-enforcement: keel guard {label} lost "
+                    "its status value."
+                )
+                return 1
+            human = run_keel(
+                project,
+                "guard",
+                *(("start", "--change", "demo", "--task", "1.1", "--force")
+                  if label == "start" else ("status",)),
+            )
+            if "runtime hook" not in (human.stdout or ""):
+                report(
+                    f"guard-status-is-not-enforcement: the human-readable keel "
+                    f"guard {label} output omits the enforcement boundary."
+                )
+                report(human.stdout or human.stderr or "")
+                return 1
+            for phrase in forbidden:
+                if phrase in warnings or phrase in (human.stdout or ""):
+                    report(
+                        f"guard-status-is-not-enforcement: keel guard {label} "
+                        f"asserts observed enforcement: {phrase!r}."
+                    )
+                    return 1
+        # The pre-existing durability statement must survive alongside it.
+        status_payload = json.loads(
+            run_keel(project, "guard", "status", "--json").stdout
+        )
+        if not any(
+            "durable authority" in warning
+            for warning in status_payload.get("warnings", [])
+        ):
+            report(
+                "guard-status-is-not-enforcement: the existing durable-authority "
+                "statement was dropped."
+            )
+            return 1
+    if "guard-status-is-not-enforcement" not in {name for name, _ in SCENARIOS}:
+        report(
+            "guard-status-is-not-enforcement: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("guard-status-is-not-enforcement scenario passed.")
+    return 0
+
+
+def validate_source_repo_cli_resolution_scenario() -> int:
+    """Issue #13 item 3: a bare `keel` runs the installed package.
+
+    When the repository under change *is* Keel, gate commands verify the
+    installed CLI rather than the working tree, and the failure mode is a
+    silently stale result rather than an error. One dogfood round was lost to
+    two spurious problems reported by a stale global CLI.
+    """
+    own = run_keel(ROOT, "--doctor")
+    out = own.stdout or ""
+    if "node bin/keel.js" not in out:
+        report(
+            "source-repo-cli-resolution: Keel's own repository is not told to "
+            "run gate commands through its own entry point."
+        )
+        report(out)
+        return 1
+    # The local entry point needs an explicit repository argument; an author
+    # who copies the hint without it gets an unrelated failure.
+    hint = next(
+        (line for line in out.splitlines() if "node bin/keel.js" in line), ""
+    )
+    # The line must be advisory: it describes a hazard, not a repository
+    # failure, so it must never push doctor toward a non-ok verdict.
+    for needle in ("gate", ".", "advisory"):
+        if needle not in hint:
+            report(
+                "source-repo-cli-resolution: the hint does not name a usable "
+                f"invocation, or is not advisory; missing {needle!r} in: {hint}"
+            )
+            return 1
+    with tempfile.TemporaryDirectory(prefix="keel-cli-resolution-") as raw:
+        consumer = Path(raw)
+        init = run_keel(consumer, "--init", "--target", "claude")
+        if init.returncode != 0:
+            report("source-repo-cli-resolution: keel --init failed.")
+            report((init.stderr or init.stdout).strip())
+            return 1
+        consumer_doctor = run_keel(consumer, "--doctor")
+        if "node bin/keel.js" in (consumer_doctor.stdout or ""):
+            report(
+                "source-repo-cli-resolution: a consuming project was shown a "
+                "hazard that exists only in Keel's own repository."
+            )
+            report(consumer_doctor.stdout or "")
+            return 1
+    if "source-repo-cli-resolution" not in {name for name, _ in SCENARIOS}:
+        report(
+            "source-repo-cli-resolution: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("source-repo-cli-resolution scenario passed.")
+    return 0
+
+
 def validate_task_capsule_scenario() -> int:
     with tempfile.TemporaryDirectory(prefix="keel-task-capsule-") as raw_tmp:
         repo = Path(raw_tmp)
@@ -9963,6 +10367,294 @@ def expect_guard_allow(
     return 0
 
 
+RECORD_LAYER_SPEC = (
+    "# demo-cap Specification\n\n"
+    "## Purpose\n"
+    "Fixture capability for the record-layer scenario.\n\n"
+    "## Requirements\n"
+    "### Requirement: Guarded behavior holds\n"
+    "The guarded feature MUST keep its public behavior.\n\n"
+    "#### Scenario: Guarded public behavior passes\n"
+    "- **WHEN** the guarded feature runs\n"
+    "- **THEN** it passes\n"
+)
+
+
+def record_layer_tasks(checked: bool = False, touch: str = "src/feature.js") -> str:
+    box = "x" if checked else " "
+    return (
+        "# Tasks\n\n"
+        f"- [{box}] 1.1 Exercise guarded feature\n"
+        "  - Covers:\n"
+        "    - demo-cap / Guarded behavior holds / Guarded public behavior passes\n"
+        "  - Touch:\n"
+        f"    - {touch}\n"
+        "  - Verify:\n"
+        "    - Strategy: evidence-first\n"
+        "    - M1: node test.js\n"
+        "  - Evidence:\n"
+        "    - M1: pending\n"
+    )
+
+
+def mode_fixture_tasks(mode: str, touch: str) -> str:
+    return (
+        "# Tasks\n\n"
+        "- [ ] 1.1 Establish the version baseline\n"
+        f"  - Mode: {mode}\n"
+        "  - Covers:\n"
+        "    - E1: the repository carries its first commit\n"
+        "  - Touch:\n"
+        f"    - {touch}\n"
+        "  - Verify:\n"
+        "    - Strategy: evidence-first\n"
+        "    - M1: git rev-parse HEAD resolves and git log reports one commit\n"
+        "  - Evidence:\n"
+        "    - Contract: pending\n"
+        "    - M1: pending\n"
+    )
+
+
+def validate_repo_action_mode_scenario() -> int:
+    """Issue #8 example 2: a repository action had no legal contract.
+
+    A task whose whole effect is the repository's first commit writes no
+    worktree file, so it has no concrete Touch; it is not diagnose-only,
+    because it has real side effects needing evidence; and `Touch: none` was
+    accepted for no other mode. The author was forced to name a path the task
+    did not write, which then tripped the drift defect in example 1.
+    """
+    label = "repo-action-mode"
+
+    def compile_task(repo: Path, mode: str, touch: str):
+        write_text(repo / "openspec/changes/demo/tasks.md", mode_fixture_tasks(mode, touch))
+        return run_keel(
+            repo, "gate", "task-start",
+            "--change", "demo", "--task", "1.1", "--no-guard", "--json",
+        )
+
+    with tempfile.TemporaryDirectory(prefix="keel-repo-action-") as raw:
+        repo = Path(raw)
+
+        started = compile_task(repo, "repo-action", "none")
+        if started.returncode != 0:
+            report(f"{label}: `Mode: repo-action` with `Touch: none` was rejected.")
+            report((started.stderr or started.stdout).strip())
+            return 1
+        capsule = json.loads(started.stdout).get("contract", {}).get("capsule", {})
+        prohibitions = capsule.get("prohibitions", [])
+        if capsule.get("mode") != "repo-action":
+            report(f"{label}: the capsule did not record the repo-action mode.")
+            return 1
+        if "must not write product files" not in prohibitions:
+            report(
+                f"{label}: repo-action must prohibit product writes; got "
+                f"{prohibitions}."
+            )
+            return 1
+        if "must not commit" in prohibitions:
+            report(
+                f"{label}: repo-action must be the mode that may commit; got "
+                f"{prohibitions}."
+            )
+            return 1
+
+        # Every other mode keeps the commit prohibition.
+        for mode, touch in (
+            ("implementation", "src/feature.js"),
+            ("plan-first", "src/feature.js"),
+            ("diagnose-only", "none"),
+        ):
+            other = compile_task(repo, mode, touch)
+            if other.returncode != 0:
+                report(f"{label}: `Mode: {mode}` regressed and no longer compiles.")
+                report((other.stderr or other.stdout).strip())
+                return 1
+            other_capsule = (
+                json.loads(other.stdout).get("contract", {}).get("capsule", {})
+            )
+            if "must not commit" not in other_capsule.get("prohibitions", []):
+                report(f"{label}: `Mode: {mode}` lost the commit prohibition.")
+                return 1
+            product_write_prohibited = (
+                "must not write product files"
+                in other_capsule.get("prohibitions", [])
+            )
+            if product_write_prohibited != (mode == "diagnose-only"):
+                report(
+                    f"{label}: `Mode: {mode}` changed its product-write "
+                    "prohibition."
+                )
+                return 1
+
+        # repo-action means no worktree writes, so a concrete Touch contradicts it.
+        with_touch = compile_task(repo, "repo-action", "src/feature.js")
+        with_touch_problems = (
+            json.loads(with_touch.stdout).get("problems", [])
+            if with_touch.stdout
+            else []
+        )
+        touch_message = " ".join(
+            item.get("message", "")
+            for item in with_touch_problems
+            if item.get("code") == "invalid-touch"
+        )
+        if with_touch.returncode == 0 or "Touch: none" not in touch_message:
+            report(
+                f"{label}: repo-action with a concrete Touch must fail with a "
+                "diagnostic naming the `Touch: none` it requires."
+            )
+            report((with_touch.stderr or with_touch.stdout).strip())
+            return 1
+
+        unsupported = compile_task(repo, "repo-actions", "none")
+        unsupported_message = " ".join(
+            item.get("message", "")
+            for item in (
+                json.loads(unsupported.stdout).get("problems", [])
+                if unsupported.stdout
+                else []
+            )
+            if item.get("code") == "unsupported-mode"
+        )
+        missing = [
+            mode
+            for mode in ("implementation", "diagnose-only", "plan-first", "repo-action")
+            if mode not in unsupported_message
+        ]
+        if unsupported.returncode == 0 or missing:
+            report(
+                f"{label}: the unsupported-mode diagnostic must list every "
+                f"supported mode; missing {missing}."
+            )
+            report((unsupported.stderr or unsupported.stdout).strip())
+            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_touch_guard_record_layer_scenario() -> int:
+    """Issue #8: the guard denied what the completion gate already forgives.
+
+    `scopeProblems` exempts the selected change's own `openspec/changes/<change>/`
+    directory from outside-Touch attribution, but the guard denied writes there
+    and treated the byte hash of that change's tasks.md as authority, so ticking
+    a checkbox or appending Evidence locked the task out of its own bookkeeping.
+    """
+    label = "touch-guard-record-layer"
+    with tempfile.TemporaryDirectory(prefix="keel-record-layer-") as raw:
+        repo = Path(raw)
+        tasks = repo / "openspec/changes/demo/tasks.md"
+        spec = repo / "openspec/specs/demo-cap/spec.md"
+        write_text(tasks, record_layer_tasks())
+        write_text(spec, RECORD_LAYER_SPEC)
+        write_text(repo / "openspec/changes/other/tasks.md", "# Tasks\n")
+        write_text(repo / "keel/archive/follow-ups/note.md", "# Note\n")
+
+        started = run_keel(
+            repo, "guard", "start", "--change", "demo", "--task", "1.1", "--json"
+        )
+        if started.returncode != 0:
+            report(f"{label}: guard start failed on the fixture.")
+            report((started.stderr or started.stdout).strip())
+            return 1
+        manifest = json.loads(started.stdout).get("manifest", {})
+        authority = [entry.get("path") for entry in manifest.get("authority", [])]
+        if not any(item == "openspec/specs/demo-cap/spec.md" for item in authority):
+            report(
+                f"{label}: the fixture does not record an authority file outside "
+                f"the change directory, so the negative case is untested: {authority}"
+            )
+            return 1
+
+        # The record layer: writable although Touch never named it.
+        if expect_guard_allow(repo, tasks, f"{label} record write"):
+            return 1
+        # A record write already made must not lock the task out of its product
+        # writes — this is the drift half of the reported defect.
+        write_text(tasks, record_layer_tasks().replace("M1: pending", "M1: done"))
+        if expect_guard_allow(repo, repo / "src/feature.js", f"{label} after record write"):
+            return 1
+
+        # The layer is exactly this change's directory, nothing wider.
+        if expect_guard_deny(
+            repo,
+            repo / "openspec/changes/other/tasks.md",
+            ["outside Touch"],
+            f"{label} other change",
+        ):
+            return 1
+        if expect_guard_deny(
+            repo,
+            repo / "keel/archive/follow-ups/note.md",
+            ["outside Touch"],
+            f"{label} archive tree",
+        ):
+            return 1
+
+        # Authority outside the change directory still hashes and still denies.
+        write_text(spec, RECORD_LAYER_SPEC.replace("it passes", "it passes twice"))
+        if expect_guard_deny(
+            repo,
+            repo / "src/feature.js",
+            ["authority drift"],
+            f"{label} real authority drift",
+        ):
+            return 1
+        write_text(spec, RECORD_LAYER_SPEC)
+
+        status = run_keel(repo, "guard", "status", "--json")
+        status_payload = json.loads(status.stdout) if status.stdout else {}
+        codes = [item.get("code") for item in status_payload.get("problems", [])]
+        if status_payload.get("status") != "active" or codes:
+            report(
+                f"{label}: guard status reported {status_payload.get('status')!r} "
+                f"with problems {codes} after a record write; a checkbox or "
+                "Evidence write is not authority drift."
+            )
+            return 1
+
+        # A real contract edit in the same file must still hard-stop, through the
+        # fingerprint rather than through byte hashing.
+        write_text(tasks, record_layer_tasks(touch="src/other.js"))
+        drifted = run_keel(repo, "guard", "status", "--json")
+        drifted_codes = [
+            item.get("code")
+            for item in (json.loads(drifted.stdout) if drifted.stdout else {}).get(
+                "problems", []
+            )
+        ]
+        if "fingerprint-drift" not in drifted_codes:
+            report(
+                f"{label}: editing the task's Touch line did not report "
+                f"fingerprint drift; got {drifted_codes}."
+            )
+            return 1
+
+        # Once checked, product writes stop but the task can still finish its
+        # own records — the completion gate requires that Evidence.
+        write_text(tasks, record_layer_tasks(checked=True))
+        if expect_guard_deny(
+            repo,
+            repo / "src/feature.js",
+            ["checked complete"],
+            f"{label} completed product write",
+        ):
+            return 1
+        if expect_guard_allow(repo, tasks, f"{label} completed record write"):
+            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_touch_write_guard_scenario() -> int:
     with tempfile.TemporaryDirectory(
         prefix="keel-touch-guard-", ignore_cleanup_errors=True
@@ -10752,18 +11444,32 @@ def validate_touch_guard_drift_scenario() -> int:
                 "Exercise guarded feature", "Exercise guarded feature differently"
             ),
         )
-        if expect_guard_deny(
-            repo,
-            repo / "src/feature.js",
-            ["drift", "demo", "1.1", "keel guard start"],
-            "touch-guard-drift authority edit",
+        # A contract edit inside the guarded change's own directory is caught
+        # where the capsule is compiled, not at the next write: the hook cannot
+        # compile, so it cannot separate this from a checkbox or Evidence write
+        # in the same file. It therefore allows the write and `guard status`
+        # reports the drift. Authority *outside* that directory still denies at
+        # write time — see the touch-guard-record-layer scenario.
+        if expect_guard_allow(
+            repo, repo / "src/feature.js", "touch-guard-drift contract edit"
         ):
             return 1
         status = run_keel(repo, "guard", "status", "--json")
-        if status.returncode != 3 or json.loads(status.stdout).get("status") != "drifted":
+        status_payload = json.loads(status.stdout) if status.stdout else {}
+        if status.returncode != 3 or status_payload.get("status") != "drifted":
             report("touch-guard-drift: status did not report drifted.")
             report((status.stderr or status.stdout).strip())
             return 1
+        if not any(
+            item.get("code") == "fingerprint-drift"
+            for item in status_payload.get("problems", [])
+        ):
+            report(
+                "touch-guard-drift: the contract edit was not reported as "
+                "fingerprint drift by the check that compiles the capsule."
+            )
+            report(status.stdout or "")
+            return 1
 
         restarted = run_keel(
             repo, "guard", "start", "--change", "demo", "--task", "1.1", "--json"
@@ -10780,30 +11486,41 @@ def validate_touch_guard_drift_scenario() -> int:
         ):
             return 1
 
+        # A fingerprint-neutral edit to the task's own file is a record write,
+        # not drift. This used to fail closed, which is the defect issue #8
+        # reports: appending Evidence blocked every following write.
         tasks_path.write_text(
             tasks_path.read_text(encoding="utf-8") + "\n", encoding="utf-8"
         )
-        if expect_guard_deny(
-            repo,
-            repo / "src/feature.js",
-            ["drift", "keel guard start"],
-            "touch-guard-drift cosmetic edit fails closed",
+        if expect_guard_allow(
+            repo, repo / "src/feature.js", "touch-guard-drift cosmetic edit"
         ):
             return 1
-        cosmetic = run_keel(
-            repo, "guard", "start", "--change", "demo", "--task", "1.1", "--json"
+        cosmetic = run_keel(repo, "guard", "status", "--json")
+        cosmetic_payload = json.loads(cosmetic.stdout) if cosmetic.stdout else {}
+        if cosmetic_payload.get("status") != "active" or cosmetic_payload.get(
+            "problems"
+        ):
+            report(
+                "touch-guard-drift: a fingerprint-neutral edit to the task's "
+                "own file was reported as a guard problem."
+            )
+            report(cosmetic.stdout or "")
+            return 1
+        restarted_cosmetic = run_keel(
+            repo, "guard", "start", "--change", "demo", "--task", "1.1",
+            "--force", "--json",
         )
-        if cosmetic.returncode != 0:
+        if restarted_cosmetic.returncode != 0:
             report("touch-guard-drift: cosmetic restart failed.")
+            report((restarted_cosmetic.stderr or restarted_cosmetic.stdout).strip())
             return 1
-        third = json.loads(cosmetic.stdout)["manifest"]["fingerprint"]["value"]
+        third = json.loads(restarted_cosmetic.stdout)["manifest"]["fingerprint"][
+            "value"
+        ]
         if third != second:
             report("touch-guard-drift: cosmetic edit drifted the capsule fingerprint.")
             return 1
-        if expect_guard_allow(
-            repo, repo / "src/feature.js", "touch-guard-drift cosmetic restart"
-        ):
-            return 1
 
         write_text(
             tasks_path,
@@ -10999,6 +11716,13 @@ SCENARIOS: tuple = (
         "source-repo-bootstrap-skip",
         validate_source_repo_bootstrap_skip_scenario,
     ),
+    ("tracker-durable-owner", validate_tracker_durable_owner_scenario),
+    ("guard-manifest-ignored", validate_guard_manifest_ignored_scenario),
+    (
+        "guard-status-is-not-enforcement",
+        validate_guard_status_is_not_enforcement_scenario,
+    ),
+    ("source-repo-cli-resolution", validate_source_repo_cli_resolution_scenario),
     ("task-contract-core", validate_task_contract_core_scenario),
     ("task-capsule", validate_task_capsule_scenario),
     ("task-verification-strategies", validate_task_verification_strategies_scenario),
@@ -11026,6 +11750,8 @@ SCENARIOS: tuple = (
     ("native-helper-targets", validate_native_helper_targets_scenario),
     ("native-single-task-matrix", validate_native_single_task_matrix_scenario),
     ("touch-write-guard", validate_touch_write_guard_scenario),
+    ("touch-guard-record-layer", validate_touch_guard_record_layer_scenario),
+    ("repo-action-mode", validate_repo_action_mode_scenario),
     ("touch-guard-drift", validate_touch_guard_drift_scenario),
     ("touch-guard-surface", validate_touch_guard_surface_scenario),
     ("plugin-compaction-continuity", validate_plugin_compaction_continuity_scenario),

package/src/core/gates.js

@@ -246,12 +246,21 @@ function reviewValue(task, label) {
   return match ? match[1].trim() : "";
 }
 
+// The durable-owner forms that are pure shape checks, shared by the Review
+// Findings check and the Expectation Coverage check so a form added to one is
+// never missing from the other. Gates run without network and have never
+// confirmed that an archive path resolves either, so an external tracker
+// reference is no less checkable than what was already accepted; whether the
+// owner is real stays a Review judgment.
+const SHARED_DURABLE_OWNER_FORMS =
+  /(?:\bkeel\/archive\/[A-Za-z0-9._/-]+|\bhttps?:\/\/\S)/i;
+
 function findingOwnerIsDurable(repo, findings) {
   if (/keel\/HANDOFF\.md/i.test(findings)) return false;
   if (/\b(?:explicit\s+)?discard (?:reason|rationale)\s*:/i.test(findings)) {
     return true;
   }
-  if (/\bkeel\/archive\/[A-Za-z0-9._/-]+/i.test(findings)) return true;
+  if (SHARED_DURABLE_OWNER_FORMS.test(findings)) return true;
   const owner = findings.match(
     /\b(openspec\/changes\/[A-Za-z0-9][A-Za-z0-9._-]*\/(?:proposal|design|tasks)\.md)(?:#\d+(?:\.\d+)*)?/i
   );
@@ -452,8 +461,8 @@ function completionChecks(repo, task, contract = null) {
         "finding-owner",
         "Review Findings must be `none` or carry a durable owner — a "
           + "`Discard reason:`/`Discard rationale:` prefix, a `keel/archive/…` "
-          + "path, or an existing `openspec/changes/…` artifact; "
-          + "`keel/HANDOFF.md` is not an owner."
+          + "path, an existing `openspec/changes/…` artifact, or an absolute "
+          + "`https://…` tracker reference; `keel/HANDOFF.md` is not an owner."
       )
     );
   }
@@ -520,7 +529,8 @@ function expectationProblems(content, tasks) {
         "expectation-coverage",
         "Expectation Coverage must declare each `E<n>` closure — "
           + "`- E<n>: <expectation> Covered by: <task ids>`, a `Durable owner:` "
-          + "path, or a `Discard reason:` — or `- None.`."
+          + "path or `https://…` tracker reference, or a `Discard reason:` — "
+          + "or `- None.`."
       ),
     ];
   }
@@ -528,8 +538,12 @@ function expectationProblems(content, tasks) {
   for (const entry of entries) {
     const [, id, body] = entry;
     const covered = body.match(/Covered by:\s*([0-9.,\s-]+)/i);
-    const hasDurableOwner =
-      /Durable owner:\s*(?:openspec\/changes\/|keel\/archive\/)/i.test(body);
+    const declaredOwner = body.match(/Durable owner:\s*(\S[^\n]*)/i);
+    const hasDurableOwner = Boolean(
+      declaredOwner
+      && (/^openspec\/changes\//i.test(declaredOwner[1].trim())
+        || SHARED_DURABLE_OWNER_FORMS.test(declaredOwner[1]))
+    );
     const discarded = /Discard(?:ed)? (?:reason|rationale):\s*\S/i.test(body);
     if (!covered && !hasDurableOwner && !discarded) {
       problems.push(

package/src/core/guard.js

@@ -35,6 +35,14 @@ function guardResult(subcommand, status, extra = {}) {
       "The guard manifest is a disposable enforcement pointer; OpenSpec and "
         + "Git remain the only durable authority and selection never derives "
         + "from it.",
+      // The status describes a file Keel wrote. Whether anything reads that
+      // file is a target-side fact: enforcement runs as a runtime hook the
+      // host loads, and a host that loaded different plugins keeps them for
+      // the life of its session. Reporting `started` as though it were a probe
+      // result is the same inference `--doctor` already refuses to make.
+      "This status describes the manifest only. Enforcement runs as a runtime "
+        + "hook in the host, which Keel cannot observe from the repository, so "
+        + "a written manifest is not evidence that any write was checked.",
     ],
     ...extra,
   };
@@ -239,7 +247,13 @@ function guardStatus(repo) {
         + "reauthorize through `keel gate task-start` and `keel guard start`.",
     });
   }
+  // Bytes under the guarded change's own directory are records the task
+  // produces — checkbox, Evidence, Review — not authority it must not touch.
+  // The fingerprint comparison above already covers every part of that file
+  // the capsule reads, so hashing it here only reported progress as drift.
+  const recordPrefix = `openspec/changes/${manifest.change}/`;
   for (const entry of manifest.authority) {
+    if (entry.path.replace(/\\/g, "/").startsWith(recordPrefix)) continue;
     const file = path.join(repo, entry.path);
     if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== entry.sha256) {
       problems.push({

package/src/core/task-contract.js

@@ -8,8 +8,17 @@ const SUPPORTED_MODES = new Set([
   "implementation",
   "diagnose-only",
   "plan-first",
+  // A task whose whole effect is an authorized repository-level action — the
+  // repository's first commit, a tag — writes no worktree file, so it has no
+  // concrete Touch to declare. It is not diagnose-only either: it has real side
+  // effects that need evidence. It is the one mode that may commit.
+  "repo-action",
 ]);
 
+// Modes whose contract is "no worktree writes", so `Touch: none` is required
+// rather than merely tolerated.
+const NO_WRITE_MODES = new Set(["diagnose-only", "repo-action"]);
+
 const UNFILLED_TOKEN = /(<[^>]+>|\bTODO\b|\bTBD\b|\bplaceholder\b)/i;
 
 function normalizeFieldText(value) {
@@ -241,16 +250,17 @@ function taskStartContractProblems(task) {
         code: "unsupported-mode",
         message:
           `Unsupported Mode \`${mode}\`; expected implementation, `
-          + "diagnose-only, or plan-first.",
+          + "diagnose-only, plan-first, or repo-action.",
       },
     ];
   }
-  if (mode === "diagnose-only") {
+  if (NO_WRITE_MODES.has(mode)) {
     if (touch.length !== 1 || touch[0].toLowerCase() !== "none") {
       return [
         {
           code: "invalid-touch",
-          message: "diagnose-only requires `Touch: none`.",
+          message: `${mode} writes no worktree file and requires `
+            + "`Touch: none`.",
         },
       ];
     }
@@ -819,13 +829,17 @@ function compileTaskContract(repo, change, task) {
     helperAuthority: "read-only-evidence-only",
     prohibitions: [
       "must not change Acceptance",
-      "must not commit",
+      // repo-action is the one mode whose authorized effect is the repository
+      // action itself, so it alone does not carry the commit prohibition.
+      // Whether the action it performed was the authorized one is a Review
+      // judgment; what the capsule fixes is the write posture.
+      ...(mode === "repo-action" ? [] : ["must not commit"]),
       "must not continue to another task",
       "must not mark tasks complete",
       "must not push",
       "must not sync or archive",
       "must not transfer Keel ownership",
-      ...(mode === "diagnose-only" ? ["must not write product files"] : []),
+      ...(NO_WRITE_MODES.has(mode) ? ["must not write product files"] : []),
     ],
   };
   if (resolved.diagnostics.length > 0) {