@event4u/agent-config 1.15.0 → 1.16.0

package/scripts/check_augmentignore.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+Advisory check for `.augmentignore` (road-to-governance-cleanup F6.3).
+
+Runs as part of `task ci` to surface `/optimize augmentignore` as a
+periodic reminder. Always exits 0 — this is a warn-only advisory, not
+a gate. Failures here never block CI.
+
+Checks performed:
+  1. Does `.augmentignore` exist at repo root?
+  2. Is its mtime older than 90 days? (stale reminder)
+  3. Is it suspiciously short (<5 non-blank, non-comment lines)?
+
+If any check trips, prints a friendly hint and exits 0. If all clean,
+prints a single-line OK and exits 0.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+STALE_DAYS = 90
+MIN_USEFUL_LINES = 5
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def check() -> int:
+    target = REPO_ROOT / ".augmentignore"
+    notes: list[str] = []
+
+    if not target.exists():
+        notes.append("⚠️  .augmentignore is missing — run `/optimize augmentignore` to scaffold it.")
+        _emit(notes)
+        return 0
+
+    age_days = (time.time() - target.stat().st_mtime) / 86400
+    if age_days > STALE_DAYS:
+        notes.append(
+            f"ℹ️  .augmentignore is {int(age_days)} days old (threshold: {STALE_DAYS}) — "
+            "consider running `/optimize augmentignore` to refresh."
+        )
+
+    useful = [
+        ln for ln in target.read_text().splitlines()
+        if ln.strip() and not ln.strip().startswith("#")
+    ]
+    if len(useful) < MIN_USEFUL_LINES:
+        notes.append(
+            f"ℹ️  .augmentignore has only {len(useful)} active entries — "
+            "run `/optimize augmentignore` to detect tech-stack ignores you may be missing."
+        )
+
+    _emit(notes)
+    return 0
+
+
+def _emit(notes: list[str]) -> None:
+    if not notes:
+        print("✅  .augmentignore advisory: nothing to suggest.")
+        return
+    print("📒  .augmentignore advisory (non-blocking):")
+    for n in notes:
+        print(f"    {n}")
+    print("    (This is a reminder, not a CI failure.)")
+
+
+if __name__ == "__main__":
+    sys.exit(check())

package/scripts/check_command_count_messaging.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Command-count messaging gate (regression guard for road-to-pr-34-followups 1.2).
+
+Public surfaces (README.md, AGENTS.md, docs/getting-started.md) advertise
+the size of the command catalog. PR #34 collapses atomic commands into
+clusters via deprecation shims — the externally meaningful number is the
+**active** command count (non-shim files), not the raw file count. This
+gate sources canonical counts from `.agent-src.uncompressed/commands/`
+frontmatter and fails when any documented number drifts from those.
+
+Canonical counts:
+    total   = number of *.md files under .agent-src.uncompressed/commands/
+    shims   = files whose frontmatter declares `superseded_by:`
+    active  = total - shims
+
+Patterns checked (per file):
+
+    README.md
+      hero row     "<strong>{N} Commands</strong>"            → active
+      browse line  "Browse all {N} active commands"           → active
+      browse meta  "{N} files total"                          → total
+      browse meta  "{N} are deprecation shims"                → shims
+      tools blurb  "{N} native commands"                      → active
+
+    AGENTS.md
+      tree         "commands/  ({N} files — {A} active + {S} deprecation shims)"
+
+    docs/getting-started.md
+      browse line  "Browse all {N} active commands"           → active
+
+Exit codes: 0 = clean, 1 = drift detected.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIR = ROOT / ".agent-src.uncompressed" / "commands"
+README = ROOT / "README.md"
+AGENTS = ROOT / "AGENTS.md"
+GETTING_STARTED = ROOT / "docs" / "getting-started.md"
+
+FM_RE = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+SUPERSEDED_RE = re.compile(r"^superseded_by:\s*\S", re.MULTILINE)
+
+
+def canonical_counts() -> tuple[int, int, int]:
+    if not COMMANDS_DIR.is_dir():
+        print(f"❌  {COMMANDS_DIR.relative_to(ROOT)} not found", file=sys.stderr)
+        sys.exit(1)
+    total = shims = 0
+    for f in COMMANDS_DIR.glob("*.md"):
+        total += 1
+        m = FM_RE.match(f.read_text(encoding="utf-8"))
+        fm = m.group(1) if m else ""
+        if SUPERSEDED_RE.search(fm):
+            shims += 1
+    return total, shims, total - shims
+
+
+def _check(path: Path, pattern: str, expected: int, label: str) -> str | None:
+    if not path.exists():
+        return f"missing file: {path.relative_to(ROOT)}"
+    m = re.search(pattern, path.read_text(encoding="utf-8"))
+    if not m:
+        return f"{path.relative_to(ROOT)}: pattern not found for `{label}` — /{pattern}/"
+    found = int(m.group(1))
+    if found != expected:
+        return f"{path.relative_to(ROOT)}: `{label}` says {found}, expected {expected}"
+    return None
+
+
+def main() -> int:
+    total, shims, active = canonical_counts()
+    print(f"Canonical counts: {total} files · {shims} shims · {active} active")
+
+    checks = [
+        # README.md
+        (README, r"<strong>(\d+) Commands</strong>", active, "hero row"),
+        (README, r"Browse all (\d+) active commands", active, "browse line"),
+        (README, r"\((\d+) files total ", total, "browse meta · total files"),
+        (README, r"— (\d+) are deprecation shims", shims, "browse meta · shims"),
+        (README, r"\+ (\d+) native commands\)", active, "tools blurb"),
+        # AGENTS.md (`commands/  (84 files — 69 active + 15 deprecation shims)`)
+        (AGENTS, r"commands/\s+\((\d+) files —", total, "tree · total files"),
+        (AGENTS, r"files — (\d+) active", active, "tree · active"),
+        (AGENTS, r"active \+ (\d+) deprecation shims", shims, "tree · shims"),
+        # docs/getting-started.md
+        (GETTING_STARTED, r"Browse all (\d+) active commands", active, "browse line"),
+    ]
+
+    errors: list[str] = []
+    for path, pattern, expected, label in checks:
+        err = _check(path, pattern, expected, label)
+        if err:
+            errors.append(err)
+
+    if not errors:
+        print("✅  All command-count messaging in sync with registry.")
+        return 0
+
+    print(f"❌  Command-count messaging drift — {len(errors)} mismatch(es):")
+    for e in errors:
+        print(f"    {e}")
+    print(
+        "\nFix: update the documented numbers above, or run "
+        "`task check-command-count` after editing."
+    )
+    print(
+        "Why this gate exists: see `agents/roadmaps/road-to-pr-34-followups.md` § 1.2."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_portability.py

@@ -250,6 +250,55 @@ def check_file(filepath: Path, patterns: list, allowlist: list) -> List[Violatio
     return violations
 
 
+# ── Identity-framing detector ───────────────────────────────────────────
+# The package's public identity surface (README, AGENTS, copilot-instructions)
+# must read stack-neutral. Laravel is the deepest reference stack today, never
+# the headline. This detector flags banned phrases that elevate any single
+# stack to identity status. Source-of-truth list lives in the
+# road-to-1-15-followups.md roadmap (P0 #1, F1.5).
+_IDENTITY_FRAMING_PATTERNS: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"\bLaravel-first\b", re.IGNORECASE), "identity-laravel-first"),
+    (re.compile(r"\bfor\s+PHP\s*/\s*Laravel\s+teams?\b", re.IGNORECASE), "identity-for-php-laravel-teams"),
+    (re.compile(r"\bfor\s+Laravel\s+teams?\b", re.IGNORECASE), "identity-for-laravel-teams"),
+    (re.compile(r"\bprimary\s+audience\s*[:=]\s*Laravel\b", re.IGNORECASE), "identity-primary-audience-laravel"),
+    (re.compile(r"\bbuilt\s+for\s+Laravel\b", re.IGNORECASE), "identity-built-for-laravel"),
+    (re.compile(r"\bLaravel\s*=\s*primary\b", re.IGNORECASE), "identity-laravel-equals-primary"),
+    (re.compile(r"\*\*Reference\s+implementation:\s*Laravel\.?\*\*", re.IGNORECASE), "identity-reference-implementation-laravel"),
+]
+
+# Files whose identity framing must stay stack-neutral. Relative to repo root.
+IDENTITY_SCAN_FILES = [
+    "README.md",
+    "AGENTS.md",
+    ".github/copilot-instructions.md",
+]
+
+
+def check_identity_framing(filepath: Path) -> List[Violation]:
+    """Flag banned identity-framing phrases in README / AGENTS / copilot-instructions.
+
+    The package presents itself as a universal governance system; any phrase
+    that pins identity to a single stack (Laravel-first, built for Laravel,
+    Reference implementation: Laravel as a bolded headline) is a regression.
+    """
+    violations: List[Violation] = []
+    try:
+        lines = filepath.read_text(encoding="utf-8").splitlines()
+    except Exception:
+        return violations
+
+    for i, line in enumerate(lines, 1):
+        for pattern, name in _IDENTITY_FRAMING_PATTERNS:
+            m = pattern.search(line)
+            if m:
+                violations.append(Violation(
+                    file=str(filepath), line=i, match=m.group(0),
+                    pattern_name=name, severity="error",
+                    context=line.strip(),
+                ))
+    return violations
+
+
 # ── Task-command detector ───────────────────────────────────────────────
 # Artefact files shipped in the package must not reference `task <name>`
 # invocations (per augment-portability rule). Consumer projects may not
@@ -467,6 +516,12 @@ def scan_all(root: Path) -> tuple[List[Violation], list[str]]:
                 if not any(path_str.endswith(skip) for skip in _CLI_DETECTOR_SKIP):
                     violations.extend(check_cli_invocations(f))
 
+    # Layer 5: identity-framing scan on the public identity surface
+    for rel in IDENTITY_SCAN_FILES:
+        f = root / rel
+        if f.is_file():
+            violations.extend(check_identity_framing(f))
+
     return violations, detected
 
 

package/scripts/check_public_catalog_links.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+Public-catalog link checker (regression guard for road-to-pr-34-followups 1.1).
+
+`docs/catalog.md` is the consumer-facing catalog rendered by
+`scripts/generate_index.py`. Consumers receive the package via npm /
+Composer / archive surfaces — `.agent-src.uncompressed/` is **not**
+shipped (see `package.json#files`). Every link in the public catalog
+must therefore resolve to a shipped surface.
+
+Checks:
+  1. No link href contains `.agent-src.uncompressed/`.
+  2. Every link href resolves on disk.
+  3. Every link href starts with a path declared in `package.json#files`
+     (or one of the always-shipped root files).
+
+Exit codes: 0 = clean, 1 = violations found.
+
+Usage:
+    python3 scripts/check_public_catalog_links.py
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CATALOG = ROOT / "docs" / "catalog.md"
+PACKAGE_JSON = ROOT / "package.json"
+
+LINK_RE = re.compile(r"\]\((?P<href>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
+FORBIDDEN_PREFIX = ".agent-src.uncompressed/"
+
+
+def _shipped_roots() -> tuple[set[str], set[str]]:
+    """Return (shipped_dirs, shipped_files) from package.json#files."""
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    dirs: set[str] = set()
+    files: set[str] = set()
+    for entry in data.get("files", []):
+        if entry.endswith("/"):
+            dirs.add(entry.rstrip("/"))
+        else:
+            files.add(entry)
+    return dirs, files
+
+
+def _resolve(href: str) -> Path | None:
+    href = href.split("#", 1)[0]
+    if not href or href.startswith(("http://", "https://", "mailto:", "tel:")):
+        return None
+    target = (CATALOG.parent / href).resolve()
+    try:
+        return target.relative_to(ROOT.resolve())
+    except ValueError:
+        return None
+
+
+def _under_shipped_surface(rel: Path, dirs: set[str], files: set[str]) -> bool:
+    s = str(rel)
+    if s in files:
+        return True
+    return any(s == d or s.startswith(d + "/") for d in dirs)
+
+
+def main() -> int:
+    if not CATALOG.exists():
+        print(f"❌  {CATALOG.relative_to(ROOT)} not found")
+        return 1
+
+    dirs, files = _shipped_roots()
+    text = CATALOG.read_text(encoding="utf-8")
+
+    forbidden: list[tuple[int, str]] = []
+    missing: list[tuple[int, str]] = []
+    unshipped: list[tuple[int, str]] = []
+
+    for lineno, line in enumerate(text.splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            href = m.group("href")
+            if FORBIDDEN_PREFIX in href:
+                forbidden.append((lineno, href))
+                continue
+            rel = _resolve(href)
+            if rel is None:
+                continue  # external / non-resolvable
+            if not (ROOT / rel).exists():
+                missing.append((lineno, href))
+                continue
+            if not _under_shipped_surface(rel, dirs, files):
+                unshipped.append((lineno, href))
+
+    total_violations = len(forbidden) + len(missing) + len(unshipped)
+    if not total_violations:
+        print(f"✅  docs/catalog.md — all links resolve to shipped surfaces.")
+        return 0
+
+    print(f"❌  docs/catalog.md — {total_violations} violation(s):")
+    if forbidden:
+        print(f"\n  {len(forbidden)} link(s) point at unshipped `.agent-src.uncompressed/`:")
+        for ln, href in forbidden[:10]:
+            print(f"    line {ln}: {href}")
+        if len(forbidden) > 10:
+            print(f"    … and {len(forbidden) - 10} more")
+    if missing:
+        print(f"\n  {len(missing)} link(s) do not resolve on disk:")
+        for ln, href in missing[:10]:
+            print(f"    line {ln}: {href}")
+    if unshipped:
+        print(f"\n  {len(unshipped)} link(s) point outside `package.json#files`:")
+        for ln, href in unshipped[:10]:
+            print(f"    line {ln}: {href}")
+    print("\nFix: update `scripts/generate_index.py` _to_shipped_path() / catalog renderer,")
+    print("then re-run `python3 scripts/generate_index.py`.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_references.py

@@ -32,7 +32,10 @@ class BrokenRef:
 
 
 SCAN_DIRS = [".agent-src", "agents"]
-SKIP_DIRS = ["agents/roadmaps/archive"]  # archived roadmaps have historical refs
+SKIP_DIRS = [
+    "agents/roadmaps/archive",  # archived roadmaps have historical refs
+    "agents/council-sessions",  # per-user audit trail (gitignored), captured provider output
+]
 ROOT = Path(".")
 
 # YAML memory files (engineering-memory layer) live under `agents/memory/`.

package/scripts/check_roadmap_trackable.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""CI guard for the `roadmap-progress-sync` rule's trackability Iron Law.
+
+Every non-draft file under `agents/roadmaps/` (excluding `archive/`,
+`skipped/`, template/README/open-questions) MUST:
+
+  1. Be parseable by the dashboard's `PHASE_RE` — i.e. contain at least
+     one `## Phase <id>` or `### Phase <id>` heading.
+  2. Have at least one trackable checkbox (`- [ ]`, `[x]`, `[~]`, `[-]`)
+     under every parsed phase.
+
+A roadmap that fails (1) is invisible to `agents/roadmaps-progress.md`
+and silently lies to the next reader. A phase that fails (2) shows as
+`⬜ empty` and contributes nothing to progress percentages.
+
+Both failure modes are rule violations per
+`.augment/rules/roadmap-progress-sync.md` § "Iron Law — every active
+roadmap is trackable". This script is the CI backstop so the rule
+cannot be quietly broken again.
+
+Exit codes:
+  0 — every active roadmap has parseable phases with at least one
+      checkbox per phase.
+  1 — at least one violation found; details printed to stdout.
+
+Invocation (from project root):
+  python3 scripts/check_roadmap_trackable.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Reuse the dashboard's regexes and helpers — single source of truth so
+# the linter cannot drift from what the dashboard actually parses.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / ".augment" / "scripts"))
+from update_roadmap_progress import (  # noqa: E402
+    CHECKBOX_RE,
+    PHASE_RE,
+    is_draft,
+    is_roadmap_candidate,
+    parse_frontmatter,
+)
+
+ROADMAP_ROOT = Path("agents/roadmaps")
+
+
+def find_active_roadmaps(root: Path) -> list[Path]:
+    """Return every non-draft roadmap candidate under root."""
+    out: list[Path] = []
+    for path in sorted(root.rglob("*.md")):
+        if not path.is_file() or not is_roadmap_candidate(path):
+            continue
+        text = path.read_text(encoding="utf-8")
+        if is_draft(parse_frontmatter(text)):
+            continue
+        out.append(path)
+    return out
+
+
+def violations_for(path: Path) -> list[str]:
+    """Return human-readable violation strings for a single roadmap."""
+    text = path.read_text(encoding="utf-8")
+    matches = list(PHASE_RE.finditer(text))
+    if not matches:
+        return [
+            f"{path}: no `## Phase <id>` or `### Phase <id>` heading "
+            "matched the dashboard's PHASE_RE — roadmap is invisible "
+            "to agents/roadmaps-progress.md. Either rename headings to "
+            "the canonical `Phase <id>` form or add `status: draft` to "
+            "the frontmatter."
+        ]
+    out: list[str] = []
+    for i, pm in enumerate(matches):
+        start = pm.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        if not CHECKBOX_RE.search(text[start:end]):
+            phase_id = pm.group(2)
+            name = (pm.group(3) or "").strip() or f"Phase {phase_id}"
+            out.append(
+                f"{path}: Phase {phase_id} ({name[:60]}) has zero "
+                "trackable checkboxes — add at least one `- [ ]` (or "
+                "`[x]`/`[~]`/`[-]`) item or remove the phase."
+            )
+    return out
+
+
+def main() -> int:
+    if not ROADMAP_ROOT.is_dir():
+        print(f"❌  {ROADMAP_ROOT} not found — run from project root.", file=sys.stderr)
+        return 1
+    findings: list[str] = []
+    for path in find_active_roadmaps(ROADMAP_ROOT):
+        findings.extend(violations_for(path))
+    if findings:
+        print("❌  Trackable-roadmap rule violations:\n")
+        for f in findings:
+            print(f"  - {f}")
+        print(
+            "\nRule: .augment/rules/roadmap-progress-sync.md "
+            '§ "Iron Law — every active roadmap is trackable"'
+        )
+        return 1
+    count = len(find_active_roadmaps(ROADMAP_ROOT))
+    print(f"✅  {count} active roadmap(s) — all parseable, all phases have checkboxes.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/command_suggester/cooldown.py

@@ -31,7 +31,7 @@ def is_explicit_slash_invocation(message: str) -> bool:
 
     Per the `command-suggestion` rule, explicit slash invocations
     bypass the suggestion layer entirely \u2014 they're handled by
-    `slash-commands` directly. The engine should not score in that
+    `slash-command-routing-policy` directly. The engine should not score in that
     case. Helper exposed for the runtime caller and the GT-CS4
     golden.
     """