@christang/keel 5.69.0 → 5.71.0

package/README.md

@@ -268,6 +268,25 @@ material choice, every gate still runs, and the write guard still binds. In part
 each step decidable with authority. And a run that stops at a real decision has ended the way it was
 designed to — resist widening the policy until it stops happening.
 
+### Who merges
+
+Keel never lets the agent merge — an unattended run opens a pull request and stops. A repository can
+still merge without a person, on a rule of its own: GitHub auto-merge behind a required status check.
+If yours does, say so:
+
+```yaml
+merge: repository:full-gate
+```
+
+`keel context` then reports that the default branch merges when `full-gate` passes and that **no human
+reviews before merge**. Without it, a reader of your protocol concludes a person looked at every change,
+because the only thing the protocol says about merging is that the agent may not.
+
+`merge: human` says the opposite. A bare `repository` is refused — "nobody reviews this" is only honest
+beside what replaced the reviewer. It is not a permission: `authorize:` has no `merge` entry and should
+not gain one. Keel reads the declaration and never GitHub, so it cannot check that auto-merge is really
+on; it reports what you declared.
+
 ### Full vs Lite
 
 Use **Full mode** (the OpenSpec flow above) for new features, interface or protocol changes,

package/assets/bootstrap/AGENTS.md

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

@@ -50,6 +50,7 @@ const {
   readStandingAuthorization,
   readFullModePaths,
   readExecutorTier,
+  readMergeDeclaration,
   fullModePathsUnreadableMessage,
   readTriagePolicy,
   triageIssue,
@@ -1733,6 +1734,7 @@ function runDoctor(options) {
   printTriageSurface(repo);
   printRoutingSurface(repo);
   printExecutorTierSurface(repo);
+  printMergeSurface(repo);
   printFastPrePushSurface(repo);
   printSourceRepoCliResolution(repo);
 
@@ -1860,6 +1862,29 @@ function printRoutingSurface(repo) {
 // Reported whether or not it is declared, because the default is the state a
 // reader most needs to see: a repository that declared nothing is loading every
 // skill's guidance and has no other surface that says so.
+// Reported whether or not it is declared: the doctor is where a reader goes to
+// learn what is and is not declared, and "undeclared" is itself the answer to
+// "does anything here claim merges are reviewed".
+function printMergeSurface(repo) {
+  process.stdout.write("\nMerge:\n");
+  const merge = readMergeDeclaration(repo);
+  if (!merge.declared) {
+    printDoctorLine("merge", "undeclared", "nothing here claims how merges happen");
+    return;
+  }
+  if (merge.unknown.length > 0) {
+    printDoctorLine("merge", "unreadable", merge.message);
+    return;
+  }
+  printDoctorLine(
+    "merge",
+    merge.kind === "repository" ? `repository:${merge.check}` : merge.kind,
+    merge.kind === "repository"
+      ? `declared in keel/config.yaml - the default branch merges when ${merge.check} passes, with no human review; the agent still never merges`
+      : "declared in keel/config.yaml - a person merges"
+  );
+}
+
 function printExecutorTierSurface(repo) {
   process.stdout.write("\nExecutor tier:\n");
   const { declared, tier, unknown, message } = readExecutorTier(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.69.0",
+  "version": "5.71.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.69.0",
+  "version": "5.71.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.69.0",
+  "version": "5.71.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.69.0"
-PROTOCOL_VERSION = "5.69.0"
+PACKAGE_VERSION = "5.71.0"
+PROTOCOL_VERSION = "5.71.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
@@ -17219,15 +17219,46 @@ def run_node_expression(root: Path, expression: str) -> str:
     return result.stdout
 
 
-def config_header_problem(names: list, flat_header: str) -> str:
+def config_header_paragraph(config_text: str) -> str:
+    """The opening paragraph that lists the declarations, whitespace-collapsed.
+
+    The header, not the file. Both callers used to pass the whole of
+    `keel/config.yaml`, so a declaration name appearing anywhere in the body — a
+    comment elsewhere that happened to use the word — satisfied "the header names
+    it". `merge` did exactly that in 5.71.0, through the triage section's "never
+    authorizes a merge", before the header said anything about it (#155).
+    """
+    lines = config_text.splitlines()
+    start = next(
+        (i for i, line in enumerate(lines) if "independent declarations live here" in line),
+        None,
+    )
+    if start is None:
+        return ""
+    paragraph = []
+    for line in lines[start:]:
+        if not line.startswith("#") or line.strip() == "#":
+            break
+        paragraph.append(line.lstrip("#").strip())
+    return re.sub(r"\s+", " ", " ".join(paragraph))
+
+
+def config_header_problem(names: list, config_text: str) -> str:
     """The one rule for "the header names every declaration", or "" when it does.
 
     Returns the diagnostic naming the missing declaration. Deliberately reports
     no count: a count tells an author that two numbers differ, and the name tells
     them which line to write.
     """
+    header = config_header_paragraph(config_text)
+    if not header:
+        return (
+            "keel/config.yaml has no header paragraph listing its declarations "
+            "(the one containing `independent declarations live here`), so "
+            "nothing tells a project which keys it may write."
+        )
     for name in names:
-        if name not in flat_header:
+        if name not in header:
             return (
                 f"keel/config.yaml's header does not name the `{name}` "
                 "declaration, so a project reading it would never learn it may "
@@ -28874,7 +28905,7 @@ def validate_a_count_is_derived_from_what_it_counts_scenario() -> int:
             return 1
 
     header = (ROOT / "keel/config.yaml").read_text(encoding="utf-8")
-    flat_header = re.sub(r"\s+", " ", header)
+    flat_header = config_header_paragraph(header)
     for name in names:
         if name not in flat_header:
             report(
@@ -28887,7 +28918,7 @@ def validate_a_count_is_derived_from_what_it_counts_scenario() -> int:
     # The derivation is proved by feeding the check a member the header cannot
     # contain. Without this the whole scenario is satisfied by a list that
     # happens to agree with a header nobody compared it to.
-    missing = config_header_problem(names + ["invented_declaration"], flat_header)
+    missing = config_header_problem(names + ["invented_declaration"], header)
     if not missing:
         report(
             f"{label}: the assertion is a literal — a declaration absent from "
@@ -28908,6 +28939,23 @@ def validate_a_count_is_derived_from_what_it_counts_scenario() -> int:
         )
         return 1
 
+    # The header is the opening paragraph, not the file. A declaration name that
+    # appears only in the body — a comment elsewhere happening to use the word —
+    # does not tell a new project it may write that key. Found when `merge` was
+    # added in 5.71.0: the triage section's "never authorizes a merge" satisfied
+    # the rule before the header said anything (#155).
+    body_only = header.replace(
+        "# delegation, which names who runs a task;",
+        "# delegation, which names who runs a task;",
+    ) + "\n# a body comment that mentions body_only_declaration in passing\n"
+    if not config_header_problem(names + ["body_only_declaration"], body_only):
+        report(
+            f"{label}: a declaration named only in the file body was accepted as "
+            "named in the header — the rule reads the whole file, so any common "
+            "word used anywhere satisfies it."
+        )
+        return 1
+
     # A header naming every declaration while miscounting them in prose passes:
     # membership is the checkable property, and a count is a lossy restatement.
     # The numeral is located by shape, not by its current value. Pinning the
@@ -28917,7 +28965,7 @@ def validate_a_count_is_derived_from_what_it_counts_scenario() -> int:
     miscounted, varied = re.subn(
         r"\b\w+ independent declarations\b",
         "Zero independent declarations",
-        flat_header,
+        header,
         count=1,
     )
     if not varied:
@@ -29697,6 +29745,263 @@ def validate_an_equivalence_claim_names_its_base_scenario() -> int:
     return 0
 
 
+# The workflow serializes, or it does not. Asserted by reading the file, because
+# it runs only on GitHub, only on a `release` event, and nothing local can
+# exercise it — which is exactly why an edit could drop the declaration and
+# nobody would find out until the next day someone cut several releases at once.
+PUBLISH_WORKFLOW = ".github/workflows/publish.yml"
+
+
+def publish_serialization_problem(workflow: str) -> str | None:
+    """Return the problem the publish workflow's ordering has, or None.
+
+    Takes the text rather than reading the path, so each broken shape can be
+    exercised on a planted copy. A rule that could only ever see the file already
+    known to be correct would pass forever without anyone learning whether it
+    fires.
+    """
+    block = re.search(
+        r"^concurrency:\n((?:[ \t]+\S[^\n]*\n)+)", workflow, re.M
+    )
+    if not block:
+        return (
+            "simultaneous releases publish concurrently — "
+            f"{PUBLISH_WORKFLOW} declares no `concurrency:` group, so every "
+            "release event starts its own publish against the same package."
+        )
+    body = block.group(1)
+    if not re.search(r"^[ \t]+cancel-in-progress:\s*false\s*$", body, re.M):
+        return (
+            "a queued publish would be cancelled — the group declares no "
+            "`cancel-in-progress: false`, and the default is `true`: the next "
+            "release would cancel a publish still waiting to run, losing that "
+            "version outright rather than appearing to."
+        )
+    group = re.search(r"^[ \t]+group:\s*(\S.*?)\s*$", body, re.M)
+    if not group:
+        return (
+            "a per-run group serializes nothing — the `concurrency:` block "
+            "names no `group:`, so there is nothing for a run to queue behind."
+        )
+    if "${{" in group.group(1):
+        return (
+            "a per-run group serializes nothing — the group expression "
+            f"`{group.group(1)}` is evaluated per run, so each release gets a "
+            "group of its own and none of them wait. The thing being protected "
+            "is the package, and there is one of those."
+        )
+    return None
+
+
+def validate_a_publish_waits_for_the_one_before_it_scenario() -> int:
+    """Issue #153: eleven releases at once, and a registry that lied about it.
+
+    Nothing was lost — every job logged its own `+ @christang/keel@<version>`,
+    and the write side proved it by refusing a re-run with `You cannot publish
+    over the previously published versions`. What broke was the read side: the
+    packument reported published versions as missing, and the set changed
+    between reads. Two re-runs were triggered on that false reading and are now
+    red rows against a release that succeeded. Serialized, each publish finishes
+    before the next begins and the window does not exist.
+    """
+    label = "a-publish-waits-for-the-one-before-it"
+    path = ROOT / PUBLISH_WORKFLOW
+    if not path.is_file():
+        report(f"{label}: {PUBLISH_WORKFLOW} is missing.")
+        return 1
+    workflow = path.read_text(encoding="utf-8")
+
+    # M1 — the real file declares it, and a copy with the block removed does not.
+    # The removal is the state the file was actually in on 2026-09-25.
+    problem = publish_serialization_problem(workflow)
+    if problem:
+        report(f"{label}: {problem}")
+        return 1
+    stripped = re.sub(
+        r"^concurrency:\n(?:[ \t]+\S[^\n]*\n)+", "", workflow, flags=re.M
+    )
+    if stripped == workflow:
+        report(
+            f"{label}: simultaneous releases publish concurrently — no "
+            "`concurrency:` block could be located to remove, so the real file "
+            "does not declare one and the check has nothing to prove."
+        )
+        return 1
+    if not publish_serialization_problem(stripped):
+        report(
+            f"{label}: simultaneous releases publish concurrently — a workflow "
+            "with no concurrency group was accepted, which is the configuration "
+            "that let eleven releases publish at once."
+        )
+        return 1
+
+    # M2 — the option whose default is wrong for this job. A check satisfied by
+    # the block alone would pass on the configuration that loses a version
+    # outright, which is worse than the one being fixed here.
+    cancelling = workflow.replace("  cancel-in-progress: false\n", "")
+    if cancelling == workflow:
+        report(
+            f"{label}: a queued publish would be cancelled — "
+            "`cancel-in-progress: false` could not be located to remove, so the "
+            "real file does not declare it."
+        )
+        return 1
+    if not publish_serialization_problem(cancelling):
+        report(
+            f"{label}: a queued publish would be cancelled — a group without "
+            "`cancel-in-progress: false` was accepted, and the default cancels "
+            "a queued publish when the next release fires."
+        )
+        return 1
+
+    # M3 — the shape that looks like a fix and is not. A group keyed per release
+    # gives every run its own group, so nothing ever queues behind anything.
+    per_ref = workflow.replace(
+        "  group: publish\n", "  group: publish-${{ github.ref }}\n"
+    )
+    if per_ref == workflow:
+        report(f"{label}: a per-run group serializes nothing — `group: publish` could not be located to vary.")
+        return 1
+    if not publish_serialization_problem(per_ref):
+        report(
+            f"{label}: a per-run group serializes nothing — a group expression "
+            "that differs per release was accepted, so each publish gets a group "
+            "of its own and none of them wait."
+        )
+        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_a_merge_names_who_makes_it_scenario() -> int:
+    """Issue #155: the protocol says the agent may not merge, and stops there.
+
+    Once a repository merges on its own rule — auto-merge behind a required
+    check — that sentence is literally true and misleading: a reader concludes
+    every change reaching the default branch was looked at by a person. The
+    declaration says who merges, so the projection can say it too.
+    """
+    label = "a-merge-names-who-makes-it"
+
+    with tempfile.TemporaryDirectory(prefix="keel-merge-") as raw:
+        root = Path(raw)
+
+        def fixture(name: str, body: str) -> Path:
+            repo = root / name
+            repo.mkdir()
+            (repo / "keel").mkdir()
+            (repo / "keel" / "config.yaml").write_text(body, encoding="utf-8")
+            return repo
+
+        def merge_lines(out: str) -> list[str]:
+            return [l for l in out.splitlines() if l.startswith("Merge:")]
+
+        # M1 — a repository merge is reported with its consequence.
+        repo = fixture("repository", "fast_check: echo r\nmerge: repository:full-gate\n")
+        out = run_keel(repo, "context").stdout
+        lines = merge_lines(out)
+        if not lines:
+            report(
+                f"{label}: no merge declaration reported — a repository that "
+                "declared its default branch merges on `full-gate` is told "
+                "nothing about it where the session starts."
+            )
+            report(out)
+            return 1
+        if "full-gate" not in lines[0]:
+            report(f"{label}: the Merge line does not name the check; got {lines[0]!r}.")
+            return 1
+        if "no human" not in lines[0].lower():
+            report(
+                f"{label}: the Merge line echoes the value without its "
+                f"consequence — that no human reviews before merge; got {lines[0]!r}."
+            )
+            return 1
+
+        human = fixture("human", "fast_check: echo h\nmerge: human\n")
+        lines = merge_lines(run_keel(human, "context").stdout)
+        if not lines:
+            report(f"{label}: no merge declaration reported for `merge: human`.")
+            return 1
+        if "human" not in lines[0]:
+            report(f"{label}: the `merge: human` line does not say human; got {lines[0]!r}.")
+            return 1
+
+        absent = fixture("absent", "fast_check: echo a\n")
+        out = run_keel(absent, "context").stdout
+        if merge_lines(out):
+            report(
+                f"{label}: an undeclared repository was given a Merge line — "
+                "Keel cannot know how it merges and must not claim it."
+            )
+            report(out)
+            return 1
+
+        # M2 — a claim without its basis claims nothing. A bare `repository`
+        # says no person reviews without naming what does, which is the claim
+        # that misleads most; an unknown value is a typo its author believes.
+        for name, value in (("bare", "repository"), ("unknown", "robots")):
+            bad = fixture(name, f"fast_check: echo b\nmerge: {value}\n")
+            out = run_keel(bad, "context").stdout
+            if merge_lines(out):
+                report(
+                    f"{label}: accepted a merge claim with no basis — "
+                    f"`merge: {value}` produced {merge_lines(out)!r}."
+                )
+                return 1
+            if value not in out:
+                report(f"{label}: the refusal does not name `{value}`.")
+                report(out)
+                return 1
+            if "repository:<check>" not in out:
+                report(f"{label}: the refusal does not name the accepted forms.")
+                report(out)
+                return 1
+
+        # M3 — the declaration is not a permission. `merge` under `authorize:`
+        # stays an unrecognized action, so nobody can read the new key as leave
+        # for the agent to merge.
+        perm = fixture("perm", "fast_check: echo p\nauthorize:\n  - merge\n")
+        doctor = run_keel(perm, "--doctor").stdout
+        if "unrecognized action: merge" not in doctor:
+            report(
+                f"{label}: `authorize: merge` is not reported as an unrecognized "
+                "action, so the new declaration could be read as permission."
+            )
+            report(doctor)
+            return 1
+
+        for name, repo_, expected in (
+            ("repository", repo, "full-gate"),
+            ("human", human, "human"),
+            ("absent", absent, "undeclared"),
+        ):
+            doctor = run_keel(repo_, "--doctor").stdout
+            merge_doctor = [l for l in doctor.splitlines() if l.startswith("merge:")]
+            if not merge_doctor:
+                report(
+                    f"{label}: no merge declaration reported by the doctor for the "
+                    f"{name} fixture — it has no `merge:` line at all."
+                )
+                return 1
+            if expected not in merge_doctor[0]:
+                report(
+                    f"{label}: the doctor's merge line for the {name} fixture does "
+                    f"not name {expected!r}; got {merge_doctor[0]!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
+
+
 SCENARIOS: tuple = (
     ("stateless-continuity", validate_stateless_continuity_scenario),
     ("core-gates", validate_core_gates_scenario),
@@ -30063,6 +30368,14 @@ SCENARIOS: tuple = (
         "an-equivalence-claim-names-its-base",
         validate_an_equivalence_claim_names_its_base_scenario,
     ),
+    (
+        "a-merge-names-who-makes-it",
+        validate_a_merge_names_who_makes_it_scenario,
+    ),
+    (
+        "a-publish-waits-for-the-one-before-it",
+        validate_a_publish_waits_for_the_one_before_it_scenario,
+    ),
     (
         "guidance-is-referenced-and-carries-no-criterion",
         validate_guidance_is_referenced_and_carries_no_criterion_scenario,

package/src/core/config.js

@@ -82,6 +82,7 @@ const CONFIG_DECLARATIONS = [
   "delegation",
   "full_mode_paths",
   "executor_tier",
+  "merge",
 ];
 
 const CONFIG_RELATIVE_PATH = path.join("keel", "config.yaml");
@@ -452,6 +453,43 @@ function executorTierUnreadableMessage(value, accepted) {
   );
 }
 
+// Who merges into the default branch. Not an `authorize:` entry: that list says
+// what the *agent* may do without asking, and merging stays out of it — both the
+// host's classifier and this protocol refuse an agent merge. This key describes
+// the repository instead. Once a repository merges on its own rule, "the agent
+// may not merge" is literally true and misleading, because a reader concludes a
+// person looked at every change (#155). Keel reads the claim and never GitHub:
+// it stays local and offline, so the declaration is the owner's statement,
+// reported where Review can see it.
+function readMergeDeclaration(repo) {
+  const declared = configScalar(repo, "merge");
+  if (!declared) return { declared: false, kind: null, check: null, unknown: [] };
+  if (declared === "human") {
+    return { declared: true, kind: "human", check: null, unknown: [] };
+  }
+  const scoped = declared.match(/^repository:(\S+)$/);
+  if (scoped) {
+    return { declared: true, kind: "repository", check: scoped[1], unknown: [] };
+  }
+  // A bare `repository` is refused like a bare `issue`: "no person reviews this"
+  // without naming what does is the claim that misleads most. An unreadable value
+  // claims nothing — neither human review nor its absence.
+  return {
+    declared: true,
+    kind: null,
+    check: null,
+    unknown: [declared],
+    message:
+      `keel/config.yaml declares merge: ${declared}, which is not one of `
+      + "human, repository:<check>; nothing is claimed about how merges happen "
+      + "until it is corrected"
+      + (declared === "repository"
+        ? " — name the required check the repository merges on, because a claim "
+          + "that no person reviews is only honest beside what replaced them"
+        : ""),
+  };
+}
+
 function configScalar(repo, key) {
   const configPath = path.join(repo, "keel", "config.yaml");
   if (!fs.existsSync(configPath)) return null;
@@ -607,6 +645,7 @@ module.exports = {
   fullModePathsUnreadableMessage,
   readDelegationPolicy,
   readExecutorTier,
+  readMergeDeclaration,
   executorTierUnreadableMessage,
   readPrecedentStore,
   readStandingAuthorization,

package/src/core/context.js

@@ -16,6 +16,7 @@ const {
   readFullModePaths,
   fullModePathsUnreadableMessage,
   readExecutorTier,
+  readMergeDeclaration,
 } = require("./config");
 
 const NEXT_ACTIONS = new Set([
@@ -701,6 +702,12 @@ function resolveContext(repo, options) {
   // the default is the one a reader most needs to see, because a repository
   // that declared nothing is loading guidance it may not want and has no other
   // surface that would tell it so.
+  // Reported only when declared, like `full_mode_paths`: an absent declaration
+  // changes nothing, and Keel cannot know how an undeclared repository merges,
+  // so it must not print a line that implies it does.
+  const merge = readMergeDeclaration(repo);
+  if (merge.declared && merge.unknown.length === 0) context.merge = merge;
+  if (merge.unknown.length > 0) context.warnings.push(merge.message);
   const executor = readExecutorTier(repo);
   context.executorTier = executor.tier;
   if (executor.unknown.length > 0) context.warnings.push(executor.message);
@@ -757,6 +764,14 @@ function renderContext(result) {
   for (const entry of result.routing || []) {
     lines.push(`Routing: ${entry.path} always routes Full — ${entry.reason}`);
   }
+  if (result.merge) {
+    lines.push(
+      result.merge.kind === "repository"
+        ? `Merge: repository — the default branch merges when ${result.merge.check} `
+          + "passes; no human reviews before merge, so that check is the last gate"
+        : `Merge: ${result.merge.kind} — a person merges into the default branch`
+    );
+  }
   if (result.executorTier) {
     lines.push(
       `Executor tier: ${result.executorTier} — affects which skill guidance is `