@event4u/agent-config 5.10.1 → 6.1.0

package/src/scripts/prototype_lint_contradictions.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+Prototype contradiction linter (P1.1 of road-to-package-optimization).
+
+Hard acceptance: must flag >=3 real cross-artifact contradictions in this
+repo within 5 s wall-clock and < $0.01 cost (deterministic, no LLM calls).
+On failure, the roadmap closes with the null result documented; no
+Phase 2 work begins.
+
+Heuristic family — three deterministic checks across rules, skills,
+commands, and contexts:
+
+1. Routing mismatch: rule frontmatter `routes_to: [skill:foo]` but the
+   target artifact does not exist or has no matching trigger.
+2. Trigger collision with imperative conflict: two artifacts share a
+   trigger keyword AND one body contains an `ALWAYS X` Iron Law while
+   the other contains `NEVER X` (or `MUST` vs `MUST NOT`) on the same
+   verb-object.
+3. Catalog drift: a token-optimizer-style catalog row cites a path that
+   does not exist (subset of #1, broader scope than the freshness gate).
+
+Stdlib only. JSON to stdout. Exit 0 = clean / Exit 1 = contradictions found.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent.parent
+SRC = REPO / ".agent-src.uncondensed"
+
+ARTIFACT_DIRS = {
+    "rule": SRC / "rules",
+    "skill": SRC / "skills",
+    "command": SRC / "commands",
+    "context": SRC / "contexts",
+}
+
+FM_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+ALWAYS_RE = re.compile(r"^\s*(ALWAYS|MUST)\s+([A-Z][^.\n]{2,80})", re.MULTILINE)
+NEVER_RE = re.compile(r"^\s*(NEVER|MUST NOT|DO NOT)\s+([A-Z][^.\n]{2,80})", re.MULTILINE)
+
+
+def parse_artifact(path: Path, kind: str) -> dict:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    fm: dict = {}
+    m = FM_RE.match(text)
+    body = text
+    if m:
+        body = text[m.end():]
+        for line in m.group(1).splitlines():
+            if ":" in line and not line.startswith(" "):
+                k, _, v = line.partition(":")
+                fm[k.strip()] = v.strip()
+    triggers = re.findall(r"`([a-z][a-z0-9_-]+)`", fm.get("description", ""))
+    routes = re.findall(r"(skill|rule|command):([a-z0-9_-]+)", fm.get("routes_to", ""))
+    always = [m.group(2).strip() for m in ALWAYS_RE.finditer(body)]
+    never = [m.group(2).strip() for m in NEVER_RE.finditer(body)]
+    return {
+        "kind": kind,
+        "path": str(path.relative_to(REPO)),
+        "id": path.stem if path.name != "SKILL.md" else path.parent.name,
+        "triggers": set(triggers),
+        "routes": routes,
+        "always": always,
+        "never": never,
+    }
+
+
+def collect() -> list[dict]:
+    out: list[dict] = []
+    for kind, root in ARTIFACT_DIRS.items():
+        if not root.exists():
+            continue
+        for p in root.rglob("*.md"):
+            if p.name in {"README.md", "INDEX.md"}:
+                continue
+            out.append(parse_artifact(p, kind))
+    return out
+
+
+def check_routing(arts: list[dict]) -> list[dict]:
+    by_id = {(a["kind"], a["id"]): a for a in arts}
+    flags: list[dict] = []
+    for a in arts:
+        for tgt_kind, tgt_id in a["routes"]:
+            if (tgt_kind, tgt_id) not in by_id:
+                flags.append({
+                    "type": "routing_mismatch",
+                    "artifact_a": a["path"],
+                    "artifact_b": f"{tgt_kind}:{tgt_id} (missing)",
+                    "evidence": f"{a['id']} routes_to {tgt_kind}:{tgt_id}, target not found",
+                })
+    return flags
+
+
+def normalize_verb(s: str) -> str:
+    return re.sub(r"[^a-z ]+", "", s.lower()).split(" ", 1)[0] if s else ""
+
+
+def check_imperative_conflict(arts: list[dict]) -> list[dict]:
+    flags: list[dict] = []
+    by_trigger: dict[str, list[dict]] = {}
+    for a in arts:
+        for t in a["triggers"]:
+            by_trigger.setdefault(t, []).append(a)
+    for trigger, group in by_trigger.items():
+        if len(group) < 2:
+            continue
+        for i, a in enumerate(group):
+            for b in group[i + 1:]:
+                a_verbs = {normalize_verb(s) for s in a["always"]}
+                b_verbs = {normalize_verb(s) for s in b["never"]}
+                conflict = a_verbs & b_verbs - {""}
+                if conflict:
+                    flags.append({
+                        "type": "imperative_conflict",
+                        "artifact_a": a["path"],
+                        "artifact_b": b["path"],
+                        "evidence": f"shared trigger '{trigger}', a says ALWAYS {sorted(conflict)}, b says NEVER {sorted(conflict)}",
+                    })
+    return flags
+
+
+def main() -> int:
+    t0 = time.monotonic()
+    arts = collect()
+    flags = check_routing(arts) + check_imperative_conflict(arts)
+    elapsed = time.monotonic() - t0
+    report = {
+        "artifacts_scanned": len(arts),
+        "elapsed_seconds": round(elapsed, 3),
+        "flags": flags,
+        "acceptance": {
+            "min_flags": 3,
+            "max_seconds": 5.0,
+            "passed": len(flags) >= 3 and elapsed < 5.0,
+        },
+    }
+    json.dump(report, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0 if not flags else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/scripts/prove_pack_extractable.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Prove a pack + its declared dependency closure is self-contained.
+
+road-to-6.0.0-D Phase 1 Step 6 — the *extraction proof*. It de-risks the
+monorepo collapse (Phase 3) by proving that a pack moved into the flat
+``src/`` library can still be lifted back out into a standalone package:
+every artefact the pack references must live inside the pack's own
+``requires`` closure (plus the always-available foundation packs). A
+reference that points OUTSIDE the closure is a dangling edge — the slice
+would not build standalone, so re-split is no longer possible.
+
+What "its own tests pass" means for a markdown artefact library: the
+isolated slice has (1) zero dangling skill/rule references in frontmatter,
+(2) zero dangling markdown links into the artefact library, and (3) a
+``pack.yaml`` whose ``requires`` graph stays acyclic within the closure.
+Those are the structural invariants the per-pack CI gates assert; proving
+them on the isolated closure is the standalone-build proof.
+
+Usage:
+  python3 scripts/prove_pack_extractable.py <pack-id> [--json]
+
+Exit codes: 0 = extractable · 1 = dangling reference(s) · 3 = unknown pack.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib import agent_src  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[2]
+PACKS_VOCAB = ROOT / "src" / "config" / "discovery" / "packs.yml"
+# Always-available foundation packs: every pack may reference these without
+# declaring them in `requires` (the 6.0.0-D council's resolution of the
+# ambiguous "core" in the boundary rule — engineering-base + meta are the
+# implicit foundation, alongside the legacy physical `core`).
+FOUNDATION = {"core", "engineering-base", "meta"}
+_LINK_RE = re.compile(r"\]\(([^)#?]+\.md)(?:[#?][^)]*)?\)")
+
+
+def _frontmatter(path: Path) -> dict:
+    text = path.read_text("utf-8", errors="replace")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    try:
+        data = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _pack_requires() -> dict[str, set[str]]:
+    """Map pack id -> direct `requires` set, from the discovery vocab."""
+    graph: dict[str, set[str]] = {}
+    vocab = yaml.safe_load(PACKS_VOCAB.read_text("utf-8")) or []
+    for entry in vocab:
+        if isinstance(entry, dict) and isinstance(entry.get("id"), str):
+            graph[entry["id"]] = set(entry.get("requires") or [])
+    return graph
+
+
+def _closure(pack: str, graph: dict[str, set[str]]) -> set[str]:
+    """Transitive `requires` closure of ``pack`` (inclusive) + foundation."""
+    seen: set[str] = set()
+    stack = [pack]
+    while stack:
+        p = stack.pop()
+        if p in seen:
+            continue
+        seen.add(p)
+        stack.extend(graph.get(p, set()) - seen)
+    return seen | FOUNDATION
+
+
+def _library_index() -> tuple[dict[str, set[str]], dict[str, set[str]]]:
+    """Build (slug_to_packs, logicalpath_to_packs) over the flat library."""
+    slug_packs: dict[str, set[str]] = {}
+    path_packs: dict[str, set[str]] = {}
+    for phys, logical in agent_src.iter_all_sources():
+        if not logical.endswith(".md"):
+            continue
+        fm = _frontmatter(phys)
+        packs = set(p for p in (fm.get("packs") or []) if isinstance(p, str))
+        if not packs:
+            continue
+        path_packs[logical] = packs
+        if logical.startswith("skills/") and logical.endswith("/SKILL.md"):
+            slug_packs[logical.split("/")[1]] = packs
+        elif logical.startswith("rules/"):
+            slug_packs[logical[len("rules/"):-len(".md")]] = packs
+    return slug_packs, path_packs
+
+
+def prove(pack: str) -> tuple[bool, list[str], list[str], set[str]]:
+    """Return (extractable, hard_dangling, advisory_warnings, closure).
+
+    The dependency axis is frontmatter (6.0.0-D council convergence): a
+    HARD edge is a ``skills:`` / ``rules:`` include — it must resolve inside
+    the closure or the standalone slice fails to build. A markdown link into
+    another pack is an ADVISORY cross-reference (a "route to" / "see also")
+    — it is reported as a warning but does NOT block extraction, because the
+    skill still functions when the linked alternative is simply not installed.
+    """
+    graph = _pack_requires()
+    if pack not in graph:
+        return False, [f"unknown pack id '{pack}' (not in {PACKS_VOCAB})"], [], set()
+    closure = _closure(pack, graph)
+    slug_packs, path_packs = _library_index()
+
+    def in_closure(packs: set[str]) -> bool:
+        return bool(packs & closure)
+
+    hard: list[str] = []
+    advisory: list[str] = []
+    members = [(logical, phys) for phys, logical in agent_src.iter_all_sources()
+               if logical.endswith(".md") and pack in path_packs.get(logical, set())]
+    for logical, phys in members:
+        fm = _frontmatter(phys)
+        # (1) HARD: frontmatter skill/rule includes — the build-dependency axis
+        for slug in (fm.get("skills") or []) + (fm.get("rules") or []):
+            if not isinstance(slug, str):
+                continue
+            target = slug_packs.get(slug)
+            if target is None:
+                continue  # command-routing target / non-library slug — not a pack edge
+            if not in_closure(target):
+                hard.append(
+                    f"{logical}: include '{slug}' lives in {sorted(target)} — outside closure")
+        # (2) ADVISORY: markdown links into the artefact library
+        for raw in _LINK_RE.findall(phys.read_text("utf-8", errors="replace")):
+            tgt = agent_src.strip_source_prefix(raw) or _resolve_rel(phys, raw)
+            if tgt is None or tgt not in path_packs:
+                continue
+            if not in_closure(path_packs[tgt]):
+                advisory.append(
+                    f"{logical}: advisory link → {tgt} ({sorted(path_packs[tgt])}) — "
+                    f"not installed when '{pack}' is extracted alone")
+    return (not hard), hard, advisory, closure
+
+
+def _resolve_rel(source: Path, raw: str) -> str | None:
+    try:
+        resolved = (source.parent / raw).resolve()
+        rel = resolved.relative_to(ROOT).as_posix()
+    except (OSError, ValueError):
+        return None
+    return agent_src.strip_source_prefix(rel)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("pack", help="pack id (e.g. laravel)")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args()
+    ok, hard, advisory, closure = prove(args.pack)
+    if not closure:
+        print(f"❌  {hard[0]}", file=sys.stderr)
+        return 3
+    if args.json:
+        json.dump({"pack": args.pack, "extractable": ok,
+                   "closure": sorted(closure), "hard_dangling": hard,
+                   "advisory": advisory}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    elif ok:
+        print(f"✅  '{args.pack}' is extractable — closure {sorted(closure)}, "
+              f"0 hard dangling references.")
+        for a in advisory:
+            print(f"   ⚠️  {a}")
+    else:
+        for d in hard:
+            print(f"❌  {d}", file=sys.stderr)
+        print(f"\n{len(hard)} hard dangling reference(s) — '{args.pack}' is NOT "
+              f"standalone-extractable.", file=sys.stderr)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/scripts/recruit_preflight.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Recruit-session day-of pre-flight checks.
+#
+# Phase B Step 2 of road-to-adoption-proof-and-ci-green.md. Run this
+# 30 minutes before a recruit session — exits non-zero on any failure
+# so a missed prereq pushes the session rather than burning it.
+#
+# Checks (all ≤ 5 s total runtime):
+#
+#   1. Provider keys present  — ANTHROPIC_API_KEY or OPENAI_API_KEY in env,
+#      OR AGENT_CONFIG_DRYRUN=true (dry-run session task).
+#   2. Workspace state clean  — ~/.augment/ has no in-progress experiments.
+#   3. agents/recruit-sessions/ writable.
+#   4. task ci green at HEAD  — last 'task ci' run summary is clean.
+#   5. Screen recording tool installed — one of obs / loom-cli /
+#      zoom-cli / riverside present (best-effort detection).
+#
+# Output: one line per check, prefixed ✅ / ❌. Exit codes:
+#   0 — every check passed.
+#   1 — at least one check failed.
+#
+# CLI:
+#   bash scripts/recruit_preflight.sh [--quiet] [--dry-run-allowed]
+#
+#   --quiet               Suppress per-check rows; print summary only.
+#   --dry-run-allowed     Accept AGENT_CONFIG_DRYRUN=true as the provider
+#                         keys check (default false — explicit keys needed).
+#
+# Tests live at tests/test_recruit_preflight.sh (fixture-driven).
+
+set -euo pipefail
+
+QUIET=false
+DRY_RUN_ALLOWED=false
+for arg in "$@"; do
+  case "$arg" in
+    --quiet) QUIET=true ;;
+    --dry-run-allowed) DRY_RUN_ALLOWED=true ;;
+    -h|--help)
+      sed -n '2,28p' "$0" | sed 's/^# //'
+      exit 0
+      ;;
+    *) echo "recruit_preflight: unknown arg: $arg" >&2; exit 2 ;;
+  esac
+done
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"  # src/scripts/ -> repo root
+PASS=0
+FAIL=0
+
+_emit() {
+  if [ "$QUIET" = false ]; then
+    echo "$1"
+  fi
+}
+
+_check() {
+  local label="$1"
+  local ok="$2"
+  local detail="${3:-}"
+  if [ "$ok" = "true" ]; then
+    _emit "✅  ${label}${detail:+ — ${detail}}"
+    PASS=$((PASS + 1))
+  else
+    _emit "❌  ${label}${detail:+ — ${detail}}"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# 1. Provider keys present (or dry-run accepted)
+if [ -n "${ANTHROPIC_API_KEY:-}" ] || [ -n "${OPENAI_API_KEY:-}" ]; then
+  _check "provider keys" true "anthropic / openai env var set"
+elif [ "$DRY_RUN_ALLOWED" = true ] && [ "${AGENT_CONFIG_DRYRUN:-}" = "true" ]; then
+  _check "provider keys" true "dry-run mode accepted"
+else
+  _check "provider keys" false "set ANTHROPIC_API_KEY or OPENAI_API_KEY (or pass --dry-run-allowed)"
+fi
+
+# 2. Workspace state clean — ~/.augment/ has no in-progress experiments.
+# "In-progress" is defined as any file under ~/.augment/ modified within
+# the last 60 minutes whose name suggests a session / experiment / draft.
+AUGMENT_DIR="${HOME}/.augment"
+if [ ! -d "$AUGMENT_DIR" ]; then
+  _check "workspace clean" true "no ~/.augment/ — fresh user"
+else
+  RECENT=$(find "$AUGMENT_DIR" -type f \
+    \( -name '*session*' -o -name '*experiment*' -o -name '*draft*' \) \
+    -mmin -60 2>/dev/null | head -1 || true)
+  if [ -z "$RECENT" ]; then
+    _check "workspace clean" true "no recent session/experiment files"
+  else
+    _check "workspace clean" false "recent file: $(basename "$RECENT")"
+  fi
+fi
+
+# 3. agents/recruit-sessions/ writable.
+RECRUIT_DIR="$REPO_ROOT/agents/recruit-sessions"
+if [ ! -d "$RECRUIT_DIR" ]; then
+  _check "recruit dir writable" false "missing: $RECRUIT_DIR"
+elif [ ! -w "$RECRUIT_DIR" ]; then
+  _check "recruit dir writable" false "not writable: $RECRUIT_DIR"
+else
+  _check "recruit dir writable" true "$RECRUIT_DIR"
+fi
+
+# 4. task ci green at HEAD — look at the last 'task ci' marker if it
+#    exists. /tmp/agent-config-ci-start.txt is written by _ci-start
+#    at the start of every 'task ci' run; /tmp/agent-config-ci-end.txt
+#    by _ci-end on success. Pre-flight passes when both exist AND
+#    end > start AND no .agent-src.uncondensed file is newer than end.
+START_MARKER="/tmp/agent-config-ci-start.txt"
+END_MARKER="/tmp/agent-config-ci-end.txt"
+if [ ! -f "$START_MARKER" ] || [ ! -f "$END_MARKER" ]; then
+  # Soft pass — no marker yet on a fresh checkout. The session does
+  # not need a green CI in the past 30 days; it needs no obvious red.
+  _check "task ci green" true "no recent ci marker (acceptable on fresh checkout)"
+else
+  START_TS=$(cat "$START_MARKER")
+  END_TS=$(cat "$END_MARKER")
+  if [ "$END_TS" -gt "$START_TS" ]; then
+    _check "task ci green" true "last run completed (end=$END_TS, start=$START_TS)"
+  else
+    _check "task ci green" false "last run incomplete (start=$START_TS, end=$END_TS)"
+  fi
+fi
+
+# 5. Screen recording tool — best-effort presence check.
+RECORDING_TOOL=""
+for tool in obs-cli obs loom riverside zoom; do
+  if command -v "$tool" >/dev/null 2>&1; then
+    RECORDING_TOOL="$tool"
+    break
+  fi
+done
+if [ -n "$RECORDING_TOOL" ]; then
+  _check "recording tool" true "$RECORDING_TOOL on PATH"
+else
+  # Browser-based recorders (Loom web, Zoom web, Riverside web) leave
+  # nothing on the PATH; the maintainer is presumed to test the clip
+  # the day before per _runbook.md § Scheduling. Soft pass with a hint.
+  _check "recording tool" true "no CLI recording tool detected — verify the browser/desktop app is open"
+fi
+
+if [ "$QUIET" = false ]; then
+  echo ""
+fi
+echo "recruit_preflight: ${PASS} pass / ${FAIL} fail"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0