@event4u/agent-config 1.14.0 → 1.15.0

package/scripts/lint_rule_interactions.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Lint docs/contracts/rule-interactions.yml.
+
+Validates:
+  - Schema (required fields per pair)
+  - All rule slugs in `rules:` exist as `.agent-src.uncompressed/rules/<slug>.md`
+  - Every pair references rules listed in the top-level `rules:` block
+  - `relation` is one of the allowed values
+  - All `evidence:` entries point at real files (anchors are advisory, not checked)
+  - Pair `id`s are unique
+  - The anchor pair from `road-to-post-pr29-optimize.md` Phase 2 is present:
+    `non-destructive-by-default` × {autonomous-execution, scope-control,
+    commit-policy, ask-when-uncertain, verify-before-complete}.
+
+Exits non-zero on any failure. Used in CI via Taskfile target
+`lint-rule-interactions`.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+MATRIX = ROOT / "docs" / "contracts" / "rule-interactions.yml"
+RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
+
+ALLOWED_RELATIONS = {
+    "overrides",
+    "narrows",
+    "defers_to",
+    "restates",
+    "gates",
+    "complements",
+}
+
+REQUIRED_PAIR_FIELDS = {"id", "rules", "relation", "conflict", "resolution", "evidence"}
+
+ANCHOR_PARTNERS = {
+    "autonomous-execution",
+    "scope-control",
+    "commit-policy",
+    "ask-when-uncertain",
+    "verify-before-complete",
+}
+ANCHOR_RULE = "non-destructive-by-default"
+
+
+def fail(errors: list[str]) -> None:
+    print(f"❌  rule-interactions.yml — {len(errors)} issue(s):")
+    for e in errors:
+        print(f"  • {e}")
+    sys.exit(1)
+
+
+def main() -> int:
+    if not MATRIX.exists():
+        fail([f"{MATRIX.relative_to(ROOT)} is missing"])
+
+    data = yaml.safe_load(MATRIX.read_text())
+    errors: list[str] = []
+
+    if not isinstance(data, dict):
+        fail(["top-level YAML must be a mapping"])
+
+    if data.get("version") != 1:
+        errors.append("version must be 1")
+
+    declared_rules = data.get("rules") or []
+    if not isinstance(declared_rules, list) or not declared_rules:
+        errors.append("`rules:` must be a non-empty list of slugs")
+
+    for slug in declared_rules:
+        if not isinstance(slug, str):
+            errors.append(f"rule slug not a string: {slug!r}")
+            continue
+        rule_path = RULES_DIR / f"{slug}.md"
+        if not rule_path.exists():
+            errors.append(f"rule slug `{slug}` has no file at {rule_path.relative_to(ROOT)}")
+
+    pairs = data.get("pairs") or []
+    if not isinstance(pairs, list) or not pairs:
+        errors.append("`pairs:` must be a non-empty list")
+
+    seen_ids: set[str] = set()
+    declared_set = set(declared_rules) if isinstance(declared_rules, list) else set()
+    anchor_partners_seen: set[str] = set()
+
+    for idx, pair in enumerate(pairs):
+        if not isinstance(pair, dict):
+            errors.append(f"pair[{idx}] is not a mapping")
+            continue
+        missing = REQUIRED_PAIR_FIELDS - set(pair)
+        if missing:
+            errors.append(f"pair[{idx}] missing fields: {sorted(missing)}")
+            continue
+
+        pid = pair["id"]
+        if pid in seen_ids:
+            errors.append(f"duplicate pair id: {pid}")
+        seen_ids.add(pid)
+
+        rules_pair = pair["rules"]
+        if not (isinstance(rules_pair, list) and len(rules_pair) == 2):
+            errors.append(f"pair `{pid}` rules must be a 2-element list")
+            continue
+        for r in rules_pair:
+            if r not in declared_set:
+                errors.append(f"pair `{pid}` references undeclared rule `{r}`")
+
+        if pair["relation"] not in ALLOWED_RELATIONS:
+            errors.append(
+                f"pair `{pid}` relation `{pair['relation']}` not in {sorted(ALLOWED_RELATIONS)}"
+            )
+
+        evidence = pair.get("evidence") or []
+        if not isinstance(evidence, list) or not evidence:
+            errors.append(f"pair `{pid}` evidence must be a non-empty list")
+        for citation in evidence:
+            if not isinstance(citation, str):
+                errors.append(f"pair `{pid}` evidence item not a string: {citation!r}")
+                continue
+            file_part = citation.split("#", 1)[0]
+            if not (ROOT / file_part).exists():
+                errors.append(f"pair `{pid}` evidence path does not exist: {file_part}")
+
+        # Anchor coverage check
+        if ANCHOR_RULE in rules_pair:
+            partner = next((r for r in rules_pair if r != ANCHOR_RULE), None)
+            if partner in ANCHOR_PARTNERS:
+                anchor_partners_seen.add(partner)
+
+    missing_anchors = ANCHOR_PARTNERS - anchor_partners_seen
+    if missing_anchors:
+        errors.append(
+            f"anchor pairs missing for `{ANCHOR_RULE}` × {sorted(missing_anchors)} "
+            "(required by road-to-post-pr29-optimize.md P2.2)"
+        )
+
+    if errors:
+        fail(errors)
+
+    print(f"✅  rule-interactions.yml clean — {len(declared_rules)} rules, {len(pairs)} pairs.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/memory_lookup.py

@@ -246,7 +246,7 @@ def _apply_conflict_rule(
 # says retrieval should route through `@event4u/agent-memory`. The package
 # CLI is purely **semantic** (`memory retrieve <query> --type T …`); the
 # shared `retrieve(types, keys, …)` API is **key-based**. The hybrid
-# resolution agreed in `agents/contexts/agent-memory-contract.md` synthesises
+# resolution agreed in `docs/contracts/agent-memory-contract.md` synthesises
 # `keys` into a single natural-language query for the package call, while
 # the file fallback continues to do glob/substring matching on the same
 # keys. Both legs land in the same `Hit` shape so the conflict rule can

package/scripts/release.py

@@ -20,10 +20,13 @@ Pipeline:
                            push the tag (this triggers publish-npm.yml).
     9. GitHub Release    — `gh release create X.Y.Z --notes <changelog>`.
 
-Idempotency is intentionally limited: this script mutates git state, so
-re-running after a partial failure needs a clean tree. Each step prints
-what it's about to do before doing it, so a crash leaves a recoverable
-trail.
+Idempotency: pass `--resume` to recover from a partial failure. Each
+step then probes existing state (branch, commit, PR, tag, GitHub
+Release) and skips work that is already done, instead of erroring out.
+Without `--resume` the pipeline still mutates git/network state, so
+re-running on a dirty tree needs `--resume` (or a manual cleanup).
+Each step prints what it's about to do before doing it, so a crash
+leaves a recoverable trail.
 
 Stdlib-only (Python 3.10+). No third-party runtime dependencies.
 """
@@ -183,6 +186,61 @@ def have(bin: str) -> bool:
     )
 
 
+# ─── resume-mode state probes ────────────────────────────────────────────────
+
+
+def _branch_exists_local(branch: str) -> bool:
+    r = run(
+        "git", "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}",
+        check=False, capture=True,
+    )
+    return r.returncode == 0
+
+
+def _branch_exists_remote(branch: str) -> bool:
+    r = run(
+        "git", "ls-remote", "--exit-code", "--heads", REMOTE, branch,
+        check=False, capture=True,
+    )
+    return r.returncode == 0
+
+
+def _tag_exists_local(tag: str) -> bool:
+    return tag in git("tag", "-l", tag, capture=True).splitlines()
+
+
+def _tag_exists_remote(tag: str) -> bool:
+    r = run(
+        "git", "ls-remote", "--exit-code", "--tags", REMOTE, tag,
+        check=False, capture=True,
+    )
+    return r.returncode == 0
+
+
+def _pr_for_branch(branch: str) -> dict | None:
+    """Most recent PR (any state) with `release/X.Y.Z` as head, or None."""
+    r = run(
+        "gh", "pr", "list",
+        "--head", branch,
+        "--state", "all",
+        "--json", "number,state,url",
+        "--limit", "1",
+        check=False, capture=True,
+    )
+    if r.returncode != 0:
+        return None
+    try:
+        items = json.loads(r.stdout or "[]")
+    except json.JSONDecodeError:
+        return None
+    return items[0] if items else None
+
+
+def _release_exists(tag: str) -> bool:
+    r = run("gh", "release", "view", tag, check=False, capture=True)
+    return r.returncode == 0
+
+
 # ─── version math ─────────────────────────────────────────────────────────────
 
 
@@ -353,8 +411,21 @@ def set_marketplace_version(path: Path, version: str) -> None:
 # ─── preflight ────────────────────────────────────────────────────────────────
 
 
-def preflight(target: str) -> None:
-    """Fail fast on conditions that would break the release mid-flight."""
+def preflight(target: str, *, resume: bool = False) -> None:
+    """Fail fast on conditions that would break the release mid-flight.
+
+    In ``--resume`` mode two invariants are relaxed:
+
+    * The starting branch may be ``release/{target}`` in addition to
+      ``main`` — both are valid resume positions (mid-pipeline crash
+      after step 1 leaves you on the release branch).
+    * The target-tag-exists check is dropped — execute() probes for
+      existing tags/releases and skips them.
+
+    Tree cleanliness, gh auth, and ``main`` in-sync with origin are
+    still enforced, so resuming has the same starting posture as a
+    fresh run; only step-level outcomes differ.
+    """
     for b in ("git", "gh"):
         if not have(b):
             die(f"{b!r} not found on PATH")
@@ -368,7 +439,14 @@ def preflight(target: str) -> None:
         die("gh is not authenticated; run `gh auth login` first")
 
     branch = git("rev-parse", "--abbrev-ref", "HEAD", capture=True)
-    if branch != MAIN_BRANCH:
+    release_branch = f"release/{target}"
+    allowed = {MAIN_BRANCH, release_branch} if resume else {MAIN_BRANCH}
+    if branch not in allowed:
+        if resume:
+            die(
+                f"resume must run from {MAIN_BRANCH!r} or {release_branch!r}, "
+                f"currently on {branch!r}"
+            )
         die(f"release must run from {MAIN_BRANCH!r}, currently on {branch!r}")
 
     porcelain = git("status", "--porcelain", capture=True)
@@ -380,17 +458,24 @@ def preflight(target: str) -> None:
     # about to create a new tag anyway — local drift (e.g. from renamed
     # release-please tags) should not block the fetch.
     run("git", "fetch", REMOTE, "--tags", "--prune", "--force", capture=True)
-    local = git("rev-parse", "HEAD", capture=True)
-    remote = git("rev-parse", f"{REMOTE}/{MAIN_BRANCH}", capture=True)
-    if local != remote:
-        die(
-            f"local {MAIN_BRANCH} is not in sync with {REMOTE}/{MAIN_BRANCH}; "
-            "pull or push first"
-        )
 
-    tags = git("tag", "-l", target, capture=True).splitlines()
-    if target in tags:
-        die(f"tag {target!r} already exists; nothing to release")
+    # The local-in-sync-with-origin check only applies to main; if we're
+    # already on the release branch in resume mode, the relevant invariant
+    # is "main hasn't moved beyond what release/X.Y.Z branched off", which
+    # `git pull --ff-only` enforces in step 8 anyway.
+    if branch == MAIN_BRANCH:
+        local = git("rev-parse", "HEAD", capture=True)
+        remote = git("rev-parse", f"{REMOTE}/{MAIN_BRANCH}", capture=True)
+        if local != remote:
+            die(
+                f"local {MAIN_BRANCH} is not in sync with "
+                f"{REMOTE}/{MAIN_BRANCH}; pull or push first"
+            )
+
+    if not resume:
+        tags = git("tag", "-l", target, capture=True).splitlines()
+        if target in tags:
+            die(f"tag {target!r} already exists; nothing to release")
 
 
 # ─── plan ─────────────────────────────────────────────────────────────────────
@@ -436,7 +521,13 @@ def _step(n: int, total: int, msg: str) -> None:
     print(f"[{n}/{total}] {msg}")
 
 
-def execute(plan: Plan, *, wait_for_checks: bool, dry_run: bool) -> None:
+def execute(
+    plan: Plan,
+    *,
+    wait_for_checks: bool,
+    dry_run: bool,
+    resume: bool = False,
+) -> None:
     branch = f"release/{plan.target}"
     total = 9
 
@@ -444,57 +535,129 @@ def execute(plan: Plan, *, wait_for_checks: bool, dry_run: bool) -> None:
         print("(dry-run) no git/gh mutations will be performed.")
         return
 
-    _step(1, total, f"Create branch {branch}")
-    run("git", "checkout", "-b", branch)
-
-    _step(2, total, "Bump package.json + marketplace.json, prepend CHANGELOG")
-    set_package_version(PACKAGE_JSON, plan.target)
-    set_marketplace_version(MARKETPLACE_JSON, plan.target)
-    prepend_changelog(CHANGELOG, plan.changelog_entry)
-
-    _step(3, total, f"Commit `release: {plan.target}`")
-    run("git", "add", str(PACKAGE_JSON), str(MARKETPLACE_JSON), str(CHANGELOG))
-    run("git", "commit", "-m", f"release: {plan.target}")
-
-    _step(4, total, f"Push {branch} to {REMOTE}")
-    run("git", "push", "-u", REMOTE, branch)
+    # Probe the world once at the top so each step skip-decision is cheap.
+    pr_info = _pr_for_branch(branch) if resume else None
+    pr_state = (pr_info or {}).get("state")
+    pr_merged = pr_state == "MERGED"
+
+    # ─── 1. branch ──────────────────────────────────────────────────────────
+    if pr_merged:
+        _step(1, total, f"PR for {branch} already merged — staying on {MAIN_BRANCH}")
+        if git("rev-parse", "--abbrev-ref", "HEAD", capture=True) != MAIN_BRANCH:
+            run("git", "checkout", MAIN_BRANCH)
+        run("git", "pull", "--ff-only", REMOTE, MAIN_BRANCH)
+    elif resume and _branch_exists_local(branch):
+        _step(1, total, f"Branch {branch} exists locally — checkout")
+        run("git", "checkout", branch)
+    elif resume and _branch_exists_remote(branch):
+        _step(1, total, f"Branch {branch} exists on {REMOTE} — fetch + checkout")
+        run("git", "fetch", REMOTE, branch)
+        run("git", "checkout", "-b", branch, f"{REMOTE}/{branch}")
+    else:
+        _step(1, total, f"Create branch {branch}")
+        run("git", "checkout", "-b", branch)
 
-    _step(5, total, "Open pull request")
-    pr_body = (
-        f"Release {plan.target}.\n\n"
-        f"{plan.changelog_body}\n\n"
-        "Created by `scripts/release.py`."
-    )
-    run(
-        "gh", "pr", "create",
-        "--base", MAIN_BRANCH,
-        "--head", branch,
-        "--title", f"release: {plan.target}",
-        "--body", pr_body,
-    )
+    # ─── 2. file mutations ──────────────────────────────────────────────────
+    if pr_merged:
+        _step(2, total, "PR already merged — skip file bumps")
+    else:
+        current_pkg = json.loads(PACKAGE_JSON.read_text(encoding="utf-8")).get("version")
+        if resume and current_pkg == plan.target:
+            _step(2, total, f"Files already at {plan.target} — skip bump")
+        else:
+            _step(2, total, "Bump package.json + marketplace.json, prepend CHANGELOG")
+            set_package_version(PACKAGE_JSON, plan.target)
+            set_marketplace_version(MARKETPLACE_JSON, plan.target)
+            prepend_changelog(CHANGELOG, plan.changelog_entry)
+
+    # ─── 3. commit ──────────────────────────────────────────────────────────
+    if pr_merged:
+        _step(3, total, "PR already merged — skip commit")
+    else:
+        last_msg = git("log", "-1", "--format=%s", capture=True)
+        porcelain = git("status", "--porcelain", capture=True)
+        if resume and last_msg == f"release: {plan.target}" and not porcelain:
+            _step(3, total, f"Last commit already `release: {plan.target}` and tree clean — skip")
+        else:
+            _step(3, total, f"Commit `release: {plan.target}`")
+            run("git", "add", str(PACKAGE_JSON), str(MARKETPLACE_JSON), str(CHANGELOG))
+            run("git", "commit", "-m", f"release: {plan.target}")
+
+    # ─── 4. push ────────────────────────────────────────────────────────────
+    if pr_merged:
+        _step(4, total, "PR already merged — skip push")
+    else:
+        # `git push -u` is naturally idempotent — it prints "Everything
+        # up-to-date" when remote already matches. No probe needed.
+        _step(4, total, f"Push {branch} to {REMOTE}")
+        run("git", "push", "-u", REMOTE, branch)
+
+    # ─── 5. PR ──────────────────────────────────────────────────────────────
+    if pr_merged:
+        _step(5, total, f"PR #{pr_info.get('number')} already merged — skip")
+    elif resume and pr_state == "OPEN":
+        _step(5, total, f"PR already open: {pr_info.get('url')}")
+    else:
+        _step(5, total, "Open pull request")
+        pr_body = (
+            f"Release {plan.target}.\n\n"
+            f"{plan.changelog_body}\n\n"
+            "Created by `scripts/release.py`."
+        )
+        run(
+            "gh", "pr", "create",
+            "--base", MAIN_BRANCH,
+            "--head", branch,
+            "--title", f"release: {plan.target}",
+            "--body", pr_body,
+        )
 
-    if wait_for_checks:
+    # ─── 6. wait for checks ─────────────────────────────────────────────────
+    if pr_merged:
+        _step(6, total, "PR already merged — skip checks wait")
+    elif wait_for_checks:
         _step(6, total, "Wait for PR checks")
         watch_pr_checks()
     else:
         _step(6, total, "Skip waiting for checks (--no-wait)")
 
-    _step(7, total, "Merge pull request (merge commit) and delete branch")
-    run("gh", "pr", "merge", "--merge", "--delete-branch")
-
-    _step(8, total, f"Fast-forward {MAIN_BRANCH}, tag merge commit, push tag")
-    run("git", "checkout", MAIN_BRANCH)
+    # ─── 7. merge ───────────────────────────────────────────────────────────
+    if pr_merged:
+        _step(7, total, f"PR #{pr_info.get('number')} already merged — skip")
+    else:
+        _step(7, total, "Merge pull request (merge commit) and delete branch")
+        run("gh", "pr", "merge", "--merge", "--delete-branch")
+
+    # ─── 8. tag main + push tag ─────────────────────────────────────────────
+    # Always idempotent — even outside resume mode this prevents a mid-flight
+    # crash on step 9 from leaving a half-tagged release that subsequent
+    # `task release` invocations can't recover from without `--resume`.
+    if git("rev-parse", "--abbrev-ref", "HEAD", capture=True) != MAIN_BRANCH:
+        run("git", "checkout", MAIN_BRANCH)
     run("git", "pull", "--ff-only", REMOTE, MAIN_BRANCH)
-    run("git", "tag", plan.target)
-    run("git", "push", REMOTE, plan.target)
-
-    _step(9, total, "Create GitHub Release (triggers publish-npm on the tag)")
-    notes = plan.changelog_body or f"Release {plan.target}"
-    run(
-        "gh", "release", "create", plan.target,
-        "--title", plan.target,
-        "--notes", notes,
-    )
+
+    if _tag_exists_local(plan.target):
+        if _tag_exists_remote(plan.target):
+            _step(8, total, f"Tag {plan.target} already on {REMOTE} — skip")
+        else:
+            _step(8, total, f"Tag {plan.target} exists locally — push only")
+            run("git", "push", REMOTE, plan.target)
+    else:
+        _step(8, total, f"Tag merge commit and push {plan.target}")
+        run("git", "tag", plan.target)
+        run("git", "push", REMOTE, plan.target)
+
+    # ─── 9. GitHub Release ──────────────────────────────────────────────────
+    if _release_exists(plan.target):
+        _step(9, total, f"GitHub Release {plan.target} already exists — skip")
+    else:
+        _step(9, total, "Create GitHub Release (triggers publish-npm on the tag)")
+        notes = plan.changelog_body or f"Release {plan.target}"
+        run(
+            "gh", "release", "create", plan.target,
+            "--title", plan.target,
+            "--notes", notes,
+        )
 
     print()
     print(f"✅  Released {plan.target}")
@@ -535,6 +698,15 @@ def _parse_args(argv: list[str]) -> argparse.Namespace:
         "--no-wait", action="store_true",
         help="Merge immediately without waiting for PR checks to pass.",
     )
+    p.add_argument(
+        "--resume", action="store_true",
+        help=(
+            "Recover from a partial run. Each step probes existing state "
+            "(branch, commit, PR, tag, GitHub Release) and skips work that "
+            "is already done. Use this when an earlier `task release` "
+            "crashed mid-pipeline."
+        ),
+    )
     return p.parse_args(argv)
 
 
@@ -545,6 +717,49 @@ def resolve_bump(override: str | None, commits: list[Commit]) -> str:
     return infer_bump(commits)
 
 
+_RELEASE_BRANCH_RE = re.compile(r"^release/(\d+\.\d+\.\d+)$")
+
+
+def _detect_in_flight_target() -> str | None:
+    """Find the in-flight release target from existing release branches.
+
+    Resume mode needs to know which `release/X.Y.Z` is being recovered,
+    not what the next bump would be. The release branch name is the
+    canonical anchor: it was committed by step 1 of an earlier run and
+    is the only state guaranteed to survive a partial pipeline.
+
+    Local branches win over remote, current-branch wins over both — if
+    you ran `git checkout release/1.15.0`, that's the target. Returns
+    None if no release branch exists; caller falls back to the regular
+    bump-inference path.
+    """
+    head = git("rev-parse", "--abbrev-ref", "HEAD", capture=True)
+    m = _RELEASE_BRANCH_RE.match(head)
+    if m:
+        return m.group(1)
+
+    local_raw = git("for-each-ref", "--format=%(refname:short)", "refs/heads/release/", capture=True)
+    candidates = [
+        m.group(1)
+        for line in local_raw.splitlines()
+        if (m := _RELEASE_BRANCH_RE.match(line.strip()))
+    ]
+    remote_raw = git(
+        "for-each-ref", "--format=%(refname:short)",
+        f"refs/remotes/{REMOTE}/release/", capture=True,
+    )
+    for line in remote_raw.splitlines():
+        bare = line.strip().removeprefix(f"{REMOTE}/")
+        if (m := _RELEASE_BRANCH_RE.match(bare)):
+            candidates.append(m.group(1))
+
+    if not candidates:
+        return None
+    # Sort semver-aware so 1.10.0 > 1.9.0 (lexicographic would lose).
+    candidates.sort(key=parse_version)
+    return candidates[-1]
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _parse_args(list(sys.argv[1:] if argv is None else argv))
 
@@ -554,11 +769,22 @@ def main(argv: list[str] | None = None) -> int:
     prev = latest_tag()
     commits = commits_since(prev)
     bump = resolve_bump(args.bump_override, commits)
-    target = args.explicit or bump_version(current, bump)
+
+    # Resume mode: prefer an existing `release/X.Y.Z` over computed bump,
+    # so we don't accidentally start a 1.16.0 release while 1.15.0 is
+    # still in flight. Explicit --version still wins.
+    in_flight = _detect_in_flight_target() if args.resume else None
+    if args.explicit:
+        target = args.explicit
+    elif in_flight:
+        target = in_flight
+        print(f"(resume) detected in-flight release branch release/{in_flight}")
+    else:
+        target = bump_version(current, bump)
     parse_version(target)
 
     if not args.dry_run:
-        preflight(target)
+        preflight(target, resume=args.resume)
 
     today = _date.today().isoformat()
     full, body = render_changelog_entry(target, prev, commits, today)
@@ -572,6 +798,8 @@ def main(argv: list[str] | None = None) -> int:
         changelog_entry=full,
     )
     print_preview(plan)
+    if args.resume:
+        print("(resume) probing existing state — completed steps will be skipped.")
 
     if args.dry_run:
         return 0
@@ -580,7 +808,12 @@ def main(argv: list[str] | None = None) -> int:
         print("aborted.")
         return 1
 
-    execute(plan, wait_for_checks=not args.no_wait, dry_run=False)
+    execute(
+        plan,
+        wait_for_checks=not args.no_wait,
+        dry_run=False,
+        resume=args.resume,
+    )
     return 0
 
 

package/scripts/skill_linter.py

@@ -867,6 +867,20 @@ def lint_command(path: Path, text: str) -> LintResult:
         # suggestion block (road-to-context-aware-command-suggestion Phase 2)
         issues.extend(_lint_command_suggestion_block(text))
 
+        # deprecation-shim warning line (P0.8b — command-clusters contract)
+        if "superseded_by:" in frontmatter:
+            shim_warning = re.search(
+                r"⚠️\s+/[a-z][a-z0-9-]*\s+is deprecated;\s+use\s+/[a-z][a-z0-9 -]+\s+instead",
+                text,
+            )
+            if not shim_warning:
+                issues.append(Issue(
+                    "error", "shim_missing_warning",
+                    "Deprecation shim must contain a one-line warning matching "
+                    "'⚠️  /<old-name> is deprecated; use /<cluster> <sub> instead.'"
+                    " (see docs/contracts/command-clusters.md § Deprecation shim contract)"
+                ))
+
     # --- Structure checks ---
     if not H1_PATTERN.search(text):
         issues.append(Issue("error", "missing_h1", "Command is missing an H1 heading (# Title)"))

package/scripts/update_counts.py

@@ -72,6 +72,16 @@ TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
             (r"(Browse all )(\d+)( commands\])", "commands"),
         ],
     ),
+    (
+        "docs/architecture.md",
+        [
+            # "What's inside" table: | **Skills** | NNN | … |
+            (r"(\| \*\*Skills\*\* \| )(\d+)( \|)", "skills"),
+            (r"(\| \*\*Rules\*\* \| )(\d+)( \|)", "rules"),
+            (r"(\| \*\*Commands\*\* \| )(\d+)( \|)", "commands"),
+            (r"(\| \*\*Guidelines\*\* \| )(\d+)( \|)", "guidelines"),
+        ],
+    ),
     # Note: ``agents/roadmaps/road-to-stronger-skills.md`` was previously
     # tracked here with a living ``baseline N as of`` pattern. The roadmap
     # was moved to ``skipped/`` on 2026-04-23 (Q35 superseded), so its