@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/lint_featured_skills.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""CI guard for docs/featured-skills.md entry validity.
+
+Every artefact referenced from the three Featured tables (Founders &
+Consultants, Content Creators, Engineering Leads) MUST resolve in
+`dist/discovery/discovery-manifest.json`. Stale entries (renamed or
+removed skills / commands) fail the build.
+
+Detection:
+
+  - Scan `docs/featured-skills.md` for inline links of shape
+    `[`<token>`](../.agent-src/{skills|commands}/<path>.md)` inside the
+    Featured tables. Strip the `/` prefix on commands and the leading
+    slash on skill names.
+  - Cross-check each token against the manifest's `artefacts` array
+    (`category` in {`skill`, `command`} + `name` match, namespaced
+    commands like `video/from-script` → `video:from-script`).
+  - Verify `--pack <slug>` install hints reference packs that exist in
+    `manifest.packs[].id`.
+
+Exit codes:
+  0 — every entry resolves; install-pack hints are valid.
+  1 — at least one stale entry or unknown pack.
+
+Invocation:
+  python3 scripts/lint_featured_skills.py
+  python3 scripts/lint_featured_skills.py --quiet
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+DOC = Path("docs/featured-skills.md")
+MANIFEST = Path("dist/discovery/discovery-manifest.json")
+
+# Matches `[`token`](../.agent-src/skills/<slug>/SKILL.md)` or
+# `[`/token`](../.agent-src/commands/<path>.md)`. Captures (category, slug-path).
+LINK_RE = re.compile(
+    r"\[`/?[^`]+`\]\(\.\./\.agent-src/(skills|commands)/([^)]+?)\.md\)"
+)
+PACK_HINT_RE = re.compile(r"--pack\s+([a-z][a-z0-9-]*)")
+
+
+def load_manifest() -> dict:
+    if not MANIFEST.exists():
+        print(f"error: manifest not found at {MANIFEST}", file=sys.stderr)
+        sys.exit(1)
+    return json.loads(MANIFEST.read_text(encoding="utf-8"))
+
+
+def manifest_names(manifest: dict) -> tuple[set[str], set[str], set[str]]:
+    """Return (skill-names, command-names, pack-ids)."""
+    skills: set[str] = set()
+    commands: set[str] = set()
+    for art in manifest.get("artefacts", []):
+        cat = art.get("category")
+        name = art.get("name")
+        if not name:
+            continue
+        if cat == "skill":
+            skills.add(name)
+        elif cat == "command":
+            commands.add(name)
+    packs = {p.get("id") for p in manifest.get("packs", []) if p.get("id")}
+    return skills, commands, packs
+
+
+def slug_from_path(category: str, raw: str) -> str:
+    """Convert a doc-link path to the manifest `name` form.
+
+    skills/<slug>/SKILL  → <slug>
+    commands/<group>/<leaf>  → <group>:<leaf>
+    commands/<leaf>     → <leaf>
+    """
+    if category == "skills":
+        # raw looks like "<slug>/SKILL"; strip trailing /SKILL if present.
+        return raw.split("/", 1)[0]
+    # commands
+    parts = raw.split("/")
+    return ":".join(parts) if len(parts) > 1 else parts[0]
+
+
+def main() -> int:
+    quiet = "--quiet" in sys.argv
+    if not DOC.exists():
+        print(f"error: {DOC} not found", file=sys.stderr)
+        return 1
+
+    manifest = load_manifest()
+    skills, commands, packs = manifest_names(manifest)
+    body = DOC.read_text(encoding="utf-8")
+
+    missing: list[str] = []
+    seen: set[tuple[str, str]] = set()
+    for cat, raw in LINK_RE.findall(body):
+        slug = slug_from_path(cat, raw)
+        key = (cat, slug)
+        if key in seen:
+            continue
+        seen.add(key)
+        pool = skills if cat == "skills" else commands
+        if slug not in pool:
+            missing.append(f"  - {cat}/{slug} (linked path: ../.agent-src/{cat}/{raw}.md)")
+
+    unknown_packs: list[str] = []
+    for pack in PACK_HINT_RE.findall(body):
+        if pack not in packs:
+            unknown_packs.append(f"  - --pack {pack}")
+
+    if missing or unknown_packs:
+        print(f"FAIL  {DOC}: stale Featured Skills entries detected.")
+        if missing:
+            print("\nMissing artefacts (not in discovery-manifest.json):")
+            for line in missing:
+                print(line)
+        if unknown_packs:
+            print("\nUnknown pack ids referenced in install hints:")
+            for line in unknown_packs:
+                print(line)
+        print(
+            "\nFix: either restore the artefact, update the doc entry to a "
+            "current name, or substitute with the nearest existing artefact."
+        )
+        return 1
+
+    if not quiet:
+        print(
+            f"OK    {DOC}: {len(seen)} artefact entries + "
+            f"{len(set(PACK_HINT_RE.findall(body)))} pack hints validated."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_framework_leakage.py

@@ -33,11 +33,30 @@ from pathlib import Path
 from typing import Iterable
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-DEFAULT_PATHS = (
-    ".agent-src.uncompressed/skills",
-    ".agent-src.uncompressed/rules",
-    ".agent-src.uncompressed/commands",
-)
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+# Post-ADR-017 source artefacts live under every packages/*/.agent-src.uncompressed/;
+# pre-move the flat .agent-src.uncompressed/ root still wins. The lint walks
+# the three artefact subtrees (skills/, rules/, commands/) under each active root.
+_SUBDIRS = ("skills", "rules", "commands")
+
+
+def _default_paths() -> tuple[str, ...]:
+    out: list[str] = []
+    for root in artefact_roots():
+        try:
+            rel = root.relative_to(REPO_ROOT)
+        except ValueError:
+            continue
+        for sub in _SUBDIRS:
+            target = root / sub
+            if target.is_dir():
+                out.append((rel / sub).as_posix())
+    return tuple(out)
+
+
+DEFAULT_PATHS = _default_paths()
 ALLOWLIST_FILE = REPO_ROOT / "scripts/lint_framework_leakage_allowlist.json"
 
 CARVE_OUT_PATTERNS = [
@@ -185,8 +204,16 @@ def _load_allowlist() -> dict:
 
 
 def _allowlisted(rel_path: str, line_no: int, allowlist: dict) -> bool:
+    # Allowlist entries cite paths under the legacy .agent-src.uncompressed/
+    # prefix; post-ADR-017 files live under packages/*/.agent-src.uncompressed/.
+    # Match either the literal repo-relative path or its logical id.
+    from _lib.agent_src import strip_source_prefix  # noqa: E402
+
+    logical = strip_source_prefix(rel_path)
     for entry in allowlist.get("entries", []):
-        if entry.get("file") != rel_path:
+        entry_file = entry.get("file")
+        entry_logical = strip_source_prefix(entry_file) if isinstance(entry_file, str) else None
+        if entry_file != rel_path and (logical is None or entry_logical != logical):
             continue
         lines = entry.get("lines")
         if lines == "*":

package/scripts/lint_framework_leakage_allowlist.json

@@ -1,38 +1,29 @@
 {
   "version": 1,
-  "_doc": "Each entry: { file: relative path from repo root, lines: [int,...] | \"*\" for whole file, reason: short justification }. Use sparingly \u2014 first ask whether the file should be neutralized instead.",
+  "_doc": "Each entry: { file: relative path from repo root, lines: [int,...] | \"*\" for whole file, reason: short justification }. Use sparingly — first ask whether the file should be neutralized instead.",
   "entries": [
     {
       "file": ".agent-src.uncompressed/skills/using-git-worktrees/SKILL.md",
       "lines": [
-        130,
-        131,
-        132,
-        152
+        142,
+        143,
+        144,
+        164
       ],
       "reason": "Multi-stack package-manager comparison table"
     },
     {
       "file": ".agent-src.uncompressed/skills/refine-prompt/SKILL.md",
       "lines": [
-        88,
-        90,
-        92,
-        137,
-        180,
-        269
+        100,
+        102,
+        104,
+        149,
+        192,
+        281
       ],
       "reason": "Project-detection enumeration listing all supported stacks"
     },
-    {
-      "file": ".agent-src.uncompressed/commands/onboard.md",
-      "lines": [
-        220,
-        221,
-        224
-      ],
-      "reason": "Stack-detection enumeration in onboard flow"
-    },
     {
       "file": ".agent-src.uncompressed/commands/analyze-reference-repo.md",
       "lines": [
@@ -43,12 +34,12 @@
     {
       "file": ".agent-src.uncompressed/commands/optimize/augmentignore.md",
       "lines": "*",
-      "reason": "Per-stack augmentignore rules \u2014 by definition stack-aware"
+      "reason": "Per-stack augmentignore rules — by definition stack-aware"
     },
     {
       "file": ".agent-src.uncompressed/commands/optimize/rtk.md",
       "lines": "*",
-      "reason": "Per-tool rtk filter detection \u2014 by definition tool-aware"
+      "reason": "Per-tool rtk filter detection — by definition tool-aware"
     },
     {
       "file": ".agent-src.uncompressed/rules/framework-neutrality-in-generic-skills.md",
@@ -68,94 +59,94 @@
     {
       "file": ".agent-src.uncompressed/rules/architecture.md",
       "lines": [
-        19,
-        20,
-        26,
-        27,
-        62
+        31,
+        32,
+        38,
+        39,
+        74
       ],
       "reason": "Stack-routing pointers and cross-stack enumeration of validation/handler primitives"
     },
     {
       "file": ".agent-src.uncompressed/skills/api-endpoint/SKILL.md",
       "lines": [
-        41,
-        58
+        53,
+        70
       ],
       "reason": "Cross-stack validation primitive enumeration and pointer to laravel-api-endpoint carve-out"
     },
     {
       "file": ".agent-src.uncompressed/skills/code-review/SKILL.md",
       "lines": [
-        40,
-        41,
-        42,
-        49,
-        62,
-        63,
+        52,
+        53,
+        54,
+        61,
         74,
-        83,
-        85,
-        87,
-        219
+        75,
+        86,
+        95,
+        97,
+        99,
+        231
       ],
       "reason": "Cross-stack code-review checklist enumerates handler shape, validation, authz, ORM, escaping per framework"
     },
     {
       "file": ".agent-src.uncompressed/skills/security/SKILL.md",
       "lines": [
-        16,
-        23,
-        27,
         28,
-        37,
-        41,
-        48,
-        58,
-        76
+        35,
+        39,
+        40,
+        49,
+        53,
+        60,
+        70,
+        88
       ],
       "reason": "Cross-stack security review enumerates auth primitives (Policies, voters, guards, middleware) and config paths"
     },
     {
       "file": ".agent-src.uncompressed/skills/verify-completion-evidence/SKILL.md",
       "lines": [
-        53,
-        54,
-        55,
-        100,
-        177
+        65,
+        66,
+        67,
+        112,
+        189
       ],
       "reason": "Evidence-mapping table enumerates the type-checker / linter / refactor tool per stack including PHPStan, Rector, ECS"
     },
     {
       "file": ".agent-src.uncompressed/commands/tests/execute.md",
       "lines": "*",
-      "reason": "Multi-stack test runner dispatch (Pest/PHPUnit/Jest/pytest/cargo-test) \u2014 enumerates per-stack commands by design"
+      "reason": "Multi-stack test runner dispatch (Pest/PHPUnit/Jest/pytest/cargo-test) — enumerates per-stack commands by design"
     },
     {
       "file": ".agent-src.uncompressed/commands/tests/create.md",
       "lines": "*",
-      "reason": "Multi-stack test framework selection \u2014 enumerates Pest/PHPUnit/Jest/pytest options by design"
+      "reason": "Multi-stack test framework selection — enumerates Pest/PHPUnit/Jest/pytest options by design"
     },
     {
       "file": ".agent-src.uncompressed/commands/module/explore.md",
       "lines": "*",
-      "reason": "Multi-stack module detection (Laravel HMVC / Symfony bundles / DDD-lite) \u2014 enumerates per-stack patterns by design"
+      "reason": "Multi-stack module detection (Laravel HMVC / Symfony bundles / DDD-lite) — enumerates per-stack patterns by design"
     },
     {
       "file": ".agent-src.uncompressed/commands/package-test.md",
       "lines": "*",
-      "reason": "Multi-stack package linking (composer/npm/pip/cargo/go) \u2014 declared in skills frontmatter"
+      "reason": "Multi-stack package linking (composer/npm/pip/cargo/go) — declared in skills frontmatter"
     },
     {
       "file": ".agent-src.uncompressed/commands/package-reset.md",
       "lines": "*",
-      "reason": "Multi-stack package reset (composer/npm) \u2014 declared in skills frontmatter"
+      "reason": "Multi-stack package reset (composer/npm) — declared in skills frontmatter"
     },
     {
       "file": ".agent-src.uncompressed/skills/dependency-upgrade/SKILL.md",
       "lines": "*",
-      "reason": "Multi-stack dependency upgrade examples (composer/npm/pip) \u2014 declared stack-agnostic in description"
+      "reason": "Multi-stack dependency upgrade examples (composer/npm/pip) — declared stack-agnostic in description"
     },
     {
       "file": ".agent-src.uncompressed/skills/fe-design/SKILL.md",
@@ -175,7 +166,7 @@
     {
       "file": ".agent-src.uncompressed/commands/project-analyze.md",
       "lines": "*",
-      "reason": "Stack-detection templates show per-framework default outputs (Laravel/Standalone PHP/etc.) \u2014 multi-stack by design"
+      "reason": "Stack-detection templates show per-framework default outputs (Laravel/Standalone PHP/etc.) — multi-stack by design"
     },
     {
       "file": ".agent-src.uncompressed/commands/commit.md",
@@ -185,7 +176,7 @@
     {
       "file": ".agent-src.uncompressed/skills/test-driven-development/SKILL.md",
       "lines": "*",
-      "reason": "Multi-stack TDD examples \u2014 PHP/Pest and TypeScript/Jest sections both present"
+      "reason": "Multi-stack TDD examples — PHP/Pest and TypeScript/Jest sections both present"
     },
     {
       "file": ".agent-src.uncompressed/skills/context-authoring/SKILL.md",
@@ -220,7 +211,7 @@
     {
       "file": ".agent-src.uncompressed/skills/systematic-debugging/SKILL.md",
       "lines": "*",
-      "reason": "Debugging examples drawn from PHP project; the procedure is stack-agnostic (reproduce \u2192 isolate \u2192 hypothesize \u2192 verify)"
+      "reason": "Debugging examples drawn from PHP project; the procedure is stack-agnostic (reproduce → isolate → hypothesize → verify)"
     },
     {
       "file": ".agent-src.uncompressed/skills/testing-anti-patterns/SKILL.md",
@@ -325,7 +316,7 @@
     {
       "file": ".agent-src.uncompressed/commands/quality-fix.md",
       "lines": "*",
-      "reason": "Quality-fix dispatches per stack (PHPStan/ECS/Rector for PHP, tsc/biome for JS) \u2014 multi-stack by design"
+      "reason": "Quality-fix dispatches per stack (PHPStan/ECS/Rector for PHP, tsc/biome for JS) — multi-stack by design"
     },
     {
       "file": ".agent-src.uncompressed/commands/roadmap/create.md",
@@ -471,6 +462,16 @@
       "file": ".agent-src.uncompressed/commands/upstream-contribute.md",
       "lines": "*",
       "reason": "Upstream-contribute examples drawn from this package's own Laravel-tooling contributions"
+    },
+    {
+      "file": ".agent-src.uncompressed/skills/code-review/SKILL.md",
+      "lines": [235],
+      "reason": "Multi-stack formatter enumeration (ECS, Prettier, Ruff, gofmt) — comparative example, no project mandate"
+    },
+    {
+      "file": ".agent-src.uncompressed/rules/architecture.md",
+      "lines": [80],
+      "reason": "Multi-framework module-system enumeration (Laravel, Turborepo, NestJS, Go) — comparative example, no project mandate"
     }
   ]
 }

package/scripts/lint_ghostwriter_source.py

@@ -7,7 +7,7 @@ Two storage tiers exist (see docs/contracts/ghostwriter-schema.md):
     fictional fixtures ONLY (`fictional: true`). Every file stem must
     be on scripts/ghostwriter_fixture_allowlist.txt. `aliases:` is
     forbidden here (consumer-only feature).
-  * agents/ghostwriter/                    — consumer real-person
+  * agents/reference/ghostwriter/                    — consumer real-person
     profiles. Gitignored. Must NOT carry `fictional: true`. Optional
     `aliases:` list validated per § Aliases storage rules.
 

package/scripts/lint_global_paths.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Permissions-audit entry-gate for the global install tree.
+
+Phase 5.0 / amendment A7 of road-to-global-only-install. Runs BEFORE
+any legacy snapshot write so a perms leak cannot be created by the
+migration itself: `agent-config migrate-to-global` is expected to call
+this script first, abort on any failure, and only then proceed with
+the copy → verify → move → bridge sequence.
+
+Policy source: scripts/expected_perms.json (parameterised so the policy
+can evolve without code changes).
+
+Exit codes:
+    0  — all checks pass.
+    1  — at least one finding (printed to stdout, one finding per line).
+    2  — bad invocation (missing policy, JSON parse error, etc).
+
+Usage:
+    python3 scripts/lint_global_paths.py
+    python3 scripts/lint_global_paths.py --policy scripts/expected_perms.json
+    python3 scripts/lint_global_paths.py --quiet
+
+The script is intentionally read-only — no fixups, no chmod, no creates.
+The migration owns side effects.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+DEFAULT_POLICY = Path(__file__).resolve().parent / "expected_perms.json"
+
+
+def _expand(p: str) -> Path:
+    return Path(os.path.expanduser(p))
+
+
+def _mode_str(mode: int) -> str:
+    return f"0{stat.S_IMODE(mode):03o}"
+
+
+def _check_mode(path: Path, expected: str, kind: str) -> str | None:
+    """Return finding text or None when path is clean."""
+    if not path.exists():
+        return None  # missing optional paths are silent — checked by `required`
+    try:
+        actual = _mode_str(path.stat().st_mode)
+    except OSError as exc:
+        return f"{path}: stat failed ({exc})"
+    if actual != expected:
+        return f"{path}: {kind} mode {actual} (expected {expected})"
+    return None
+
+
+def _check_symlinks(root: Path) -> list[str]:
+    """All symlinks under `root` must resolve to paths still under `root`."""
+    findings: list[str] = []
+    if not root.exists():
+        return findings
+    root_resolved = root.resolve()
+    for entry in root.rglob("*"):
+        if not entry.is_symlink():
+            continue
+        try:
+            target = entry.resolve(strict=False)
+        except OSError as exc:
+            findings.append(f"{entry}: symlink resolve failed ({exc})")
+            continue
+        try:
+            target.relative_to(root_resolved)
+        except ValueError:
+            findings.append(f"{entry}: symlink escapes global root → {target}")
+    return findings
+
+
+def _check_glob(root: Path, glob: str, expected_mode: str, required: bool, kind: str) -> list[str]:
+    findings: list[str] = []
+    # Globs anchored at ~ are pre-expanded; reduce them to a root-relative pattern.
+    home = Path.home()
+    pattern_path = Path(os.path.expanduser(glob))
+    try:
+        rel = pattern_path.relative_to(home)
+    except ValueError:
+        rel = pattern_path
+    matches = list(home.glob(str(rel)))
+    if not matches and required:
+        findings.append(f"{glob}: required {kind} missing")
+        return findings
+    for match in matches:
+        finding = _check_mode(match, expected_mode, kind)
+        if finding:
+            findings.append(finding)
+    return findings
+
+
+def lint(policy_path: Path, quiet: bool = False) -> int:
+    try:
+        policy = json.loads(policy_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: policy load failed: {exc}", file=sys.stderr)
+        return 2
+
+    findings: list[str] = []
+
+    root_spec = policy.get("global_root") or {}
+    root_path = _expand(root_spec.get("path", "~/.event4u/agent-config"))
+    if root_path.exists():
+        finding = _check_mode(root_path, root_spec.get("expected_mode", "0700"), "directory")
+        if finding:
+            findings.append(finding)
+        findings.extend(_check_symlinks(root_path))
+
+    for spec in policy.get("files", []):
+        findings.extend(_check_glob(
+            root_path, spec["glob"], spec["expected_mode"],
+            spec.get("required", False), "file",
+        ))
+    for spec in policy.get("directories", []):
+        findings.extend(_check_glob(
+            root_path, spec["glob"], spec["expected_mode"],
+            spec.get("required", False), "directory",
+        ))
+
+    if not findings:
+        if not quiet:
+            print(f"✅ global paths clean ({root_path})")
+        return 0
+    for f in findings:
+        print(f"❌ {f}")
+    return 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--policy", type=Path, default=DEFAULT_POLICY)
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+    return lint(args.policy, quiet=args.quiet)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_load_context.py

@@ -3,7 +3,7 @@
 
 Validates per docs/contracts/load-context-schema.md:
   - Paths exist and are .md
-  - Allowed roots only (.agent-src*/contexts/, agents/contexts/)
+  - Allowed roots only (.agent-src*/contexts/, agents/settings/contexts/)
   - No public→project-local leak (warn)
   - No circular refs across lazy + eager edges
   - Combined char-budget for eager edges (rule + eager targets ≤ cap)
@@ -32,7 +32,7 @@ SCAN_DIRS = [
 ALLOWED_PREFIXES = (
     "contexts/",                               # logical name (canonical — P1.1 / P5.3)
     ".agent-src/contexts/",                    # projected (defensive — only seen in compressed inputs)
-    "agents/contexts/",                        # project-local
+    "agents/settings/contexts/",                        # project-local
 )
 
 # `.agent-src.uncompressed/contexts/` was the legacy fully-qualified form
@@ -48,7 +48,7 @@ LEGACY_PREFIX = ".agent-src.uncompressed/contexts/"
 SOURCE_ROOT = ROOT / ".agent-src.uncompressed"
 
 PUBLIC_RULE_PREFIX = ".agent-src.uncompressed/rules/"
-PROJECT_LOCAL_PREFIX = "agents/contexts/"
+PROJECT_LOCAL_PREFIX = "agents/settings/contexts/"
 
 
 def resolve_entry(entry: str) -> Path: