@christang/keel 5.2.3 → 5.2.4

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.2.3 -->
+<!-- keel:start version=5.2.4 -->
 ## 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

@@ -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.2.4",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.2.3",
+  "version": "5.2.4",
   "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.2.4",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

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.2.4"
+PROTOCOL_VERSION = "5.2.4"
 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)
@@ -10999,6 +11403,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),

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,
   };