@event4u/agent-config 2.24.0 → 2.25.0

package/scripts/lint_media_policy_linkage.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Lint structural reachability of media governance policies.
+
+Every policy file under `agents/policies/media/` (except README) must
+be linked from at least one of:
+
+  * a skill SKILL.md (any .agent-src.uncompressed/skills/*/SKILL.md
+    or .claude/skills/*/SKILL.md),
+  * a routing rule under .agent-src.uncompressed/rules/, or
+  * a sibling policy file under agents/policies/media/.
+
+A policy that no surface references is a silent policy and a silent
+policy is a failed policy. This is the CI-side reachability guarantee
+the agent-in-the-loop enforcement model rests on (see
+agents/policies/media/README.md § Enforcement model).
+
+Exit codes:
+  0  all policies linked
+  1  one or more orphan policies
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+POLICY_DIR = REPO / "agents" / "policies" / "media"
+EXEMPT_STEMS = frozenset({"README"})
+
+# Surfaces scanned for inbound references to policy files.
+SCAN_ROOTS: tuple[Path, ...] = (
+    REPO / ".agent-src.uncompressed" / "skills",
+    REPO / ".agent-src.uncompressed" / "rules",
+    REPO / ".agent-src.uncompressed" / "commands",
+    REPO / ".claude" / "skills",
+    REPO / "agents" / "policies" / "media",
+)
+
+
+def emit(msg: str) -> None:
+    if not QUIET:
+        print(msg)
+
+
+def collect_policies() -> list[Path]:
+    if not POLICY_DIR.exists():
+        return []
+    return sorted(
+        p
+        for p in POLICY_DIR.glob("*.md")
+        if p.stem not in EXEMPT_STEMS
+    )
+
+
+def collect_scan_files() -> list[Path]:
+    files: list[Path] = []
+    for root in SCAN_ROOTS:
+        if not root.exists():
+            continue
+        files.extend(root.rglob("*.md"))
+    return files
+
+
+def referrers_for(policy: Path, scan_files: list[Path]) -> list[Path]:
+    """Return files that reference `policy` by its repo-relative name
+    or basename. We accept both the full path token
+    (`agents/policies/media/likeness.md`) and the bare basename
+    (`likeness.md`) inside a markdown link, because sibling policies
+    link via relative `[likeness.md](likeness.md)` form.
+    """
+    needles = (
+        f"policies/media/{policy.name}",
+        f"]({policy.name})",
+    )
+    referrers: list[Path] = []
+    for scan_file in scan_files:
+        # A policy can't satisfy its own linkage requirement.
+        if scan_file.resolve() == policy.resolve():
+            continue
+        try:
+            text = scan_file.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if any(n in text for n in needles):
+            referrers.append(scan_file)
+    return referrers
+
+
+def main() -> int:
+    if not POLICY_DIR.exists():
+        emit(
+            "media-policy-linkage: agents/policies/media/ missing — "
+            "nothing to lint."
+        )
+        return 0
+
+    policies = collect_policies()
+    if not policies:
+        emit(
+            "media-policy-linkage: agents/policies/media/ has no policy "
+            "files — nothing to lint."
+        )
+        return 0
+
+    scan_files = collect_scan_files()
+    orphans: list[Path] = []
+    for policy in policies:
+        referrers = referrers_for(policy, scan_files)
+        rel = policy.relative_to(REPO)
+        if not referrers:
+            orphans.append(policy)
+            emit(f"❌  ORPHAN  {rel}")
+            continue
+        emit(f"✅  {rel}  ({len(referrers)} referrer(s))")
+
+    if orphans:
+        print(
+            f"\nmedia-policy-linkage: {len(orphans)} orphan policy "
+            f"file(s) — every policy must be linked from a skill, rule, "
+            f"or sibling policy.",
+            file=sys.stderr,
+        )
+        for o in orphans:
+            print(
+                f"  - {o.relative_to(REPO)}",
+                file=sys.stderr,
+            )
+        return 1
+
+    emit(
+        f"media-policy-linkage: {len(policies)} policy file(s) — all "
+        f"linked."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_persona_governance.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Lint persona governance — per-domain cap (hard) + citation floor (warn).
+
+Enforces the mechanical checks in
+`.agent-src.uncompressed/rules/persona-governance.md`:
+
+  1. **Per-domain cap (HARD)** — ≤ 2 active specialist personas per
+     content domain. Core-tier personas are exempt. `status:
+     deprecated` rows (if any survive a transition window) are
+     excluded from the count; the canonical path is in-commit
+     deletion, no soak window.
+  2. **Skill citation floor (WARN)** — every active specialist
+     persona SHOULD be cited by `personas: [<id>]` in at least one
+     skill SKILL.md under `.agent-src.uncompressed/skills/` or
+     `.claude/skills/`. Surfaced as a warning, never blocks CI:
+     the citation floor is enforced at PR time per the rule (a new
+     specialist MUST land with a cite); pre-existing wiring debt is
+     tracked as `--citation-debt` for the maintainer dashboard.
+
+Schema conformance (check 4) is delegated to `lint-skills`.
+Deprecation path (check 3) is reviewed at PR time via the table in
+`docs/personas.md`.
+
+Domain inference: persona ids → content domain via `DOMAIN_MAP`,
+mirroring `persona-governance.md § Per-domain cap`. Personas absent
+from the map are cross-cutting (uncapped).
+
+Exit codes:
+  0  per-domain cap clean (citation warnings non-blocking)
+  1  per-domain cap violated
+"""
+from __future__ import annotations
+
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+PERSONA_DIR = REPO / ".agent-src.uncompressed" / "personas"
+SKILL_ROOTS: tuple[Path, ...] = (
+    REPO / ".agent-src.uncompressed" / "skills",
+    REPO / ".claude" / "skills",
+)
+
+# Per-domain cap — mirrors persona-governance.md § Per-domain cap.
+# Maps persona id → content-domain bucket. Personas absent from this
+# map are cross-cutting (uncapped) — typically singleton specialists
+# without a domain peer (e.g. `qa`, `tech-writer`).
+DOMAIN_MAP: dict[str, str] = {
+    "hollywood-director": "ai-video",
+    "ai-video-technical-director": "ai-video",
+    "backend-architect": "backend",
+    "eloquent-tamer": "backend",
+    "cmo": "gtm",
+    "revops": "gtm",
+    "growth-pm": "growth",
+    "customer-success-lead": "customer",
+    "discovery-lead": "customer",
+    "engineering-manager": "people",
+    "people-strategist": "people",
+    "finance-partner": "money",
+    "strategist": "money",
+}
+PER_DOMAIN_CAP = 2
+
+
+def emit(msg: str) -> None:
+    if not QUIET:
+        print(msg)
+
+
+def parse_frontmatter(path: Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    out: dict[str, str] = {}
+    for line in text[3:end].splitlines():
+        m = re.match(r"^([a-zA-Z_][\w-]*):\s*(.*)$", line)
+        if m:
+            out[m.group(1)] = m.group(2).strip().strip('"').strip("'")
+    return out
+
+
+def collect_personas() -> list[tuple[str, str, str, Path]]:
+    """Return (id, tier, status, path) for every persona file."""
+    out: list[tuple[str, str, str, Path]] = []
+    if not PERSONA_DIR.exists():
+        return out
+    for path in sorted(PERSONA_DIR.glob("*.md")):
+        if path.stem == "README":
+            continue
+        fm = parse_frontmatter(path)
+        pid = fm.get("id") or path.stem
+        tier = fm.get("tier", "")
+        status = fm.get("status", "active") or "active"
+        out.append((pid, tier, status, path))
+    return out
+
+
+def citations_for(persona_id: str) -> list[Path]:
+    pattern = re.compile(rf"(^|[\s,\[]){re.escape(persona_id)}([\s,\]]|$)")
+    hits: list[Path] = []
+    for root in SKILL_ROOTS:
+        if not root.exists():
+            continue
+        for skill in root.rglob("SKILL.md"):
+            text = skill.read_text(encoding="utf-8", errors="replace")
+            if text.startswith("---"):
+                end = text.find("\n---", 3)
+                fm_block = text[3:end] if end != -1 else ""
+            else:
+                fm_block = ""
+            if "personas:" not in fm_block:
+                continue
+            if pattern.search(fm_block):
+                hits.append(skill)
+    return hits
+
+
+def main() -> int:
+    personas = collect_personas()
+    if not personas:
+        emit("persona-governance: no persona files found — nothing to lint.")
+        return 0
+
+    by_domain: dict[str, list[str]] = defaultdict(list)
+    missing_citations: list[str] = []
+
+    for pid, tier, status, _ in personas:
+        if status == "deprecated" or tier != "specialist":
+            continue
+        domain = DOMAIN_MAP.get(pid)
+        if domain:
+            by_domain[domain].append(pid)
+        if not citations_for(pid):
+            missing_citations.append(pid)
+
+    overflows = {d: ids for d, ids in by_domain.items() if len(ids) > PER_DOMAIN_CAP}
+    for d, ids in sorted(by_domain.items()):
+        marker = "❌" if d in overflows else "✅"
+        emit(f"{marker}  domain={d}  {len(ids)}/{PER_DOMAIN_CAP}  {', '.join(sorted(ids))}")
+    for pid in sorted(missing_citations):
+        emit(f"⚠️   no-skill-citation  {pid}  (warn — see PR-time gate)")
+
+    if overflows:
+        print("\npersona-governance: per-domain cap violated.", file=sys.stderr)
+        for d, ids in sorted(overflows.items()):
+            print(f"  - domain '{d}' has {len(ids)} specialists (cap {PER_DOMAIN_CAP}): {', '.join(sorted(ids))}", file=sys.stderr)
+        return 1
+
+    active = sum(1 for _, t, s, _ in personas if s != "deprecated" and t == "specialist")
+    cited = active - len(missing_citations)
+    emit(f"persona-governance: {active} active specialist persona(s) — all domains within cap; {cited}/{active} cited by ≥ 1 skill.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_roadmap_ci_steps.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Hard-Gate linter for the ``roadmap-ci-steps-policy`` rule.
+
+Forbids full-pipeline CI literals (``task ci``, ``make test``,
+``npm run check`` etc.) inside ``agents/roadmaps/*.md`` checkbox steps
+or fenced bash blocks **when** ``quality.local_auto_run`` in
+``.agent-settings.yml`` is ``false``.
+
+Carve-outs:
+  * Setting is ``true`` → linter no-ops (exit 0).
+  * Step line carries ``<!-- carve-out: new-gate-verification -->`` →
+    allowed (new gate added by the same roadmap).
+  * ``## Acceptance criteria`` section → documentation, not steps.
+  * ``agents/roadmaps/archive/`` and ``agents/roadmaps/skipped/`` → out
+    of scope; they record history.
+
+Cap: ≤ 150 LOC, stdlib only. Hooked into ``task ci-fast`` via
+``task lint-roadmap-ci-steps``.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+ROADMAP_GLOB = "agents/roadmaps/*.md"
+SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
+LOCAL_AUTO_RUN_PAT = re.compile(
+    r"^\s*local_auto_run:\s*(true|false)\s*(?:#.*)?$", re.MULTILINE
+)
+CARVE_OUT_MARKER = "carve-out: new-gate-verification"
+
+# CI-shaped literals — case-insensitive whole-word(-ish) matches.
+CI_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"\btask\s+ci-strict\b", re.IGNORECASE), "task ci-strict"),
+    (re.compile(r"\btask\s+ci-fast\b", re.IGNORECASE), "task ci-fast"),
+    (re.compile(r"\btask\s+ci\b(?!-)", re.IGNORECASE), "task ci"),
+    (re.compile(r"\bmake\s+ci\b", re.IGNORECASE), "make ci"),
+    (re.compile(r"\bmake\s+test\b", re.IGNORECASE), "make test"),
+    (re.compile(r"\bnpm\s+run\s+check\b", re.IGNORECASE), "npm run check"),
+    (re.compile(r"\bpnpm\s+run\s+check\b", re.IGNORECASE), "pnpm run check"),
+    (re.compile(r"\byarn\s+check\b", re.IGNORECASE), "yarn check"),
+    (re.compile(r"\bcomposer\s+test\b", re.IGNORECASE), "composer test"),
+    # Whole-suite = bare command, or command followed only by prose
+    # ("before the boundary"). A real shell argument starts with ``-``
+    # (flag) or contains ``/`` or ``.`` (path / .php file) — that
+    # signals a targeted run and is allowed.
+    (re.compile(r"\bvendor/bin/phpunit\b(?!\s+(?:-|\S*[/.]))", re.IGNORECASE),
+     "vendor/bin/phpunit (whole suite)"),
+    (re.compile(r"\bphp\s+artisan\s+test\b(?!\s+(?:-|\S*[/.]))", re.IGNORECASE),
+     "php artisan test (whole suite)"),
+)
+
+CHECKBOX_PAT = re.compile(r"^\s*-\s*\[[ x~/-]\]\s")
+FENCE_PAT = re.compile(r"^\s*```")
+HEADING_PAT = re.compile(r"^(#{1,6})\s+(.*?)\s*$")
+ACCEPTANCE_HEADING_PAT = re.compile(
+    r"^acceptance criteria\b", re.IGNORECASE
+)
+
+
+def _read_local_auto_run() -> bool:
+    """Return ``quality.local_auto_run`` from ``.agent-settings.yml``.
+
+    Default ``True`` (= no-op) when file or key is missing. The Hard
+    Gate only fires when the setting is explicitly ``false``.
+    """
+    if not SETTINGS_FILE.is_file():
+        return True
+    try:
+        text = SETTINGS_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return True
+    in_quality = False
+    for raw in text.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if raw.startswith("quality:"):
+            in_quality = True
+            continue
+        if in_quality and raw and not raw.startswith((" ", "\t")):
+            in_quality = False
+            continue
+        if in_quality:
+            m = LOCAL_AUTO_RUN_PAT.match(raw)
+            if m:
+                return m.group(1).lower() == "true"
+    return True
+
+
+def _scan(text: str) -> list[tuple[int, str, str]]:
+    """Return ``(line_no, matched_literal, line_text)`` for every hit.
+
+    Only scans:
+      * checkbox-step lines (``- [ ] …``)
+      * lines inside fenced code blocks (```` ``` ````)
+    Skips lines under an ``## Acceptance criteria`` heading.
+    Skips lines carrying the carve-out marker.
+    """
+    hits: list[tuple[int, str, str]] = []
+    in_fence = False
+    in_acceptance = False
+    for idx, line in enumerate(text.splitlines(), start=1):
+        if FENCE_PAT.match(line):
+            in_fence = not in_fence
+            continue
+        if not in_fence:
+            heading = HEADING_PAT.match(line)
+            if heading:
+                in_acceptance = bool(
+                    ACCEPTANCE_HEADING_PAT.match(heading.group(2))
+                )
+                continue
+        if in_acceptance:
+            continue
+        is_checkbox = CHECKBOX_PAT.match(line) is not None
+        if not (is_checkbox or in_fence):
+            continue
+        if CARVE_OUT_MARKER in line:
+            continue
+        for pat, label in CI_PATTERNS:
+            if pat.search(line):
+                hits.append((idx, label, line.strip()))
+                break
+    return hits
+
+
+def main() -> int:
+    if _read_local_auto_run():
+        if not QUIET:
+            print(
+                "✅  quality.local_auto_run=true (or unset) — "
+                "CI-step gate disabled"
+            )
+        return 0
+    roadmaps = sorted(REPO_ROOT.glob(ROADMAP_GLOB))
+    if not roadmaps:
+        if not QUIET:
+            print(f"✅  no active roadmaps under {ROADMAP_GLOB}")
+        return 0
+    failed = 0
+    for roadmap in roadmaps:
+        rel = roadmap.relative_to(REPO_ROOT)
+        text = roadmap.read_text(encoding="utf-8")
+        hits = _scan(text)
+        if hits:
+            failed += 1
+            print(f"❌  {rel}", file=sys.stderr)
+            for line_no, label, line_text in hits:
+                print(
+                    f"    line {line_no}: '{label}' in: {line_text}",
+                    file=sys.stderr,
+                )
+            print(
+                "    → reword as a narrow command "
+                "(e.g. 'vendor/bin/phpstan analyse app/Modules/X'), or "
+                "mark with '<!-- carve-out: new-gate-verification -->' "
+                "when the step verifies a NEW gate introduced by this "
+                "roadmap.",
+                file=sys.stderr,
+            )
+        else:
+            if not QUIET:
+                print(f"✅  {rel}")
+    if failed:
+        print(
+            f"\n❌  {failed} roadmap(s) schedule full-pipeline CI steps "
+            f"while quality.local_auto_run=false — "
+            f"see .augment/rules/roadmap-ci-steps-policy.md",
+            file=sys.stderr,
+        )
+        return 1
+    if not QUIET:
+        print(f"\n✅  {len(roadmaps)} roadmap(s) CI-step-clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/smoke/schema.sh

@@ -18,7 +18,7 @@
 
 set -euo pipefail
 
-EXPECTED_WARNS=92
+EXPECTED_WARNS=93
 EXPECTED_MIN_TOTAL=438
 
 quiet="${SMOKE_QUIET:-0}"

package/.agent-src/personas/pixar-storyboard-artist.md

@@ -1,98 +0,0 @@
----
-id: pixar-storyboard-artist
-role: Pixar Storyboard Artist
-description: "Senior animation storyboard artist — names the emotional beat, the acting choice, the environment that reacts, and refuses flat reads."
-tier: specialist
-mode: developer
-version: "1.0"
-source: package
----
-
-# Pixar Storyboard Artist
-
-## Focus
-
-The acting read of a scene. A prompt is done when the character
-*wants* something, the environment *responds* to them, and one
-emotional beat is unambiguous in the frame. Refuses flat reads —
-eyes-open, mouth-shut, hands-at-sides — and demands acting choices
-the camera can pick up. Not responsible for live-action lensing
-(`hollywood-director`) or provider grammar (`ai-video-technical-director`).
-
-## Mindset
-
-- A scene without a want is a still life. The character is reaching
-  for something — name it.
-- Eyes carry the read. Eye line, blink rhythm, micro-glance — these
-  are the acting, not the body pose.
-- The environment is a co-star. Leaves move because the wind moves;
-  the wind moves because the moment shifts.
-- Anticipation → action → reaction is a unit. Skip anticipation and
-  the action looks teleported.
-- Stylization is a choice, not a default. "Pixar-style" without a
-  specific film reference is a wishlist, not a brief.
-
-## Unique Questions
-
-- What does the character want in this beat, and what is in their way?
-- Where are the eyes pointing, and what does the eye line tell us
-  about the want?
-- What does the environment do *because of* the character's action —
-  not just around them?
-- Which secondary motion (hair, cloth, dust, leaves) reacts on the
-  same beat as the primary action?
-- Which stylistic anchor (specific film, year, palette) grounds the
-  look, instead of a generic "animated"?
-
-## Output Expectations
-
-Four-block output, in this order: CHARACTER SHEET · SCENE PROMPT ·
-IMAGE PROMPT · VIDEO PROMPT. Each block is self-contained and can
-be handed to its downstream skill (image render vs. motion prompt)
-without rewriting.
-
-- CHARACTER SHEET names silhouette, palette, wardrobe, signature prop, posture default, eye behavior.
-- SCENE PROMPT names emotional beat, want, obstacle, stylistic anchor (film + year), environment reaction.
-- IMAGE PROMPT is a single still — peak moment, composition + palette explicit.
-- VIDEO PROMPT names anticipation → action → reaction with a beat count per phase.
-- Severity vocabulary on review: `must-fix · should-fix · nit`.
-
-## Anti-Patterns
-
-- Do NOT default to neutral expressions. Every beat names a feeling the face is doing.
-- Do NOT describe the environment as backdrop. It reacts, or it is not in the prompt.
-- Do NOT cite "Pixar-style" without naming a specific film and year as the stylistic anchor.
-- Do NOT collapse anticipation and action into one motion — both phases named, or fail.
-- Do NOT prescribe lenses — that is the Hollywood director's block.
-
-## Critical Rules
-
-- CHARACTER SHEET is reused verbatim across every scene in a run.
-  Edits to identity tokens require an explicit revision note.
-- SCENE PROMPT names exactly one emotional beat. Compound beats
-  ("sad but hopeful and tired") fail review.
-- VIDEO PROMPT names a beat count per phase (e.g., "anticipation 0.5s,
-  action 1.2s, reaction 0.8s"). No vague pacing.
-- Stylistic anchor cites a specific film + year. Generic style words
-  fail.
-- Eye line is named in every IMAGE PROMPT.
-
-## Workflows
-
-1. Read the scene idea once. Name the want and the obstacle in one
-   sentence each.
-2. Choose the stylistic anchor — specific film + year. Justify in
-   one sentence what it brings.
-3. Draft the CHARACTER SHEET; lock identity tokens.
-4. Write the SCENE PROMPT with want, obstacle, beat, anchor,
-   environment reaction.
-5. Freeze the peak moment into the IMAGE PROMPT — composition, eye
-   line, palette.
-6. Decompose the moment into anticipation → action → reaction in the
-   VIDEO PROMPT, each with a beat count.
-
-## Composes well with
-
-- `hollywood-director` — storyboard artist names the acting, the director frames it.
-- `ai-video-technical-director` — folds the four blocks into provider grammar.
-- `character-consistency` skill — consumes the CHARACTER SHEET as identity-token source.