@event4u/agent-config 1.9.1

package/scripts/check_portability.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""
+Portability checker for agent-config packages.
+
+Scans .agent-src/ and .agent-src.uncompressed/ for project-specific references
+that violate package portability (the package must work in ANY project).
+
+Allowed: references to packages/libraries (laravel, pest, phpstan, etc.)
+Forbidden: references to specific projects, repos, domains, teams, customers
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import List, Literal
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    match: str
+    pattern_name: str
+    severity: Severity
+    context: str  # the full line for review
+
+
+# ── Auto-detected project identifiers ────────────────────────────────────
+# Instead of hardcoding project names, we auto-detect them from:
+# 1. Git remote URL (org name, repo name)
+# 2. composer.json / package.json (package name)
+# 3. Directory name (workspace root)
+# This makes the checker portable across ANY project.
+
+
+def _detect_project_identifiers(root: Path) -> set[str]:
+    """Auto-detect project-specific identifiers from the project context."""
+    identifiers: set[str] = set()
+
+    # 1. Git remote URL
+    try:
+        import subprocess
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True, cwd=root, timeout=5,
+        )
+        if result.returncode == 0:
+            url = result.stdout.strip()
+            # Extract from SSH: git@github.com:org/repo.git
+            # Extract from HTTPS: https://github.com/org/repo.git
+            parts = re.split(r"[:/]", url.replace(".git", ""))
+            # Last 2 parts are typically org and repo
+            for part in parts[-2:]:
+                part = part.strip()
+                if part and part not in ("git", "github.com", "gitlab.com", "bitbucket.org", "com"):
+                    identifiers.add(part)
+                    # Also add sub-parts split by hyphen (e.g., "event4u-app" → "event4u")
+                    for sub in part.split("-"):
+                        if len(sub) >= 3:
+                            identifiers.add(sub)
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    # 2. composer.json
+    composer = root / "composer.json"
+    if composer.exists():
+        try:
+            data = json.loads(composer.read_text(encoding="utf-8"))
+            name = data.get("name", "")
+            if "/" in name:
+                vendor, pkg = name.split("/", 1)
+                identifiers.add(vendor)
+                identifiers.add(pkg)
+                for sub in pkg.split("-"):
+                    if len(sub) >= 3:
+                        identifiers.add(sub)
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    # 3. package.json
+    pkgjson = root / "package.json"
+    if pkgjson.exists():
+        try:
+            data = json.loads(pkgjson.read_text(encoding="utf-8"))
+            name = data.get("name", "").lstrip("@")
+            if "/" in name:
+                scope, pkg = name.split("/", 1)
+                identifiers.add(scope)
+                identifiers.add(pkg)
+            elif name:
+                identifiers.add(name)
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    # 4. Directory name (parent directories of .agent-src/)
+    augment_dir = root / ".agent-src"
+    if augment_dir.exists():
+        dir_name = root.name
+        if len(dir_name) >= 3:
+            identifiers.add(dir_name)
+        # Also check parent (often the org/group directory)
+        parent_name = root.parent.name
+        if len(parent_name) >= 3 and parent_name not in ("projects", "src", "code", "repos", "home", "Users"):
+            identifiers.add(parent_name)
+
+    # Filter out generic terms that would cause false positives
+    generic = {"app", "api", "web", "src", "lib", "pkg", "core", "main", "test",
+               "config", "agent", "tools", "packages", "server", "client", "common"}
+    identifiers -= generic
+
+    return identifiers
+
+
+def _build_patterns(root: Path) -> tuple[list[tuple[re.Pattern, str, Severity]], list[str]]:
+    """Build regex patterns from auto-detected project identifiers."""
+    identifiers = _detect_project_identifiers(root)
+    patterns: list[tuple[re.Pattern, str, Severity]] = []
+    detected: list[str] = sorted(identifiers)
+
+    for ident in identifiers:
+        escaped = re.escape(ident)
+        # Word boundary match (case-insensitive)
+        patterns.append((re.compile(rf"\b{escaped}\b", re.IGNORECASE), "project-name", "error"))
+        # As prefix with separator (db names, container names, env vars)
+        patterns.append((re.compile(rf"\b{escaped}[-_]\w+", re.IGNORECASE), "project-derivative", "warning"))
+        # Domain patterns (name.tld)
+        patterns.append((re.compile(rf"\b{escaped}\.\w{{2,6}}\b", re.IGNORECASE), "project-domain", "error"))
+        # GitHub org/user patterns
+        patterns.append((re.compile(rf"@{escaped}\b", re.IGNORECASE), "project-org", "error"))
+
+    return patterns, detected
+
+# ── Allowed patterns (NOT violations even if they match above) ──────────
+# Generic Laravel/framework patterns that are NOT project-specific
+ALLOWLIST = [
+    r"\.agent-settings\.yml",      # config file reference (YAML)
+    r"\.agent-settings\b",         # legacy reference (key=value, migration window)
+    r"agents/overrides/",          # override system
+    r"app/Modules/",               # generic Laravel module pattern
+    r"`App\\",                     # namespace pattern explanation
+    r"app/Http/Controllers/",      # generic Laravel path pattern
+    r"app/Repositories/",          # generic pattern in skills/guidelines
+    r"\.module-template",          # module template
+    r"ModuleServiceProvider",      # generic module concept
+    r"app/Services/MyService",     # example placeholder
+    r"app/Models/\{",              # template placeholder like {Model}
+    r"app/Services/\{",            # template placeholder like {Service}
+    r"agent-config",               # refers to the package concept, not a specific project
+    r"shared.*package",            # "shared package" concept
+    r"package repository",         # "package repository" concept
+]
+
+# Directories to scan (only package files, not project-specific agents/)
+SCAN_DIRS = [".agent-src", ".agent-src.uncompressed"]
+
+# Additional root-level files shipped by the package that must also stay
+# portable. These are read by agents working on the package itself and —
+# for AGENTS.md and copilot-instructions.md — serve as meta docs about
+# the package. They must never leak consumer-project identifiers.
+SCAN_ROOT_FILES = ["AGENTS.md", ".github/copilot-instructions.md"]
+
+# Skip these subdirectories (they ARE allowed to be project-specific)
+SKIP_PATTERNS = [
+    "agents/",              # project-specific by design
+    ".agent-settings.yml",  # project config (YAML)
+    ".agent-settings",      # legacy project config (migration window)
+]
+
+# Optional blocklist of identifiers from past/adjacent projects that must
+# never appear anywhere in the shared package, even when the auto-detector
+# would not flag them (e.g. because the repo was renamed or split). The
+# list is loaded from the environment variable AGENT_CONFIG_BLOCKLIST
+# (comma-separated) so the package itself ships without hardcoding any
+# consumer-specific names. Maintainers of a fork with legacy debt can set
+# the variable in their CI to catch regressions.
+def _load_forbidden_identifiers() -> list[str]:
+    raw = __import__("os").environ.get("AGENT_CONFIG_BLOCKLIST", "")
+    return [part.strip() for part in raw.split(",") if part.strip()]
+
+
+FORBIDDEN_IDENTIFIERS: list[str] = _load_forbidden_identifiers()
+
+
+def _compile_patterns(root: Path) -> tuple[list[tuple[re.Pattern, str, Severity]], list[str]]:
+    """Build patterns from auto-detected project identifiers."""
+    return _build_patterns(root)
+
+
+def _compile_forbidden_patterns() -> list[tuple[re.Pattern, str, Severity]]:
+    """Build regex patterns for hardcoded FORBIDDEN_IDENTIFIERS.
+
+    These apply to every scanned file regardless of auto-detection. They
+    catch leakage from renamed or adjacent projects.
+    """
+    patterns: list[tuple[re.Pattern, str, Severity]] = []
+    for ident in FORBIDDEN_IDENTIFIERS:
+        escaped = re.escape(ident)
+        patterns.append((re.compile(rf"\b{escaped}\b", re.IGNORECASE), "forbidden-identifier", "error"))
+    return patterns
+
+
+def _compile_allowlist() -> list[re.Pattern]:
+    return [re.compile(p) for p in ALLOWLIST]
+
+
+def check_file(filepath: Path, patterns: list, allowlist: list) -> List[Violation]:
+    violations: List[Violation] = []
+    try:
+        lines = filepath.read_text(encoding="utf-8").splitlines()
+    except Exception:
+        return violations
+
+    in_code_block = False
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+
+        # Skip YAML frontmatter
+        if i <= 10 and stripped == "---":
+            continue
+
+        # Track code blocks
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            continue
+        if in_code_block:
+            continue
+
+        # Check allowlist first
+        if any(a.search(line) for a in allowlist):
+            continue
+
+        for pattern, name, severity in patterns:
+            for m in pattern.finditer(line):
+                violations.append(Violation(
+                    file=str(filepath), line=i, match=m.group(0),
+                    pattern_name=name, severity=severity, context=stripped,
+                ))
+
+    return violations
+
+
+def scan_all(root: Path) -> tuple[List[Violation], list[str]]:
+    """Scan all package files for portability violations. Returns (violations, detected_identifiers).
+
+    Scanning has two layers:
+    1. Auto-detected identifiers — applied to `.agent-src/` and
+       `.agent-src.uncompressed/` 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 —
+       applied to every scanned file, including the root files. Catches
+       leakage from renamed or adjacent projects in downstream forks.
+    """
+    patterns, detected = _compile_patterns(root)
+    forbidden = _compile_forbidden_patterns()
+    allowlist = _compile_allowlist()
+    violations: List[Violation] = []
+
+    # Layer 1 + 2: full package content
+    for scan_dir in SCAN_DIRS:
+        d = root / scan_dir
+        if not d.exists():
+            continue
+        for f in sorted(d.rglob("*.md")):
+            violations.extend(check_file(f, patterns + forbidden, allowlist))
+
+    # Layer 2 only: root files (auto-detected identifiers are expected here)
+    for rel in SCAN_ROOT_FILES:
+        f = root / rel
+        if f.is_file():
+            violations.extend(check_file(f, forbidden, allowlist))
+
+    return violations, detected
+
+
+
+def format_text(violations: List[Violation], detected: list[str]) -> str:
+    header = f"Auto-detected identifiers: {', '.join(detected)}\n" if detected else ""
+    if not violations:
+        return f"{header}✅  No portability violations found."
+    lines = [f"{header}❌  Found {len(violations)} portability violation(s):\n"]
+    for v in violations:
+        icon = "🔴" if v.severity == "error" else "🟡"
+        lines.append(f"  {icon} {v.file}:{v.line} — [{v.pattern_name}] `{v.match}`")
+        lines.append(f"      {v.context}")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check agent-config package portability")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--root", type=Path, default=Path("."), help="Repository root")
+    args = parser.parse_args()
+
+    try:
+        violations, detected = scan_all(args.root)
+    except Exception as e:
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+
+    if args.format == "json":
+        payload = {"detected": detected, "violations": [asdict(v) for v in violations]}
+        print(json.dumps(payload, indent=2))
+    else:
+        print(format_text(violations, detected))
+
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_proposal.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""
+Stage-4 gate for curated self-improvement proposals.
+
+Validates a proposal doc produced by the pipeline documented in
+`guidelines/agent-infra/self-improvement-pipeline.md`. A proposal is
+only eligible to advance to `stage: gated` if every check here passes.
+
+Gate checks (all hard):
+  1. Frontmatter complete — proposal_id, type, scope, stage, author,
+     created, last_updated.
+  2. Type / scope / stage values are from the documented vocabulary.
+  3. Evidence block — ≥2 entries under `evidence:`, each with distinct
+     `ref` value. At least two distinct hosts/repos/paths.
+  4. No "TODO" / "TBD" / "xxx" markers in the draft body.
+  5. Required sections all present (1..10 per template).
+  6. Success signal — Section 7 has a concrete metric, target, and
+     evaluation date.
+
+Exit codes: 0 = pass, 1 = gate failure, 2 = PyYAML missing, 3 = internal error.
+
+Usage:
+    python3 scripts/check_proposal.py agents/proposals/my-proposal.md
+    python3 scripts/check_proposal.py --format json path/to.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import List, Literal, Tuple
+from urllib.parse import urlparse
+
+Severity = Literal["error", "warning"]
+
+REQUIRED_FRONTMATTER = {
+    "proposal_id", "type", "scope", "stage",
+    "author", "created", "last_updated",
+}
+VALID_TYPES = {"rule", "skill", "command", "guideline"}
+VALID_SCOPES = {"project", "package"}
+VALID_STAGES = {"captured", "classified", "proposed", "gated", "upstream"}
+REQUIRED_SECTIONS: List[Tuple[str, str]] = [
+    (r"^##\s+1\.\s+Learning\b", "1. Learning"),
+    (r"^##\s+2\.\s+Classification\b", "2. Classification"),
+    (r"^##\s+3\.\s+Evidence\b", "3. Evidence"),
+    (r"^##\s+4\.\s+Proposed artefact\b", "4. Proposed artefact"),
+    (r"^##\s+5\.\s+Quality gate expectations\b", "5. Quality gate expectations"),
+    (r"^##\s+6\.\s+Replacement justification\b", "6. Replacement justification"),
+    (r"^##\s+7\.\s+Success signal\b", "7. Success signal"),
+    (r"^##\s+8\.\s+Risks and alternatives rejected\b", "8. Risks and alternatives rejected"),
+    (r"^##\s+9\.\s+Gate verdict\b", "9. Gate verdict"),
+    (r"^##\s+10\.\s+Upstream PR\b", "10. Upstream PR"),
+]
+BAD_MARKERS = re.compile(r"\b(TODO|TBD|FIXME|XXX)\b")
+FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+@dataclass
+class Finding:
+    severity: Severity
+    section: str
+    message: str
+
+
+def _load_frontmatter(text: str) -> dict:
+    match = FRONTMATTER_PATTERN.match(text)
+    if not match:
+        return {}
+    try:
+        import yaml
+    except ImportError:
+        print("error: PyYAML not installed. Run `pip install pyyaml`.", file=sys.stderr)
+        sys.exit(2)
+    return yaml.safe_load(match.group(1)) or {}
+
+
+def _body_after_frontmatter(text: str) -> str:
+    match = FRONTMATTER_PATTERN.match(text)
+    return text[match.end():] if match else text
+
+
+def _check_frontmatter(fm: dict, findings: List[Finding]):
+    missing = REQUIRED_FRONTMATTER - set(fm.keys())
+    for key in sorted(missing):
+        findings.append(Finding("error", "frontmatter", f"missing: {key}"))
+    if fm.get("type") and fm["type"] not in VALID_TYPES:
+        findings.append(Finding("error", "frontmatter",
+                                f"invalid type '{fm['type']}'"))
+    if fm.get("scope") and fm["scope"] not in VALID_SCOPES:
+        findings.append(Finding("error", "frontmatter",
+                                f"invalid scope '{fm['scope']}'"))
+    if fm.get("stage") and fm["stage"] not in VALID_STAGES:
+        findings.append(Finding("error", "frontmatter",
+                                f"invalid stage '{fm['stage']}'"))
+
+
+def _check_sections(body: str, findings: List[Finding]):
+    for pattern, name in REQUIRED_SECTIONS:
+        if not re.search(pattern, body, flags=re.MULTILINE):
+            findings.append(Finding("error", "sections", f"missing section: {name}"))
+
+
+def _extract_evidence_refs(body: str) -> List[str]:
+    refs: List[str] = []
+    ev_match = re.search(r"^##\s+3\.\s+Evidence\b(.+?)(?=^##\s)", body,
+                         flags=re.DOTALL | re.MULTILINE)
+    if not ev_match:
+        return refs
+    for line in ev_match.group(1).splitlines():
+        m = re.match(r"\s*-?\s*ref:\s*(\S+)", line)
+        if m:
+            refs.append(m.group(1).strip())
+    return refs
+
+
+def _check_evidence(body: str, findings: List[Finding]):
+    refs = _extract_evidence_refs(body)
+    if len(refs) < 2:
+        findings.append(Finding("error", "evidence",
+                                f"need ≥2 evidence refs, found {len(refs)}"))
+        return
+    # Independence — two distinct hosts OR two distinct paths.
+    hosts = {urlparse(r).netloc or r for r in refs}
+    paths = {urlparse(r).path.rsplit("/", 2)[-2:] and urlparse(r).path for r in refs}
+    if len(hosts) < 2 and len({tuple(urlparse(r).path.strip("/").split("/")[:2]) for r in refs}) < 2:
+        findings.append(Finding("warning", "evidence",
+                                "evidence refs look similar — verify independence"))
+
+
+def _strip_html_comments(text: str) -> str:
+    return re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+
+
+def _check_markers(body: str, findings: List[Finding]):
+    stripped = _strip_html_comments(body)
+    for line_no, line in enumerate(stripped.splitlines(), 1):
+        if line.lstrip().startswith("//"):
+            continue
+        if BAD_MARKERS.search(line):
+            findings.append(Finding("error", "markers",
+                                    f"draft placeholder on line {line_no}: {line.strip()[:60]}"))
+
+
+def _check_success_signal(body: str, findings: List[Finding]):
+    m = re.search(r"^##\s+7\.\s+Success signal\b(.+?)(?=^##\s)", body,
+                  flags=re.DOTALL | re.MULTILINE)
+    if not m:
+        return
+    sect = m.group(1)
+    for label in ("Metric:", "Baseline:", "Target:", "Evaluation date:"):
+        if label not in sect:
+            findings.append(Finding("error", "success-signal",
+                                    f"missing '{label}' entry"))
+
+
+def _check_originating_project(body: str, fm: dict,
+                               findings: List[Finding]):
+    """Section 10 must name the originating project once stage=upstream.
+
+    `originating_project` is metadata only — the linter does NOT check
+    for specific identifiers. It only ensures the slot is filled so the
+    Q2 outcome measurement can group merged proposals by consumer repo.
+    """
+    if fm.get("stage") != "upstream":
+        return
+    m = re.search(r"^##\s+10\.\s+Upstream PR\b(.+?)(?:^##\s|\Z)", body,
+                  flags=re.DOTALL | re.MULTILINE)
+    sect = m.group(1) if m else ""
+    if "Originating project:" not in sect:
+        findings.append(Finding("error", "originating-project",
+                                "Section 10 must include 'Originating "
+                                "project: <slug>' when stage=upstream"))
+        return
+    line = re.search(r"Originating project:\s*(.*)", sect)
+    value = (line.group(1).strip() if line else "")
+    if not value or value.startswith("<") or value in {"-", "…", "TBD"}:
+        findings.append(Finding("error", "originating-project",
+                                "Originating project slot is empty or "
+                                "left as template placeholder"))
+
+
+def _proposal_rate_warning(path: Path, findings: List[Finding],
+                           limit: int = 6, window_days: int = 90) -> None:
+    """Soft cap: warn if the proposals/ directory already holds `limit`
+    proposals authored within the last `window_days`.
+
+    Never a hard block — the Stage-4 gate does not adjudicate volume.
+    The goal is to surface a consumer that is over-fitting the package.
+    """
+    import datetime as dt
+    parent = path.parent
+    if parent.name != "proposals":
+        return
+    cutoff = dt.date.today() - dt.timedelta(days=window_days)
+    recent = 0
+    for md in parent.glob("*.md"):
+        if md.resolve() == path.resolve():
+            continue
+        try:
+            text = md.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        fm_m = FRONTMATTER_PATTERN.match(text)
+        if not fm_m:
+            continue
+        created_m = re.search(r"^created:\s*(\S+)", fm_m.group(1),
+                              flags=re.MULTILINE)
+        if not created_m:
+            continue
+        try:
+            created = dt.date.fromisoformat(created_m.group(1).strip())
+        except ValueError:
+            continue
+        if created >= cutoff:
+            recent += 1
+    if recent >= limit:
+        findings.append(Finding(
+            "warning", "rate-limit",
+            f"{recent} proposals in the last {window_days}d — consider "
+            "bundling or pruning; the package is a public good, not a "
+            "per-project scratchpad",
+        ))
+
+
+def _run_checks(text: str, path: Path | None = None) -> List[Finding]:
+    findings: List[Finding] = []
+    fm = _load_frontmatter(text)
+    _check_frontmatter(fm, findings)
+    body = _body_after_frontmatter(text)
+    _check_sections(body, findings)
+    _check_evidence(body, findings)
+    _check_markers(body, findings)
+    _check_success_signal(body, findings)
+    _check_originating_project(body, fm, findings)
+    if path is not None:
+        _proposal_rate_warning(path, findings)
+    return findings
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("path", help="Path to the proposal .md file")
+    ap.add_argument("--format", choices=["text", "json"], default="text")
+    args = ap.parse_args()
+    path = Path(args.path)
+    if not path.exists():
+        print(f"error: {path} not found", file=sys.stderr)
+        return 3
+    findings = _run_checks(path.read_text(encoding="utf-8"), path=path)
+    errors = [f for f in findings if f.severity == "error"]
+    if args.format == "json":
+        print(json.dumps({"findings": [asdict(f) for f in findings]}, indent=2))
+    else:
+        for f in findings:
+            icon = "❌" if f.severity == "error" else "⚠️"
+            print(f"  {icon}  [{f.section}]  {f.message}")
+        print(f"\nSummary: {len(errors)} error(s), "
+              f"{sum(1 for f in findings if f.severity == 'warning')} warning(s)")
+        print(f"Verdict: {'BLOCK' if errors else 'PASS'}")
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())