@event4u/agent-config 3.3.0 → 4.1.0

package/scripts/check_module_management_neutral.py

@@ -0,0 +1,149 @@
+#!/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
+SKILL_PATH = (
+    REPO_ROOT
+    / "packages"
+    / "core"
+    / ".agent-src.uncondensed"
+    / "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/scripts/check_no_roadmap_refs.py

@@ -10,7 +10,7 @@ Allowed: directory mentions (`agents/roadmaps/`, `agents/roadmaps/archive/`,
 `agents/roadmaps/skipped/`). Forbidden: specific `*.md` files inside those
 directories.
 
-Contract: .agent-src.uncompressed/rules/no-roadmap-references.md
+Contract: .agent-src.uncondensed/rules/no-roadmap-references.md
 
 Exit codes: 0 = clean, 1 = violations, 3 = internal error.
 """
@@ -28,12 +28,12 @@ ROOT = Path(__file__).resolve().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.uncompressed/rules",
-    ".agent-src.uncompressed/skills",
-    ".agent-src.uncompressed/commands",
-    ".agent-src.uncompressed/contexts",
-    ".agent-src.uncompressed/templates",
-    ".agent-src.uncompressed/personas",
+    ".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",
@@ -64,7 +64,7 @@ ROADMAP_FILE_RE = re.compile(
 # documentation purposes — the rule itself, the companion CI script docs,
 # and the contract doc that names the rule.
 SELF_DOCUMENTING_ALLOWLIST = frozenset({
-    ".agent-src.uncompressed/rules/no-roadmap-references.md",
+    ".agent-src.uncondensed/rules/no-roadmap-references.md",
     "docs/guidelines/agent-infra/no-roadmap-references.md",
 })
 
@@ -129,7 +129,7 @@ def format_text(violations: list[Violation]) -> str:
         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.uncompressed/rules/no-roadmap-references.md."
+        "instead. See .agent-src.uncondensed/rules/no-roadmap-references.md."
     )
     return "\n".join(lines)
 

package/scripts/check_portability.py

@@ -2,7 +2,7 @@
 """
 Portability checker for agent-config packages.
 
-Scans .agent-src/ and .agent-src.uncompressed/ for project-specific references
+Scans .agent-src/ and .agent-src.uncondensed/ for project-specific references
 that violate package portability (the package must work in ANY project).
 
 Allowed: references to packages/libraries (laravel, pest, phpstan, etc.)
@@ -162,7 +162,7 @@ ALLOWLIST = [
 ]
 
 # Directories to scan (only package files, not project-specific agents/)
-SCAN_DIRS = [".agent-src", ".agent-src.uncompressed"]
+SCAN_DIRS = [".agent-src", ".agent-src.uncondensed"]
 
 # Additional root-level files shipped by the package that must also stay
 # portable. These are read by agents working on the package itself and —
@@ -478,7 +478,7 @@ def scan_all(root: Path) -> tuple[List[Violation], list[str]]:
 
     Scanning has four layers:
     1. Auto-detected identifiers — applied to `.agent-src/` and
-       `.agent-src.uncompressed/` only. The package's own root AGENTS.md and
+       `.agent-src.uncondensed/` only. The package's own root AGENTS.md and
        copilot-instructions.md are meta docs ABOUT the package, so the
        detector's own hits (e.g. "event4u", "agent-config") are expected.
     2. Optional FORBIDDEN_IDENTIFIERS from AGENT_CONFIG_BLOCKLIST —

package/scripts/check_public_catalog_links.py

@@ -4,12 +4,12 @@ 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**
+Composer / archive surfaces — `.agent-src.uncondensed/` 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/`.
+  1. No link href contains `.agent-src.uncondensed/`.
   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).
@@ -34,7 +34,7 @@ CATALOG = ROOT / "docs" / "catalog.md"
 PACKAGE_JSON = ROOT / "package.json"
 
 LINK_RE = re.compile(r"\]\((?P<href>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
-FORBIDDEN_PREFIX = ".agent-src.uncompressed/"
+FORBIDDEN_PREFIX = ".agent-src.uncondensed/"
 
 
 def _shipped_roots() -> tuple[set[str], set[str]]:
@@ -103,7 +103,7 @@ def main() -> int:
 
     print(f"❌  docs/catalog.md — {total_violations} violation(s):")
     if forbidden:
-        print(f"\n  {len(forbidden)} link(s) point at unshipped `.agent-src.uncompressed/`:")
+        print(f"\n  {len(forbidden)} link(s) point at unshipped `.agent-src.uncondensed/`:")
         for ln, href in forbidden[:10]:
             print(f"    line {ln}: {href}")
         if len(forbidden) > 10:

package/scripts/check_references.py

@@ -39,6 +39,7 @@ SKIP_DIRS = [
     "agents/runtime/council/questions",  # design Q&A trail — forward-refs to planned artifacts
     "agents/evidence/analysis",           # plate-comparison working docs — forward-refs to planned artifacts
     "agents/runtime",            # volatile / machine-generated artefacts (gitignored)
+    "agents/tmp",                # transient working docs (gitignored) — pr-bodies, council questions, manual-step scratchpads
 ]
 
 # Per-file opt-out marker. When present in the first 10 lines of a .md
@@ -88,7 +89,7 @@ UNCHECKED_TODO_PATTERN = re.compile(r'^\s*[-*+]\s+\[[ ~]\]\s')
 _SKIP_NAMES = {"the", "a", "an", "this", "that", "your", "my", "no", "any", "each", "one",
                "always", "auto", "fail", "vue", "guidelines", "naming",
                "orderBy", "no-commit", "skill-linter", "skill-validator",
-               "skill-refactor", "skill-caveman-compression", "skill-decompression",
+               "skill-refactor", "skill-telegraph-condensation", "skill-decondensation",
                "broad_scope", "composer"}
 
 # Paths that are clearly example/template placeholders (not real references)
@@ -118,7 +119,7 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"skills/[\w-]+\.md"),          # short skill refs in examples (not SKILL.md path)
     re.compile(r"skills/[\w-]+/SKILL\.md"),    # example skill paths in commands
     re.compile(r"\{"),                         # template placeholders like {module}
-    re.compile(r"\.compression-hashes\.json"), # JSON file, not .md
+    re.compile(r"\.condensation-hashes\.json"), # JSON file, not .md
     re.compile(r"-foo\.(md|json|yml|yaml)$"),  # `-foo.<ext>` placeholder examples
     re.compile(r"-bar\.(md|json|yml|yaml)$"),  # `-bar.<ext>` placeholder examples
     # Forward references inside in-flight planning docs (road-to-
@@ -211,7 +212,7 @@ def _extract_personas_frontmatter(text: str) -> list[tuple[int, str]]:
 
 def _find_suggestion(path: str, root: Path) -> str:
     name = Path(path).name
-    for d in [root / ".agent-src", root / ".agent-src.uncompressed", root / "agents"]:
+    for d in [root / ".agent-src", root / ".agent-src.uncondensed", root / "agents"]:
         if d.exists():
             for f in d.rglob(name):
                 return str(f.relative_to(root))
@@ -313,18 +314,18 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
             else:
                 # Strip leading ./ and try with prefixes
                 ref = raw_ref.lstrip("./")
-                for prefix in [root, root / ".agent-src", root / ".agent-src.uncompressed"]:
+                for prefix in [root, root / ".agent-src", root / ".agent-src.uncondensed"]:
                     if (prefix / ref).exists():
                         resolved = True
                         break
                 # `.augment/` is a local projection of `.agent-src/` (gitignored).
                 # In CI the projection doesn't exist, so resolve `.augment/X`
                 # against the canonical source at `.agent-src/X` (and the
-                # uncompressed authoring tree as a fallback). Note: `raw_ref`
+                # uncondensed authoring tree as a fallback). Note: `raw_ref`
                 # keeps the leading dot; `ref` above was stripped via lstrip.
                 if not resolved and raw_ref.startswith(".augment/"):
                     rel = raw_ref[len(".augment/") :]
-                    for prefix in [root / ".agent-src", root / ".agent-src.uncompressed"]:
+                    for prefix in [root / ".agent-src", root / ".agent-src.uncondensed"]:
                         if (prefix / rel).exists():
                             resolved = True
                             break

package/scripts/check_release_pr_shape.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Release-PR shape checker — fail-closed gate for `docs/contracts/release-pr-gating.md`.
+
+Given a PR number, fetches the file list via `gh pr diff <n> --name-only`
+and asserts every changed file matches the version-bump allowlist:
+
+  * `package.json`
+  * `CHANGELOG.md`
+  * `.claude-plugin/marketplace.json`
+  * `packages/*/pack.yaml`
+  * `packages/*/README.md`
+
+Exit codes:
+
+  0 — every file matches; release-PR is shape-clean and the heavy install /
+      test matrices may skip per `release-pr-gating.md`.
+  1 — at least one file outside the allowlist OR no files at all. Stdout
+      lists each offending entry one per line with an "OUT-OF-SHAPE: " prefix
+      so CI logs surface the precise reason.
+  2 — usage / environment error (gh missing, invalid PR number, gh non-zero).
+
+Design constraints from the roadmap:
+
+  * stdlib-only — no jsonschema, no requests, no PyYAML
+  * ≤ 150 LOC including this docstring
+  * deterministic — same diff in, same exit
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import shutil
+import subprocess
+import sys
+
+ALLOWLIST_GLOBS = (
+    "package.json",
+    "CHANGELOG.md",
+    ".claude-plugin/marketplace.json",
+    "packages/*/pack.yaml",
+    "packages/*/README.md",
+)
+
+
+def _matches(path: str) -> bool:
+    return any(fnmatch.fnmatch(path, pat) for pat in ALLOWLIST_GLOBS)
+
+
+def _gh_diff_files(pr: str) -> list[str]:
+    """Return the list of files changed in `pr`, via `gh pr diff --name-only`."""
+    if shutil.which("gh") is None:
+        print("ERROR: gh CLI not on PATH; cannot fetch PR diff.", file=sys.stderr)
+        sys.exit(2)
+    try:
+        out = subprocess.run(
+            ["gh", "pr", "diff", pr, "--name-only"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or "").strip()
+        print(f"ERROR: gh pr diff {pr} failed: {stderr}", file=sys.stderr)
+        sys.exit(2)
+    return [line.strip() for line in out.splitlines() if line.strip()]
+
+
+def check(files: list[str]) -> int:
+    """Return exit code; print per-file diff to stdout on failure."""
+    if not files:
+        print("OUT-OF-SHAPE: empty diff — release PR must touch at least one file.")
+        return 1
+    bad = [f for f in files if not _matches(f)]
+    if bad:
+        for f in bad:
+            print(f"OUT-OF-SHAPE: {f}")
+        return 1
+    print(f"SHAPE-CLEAN: {len(files)} file(s) — all within release-PR allowlist.")
+    for f in files:
+        print(f"  ok: {f}")
+    return 0
+
+
+def _read_files_arg(value: str) -> list[str]:
+    """`--files` accepts comma-separated paths or `-` to read stdin (one per line)."""
+    if value == "-":
+        return [line.strip() for line in sys.stdin.read().splitlines() if line.strip()]
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Fail-closed shape checker for release PRs.",
+    )
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument("--pr", help="GitHub PR number; uses `gh pr diff --name-only`.")
+    src.add_argument(
+        "--files",
+        help=(
+            "Comma-separated file list, or '-' to read one path per line from "
+            "stdin. Bypasses gh — useful for tests and local previews."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    files = _gh_diff_files(args.pr) if args.pr else _read_files_arg(args.files)
+    return check(files)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_reply_consistency.py

@@ -99,11 +99,11 @@ def validate(text: str, strict: bool = False) -> tuple[int, str]:
 
 
 def cmd_scan_dir(root: Path) -> int:
-    # If the requested root is the legacy ".agent-src.uncompressed" and it
+    # If the requested root is the legacy ".agent-src.uncondensed" and it
     # no longer exists (post-monorepo-move), fall back to artefact_roots()
-    # so every packages/*/.agent-src.uncompressed/ is scanned.
+    # so every packages/*/.agent-src.uncondensed/ is scanned.
     if not root.is_dir():
-        legacy = ROOT / ".agent-src.uncompressed"
+        legacy = ROOT / ".agent-src.uncondensed"
         if root.resolve() == legacy.resolve():
             roots = artefact_roots()
             if not roots:

package/scripts/check_safety_floor_untouched.py

@@ -28,7 +28,7 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-RULES_DIR_REL = ".agent-src.uncompressed/rules"
+RULES_DIR_REL = ".agent-src.uncondensed/rules"
 SAFETY_FLOOR = (
     "non-destructive-by-default.md",
     "commit-policy.md",

package/scripts/check_template_pin_drift.py

@@ -5,8 +5,8 @@ CI guard for P3.3 of road-to-portable-runtime-and-update-check.md.
 
 A release bump of ``package.json`` must update
 ``agent_config_version`` in
-``.agent-src.uncompressed/templates/agents/agent-project-settings.example.yml``
-(and its compressed twin under ``.agent-src/``) in lockstep. Otherwise
+``.agent-src.uncondensed/templates/agents/agent-project-settings.example.yml``
+(and its condensed twin under ``.agent-src/``) in lockstep. Otherwise
 a fresh ``init`` on a new project would bootstrap onto a stale pin,
 and the pin-resolver would re-exec back to the older version.
 
@@ -30,8 +30,8 @@ from _lib.agent_src import resolve_logical  # noqa: E402
 PACKAGE_JSON = REPO_ROOT / "package.json"
 
 # Source-of-truth template lives under whichever artefact root owns it
-# (legacy .agent-src.uncompressed/ pre-move, packages/*/.agent-src.uncompressed/
-# post-ADR-017). Compressed twin always lands at the flat .agent-src/ surface.
+# (legacy .agent-src.uncondensed/ pre-move, packages/*/.agent-src.uncondensed/
+# post-ADR-017). Condensed twin always lands at the flat .agent-src/ surface.
 _TEMPLATE_LOGICAL = "templates/agents/agent-project-settings.example.yml"
 
 
@@ -41,7 +41,7 @@ def _template_files() -> tuple[Path, ...]:
     if src is not None:
         files.append(src)
     else:
-        files.append(REPO_ROOT / ".agent-src.uncompressed" / _TEMPLATE_LOGICAL)
+        files.append(REPO_ROOT / ".agent-src.uncondensed" / _TEMPLATE_LOGICAL)
     files.append(REPO_ROOT / ".agent-src" / _TEMPLATE_LOGICAL)
     return tuple(files)
 PIN_LINE_RE = re.compile(r"^\s*agent_config_version\s*:\s*\"?([^\"\s#]*)\"?")

package/scripts/check_token_optimizer_freshness.py

@@ -3,7 +3,7 @@
 Token-Optimizer freshness validator.
 
 Per `road-to-token-optimization.md` P1.3: parses the catalog table inside
-`.agent-src.uncompressed/skills/token-optimizer/SKILL.md`, verifies every
+`.agent-src.uncondensed/skills/token-optimizer/SKILL.md`, verifies every
 cited internal asset exists, and `grep`s the trigger keywords against
 each target file. Fails on missing target OR keyword mismatch.
 
@@ -27,7 +27,7 @@ from _lib.agent_src import resolve_logical  # noqa: E402
 # Post-ADR-017 the source-of-truth lives under whichever package owns
 # the skill; resolve_logical() walks every artefact root.
 SKILL = resolve_logical("skills/token-optimizer/SKILL.md") or (
-    REPO_ROOT / ".agent-src.uncompressed" / "skills" / "token-optimizer" / "SKILL.md"
+    REPO_ROOT / ".agent-src.uncondensed" / "skills" / "token-optimizer" / "SKILL.md"
 )
 
 from _lib.agent_src import strip_source_prefix  # noqa: E402
@@ -83,7 +83,7 @@ def resolve(path: str) -> Path | None:
         return None
     cleaned = path.strip().lstrip("`").rstrip("`")
     cleaned = cleaned.split(")")[0].lstrip("[(")
-    # Catalog rows still cite the legacy .agent-src.uncompressed/ prefix
+    # Catalog rows still cite the legacy .agent-src.uncondensed/ prefix
     # for compactness; resolve those across every packages/* root.
     logical = strip_source_prefix(cleaned)
     if logical is not None: