@event4u/agent-config 3.3.0 → 4.1.0

package/scripts/propose_modules_config.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Propose a ``modules:`` block for ``.agent-project-settings.yml``.
+
+Phase B Step 2 of road-to-configurable-modules. Wraps the pure
+:mod:`scripts._lib.module_detection` helper in a CLI surface that the
+installer, the GUI wizard, and the ``/agents init`` command can all call
+without re-implementing the detection table.
+
+Usage:
+    python3 scripts/propose_modules_config.py                  # interactive
+    python3 scripts/propose_modules_config.py --json           # machine-readable
+    python3 scripts/propose_modules_config.py --project <path> # custom root
+
+Exit codes:
+    0 — candidates surfaced (or none found, with ``modules.enabled: false``)
+    2 — invalid arguments / unreachable path
+
+The CLI never writes files. Callers consume the JSON / TTY output and
+patch ``.agent-project-settings.yml`` themselves (preserves comments +
+ordering per the layered-settings contract).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Re-export so consumers can import either path.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from scripts._lib.module_detection import (  # noqa: E402
+    ModuleCandidate,
+    detect_module_roots,
+)
+
+
+def _candidate_to_dict(cand: ModuleCandidate) -> dict[str, str]:
+    return {
+        "path": cand.path,
+        "stack": cand.stack,
+        "namespace_template_guess": cand.namespace_template_guess,
+        "confidence": cand.confidence,
+    }
+
+
+def _render_interactive(candidates: list[ModuleCandidate]) -> None:
+    """Print a numbered-options block — the same shape ``/agents init`` shows."""
+    if not candidates:
+        print("⚠️  No module roots detected.")
+        print()
+        print(
+            "Skipping `modules:` config. Re-run after adding a module "
+            "directory (app/Modules/, src/Module/, packages/, internal/, ...)."
+        )
+        return
+    print("📦 Detected module-root candidates:")
+    print()
+    print("  #  Path              Stack            Confidence  Namespace template")
+    print("  ─  ────────────────  ───────────────  ──────────  ────────────────────")
+    for idx, cand in enumerate(candidates, start=1):
+        ns = cand.namespace_template_guess or "—"
+        print(
+            f"  {idx:>1}  {cand.path:<16}  {cand.stack:<15}"
+            f"  {cand.confidence:<10}  {ns}"
+        )
+    print()
+    print("Suggested `modules:` block (paste into .agent-project-settings.yml):")
+    print()
+    print("modules:")
+    print("  enabled: true")
+    print(f"  root_paths: [{', '.join(c.path for c in candidates)}]")
+    primary_ns = next(
+        (c.namespace_template_guess for c in candidates
+         if c.namespace_template_guess),
+        "",
+    )
+    if primary_ns:
+        print(f"  namespace_template: '{primary_ns}'")
+    else:
+        print("  # namespace_template: ''  # stack has no PHP-style namespace")
+    print("  agent_folder: agents")
+    print("  skip_dirs: [.module-template, .example]")
+
+
+def _resolve_project_root(arg: str | None) -> Path:
+    if arg:
+        root = Path(arg).expanduser().resolve()
+    else:
+        root = Path.cwd().resolve()
+    if not root.is_dir():
+        print(
+            f"error: project root is not a directory: {root}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    return root
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="propose_modules_config.py",
+        description=(
+            "Detect module-root candidates and propose a `modules:` block "
+            "for .agent-project-settings.yml. Pure read-only scan."
+        ),
+    )
+    parser.add_argument(
+        "--project",
+        default=None,
+        help="project root (default: cwd)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="emit machine-readable JSON instead of the TTY table",
+    )
+    args = parser.parse_args(argv)
+    root = _resolve_project_root(args.project)
+    candidates = detect_module_roots(root)
+    if args.json:
+        payload = {
+            "project_root": str(root),
+            "candidates": [_candidate_to_dict(c) for c in candidates],
+            "proposed_block": {
+                "enabled": bool(candidates),
+                "root_paths": [c.path for c in candidates],
+                "namespace_template": next(
+                    (c.namespace_template_guess for c in candidates
+                     if c.namespace_template_guess),
+                    "",
+                ),
+                "agent_folder": "agents",
+                "skip_dirs": [".module-template", ".example"],
+            },
+        }
+        json.dump(payload, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        return 0
+    _render_interactive(candidates)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/scripts/prototype_lint_contradictions.py

@@ -31,7 +31,7 @@ import time
 from pathlib import Path
 
 REPO = Path(__file__).resolve().parent.parent
-SRC = REPO / ".agent-src.uncompressed"
+SRC = REPO / ".agent-src.uncondensed"
 
 ARTIFACT_DIRS = {
     "rule": SRC / "rules",

package/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)"
+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

package/scripts/refine_ticket_detect.py

@@ -2,7 +2,7 @@
 """Deterministic detection helper for the refine-ticket skill.
 
 Reads the detection-map.yml from
-.agent-src.uncompressed/skills/refine-ticket/ (or the projected copy),
+.agent-src.uncondensed/skills/refine-ticket/ (or the projected copy),
 takes ticket body text, and returns a structured decision — which
 sub-skills should fire, which keywords matched, and an
 orchestration-notes line per sub-skill ready to fold into the skill
@@ -34,7 +34,7 @@ except ImportError as exc:
 REPO_ROOT = Path(__file__).resolve().parent.parent
 
 # Post-monorepo Phase 4 the detection map lives under any package's
-# .agent-src.uncompressed/. Discover it via the shared helper; fall
+# .agent-src.uncondensed/. Discover it via the shared helper; fall
 # back to the legacy flat path so consumers and older sub-trees still
 # work.
 import sys as _sys  # noqa: E402
@@ -54,7 +54,7 @@ def _discover_default_map() -> Path:
                 return candidate
     return (
         REPO_ROOT
-        / ".agent-src.uncompressed"
+        / ".agent-src.uncondensed"
         / "skills"
         / "refine-ticket"
         / "detection-map.yml"

package/scripts/release.py

@@ -33,6 +33,16 @@ Each step prints what it's about to do before doing it, so a crash
 leaves a recoverable trail.
 
 Stdlib-only (Python 3.10+). No third-party runtime dependencies.
+
+See also:
+    - docs/contracts/release-pr-gating.md — release-PR shape, cut surface,
+      kept surface, fail-closed contract.
+    - docs/contracts/branch-protection-policy.md — per-PR-shape
+      required-check matrix; `task ci:required-checks` previews it.
+    - docs/contracts/ci-cost-budget.md — measured baselines + quarterly
+      review cadence.
+    - .github/workflows/release-validation.yml — the tight release-PR
+      validation jobs (release-shape, changelog-entry, version-consistency).
 """
 
 from __future__ import annotations
@@ -623,6 +633,16 @@ def print_preview(plan: Plan) -> None:
     print(plan.changelog_entry.rstrip())
     print("─" * 72)
     print()
+    print("Release-PR CI shape (docs/contracts/release-pr-gating.md):")
+    print(
+        "  will run: Consistency · Smoke Contracts · Migration Dry-Run · "
+        "Release Validation · Release Guard (post-tag, ~30 s)"
+    )
+    print(
+        "  will skip: Tests (install / aux / python / node / windows-lockfile-export) · "
+        "Public Install Smoke — heavy install matrices cannot be regressed by a release-shape diff"
+    )
+    print()
 
 
 def confirm(prompt: str) -> bool:

package/scripts/render_benchmark_md.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""Render `docs/benchmark.md` from the latest paired A/B bench reports.
+
+Phase 5 Step 1 of `agents/roadmaps/road-to-package-impact-benchmark.md`.
+
+Reads:
+  - internal/bench/reports/ab/{stamp}-ab-tracka-{with,without}.json (latest pair)
+  - internal/bench/reports/ab/{stamp}-ab-trackb-{with,without}.json (latest pair)
+  - any matching diff under internal/bench/reports/ab/diff/
+
+Emits: `docs/benchmark.md`. The renderer is deterministic — it does not run
+any bench; it only formats existing reports. `task bench:ab` calls this last;
+`task bench:ab:diff` calls it alone.
+
+Sections of the rendered file:
+  - Headline (delta table)
+  - Track A — behavioural
+  - Track B — task completion
+  - Methodology (target shape, corpus versions, claude CLI version, timestamps)
+  - History (last 5 runs)
+
+If no reports exist yet, the script writes a placeholder document explaining
+how to produce one — never errors out, so the file is always a real
+description of the current bench state.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+REPORTS_DIR = REPO_ROOT / "internal" / "bench" / "reports" / "ab"
+DIFF_DIR = REPORTS_DIR / "diff"
+OUT_PATH = REPO_ROOT / "docs" / "benchmark.md"
+
+REQUIRED_SECTIONS = (
+    "## Headline",
+    "## Track A",
+    "## Track B",
+    "## Methodology",
+    "## History",
+)
+
+
+def utc_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def latest_pair(corpus: str) -> tuple[Path | None, Path | None]:
+    """Return the (with, without) report pair for a corpus, both with the same stamp.
+
+    If only one variant has a fresh report, the other position is None.
+    """
+    with_reports = sorted(REPORTS_DIR.glob(f"*-{corpus}-with.json"))
+    without_reports = sorted(REPORTS_DIR.glob(f"*-{corpus}-without.json"))
+    if not with_reports and not without_reports:
+        return None, None
+    # Latest of each — they don't have to share stamps; the diff handles that.
+    return (
+        with_reports[-1] if with_reports else None,
+        without_reports[-1] if without_reports else None,
+    )
+
+
+def latest_diff(corpus: str) -> Path | None:
+    diffs = sorted(DIFF_DIR.glob(f"*-{corpus}-diff.json"))
+    return diffs[-1] if diffs else None
+
+
+def safe_load(path: Path | None) -> dict:
+    if path is None or not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError:
+        return {}
+
+
+def fmt_pct(value: float | None) -> str:
+    if value is None:
+        return "—"
+    return f"{value * 100:.1f}%"
+
+
+def fmt_num(value: float | None, places: int = 2) -> str:
+    if value is None:
+        return "—"
+    return f"{value:.{places}f}"
+
+
+def render_headline(track_a: dict, track_b: dict) -> str:
+    a_results = (track_a.get("with") or {}).get("results", {})
+    a_without = (track_a.get("without") or {}).get("results", {})
+    b_results = (track_b.get("with") or {}).get("results", {})
+    b_without = (track_b.get("without") or {}).get("results", {})
+    a_with_acc = a_results.get("trigger_accuracy")
+    a_wo_acc = a_without.get("trigger_accuracy")
+    b_with_comp = b_results.get("completion_rate")
+    b_wo_comp = b_without.get("completion_rate")
+    lines = [
+        "## Headline",
+        "",
+        "| Metric | with | without | delta |",
+        "|---|---|---|---|",
+        f"| Track A trigger-accuracy | {fmt_pct(a_with_acc)} | {fmt_pct(a_wo_acc)} | "
+        f"{fmt_pct((a_with_acc or 0) - (a_wo_acc or 0))} |",
+        f"| Track B completion-rate  | {fmt_pct(b_with_comp)} | {fmt_pct(b_wo_comp)} | "
+        f"{fmt_pct((b_with_comp or 0) - (b_wo_comp or 0))} |",
+        f"| Track B mean wall-time   | {fmt_num(b_results.get('mean_wall_time'))}s "
+        f"| {fmt_num(b_without.get('mean_wall_time'))}s | "
+        f"{fmt_num((b_results.get('mean_wall_time') or 0) - (b_without.get('mean_wall_time') or 0))}s |",
+        f"| Track B ask-vs-act ratio | {fmt_num(b_results.get('ask_vs_act_ratio'), 3)} "
+        f"| {fmt_num(b_without.get('ask_vs_act_ratio'), 3)} | — |",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def render_track_a(track_a: dict) -> str:
+    with_data = (track_a.get("with") or {}).get("results", {})
+    without_data = (track_a.get("without") or {}).get("results", {})
+    lines = ["## Track A — Behavioural eval", ""]
+    if not with_data and not without_data:
+        lines.append("_No Track A reports yet. Run `task bench:ab:track-a`._")
+        lines.append("")
+        return "\n".join(lines)
+    lines.extend(
+        [
+            f"- with → **{fmt_pct(with_data.get('trigger_accuracy'))}** "
+            f"({with_data.get('matched', 0)}/{with_data.get('total', 0)})",
+            f"- without → **{fmt_pct(without_data.get('trigger_accuracy'))}** "
+            f"({without_data.get('matched', 0)}/{without_data.get('total', 0)})",
+            f"- integrity OK: `{track_a.get('with', {}).get('integrity_ok', '—')}`",
+            "",
+            "Per-target presence (sample):",
+            "",
+        ]
+    )
+    per_target = with_data.get("per_target_present", {})
+    for i, (target, score) in enumerate(sorted(per_target.items())):
+        if i >= 10:
+            lines.append(f"- … {len(per_target) - 10} more")
+            break
+        lines.append(f"- `{target}` → with={score}, without=0")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_track_b(track_b: dict) -> str:
+    lines = ["## Track B — Task completion", ""]
+    with_data = (track_b.get("with") or {}).get("results", {})
+    without_data = (track_b.get("without") or {}).get("results", {})
+    mode = with_data.get("mode") or without_data.get("mode") or "—"
+    lines.append(f"- Mode: `{mode}`")
+    if not with_data and not without_data:
+        lines.append("")
+        lines.append("_No Track B reports yet. Run `task bench:ab:track-b`._")
+        lines.append("")
+        return "\n".join(lines)
+    lines.extend(
+        [
+            f"- with → **{fmt_pct(with_data.get('completion_rate'))}** "
+            f"({with_data.get('passed', 0)}/{with_data.get('total', 0)})",
+            f"- without → **{fmt_pct(without_data.get('completion_rate'))}** "
+            f"({without_data.get('passed', 0)}/{without_data.get('total', 0)})",
+            "",
+            "Per-category:",
+            "",
+            "| Category | with | without | delta |",
+            "|---|---|---|---|",
+        ]
+    )
+    with_cats = with_data.get("per_category", {})
+    without_cats = without_data.get("per_category", {})
+    for cat in sorted(set(with_cats) | set(without_cats)):
+        w = with_cats.get(cat, {}).get("completion_rate") or 0
+        wo = without_cats.get(cat, {}).get("completion_rate") or 0
+        lines.append(
+            f"| {cat} | {fmt_pct(w)} | {fmt_pct(wo)} | {fmt_pct(w - wo)} |"
+        )
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_methodology(track_a: dict, track_b: dict) -> str:
+    with_report = track_a.get("with") or track_b.get("with") or {}
+    cache_key = with_report.get("cache_key", {})
+    lines = [
+        "## Methodology",
+        "",
+        "- **Target shape:** Shape A (neutral TypeScript fixture under `internal/bench/ab/fixture/`).",
+        "- **Variants:** `with` clone inherits `.claude/`, `.augment/`, `AGENTS.md`, "
+        "`CLAUDE.md` from the package root; `without` does not.",
+        "- **Integrity:** `python3 scripts/bench_ab_integrity.py` exits 0 on every run "
+        "(clones differ only at the agent-config surface).",
+        "- **Scoring:** structural only (no LLM judge). See `scripts/_lib/bench_ab_scoring.py`.",
+        "",
+        "Cache key for the latest run:",
+        "",
+    ]
+    if cache_key:
+        for k in ("corpus_hash", "claude_cli_version", "target_shape_hash"):
+            lines.append(f"- `{k}`: `{cache_key.get(k, '—')}`")
+    else:
+        lines.append("- _no cache key recorded yet_")
+    lines.append("")
+    lines.append(f"- **Last rendered:** `{utc_iso()}`")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_history() -> str:
+    lines = ["## History", "", "Last 5 runs (per corpus):", ""]
+    for corpus in ("ab-tracka", "ab-trackb"):
+        lines.append(f"### `{corpus}`")
+        lines.append("")
+        reports = sorted(
+            REPORTS_DIR.glob(f"*-{corpus}-with.json"), reverse=True
+        )[:5]
+        if not reports:
+            lines.append("_no runs yet_")
+            lines.append("")
+            continue
+        for report in reports:
+            try:
+                data = json.loads(report.read_text())
+            except json.JSONDecodeError:
+                continue
+            results = data.get("results") or {}
+            metric = (
+                results.get("trigger_accuracy")
+                if corpus == "ab-tracka"
+                else results.get("completion_rate")
+            )
+            lines.append(f"- `{data.get('stamp', '—')}` → {fmt_pct(metric)}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def render_placeholder() -> str:
+    return (
+        "# Package-Impact A/B Benchmark\n"
+        "\n"
+        "_No A/B bench reports yet._ Produce one with:\n"
+        "\n"
+        "```sh\n"
+        "task bench:ab\n"
+        "```\n"
+        "\n"
+        "Methodology lives in `agents/roadmaps/road-to-package-impact-benchmark.md` "
+        "and `internal/bench/ab/README.md`.\n"
+        f"\n_Last rendered: {utc_iso()}_\n"
+    )
+
+
+def render(quiet: bool = False) -> int:
+    a_with, a_without = latest_pair("ab-tracka")
+    b_with, b_without = latest_pair("ab-trackb")
+    track_a = {"with": safe_load(a_with), "without": safe_load(a_without)}
+    track_b = {"with": safe_load(b_with), "without": safe_load(b_without)}
+    have_data = bool(
+        track_a["with"] or track_a["without"] or track_b["with"] or track_b["without"]
+    )
+    if not have_data:
+        OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
+        OUT_PATH.write_text(render_placeholder())
+        if not quiet:
+            sys.stdout.write(
+                f"render_benchmark_md: no reports — wrote placeholder to {OUT_PATH.relative_to(REPO_ROOT)}\n"
+            )
+        return 0
+    parts = [
+        "# Package-Impact A/B Benchmark",
+        "",
+        "> Generated by `scripts/render_benchmark_md.py`. Source of truth: "
+        "`internal/bench/reports/ab/`. Re-render anytime with `task bench:ab:diff`.",
+        "",
+        render_headline(track_a, track_b),
+        render_track_a(track_a),
+        render_track_b(track_b),
+        render_methodology(track_a, track_b),
+        render_history(),
+    ]
+    OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    OUT_PATH.write_text("\n".join(parts))
+    if not quiet:
+        sys.stdout.write(
+            f"render_benchmark_md: wrote {OUT_PATH.relative_to(REPO_ROOT)}\n"
+        )
+    return 0
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Render docs/benchmark.md from A/B reports.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress stdout.")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    return render(quiet=args.quiet)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/roadmap_progress_hook.py

@@ -100,7 +100,7 @@ def _resolve_regenerator(consumer_root: Path) -> Path | None:
     for candidate in (
         consumer_root / ".augment" / "scripts" / "update_roadmap_progress.py",
         consumer_root / ".agent-src" / "scripts" / "update_roadmap_progress.py",
-        consumer_root / ".agent-src.uncompressed" / "scripts" / "update_roadmap_progress.py",
+        consumer_root / ".agent-src.uncondensed" / "scripts" / "update_roadmap_progress.py",
     ):
         if candidate.is_file():
             return candidate