@christang/keel 5.60.0 → 5.62.0

package/README.md

@@ -132,7 +132,7 @@ because a permission granted in conversation does not survive a context reset. D
 `keel/config.yaml` instead:
 
 ```yaml
-authorize:          # accepted names: commit, push, release, archive, continuation
+authorize:          # accepted names: commit, push, release, archive, continuation, issue:<owner>/<repo>
   - commit
   - push
 ```
@@ -151,6 +151,16 @@ question — still stops. It authorizes no repository action and schedules nothi
 whose vocabulary predates the word, the entry is unrecognized and the whole declaration authorizes
 nothing until corrected — fail-closed, never a silent grant.
 
+`issue:<owner>/<repo>`, the sixth name, is the only one that names the resource it reaches, and
+it is refused without one. The other five act on the checkout the declaration sits in, so each is
+already bounded by the repository you declared it in. The credentials that open an issue are not:
+`gh` is account-wide, so a bare `issue` would reach every repository your account can touch —
+silently the widest entry in the file, and wider than `push`. Naming the repository keeps the
+grant the size of what it says. Keel carries that scope to `keel --doctor` and to the compiled
+capsule and **does not enforce it**: it invokes no tracker client and cannot observe one, exactly
+as it never commits on your behalf either. Closing an issue is not in scope and does not need to
+be — a pull request body carrying `Closes #<n>` does that when it lands.
+
 Three things the declaration is not:
 
 - **Not a way past a gate.** It authorizes the action, never the proof. `keel gate task-complete`
@@ -158,7 +168,7 @@ Three things the declaration is not:
   anything.
 - **Not a trigger.** It removes a confirmation, not the step that reaches the action. Nothing
   schedules itself, and no next task is selected for you.
-- **Not open-ended.** The five names above are the whole vocabulary. An unrecognized entry is
+- **Not open-ended.** The six names above are the whole vocabulary. An unrecognized entry is
   reported with the accepted names and the declaration authorizes nothing until you fix it — a
   typo never becomes a silent grant.
 

package/assets/bootstrap/AGENTS.md

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

@@ -1776,7 +1776,7 @@ function gitConfigHooksPath(repo) {
 
 function printStandingAuthorizationSurface(repo) {
   process.stdout.write("\nStanding authorization:\n");
-  const { declared, unknown, message } = readStandingAuthorization(repo);
+  const { declared, scopes, unknown, message } = readStandingAuthorization(repo);
   if (unknown.length > 0) {
     printDoctorLine("authorize", "failed", message);
     return false;
@@ -1789,9 +1789,32 @@ function printStandingAuthorizationSurface(repo) {
       : "undeclared; every action stays hard-stop"
   );
   for (const action of STANDING_AUTHORIZATION_ACTIONS) {
+    // Keyed on the action, never on the declared string. A scoped entry is
+    // `issue:acme/widgets` in the file, so a membership test against the bare
+    // name reports it `not authorized` on the same screen that has just listed
+    // it as declared — a diagnostic contradicting itself six lines apart.
+    if (!scopes.has(action)) {
+      printDoctorLine(action, "not authorized");
+      continue;
+    }
+    const scope = scopes.get(action);
     printDoctorLine(
       action,
-      declared.includes(action) ? "authorized" : "not authorized"
+      "authorized",
+      scope ? `scoped to ${scope}` : ""
+    );
+  }
+  // Said once, and only where it applies. Keel invokes no tracker client and
+  // observes none that an agent runs, so the scope is a declaration carried to
+  // the people who read it rather than a boundary anything holds. A reader who
+  // took it for a sandbox would be relying on nothing.
+  if ([...scopes.values()].some((scope) => scope !== null)) {
+    printDoctorLine(
+      "scope",
+      "carried",
+      "Keel records a scope and does not enforce it — it invokes no tracker "
+        + "client and cannot observe one, so the boundary is kept by whoever "
+        + "acts, not by this check"
     );
   }
   return true;

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.60.0",
+  "version": "5.62.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.60.0",
+  "version": "5.62.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

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import json
 import hashlib
 import os
@@ -37,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.60.0"
-PROTOCOL_VERSION = "5.60.0"
+PACKAGE_VERSION = "5.62.0"
+PROTOCOL_VERSION = "5.62.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
@@ -5521,36 +5522,46 @@ def validate_a_declared_dependency_is_resolved_scenario() -> int:
     """
     label = "a-declared-dependency-is-resolved"
 
-    # `no openspec on PATH`, and nothing else removed. Emptying PATH outright
-    # would also remove `node`, and the openspec shim needs it — the scenario
-    # would then be asserting that a shell without an interpreter fails.
-    without = dict(os.environ)
-    without["PATH"] = os.pathsep.join(
-        entry
-        for entry in os.environ.get("PATH", "").split(os.pathsep)
-        if entry and not (Path(entry) / "openspec").exists()
-    )
-    if shutil.which("openspec", path=without["PATH"]) is not None:
-        report(
-            f"{label}: could not build a PATH without openspec on it, so the "
-            "reproduction cannot be set up."
-        )
-        return 1
-    resolved = run_openspec(ROOT, "--version", env=without)
-    if resolved is None:
-        report(
-            f"{label}: with no `openspec` on PATH the runner resolved nothing, "
-            "but this package declares it as a dependency and installs it at "
-            "node_modules/.bin. A tool the repository ships is not a tool the "
-            "host has to provide."
-        )
-        return 1
-    if resolved.returncode != 0 or not re.search(r"\d+\.\d+\.\d+", resolved.stdout):
-        report(
-            f"{label}: the resolved openspec did not report a version. "
-            f"exit={resolved.returncode} out={(resolved.stdout or '').strip()!r}"
-        )
-        return 1
+    # `no openspec on PATH`, and nothing else removed — by file, not by
+    # directory. Removing the directory would also remove `node`, and the
+    # openspec shim needs it, so the scenario would be asserting that a shell
+    # without an interpreter fails (issue #137).
+    with path_without_openspec() as sanitized:
+        without = dict(os.environ)
+        without["PATH"] = sanitized
+        if shutil.which("openspec", path=without["PATH"]) is not None:
+            report(
+                f"{label}: could not build a PATH without openspec on it, so the "
+                "reproduction cannot be set up."
+            )
+            return 1
+        # The scenario's own precondition, asserted before the behavior. A shim
+        # with no interpreter exits 127, and calling that a fact about openspec
+        # sends the reader to a tool with nothing wrong with it.
+        if shutil.which("node", path=without["PATH"]) is None:
+            return skip_scenario(
+                label,
+                "node does not resolve on the PATH this scenario built, so the "
+                "openspec shim it resolves would have no interpreter. That is a "
+                "broken fixture, not a fact about openspec.",
+            )
+        resolved = run_openspec(ROOT, "--version", env=without)
+        if resolved is None:
+            report(
+                f"{label}: with no `openspec` on PATH the runner resolved "
+                "nothing, but this package declares it as a dependency and "
+                "installs it at node_modules/.bin. A tool the repository ships "
+                "is not a tool the host has to provide."
+            )
+            return 1
+        if resolved.returncode != 0 or not re.search(
+            r"\d+\.\d+\.\d+", resolved.stdout
+        ):
+            report(
+                f"{label}: the resolved openspec did not report a version. "
+                f"exit={resolved.returncode} out={(resolved.stdout or '').strip()!r}"
+            )
+            return 1
 
     # And it is the declared one, not whatever a host happens to carry.
     declared = ROOT / "node_modules" / ".bin" / "openspec"
@@ -14043,6 +14054,60 @@ OPENSPEC_SEARCH_ORDER = (
 )
 
 
+@contextlib.contextmanager
+def path_without_openspec(path: str | None = None):
+    """Yield `path` with every `openspec` executable on it removed, and nothing else.
+
+    Dropping a PATH *directory* because it holds an `openspec` also drops that
+    directory's other contents. On the ordinary Homebrew plus `npm install -g`
+    layout one directory holds both `openspec` and `node`, so the filter took the
+    interpreter the openspec shim needs and the scenario built on it asserted that
+    a shell without an interpreter fails — reported against `openspec`, which was
+    installed and working (issue #137).
+
+    So a directory that holds the tool is replaced in place, at the same index, by
+    a mirror symlinking every one of its entries except the `openspec` ones; a
+    directory that does not hold it is passed through untouched. Exclusion is by
+    stem, so `openspec.cmd` and its siblings cannot survive a filter whose whole
+    purpose is that the name does not resolve.
+
+    The mirrors live for the duration of the context, so callers must hold it open
+    across every child process they run against the PATH, not only across the call
+    that built it.
+    """
+    original = os.environ.get("PATH", "") if path is None else path
+    entries = [entry for entry in original.split(os.pathsep) if entry]
+    with tempfile.TemporaryDirectory(prefix="keel-no-openspec-") as raw:
+        mirrors = Path(raw)
+        rebuilt: list[str] = []
+        for index, entry in enumerate(entries):
+            source = Path(entry)
+            try:
+                contents = sorted(source.iterdir())
+            except OSError:
+                # Unreadable or absent: it carried nothing resolvable either way.
+                rebuilt.append(entry)
+                continue
+            if not any(item.stem == "openspec" for item in contents):
+                rebuilt.append(entry)
+                continue
+            mirror = mirrors / str(index)
+            try:
+                mirror.mkdir()
+                for item in contents:
+                    if item.stem == "openspec":
+                        continue
+                    (mirror / item.name).symlink_to(item)
+            except OSError:
+                # Windows can refuse a symlink without the privilege. Fall back to
+                # dropping the directory, which is what this replaces; the caller's
+                # precondition check then reports the consequence by name instead
+                # of attributing it to the tool.
+                continue
+            rebuilt.append(str(mirror))
+        yield os.pathsep.join(rebuilt)
+
+
 def resolve_openspec(env: dict[str, str] | None = None) -> str | None:
     local = ROOT / "node_modules" / ".bin" / "openspec"
     if local.is_file():
@@ -19743,19 +19808,20 @@ def validate_continuation_docs_scenario() -> int:
 
     readme = (ROOT / "README.md").read_text(encoding="utf-8")
     for needle in (
-        "accepted names: commit, push, release, archive, continuation",
+        "accepted names: commit, push, release, archive, continuation, "
+        "issue:<owner>/<repo>",
         "next unchecked task of the same change",
         "the stop that re-asks for an approval already given",
-        "The five names above are the whole vocabulary.",
+        "The six names above are the whole vocabulary.",
     ):
         if needle not in readme:
             report(f"{label}: README.md lacks: {needle}")
             return 1
 
     config_text = (ROOT / "keel/config.yaml").read_text(encoding="utf-8")
-    if "commit, push, release, archive,\n# continuation" not in config_text:
+    if "commit, push, release, archive,\n# continuation, issue:<owner>/<repo>" not in config_text:
         report(
-            f"{label}: keel/config.yaml's comment does not name the five-name "
+            f"{label}: keel/config.yaml's comment does not name the six-name "
             "vocabulary."
         )
         return 1
@@ -24659,14 +24725,13 @@ def validate_dependency_resolves_where_npm_put_it_scenario() -> int:
         shutil.copy2(ROOT / "package.json", package_root / "package.json")
 
     # PATH without any openspec, so what resolves came from the layout and not
-    # from the machine running the suite.
+    # from the machine running the suite. Removed by file rather than by
+    # directory: one directory holds `openspec` and `node` on the ordinary
+    # Homebrew plus `npm install -g` layout, and the children below are run by
+    # `node` (issue #137).
     def clean_env(extra_path: Path | None = None) -> dict[str, str]:
         env = dict(os.environ)
-        entries = [
-            entry
-            for entry in env.get("PATH", "").split(os.pathsep)
-            if entry and not (Path(entry) / "openspec").exists()
-        ]
+        entries = [entry for entry in sanitized_path.split(os.pathsep) if entry]
         if extra_path is not None:
             entries.insert(0, str(extra_path))
         env["PATH"] = os.pathsep.join(entries)
@@ -24696,7 +24761,21 @@ def validate_dependency_resolves_where_npm_put_it_scenario() -> int:
             "",
         )
 
-    with tempfile.TemporaryDirectory(prefix="keel-hoisted-") as raw:
+    # The mirrors live for the duration of the context, so it stays open across
+    # every child process below rather than only across the call that built it.
+    with path_without_openspec() as sanitized_path, tempfile.TemporaryDirectory(
+        prefix="keel-hoisted-"
+    ) as raw:
+        # The scenario's own precondition, asserted before the behavior: every
+        # assertion below runs `node`, so a PATH without one is a broken fixture
+        # and not a fact about where the dependency resolves.
+        if shutil.which("node", path=sanitized_path) is None:
+            return skip_scenario(
+                label,
+                "node does not resolve on the PATH this scenario built, and "
+                "every assertion below runs the installed Keel through it. That "
+                "is a broken fixture, not a fact about openspec.",
+            )
         root = Path(raw)
 
         # The layout npm actually produces: Keel unpacked under the consumer's
@@ -27445,6 +27524,266 @@ def validate_authored_scenario_names_scenario() -> int:
     return 0
 
 
+def validate_a_filter_drops_only_what_it_named_scenario() -> int:
+    """Issue #137: a PATH built to exclude one tool removed a whole directory.
+
+    Both scenarios that need "no openspec on PATH" dropped every directory that
+    held an `openspec`. On the ordinary Homebrew plus `npm install -g` layout one
+    directory holds `openspec` and `node`, so the filter took the interpreter the
+    openspec shim needs, and the diagnostic named `openspec` — a tool that was
+    installed and working.
+
+    The defect is a layout, so the fixture builds the layout instead of relying on
+    this host having it: a directory carrying both binaries, on a PATH between two
+    that carry neither. Asserted from both sides — that the runtime survived is the
+    regression guard, that the tool is gone is the positive control, because a
+    mirror that produced an empty directory would satisfy the second alone.
+    """
+    label = "a-filter-drops-only-what-it-named"
+
+    def write_executable(path: Path, body: str) -> None:
+        path.write_text(body, encoding="utf-8")
+        path.chmod(0o755)
+
+    with tempfile.TemporaryDirectory(prefix="keel-shared-bin-") as raw:
+        root = Path(raw)
+        before = root / "before"
+        shared = root / "shared"
+        after = root / "after"
+        for directory in (before, shared, after):
+            directory.mkdir()
+        write_executable(before / "tool-a", "#!/bin/sh\necho a\n")
+        write_executable(after / "tool-b", "#!/bin/sh\necho b\n")
+        # The layout under test: the interpreter and the tool in one directory,
+        # plus a neighbour that belongs to neither and must survive with it.
+        write_executable(shared / "node", "#!/bin/sh\necho node\n")
+        write_executable(shared / "openspec", "#!/bin/sh\necho 1.12.0\n")
+        write_executable(shared / "openspec.cmd", "#!/bin/sh\necho 1.12.0\n")
+        write_executable(shared / "unrelated", "#!/bin/sh\necho unrelated\n")
+
+        source = os.pathsep.join(str(entry) for entry in (before, shared, after))
+        with path_without_openspec(source) as sanitized:
+            entries = sanitized.split(os.pathsep)
+
+            # Behavior before shape: what the defect destroys is the ability to
+            # run the interpreter, and an entry count is only its symptom.
+            node = shutil.which("node", path=sanitized)
+            if node is None:
+                report(
+                    f"{label}: node did not survive a filter that was removing "
+                    f"openspec. The interpreter shares a directory with the "
+                    f"tool, and the whole directory went. sanitized PATH "
+                    f"{sanitized!r}"
+                )
+                return 1
+            if shutil.which("unrelated", path=sanitized) is None:
+                report(
+                    f"{label}: an executable unrelated to openspec was removed "
+                    f"along with it."
+                )
+                return 1
+
+            # The positive control. Without it, an empty mirror passes.
+            for name in ("openspec", "openspec.cmd"):
+                found = shutil.which(name, path=sanitized)
+                if found is not None:
+                    report(
+                        f"{label}: {name} still resolves on a PATH built to "
+                        f"exclude it, at {found!r}."
+                    )
+                    return 1
+
+            if len(entries) != 3:
+                report(
+                    f"{label}: the sanitized PATH has {len(entries)} entries, "
+                    f"not the 3 it was given, so search order did not survive. "
+                    f"got {sanitized!r}"
+                )
+                return 1
+            if Path(node).parent != Path(entries[1]):
+                report(
+                    f"{label}: node survived but moved search position; it "
+                    f"resolved from {str(Path(node).parent)!r}, not from PATH "
+                    f"entry 1 {entries[1]!r}."
+                )
+                return 1
+
+            # M2: an entry that does not hold the tool is passed through, not
+            # mirrored — the cost and the blast radius stay on the directories
+            # that carry it.
+            for index, original in ((0, before), (2, after)):
+                if entries[index] != str(original):
+                    report(
+                        f"{label}: a PATH entry holding no openspec was "
+                        f"rewritten; expected {str(original)!r}, got "
+                        f"{entries[index]!r}."
+                    )
+                    return 1
+
+    if label not in {name for name, _ in SCENARIOS}:
+        report(f"{label}: the scenario registry does not include it.")
+        return 1
+    report(f"{label} scenario passed.")
+    return 0
+
+
+def validate_an_authorization_names_its_repository_scenario() -> int:
+    """Issue #136: the vocabulary had no name for a tracker write.
+
+    `change-close` routes an unresolved follow-up to a durable owner and accepts
+    an absolute https reference, which in practice is a tracker issue — while the
+    standing-authorization vocabulary had no way to say the agent may create one.
+    The entry added for it is the first whose credential reaches further than the
+    checkout the declaration sits in: `gh` is account-wide, so a bare `issue`
+    would be the widest entry in a file whose other entries the checkout bounds.
+    It therefore names the repository it reaches, and the bare form is refused.
+    """
+    label = "an-authorization-names-its-repository"
+
+    with tempfile.TemporaryDirectory(prefix="keel-issue-scope-") as raw:
+        root = Path(raw)
+
+        def fixture(name: str, body: str) -> Path:
+            repo = root / name
+            repo.mkdir()
+            write_authorize_config(repo, body)
+            return repo
+
+        # M1 — the scoped form is accepted, beside an ordinary entry so the
+        # assertion is about this entry and not about the block parsing at all.
+        scoped = fixture(
+            "scoped", "authorize:\n  - commit\n  - issue:acme/widgets\n"
+        )
+        out = run_keel(scoped, "--doctor").stdout
+        if "authorize: ok" not in out or "issue:acme/widgets" not in out:
+            report(
+                f"{label}: a scoped tracker entry was refused. `gh` is "
+                "account-wide, so this is the one entry that has to name its "
+                "repository, and it is the one the vocabulary rejects."
+            )
+            report(out)
+            return 1
+        if "commit: authorized" not in out:
+            report(
+                f"{label}: the entry beside the scoped one lost its "
+                "authorization, so the scoped entry voided the declaration "
+                "rather than joining it."
+            )
+            report(out)
+            return 1
+
+        # The per-action line, which is the half a reader looks at. Without it
+        # the same screen lists the entry as declared and reports the action as
+        # unauthorized.
+        if "issue: authorized" not in out or "acme/widgets" not in out.split(
+            "issue: authorized", 1
+        )[-1].split("\n", 1)[0]:
+            report(
+                f"{label}: the per-action line does not report the scoped entry "
+                "as authorized and name its scope."
+            )
+            report(out)
+            return 1
+        if "issue: not authorized" in out:
+            report(
+                f"{label}: the doctor lists the entry as declared and reports "
+                "`issue: not authorized` on the same screen, so the diagnostic "
+                "contradicts itself."
+            )
+            report(out)
+            return 1
+        # D2 is unfixable by mechanism, so it is owed to wording: a reader must
+        # not take the scope for a sandbox.
+        if "does not enforce" not in out:
+            report(
+                f"{label}: the output does not say Keel carries the scope "
+                "without enforcing it, so a reader can take it for a fence."
+            )
+            report(out)
+            return 1
+
+        # M2 — the bare form is refused, and the refusal carries the form it
+        # needs. The refusal alone is not the assertion: a bare `issue` was
+        # already refused before this existed, by not being a name at all.
+        bare = fixture("bare", "authorize:\n  - commit\n  - issue\n")
+        out = run_keel(bare, "--doctor").stdout
+        if "authorize: failed" not in out:
+            report(f"{label}: a bare tracker entry was granted.")
+            report(out)
+            return 1
+        if "issue:<owner>/<repo>" not in out:
+            report(
+                f"{label}: the bare-entry refusal does not name the form it "
+                "requires, so a reader is told `issue` is not a name rather "
+                "than that it is a name needing a scope."
+            )
+            report(out)
+            return 1
+
+        # M3 — the shape is checked, on both sides of correct.
+        for name, body in (
+            ("short", "authorize:\n  - issue:acme\n"),
+            ("long", "authorize:\n  - issue:acme/widgets/extra\n"),
+            ("empty-owner", "authorize:\n  - issue:/widgets\n"),
+            ("empty-repo", "authorize:\n  - issue:acme/\n"),
+        ):
+            repo = fixture(name, body)
+            out = run_keel(repo, "--doctor").stdout
+            if "authorize: failed" not in out:
+                report(
+                    f"{label}: a malformed scope ({name}) was accepted; a shape "
+                    "check that passes everything checks nothing."
+                )
+                report(out)
+                return 1
+            declared_entry = body.strip().splitlines()[-1].strip("- ")
+            if declared_entry not in out:
+                report(
+                    f"{label}: the refusal for {name} does not name the "
+                    f"offending entry {declared_entry!r}."
+                )
+                report(out)
+                return 1
+
+        # M3 — and fail-closed is unchanged by the new form: a valid scoped
+        # entry beside an unrecognized one authorizes nothing.
+        mixed = fixture(
+            "mixed", "authorize:\n  - issue:acme/widgets\n  - deploy\n"
+        )
+        out = run_keel(mixed, "--doctor").stdout
+        if "authorize: failed" not in out or "deploy" not in out:
+            report(f"{label}: an unrecognized entry beside a scoped one did not fail closed.")
+            report(out)
+            return 1
+        if "issue: authorized" in out:
+            report(
+                f"{label}: the scoped entry stayed authorized beside an "
+                "unrecognized one, so the declaration did not fail closed."
+            )
+            report(out)
+            return 1
+
+
+        # M3 — the new rendering did not turn an undeclared action into a
+        # declared one.
+        only_commit = fixture("only-commit", "authorize:\n  - commit\n")
+        out = run_keel(only_commit, "--doctor").stdout
+        for action in ("push", "release", "archive", "continuation", "issue"):
+            if f"{action}: not authorized" not in out:
+                report(
+                    f"{label}: {action} is not reported as unauthorized in a "
+                    "repository that declared only commit."
+                )
+                report(out)
+                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
+
+
 SCENARIOS: tuple = (
     ("stateless-continuity", validate_stateless_continuity_scenario),
     ("core-gates", validate_core_gates_scenario),
@@ -27787,6 +28126,14 @@ SCENARIOS: tuple = (
         "change-verify-deferred-evidence",
         validate_change_verify_deferred_evidence_scenario,
     ),
+    (
+        "a-filter-drops-only-what-it-named",
+        validate_a_filter_drops_only_what_it_named_scenario,
+    ),
+    (
+        "an-authorization-names-its-repository",
+        validate_an_authorization_names_its_repository_scenario,
+    ),
 )
 
 

package/src/core/config.js

@@ -13,8 +13,53 @@ const STANDING_AUTHORIZATION_ACTIONS = [
   "release",
   "archive",
   "continuation",
+  "issue",
 ];
 
+// The actions whose credential reaches further than the checkout the
+// declaration sits in. Every other name here acts on this repository, so the
+// declaration and the thing it permits are the same size; `gh` is account-wide,
+// so a bare `issue` would silently be the widest entry in the file. Those
+// actions are declared with the resource they may reach and refused bare —
+// accepting the bare form as a convenience would make the narrow form optional
+// and the wide one the default, which is the decision inverted.
+const SCOPED_AUTHORIZATION_ACTIONS = new Set(["issue"]);
+
+// `<owner>/<repo>`: two non-empty segments and nothing else. The shape is
+// checked and the existence is not, for the reason `triage` never fetches an
+// issue — a check that reaches the network trades the local, offline,
+// deterministic evaluation its verdict rests on.
+const AUTHORIZATION_SCOPE_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+// How the accepted names are spelled back to an author: the scoped ones carry
+// their form, so the list is copyable rather than a name the next message
+// refuses.
+const STANDING_AUTHORIZATION_ACCEPTED_FORMS = STANDING_AUTHORIZATION_ACTIONS.map(
+  (action) =>
+    SCOPED_AUTHORIZATION_ACTIONS.has(action) ? `${action}:<owner>/<repo>` : action
+);
+
+// One declared entry, split into the action and the resource it names. Returns
+// the action and scope when the entry is usable, and otherwise why it is not,
+// so the caller can say which of the three mistakes an author made.
+function classifyAuthorizationEntry(entry) {
+  const separator = entry.indexOf(":");
+  const action = separator === -1 ? entry : entry.slice(0, separator);
+  const scope = separator === -1 ? null : entry.slice(separator + 1);
+  if (!STANDING_AUTHORIZATION_ACTIONS.includes(action)) {
+    return { ok: false, entry, reason: "unknown-action" };
+  }
+  if (!SCOPED_AUTHORIZATION_ACTIONS.has(action)) {
+    if (scope !== null) return { ok: false, entry, action, reason: "unexpected-scope" };
+    return { ok: true, entry, action, scope: null };
+  }
+  if (scope === null) return { ok: false, entry, action, reason: "missing-scope" };
+  if (!AUTHORIZATION_SCOPE_PATTERN.test(scope)) {
+    return { ok: false, entry, action, reason: "malformed-scope" };
+  }
+  return { ok: true, entry, action, scope };
+}
+
 // The closed vocabulary of capability tiers a repository may declare for a
 // delegated task. The names describe the capability the work requires, never
 // the size of the work: a tier named for size would authorize the agent's guess
@@ -162,24 +207,64 @@ function readTriagePolicy(repo) {
 // both — but only `archive` is a name this vocabulary accepts (#93). Naming
 // that confusion only when `sync` is the entry present keeps every other
 // unrecognized name (a genuine typo) unchanged.
-function standingAuthorizationUnknownMessage(unknown) {
+function standingAuthorizationUnknownMessage(unknown, problems = []) {
   const base = `keel/config.yaml declares unrecognized ${
     unknown.length === 1 ? "action" : "actions"
   }: ${unknown.join(", ")}; accepted names are `
-    + `${STANDING_AUTHORIZATION_ACTIONS.join(", ")}. The whole declaration `
+    + `${STANDING_AUTHORIZATION_ACCEPTED_FORMS.join(", ")}. The whole declaration `
     + "authorizes nothing until it is corrected.";
-  if (!unknown.includes("sync")) return base;
-  return `${base} \`sync\` is a value of \`change-close --action\`, not a `
-    + "name `authorize:` accepts; declare `archive` if you mean to authorize "
-    + "the gate that runs it.";
+  const notes = [];
+  if (unknown.includes("sync")) {
+    notes.push(
+      "`sync` is a value of `change-close --action`, not a name `authorize:` "
+        + "accepts; declare `archive` if you mean to authorize the gate that "
+        + "runs it."
+    );
+  }
+  // A scoped action refused for its scope is not a typo, and saying "accepted
+  // names are ... issue" beside "unrecognized action: issue" would contradict
+  // itself. Name what is missing instead, and why this one name carries it.
+  for (const problem of problems) {
+    if (problem.reason === "missing-scope") {
+      notes.push(
+        `\`${problem.action}\` names no repository; write it as `
+          + `\`${problem.action}:<owner>/<repo>\`. The credentials that open an `
+          + "issue are account-wide, so an unscoped grant would reach every "
+          + "repository the account can touch — wider than commit or push, "
+          + "which this checkout bounds."
+      );
+    } else if (problem.reason === "malformed-scope") {
+      notes.push(
+        `\`${problem.entry}\` does not name a repository as `
+          + `\`<owner>/<repo>\` — two non-empty segments and nothing else.`
+      );
+    } else if (problem.reason === "unexpected-scope") {
+      notes.push(
+        `\`${problem.action}\` takes no scope; it acts on this checkout, which `
+          + "already bounds it."
+      );
+    }
+  }
+  return notes.length === 0 ? base : `${base} ${notes.join(" ")}`;
 }
 
 function readStandingAuthorization(repo) {
   const declared = [];
   const unknown = [];
+  const problems = [];
+  // Action -> the resource it names, or null for an action the checkout bounds.
+  // Additive: `declared` stays the entries as written, so the capsule's
+  // inherited autonomy line reads back what the file says.
+  const scopes = new Map();
   for (const entry of configList(repo, "authorize")) {
-    if (STANDING_AUTHORIZATION_ACTIONS.includes(entry)) declared.push(entry);
-    else unknown.push(entry);
+    const classified = classifyAuthorizationEntry(entry);
+    if (classified.ok) {
+      declared.push(entry);
+      scopes.set(classified.action, classified.scope);
+      continue;
+    }
+    unknown.push(entry);
+    if (classified.reason !== "unknown-action") problems.push(classified);
   }
   // Fail closed. A declaration Keel cannot fully read authorizes nothing,
   // because the alternative is granting the entries beside a typo while the
@@ -187,11 +272,12 @@ function readStandingAuthorization(repo) {
   if (unknown.length > 0) {
     return {
       declared: [],
+      scopes: new Map(),
       unknown,
-      message: standingAuthorizationUnknownMessage(unknown),
+      message: standingAuthorizationUnknownMessage(unknown, problems),
     };
   }
-  return { declared, unknown, message: null };
+  return { declared, scopes, unknown, message: null };
 }
 
 // A nested block of `name: value` entries under one top-level key. Delegation
@@ -389,6 +475,7 @@ module.exports = {
   CONFIG_RELATIVE_PATH,
   DELEGATION_TIERS,
   STANDING_AUTHORIZATION_ACTIONS,
+  SCOPED_AUTHORIZATION_ACTIONS,
   readDelegationPolicy,
   readPrecedentStore,
   readStandingAuthorization,