@event4u/agent-config 1.14.0 → 1.16.0

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/schemas/command.schema.json

@@ -28,6 +28,26 @@
         "pattern": "^[a-z][a-z0-9-]*$"
       }
     },
+    "cluster": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Locked verb cluster this command belongs to. See docs/contracts/command-clusters.md."
+    },
+    "sub": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Sub-command identifier within the cluster (e.g. `ci` for `/fix ci`)."
+    },
+    "superseded_by": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)?$",
+      "description": "Set on deprecation shims. Format: '<cluster> <sub>' (e.g. 'fix ci'). See docs/contracts/command-clusters.md § Deprecation shim contract."
+    },
+    "deprecated_in": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semver release in which this command became a shim (e.g. '1.15.0')."
+    },
     "suggestion": {
       "type": "object",
       "additionalProperties": false,

package/scripts/schemas/rule.schema.json

@@ -23,6 +23,16 @@
     "alwaysApply": {
       "type": "boolean",
       "description": "Optional sidecar for Cursor/Cline; by convention true when type=always, false when type=auto."
+    },
+    "load_context": {
+      "type": "array",
+      "items": {"type": "string", "pattern": "\\.md$"},
+      "description": "Lazy on-demand context references. Path rules and budget caps enforced by scripts/lint_load_context.py. Contract: docs/contracts/load-context-schema.md."
+    },
+    "load_context_eager": {
+      "type": "array",
+      "items": {"type": "string", "pattern": "\\.md$"},
+      "description": "Eager auto-loaded context references. Counts against the per-rule char budget; enforced by scripts/lint_load_context.py."
     }
   }
 }

package/scripts/skill_linter.py

@@ -136,9 +136,7 @@ def read_text(path: Path) -> str:
 # --- Role-contract anchor cache (see road-to-role-modes Phase 1) ---
 # Populated lazily so the linter stays fast when the guideline is absent.
 _ROLE_CONTRACT_CANDIDATES = (
-    Path(".agent-src.uncompressed/guidelines/agent-infra/role-contracts.md"),
-    Path(".agent-src/guidelines/agent-infra/role-contracts.md"),
-    Path(".augment/guidelines/agent-infra/role-contracts.md"),
+    Path("docs/guidelines/agent-infra/role-contracts.md"),
 )
 _ROLE_CONTRACT_SLUGS_CACHE: Optional[set[str]] = None
 
@@ -373,7 +371,8 @@ def lint_skill(path: Path, text: str) -> LintResult:
 
     if description:
         if len(description) > 200:
-            issues.append(Issue("warning", "description_too_long", "Description is longer than 200 characters"))
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
         for pattern in TRIGGER_WARNING_PATTERNS:
             if re.search(pattern, description, re.IGNORECASE):
                 issues.append(Issue("warning", "weak_trigger", f"Description looks too generic: {description}"))
@@ -716,6 +715,12 @@ def lint_rule(path: Path, text: str) -> LintResult:
             if not description:
                 issues.append(Issue("error", "auto_missing_description", "Auto rules require a 'description' field for matching"))
 
+        # description length cap (F6 — 200-char hard cap, see road-to-governance-cleanup)
+        rule_description = extract_description(text)
+        if rule_description and len(rule_description) > 200:
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(rule_description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
+
         # always-rules that look like auto candidates (rule-type-governance check)
         if rule_type == "always":
             description = extract_description(text) or ""
@@ -863,10 +868,27 @@ def lint_command(path: Path, text: str) -> LintResult:
         description = extract_description(text)
         if not description:
             issues.append(Issue("warning", "missing_description", "Frontmatter description is missing"))
+        elif len(description) > 200:
+            issues.append(Issue("error", "description_too_long",
+                                f"Description is {len(description)} chars (hard cap: 200) — see road-to-governance-cleanup F6"))
 
         # 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/sync_agent_settings.py

@@ -2,7 +2,7 @@
 """Sync `.agent-settings.yml` against the template + profile.
 
 Applies the section-aware merge rules documented in
-`.agent-src.uncompressed/guidelines/agent-infra/layered-settings.md`:
+`docs/guidelines/agent-infra/layered-settings.md`:
 
 - Template section order always wins — reorder keys to match.
 - Existing user scalar values are preserved verbatim (as parsed).

package/scripts/update_counts.py

@@ -28,8 +28,9 @@ def count(kind: str) -> int:
     if kind == "skills":
         return sum(1 for _ in (SRC / "skills").rglob("SKILL.md"))
     if kind == "guidelines":
-        # guidelines are grouped by topic subdirectory
-        return sum(1 for _ in (SRC / "guidelines").rglob("*.md"))
+        # Guidelines live under docs/guidelines/{topic}/ — they are reference
+        # material, not packaged artefacts. Recursive walk to count every .md.
+        return sum(1 for _ in (REPO_ROOT / "docs" / "guidelines").rglob("*.md"))
     if kind == "personas":
         # personas live as flat .md files, README excluded
         pdir = SRC / "personas"
@@ -47,12 +48,16 @@ TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
         [
             (r"(Browse all )(\d+)( commands\])", "commands"),
             (r"(package \(rules \+ )(\d+)( skills)", "skills"),
-            (r"(skills \+ )(\d+)( native commands)", "commands"),
             # Hero line: **NNN Skills** · **NNN Rules** · **NNN Commands** · **NNN Guidelines**
             (r"(<strong>)(\d+)( Skills</strong>)", "skills"),
             (r"(<strong>)(\d+)( Rules</strong>)", "rules"),
-            (r"(<strong>)(\d+)( Commands</strong>)", "commands"),
             (r"(<strong>)(\d+)( Guidelines</strong>)", "guidelines"),
+            # NOTE: hero `<strong>N Commands</strong>` and tools-blurb
+            # `skills + N native commands` are owned by
+            # `check_command_count_messaging.py` (Phase-1.2 of
+            # road-to-pr-34-followups). Those surfaces advertise the
+            # **active** command count (total − deprecation shims), not
+            # the raw file count this script computes.
         ],
     ),
     (
@@ -72,6 +77,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