@christang/keel 5.61.0 → 5.63.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.
 
@@ -263,7 +273,27 @@ designed to — resist widening the policy until it stops happening.
 Use **Full mode** (the OpenSpec flow above) for new features, interface or protocol changes,
 cross-module work, or anything over ~3 files / 100 lines. Use **Lite mode** for local fixes,
 small scripts, docs, or tests with no interface change and locally provable impact; Lite does
-not write OpenSpec state.
+not write OpenSpec state. The rule is in the block `keel --init` installs, because routing is
+the first decision of a session and a rule reachable only from this README is reachable only by
+an agent that already went looking.
+
+The size bar is a proxy for risk, not risk itself, and some repositories invert it: an
+append-only record whose schema change is a one-field diff can be the highest-risk change in the
+project, and a mechanical rename across twenty files the lowest. Declare the paths the heuristic
+gets wrong, each with the reason it is wrong:
+
+```yaml
+full_mode_paths:
+  - results/experiments.jsonl: append-only; a one-field diff is not revertible
+```
+
+`keel context` reports what is declared, so the exception arrives at the decision, and
+`keel --doctor` reports the declaration's health. There is deliberately **no key for the
+opposite direction**: every declaration in that file removes a confirmation and never a gate, and
+an entry that held work *out* of the flow would be the first to break that. Keel gates no routing
+decision either — routing decides whether a change exists, so there is nothing for a gate to bind
+to; what Keel does is make sure the rule and your exceptions are in front of the agent when it
+decides.
 
 ## How the agent uses these
 
@@ -273,8 +303,9 @@ command at the right moment. Three things make that happen.
 
 - **The protocol.** `keel --init` writes a bootstrap block into your repo's `AGENTS.md`
   (imported by `CLAUDE.md` on Claude). It states the rules the agent follows: open every
-  session with `keel context`, pass the gates at task boundaries, and stay inside the task's
-  declared write scope. That is how the agent knows *when* to run what.
+  session with `keel context`, route the work Full or Lite, pass the gates at task boundaries,
+  and stay inside the task's declared write scope. That is how the agent knows *when* to run
+  what.
 - **The skills.** The `keel-*` execution skills and the `/opsx:*` command overlays walk the
   agent through align → apply → review → complete, invoking the gates at each step.
 - **The hooks.** A SessionStart hook runs the continuity projection the moment a session

package/assets/bootstrap/AGENTS.md

@@ -1,9 +1,10 @@
-<!-- keel:start version=5.61.0 -->
+<!-- keel:start version=5.63.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.
 - Obey the selected task capsule: `keel gate task-start` before implementing, `--record` its fingerprint to Evidence `Contract`, which `task-complete` requires, before checking complete. Touch bounds product writes; the change's own dir is exempt. On Claude a passing `task-start` guards it by default (`--no-guard` opts out).
 - One current agent owns writes; helpers return read-only report/evidence only. No commit, sync, or archive without explicit authorization.
+- Route Full (the OpenSpec flow) for new features, interface or protocol changes, cross-module work, or over ~3 files / 100 lines; Lite for local fixes with no interface change. No gate checks routing; a project corrects the size bar with `full_mode_paths:` in `keel/config.yaml`, which `keel context` reports.
 - Native plugin projections (SessionStart context) are disposable views, never authority; without the plugin or hook, run the commands manually.
 - Keel skills and hooks come from the `keel` native plugin (`codex plugin add` / `claude plugin install`); `keel --init` owns only the OpenSpec schema, overlays, and this bootstrap.
 <!-- keel:end -->

package/bin/keel.js

@@ -48,6 +48,8 @@ const {
   STANDING_AUTHORIZATION_ACTIONS,
   readPrecedentStore,
   readStandingAuthorization,
+  readFullModePaths,
+  fullModePathsUnreadableMessage,
   readTriagePolicy,
   triageIssue,
 } = require("../src/core/config");
@@ -1728,6 +1730,7 @@ function runDoctor(options) {
   const authorizationOk = printStandingAuthorizationSurface(repo);
   printPrecedentSurface(repo);
   printTriageSurface(repo);
+  printRoutingSurface(repo);
   printFastPrePushSurface(repo);
   printSourceRepoCliResolution(repo);
 
@@ -1776,7 +1779,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,14 +1792,69 @@ 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;
 }
 
+function printRoutingSurface(repo) {
+  process.stdout.write("\nFull/Lite routing:\n");
+  const { paths, unreadable } = readFullModePaths(repo);
+  if (unreadable.length > 0) {
+    // Same verdict the projection reaches, from the same read: a diagnostic
+    // that reported health while `keel context` reported the conservative
+    // state would leave a reader to pick which one to believe.
+    printDoctorLine(
+      "full_mode_paths",
+      "failed",
+      `${fullModePathsUnreadableMessage(unreadable)} Every change routes Full `
+        + "until it is corrected."
+    );
+    return;
+  }
+  if (paths.length === 0) {
+    printDoctorLine(
+      "full_mode_paths",
+      "none",
+      "undeclared; routing follows the size heuristic alone"
+    );
+    return;
+  }
+  printDoctorLine(
+    "full_mode_paths",
+    "ok",
+    `declared in keel/config.yaml: ${paths.length} `
+      + `${paths.length === 1 ? "path always routes" : "paths always route"} Full`
+  );
+  for (const entry of paths) printDoctorLine(entry.path, "Full", entry.reason);
+}
+
 function printTriageSurface(repo) {
   process.stdout.write("\nUnattended triage:\n");
   const { labels, issues, unreadable } = readTriagePolicy(repo);

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.61.0",
+  "version": "5.63.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.61.0",
+  "version": "5.63.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

@@ -38,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.61.0"
-PROTOCOL_VERSION = "5.61.0"
+PACKAGE_VERSION = "5.63.0"
+PROTOCOL_VERSION = "5.63.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
@@ -90,6 +90,28 @@ MANAGED_END = "<!-- keel:end -->"
 TEMPLATE_CHECKSUM_PREFIX = "<!-- keel:content-sha256 "
 TEMPLATE_CHECKSUM_SUFFIX = " -->"
 
+# The installed bootstrap block's byte budget, asserted by `thin-native-install`
+# and `delegation-resident-text`. Raised from 1024 to 1400 in 5.63.0 to carry the
+# Full/Lite routing rule (#131), deliberately and in a diff.
+#
+# The reason has to live here, because the cap's purpose is that the budget is
+# **not quietly spent later** — the adjective is the whole specification. A cap
+# phrased that way is not a claim that the number is right forever; it is a claim
+# that nobody moves it without a reader noticing. So a documented raise satisfies
+# it and a bare larger constant does not.
+#
+# Why routing earned it, when delegation did not: delegation is inert until a
+# project declares it, so a repository declaring nothing was already served by the
+# sentence in the block. Routing is never inert — every session routes, declared
+# or not — and it was the one durable rule with no gate, no command, and no
+# declaration carrying it to the agent. The rejected alternative was compressing
+# the existing bullets to fit under 1024, which would have gone green while paying
+# for routing out of gate-discipline prose that was already earning its place.
+#
+# 1400 rather than a round 1536: the headroom is "current content plus one short
+# clause", so the next addition has to argue for itself the way this one did.
+BOOTSTRAP_BLOCK_BYTE_BUDGET = 1400
+
 RESIDENT_BLOCKS = [
     {
         "name": "Bootstrap resident block",
@@ -110,6 +132,11 @@ RESIDENT_BLOCKS = [
             "read-only report/evidence",
             "native plugin",
             "keel --init",
+            # Routing is the one durable rule with no gate behind it, so the
+            # block is the only place it reaches a consuming repository (#131).
+            # Matched as a topic: both modes named in one statement.
+            re.compile(r"\bFull\b[^\n]*\bLite\b", re.IGNORECASE),
+            "full_mode_paths",
         ],
     },
 ]
@@ -18065,11 +18092,13 @@ def validate_delegation_resident_text_scenario() -> int:
             return 1
 
     # M1 — the consumer bootstrap deliberately does NOT carry the delegation
-    # clause. Its block has a sub-1KB budget with 11 bytes of headroom, and
-    # delegation is inert until declared, so an installing repository that
-    # declares nothing is fully served by the sentence already there. What the
-    # check enforces is that the sentence stays true by default, and that the
-    # budget is not quietly spent later.
+    # clause. Its block has a byte budget (BOOTSTRAP_BLOCK_BYTE_BUDGET) with
+    # little headroom, and delegation is inert until declared, so an installing
+    # repository that declares nothing is fully served by the sentence already
+    # there. What the check enforces is that the sentence stays true by default,
+    # and that the budget is not quietly spent later — the budget moved once, in
+    # 5.63.0 for the routing rule (#131), with the argument recorded at the
+    # constant; a raise with no reason beside it is the drift this guards.
     bootstrap = ROOT / "assets/bootstrap/AGENTS.md"
     boot = flat(bootstrap)
     if re.sub(r"\s+", " ", "One current agent owns writes") not in boot:
@@ -18078,18 +18107,21 @@ def validate_delegation_resident_text_scenario() -> int:
     block = bootstrap.read_text(encoding="utf-8")
     body = block.split("<!-- keel:start", 1)[1].split("<!-- keel:end -->", 1)[0]
     size = len(("<!-- keel:start" + body + "<!-- keel:end -->").encode())
-    if size >= 1024:
-        report(f"delegation-resident-text: the bootstrap block is {size} bytes, over its 1KB budget.")
+    if size >= BOOTSTRAP_BLOCK_BYTE_BUDGET:
+        report(
+            f"delegation-resident-text: the bootstrap block is {size} bytes, "
+            f"over its {BOOTSTRAP_BLOCK_BYTE_BUDGET}-byte budget."
+        )
         return 1
 
     # M1 — the config header counts its declarations correctly.
     config = ROOT / "keel/config.yaml"
     cfg = flat(config)
-    if re.sub(r"\s+", " ", "Four independent declarations") in cfg:
-        report("delegation-resident-text: the config header still says four declarations.")
+    if re.sub(r"\s+", " ", "Five independent declarations") in cfg:
+        report("delegation-resident-text: the config header still says five declarations.")
         return 1
-    if re.sub(r"\s+", " ", "Five independent declarations") not in cfg:
-        report("delegation-resident-text: the config header does not name five declarations.")
+    if re.sub(r"\s+", " ", "Six independent declarations") not in cfg:
+        report("delegation-resident-text: the config header does not name six declarations.")
         return 1
     if "delegation" not in cfg:
         report("delegation-resident-text: the config header does not document delegation.")
@@ -19808,19 +19840,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
@@ -21096,10 +21129,10 @@ def validate_thin_native_install_scenario() -> int:
             return 1
         block = extract_managed_block(agents_text)
         block_bytes = len(block.encode("utf-8"))
-        if block_bytes >= 1024:
+        if block_bytes >= BOOTSTRAP_BLOCK_BYTE_BUDGET:
             report(
-                "thin-native-install bootstrap block is not sub-1KB: "
-                f"{block_bytes} bytes"
+                "thin-native-install bootstrap block is over its "
+                f"{BOOTSTRAP_BLOCK_BYTE_BUDGET}-byte budget: {block_bytes} bytes"
             )
             return 1
 
@@ -27626,6 +27659,408 @@ def validate_a_filter_drops_only_what_it_named_scenario() -> int:
     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
+
+
+def validate_the_routing_rule_reaches_the_decision_scenario() -> int:
+    """Issue #131: routing is the one durable rule with nowhere to reach the agent.
+
+    The block `keel --init` installs is five bullets and says nothing about Full
+    or Lite; routing has no implementation at all, only four lines of prose in
+    Keel's own README. So the first decision of every session is taken without
+    the rule, and a project whose risk does not track diff size has no way to say
+    so. The declaration is one-directional on purpose: it can raise the process
+    floor and there is no key that lowers it.
+    """
+    label = "the-routing-rule-reaches-the-decision"
+    declared = "results/experiments.jsonl"
+    reason = "append-only; a one-field diff is not revertible"
+
+    with tempfile.TemporaryDirectory(prefix="keel-routing-") as raw:
+        root = Path(raw)
+
+        def fixture(name: str, body: str | None) -> Path:
+            repo = root / name
+            repo.mkdir()
+            if body is not None:
+                (repo / "keel").mkdir()
+                (repo / "keel" / "config.yaml").write_text(body, encoding="utf-8")
+            return repo
+
+        def context(repo: Path) -> str:
+            return run_keel(repo, "context").stdout
+
+        # M1 — a declared path is reported with the reason it carries, and the
+        # projection is otherwise the one it would have printed anyway.
+        plain = fixture("plain", "fast_check: echo plain\n")
+        declaring = fixture(
+            "declaring",
+            f"fast_check: echo plain\nfull_mode_paths:\n  - {declared}: {reason}\n",
+        )
+        out = context(declaring)
+        if declared not in out:
+            report(
+                f"{label}: no routing line — a repository that declared "
+                f"{declared!r} is told nothing about it at the one moment the "
+                "routing decision is made."
+            )
+            report(out)
+            return 1
+        if reason not in out:
+            report(
+                f"{label}: the declared path is reported without its reason, so "
+                "the agent learns the file is special and not what makes it so."
+            )
+            report(out)
+            return 1
+        # D5 — the fixture creates no file at that path, on purpose.
+        if (declaring / declared).exists():
+            report(f"{label}: the fixture created the declared path; D5 is untested.")
+            return 1
+        baseline = [
+            line
+            for line in context(plain).splitlines()
+            if line.startswith(("Keel context:", "Next action:"))
+        ]
+        moved = [
+            line
+            for line in out.splitlines()
+            if line.startswith(("Keel context:", "Next action:"))
+        ]
+        if baseline != moved:
+            report(
+                f"{label}: the declaration moved the projection's status or next "
+                f"action; {baseline!r} became {moved!r}."
+            )
+            return 1
+
+        # M2 — an entry with no reason is not a declaration.
+        bare = fixture(
+            "bare", f"full_mode_paths:\n  - {declared}\n"
+        )
+        out = context(bare)
+        # Behavior before message: what D2 forbids is the entry counting as a
+        # declaration, and whether it is also reported well comes after that.
+        routing_lines = [
+            line for line in out.splitlines() if line.startswith("Routing:")
+        ]
+        if any(declared in line for line in routing_lines):
+            report(
+                f"{label}: the reason-less entry was read as a declaration; "
+                f"{routing_lines!r}"
+            )
+            return 1
+        if "full_mode_paths" not in out or declared not in out:
+            report(
+                f"{label}: an entry with no reason was dropped silently; the "
+                "author is left believing they declared what they typed."
+            )
+            report(out)
+            return 1
+        if "<path>: <reason>" not in out:
+            report(
+                f"{label}: the refusal does not name the form the entry needs."
+            )
+            report(out)
+            return 1
+
+        # 1.2 — a declaration Keel cannot fully read raises the floor rather
+        # than dropping it. `authorize:` and `triage:` fail closed and closed
+        # means *less proceeds without a human*; for a declaration whose purpose
+        # is to add process, the same principle is more Full mode, not less.
+        mixed = fixture(
+            "mixed",
+            f"full_mode_paths:\n  - {declared}: {reason}\n  - src/lib.js\n",
+        )
+        out = context(mixed)
+        routing_lines = [
+            line for line in out.splitlines() if line.startswith("Routing:")
+        ]
+        if not any("every change" in line.lower() for line in routing_lines):
+            report(
+                f"{label}: routes only the entries it could read — a "
+                "declaration Keel half-read was treated as the policy, so a "
+                "typo silently lowers the process floor. {0!r}".format(
+                    routing_lines
+                )
+            )
+            report(out)
+            return 1
+        if any(declared in line for line in routing_lines):
+            report(
+                f"{label}: the readable entry was reported as the declared set "
+                "beside an unreadable one, so half a declaration acted as a "
+                f"whole one; {routing_lines!r}"
+            )
+            return 1
+        if "src/lib.js" not in out:
+            report(f"{label}: the unreadable entry is not named, so the state is not attributable.")
+            report(out)
+            return 1
+        doctor = run_keel(mixed, "--doctor").stdout
+        if "full_mode_paths: failed" not in doctor or "src/lib.js" not in doctor:
+            report(
+                f"{label}: the doctor does not report the declaration as failed "
+                "and name the entry, so it reports health the projection "
+                "contradicts."
+            )
+            report(doctor)
+            return 1
+        # The conservative branch is reached by an unreadable declaration, not
+        # by any declaration at all.
+        if "every change" in context(declaring).lower():
+            report(
+                f"{label}: a readable declaration reported the "
+                "everything-routes-Full state."
+            )
+            return 1
+
+        # M3 — the common case pays nothing.
+        for name, body in (
+            ("absent", None),
+            ("blockless", "fast_check: echo blockless\n"),
+            ("empty", "fast_check: echo empty\nfull_mode_paths:\n"),
+        ):
+            repo = fixture(name, body)
+            out = context(repo)
+            if "Routing:" in out or "full_mode_paths" in out:
+                report(
+                    f"{label}: the {name} repository was told about a routing "
+                    "declaration it does not have."
+                )
+                report(out)
+                return 1
+
+    # 1.3 — the rule itself, in the artifact `keel --init` installs. Asserted on
+    # the shipped block rather than on a fixture: this is the file a consuming
+    # repository receives, and its two budgets are what keep it resident.
+    bootstrap_path = ROOT / "assets/bootstrap/AGENTS.md"
+    bootstrap = bootstrap_path.read_text(encoding="utf-8")
+    for needle, why in (
+        ("Full", "the block must name the complete flow"),
+        ("Lite", "the block must name the local flow"),
+        ("100 lines", "the block must carry the size heuristic it is correcting"),
+        ("full_mode_paths", "the block must say a project can declare exceptions"),
+    ):
+        if needle not in bootstrap:
+            report(
+                f"{label}: bootstrap states no routing rule — {why}; "
+                f"{needle!r} is absent. Routing is the first decision of a "
+                "session and the block a consuming repository receives is "
+                "where it has to arrive."
+            )
+            return 1
+    # Both budgets. The line one runs the check the suite enforces rather than
+    # counting here; the byte one is asserted at its raised value.
+    budget_errors: list[str] = []
+    validate_resident_blocks(budget_errors)
+    if budget_errors:
+        report(f"{label}: the routing line broke the resident block line budget.")
+        for error in budget_errors:
+            report(f"- {error}")
+        return 1
+    body = bootstrap.split("<!-- keel:start", 1)[1].split("<!-- keel:end -->", 1)[0]
+    block_bytes = len(("<!-- keel:start" + body + "<!-- keel:end -->").encode())
+    if block_bytes >= BOOTSTRAP_BLOCK_BYTE_BUDGET:
+        report(
+            f"{label}: the block is {block_bytes} bytes, over its "
+            f"{BOOTSTRAP_BLOCK_BYTE_BUDGET}-byte budget."
+        )
+        return 1
+
+    # The raise is only authorized because it is loud: a larger constant with no
+    # argument beside it is exactly the quiet drift the cap was built to stop,
+    # and it would pass every check above. So both assertions of the cap must
+    # carry the reason it moved, not just the number.
+    suite = (ROOT / "scripts/validate_plugin.py").read_text(encoding="utf-8")
+    for marker in ("thin-native-install bootstrap block", "over its"):
+        start = suite.find(marker)
+        if start < 0:
+            report(f"{label}: the byte-cap assertion {marker!r} is gone.")
+            return 1
+    # The rationale for a constant in this file lives in the comment block above
+    # it, so that is where it is read from — walking back over the contiguous
+    # comment lines rather than guessing a window.
+    lines = suite.splitlines()
+    at = next(
+        i for i, line in enumerate(lines)
+        if line.startswith("BOOTSTRAP_BLOCK_BYTE_BUDGET =")
+    )
+    top = at
+    while top > 0 and lines[top - 1].startswith("#"):
+        top -= 1
+    rationale = "\n".join(lines[top:at + 1])
+    for needle in ("routing", "not quietly"):
+        if needle not in rationale:
+            report(
+                f"{label}: names the new cap without the reason it moved; "
+                f"{needle!r} is absent from the constant's own rationale. A "
+                "reader inheriting a larger number and no argument is the drift "
+                "the cap exists to prevent."
+            )
+            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),
@@ -27972,6 +28407,14 @@ SCENARIOS: tuple = (
         "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,
+    ),
+    (
+        "the-routing-rule-reaches-the-decision",
+        validate_the_routing_rule_reaches_the_decision_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,71 @@ 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 };
+}
+
+// `full_mode_paths:` — the paths whose change always routes Full, whatever the
+// diff size says. One direction only: there is no key that holds a path *out* of
+// the complete flow however large its change, because every other declaration in
+// this file removes a confirmation and never a gate, and a routing entry that
+// skipped the flow would be the first to break that.
+//
+// Each entry carries its reason. A bare path declares that a file is special and
+// leaves a reader unable to recognise the sibling the list does not name; the
+// reason is the part that transfers, so an entry without one is reported rather
+// than read.
+//
+// Neither existing reader can hold the form. `configList` takes one token per
+// item and a sentence is not one; `configMap` keys on `\w+`, which
+// `results/experiments.jsonl` is not, and values on a single token. So this gets
+// its own reader, confined to this key rather than loosening a pattern the other
+// declarations rely on being exact.
+const FULL_MODE_PATH_ENTRY = /^\s+-\s*(\S+?)\s*:\s*(\S.*?)\s*$/;
+
+function readFullModePaths(repo) {
+  const configPath = path.join(repo, "keel", "config.yaml");
+  const paths = [];
+  const unreadable = [];
+  if (!fs.existsSync(configPath)) return { paths, unreadable };
+  const opener = /^full_mode_paths\s*:\s*$/;
+  let inBlock = false;
+  for (const line of fs.readFileSync(configPath, "utf8").split(/\r?\n/)) {
+    if (/^\s*#/.test(line)) continue;
+    if (opener.test(line)) {
+      inBlock = true;
+      continue;
+    }
+    if (!inBlock) continue;
+    if (line.trim() === "") continue;
+    const item = line.match(/^\s+-\s*(.*?)\s*$/);
+    // Anything that is not a list item closes the block, exactly as it does for
+    // the other two readers.
+    if (!item) break;
+    const entry = line.match(FULL_MODE_PATH_ENTRY);
+    if (!entry) {
+      unreadable.push(item[1]);
+      continue;
+    }
+    // The path's shape is read and its existence is not. An entry may name a
+    // file that does not exist yet, which is much of the point: the schema
+    // change that has not happened is the one worth routing Full.
+    paths.push({ path: entry[1], reason: entry[2] });
+  }
+  return { paths, unreadable };
+}
+
+function fullModePathsUnreadableMessage(unreadable) {
+  return `keel/config.yaml declares a full_mode_paths ${
+    unreadable.length === 1 ? "entry" : "entries"
+  } Keel could not read: ${unreadable.join(", ")}. Write each entry as `
+    + "`- <path>: <reason>`. The reason is required: a bare path says a file is "
+    + "special without saying what makes it so, and the agent reading it cannot "
+    + "then recognise the sibling the list does not name.";
 }
 
 // A nested block of `name: value` entries under one top-level key. Delegation
@@ -389,6 +534,9 @@ module.exports = {
   CONFIG_RELATIVE_PATH,
   DELEGATION_TIERS,
   STANDING_AUTHORIZATION_ACTIONS,
+  SCOPED_AUTHORIZATION_ACTIONS,
+  readFullModePaths,
+  fullModePathsUnreadableMessage,
   readDelegationPolicy,
   readPrecedentStore,
   readStandingAuthorization,

package/src/core/context.js

@@ -11,7 +11,11 @@ const {
   field,
   parseTasks,
 } = require("./task-contract");
-const { readStandingAuthorization } = require("./config");
+const {
+  readStandingAuthorization,
+  readFullModePaths,
+  fullModePathsUnreadableMessage,
+} = require("./config");
 
 const NEXT_ACTIONS = new Set([
   "discuss",
@@ -671,6 +675,27 @@ function resolveContext(repo, options) {
   if (authorization.unknown.length > 0) {
     context.warnings.push(authorization.message);
   }
+  // Routing is the first decision of a session and the only durable rule with
+  // no gate behind it, so a project's declared exceptions are reported here —
+  // the one surface the protocol already requires an agent to read before
+  // deciding anything. Reported only when a declaration exists: a line printed
+  // every session for the repositories that declared nothing is a line a reader
+  // learns to skip (#131).
+  const routing = readFullModePaths(repo);
+  if (routing.unreadable.length > 0) {
+    // The other declarations in this file fail closed, and closed for them
+    // means *less proceeds without a human* — `authorize:` authorizes nothing,
+    // `triage:` admits nothing. The shared principle is to fail toward more
+    // scrutiny, and for a declaration whose whole purpose is to add process,
+    // more scrutiny is more Full mode. Reporting the entries it could read
+    // would let a typo silently lower the floor, which is the outcome the
+    // one-directional design exists to prevent.
+    context.routing = [];
+    context.routingUnreadable = true;
+    context.warnings.push(fullModePathsUnreadableMessage(routing.unreadable));
+  } else {
+    context.routing = routing.paths;
+  }
   // Set here rather than by the caller, so every consumer of the projection —
   // text, JSON, and any host reading it — carries the version without having
   // to know to add it.
@@ -714,6 +739,15 @@ function renderContext(result) {
         + ` (${result.selection.source})`
     );
   }
+  if (result.routingUnreadable) {
+    lines.push(
+      "Routing: every change routes Full until keel/config.yaml's "
+        + "full_mode_paths is corrected"
+    );
+  }
+  for (const entry of result.routing || []) {
+    lines.push(`Routing: ${entry.path} always routes Full — ${entry.reason}`);
+  }
   for (const reason of result.reasons) lines.push(`Reason: ${reason}`);
   for (const warning of result.warnings) lines.push(`Warning: ${warning}`);
   return `${lines.join("\n")}\n`;