@event4u/agent-config 8.3.0 → 8.4.1

package/dist/mcp/registry-manifest.json

@@ -9,7 +9,7 @@
     "homepage": "https://github.com/event4u-app/agent-config#readme",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "8.3.0"
+    "version": "8.4.1"
   },
   "registries": [
     {

package/docs/contracts/surface-matrix.md

@@ -0,0 +1,103 @@
+# Surface Matrix — per-tool canonical-surface contract
+
+> Machine-checked inventory of which install surface is canonical per tool,
+> which alternates are legitimate, what counts as a duplicate surface, and
+> how a duplicate converges. One data file replaces 23 hand-maintained
+> special cases (council Q3, 2026-07-07 — see
+> `agents/settings/contexts/claude-code-single-surface-decision.md` for the
+> parent decision).
+
+## The file
+
+`src/config/surface-matrix.yml` — ships in the npm package, resolved at
+runtime relative to the package root (works from both the tsx dev path and
+the bundled CLI).
+
+```yaml
+schema_version: 1
+tools:
+  <tool-id>:                # must exist in install.ts::USER_SCOPE_PATHS
+    surface: projection | plugin | bundles | export-only
+    scope_path: "~/..."     # must equal USER_SCOPE_PATHS[tool-id]
+    hooks: managed-settings-block | settings-hooks-opt-in | plugin | none
+    alternates:             # optional — legitimate secondary surfaces
+      - id: <slug>
+        role: <why it is legitimate>
+        detail: <prose>
+    duplicate:              # optional — the duplicate-surface class
+      description: <prose>
+      detect:
+        all_of: [<path>, …] # ~/ = user scope, ./ = package-relative;
+                            # ALL present ⇒ duplicate surface exists
+      # OR, when suspected but unverified:
+      pending_evidence: <prose + pointer to the evidence gate>
+    converge:               # required when detect is defined
+      action: <slug>
+      command: "<copy-paste fix>"
+      reaps: [<path>, …]    # package-tagged locations converge may remove
+    notes: <provenance>
+```
+
+## Semantics
+
+- **`surface`** — `projection` (installer writes content into the user
+  scope path; that projection is canonical), `plugin` (the tool's own
+  plugin channel is canonical — e.g. Copilot, where no user-scope
+  projection exists), `bundles` (manual import artifacts, e.g.
+  Claude Desktop ZIPs), `export-only` (config/marker export, no content
+  tree).
+- **`duplicate.detect.all_of`** — existence checks only, never content
+  reads. All paths present ⇒ the duplicate class is live. Tools without a
+  `detect` block are never flagged.
+- **`pending_evidence`** — documents a *suspected* class that MUST NOT be
+  acted on (doctor ignores it, converge refuses it) until an evidence gate
+  defines real detect paths. Current example: Augment
+  (`agents/settings/contexts/augment-surface-parity.md`).
+- **`converge`** — the consented cleanup. `converge.reaps` is the
+  exhaustive allowlist of what `agent-config converge` may remove for this
+  tool; anything outside it is refused (hard floor: never user-authored
+  files).
+
+## Consumers
+
+| Consumer | What it reads | Behavior |
+|---|---|---|
+| `agent-config doctor` (`surface-state` check) | `duplicate.detect.all_of` | Existence-checks every declared duplicate class; `fail` names the tool + the `converge.command` as copy-paste remedy. The legacy `claude-plugin` check stays as the named first consumer with richer version diagnostics. |
+| `agent-config converge` (+ `upgrade --converge`) | `converge.*` | Performs the per-tool cleanup, only on matrix-declared, package-tagged paths (`converge.reaps`), after consent (`install.auto_converge` or interactive y/N). |
+| `dispatch:hook` `surface-probe` concern | `duplicate.detect.all_of` | Once-per-day SessionStart existence probe; one-line nudge naming the duplicate + the converge command. Fail-open, never blocking. |
+| CI (`task lint-surface-matrix` → `src/scripts/lint_surface_matrix.ts`) | whole file | Set equality with `USER_SCOPE_PATHS`, scope-path drift, enum validity, detect-path resolution, converge-command presence, plugin-id drift guard. |
+
+## Onboarding a new tool
+
+1. Add the tool to `install.ts::USER_SCOPE_PATHS` (and `SCOPE_SUPPORT`,
+   deploy sources) as usual.
+2. Add the matrix entry in the same commit — `lint-surface-matrix` fails
+   the build on a missing entry (that is the point: no tool ships without
+   a declared canonical surface).
+3. Default shape for a plain projection with no plugin channel:
+   `surface: projection`, `hooks: none`, no `duplicate` block.
+4. Only add a `duplicate` block when a second install channel actually
+   exists for the tool — and only add `detect.all_of` once the class has
+   been reproduced on a real setup (evidence gate; until then use
+   `pending_evidence`).
+
+## Consent model (converge)
+
+- First `agent-config converge` run persists `install.auto_converge: true`
+  into the **global** settings file
+  (`~/.event4u/agent-config/agent-settings.yml`). The key is read directly
+  by the CLI (converge/upgrade); it is intentionally NOT part of the
+  `MERGEABLE_KEYS` whitelist — it never merges into project-level agent
+  settings and never reaches session context.
+- Plain `upgrade` without the key keeps the print-only prompt (no silent
+  mutation of a user-owned surface — council Q2, 2026-07-07).
+- `converge --dry-run` prints the exact actions without touching anything.
+
+## See also
+
+- `agents/settings/contexts/claude-code-single-surface-decision.md` —
+  parent decision (single surface for Claude Code).
+- `agents/settings/contexts/augment-surface-parity.md` — the Augment
+  evidence gate that keeps its duplicate class `pending_evidence`.
+- `docs/contracts/skill-distribution-channels.md` — canonical-channel
+  contract the matrix operationalizes.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.3.0",
+    "version": "8.4.1",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -38,6 +38,9 @@
         "dist/",
         "docs/",
         "src/scripts/",
+        "src/install/",
+        "src/agent-src/scripts/",
+        "src/agent-src/templates/scripts/",
         "src/templates/",
         "tests/fixtures/hooks/",
         "AGENTS.md",

package/src/agent-src/README.md

@@ -0,0 +1,64 @@
+# Agent Infrastructure
+
+> **⚠️ DO NOT edit files in `dist/agent-src/` or `.augment/` directly.**
+> The source of truth is `.agent-src.uncondensed/`. Edit there, then run `task sync`.
+> See `.agent-src.uncondensed/commands/condense.md` for the full workflow.
+
+This directory contains the shared agent infrastructure: skills, commands, rules, guidelines,
+templates, and contexts that power the AI coding assistant across all projects.
+
+In the package repo, this content lives in `dist/agent-src/` (shipped). Consumer projects install
+it as `.augment/` (local projection).
+
+## Directory Structure
+
+```
+├── commands/       # Slash commands — executable workflows (/fix-pr-comments, /agent-handoff, ...)
+├── contexts/       # Background context documents for the agent
+├── guidelines/     # Coding guidelines by language (reference material)
+├── rules/          # Always-active behavior rules (auto-loaded every conversation)
+├── skills/         # On-demand expertise (matched by topic)
+└── templates/      # File templates for roadmaps, features, skills, etc.
+```
+
+## How It Works
+
+| Layer | Always active? | Purpose |
+|---|---|---|
+| **Rules** | ✅ Yes | Behavior constraints — loaded every conversation |
+| **Skills** | 🔄 On demand | Expertise — matched when the topic is relevant |
+| **Commands** | ⚡ On trigger | Workflows — triggered by `/command-name` |
+| **Guidelines** | 📖 Reference | Coding conventions — read when writing code |
+| **Templates** | 📄 Blueprints | File structure templates for new documents |
+| **Contexts** | 🧠 Background | System-level context about the infrastructure |
+
+For full details see [augment-infrastructure.md](contexts/augment-infrastructure.md).
+
+## Quick Reference
+
+### Most-used commands
+
+| Command | Purpose |
+|---|---|
+| `/agent-handoff` | Generate context summary for a fresh chat |
+| `/fix-pr-comments` | Fix all open PR review comments |
+| `/quality-fix` | Run PHPStan + Rector and fix errors |
+| `/create-pr` | Create a GitHub PR with description |
+| `/bug-investigate` | Investigate a bug from Jira/Sentry |
+| `/tests-create` | Write tests for current changes |
+
+### Key rules
+
+| Rule | What it enforces |
+|---|---|
+| `verify-before-complete` | Must run tests/PHPStan before claiming "done" |
+| `scope-control` | Don't commit/push without permission, no unasked changes |
+| `token-efficiency` | Redirect output, don't narrate, trust ECS/Rector |
+| `downstream-changes` | After every edit, update ALL callers, tests, imports |
+| `php-coding` | Strict types, getters/setters, observers |
+
+## Project-Level Overrides
+
+Projects can override shared skills, rules, and commands via `agents/overrides/`.
+See [override-system.md](contexts/override-system.md) for details.
+

package/src/agent-src/scripts/archive_completed_roadmaps.ts

@@ -0,0 +1,497 @@
+#!/usr/bin/env tsx
+/**
+ * Archive completed roadmaps — the PR-gate (council 2026-06-14).
+ *
+ * TypeScript twin of `src/agent-src/scripts/archive_completed_roadmaps.py`
+ * (ADR-200, Python→TypeScript migration). The CLI contract is mirrored EXACTLY
+ * — the `--all` / `--base` / `--dry-run` flags, the argparse usage / error text
+ * (`-h`/`--help` → exit 0, unknown arg → exit 2), the `git`-shell-out semantics
+ * (argv / cwd / returncode / stdout / stderr captured via `spawnSync`, matching
+ * `subprocess.run(..., capture_output=True, text=True)`), byte-identical stdout
+ * (the `ℹ️` / `✅` summary) and stderr (the `⚠️` warnings), the
+ * `urp.collect()` completion criterion, and exit code 0. snake_case kept.
+ *
+ * A roadmap that has reached `count_open == 0` and `count_deferred == 0` is
+ * **complete**. This sweep moves it to `agents/roadmaps/archive/`, rewrites
+ * inbound references (`agents/roadmaps/<x>.md` → `agents/roadmaps/archive/<x>.md`)
+ * across tracked files so links never break, and regenerates the dashboard.
+ *
+ * It replaces the old **merge-gate** (keep one item open + a manual post-merge
+ * archival step that got forgotten — leaving finished roadmaps to rot in `main`)
+ * with a deterministic **PR-gate**: `/create-pr` runs this before the PR is
+ * created, so the roadmap lands already-archived in the PR and merges clean.
+ *
+ * Default `--changed-only`: only archive roadmaps that appear in this branch's
+ * history since it diverged from `origin/main` (`git log origin/main..HEAD`),
+ * so a PR archives exactly the roadmaps it completed — never an unrelated complete
+ * roadmap. `--all` archives every complete active roadmap. No agent-set
+ * annotation is required — completion is detected from the checkbox counts.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/archive_completed_roadmaps            # --changed-only (default)
+ *     ./scripts-run src/scripts/archive_completed_roadmaps --all
+ *     ./scripts-run src/scripts/archive_completed_roadmaps --base origin/main --dry-run
+ *
+ * --- Parity notes (ADR-200) ---
+ *
+ * - `subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)` →
+ *   `spawnSync(cmd[0], cmd.slice(1), { cwd, encoding: 'utf-8' })`, wrapped in a
+ *   `CompletedProcess`-shaped object. A spawn that fails to launch surfaces as
+ *   `returncode = -1` with the error message on `stderr` (the Python path would
+ *   raise; no test exercises a missing-git environment).
+ * - The Python `sys.path.insert(0, …); import update_roadmap_progress as urp`
+ *   becomes an eager static import of the `.ts` twin — same `collect()`
+ *   surface, no observable difference.
+ * - `_regen_dashboard` runs `[sys.executable, str(script)]`; the twin spawns
+ *   the dashboard twin via the same `tsx` runtime so the regen + `git add`
+ *   side effects match. It only fires on a non-dry-run with archived roadmaps.
+ * - JSON is not emitted. `set[str]` (touched paths) → `Set<string>`; iteration
+ *   order is never rendered, so the unordered semantics match.
+ * - `process.exitCode` is set; `process.exit()` is never called. argparse
+ *   usage errors throw `ArgparseExit(2)`; `-h`/`--help` throws `ArgparseExit(0)`.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { collect } from './update_roadmap_progress.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+interface CompletedProcess {
+    returncode: number;
+    stdout: string;
+    stderr: string;
+}
+
+class ArgparseExit extends Error {
+    code: number;
+    constructor(code: number) {
+        super(`ArgparseExit(${code})`);
+        this.name = 'ArgparseExit';
+        this.code = code;
+    }
+}
+
+/** subprocess.run(cmd, cwd=cwd, capture_output=True, text=True). */
+function _run(cmd: string[], cwd: string): CompletedProcess {
+    const res = spawnSync(cmd[0] as string, cmd.slice(1), { cwd, encoding: 'utf-8' });
+    if (res.error) {
+        return { returncode: -1, stdout: res.stdout ?? '', stderr: String(res.error.message ?? '') };
+    }
+    return {
+        returncode: res.status === null ? -1 : res.status,
+        stdout: res.stdout ?? '',
+        stderr: res.stderr ?? '',
+    };
+}
+
+function _repo_root(): string {
+    const cp = _run(['git', 'rev-parse', '--show-toplevel'], process.cwd());
+    return cp.returncode === 0 ? cp.stdout.trim() : process.cwd();
+}
+
+/** `str.splitlines()` over LF/CRLF/CR (subprocess text output). */
+function _splitlines(s: string): string[] {
+    if (s === '') return [];
+    const parts = s.split(/\r\n|\r|\n/);
+    if (parts.length && parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts;
+}
+
+/**
+ * Repo-relative paths touched in any commit since divergence from base.
+ *
+ * Returns null when the base ref is unavailable — callers treat null as
+ * "cannot scope, fall back to --all".
+ */
+function _branch_touched_paths(root: string, base: string): Set<string> | null {
+    const cp = _run(
+        ['git', 'log', `${base}..HEAD`, '--name-only', '--pretty=format:'],
+        root,
+    );
+    if (cp.returncode !== 0) {
+        return null;
+    }
+    const out = new Set<string>();
+    for (const line of _splitlines(cp.stdout)) {
+        const t = line.trim();
+        if (t) {
+            out.add(t);
+        }
+    }
+    return out;
+}
+
+/**
+ * Rewrite full-path references `old_rel` → `new_rel` in tracked files.
+ *
+ * Only the exact repo-relative path is rewritten (bare-filename mentions are
+ * left alone). The archived file's own path never matches because the search
+ * string is the un-archived path.
+ */
+function _inbound_ref_rewrite(
+    root: string,
+    old_rel: string,
+    new_rel: string,
+    dry_run: boolean,
+    tracked = true,
+): string[] {
+    const changed: string[] = [];
+    // Tracked repo → `git grep` (fast, index-aware). Untracked fallback (gap A)
+    // → walk the filesystem, since `git grep` only sees committed content and
+    // would miss every inbound ref in a pre-first-commit consumer.
+    let candidates: string[];
+    if (tracked) {
+        const grep = _run(['git', 'grep', '-l', '--', old_rel], root);
+        if (grep.returncode === 1) {
+            return changed; // no matches
+        }
+        candidates =
+            grep.returncode === 0
+                ? _splitlines(grep.stdout).map((l) => l.trim())
+                : _fs_grep_files(root, old_rel); // git grep unusable → fs walk
+    } else {
+        candidates = _fs_grep_files(root, old_rel);
+    }
+    for (const line of candidates) {
+        const rel = line.trim();
+        if (!rel || rel === old_rel) {
+            // skip the roadmap file itself
+            continue;
+        }
+        const fp = path.join(root, rel);
+        let text: string;
+        try {
+            text = fs.readFileSync(fp, { encoding: 'utf-8' });
+        } catch {
+            continue;
+        }
+        if (!text.includes(old_rel)) {
+            continue;
+        }
+        if (!dry_run) {
+            fs.writeFileSync(fp, _replaceAll(text, old_rel, new_rel), { encoding: 'utf-8' });
+        }
+        changed.push(rel);
+    }
+    return changed;
+}
+
+/** str.replace(old, new) — replace every occurrence (Python str.replace). */
+function _replaceAll(text: string, oldStr: string, newStr: string): string {
+    return text.split(oldStr).join(newStr);
+}
+
+interface MoveResult {
+    /** the move (or dry-run no-op) succeeded */
+    ok: boolean;
+    /** the move went through `git mv` (tracked); false → plain filesystem
+     *  rename was used because the repo has no commits / the file is untracked.
+     *  The caller rewrites inbound refs on the filesystem (not via `git add`)
+     *  when this is false. */
+    tracked: boolean;
+}
+
+/**
+ * Move `src_rel` → `dst_rel`, preferring `git mv`.
+ *
+ * Untracked-safe (road-to-roadmap-archival-robustness, gap A): a consumer that
+ * closed a roadmap in a pre-first-commit / untracked working tree cannot use
+ * `git mv` (it errors). Instead of printing `git mv failed` and leaving the
+ * completed roadmap to rot in the active tree, fall back to a plain
+ * `fs.renameSync`. The TS-only enhancement post-dates the deleted Python twin
+ * (ADR-200), so there is no byte-parity obligation on this failure path.
+ */
+function _git_mv(root: string, src_rel: string, dst_rel: string, dry_run: boolean): MoveResult {
+    const dst = path.join(root, dst_rel);
+    if (dry_run) {
+        return { ok: true, tracked: true };
+    }
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    const cp = _run(['git', 'mv', src_rel, dst_rel], root);
+    if (cp.returncode === 0) {
+        return { ok: true, tracked: true };
+    }
+    // Fallback: untracked file or a repo with no commits — plain rename.
+    try {
+        fs.renameSync(path.join(root, src_rel), dst);
+        return { ok: true, tracked: false };
+    } catch {
+        return { ok: false, tracked: false };
+    }
+}
+
+/**
+ * Repo-relative paths of files containing `needle`, by walking the filesystem.
+ *
+ * The untracked fallback for `_inbound_ref_rewrite`: `git grep` only sees
+ * tracked content, so in a pre-first-commit consumer it misses every inbound
+ * reference. Walk the tree (skipping `.git` / `node_modules` and obvious binary
+ * trees), read text files, and match the literal path. Bounded by skipping the
+ * heavy dirs; an untracked consumer's tree is small.
+ */
+function _fs_grep_files(root: string, needle: string): string[] {
+    const SKIP = new Set(['.git', 'node_modules', '.augment', 'dist']);
+    const hits: string[] = [];
+    const walk = (dirAbs: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.git') || SKIP.has(e.name)) {
+                continue;
+            }
+            const abs = path.join(dirAbs, e.name);
+            if (e.isDirectory()) {
+                walk(abs);
+            } else if (e.isFile() && /\.(md|json|ya?ml|ts|js|txt)$/.test(e.name)) {
+                let text: string;
+                try {
+                    text = fs.readFileSync(abs, { encoding: 'utf-8' });
+                } catch {
+                    continue;
+                }
+                if (text.includes(needle)) {
+                    hits.push(path.relative(root, abs).split(path.sep).join('/'));
+                }
+            }
+        }
+    };
+    walk(root);
+    return hits;
+}
+
+interface ArchiveRecord {
+    roadmap: string;
+    archived_to: string;
+    refs_migrated: string[];
+}
+
+/** Archive every complete active roadmap (count_open==0, count_deferred==0). */
+function archive_completed(
+    root: string,
+    opts: { changed_only: boolean; base: string; dry_run: boolean },
+): ArchiveRecord[] {
+    const { changed_only, base, dry_run } = opts;
+    const roadmap_root = path.join(root, 'agents', 'roadmaps');
+    if (!_isDir(roadmap_root)) {
+        return [];
+    }
+    const touched = changed_only ? _branch_touched_paths(root, base) : null;
+    // changed_only requested but base unavailable → conservative: archive nothing.
+    if (changed_only && touched === null) {
+        process.stderr.write(
+            `  ⚠️  cannot resolve \`${base}\` — skipping the changed-only ` +
+                'archival sweep (run with --all to force).\n',
+        );
+        return [];
+    }
+
+    const archived: ArchiveRecord[] = [];
+    for (const stats of collect(roadmap_root)) {
+        if (stats.open_ !== 0 || stats.deferred !== 0) {
+            continue; // not complete
+        }
+        const old_rel = `agents/roadmaps/${stats.rel}`;
+        if (changed_only && !(touched as Set<string>).has(old_rel)) {
+            continue; // complete, but not this branch's work
+        }
+        const new_rel = `agents/roadmaps/archive/${stats.rel}`;
+        const mv = _git_mv(root, old_rel, new_rel, dry_run);
+        if (!mv.ok) {
+            process.stderr.write(`  ⚠️  could not archive ${old_rel} (mv failed)\n`);
+            continue;
+        }
+        const refs = _inbound_ref_rewrite(root, old_rel, new_rel, dry_run, mv.tracked);
+        // Stage rewritten refs only in a tracked repo; an untracked consumer's
+        // files are not in the index, so the filesystem rewrite is the whole job.
+        if (!dry_run && refs.length && mv.tracked) {
+            _run(['git', 'add', '--', ...refs], root);
+        }
+        archived.push({ roadmap: old_rel, archived_to: new_rel, refs_migrated: refs });
+    }
+    return archived;
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function _regen_dashboard(root: string, dry_run: boolean): void {
+    if (dry_run) {
+        return;
+    }
+    const script = path.join(path.dirname(_HERE), 'update_roadmap_progress.ts');
+    // Python: `_run([sys.executable, str(script)], root)`; the twin spawns the
+    // dashboard generator twin through the same `tsx` runtime, cwd=root.
+    _runTwin(root, script);
+    const dash = path.join(root, 'agents', 'roadmaps-progress.md');
+    if (_isFile(dash)) {
+        _run(['git', 'add', '--', 'agents/roadmaps-progress.md'], root);
+    }
+}
+
+/** Spawn the dashboard generator twin (tsx) with cwd=root, mirroring `[sys.executable, script]`. */
+function _runTwin(root: string, script: string): void {
+    // Python uses `sys.executable` — the interpreter already running this
+    // script, which is always present. The TS analog is the `tsx` that owns
+    // THIS twin, found by walking up from the script's own dir (matching the
+    // canonical `run.ts` resolver), NOT the `git rev-parse` consumer-repo root
+    // (which need not carry a node_modules). Fall back to `npx tsx`.
+    const binName = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';
+    let dir = path.dirname(_HERE);
+    for (;;) {
+        const candidate = path.join(dir, 'node_modules', '.bin', binName);
+        if (fs.existsSync(candidate)) {
+            spawnSync(candidate, [script], { cwd: root, encoding: 'utf-8' });
+            return;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    spawnSync('npx', ['tsx', script], { cwd: root, encoding: 'utf-8' });
+}
+
+const _PROG = 'archive_completed_roadmaps.py';
+
+function _usage(): string {
+    return `usage: ${_PROG} [-h] [--all] [--base BASE] [--dry-run]\n`;
+}
+
+interface Args {
+    all: boolean;
+    base: string;
+    dry_run: boolean;
+}
+
+function _parseArgs(argv: readonly string[]): Args {
+    let all = false;
+    let base = 'origin/main';
+    let dry_run = false;
+    const emitError = (msg: string): never => {
+        process.stderr.write(_usage());
+        process.stderr.write(`${_PROG}: error: ${msg}\n`);
+        throw new ArgparseExit(2);
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const tok = argv[i] as string;
+        if (tok === '-h' || tok === '--help') {
+            process.stdout.write(_usage());
+            throw new ArgparseExit(0);
+        } else if (tok === '--all') {
+            all = true;
+            i += 1;
+        } else if (tok === '--dry-run') {
+            dry_run = true;
+            i += 1;
+        } else if (tok === '--base') {
+            const val = argv[i + 1];
+            if (val === undefined) {
+                emitError('argument --base: expected one argument');
+            }
+            base = val as string;
+            i += 2;
+        } else if (tok.startsWith('--base=')) {
+            base = tok.slice('--base='.length);
+            i += 1;
+        } else {
+            emitError(`unrecognized arguments: ${tok}`);
+        }
+    }
+    return { all, base, dry_run };
+}
+
+function main(argv?: readonly string[]): number {
+    const ns = _parseArgs(argv ?? process.argv.slice(2));
+
+    const root = _repo_root();
+    const archived = archive_completed(root, {
+        changed_only: !ns.all,
+        base: ns.base,
+        dry_run: ns.dry_run,
+    });
+    if (archived.length === 0) {
+        process.stdout.write('  ℹ️  No completed roadmaps to archive.\n');
+        return 0;
+    }
+    _regen_dashboard(root, ns.dry_run);
+    const verb = ns.dry_run ? 'Would archive' : 'Archived';
+    for (const rec of archived) {
+        process.stdout.write(
+            `  ✅  ${verb}: ${rec.roadmap} → ${rec.archived_to}` +
+                (rec.refs_migrated.length
+                    ? `  (${rec.refs_migrated.length} ref(s) migrated)`
+                    : '') +
+                '\n',
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via `.augment/scripts` → `dist/agent-src/scripts`,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the symlink
+    // path. Compare realpaths so the entry guard still fires (without this the
+    // archival sweep silently no-ops when run through the symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    try {
+        process.exitCode = main();
+    } catch (exc) {
+        if (exc instanceof ArgparseExit) {
+            process.exitCode = exc.code;
+        } else {
+            throw exc;
+        }
+    }
+}
+
+export {
+    archive_completed,
+    main,
+    _branch_touched_paths,
+    _inbound_ref_rewrite,
+    _git_mv,
+    _repo_root,
+};
+export type { ArchiveRecord, CompletedProcess };