@event4u/agent-config 1.15.0 → 1.16.0

package/scripts/generate_index.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Generate `agents/index.md` (internal) and `docs/catalog.md` (public).
+
+Scans `.agent-src.uncompressed/{skills,rules,commands}/` plus `docs/guidelines/`
+and renders two artefact tables — one for maintainers, one for consumers.
+
+Both files are sync-checked in CI via `--check`; drift = build break.
+
+Usage:
+    python3 scripts/generate_index.py            # write both files
+    python3 scripts/generate_index.py --check    # exit 1 if drift
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / ".agent-src.uncompressed"
+GUIDELINES = ROOT / "docs" / "guidelines"
+INDEX_PATH = ROOT / "agents" / "index.md"
+CATALOG_PATH = ROOT / "docs" / "catalog.md"
+
+# Internal-only rules — excluded from the public catalog.
+INTERNAL_RULES = {
+    "augment-source-of-truth",
+    "augment-portability",
+    "docs-sync",
+}
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class Entry:
+    kind: str          # skill | rule | command | shim | guideline
+    name: str
+    description: str
+    extra: str         # rule type · cluster · sub-folder, etc.
+    path: str          # repo-relative link target
+
+
+def _parse_frontmatter(text: str) -> dict[str, str]:
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    out: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" not in line or line.startswith(" "):
+            continue
+        k, _, v = line.partition(":")
+        out[k.strip()] = v.strip().strip('"').strip("'")
+    return out
+
+
+def _truncate(text: str, limit: int = 200) -> str:
+    text = text.replace("|", "\\|").replace("\n", " ").strip()
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def _collect_skills() -> list[Entry]:
+    out = []
+    for skill_dir in sorted((SRC / "skills").iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        fm = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+        name = fm.get("name") or skill_dir.name
+        out.append(Entry(
+            kind="skill",
+            name=name,
+            description=_truncate(fm.get("description", "")),
+            extra="",
+            path=f".agent-src.uncompressed/skills/{skill_dir.name}/SKILL.md",
+        ))
+    return out
+
+
+def _collect_rules() -> list[Entry]:
+    out = []
+    for rule_md in sorted((SRC / "rules").glob("*.md")):
+        fm = _parse_frontmatter(rule_md.read_text(encoding="utf-8"))
+        out.append(Entry(
+            kind="rule",
+            name=rule_md.stem,
+            description=_truncate(fm.get("description", "")),
+            extra=fm.get("type", "?"),
+            path=f".agent-src.uncompressed/rules/{rule_md.name}",
+        ))
+    return out
+
+
+def _collect_commands() -> list[Entry]:
+    out = []
+    for cmd_md in sorted((SRC / "commands").glob("*.md")):
+        fm = _parse_frontmatter(cmd_md.read_text(encoding="utf-8"))
+        is_shim = bool(fm.get("superseded_by"))
+        extra = ""
+        if is_shim:
+            extra = f"shim → /{fm['superseded_by']}"
+        elif fm.get("cluster"):
+            extra = f"cluster: {fm['cluster']}"
+        out.append(Entry(
+            kind="shim" if is_shim else "command",
+            name=fm.get("name") or cmd_md.stem,
+            description=_truncate(fm.get("description", "")),
+            extra=extra,
+            path=f".agent-src.uncompressed/commands/{cmd_md.name}",
+        ))
+    return out
+
+
+def _collect_guidelines() -> list[Entry]:
+    out = []
+    if not GUIDELINES.exists():
+        return out
+    for g_md in sorted(GUIDELINES.rglob("*.md")):
+        rel = g_md.relative_to(ROOT)
+        category = g_md.parent.name if g_md.parent != GUIDELINES else "(root)"
+        out.append(Entry(
+            kind="guideline",
+            name=g_md.stem,
+            description="",
+            extra=category,
+            path=str(rel),
+        ))
+    return out
+
+
+# Path rewriter for the public catalog: link to the shipped surface
+# (`.agent-src/`) instead of the source-of-truth (`.agent-src.uncompressed/`),
+# which is excluded from `package.json#files` and `composer.json` archives.
+def _to_shipped_path(path: str) -> str:
+    return path.replace(".agent-src.uncompressed/", ".agent-src/", 1)
+
+
+def _render_table(
+    entries: list[Entry],
+    cols: list[str],
+    link_prefix: str,
+    path_rewrite=None,
+) -> str:
+    rows = ["| " + " | ".join(cols) + " |", "|" + "|".join(["---"] * len(cols)) + "|"]
+    for e in entries:
+        path = path_rewrite(e.path) if path_rewrite else e.path
+        link = f"[`{e.name}`]({link_prefix}{path})"
+        row = [e.kind, link, e.extra, e.description]
+        rows.append("| " + " | ".join(row) + " |")
+    return "\n".join(rows)
+
+
+
+def _render_index(skills, rules, commands, guidelines) -> str:
+    total = len(skills) + len(rules) + len(commands) + len(guidelines)
+    parts = [
+        "# Agent-Config Internal Index",
+        "",
+        f"Maintainer-facing index of all **{total} artefacts** in this package.",
+        "Auto-generated from `.agent-src.uncompressed/` and `docs/guidelines/`.",
+        "",
+        "> **Regenerate:** `python3 scripts/generate_index.py`",
+        "> **Drift check:** `python3 scripts/generate_index.py --check` (runs in `task ci`)",
+        "> Do not edit manually.",
+        "",
+        f"## Skills ({len(skills)})",
+        "",
+        _render_table(skills, ["kind", "name", "extra", "description"], "../"),
+        "",
+        f"## Rules ({len(rules)})",
+        "",
+        _render_table(rules, ["kind", "name", "type", "description"], "../"),
+        "",
+        f"## Commands ({len(commands)})",
+        "",
+        _render_table(commands, ["kind", "name", "cluster/shim", "description"], "../"),
+        "",
+        f"## Guidelines ({len(guidelines)})",
+        "",
+        _render_table(guidelines, ["kind", "name", "category", "description"], "../"),
+        "",
+    ]
+    return "\n".join(parts)
+
+
+def _render_catalog(skills, rules, commands, guidelines) -> str:
+    public_rules = [r for r in rules if r.name not in INTERNAL_RULES]
+    public_commands = [c for c in commands if c.kind == "command"]
+    total = len(skills) + len(public_rules) + len(public_commands) + len(guidelines)
+    parts = [
+        "# agent-config — Public Catalog",
+        "",
+        f"Consumer-facing catalog of all **{total} public artefacts** shipped by",
+        "this package. Internal package-maintenance rules and deprecation shims",
+        "are excluded.",
+        "",
+        "> **Regenerate:** `python3 scripts/generate_index.py`",
+        "> Auto-generated — do not edit manually.",
+        "",
+        f"## Skills ({len(skills)})",
+        "",
+        _render_table(skills, ["kind", "name", "extra", "description"], "../", _to_shipped_path),
+        "",
+        f"## Rules ({len(public_rules)})",
+        "",
+        _render_table(public_rules, ["kind", "name", "type", "description"], "../", _to_shipped_path),
+        "",
+        f"## Commands ({len(public_commands)})",
+        "",
+        _render_table(public_commands, ["kind", "name", "cluster", "description"], "../", _to_shipped_path),
+        "",
+        f"## Guidelines ({len(guidelines)})",
+        "",
+        _render_table(guidelines, ["kind", "name", "category", "description"], "../", _to_shipped_path),
+        "",
+        "---",
+        "",
+        "← [Back to README](../README.md)",
+        "",
+    ]
+    return "\n".join(parts)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true",
+                        help="Exit 1 if generated content differs from on-disk files.")
+    args = parser.parse_args()
+
+    skills = _collect_skills()
+    rules = _collect_rules()
+    commands = _collect_commands()
+    guidelines = _collect_guidelines()
+
+    index_text = _render_index(skills, rules, commands, guidelines)
+    catalog_text = _render_catalog(skills, rules, commands, guidelines)
+
+    if args.check:
+        drift = []
+        if not INDEX_PATH.exists() or INDEX_PATH.read_text(encoding="utf-8") != index_text:
+            drift.append(str(INDEX_PATH.relative_to(ROOT)))
+        if not CATALOG_PATH.exists() or CATALOG_PATH.read_text(encoding="utf-8") != catalog_text:
+            drift.append(str(CATALOG_PATH.relative_to(ROOT)))
+        if drift:
+            print("❌  Index drift detected — regenerate with:")
+            print("    python3 scripts/generate_index.py")
+            for d in drift:
+                print(f"    - {d}")
+            return 1
+        print("✅  Index files in sync.")
+        return 0
+
+    INDEX_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CATALOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    INDEX_PATH.write_text(index_text, encoding="utf-8")
+    CATALOG_PATH.write_text(catalog_text, encoding="utf-8")
+    print(f"✅  Wrote {INDEX_PATH.relative_to(ROOT)} ({len(skills)} skills, "
+          f"{len(rules)} rules, {len(commands)} commands, {len(guidelines)} guidelines)")
+    print(f"✅  Wrote {CATALOG_PATH.relative_to(ROOT)} (public subset)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install_anthropic_key.sh

@@ -99,3 +99,8 @@ echo "✅  Key installed: ${TARGET_FILE} (mode 0600)."
 echo "    Verify:  ls -la ${TARGET_FILE}"
 echo "    Rotate:  rerun this script (you'll be prompted to overwrite)."
 echo "    Remove:  rm ${TARGET_FILE}"
+echo
+echo "ℹ️   Key install ≠ enable. To use this provider in /council:"
+echo "    set ai_council.enabled: true and ai_council.members.anthropic.enabled: true"
+echo "    in .agent-settings.yml. Council is a 'full' cost_profile feature; under"
+echo "    'minimal' / 'balanced' the runtime hooks stay inactive."

package/scripts/install_openai_key.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Interactive OpenAI-API-key installer for scripts/ai_council/clients.py.
+#
+# Reads the key with `read -s` so it never echoes to the terminal and
+# never lands in shell history or scrollback. Writes atomically to
+# ~/.config/agent-config/openai.key with mode 0600.
+#
+# Contract — companion to scripts/ai_council/clients.py:
+#   - File path:  $HOME/.config/agent-config/openai.key
+#   - File mode:  0600 (owner read/write only)
+#   - Key format: must start with `sk-`
+#   - No --force, no --yes, no env-var bypass. Piped stdin is rejected.
+#
+# The runner re-checks all of the above at every live invocation and
+# refuses to run if the file drifts from this contract.
+
+set -euo pipefail
+
+TARGET_DIR="${HOME}/.config/agent-config"
+TARGET_FILE="${TARGET_DIR}/openai.key"
+
+# ── controlling-terminal requirement ─────────────────────────────────────
+# We read from /dev/tty directly (fd 3), not from stdin. This is the
+# stricter and more portable contract:
+#   - works under `task`, `script`, `sudo`, anything that reattaches stdin
+#   - forces every character to come from the user's real keyboard, so a
+#     pipe or redirected file cannot smuggle the key into the process
+#   - exits cleanly if there is no controlling terminal at all (e.g. CI,
+#     cron, agent automation)
+if ! exec 3</dev/tty 2>/dev/null; then
+    echo "❌  install_openai_key.sh requires a controlling terminal." >&2
+    echo "    /dev/tty not available — refusing to run under automation." >&2
+    exit 2
+fi
+
+# ── overwrite confirmation ───────────────────────────────────────────────
+if [[ -e "${TARGET_FILE}" ]]; then
+    echo "⚠️   ${TARGET_FILE} already exists."
+    printf "Overwrite? [type 'yes' to replace, anything else aborts]: "
+    read -r -u 3 answer
+    if [[ "${answer}" != "yes" ]]; then
+        echo "Aborted. Existing key untouched."
+        exit 0
+    fi
+fi
+
+# ── read key (no echo, no history) ───────────────────────────────────────
+echo "Paste your OpenAI API key (input is hidden, no echo)."
+echo "The key should start with 'sk-'."
+printf "Key: "
+# -s = silent (no echo), read from fd 3 = /dev/tty, not stdin.
+read -r -s -u 3 API_KEY
+echo
+
+if [[ -z "${API_KEY}" ]]; then
+    echo "❌  Empty input — no file written." >&2
+    exit 2
+fi
+
+if [[ "${API_KEY}" != sk-* ]]; then
+    echo "❌  Input does not look like an OpenAI key (missing 'sk-' prefix)." >&2
+    echo "    No file written." >&2
+    exit 2
+fi
+
+# ── create config dir with 0700, atomic write with 0600 ──────────────────
+mkdir -p "${TARGET_DIR}"
+chmod 0700 "${TARGET_DIR}"
+
+TMP_FILE="$(mktemp "${TARGET_DIR}/.openai.key.XXXXXX")"
+cleanup() { rm -f "${TMP_FILE}"; }
+trap cleanup EXIT
+
+# chmod the tmpfile BEFORE writing the key, so there is no window where
+# the key sits on disk with group/other-readable permissions.
+chmod 0600 "${TMP_FILE}"
+printf '%s\n' "${API_KEY}" > "${TMP_FILE}"
+mv "${TMP_FILE}" "${TARGET_FILE}"
+trap - EXIT
+
+# Clear the variable and the `mv` positional argument — defence in depth
+# against a crash handler that dumps the process environment.
+API_KEY=""
+
+# ── verify mode post-write (portable stat: BSD on macOS, GNU on Linux) ───
+if ACTUAL_MODE=$(stat -f '%Lp' "${TARGET_FILE}" 2>/dev/null); then
+    :  # macOS / BSD
+else
+    ACTUAL_MODE=$(stat -c '%a' "${TARGET_FILE}")
+fi
+
+if [[ "${ACTUAL_MODE}" != "600" ]]; then
+    echo "❌  Permissions verification failed: ${TARGET_FILE} has mode ${ACTUAL_MODE}, expected 600." >&2
+    echo "    Delete and reinstall:  rm ${TARGET_FILE} && $0" >&2
+    exit 3
+fi
+
+echo "✅  Key installed: ${TARGET_FILE} (mode 0600)."
+echo "    Verify:  ls -la ${TARGET_FILE}"
+echo "    Rotate:  rerun this script (you'll be prompted to overwrite)."
+echo "    Remove:  rm ${TARGET_FILE}"
+echo
+echo "ℹ️   Key install ≠ enable. To use this provider in /council:"
+echo "    set ai_council.enabled: true and ai_council.members.openai.enabled: true"
+echo "    in .agent-settings.yml. Council is a 'full' cost_profile feature; under"
+echo "    'minimal' / 'balanced' the runtime hooks stay inactive."

package/scripts/lint_load_context.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Lint the `load_context:` / `load_context_eager:` frontmatter schema.
+
+Validates per docs/contracts/load-context-schema.md:
+  - Paths exist and are .md
+  - Allowed roots only (.agent-src*/contexts/, agents/contexts/)
+  - No public→project-local leak (warn)
+  - No circular refs across lazy + eager edges
+  - Combined char-budget for eager edges (rule + eager targets ≤ cap)
+
+Exits non-zero on error; warnings are reported but do not fail.
+Used in CI via `task lint-load-context`.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+
+SCAN_DIRS = [
+    ROOT / ".agent-src.uncompressed" / "rules",
+    ROOT / ".agent-src.uncompressed" / "contexts",
+    ROOT / "agents" / "contexts",
+]
+
+ALLOWED_PREFIXES = (
+    ".agent-src.uncompressed/contexts/",
+    ".agent-src/contexts/",
+    "agents/contexts/",
+)
+
+PUBLIC_RULE_PREFIX = ".agent-src.uncompressed/rules/"
+PROJECT_LOCAL_PREFIX = "agents/contexts/"
+
+HARD_FLOOR_RULES = {"non-destructive-by-default", "security-sensitive-stop"}
+
+CAP_ALWAYS = 2_500
+CAP_AUTO = 4_000
+CAP_SAFETY = 5_000
+
+
+def parse_frontmatter(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {}
+    try:
+        data = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def collect_files() -> Iterable[Path]:
+    for d in SCAN_DIRS:
+        if d.exists():
+            yield from d.rglob("*.md")
+
+
+def rel(p: Path) -> str:
+    return p.relative_to(ROOT).as_posix()
+
+
+def cap_for(rule_path: Path, fm: dict) -> int:
+    if rule_path.stem in HARD_FLOOR_RULES:
+        return CAP_SAFETY
+    rtype = (fm.get("type") or "").strip('"').strip("'")
+    if rtype == "always":
+        return CAP_ALWAYS
+    if rtype == "auto":
+        return CAP_AUTO
+    return CAP_AUTO  # default for non-rule contexts cited in eager (won't trigger)
+
+
+def find_cycles(graph: dict[str, list[str]]) -> list[list[str]]:
+    cycles: list[list[str]] = []
+    visiting: set[str] = set()
+    visited: set[str] = set()
+    stack: list[str] = []
+
+    def dfs(node: str) -> None:
+        if node in visiting:
+            i = stack.index(node)
+            cycles.append(stack[i:] + [node])
+            return
+        if node in visited:
+            return
+        visiting.add(node)
+        stack.append(node)
+        for nxt in graph.get(node, []):
+            dfs(nxt)
+        stack.pop()
+        visiting.discard(node)
+        visited.add(node)
+
+    for n in graph:
+        dfs(n)
+    return cycles
+
+
+def main() -> int:
+    errors: list[str] = []
+    warnings: list[str] = []
+    graph: dict[str, list[str]] = {}
+
+    for f in collect_files():
+        fm = parse_frontmatter(f)
+        lazy = fm.get("load_context") or []
+        eager = fm.get("load_context_eager") or []
+        if not (lazy or eager):
+            continue
+        if not isinstance(lazy, list) or not isinstance(eager, list):
+            errors.append(f"{rel(f)}: load_context* must be a list")
+            continue
+
+        edges = list(lazy) + list(eager)
+        graph[rel(f)] = edges
+
+        for entry in edges:
+            if not isinstance(entry, str) or not entry.endswith(".md"):
+                errors.append(f"{rel(f)}: entry not str ending in .md → {entry!r}")
+                continue
+            if not entry.startswith(ALLOWED_PREFIXES):
+                errors.append(f"{rel(f)}: disallowed root → {entry}")
+                continue
+            target = ROOT / entry
+            if not target.exists():
+                errors.append(f"{rel(f)}: target missing → {entry}")
+                continue
+            if rel(f).startswith(PUBLIC_RULE_PREFIX) and entry.startswith(PROJECT_LOCAL_PREFIX):
+                warnings.append(f"{rel(f)}: public rule references project-local context → {entry}")
+
+        if eager:
+            cap = cap_for(f, fm)
+            total = len(f.read_text(encoding="utf-8"))
+            for entry in eager:
+                tgt = ROOT / entry
+                if tgt.exists():
+                    total += len(tgt.read_text(encoding="utf-8"))
+            if total > cap:
+                errors.append(f"{rel(f)}: eager-load combined chars {total} > cap {cap}")
+
+    for cycle in find_cycles(graph):
+        errors.append("circular load_context: " + " → ".join(cycle))
+
+    for w in warnings:
+        print(f"⚠️  {w}")
+    for e in errors:
+        print(f"❌  {e}")
+    if errors:
+        return 1
+    print(f"✅  load_context schema clean ({len(graph)} declarer(s))")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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,6 +868,9 @@ 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))

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.
         ],
     ),
     (