@christang/keel 5.68.0 → 5.70.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.68.0 -->
+<!-- keel:start version=5.70.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/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.68.0",
+  "version": "5.70.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.68.0",
+  "version": "5.70.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.68.0",
+  "version": "5.70.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.68.0"
-PROTOCOL_VERSION = "5.68.0"
+PACKAGE_VERSION = "5.70.0"
+PROTOCOL_VERSION = "5.70.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
@@ -2302,6 +2302,61 @@ def validate_domain_lenses_scenario() -> int:
     return 0
 
 
+# `bump_version.js` writes a stub section for the new release, and the convention
+# is to fill it in. Writing the entry *above* it instead leaves an orphan, and
+# the stub carries the `Version alignment:` line this scenario reads — so the
+# section describing nothing was the section that passed (#151). It happened in
+# 5.67.0 and 5.68.0, with the suite green both times.
+#
+# Takes the text rather than reading the file, so the rule can be exercised on a
+# planted copy: a rule that could only ever see the changelog already known to be
+# correct would pass forever without anyone learning whether it fires.
+def release_description_problem(changelog: str, version: str) -> str | None:
+    """Return the problem the released version's section has, or None.
+
+    Scoped to the version being released. An older section is history a current
+    author cannot act on, and a rule that swept the whole file would fail on the
+    archive — which is how a check gets disabled rather than fixed. The file also
+    legitimately quotes `TODO` when describing the rules that refuse it.
+    """
+    pattern = re.compile(
+        r"^## " + re.escape(version) + r"\b[^\n]*$", re.M
+    )
+    headings = pattern.findall(changelog)
+    if not headings:
+        return (
+            f"the changelog carries no `## {version}` section, so the release "
+            "describes nothing at all."
+        )
+    if len(headings) > 1:
+        return (
+            f"the changelog describes {version} twice — {len(headings)} `## "
+            f"{version}` headings: {', '.join(h.strip() for h in headings)}. A "
+            "release entry written above the stub instead of into it leaves both."
+        )
+    for heading in headings:
+        if "TODO" in heading:
+            return (
+                f"the changelog still carries the stub heading `{heading.strip()}`"
+                f", so the {version} release was never described. Fill that "
+                "section in rather than writing the entry above it."
+            )
+    # The section body, bounded by the next `## ` heading, so a `TODO` belonging
+    # to an older release is not read as this one's.
+    start = changelog.index(headings[0])
+    rest = changelog[start + len(headings[0]):]
+    end = rest.find("\n## ")
+    body = rest if end < 0 else rest[:end]
+    for line in body.splitlines():
+        if re.match(r"^\s*-\s*TODO\b", line):
+            return (
+                f"the {version} section still carries the stub bullet "
+                f"`{line.strip().lstrip('- ')}`, so the release is titled but "
+                "not described."
+            )
+    return None
+
+
 def validate_version_alignment_scenario() -> int:
     package = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
     if package.get("version") != PACKAGE_VERSION:
@@ -2366,6 +2421,103 @@ def validate_version_alignment_scenario() -> int:
         )
         return 1
 
+    # The released version's section has to say what the release did. Asserted on
+    # planted copies first, so the rule is known to fire, and then on the
+    # repository's own changelog.
+    stub = (
+        f"# Keel Changelog\n\n## {PACKAGE_VERSION} - TODO: summarize this "
+        f"release\n\n- TODO: describe the change.\n- Version alignment: "
+        f"shares Keel {PACKAGE_VERSION}.\n\n## 5.0.0 - older\n\n- Done.\n"
+    )
+    planted = release_description_problem(stub, PACKAGE_VERSION)
+    if not planted:
+        report(
+            "version-alignment scenario: an unfilled stub was accepted — a "
+            f"changelog whose {PACKAGE_VERSION} section is the stub "
+            "`bump_version.js` writes produced no problem, so a release can "
+            "ship describing nothing while this scenario passes."
+        )
+        return 1
+    if "TODO: summarize this release" not in planted:
+        report(
+            "version-alignment scenario: the refusal does not name the offending "
+            f"line, so an author is sent to read the whole changelog; got "
+            f"{planted!r}."
+        )
+        return 1
+
+    # Still M1 — the stub survives renaming its heading. The bullet is the other
+    # half of what `bump_version.js` writes, and a section titled correctly while
+    # its only content is `- TODO: describe the change.` describes nothing.
+    renamed = (
+        f"# Keel Changelog\n\n## {PACKAGE_VERSION} - a real sounding title\n\n"
+        f"- TODO: describe the change.\n- Version alignment: shares Keel "
+        f"{PACKAGE_VERSION}.\n"
+    )
+    bullet = release_description_problem(renamed, PACKAGE_VERSION)
+    if not bullet:
+        report(
+            "version-alignment scenario: an unfilled stub was accepted — a "
+            "section with a real heading whose content is still `- TODO: describe "
+            "the change.` produced no problem, so renaming the stub is enough to "
+            "ship an undescribed release."
+        )
+        return 1
+    if "TODO: describe the change." not in bullet:
+        report(
+            "version-alignment scenario: the bullet refusal does not name the "
+            f"line it found; got {bullet!r}."
+        )
+        return 1
+
+    # M2 — two sections for one version. This is the shape the real defect had,
+    # and neither TODO rule catches it once the stub's heading has been renamed:
+    # the reader then sees two identical version headings, one of which describes
+    # nothing.
+    doubled = (
+        f"# Keel Changelog\n\n## {PACKAGE_VERSION} - the real entry\n\n"
+        f"- Did the thing.\n- Version alignment: shares Keel {PACKAGE_VERSION}."
+        f"\n\n## {PACKAGE_VERSION} - summarized\n\n- Also this.\n"
+    )
+    problem_found = release_description_problem(doubled, PACKAGE_VERSION)
+    if not problem_found:
+        report(
+            "version-alignment scenario: a version described twice was accepted "
+            f"— two `## {PACKAGE_VERSION}` sections produced no problem, which is "
+            "the shape the defect this rule exists for actually had."
+        )
+        return 1
+    if "twice" not in problem_found:
+        report(
+            "version-alignment scenario: the duplicate-section refusal does not "
+            f"say the version is described twice; got {problem_found!r}."
+        )
+        return 1
+
+    # M3 — only the version being released is judged. An older section is history,
+    # and this file legitimately quotes `TODO` when describing the rules that
+    # refuse it, so a rule sweeping the whole file would fire on its own
+    # documentation.
+    older = (
+        f"# Keel Changelog\n\n## {PACKAGE_VERSION} - the real entry\n\n"
+        f"- Did the thing.\n- Version alignment: shares Keel {PACKAGE_VERSION}."
+        "\n\n## 5.0.0 - TODO: summarize this release\n\n- TODO: describe it.\n"
+    )
+    if release_description_problem(older, PACKAGE_VERSION):
+        report(
+            "version-alignment scenario: an older section was refused — a `TODO` "
+            "in a section for another version failed the current release, which "
+            "is a check the archive can only be edited to satisfy."
+        )
+        return 1
+    if release_description_problem(changelog, PACKAGE_VERSION):
+        report(
+            "version-alignment scenario: an older section was refused — the "
+            "repository's own changelog does not satisfy the rule: "
+            f"{release_description_problem(changelog, PACKAGE_VERSION)}"
+        )
+        return 1
+
     with tempfile.TemporaryDirectory(prefix="keel-version-") as raw_tmp:
         repo = Path(raw_tmp) / "repo"
         repo.mkdir()
@@ -29545,6 +29697,138 @@ 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
+
+
 SCENARIOS: tuple = (
     ("stateless-continuity", validate_stateless_continuity_scenario),
     ("core-gates", validate_core_gates_scenario),
@@ -29911,6 +30195,10 @@ SCENARIOS: tuple = (
         "an-equivalence-claim-names-its-base",
         validate_an_equivalence_claim_names_its_base_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,