@event4u/agent-config 3.3.0 → 4.2.0

package/scripts/ci_status.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""Wrap ``gh run list`` and assert the required-check set is green.
+
+Phase A Step 6 of ``road-to-adoption-proof-and-ci-green.md``. Sits
+between the maintainer and the GitHub UI so a one-line
+``task ci:status`` shows whether the required-check floor (as defined
+in ``docs/contracts/branch-protection-policy.md`` § Per-PR-shape
+required-check matrix) is green on the branch passed via ``--branch``.
+
+Phantom 0-job runs are filtered before the tally — they are listed
+under "advisory / phantom" in ``docs/contracts/ci-green-floor.md`` and
+must not freeze merges (the ``--strict`` flag honours this).
+
+CLI:
+
+  scripts/ci_status.py [--branch main] [--limit 30] [--strict]
+                       [--shape feature|release|docs] [--json]
+
+Exit codes:
+
+  0 — every required check on the most recent run is success
+      (or the matching workflow simply has not run yet under
+      ``--strict``; the gate distinguishes "missing" from "red").
+  1 — at least one required-check workflow is red or in a
+      terminal-non-success state.
+  2 — invalid arguments / unreachable gh CLI.
+
+The required-check shape vocabulary mirrors
+``branch-protection-policy.md`` exactly so a future ruleset edit in
+one place stays single-sourced.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+# Source-of-truth for the per-shape required-check set. Anchored to
+# the matrix in docs/contracts/branch-protection-policy.md § Per-PR-shape
+# required-check matrix. When that doc changes, this dict changes in
+# lockstep — a CI-side linter cross-checks the two surfaces.
+REQUIRED_CHECKS_BY_SHAPE: dict[str, set[str]] = {
+    "feature": {
+        "Consistency",
+        "Smoke Contracts",
+        "Skill Lint",
+        "Tests",
+        "Python Version Sweep",
+        "Public Install Smoke",
+    },
+    "release": {
+        "Consistency",
+        "Smoke Contracts",
+        "Release Validation",
+    },
+    "docs": {
+        "Consistency",
+        "Smoke Contracts",
+    },
+}
+
+
+@dataclass(frozen=True)
+class Run:
+    name: str
+    conclusion: str
+    status: str
+    jobs: int
+
+
+def fetch_runs(branch: str, limit: int) -> list[Run]:
+    """Call `gh run list` and return parsed Run records."""
+    if shutil.which("gh") is None:
+        raise SystemExit("error: gh CLI not found in PATH")
+    cmd = [
+        "gh",
+        "run",
+        "list",
+        "--branch",
+        branch,
+        "--limit",
+        str(limit),
+        "--json",
+        "databaseId,name,status,conclusion",
+    ]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    except subprocess.CalledProcessError as exc:
+        raise SystemExit(f"error: gh run list failed — {exc.stderr.strip()}")
+    raw = json.loads(proc.stdout or "[]")
+    runs: list[Run] = []
+    for r in raw:
+        # `gh run list` does not surface Jobs count — we need a second
+        # call per run id to find phantom 0-job runs. Keep that call to
+        # the runs that *would* be counted (non-success terminal) so the
+        # cost is bounded by the number of red runs, not the full window.
+        runs.append(
+            Run(
+                name=r.get("name", ""),
+                conclusion=r.get("conclusion", ""),
+                status=r.get("status", ""),
+                jobs=-1,  # unknown — resolved lazily for non-success runs
+            )
+        )
+    return runs
+
+
+def resolve_jobs_count(run_id: int) -> int:
+    """Return the number of jobs for a single run id (for phantom filter)."""
+    cmd = [
+        "gh",
+        "run",
+        "view",
+        str(run_id),
+        "--json",
+        "jobs",
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        return -1
+    data = json.loads(proc.stdout or "{}")
+    return len(data.get("jobs", []))
+
+
+def is_phantom(run: Run) -> bool:
+    """True when the run has 0 jobs AND its conclusion is `failure`."""
+    if run.conclusion != "failure":
+        return False
+    if run.jobs == 0:
+        return True
+    return False
+
+
+def latest_per_workflow(runs: list[Run]) -> dict[str, Run]:
+    """Pick the latest run per workflow name (input order is mtime-desc)."""
+    out: dict[str, Run] = {}
+    for r in runs:
+        if r.name in out:
+            continue
+        if r.status != "completed":
+            # In-progress / queued runs are pending; treat as unknown.
+            continue
+        out[r.name] = r
+    return out
+
+
+def compute_status(
+    runs: list[Run],
+    required: set[str],
+    resolve_jobs: bool = True,
+) -> tuple[list[tuple[str, Run]], list[str], list[tuple[str, Run]]]:
+    """Return (greens, missing, reds-after-phantom-filter)."""
+    by_name = latest_per_workflow(runs)
+    greens: list[tuple[str, Run]] = []
+    reds: list[tuple[str, Run]] = []
+    missing: list[str] = []
+    for name in sorted(required):
+        run = by_name.get(name)
+        if run is None:
+            missing.append(name)
+            continue
+        if run.conclusion == "success":
+            greens.append((name, run))
+            continue
+        # Non-success — check for phantom 0-job.
+        if resolve_jobs and run.jobs < 0:
+            # Resolve the jobs count for this single run lazily.
+            # We don't have the database id in our Run records (the JSON
+            # field is `databaseId` and we dropped it for brevity); refetch
+            # the latest red run for this workflow by name.
+            run_id = _latest_run_id_for_workflow(name, run)
+            jobs_count = resolve_jobs_count(run_id) if run_id else -1
+            run = Run(
+                name=run.name,
+                conclusion=run.conclusion,
+                status=run.status,
+                jobs=jobs_count,
+            )
+        if is_phantom(run):
+            # Phantom — filter out; treat as success-equivalent for gating.
+            greens.append((name, run))
+        else:
+            reds.append((name, run))
+    return greens, missing, reds
+
+
+# Cache for the lazy run-id lookup; keyed by workflow name + conclusion.
+_RUN_ID_CACHE: dict[tuple[str, str], int | None] = {}
+
+
+def _latest_run_id_for_workflow(name: str, run: Run) -> int | None:
+    """Refetch the latest run id for a workflow whose top-of-list run is non-success."""
+    key = (name, run.conclusion)
+    if key in _RUN_ID_CACHE:
+        return _RUN_ID_CACHE[key]
+    cmd = [
+        "gh",
+        "run",
+        "list",
+        "--workflow",
+        name,
+        "--limit",
+        "1",
+        "--json",
+        "databaseId",
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        _RUN_ID_CACHE[key] = None
+        return None
+    data = json.loads(proc.stdout or "[]")
+    if not data:
+        _RUN_ID_CACHE[key] = None
+        return None
+    rid = int(data[0].get("databaseId", 0)) or None
+    _RUN_ID_CACHE[key] = rid
+    return rid
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="ci_status",
+        description="Assert the required-check set is green on a branch.",
+    )
+    p.add_argument(
+        "--branch",
+        default="main",
+        help="Branch to check (default: main).",
+    )
+    p.add_argument(
+        "--limit",
+        type=int,
+        default=30,
+        help="Number of recent runs to scan (default: 30).",
+    )
+    p.add_argument(
+        "--shape",
+        choices=["feature", "release", "docs"],
+        default="feature",
+        help="PR shape (default: feature) — picks the required-check set.",
+    )
+    p.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit non-zero if any required check is missing (not just red).",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit JSON instead of human-readable text.",
+    )
+    p.add_argument(
+        "--no-phantom-resolve",
+        action="store_true",
+        help="Skip the lazy 0-job lookup (faster but lets phantoms through).",
+    )
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    required = REQUIRED_CHECKS_BY_SHAPE[args.shape]
+    runs = fetch_runs(args.branch, args.limit)
+    greens, missing, reds = compute_status(
+        runs,
+        required,
+        resolve_jobs=not args.no_phantom_resolve,
+    )
+
+    if args.json:
+        out = {
+            "branch": args.branch,
+            "shape": args.shape,
+            "required": sorted(required),
+            "green": [name for name, _ in greens],
+            "missing": missing,
+            "red": [{"name": name, "conclusion": run.conclusion} for name, run in reds],
+        }
+        print(json.dumps(out, indent=2))
+    else:
+        print(f"branch={args.branch} shape={args.shape} required={len(required)}")
+        for name, _ in greens:
+            print(f"  ✅  {name}")
+        for name in missing:
+            print(f"  ⚠️   {name} — no run found on this branch (last {args.limit})")
+        for name, run in reds:
+            print(f"  ❌  {name} — {run.conclusion}")
+
+    if reds:
+        return 1
+    if args.strict and missing:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/ci_time_ratio.py

@@ -62,7 +62,7 @@ def classify(sha: str) -> str:
     if not files:
         return "empty"
     doc = sum(1 for f in files if f.startswith("docs/") or f.endswith(".md"))
-    skill = sum(1 for f in files if "/skills/" in f or f.startswith(".agent-src.uncompressed/skills/"))
+    skill = sum(1 for f in files if "/skills/" in f or f.startswith(".agent-src.uncondensed/skills/"))
     test = sum(1 for f in files if f.startswith("tests/") or "/tests/" in f)
     meta = sum(1 for f in files if f.startswith(("Taskfile", "scripts/", ".github/", "pyproject", "package")))
     total = len(files)

package/scripts/cleanup_other_scope.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# cleanup_other_scope.sh — remove a stale agent-config install at the OTHER
+# scope (typically ~/.claude/skills/ when working in a project-local install).
+#
+# Roadmap: road-to-clean-skill-distribution-channels.md, Phase B Step 5.
+# Companion to scripts/_lib/scope_guard.sh. Refuses to run without --confirm
+# per `non-destructive-by-default`.
+#
+# Usage:
+#   bash scripts/cleanup_other_scope.sh                      # dry-run, list what would be removed
+#   bash scripts/cleanup_other_scope.sh --confirm            # actually delete
+#   bash scripts/cleanup_other_scope.sh --confirm --user     # default — remove user-global tree
+#   bash scripts/cleanup_other_scope.sh --confirm --project /path/to/proj
+#                                                            # remove from a specific project root
+#
+# What it removes (subject to --tools selection):
+#   .claude/skills/                — Claude project-local skill tree
+#   .augment/                       — Augment substrate
+#   .cursor/rules/                  — Cursor rules tree
+#   .clinerules/                    — Cline rules tree
+#   .windsurf/rules/                — Windsurf rules tree
+#   .github/copilot-instructions.md — Copilot single-file
+#
+# What it NEVER removes without explicit overrides:
+#   .agent-settings.yml             — settings the operator may have edited
+#   agents/                          — project-local content authored by the user
+#   any path outside the scoped roots
+
+set -euo pipefail
+
+SCOPE="user"
+SCOPE_ROOT=""
+TOOLS_FILTER="all"
+DRY_RUN=true
+
+usage() {
+    cat <<'EOF'
+Usage: bash scripts/cleanup_other_scope.sh [--confirm] [--user | --project <dir>] [--tools <list>]
+
+Removes a stale agent-config install at the OTHER scope (user-global by default).
+Refuses to delete anything without --confirm.
+
+Options:
+  --confirm              Actually remove files. Default is dry-run (lists only).
+  --user                 Operate on $HOME (user-global scope). Default.
+  --project <dir>        Operate on a specific project root.
+  --tools <list>         Comma-separated tool IDs (default: all).
+                         Choices: claude-code, augment, cursor, cline, windsurf, copilot.
+  --help, -h             Show this help.
+
+Examples:
+  bash scripts/cleanup_other_scope.sh                                 # dry-run, user scope
+  bash scripts/cleanup_other_scope.sh --confirm                       # delete user-global tree
+  bash scripts/cleanup_other_scope.sh --confirm --tools=claude-code   # delete only ~/.claude/skills/
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --confirm)         DRY_RUN=false; shift ;;
+        --user)            SCOPE="user"; shift ;;
+        --project)
+            if [[ $# -lt 2 ]] || [[ "$2" == --* ]]; then
+                echo "❌  --project requires a path argument." >&2
+                exit 1
+            fi
+            SCOPE="project"; SCOPE_ROOT="$2"; shift 2 ;;
+        --project=*)       SCOPE="project"; SCOPE_ROOT="${1#*=}"; shift ;;
+        --tools)           TOOLS_FILTER="$2"; shift 2 ;;
+        --tools=*)         TOOLS_FILTER="${1#*=}"; shift ;;
+        --help|-h)         usage; exit 0 ;;
+        *)                 echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+    esac
+done
+
+is_tool() {
+    [[ "$TOOLS_FILTER" == "all" ]] && return 0
+    case ",$TOOLS_FILTER," in
+        *,"$1",*) return 0 ;;
+    esac
+    return 1
+}
+
+# Resolve scope root.
+if [[ "$SCOPE" == "user" ]]; then
+    SCOPE_ROOT="${HOME:-/tmp}"
+elif [[ -z "$SCOPE_ROOT" ]]; then
+    echo "❌  --project requires a path." >&2
+    exit 1
+fi
+if [[ ! -d "$SCOPE_ROOT" ]]; then
+    echo "❌  Scope root not found: $SCOPE_ROOT" >&2
+    exit 1
+fi
+
+declare -a targets=()
+is_tool claude-code && {
+    targets+=("$SCOPE_ROOT/.claude/skills")
+    targets+=("$SCOPE_ROOT/.claude/rules")
+    targets+=("$SCOPE_ROOT/.claude-plugin/marketplace.json")
+}
+is_tool augment      && {
+    targets+=("$SCOPE_ROOT/.augment")
+    targets+=("$SCOPE_ROOT/.augment-plugin")
+}
+is_tool cursor       && targets+=("$SCOPE_ROOT/.cursor/rules")
+is_tool cline        && targets+=("$SCOPE_ROOT/.clinerules")
+is_tool windsurf     && {
+    targets+=("$SCOPE_ROOT/.windsurf/rules")
+    targets+=("$SCOPE_ROOT/.windsurfrules")
+}
+is_tool copilot      && targets+=("$SCOPE_ROOT/.github/copilot-instructions.md")
+
+if [[ ${#targets[@]} -eq 0 ]]; then
+    echo "❌  No tools selected (--tools=$TOOLS_FILTER)." >&2
+    exit 1
+fi
+
+echo "Scope:   $SCOPE ($SCOPE_ROOT)"
+echo "Tools:   $TOOLS_FILTER"
+echo "Mode:    $($DRY_RUN && echo 'DRY RUN (use --confirm to delete)' || echo 'DELETE')"
+echo ""
+
+removed=0
+skipped=0
+for t in "${targets[@]}"; do
+    if [[ -e "$t" ]] || [[ -L "$t" ]]; then
+        if $DRY_RUN; then
+            echo "  would remove: $t"
+        else
+            rm -rf "$t"
+            echo "  removed:      $t"
+        fi
+        ((removed++)) || true
+    else
+        ((skipped++)) || true
+    fi
+done
+
+echo ""
+if $DRY_RUN; then
+    echo "✅  Dry-run complete: $removed entries would be removed, $skipped already absent."
+    echo "    Re-run with --confirm to apply."
+else
+    echo "✅  Cleanup complete: $removed entries removed, $skipped already absent."
+fi

package/scripts/compile_router.py

@@ -1,12 +1,12 @@
 #!/usr/bin/env python3
 """Compile rule frontmatter into ``router.json``.
 
-Reads ``.agent-src.uncompressed/rules/*.md``; produces deterministic JSON
+Reads ``.agent-src.uncondensed/rules/*.md``; produces deterministic JSON
 mapping kernel + tier-1 + tier-2 rules to their triggers and routed
 artifacts, per ``docs/contracts/rule-router.md``.
 
 Stdlib-only, deterministic (sorted keys + sorted lists), idempotent.
-Wired into ``task generate-tools`` after the compress step.
+Wired into ``task generate-tools`` after the condense step.
 """
 from __future__ import annotations
 
@@ -16,20 +16,20 @@ from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
 # ADR-017: rules now live across multiple source roots. Legacy
-# .agent-src.uncompressed/rules/ is kept as a fallback for the
-# pure-compressed consumer projection.
-RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
+# .agent-src.uncondensed/rules/ is kept as a fallback for the
+# pure-condensed consumer projection.
+RULES_DIR = ROOT / ".agent-src.uncondensed" / "rules"
 OUT_PATH = ROOT / "dist" / "router.json"
 SETTINGS_PATH = ROOT / ".agent-settings.yml"
 SCHEMA_VERSION = 1
 
 # Compile-time rule toggles. Maps rule-id → settings predicate.
 # Rule omitted from router.json when predicate returns False.
-# Per road-to-token-frugality § Phase 8.2 — caveman.speak compile-time toggle.
+# Per road-to-token-frugality § Phase 8.2 — telegraph.speak compile-time toggle.
 COMPILE_TIME_TOGGLES = {
-    "caveman-speak": lambda s: bool(
-        s.get("caveman", {}).get("enabled", True)
-    ) and bool(s.get("caveman", {}).get("speak", True)),
+    "telegraph-speak": lambda s: bool(
+        s.get("telegraph", {}).get("enabled", True)
+    ) and bool(s.get("telegraph", {}).get("speak", True)),
 }
 
 # Maps legacy tier values to the router-canonical names. See
@@ -132,7 +132,7 @@ def _iter_rule_files() -> list[Path]:
     seen: dict[str, Path] = {}
     roots = artefact_roots()
     if not roots:
-        # Pure-compressed fallback for consumer projections that vendor
+        # Pure-condensed fallback for consumer projections that vendor
         # the flat .agent-src/ tree without sources.
         if RULES_DIR.exists():
             for path in sorted(RULES_DIR.glob("*.md")):