@event4u/agent-config 5.3.0 → 5.4.1

package/scripts/_cli/cmd_doctor.py

@@ -49,7 +49,7 @@ import sys
 from pathlib import Path
 from typing import Any
 
-from scripts._lib import installed_tools
+from scripts._lib import installed_lock, installed_tools
 from scripts._lib.agent_settings import (
     PROJECT_ROOT_ENV,
     ROOT_OVERRIDE_ENV,
@@ -440,6 +440,7 @@ def _foreign_records(
 #: a runner below and an entry in :func:`_run_checks`.
 CHECK_IDS = (
     "scope",
+    "global-binary",
     "manifest-integrity",
     "lockfile-freshness",
     "bridge-drift",
@@ -587,6 +588,47 @@ def _check_lockfile_freshness(manifest: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _check_global_binary(project_root: Path) -> dict[str, Any]:
+    """`agent-config` PATH resolution + global-install version parity.
+
+    The Claude plugin hook resolves `agent-config` from PATH (ADR-020
+    global-only); if it is missing, every PostToolUse hook fails silently —
+    this is the root cause of the "dashboard never updates" report. Version
+    drift between the binary on PATH and the global install root means the
+    plugin may emit a hook spec the installed binary predates.
+    """
+    binary = shutil.which("agent-config")
+    if not binary:
+        return {
+            "id": "global-binary", "status": "fail",
+            "message": "`agent-config` is not on PATH — Claude plugin hooks "
+                       "cannot resolve it (hooks silently no-op)",
+            "remedy": "npm install -g @event4u/agent-config, then re-run doctor",
+        }
+    lock = installed_lock.read_lockfile()
+    global_v = ""
+    if isinstance(lock, dict):
+        raw = lock.get("agent_config_version")
+        global_v = raw.strip().lstrip("v") if isinstance(raw, str) else ""
+    binary_v = (_current_package_version() or "").lstrip("v")
+    if global_v and binary_v and global_v != binary_v:
+        return {
+            "id": "global-binary", "status": "warn",
+            "message": f"version drift — binary {binary_v}, global install "
+                       f"{global_v}",
+            "remedy": "agent-config upgrade (refresh the global install + plugin)",
+        }
+    bridge = project_root / "agents" / ".event4u-bridge.yml"
+    bridge_note = "" if bridge.is_file() else " · no project bridge marker"
+    return {
+        "id": "global-binary", "status": "ok",
+        "message": f"on PATH ({binary}); version {binary_v or 'unknown'}"
+                   f"{bridge_note}",
+        "remedy": "" if not bridge_note else
+                  "agent-config refresh --project (scaffold the bridge marker)",
+    }
+
+
 def _check_bridge_drift(
     missing: list[dict[str, Any]],
     modified: list[dict[str, Any]],
@@ -1092,6 +1134,7 @@ def _run_checks(
     """
     runners: dict[str, Any] = {
         "scope": lambda: _check_scope(project_root),
+        "global-binary": lambda: _check_global_binary(project_root),
         "manifest-integrity": lambda: _check_manifest_integrity(manifest),
         "lockfile-freshness": lambda: _check_lockfile_freshness(manifest),
         "bridge-drift": lambda: _check_bridge_drift(

package/scripts/_cli/cmd_refresh.py

@@ -0,0 +1,173 @@
+"""``agent-config refresh`` — idempotent re-install, no version change.
+
+The same-version counterpart to ``agent-config upgrade`` (which fetches
+the latest). Two scopes, exactly one required:
+
+* ``--global`` — re-run the global install (``scripts/install --global``)
+  so the global root + Claude plugin hooks are rewritten from the
+  currently-installed package. Idempotent: a second run is a no-op diff.
+* ``--project`` — refresh the **minimal** project surface ADR-020 permits
+  for a consumer: the ``agents/.event4u-bridge.yml`` marker, an
+  ``agents/overrides/`` scaffold, and the managed ``agents/`` block in
+  ``.gitignore``. Writes **no** distributed content (no ``.augment/`` /
+  ``.claude/`` / skills / hooks). No wizard.
+
+Bare ``agent-config refresh`` (no scope flag) errors — never a silent
+global default (council 2026-05-30).
+
+Exit codes: ``0`` success · ``1`` a step failed / bad invocation.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+
+Runner = Callable[[list[str]], int]
+
+
+def _default_runner(cmd: list[str]) -> int:
+    try:
+        return subprocess.run(cmd, check=False).returncode
+    except OSError as exc:
+        sys.stderr.write(f"agent-config refresh: cannot run {cmd[0]}: {exc}\n")
+        return 1
+
+
+def _refresh_global(runner: Runner, out, err) -> int:
+    install_sh = PACKAGE_ROOT / "scripts" / "install"
+    if not install_sh.is_file():
+        print(f"❌  agent-config refresh: installer not found at {install_sh}",
+              file=err)
+        return 1
+    print("→ refreshing global install (scripts/install --global)", file=out)
+    rc = runner(["bash", str(install_sh), "--global"])
+    if rc != 0:
+        print(f"❌  agent-config refresh --global: install failed (exit {rc})",
+              file=err)
+        return 1
+    print("✅  global install refreshed.", file=out)
+    return 0
+
+
+def _is_source_repo(project_root: Path) -> bool:
+    """True when project_root is the agent-config package itself.
+
+    ``_write_consumer_bridge_marker`` only guards on a root-level
+    ``.agent-src.uncondensed/``, which the monorepo keeps under
+    ``packages/*/`` instead — so the narrow guard misses here and would
+    write a consumer marker into the maintainer tree. This broader check
+    (condensed output, packaged source, or the package's own
+    ``package.json`` name) makes ``refresh --project`` a no-op in any
+    agent-config checkout. Consumers use dev-mode, not refresh.
+    """
+    if (project_root / ".agent-src").is_dir():
+        return True
+    if any((project_root / "packages").glob("*/.agent-src.uncondensed")):
+        return True
+    pkg = project_root / "package.json"
+    if pkg.is_file():
+        try:
+            import json
+            if json.loads(pkg.read_text(encoding="utf-8")).get("name") == \
+                    "@event4u/agent-config":
+                return True
+        except (OSError, ValueError):
+            pass
+    return False
+
+
+def _refresh_project(project_root: Path, out, err) -> int:
+    # Imported lazily: scripts.install is large and only needed for --project.
+    from scripts import install as installer
+    from scripts._lib import installed_lock
+
+    if _is_source_repo(project_root):
+        print("ℹ️  refresh --project skipped: this is the agent-config package "
+              "itself (or a checkout of it). Maintainers use "
+              "AGENT_CONFIG_DEV_MODE=1, not a consumer refresh.", file=out)
+        return 0
+
+    version = installed_lock.current_package_version() or "0.0.0"
+    marker = installer._write_consumer_bridge_marker(project_root, version)
+    if marker is None:
+        print("ℹ️  refresh --project skipped the bridge marker: this is the "
+              "agent-config source repo (or AGENT_CONFIG_DEV_MODE=1). Nothing "
+              "to scaffold in a maintainer checkout.", file=out)
+        return 0
+
+    print(f"✅  bridge marker: {marker}", file=out)
+
+    overrides = project_root / "agents" / "overrides"
+    overrides.mkdir(parents=True, exist_ok=True)
+    keep = overrides / "README.md"
+    if not keep.exists():
+        keep.write_text(
+            "# Project overrides\n\n"
+            "Project-local overrides/extensions of shared skills, rules, and "
+            "commands. The only project-side agent surface ADR-020 permits "
+            "besides the bridge marker. See the `override-management` skill.\n",
+            encoding="utf-8")
+    print(f"✅  overrides scaffold: {overrides}", file=out)
+
+    rc = _sync_gitignore(project_root, out, err)
+    if rc != 0:
+        return rc
+    print("✅  refresh --project complete.", file=out)
+    return 0
+
+
+def _sync_gitignore(project_root: Path, out, err) -> int:
+    try:
+        from scripts import sync_gitignore
+    except ImportError as exc:
+        print(f"⚠️  refresh --project: gitignore sync unavailable ({exc})",
+              file=err)
+        return 0  # advisory — do not fail the refresh on a missing helper
+    rc = sync_gitignore.main(["--path", str(project_root / ".gitignore")])
+    if rc not in (0, None):
+        print(f"⚠️  refresh --project: gitignore sync returned {rc}", file=err)
+    else:
+        print("✅  .gitignore agents/ block synced.", file=out)
+    return 0
+
+
+def main(
+    argv: Optional[list[str]] = None,
+    *,
+    runner: Runner = _default_runner,
+    project_root: Optional[Path] = None,
+    out=sys.stdout,
+    err=sys.stderr,
+) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config refresh",
+        description="Idempotent re-install (no version change). Requires a scope.",
+    )
+    parser.add_argument("--global", dest="is_global", action="store_true",
+                        help="Re-run the global install (root + Claude plugin).")
+    parser.add_argument("--project", dest="is_project", action="store_true",
+                        help="Refresh the minimal project surface (bridge "
+                             "marker, overrides scaffold, .gitignore).")
+    args = parser.parse_args(argv)
+
+    if not args.is_global and not args.is_project:
+        print("❌  agent-config refresh: specify a scope — --global "
+              "and/or --project (never a silent default).", file=err)
+        return 1
+
+    root = project_root or Path.cwd()
+    rc = 0
+    if args.is_global:
+        rc = _refresh_global(runner, out, err) or rc
+    if args.is_project and rc == 0:
+        rc = _refresh_project(root, out, err) or rc
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/_cli/cmd_upgrade.py

@@ -0,0 +1,142 @@
+"""``agent-config upgrade`` — fetch + install the latest global binary + refresh.
+
+Distinct from ``agent-config update`` (which only flips the
+``agent_config_version`` pin in ``.agent-settings.yml`` — a project
+decision, see :mod:`scripts._cli.cmd_update`). ``upgrade`` is the
+**global** self-update path mandated by ADR-020's "no per-repo bump"
+goal: it installs the latest published package globally and re-runs the
+global install so new skills / rules / hooks reach every consumer at
+once.
+
+Two side effects, in order:
+
+1. ``npm install -g @event4u/agent-config@latest`` — refresh the global
+   binary on PATH (the binary the Claude plugin hook resolves).
+2. ``agent-config global`` (→ ``install.py --global``) — refresh the
+   global root (``~/.event4u/agent-config/``) + regenerate plugin hooks.
+
+The **Claude marketplace plugin** updates on Claude Code's own cadence,
+independent of npm; ``upgrade`` cannot drive it. ``agent-config doctor``
+surfaces binary↔plugin drift so the user knows when to update the plugin
+from the marketplace.
+
+Flags:
+
+* ``--check`` — report installed vs latest; install nothing. Exit 0.
+* ``--dry-run`` — print the exact commands that would run; execute none.
+* (no flag) — perform the upgrade.
+
+Exit codes: ``0`` success / already-latest / check / dry-run · ``1`` a
+step failed.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+
+from scripts._lib import installed_lock, update_check
+
+PACKAGE_NAME = "@event4u/agent-config"
+
+# A runner is injected in tests so the global-mutating commands are never
+# executed in CI / sandbox. Returns the subprocess return code.
+Runner = Callable[[list[str]], int]
+
+
+def _default_runner(cmd: list[str]) -> int:
+    try:
+        return subprocess.run(cmd, check=False).returncode
+    except OSError as exc:  # npm / bash missing
+        sys.stderr.write(f"agent-config upgrade: cannot run {cmd[0]}: {exc}\n")
+        return 1
+
+
+def _installed_version() -> str:
+    lock = installed_lock.read_lockfile()
+    if isinstance(lock, dict):
+        v = lock.get("agent_config_version")
+        if isinstance(v, str) and v:
+            return v.strip().lstrip("v")
+    return ""
+
+
+def _agent_config_bin() -> str:
+    """The global wrapper the second step invokes. Prefer the binary on
+    PATH; fall back to the package-local wrapper so a maintainer dev-loop
+    (no global install yet) still refreshes."""
+    from shutil import which
+    return which("agent-config") or str(
+        Path(__file__).resolve().parents[2] / "agent-config")
+
+
+def main(
+    argv: Optional[list[str]] = None,
+    *,
+    runner: Runner = _default_runner,
+    fetcher=update_check.fetch_latest_from_npm,
+    installed: Optional[str] = None,
+    out=sys.stdout,
+    err=sys.stderr,
+) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config upgrade",
+        description="Install the latest @event4u/agent-config globally and "
+                    "refresh the global install.",
+    )
+    parser.add_argument("--check", action="store_true",
+                        help="Report installed vs latest; install nothing.")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Print the commands that would run; execute none.")
+    args = parser.parse_args(argv)
+
+    installed = installed if installed is not None else _installed_version()
+    latest = fetcher() or ""
+
+    if args.check:
+        if not latest:
+            print("agent-config upgrade: latest version unavailable "
+                  "(registry unreachable).", file=err)
+            return 0
+        if installed and not installed_lock_is_newer(latest, installed):
+            print(f"✅  agent-config is up to date ({installed}).", file=out)
+        else:
+            print(f"ℹ️  agent-config {latest} available "
+                  f"(installed: {installed or 'unknown'}). Run "
+                  f"`agent-config upgrade`.", file=out)
+        return 0
+
+    target = f"{PACKAGE_NAME}@latest"
+    steps = [
+        ["npm", "install", "-g", target],
+        [_agent_config_bin(), "global"],
+    ]
+
+    if args.dry_run:
+        print("agent-config upgrade — dry run, would execute:", file=out)
+        for cmd in steps:
+            print("  " + " ".join(cmd), file=out)
+        return 0
+
+    for cmd in steps:
+        print("→ " + " ".join(cmd), file=out)
+        rc = runner(cmd)
+        if rc != 0:
+            print(f"❌  agent-config upgrade: step failed (exit {rc}): "
+                  f"{' '.join(cmd)}", file=err)
+            return 1
+
+    print("✅  agent-config upgraded. Run `agent-config doctor` to verify "
+          "PATH + plugin parity.", file=out)
+    return 0
+
+
+def installed_lock_is_newer(latest: str, installed: str) -> bool:
+    """Thin wrapper around update_check._is_newer for one import site."""
+    return update_check._is_newer(latest, installed)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/_dispatch.bash

@@ -72,11 +72,19 @@ EOF
 Tier 1 — power-user (release shape, audit, migration):
   update                     Update the agent_config_version pin in .agent-settings.yml
                              Flags: --check (read-only) | --to <version> (explicit pin)
+  upgrade                    Install the latest @event4u/agent-config globally
+                             (npm i -g) and refresh the global install + plugin.
+                             Flags: --check (report only) | --dry-run
+  refresh                    Idempotent re-install, no version change.
+                             --global (root + plugin) | --project (bridge
+                             marker + overrides + .gitignore). Scope required.
   versions                   List available @event4u/agent-config versions
                              on npm. Marks the current pin and latest.
                              Flags: --offline | --limit=N | --json
   global                     Install to user-scope paths (~/.claude/, ~/.cursor/, …)
                              Forwards to `scripts/install --global` (ADR-007).
+                             `refresh --global` is the clearer name for a re-run;
+                             `global` is retained as the original alias.
                              Flags: --tools=<list> | --ai=<list> | --yes | --force
   export                     Eject a tool's canonical content into a chosen path
                              (real file, no symlink). Idempotent; --force overrides
@@ -773,6 +781,16 @@ cmd_update() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_update "$@"
 }
 
+cmd_upgrade() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_upgrade "$@"
+}
+
+cmd_refresh() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_refresh "$@"
+}
+
 # `agent-config migrate` — one-shot migration off legacy composer / npm
 # install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.py
 # (P3.5 of road-to-portable-runtime-and-update-check.md).
@@ -932,6 +950,8 @@ main() {
     council:run)             cmd_council run "$@" ;;
     council:render)          cmd_council render "$@" ;;
     update)                  cmd_update "$@" ;;
+    upgrade)                 cmd_upgrade "$@" ;;
+    refresh)                 cmd_refresh "$@" ;;
     migrate)                 cmd_migrate "$@" ;;
     init)                    cmd_init "$@" ;;
     global)                  cmd_global "$@" ;;

package/scripts/backfill_model_tier.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Backfill / migrate `model_tier` on every skill and command (ADR-035).
+
+Vendor-neutral capability band `lite | medium | high | inherit` (replaces the
+concrete-model `recommended_model` from ADR-034). Behaviour per artefact:
+
+- **Has `recommended_model`** (ADR-034 legacy) → migrate via the value map
+  (`opus→high`, `sonnet→medium`, `gpt→high`, `inherit→inherit`) and rename the
+  key to `model_tier`. Same line count — no body shift.
+- **Already `model_tier`** → leave (idempotent).
+- **Untagged** → classify fresh from the task→tier heuristic
+  (`contexts/model-recommendations.md`): deep reasoning → high; mechanical /
+  impl / docs / tests / quality → medium; clearly-trivial → lite; meta /
+  ambiguous → inherit.
+
+A small explicit `_LITE` set demotes obviously-trivial mechanical skills to the
+cheapest band; `_CONTEXT_LARGE` adds the orthogonal `context: large` modifier to
+genuinely long-context skills. Writes BOTH the source and its `.agent-src` copy
+(frontmatter stays byte-identical); refresh condensation hashes afterwards.
+
+CLI: python3 scripts/backfill_model_tier.py [--dry-run]
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[1]
+CONDENSED = ROOT / ".agent-src"
+
+# ADR-034 → ADR-035 value map.
+_MIGRATE = {"opus": "high", "sonnet": "medium", "gpt": "high", "inherit": "inherit"}
+
+# Fresh-classification slug signals (deep reasoning / large-analysis → high).
+_HIGH = (
+    "architect", "refactor", "debug", "threat", "authz", "adversarial",
+    "blast-radius", "defense-in-depth", "data-flow", "decision-record",
+    "adr-create", "security-audit", "privacy-review", "review", "judge-",
+    "bug-analyzer", "systematic-debugging", "incident", "risk-officer",
+    "migration-architect", "moat", "analysis", "analyze", "analyzer",
+    "research", "deep-reading", "repomix", "sequential-thinking",
+    "project-analysis", "universal-project", "market-entry",
+    "scenario-modeling", "forecast", "dcf-modeling", "unit-economics",
+    "funnel-analysis",
+)
+_MEDIUM = (
+    "test", "pest", "playwright", "lint", "quality-tools", "format", "docs",
+    "readme-writing", "commit", "conventional", "css", "tailwind", "blade",
+    "flux", "livewire", "form-handler", "api-endpoint", "api-testing",
+    "eloquent", "laravel", "dto", "mail", "notification", "migration",
+    "middleware", "scheduling", "websocket", "reverb", "horizon", "pulse",
+    "pennant", "validation", "docker", "terraform", "terragrunt", "github-ci",
+    "traefik", "grafana", "dashboard", "openapi", "sql", "artisan", "composer",
+    "jobs-events", "multi-tenancy", "secrets", "logging", "database",
+    "php-coder", "php-service", "nextjs", "react", "symfony", "mcp",
+    "devcontainer", "copilot", "module",
+)
+_DOMAIN_DEFAULT = {
+    "engineering": "medium", "quality": "medium", "devops": "medium",
+    "discovery": "high", "product": "inherit", "process": "inherit",
+}
+
+# Clearly-trivial, no-reasoning mechanical skills → cheapest band.
+_LITE = {"file-editor", "md-language-check"}
+# Genuinely long-context skills → orthogonal context modifier (ADR-035).
+_CONTEXT_LARGE = {
+    "project-analysis-core", "project-analysis-hypothesis-driven",
+    "project-analyzer", "universal-project-analysis", "repomix-packer",
+    "deep-reading-analyst",
+}
+
+_RM_RE = re.compile(r'^recommended_model:[ \t]*"?[a-z0-9-]+"?[ \t]*$', re.MULTILINE)
+_MT_RE = re.compile(r'^model_tier:', re.MULTILINE)
+_CTX_RE = re.compile(r'^context:', re.MULTILINE)
+
+
+def _classify(slug: str, domain: str | None) -> str:
+    s = slug.lower()
+    if s in _LITE:
+        return "lite"
+    if any(k in s for k in _HIGH):
+        return "high"
+    if any(k in s for k in _MEDIUM):
+        return "medium"
+    return _DOMAIN_DEFAULT.get(domain or "", "inherit")
+
+
+def _resolve_tier(slug: str, fm: dict | None) -> str:
+    existing_mt = fm.get("model_tier") if isinstance(fm, dict) else None
+    if existing_mt:
+        tier = existing_mt
+    else:
+        existing_rm = fm.get("recommended_model") if isinstance(fm, dict) else None
+        if existing_rm:
+            tier = _MIGRATE.get(existing_rm, "inherit")
+        else:
+            tier = _classify(slug, fm.get("domain") if isinstance(fm, dict) else None)
+    return "lite" if slug in _LITE else tier
+
+
+def _apply(path: Path, tier: str, want_context: bool) -> bool:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return False
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return False
+    fm, body = text[4:end], text[end:]
+    changed = False
+    if _MT_RE.search(fm):
+        pass  # already migrated — idempotent
+    elif _RM_RE.search(fm):
+        fm = _RM_RE.sub(f"model_tier: {tier}", fm, count=1)
+        changed = True
+    else:
+        fm = f"model_tier: {tier}\n" + fm
+        changed = True
+    if want_context and not _CTX_RE.search(fm):
+        fm = re.sub(r'(^model_tier:.*$)', r'\1\ncontext: large', fm, count=1, flags=re.MULTILINE)
+        changed = True
+    if changed:
+        path.write_text("---\n" + fm + body, encoding="utf-8")
+    return changed
+
+
+def _iter():
+    for root in artefact_roots():
+        sdir = root / "skills"
+        if sdir.exists():
+            for p in sorted(sdir.rglob("SKILL.md")):
+                slug = p.parent.name
+                yield p, CONDENSED / "skills" / slug / "SKILL.md", slug
+        cdir = root / "commands"
+        if cdir.exists():
+            for p in sorted(cdir.rglob("*.md")):
+                if p.name == "AGENTS.md":
+                    continue
+                rel = p.relative_to(cdir)
+                slug = "-".join(rel.with_suffix("").parts)
+                yield p, CONDENSED / "commands" / rel, slug
+
+
+def run(apply: bool) -> int:
+    dist: Counter = Counter()
+    ctx = 0
+    touched = 0
+    for src, cond, slug in _iter():
+        fm, _ = parse_frontmatter(src.read_text(encoding="utf-8"))
+        tier = _resolve_tier(slug, fm)
+        want_ctx = slug in _CONTEXT_LARGE
+        dist[tier] += 1
+        if want_ctx:
+            ctx += 1
+        if apply:
+            if _apply(src, tier, want_ctx):
+                touched += 1
+            if cond.exists():
+                _apply(cond, tier, want_ctx)
+    verb = "would set" if not apply else "set"
+    print(f"model_tier backfill ({'dry-run' if not apply else 'apply'}):")
+    for t in ("lite", "medium", "high", "inherit"):
+        print(f"  {t:8s}: {dist[t]}")
+    print(f"  context:large on {ctx} skills · {verb} {touched} newly · total {sum(dist.values())}")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args(argv)
+    return run(apply=not args.dry_run)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_release_pr_shape.py

@@ -9,6 +9,7 @@ and asserts every changed file matches the version-bump allowlist:
   * `.claude-plugin/marketplace.json`
   * `packages/*/pack.yaml`
   * `packages/*/README.md`
+  * `docs/archive/CHANGELOG-pre-*.md`
 
 Exit codes:
 
@@ -40,6 +41,12 @@ ALLOWLIST_GLOBS = (
     ".claude-plugin/marketplace.json",
     "packages/*/pack.yaml",
     "packages/*/README.md",
+    # `scripts/release.py` auto-splits the CHANGELOG era before bumping
+    # (perform_split / plan_split in `_lib/changelog_eras.py`) whenever the
+    # current era body crosses CURRENT_ERA_BODY_CAP. The split emits a new
+    # `docs/archive/CHANGELOG-pre-X.Y.Z.md` — part of the release surface,
+    # so the shape gate must allow it. Test-enforced by test_changelog_eras.
+    "docs/archive/CHANGELOG-pre-*.md",
 )