@event4u/agent-config 1.14.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

@@ -157,6 +157,8 @@ ALLOWLIST = [
     r"agent-config",               # refers to the package concept, not a specific project
     r"shared.*package",            # "shared package" concept
     r"package repository",         # "package repository" concept
+    r"scripts/mcp_server/",        # MCP server module path (road-to-mcp-server.md Phase 1)
+    r"scripts\.mcp_server",        # MCP server Python module entrypoint
 ]
 
 # Directories to scan (only package files, not project-specific agents/)
@@ -248,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
@@ -465,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_public_links.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+Public-link checker for the agent-config public surface.
+
+Scans the public-surface files (README.md, AGENTS.md, docs/architecture.md)
+for markdown links into `docs/contracts/`, then validates each link against
+the `stability:` frontmatter declared by the target file (per
+`docs/contracts/STABILITY.md`).
+
+Rules:
+  - target stability=stable        → OK (no marker required).
+  - target stability=beta          → OK; warns if surrounding text has no
+                                     visible "(beta)" marker.
+  - target stability=experimental  → ERROR. Public surface MUST NOT link
+                                     to experimental contracts.
+  - target outside docs/contracts/ but referenced for contract-shaped
+    intent (links into agents/contexts/*.md from public files) → ERROR.
+  - target file missing            → ERROR.
+  - target file under docs/contracts/ without `stability:` frontmatter
+    (except STABILITY.md itself) → ERROR.
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+
+Usage:
+    python3 scripts/check_public_links.py
+    python3 scripts/check_public_links.py --list      # list contracts + levels
+    python3 scripts/check_public_links.py --json      # machine-readable
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PUBLIC_FILES = [Path("README.md"), Path("AGENTS.md"), Path("docs/architecture.md")]
+CONTRACTS_DIR = Path("docs/contracts")
+STABILITY_FILE = CONTRACTS_DIR / "STABILITY.md"
+
+LINK_RE = re.compile(r"\[(?P<text>[^\]]+)\]\((?P<href>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+STABILITY_RE = re.compile(r"^stability:\s*(\w+)\s*$", re.MULTILINE)
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    href: str
+    reason: str
+    severity: str  # "error" | "warning"
+
+
+def read_stability(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    txt = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(txt)
+    if not m:
+        return None
+    sm = STABILITY_RE.search(m.group(1))
+    return sm.group(1) if sm else None
+
+
+def collect_contracts() -> dict[Path, str | None]:
+    out: dict[Path, str | None] = {}
+    for p in sorted((ROOT / CONTRACTS_DIR).glob("*.md")):
+        rel = p.relative_to(ROOT)
+        out[rel] = read_stability(p)
+    return out
+
+
+def resolve(public_file: Path, href: str) -> Path | None:
+    href = href.split("#", 1)[0]
+    if not href or href.startswith(("http://", "https://", "mailto:", "tel:")):
+        return None
+    if href.startswith("/"):
+        return Path(href.lstrip("/"))
+    return (public_file.parent / href).resolve().relative_to(ROOT.resolve())
+
+
+def scan_file(public_file: Path, contracts: dict[Path, str | None]) -> list[Violation]:
+    abs_path = ROOT / public_file
+    if not abs_path.exists():
+        return []
+    violations: list[Violation] = []
+    for lineno, line in enumerate(abs_path.read_text(encoding="utf-8").splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            href = m.group("href")
+            text = m.group("text")
+            try:
+                target = resolve(public_file, href)
+            except ValueError:
+                continue
+            if target is None:
+                continue
+            if target.parts[:2] == ("agents", "contexts") and target.suffix == ".md":
+                violations.append(Violation(str(public_file), lineno, href,
+                    "public surface MUST NOT link into agents/contexts/ — move target to docs/contracts/",
+                    "error"))
+                continue
+            if target.parts[:2] != ("docs", "contracts") or target.suffix != ".md":
+                continue
+            if target == STABILITY_FILE:
+                continue
+            if target not in contracts:
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"target not found: {target}", "error"))
+                continue
+            level = contracts[target]
+            if level is None:
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"target missing 'stability:' frontmatter: {target}", "error"))
+                continue
+            if level == "experimental":
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"public surface MUST NOT link to experimental contract: {target}",
+                    "error"))
+                continue
+            if level == "beta":
+                window = line.lower()
+                if "(beta)" not in window and "[beta]" not in window:
+                    violations.append(Violation(str(public_file), lineno, href,
+                        f"link to beta contract '{target}' lacks visible (beta) marker",
+                        "warning"))
+    return violations
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--list", action="store_true", help="list contracts + stability levels")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    ap.add_argument("--strict", action="store_true",
+                    help="fail on warnings as well as errors (default: errors only)")
+    args = ap.parse_args()
+
+    contracts = collect_contracts()
+    if args.list:
+        for p, lvl in contracts.items():
+            print(f"  {lvl or '(no frontmatter)':14}  {p}")
+        return 0
+
+    missing_fm = [p for p, lvl in contracts.items() if lvl is None and p != STABILITY_FILE]
+    violations: list[Violation] = []
+    for p in missing_fm:
+        violations.append(Violation(str(p), 0, "(self)",
+            "missing 'stability:' frontmatter required by docs/contracts/STABILITY.md",
+            "error"))
+    for f in PUBLIC_FILES:
+        violations.extend(scan_file(f, contracts))
+
+    if args.json:
+        print(json.dumps([asdict(v) for v in violations], indent=2))
+    else:
+        errors = [v for v in violations if v.severity == "error"]
+        warnings = [v for v in violations if v.severity == "warning"]
+        for v in violations:
+            icon = "❌" if v.severity == "error" else "⚠️ "
+            loc = f"{v.file}:{v.line}" if v.line else v.file
+            print(f"{icon}  {loc}  {v.href}\n     → {v.reason}")
+        if not violations:
+            print(f"✅  public-link check clean — {len(contracts)} contracts scanned, "
+                  f"{len(PUBLIC_FILES)} public files clean")
+        else:
+            print(f"\nsummary: {len(errors)} error(s), {len(warnings)} warning(s)")
+
+    has_errors = any(v.severity == "error" for v in violations)
+    has_warnings = any(v.severity == "warning" for v in violations)
+    if has_errors:
+        return 1
+    if has_warnings and args.strict:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as e:
+        print(f"❌  internal error: {e}", file=sys.stderr)
+        sys.exit(3)

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/`.
@@ -78,6 +81,7 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"agents/overrides/"),           # override examples
     re.compile(r"commands/old-cmd"),            # example placeholder
     re.compile(r"agents/README"),               # README reference (may not exist in package)
+    re.compile(r"agents/index[\w.-]*\.md"),     # planned auto-generated artefact index (F5)
     re.compile(r"agents/docs/"),               # project-specific docs (not in package)
     re.compile(r"agents/contexts/"),           # project-specific contexts (not in package)
     re.compile(r"agents/gates"),               # project-specific policy docs