@event4u/agent-config 3.3.0 → 4.2.0

package/scripts/_lib/module_detection.py

@@ -0,0 +1,223 @@
+"""Detect module root directories from a project tree.
+
+Phase B of road-to-configurable-modules. Lifts the multi-stack
+detection table from ``commands/module/explore.md`` Step 1 into a
+reusable, pure Python helper that the installer, onboarding wizard,
+and ``/agents init`` flow all share.
+
+Contract — pure, read-only, tolerant:
+
+* :func:`detect_module_roots` walks the candidate paths once and
+  reports every directory that *exists*. It never creates files,
+  never recurses past the first level needed to score confidence,
+  and silently skips paths it cannot read.
+* The return shape is a list of :class:`ModuleCandidate` typed
+  dicts ordered by descending confidence; callers may turn that
+  list straight into numbered options.
+* Confidence is a three-step ladder:
+
+  - ``high`` — directory exists *and* its first level contains
+    plausible module subdirectories for the stack.
+  - ``medium`` — directory exists but is empty / unclear; still
+    surfaced so the installer can ask the user.
+  - Absent paths are skipped entirely; they never appear in the
+    output.
+
+No interactive logic, no settings I/O, no logging side-effects.
+Settings wiring lives in ``scripts/install.py`` (Step 2) and the
+GUI wizard (Step 3).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+#: Directory entry names that never count as modules. Mirrors the
+#: ``modules.skip_dirs`` default from
+#: ``templates/agents/agent-project-settings.example.yml``.
+_SKIP_DIRS: frozenset[str] = frozenset({
+    ".module-template",
+    ".example",
+})
+
+#: Path segments that exclude a file from module-like detection.
+#: Vendored dependencies, build artefacts, VCS state, IDE config —
+#: never a real module no matter what shape the parent directory has.
+_NOISE_SEGMENTS: frozenset[str] = frozenset({
+    "vendor",
+    "node_modules",
+    ".git",
+    ".idea",
+    ".vscode",
+    "dist",
+    "build",
+    "tmp",
+    "var",
+    "storage",
+    "bootstrap",
+    "public",
+    ".venv",
+    "venv",
+    "__pycache__",
+})
+
+#: Parent directory names that hint at a module layout when their
+#: immediate child is a non-noise segment (i.e. ``Modules/User/...``,
+#: ``packages/foo/...``). Case-sensitive — ``Modules`` (Laravel HMVC)
+#: differs from ``modules`` (Node convention) intentionally; both are
+#: accepted.
+_MODULE_PARENTS: frozenset[str] = frozenset({
+    "Modules",
+    "modules",
+    "packages",
+    "apps",
+    "internal",
+})
+
+
+def is_module_like_path(rel_path: str) -> bool:
+    """Return ``True`` when ``rel_path`` sits inside a module-shaped tree.
+
+    Heuristic for the ``module-detect-on-the-fly`` skill: triggered by
+    repo-relative POSIX paths the agent is about to edit or reference.
+    A path is *module-like* when:
+
+    1. None of its segments are in :data:`_NOISE_SEGMENTS` (vendored,
+       build, VCS, IDE state — never a real module).
+    2. At least one segment matches :data:`_MODULE_PARENTS` AND has a
+       non-noise sibling directly underneath (so ``Modules/`` alone
+       does not trigger, but ``Modules/User/...`` does).
+
+    Pure, case-sensitive on parent names. Empty / dotted / Windows-style
+    inputs return ``False``. The function never touches the filesystem
+    — callers pass in a path string they already know about.
+    """
+    if not rel_path:
+        return False
+    normalised = rel_path.replace("\\", "/").strip("/")
+    if not normalised:
+        return False
+    parts = normalised.split("/")
+    for segment in parts:
+        if segment in _NOISE_SEGMENTS:
+            return False
+    for idx, segment in enumerate(parts[:-1]):
+        if segment not in _MODULE_PARENTS:
+            continue
+        child = parts[idx + 1]
+        if not child or child.startswith("."):
+            continue
+        if child in _SKIP_DIRS:
+            continue
+        return True
+    return False
+
+
+@dataclass(frozen=True)
+class ModuleCandidate:
+    """One detected module-root candidate.
+
+    Attributes mirror the JSON shape callers ultimately persist into
+    ``modules.root_paths`` (the ``path`` field) plus metadata used
+    by the installer to phrase the numbered-options prompt.
+    """
+
+    path: str
+    """Repo-relative POSIX path of the module root (e.g. ``app/Modules``)."""
+
+    stack: str
+    """Stack identifier — one of ``laravel-hmvc``, ``symfony-ddd``,
+    ``node-monorepo``, ``python-src``, ``go-internal``, ``composer-src``."""
+
+    namespace_template_guess: str
+    """PHP-style namespace template with ``{ModuleName}`` placeholder
+    (e.g. ``App\\Modules\\{ModuleName}``). Empty string for stacks
+    without a PHP-style namespace (Node, Python, Go)."""
+
+    confidence: str
+    """One of ``high`` or ``medium`` per the ladder in the module
+    docstring."""
+
+
+# Detection rules — order encodes priority when two rules match the
+# same directory. ``namespace_template`` is the value emitted as
+# ``namespace_template_guess`` on a hit; empty for non-PHP stacks.
+_RULES: tuple[tuple[str, str, str], ...] = (
+    ("app/Modules", "laravel-hmvc", "App\\Modules\\{ModuleName}"),
+    ("src/Module", "symfony-ddd", "App\\Module\\{ModuleName}"),
+    ("packages", "node-monorepo", ""),
+    ("apps", "node-monorepo", ""),
+    ("modules", "node-monorepo", ""),
+    ("src", "python-src", ""),
+    ("internal", "go-internal", ""),
+    ("cmd", "go-internal", ""),
+)
+
+
+def _list_module_subdirs(root: Path) -> list[Path]:
+    """Return first-level subdirectories of ``root`` that look like modules."""
+    try:
+        entries = sorted(root.iterdir())
+    except (OSError, PermissionError):
+        return []
+    out: list[Path] = []
+    for entry in entries:
+        if not entry.is_dir():
+            continue
+        if entry.name.startswith("."):
+            continue
+        if entry.name in _SKIP_DIRS:
+            continue
+        out.append(entry)
+    return out
+
+
+def _score_confidence(stack: str, subdirs: Iterable[Path]) -> str:
+    """Return ``high`` when ``subdirs`` looks like a populated module root."""
+    subdirs_list = list(subdirs)
+    if not subdirs_list:
+        return "medium"
+    if stack in {"laravel-hmvc", "symfony-ddd"}:
+        capitalized = [d for d in subdirs_list if d.name[:1].isupper()]
+        return "high" if capitalized else "medium"
+    if stack == "node-monorepo":
+        with_pkg_json = [d for d in subdirs_list if (d / "package.json").is_file()]
+        return "high" if with_pkg_json else "medium"
+    if stack == "python-src":
+        with_init = [d for d in subdirs_list if (d / "__init__.py").is_file()]
+        return "high" if with_init else "medium"
+    if stack == "go-internal":
+        return "high" if subdirs_list else "medium"
+    return "medium"
+
+
+def detect_module_roots(project_root: Path) -> list[ModuleCandidate]:
+    """Return module-root candidates discovered under ``project_root``.
+
+    Pure read-only scan. Walks each rule in :data:`_RULES`, reports
+    every directory that exists, and never recurses past the first
+    level needed to score confidence. Order: ``high`` first, then
+    ``medium``; rule order breaks ties. Absent paths never appear
+    in the output.
+    """
+    project_root = Path(project_root)
+    high: list[ModuleCandidate] = []
+    medium: list[ModuleCandidate] = []
+    for rel_path, stack, namespace_template in _RULES:
+        abs_path = project_root / rel_path
+        if not abs_path.is_dir():
+            continue
+        subdirs = _list_module_subdirs(abs_path)
+        confidence = _score_confidence(stack, subdirs)
+        candidate = ModuleCandidate(
+            path=rel_path,
+            stack=stack,
+            namespace_template_guess=namespace_template,
+            confidence=confidence,
+        )
+        if confidence == "high":
+            high.append(candidate)
+        else:
+            medium.append(candidate)
+    return high + medium

package/scripts/_lib/scope_guard.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# scope_guard.sh — detect cross-scope install drift for event4u/agent-config.
+#
+# Roadmap reference: road-to-clean-skill-distribution-channels.md, Phase B Step 2.
+# Contract: docs/contracts/skill-distribution-channels.md + docs/contracts/install-scopes.md.
+#
+# Pre-install hook called by scripts/install.sh. Detects whether the same package
+# is already installed at the OTHER scope (user-global vs project-local) for any
+# of the six supported tools. Emits one verdict per tool plus a global verdict
+# on stdout (one finding per line).
+#
+# Verdicts (per the roadmap contract):
+#   OK     — no install at the other scope; the install can proceed.
+#   WARN   — install at the other scope, SAME version as the one being installed.
+#            Same content; duplicate registration but no drift.
+#   DRIFT  — install at the other scope, DIFFERENT version (or unreadable).
+#            Drift will produce the 2026-05-25 failure mode (stale frontmatter
+#            registered alongside fresh frontmatter).
+#
+# Output shape (line-oriented, parseable by install.sh):
+#   <verdict>\t<tool-id>\t<other-scope-path>\t<other-version>\t<this-version>
+#
+# A final summary line is emitted:
+#   SUMMARY\t<verdict>\t<count-OK>\t<count-WARN>\t<count-DRIFT>
+#
+# The script exits 0 always — verdict interpretation is the caller's job.
+
+set -euo pipefail
+
+THIS_SCOPE="${1:-project}"   # project|user — which scope we're ABOUT to install to
+SOURCE_DIR="${2:-}"          # package source repo (read version from here)
+TARGET_DIR="${3:-}"          # consumer install root for "this" scope
+
+# Default SOURCE_DIR to the package root when invoked from inside this repo.
+if [[ -z "$SOURCE_DIR" ]]; then
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+fi
+
+# Resolve the version we're about to install. Authoritative source:
+# package.json at the package root (release.py keeps this current).
+this_version() {
+    local pkg="$SOURCE_DIR/package.json"
+    [[ -f "$pkg" ]] || { echo "unknown"; return; }
+    # Tiny scoped parser — no jq / python dependency.
+    awk -F'"' '/"version":/ { print $4; exit }' "$pkg" 2>/dev/null || echo "unknown"
+}
+
+# Resolve the version recorded at a given install root. Falls back through
+# package.json → .augment-plugin/plugin.json → "unknown".
+installed_version_at() {
+    local root="$1"
+    if [[ -f "$root/package.json" ]]; then
+        awk -F'"' '/"version":/ { print $4; exit }' "$root/package.json" 2>/dev/null && return
+    fi
+    if [[ -f "$root/.augment-plugin/plugin.json" ]]; then
+        awk -F'"' '/"version":/ { print $4; exit }' "$root/.augment-plugin/plugin.json" 2>/dev/null && return
+    fi
+    echo "unknown"
+}
+
+# Heuristic: does this look like an agent-config install (vs a vanilla user
+# directory with the same path layout)? We accept "looks like" if the tool
+# directory contains ≥ N entries that ALSO exist in the SOURCE_DIR tree —
+# but we keep the check coarse: simply that the directory is non-empty.
+dir_nonempty() {
+    [[ -d "$1" ]] && [[ -n "$(ls -A "$1" 2>/dev/null | head -1)" ]]
+}
+
+# Per-tool probe definitions: tool-id, user-scope path, project-scope path.
+# Project-scope path is relative to "$TARGET_DIR" (or "$HOME/<proj>" for user).
+probe_tool() {
+    local tool="$1"
+    local user_path="$2"
+    local project_path="$3"
+
+    local other_path other_scope this_scope_path
+    if [[ "$THIS_SCOPE" == "project" ]]; then
+        this_scope_path="$project_path"
+        other_path="$user_path"
+        other_scope="user"
+    else
+        this_scope_path="$user_path"
+        other_path="$project_path"
+        other_scope="project"
+    fi
+
+    if ! dir_nonempty "$other_path"; then
+        printf 'OK\t%s\t-\t-\t%s\n' "$tool" "$(this_version)"
+        return
+    fi
+
+    local other_root other_ver
+    # Walk up from the tool directory to find the install root (containing
+    # package.json or .augment-plugin/plugin.json).
+    other_root="$(cd "$other_path/.." 2>/dev/null && pwd)" || other_root=""
+    if [[ -n "$other_root" ]]; then
+        # Look up to 3 levels up for an install root.
+        local probe="$other_root"
+        for _ in 1 2 3; do
+            if [[ -f "$probe/package.json" ]] || [[ -f "$probe/.augment-plugin/plugin.json" ]]; then
+                other_root="$probe"
+                break
+            fi
+            probe="$(dirname "$probe")"
+            [[ "$probe" == "/" ]] && break
+        done
+    fi
+    other_ver="$(installed_version_at "$other_root")"
+
+    local this_ver
+    this_ver="$(this_version)"
+
+    if [[ "$other_ver" == "unknown" ]] || [[ "$this_ver" == "unknown" ]] || [[ "$other_ver" != "$this_ver" ]]; then
+        printf 'DRIFT\t%s\t%s\t%s\t%s\n' "$tool" "$other_path" "$other_ver" "$this_ver"
+    else
+        printf 'WARN\t%s\t%s\t%s\t%s\n' "$tool" "$other_path" "$other_ver" "$this_ver"
+    fi
+}
+
+main() {
+    # Resolve target root for project-scope probes.
+    local project_root="${TARGET_DIR:-$(pwd)}"
+    local home_root="${HOME:-/tmp}"
+
+    local count_ok=0 count_warn=0 count_drift=0 finding
+
+    # Each probe_tool call prints exactly one line. Use
+    # assignment-arithmetic (returns 0) rather than post-increment
+    # (returns the OLD value — 0 trips `set -e` on the first OK hit
+    # under bash 5+ / GitHub Actions runners).
+    while IFS= read -r finding; do
+        echo "$finding"
+        case "${finding%%$'\t'*}" in
+            OK)    count_ok=$((count_ok + 1))       ;;
+            WARN)  count_warn=$((count_warn + 1))   ;;
+            DRIFT) count_drift=$((count_drift + 1)) ;;
+        esac
+    done < <(
+        probe_tool claude-code "$home_root/.claude/skills" "$project_root/.claude/skills"
+        probe_tool augment     "$home_root/.augment/skills" "$project_root/.augment/skills"
+        probe_tool cursor      "$home_root/.cursor/rules"  "$project_root/.cursor/rules"
+        probe_tool cline       "$home_root/.clinerules"    "$project_root/.clinerules"
+        probe_tool windsurf    "$home_root/.windsurf/rules" "$project_root/.windsurf/rules"
+        probe_tool copilot     "$home_root/.github/copilot-instructions.md" "$project_root/.github/copilot-instructions.md"
+    )
+
+    local overall
+    if [[ $count_drift -gt 0 ]]; then
+        overall=DRIFT
+    elif [[ $count_warn -gt 0 ]]; then
+        overall=WARN
+    else
+        overall=OK
+    fi
+    printf 'SUMMARY\t%s\t%d\t%d\t%d\n' "$overall" "$count_ok" "$count_warn" "$count_drift"
+}
+
+# Allow sourcing without executing (so other scripts can call individual
+# functions). Only run main() when invoked directly.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

package/scripts/_phase4_bucket.py

@@ -2,7 +2,7 @@
 """R3 Phase 4 — one-off artefact-to-pack bucket map.
 
 Encodes the council-locked mapping for all skills/rules/commands under
-.agent-src.uncompressed/. Run with `--check` to emit a CSV preview;
+.agent-src.uncondensed/. Run with `--check` to emit a CSV preview;
 run with `--pack <id>` to print the artefact paths for that pack so
 the annotator can consume them via xargs.
 
@@ -17,7 +17,7 @@ import sys
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[1]
-SRC = ROOT / ".agent-src.uncompressed"
+SRC = ROOT / ".agent-src.uncondensed"
 
 # Explicit per-name overrides (highest priority). Use when domain/keyword
 # heuristics misclassify. Council Q3 fallback is applied only if no entry.
@@ -80,7 +80,7 @@ NAME_TO_PACK: dict[str, str] = {
     "video-director": "ai-video", "canvas-design": "ai-video",
     # Meta (agent-config maintenance)
     "ai-council": "meta", "command-routing": "meta", "command-writing": "meta",
-    "compress-memory": "meta", "context-authoring": "meta", "context-document": "meta",
+    "condense-memory": "meta", "context-authoring": "meta", "context-document": "meta",
     "copilot-agents-optimization": "meta", "copilot-config": "meta",
     "description-assist": "meta", "guideline-writing": "meta",
     "learning-to-rule-or-skill": "meta", "lint-skills": "meta",

package/scripts/_pilot_measure.py

@@ -1,4 +1,4 @@
-"""Pilot compression ratio + Iron-Law checksum verification (one-off, not CI)."""
+"""Pilot condensation ratio + Iron-Law checksum verification (one-off, not CI)."""
 import sys, re, hashlib, statistics
 from pathlib import Path
 
@@ -15,9 +15,9 @@ def iron_law_sha(body: str) -> str:
 
 
 pairs = [
-    ("agent-authority",   ".agent-src.uncompressed/rules/agent-authority.md",   "docs/contracts/pilot/agent-authority.md"),
-    ("direct-answers",    ".agent-src.uncompressed/rules/direct-answers.md",    "docs/contracts/pilot/direct-answers.md"),
-    ("language-and-tone", ".agent-src.uncompressed/rules/language-and-tone.md", "docs/contracts/pilot/language-and-tone.md"),
+    ("agent-authority",   ".agent-src.uncondensed/rules/agent-authority.md",   "docs/contracts/pilot/agent-authority.md"),
+    ("direct-answers",    ".agent-src.uncondensed/rules/direct-answers.md",    "docs/contracts/pilot/direct-answers.md"),
+    ("language-and-tone", ".agent-src.uncondensed/rules/language-and-tone.md", "docs/contracts/pilot/language-and-tone.md"),
 ]
 
 header = f"{'rule':25s} {'orig':>6s}  {'pilot':>6s}  {'r':>6s}  {'budget':>7s}  {'sha-orig':>16s}  {'sha-pilot':>16s}  {'IL':>3s}"

package/scripts/_tmp_scan_framework_leakage.py

@@ -11,7 +11,7 @@ import re
 import sys
 from pathlib import Path
 
-ROOT = Path(".agent-src.uncompressed")
+ROOT = Path(".agent-src.uncondensed")
 
 CARVE_OUT_PATTERNS = [
     r"laravel", r"^php-", r"^eloquent", r"^blade", r"^livewire", r"^flux",

package/scripts/adoption_report.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Roll up ``adoption-snapshots.jsonl`` into a Markdown trend report.
+
+Phase D Step 3 of ``road-to-adoption-proof-and-ci-green.md``.
+Reads the JSONL produced by ``scripts/adoption_snapshot.py`` and
+writes an ``agents/runtime/metrics/adoption-report.md`` snapshot
+covering an 8-week rolling window per signal.
+
+Mirrors the shape of ``scripts/skill_usage_report.py``: a single
+file, ≤ 200 LOC, no external deps. The report is regenerated on
+every invocation (idempotent for a given JSONL state).
+
+CLI:
+
+  scripts/adoption_report.py [--in <path>] [--out <path>] [--weeks 8]
+
+  --in                  JSONL input (default
+                        ``agents/runtime/metrics/adoption-snapshots.jsonl``).
+  --out                 Markdown output (default
+                        ``agents/runtime/metrics/adoption-report.md``).
+  --weeks               Window size (default 8).
+
+Exit codes:
+
+  0 — report written.
+  1 — IO failure on read or write.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_IN = REPO_ROOT / "agents" / "runtime" / "metrics" / "adoption-snapshots.jsonl"
+DEFAULT_OUT = REPO_ROOT / "agents" / "runtime" / "metrics" / "adoption-report.md"
+
+
+def parse_jsonl(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    if not path.exists():
+        return rows
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+def filter_window(rows: list[dict[str, Any]], weeks: int) -> list[dict[str, Any]]:
+    if not rows:
+        return rows
+    cutoff = dt.datetime.now(dt.timezone.utc) - dt.timedelta(weeks=weeks)
+    out: list[dict[str, Any]] = []
+    for r in rows:
+        ts = r.get("snapshot_at", "")
+        try:
+            when = dt.datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(
+                tzinfo=dt.timezone.utc
+            )
+        except ValueError:
+            continue
+        if when >= cutoff:
+            out.append(r)
+    return out
+
+
+def render_section(title: str, lines: list[str]) -> str:
+    return f"## {title}\n\n" + "\n".join(lines) + "\n\n"
+
+
+def render_npm_downloads(rows: list[dict[str, Any]]) -> str:
+    lines = []
+    lines.append("| Snapshot | Last 7 days (npm installs) |")
+    lines.append("|---|---:|")
+    for r in rows:
+        signal = r.get("signals", {}).get("npm_downloads", {})
+        if "error" in signal:
+            cell = f"_(error: {signal['error'][:40]})_"
+        else:
+            cell = f"{signal.get('last_7_days', 0):,}"
+        lines.append(f"| `{r.get('snapshot_at', '?')}` | {cell} |")
+    return render_section("npm install count (last 7 days, weekly snapshot)", lines)
+
+
+def render_npm_version(rows: list[dict[str, Any]]) -> str:
+    lines = []
+    lines.append("| Snapshot | Latest version | Version count |")
+    lines.append("|---|---|---:|")
+    for r in rows:
+        signal = r.get("signals", {}).get("npm_version", {})
+        if "error" in signal:
+            lines.append(f"| `{r.get('snapshot_at', '?')}` | _(error)_ | _(error)_ |")
+        else:
+            latest = signal.get("latest", "?")
+            count = signal.get("version_count", 0)
+            lines.append(f"| `{r.get('snapshot_at', '?')}` | `{latest}` | {count} |")
+    return render_section("npm version distribution", lines)
+
+
+def render_github_stars(rows: list[dict[str, Any]]) -> str:
+    lines = []
+    lines.append("| Snapshot | Stars | Forks | Watchers |")
+    lines.append("|---|---:|---:|---:|")
+    for r in rows:
+        signal = r.get("signals", {}).get("github_stars", {})
+        if "error" in signal:
+            lines.append(f"| `{r.get('snapshot_at', '?')}` | _(error)_ | _(error)_ | _(error)_ |")
+        else:
+            lines.append(
+                f"| `{r.get('snapshot_at', '?')}` | "
+                f"{signal.get('stars', 0):,} | "
+                f"{signal.get('forks', 0):,} | "
+                f"{signal.get('watchers', 0):,} |"
+            )
+    return render_section("GitHub stars / forks / watchers", lines)
+
+
+def render_topic_rank(rows: list[dict[str, Any]]) -> str:
+    lines = []
+    lines.append("| Snapshot | `agent-skills` rank | `cinematic-ai-video` rank |")
+    lines.append("|---|---:|---:|")
+    for r in rows:
+        signal = r.get("signals", {}).get("topic_rank", {})
+        as_block = signal.get("agent-skills", {})
+        cav_block = signal.get("cinematic-ai-video", {})
+        as_rank = "_(error)_" if "error" in as_block else (as_block.get("rank") or "—")
+        cav_rank = "_(error)_" if "error" in cav_block else (cav_block.get("rank") or "—")
+        lines.append(
+            f"| `{r.get('snapshot_at', '?')}` | {as_rank} | {cav_rank} |"
+        )
+    return render_section("Topic-search rank (`agent-skills` + `cinematic-ai-video`)", lines)
+
+
+def render_report(rows: list[dict[str, Any]], weeks: int) -> str:
+    header = (
+        "# Adoption report — rolling trend\n\n"
+        f"> Generated by `scripts/adoption_report.py` from "
+        f"`agents/runtime/metrics/adoption-snapshots.jsonl`.\n"
+        f"> Window: rolling {weeks} weeks. Source contract: "
+        f"`docs/contracts/adoption-signal-floor.md`.\n\n"
+    )
+    if not rows:
+        header += (
+            "_No snapshots in the current window — run `python3 scripts/adoption_snapshot.py` "
+            "(scheduled weekly via the cron in `.github/workflows/`) to populate the trend._\n"
+        )
+        return header
+    return (
+        header
+        + render_npm_downloads(rows)
+        + render_npm_version(rows)
+        + render_github_stars(rows)
+        + render_topic_rank(rows)
+    )
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(prog="adoption_report")
+    p.add_argument("--in", dest="in_path", type=Path, default=DEFAULT_IN)
+    p.add_argument("--out", type=Path, default=DEFAULT_OUT)
+    p.add_argument("--weeks", type=int, default=8)
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        rows = parse_jsonl(args.in_path)
+    except OSError as exc:
+        print(f"error: failed to read {args.in_path}: {exc}", file=sys.stderr)
+        return 1
+    rows = filter_window(rows, args.weeks)
+    rows.sort(key=lambda r: r.get("snapshot_at", ""))
+    report = render_report(rows, args.weeks)
+    try:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(report, encoding="utf-8")
+    except OSError as exc:
+        print(f"error: failed to write {args.out}: {exc}", file=sys.stderr)
+        return 1
+    print(f"adoption_report: wrote {args.out} ({len(rows)} snapshot(s))")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())