@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/check_module_management_neutral.py

@@ -1,147 +0,0 @@
-#!/usr/bin/env python3
-"""Lint guard: ``module-management`` SKILL must stay framework-neutral.
-
-Phase C Step 5 of road-to-configurable-modules. Refuses two regressions:
-
-1. ``framework:`` frontmatter key is back (locks the skill to one stack
-   again).
-2. ``app/Modules/`` literal appears outside the explicitly-labeled
-   "Laravel HMVC carve-out" section (drift back to a Laravel-only body).
-
-Stack-specific paths inside their own carve-out sections (Laravel HMVC,
-Symfony DDD-lite, Node monorepo, Python src layout, Go internal) are
-allowed by construction \u2014 the section header is the carve-out boundary.
-
-Exit codes:
-    0 \u2014 file clean
-    2 \u2014 lint violation (regression)
-"""
-from __future__ import annotations
-
-import re
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent
-SKILL_PATH = (
-    REPO_ROOT
-    / "src"
-    / "skills"
-    / "module-management"
-    / "SKILL.md"
-)
-
-CARVE_OUT_HEADER = "### Laravel HMVC carve-out"
-FRONTMATTER_BANNED_KEYS = ("framework:",)
-BODY_BANNED_PATTERNS = (
-    re.compile(r"\bapp/Modules/"),
-    re.compile(r"App\\\\Modules\\\\"),
-)
-
-
-def _split_frontmatter(text: str) -> tuple[str, str]:
-    """Return ``(frontmatter, body)`` \u2014 body starts after closing ``---``."""
-    if not text.startswith("---\n"):
-        return "", text
-    end = text.find("\n---\n", 4)
-    if end < 0:
-        return "", text
-    return text[4:end], text[end + 5:]
-
-
-def _laravel_carveout_span(body: str) -> tuple[int, int] | None:
-    """Locate ``### Laravel HMVC carve-out`` and return ``(start, end)`` lines.
-
-    ``end`` is exclusive and points at the next ``### `` header (or EOF).
-    Returns ``None`` if the carve-out is missing.
-    """
-    lines = body.splitlines()
-    start: int | None = None
-    for idx, line in enumerate(lines):
-        if line.strip() == CARVE_OUT_HEADER:
-            start = idx
-            break
-    if start is None:
-        return None
-    end = len(lines)
-    for idx in range(start + 1, len(lines)):
-        if lines[idx].startswith("### "):
-            end = idx
-            break
-    return start, end
-
-
-def _scan_body(body: str) -> list[str]:
-    """Return human-readable violations from the SKILL body."""
-    span = _laravel_carveout_span(body)
-    if span is None:
-        return [
-            "Laravel HMVC carve-out section "
-            f"({CARVE_OUT_HEADER!r}) missing \u2014 add it back before "
-            "moving Laravel-specific prose around."
-        ]
-    carve_start, carve_end = span
-    lines = body.splitlines()
-    violations: list[str] = []
-    for idx, line in enumerate(lines):
-        if carve_start <= idx < carve_end:
-            continue
-        for pattern in BODY_BANNED_PATTERNS:
-            if pattern.search(line):
-                violations.append(
-                    f"line {idx + 1}: {pattern.pattern!r} outside the "
-                    "Laravel HMVC carve-out section "
-                    f"\u2014 {line.strip()!r}"
-                )
-                break
-    return violations
-
-
-def _scan_frontmatter(fm: str) -> list[str]:
-    violations: list[str] = []
-    for line in fm.splitlines():
-        stripped = line.strip()
-        for banned in FRONTMATTER_BANNED_KEYS:
-            if stripped.startswith(banned):
-                violations.append(
-                    f"frontmatter has banned key {banned!r} \u2014 "
-                    "module-management is stack-agnostic; "
-                    "stack hints live in body carve-outs"
-                )
-    return violations
-
-
-def main() -> int:
-    if not SKILL_PATH.is_file():
-        print(
-            f"error: SKILL.md not found at {SKILL_PATH}",
-            file=sys.stderr,
-        )
-        return 2
-    text = SKILL_PATH.read_text(encoding="utf-8")
-    fm, body = _split_frontmatter(text)
-    issues = _scan_frontmatter(fm) + _scan_body(body)
-    if not issues:
-        print(
-            f"\u2705  {SKILL_PATH.relative_to(REPO_ROOT)} "
-            "framework-neutral check: clean"
-        )
-        return 0
-    print(
-        f"\u274c  {SKILL_PATH.relative_to(REPO_ROOT)} "
-        "framework-neutral check: FAIL",
-        file=sys.stderr,
-    )
-    for issue in issues:
-        print(f"   {issue}", file=sys.stderr)
-    print(
-        "   Fix: keep stack-specific prose inside its labeled "
-        "carve-out section; do not put `framework:` back into "
-        "frontmatter.",
-        file=sys.stderr,
-    )
-    return 2
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/check_no_external_sources.py

@@ -1,101 +0,0 @@
-#!/usr/bin/env python3
-"""check_no_external_sources — block readable inspiration/harvest source names.
-
-Backstop for the source-confidentiality policy (rule: source-confidentiality;
-the 2026-06-13 sweep). Scans the **tracked** tree for a denylist of external
-inspiration / harvest / comparison source slugs so they cannot re-enter the
-repo by accident. Recommending an integrated tool is allowed; recording that
-we copied / derived / were-inspired-by a named external source is not.
-
-Carve-outs (see external_sources_denylist.json):
-- Vendored Apache/MIT code keeps its license-required attribution.
-- Recommendation/registry docs may name registries (Smithery/Glama).
-- A retained source link must be stored encrypted via
-  src/scripts/_lib/link_crypto.py, never in plaintext.
-
-Exit codes: 0 = clean, 1 = at least one denied token in a non-skipped tracked
-file, 2 = usage / config error.
-
-Usage:
-    python3 src/scripts/check_no_external_sources.py [--json]
-"""
-
-from __future__ import annotations
-
-import fnmatch
-import json
-import re
-import subprocess
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[2]
-CONFIG = Path(__file__).with_name("external_sources_denylist.json")
-# Scan only text-ish files; skip binaries / lockfiles / images.
-_SKIP_EXT = {
-    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".zip", ".gz",
-    ".woff", ".woff2", ".ttf", ".mp3", ".mp4", ".wav", ".lock",
-}
-
-
-def _tracked_files() -> list[str]:
-    out = subprocess.run(
-        ["git", "ls-files"], cwd=ROOT, capture_output=True, text=True, check=True
-    ).stdout
-    return [line for line in out.splitlines() if line]
-
-
-def _load_config() -> dict:
-    data = json.loads(CONFIG.read_text(encoding="utf-8"))
-    if not data.get("deny"):
-        raise SystemExit("config error: empty deny list")
-    return data
-
-
-def _skipped(path: str, skip_globs: list[str]) -> bool:
-    return any(fnmatch.fnmatch(path, g) for g in skip_globs)
-
-
-def main(argv: list[str]) -> int:
-    as_json = "--json" in argv
-    cfg = _load_config()
-    patterns = [(p, re.compile(p, re.IGNORECASE)) for p in cfg["deny"]]
-    skip_globs = cfg.get("skip_paths", [])
-
-    hits: list[dict] = []
-    for rel in _tracked_files():
-        if Path(rel).suffix.lower() in _SKIP_EXT:
-            continue
-        if _skipped(rel, skip_globs):
-            continue
-        try:
-            text = (ROOT / rel).read_text(encoding="utf-8", errors="replace")
-        except (OSError, IsADirectoryError):
-            continue
-        for lineno, line in enumerate(text.splitlines(), start=1):
-            for raw, rx in patterns:
-                if rx.search(line):
-                    hits.append({"file": rel, "line": lineno, "token": raw,
-                                 "text": line.strip()[:160]})
-
-    if as_json:
-        print(json.dumps({"ok": not hits, "hits": hits}, indent=2))
-    else:
-        if hits:
-            print(f"❌  {len(hits)} external-source reference(s) in the tracked tree:\n")
-            for h in hits:
-                print(f"  {h['file']}:{h['line']}  [{h['token']}]  {h['text']}")
-            print(
-                "\nThese name an external inspiration/harvest source. Remove the name,\n"
-                "or — if a real source link must be retained — encrypt it via\n"
-                "src/scripts/_lib/link_crypto.py. Legitimate carve-outs (vendored code,\n"
-                "registry recommendations) belong in external_sources_denylist.json\n"
-                "skip_paths. See rule: source-confidentiality."
-            )
-        else:
-            print("✅  No external inspiration-source references in the tracked tree.")
-    return 1 if hits else 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main(sys.argv[1:]))

package/src/scripts/check_no_local_settings_committed.py

@@ -1,51 +0,0 @@
-#!/usr/bin/env python3
-"""Fail if any ``.agent-settings.local.yml`` is tracked by git.
-
-`.agent-settings.local.yml` is the per-developer, per-machine override layer
-(see ``scripts/_lib/agent_settings.py`` ``LOCAL_PROJECT_FILE``). It is
-gitignored on purpose — committing one would leak one developer's local
-machine paths (e.g. linked-project siblings) into everyone's checkout.
-
-Exit 0 when none are tracked, 1 (with the offending paths) otherwise.
-"""
-
-from __future__ import annotations
-
-import subprocess
-import sys
-
-LOCAL_FILE = ".agent-settings.local.yml"
-
-
-def tracked_local_settings() -> list[str]:
-    try:
-        out = subprocess.run(
-            ["git", "ls-files"],
-            check=True,
-            capture_output=True,
-            text=True,
-        ).stdout
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        # Not a git repo / git missing — nothing to enforce here.
-        return []
-    return [
-        line
-        for line in out.splitlines()
-        if line.split("/")[-1] == LOCAL_FILE
-    ]
-
-
-def main() -> int:
-    offenders = tracked_local_settings()
-    if not offenders:
-        print(f"✅  No tracked {LOCAL_FILE} files.")
-        return 0
-    print(f"❌  {LOCAL_FILE} must never be committed (per-machine local layer):")
-    for path in offenders:
-        print(f"  🔴 {path}")
-    print(f"\nRun: git rm --cached <path>  — and confirm {LOCAL_FILE} is gitignored.")
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/check_no_new_legacy_path.py

@@ -1,100 +0,0 @@
-#!/usr/bin/env python3
-"""Regression guard: no NEW `.agent-src.uncondensed/` references in `src/`.
-
-`.agent-src.uncondensed/` is the dead pre-relocation source path (the source of
-truth moved to `src/`, ADR-051). Existing stale *prose* mentions in `src/` are
-fixed opportunistically — a large blind sweep was rejected by AI-council
-(2026-06-09): the path literal is also the *detection subject* of the reference
-linters, so a blanket rewrite is a loaded gun, and historical ADRs are correct
-as written. This guard stops the debt from *growing*: it fails when a diff
-**adds** a new `.agent-src.uncondensed/` line under `src/`.
-
-Three `src/` files legitimately contain the literal forever and are exempt:
-  - src/scripts/_lib/agent_src.py        (the LEGACY_SRC constant)
-  - src/scripts/check_references.py       (forbidden-substring detector)
-  - src/scripts/check_condensed_paths.py  (forbidden-substring detector)
-
-Diff-based: compares added lines against a base ref (default `origin/main`).
-On a clean checkout with no diff, it is a no-op (exit 0).
-
-Usage:  python3 src/scripts/check_no_new_legacy_path.py [--base <ref>]
-Exit:   0 = no new references, 1 = a new reference was added, 2 = internal error.
-"""
-from __future__ import annotations
-
-import subprocess
-import sys
-
-LEGACY = ".agent-src.uncondensed/"
-EXEMPT = {
-    "src/scripts/_lib/agent_src.py",
-    "src/scripts/check_references.py",
-    "src/scripts/check_condensed_paths.py",
-    "src/scripts/check_no_new_legacy_path.py",  # this file documents the literal
-}
-
-
-def _base() -> str:
-    for i, a in enumerate(sys.argv):
-        if a == "--base" and i + 1 < len(sys.argv):
-            return sys.argv[i + 1]
-    return "origin/main"
-
-
-def find_offenders(diff_text: str) -> list[str]:
-    """Added (`+`) lines under a non-exempt src/ file that introduce the legacy
-    path. Pure function over a unified-diff string — unit-testable."""
-    cur_file = None
-    offenders: list[str] = []
-    for line in diff_text.splitlines():
-        if line.startswith("+++ b/"):
-            cur_file = line[6:]
-            continue
-        if line.startswith("+") and not line.startswith("+++"):
-            # src/-scoped: a full diff (e.g. `gh pr diff`) carries every path;
-            # only added lines under src/ (minus the exempt detectors) count.
-            if (cur_file and cur_file.startswith("src/")
-                    and cur_file not in EXEMPT and LEGACY in line):
-                offenders.append(f"{cur_file}: {line[1:].strip()[:100]}")
-    return offenders
-
-
-def main() -> int:
-    # --stdin: read a unified diff from stdin (CI pipes `gh pr diff` — auth-safe,
-    # no `git fetch <base>` extraheader race on shallow PR-merge checkouts, the
-    # documented failure the kernel-bundle step sidesteps the same way).
-    if "--stdin" in sys.argv:
-        offenders = find_offenders(sys.stdin.read())
-    else:
-        base = _base()
-        # Two-dot diff: working tree vs base — catches committed + uncommitted
-        # additions (robust locally and where the working tree is the branch tip).
-        try:
-            diff = subprocess.run(
-                ["git", "diff", base, "--", "src/"],
-                capture_output=True, text=True, check=False,
-            )
-        except Exception as exc:  # pragma: no cover
-            print(f"❌  check_no_new_legacy_path: git diff failed: {exc}")
-            return 2
-        if diff.returncode not in (0, 1):
-            # base ref missing (shallow clone / detached) — degrade to no-op.
-            print(f"⚠️  check_no_new_legacy_path: base '{base}' unavailable; skipping (no-op).")
-            return 0
-        offenders = find_offenders(diff.stdout)
-
-    if offenders:
-        print("❌  New `.agent-src.uncondensed/` reference(s) added under src/ "
-              "(the source of truth is `src/` — ADR-051):")
-        for o in offenders:
-            print(f"  🔴 {o}")
-        print("\nFix: reference the real `src/` target. Existing stale prose is "
-              "migrated opportunistically; do not ADD new dead-path references.")
-        return 1
-
-    print("✅  No new `.agent-src.uncondensed/` references added under src/.")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/check_no_roadmap_refs.py

@@ -1,155 +0,0 @@
-#!/usr/bin/env python3
-"""No-roadmap-references checker.
-
-Stable artifacts (rules, skills, commands, contexts, guidelines, AGENTS.md,
-README, copilot-instructions) must NOT cite a specific roadmap file in
-`agents/roadmaps/`. Roadmap files are transient — archived, skipped, or
-deleted as work completes — and stable artifacts citing them rot.
-
-Allowed: directory mentions (`agents/roadmaps/`, `agents/roadmaps/archive/`,
-`agents/roadmaps/skipped/`). Forbidden: specific `*.md` files inside those
-directories.
-
-Contract: .agent-src.uncondensed/rules/no-roadmap-references.md
-
-Exit codes: 0 = clean, 1 = violations, 3 = internal error.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-from dataclasses import asdict, dataclass
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-
-# Stable artefact trees — every `*.md` below MUST be free of roadmap-file
-# citations. Directory mentions stay allowed (the regex below excludes them).
-STABLE_TREES = (
-    ".agent-src.uncondensed/rules",
-    ".agent-src.uncondensed/skills",
-    ".agent-src.uncondensed/commands",
-    ".agent-src.uncondensed/contexts",
-    ".agent-src.uncondensed/templates",
-    ".agent-src.uncondensed/personas",
-    "agents/settings/contexts",
-    "docs/guidelines",
-    "docs/contracts",
-)
-
-# Stable single-file artefacts at well-known paths.
-STABLE_FILES = (
-    "AGENTS.md",
-    "README.md",
-    "copilot-instructions.md",
-    "docs/architecture.md",
-    "docs/customization.md",
-    "docs/getting-started.md",
-    "docs/catalog.md",
-)
-
-# Roadmap-file pattern: any `*.md` file under `agents/roadmaps/` at any
-# depth (including `archive/`, `skipped/`, and nested topical subfolders
-# like `agent-memory/`). Directory-only mentions (`agents/roadmaps/`
-# with trailing slash, no filename) and placeholder mentions like
-# `agents/roadmaps/<file>.md` (angle-bracket placeholder) do NOT match.
-ROADMAP_FILE_RE = re.compile(
-    r"agents/roadmaps/(?:[a-z0-9][a-z0-9_-]*/)*[a-z0-9][a-z0-9_-]*\.md",
-    re.IGNORECASE,
-)
-
-# Files that may legitimately quote forbidden patterns inside backticks for
-# documentation purposes — the rule itself, the companion CI script docs,
-# and the contract doc that names the rule.
-SELF_DOCUMENTING_ALLOWLIST = frozenset({
-    ".agent-src.uncondensed/rules/no-roadmap-references.md",
-    "docs/guidelines/agent-infra/no-roadmap-references.md",
-})
-
-
-@dataclass
-class Violation:
-    file: str
-    line: int
-    match: str
-
-
-def _scan_file(path: Path, root: Path) -> list[Violation]:
-    rel = str(path.relative_to(root))
-    if rel in SELF_DOCUMENTING_ALLOWLIST:
-        return []
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
-        return []
-    out: list[Violation] = []
-    in_fence = False
-    for n, line in enumerate(text.splitlines(), start=1):
-        # Skip fenced code blocks — path listings inside ``` are functional
-        # constants (command contracts, runtime checks), not link rot.
-        stripped = line.lstrip()
-        if stripped.startswith("```"):
-            in_fence = not in_fence
-            continue
-        if in_fence:
-            continue
-        for m in ROADMAP_FILE_RE.finditer(line):
-            out.append(Violation(file=rel, line=n, match=m.group(0)))
-    return out
-
-
-def _collect_targets(root: Path) -> list[Path]:
-    targets: list[Path] = []
-    for d in STABLE_TREES:
-        base = root / d
-        if not base.exists():
-            continue
-        targets.extend(sorted(base.rglob("*.md")))
-    for f in STABLE_FILES:
-        p = root / f
-        if p.exists():
-            targets.append(p)
-    return targets
-
-
-def scan(root: Path) -> list[Violation]:
-    out: list[Violation] = []
-    for path in _collect_targets(root):
-        out.extend(_scan_file(path, root))
-    return out
-
-
-def format_text(violations: list[Violation]) -> str:
-    if not violations:
-        return "✅  No roadmap-file references in stable artifacts."
-    lines = [f"❌  Found {len(violations)} roadmap reference(s) in stable artifacts:\n"]
-    for v in violations:
-        lines.append(f"  🔴 {v.file}:{v.line}  →  {v.match}")
-    lines.append(
-        "\nPromote the durable conclusion to agents/settings/contexts/ and cite that "
-        "instead. See .agent-src.uncondensed/rules/no-roadmap-references.md."
-    )
-    return "\n".join(lines)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    parser.add_argument("--format", choices=["text", "json"], default="text")
-    parser.add_argument("--root", type=Path, default=ROOT)
-    args = parser.parse_args()
-    try:
-        violations = scan(args.root)
-    except Exception as e:    # pragma: no cover
-        print(f"Internal error: {e}", file=sys.stderr)
-        return 3
-    if args.format == "json":
-        print(json.dumps([asdict(v) for v in violations], indent=2))
-    else:
-        print(format_text(violations))
-    return 1 if violations else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/check_one_off_location.py

@@ -1,81 +0,0 @@
-#!/usr/bin/env python3
-"""One-off script-location guard (Phase 0a.2 of road-to-rule-hardening).
-
-Every ``_one_off_*.py`` script under ``scripts/`` must live inside the
-archive folder ``scripts/ai_council/one_off_archive/<YYYY-MM>/``. The
-guard fails CI if a new probe lands anywhere else in the tree.
-
-Rationale: one-off council probes / phase-specific measurements are
-inherently single-purpose; their durable artefact is the council
-session under ``agents/runtime/council/sessions/``. Keeping them in the
-archive prevents the ``scripts/`` root from accumulating noise and
-makes their lifecycle visible (folder == month archived).
-
-Exit codes:
-    0 = clean
-    1 = violation (script outside the archive)
-    3 = internal error
-"""
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent
-SCRIPTS = REPO_ROOT / "src" / "scripts"
-ARCHIVE = SCRIPTS / "ai_council" / "one_off_archive"
-ARCHIVE_MONTH_RE = re.compile(r"^\d{4}-\d{2}$")
-
-
-def find_violations() -> list[Path]:
-    """Return one-off scripts that are outside the archive folder."""
-    violations: list[Path] = []
-    for path in SCRIPTS.rglob("_one_off_*.py"):
-        if not path.is_file():
-            continue
-        # Must live under scripts/ai_council/one_off_archive/<YYYY-MM>/
-        try:
-            rel = path.relative_to(ARCHIVE)
-        except ValueError:
-            violations.append(path)
-            continue
-        # rel = "<YYYY-MM>/<name>.py"
-        parts = rel.parts
-        if len(parts) != 2 or not ARCHIVE_MONTH_RE.match(parts[0]):
-            violations.append(path)
-    return violations
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__.strip().splitlines()[0])
-    parser.add_argument("--quiet", action="store_true", help="Only print on failure")
-    args = parser.parse_args()
-
-    try:
-        violations = find_violations()
-    except Exception as exc:  # pragma: no cover — defensive
-        print(f"❌  internal error: {exc}", file=sys.stderr)
-        return 3
-
-    if violations:
-        print("❌  one-off scripts outside the archive:", file=sys.stderr)
-        for path in violations:
-            rel = path.relative_to(REPO_ROOT)
-            print(f"    {rel}", file=sys.stderr)
-        print(
-            "\n  Move them under "
-            "src/scripts/ai_council/one_off_archive/<YYYY-MM>/ "
-            "(see that folder's README.md).",
-            file=sys.stderr,
-        )
-        return 1
-
-    if not args.quiet:
-        print("✅  all _one_off_*.py scripts are archived")
-    return 0
-
-
-if __name__ == "__main__":  # pragma: no cover
-    sys.exit(main())