@event4u/agent-config 14.7.0 → 14.8.0

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

@@ -0,0 +1,212 @@
+// The `--check` tracked/untracked mode table for the roadmap dashboard.
+//
+// Extracted from `update_roadmap_progress.ts` so the verdict is a pure function
+// over observable state — the generator does the I/O, this decides. It also
+// keeps that script under its per-file size cap.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+
+/**
+ * Is the dashboard expected to be a committed artefact? Explicit, never
+ * inferred from git state — an unconditional "absent means pass" cannot tell a
+ * correctly-untracked repo from a generator that silently stopped producing
+ * output. `tracked` is the default and the historical behaviour.
+ */
+export type DashboardMode = 'tracked' | 'untracked';
+
+/**
+ * Is `abs` in the git index? Used only by `--check --untracked-mode`, to tell
+ * "correctly absent" from "still committed". No git at all answers `false`,
+ * which is correct: nothing is tracked there.
+ */
+export function isTrackedInGit(abs: string, repo_root: string): boolean {
+    const r = spawnSync('git', ['ls-files', '--error-unmatch', '--', abs], {
+        cwd: repo_root,
+        encoding: 'utf-8',
+        timeout: 10_000,
+    });
+    return r.status === 0;
+}
+
+export interface DashboardStateInput {
+    mode: DashboardMode;
+    /** Is the file on disk? */
+    present: boolean;
+    /** Is the file in the git index? Only consulted in `untracked` mode. */
+    trackedInGit: boolean;
+    /** Does the on-disk content equal a fresh render? Only meaningful if present. */
+    current: boolean;
+    /** Repo-relative path, for the messages. */
+    rel: string;
+    /**
+     * How to regenerate, for the stale/missing messages. Defaults to the
+     * dashboard's own command. A second caller — `build_archive_index --check`
+     * — reuses this table for a different generated artefact, and a message
+     * telling that reader to run the dashboard generator would be wrong.
+     */
+    regen?: string;
+    /**
+     * What the artefact is called in the "deliberately does not commit the X"
+     * hint. Defaults to `dashboard` so every existing message is byte-identical.
+     */
+    noun?: string;
+}
+
+export interface DashboardStateVerdict {
+    /** True when the dashboard half of `--check` fails. */
+    stale: boolean;
+    /** Diagnostic for stderr, or null. */
+    error: string | null;
+    /** Success line for stdout, or null when `stale`. */
+    ok: string | null;
+}
+
+// The SOURCE path, not `.augment/scripts/…`: that tree is a gitignored
+// projection built by `task sync`, so the advice failed outright in a fresh
+// worktree and in any CI step ordered before the sync.
+const REGEN =
+    'Run `./scripts-run src/agent-src/scripts/update_roadmap_progress` ' +
+    'to regenerate (or `task roadmap-progress` in Taskfile projects).';
+
+/**
+ * The mode table:
+ *
+ *   tracked:   absent -> fail | present+stale -> fail | present+current -> pass
+ *   untracked: in-index -> fail | absent -> pass | present+stale -> fail
+ *              | present+current -> pass
+ *
+ * Absence is distinguished ONLY in untracked mode; a present file is
+ * freshness-checked in both, so untracked never means unchecked.
+ */
+export function evaluateDashboardState(inp: DashboardStateInput): DashboardStateVerdict {
+    const { mode, present, trackedInGit, current, rel } = inp;
+    const regen = inp.regen ?? REGEN;
+    const noun = inp.noun ?? 'dashboard';
+
+    if (mode === 'untracked' && trackedInGit) {
+        // Migration incomplete: declared untracked, still carried by git.
+        // Print the fix; never run it — git-index ops are the user's.
+        return {
+            stale: true,
+            error:
+                `❌  ${rel} is still tracked by git, but this repository runs ` +
+                '`--untracked-mode`. Untrack it, keeping the working-tree file:\n' +
+                `      git rm --cached ${rel}\n`,
+            ok: null,
+        };
+    }
+
+    if (!present) {
+        if (mode === 'tracked') {
+            return {
+                stale: true,
+                error:
+                    `❌  ${rel} is missing. ` +
+                    regen.replace('to regenerate', 'to generate it') +
+                    ' If this repository deliberately does not commit the ' +
+                    `${noun}, pass \`--untracked-mode\`.\n`,
+                ok: null,
+            };
+        }
+        // untracked + absent: the declared state. "up to date" would mislead.
+        return {
+            stale: false,
+            error: null,
+            ok: `✅  ${rel} is not committed here (--untracked-mode) and no stale copy is on disk.\n`,
+        };
+    }
+
+    if (!current) {
+        return { stale: true, error: `❌  ${rel} is stale. ${regen}\n`, ok: null };
+    }
+    return { stale: false, error: null, ok: `✅  ${rel} is up to date.\n` };
+}
+
+/**
+ * `evaluateDashboardState` against the real filesystem and git index. The
+ * generator hands over the paths; every read the verdict needs happens here, so
+ * the caller's check branch stays three lines.
+ */
+export function evaluateDashboardOnDisk(opts: {
+    mode: DashboardMode;
+    target: string;
+    repo_root: string;
+    rendered: string;
+    rel: string;
+    regen?: string;
+    noun?: string;
+}): DashboardStateVerdict {
+    const present = fs.existsSync(opts.target);
+    return evaluateDashboardState({
+        mode: opts.mode,
+        present,
+        trackedInGit: opts.mode === 'untracked' && isTrackedInGit(opts.target, opts.repo_root),
+        current: present && fs.readFileSync(opts.target, { encoding: 'utf-8' }) === opts.rendered,
+        rel: opts.rel,
+        ...(opts.regen === undefined ? {} : { regen: opts.regen }),
+        ...(opts.noun === undefined ? {} : { noun: opts.noun }),
+    });
+}
+
+/** One roadmap row, as far as the estate report below needs it. */
+export interface EstateRow {
+    rel: string;
+    done: number;
+    total_active: number;
+    deferred: number;
+}
+
+/**
+ * The `--check` report: the artefact's own verdict, then the estate-wide
+ * conditions — completed-but-unarchived, and Iron Law 3 deferred items.
+ *
+ * `dashboardOnly` drops the estate half. Two obligations with two blast radii:
+ * the artefact verdict is about ONE file and is safe behind a required status
+ * check, while the estate conditions are about roadmaps an unrelated change
+ * never touched, so requiring them turns any pre-existing estate defect into a
+ * merge block on every PR. It did, on 2026-08-22.
+ *
+ * Extracted from the generator so the report is a pure function of the verdict
+ * and two lists — and because the generator sits exactly on its 1500-line
+ * source ceiling, where the honest way to add a feature is to take lines out.
+ */
+export function reportCheckVerdict(inp: {
+    verdict: DashboardStateVerdict;
+    complete: readonly EstateRow[];
+    pending: readonly EstateRow[];
+    dashboardOnly: boolean;
+    warnMergeGated: () => void;
+    gatedCount: number;
+}): { rc: number; stdout: string; stderr: string } {
+    const { verdict, dashboardOnly } = inp;
+    const complete = dashboardOnly ? [] : inp.complete;
+    const pending = dashboardOnly ? [] : inp.pending;
+    let err = verdict.error ?? '';
+    if (complete.length) {
+        err +=
+            '❌  Completed roadmaps are still in `agents/roadmaps/` — ' +
+            'move them to `agents/roadmaps/archive/` (per the ' +
+            '`roadmap-progress-sync` rule):\n';
+        for (const r of complete) err += `      - ${r.rel}  (${r.done}/${r.total_active} done)\n`;
+    }
+    if (pending.length) {
+        err +=
+            '❌  Iron Law 3 — roadmaps with unresolved `[~]` deferred ' +
+            'items must NOT auto-archive. Resolve via `roadmap-management § 4b` ' +
+            '(spawn follow-up, restore, or cancel):\n';
+        for (const r of pending) {
+            err += `      - ${r.rel}  (${r.done}/${r.total_active} done · ${r.deferred} deferred)\n`;
+        }
+    }
+    if (!dashboardOnly && inp.gatedCount > 0) inp.warnMergeGated();
+    const rc = verdict.stale || complete.length > 0 || pending.length > 0 ? 1 : 0;
+    return { rc, stdout: rc === 0 ? (verdict.ok ?? '') : '', stderr: err };
+}
+
+/** `--tracked-mode` / `--untracked-mode` → the mode, or null for any other token. */
+export function parseModeToken(tok: string): DashboardMode | null {
+    if (tok === '--tracked-mode') return 'tracked';
+    if (tok === '--untracked-mode') return 'untracked';
+    return null;
+}

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

@@ -64,6 +64,12 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { run_archival_sweep } from './archival_sweep.js';
+import {
+    evaluateDashboardOnDisk,
+    parseModeToken,
+    reportCheckVerdict,
+    type DashboardMode,
+} from './dashboard_mode.js';
 import type * as YamlModule from 'yaml';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -998,8 +1004,9 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null, roadmap_root
         // script name covers the rest.
         '> Auto-generated — do not edit. Regenerate with `task roadmap-progress` ' +
             'or by running the `update_roadmap_progress` script for your install; ' +
-            'rewritten on every roadmap create / execute / completion change ' +
-            '(timestamp lives in git history).\n>\n' +
+            'rewritten on every roadmap create / execute / completion change. ' +
+            'A repository that does not commit this file has no git history for ' +
+            'it — regenerate to see the current state.\n>\n' +
             header_meta,
     );
     lines.push('## Overall\n');
@@ -1214,18 +1221,32 @@ class ArgparseExit extends Error {
 const _PROG = 'update_roadmap_progress.py';
 
 function _usage(): string {
-    return `usage: ${_PROG} [-h] [--check] [--archive | --no-archive] [--repo-root REPO_ROOT]\n`;
+    return (
+        `usage: ${_PROG} [-h] [--check] [--tracked-mode | --untracked-mode]\n` +
+        `       [--archive | --no-archive] [--repo-root REPO_ROOT] [--dashboard-only]\n`
+    );
 }
 
 interface Args {
     check: boolean;
+    mode: DashboardMode;
     archive: boolean;
     repo_root: string;
+    /**
+     * Assert ONLY this artefact's own state — tracked / absent / stale — not
+     * the estate-wide conditions `--check` also carries. Two obligations, two
+     * blast radii: why that split exists, and what it cost when it did not,
+     * is on the `roadmap-dashboard-untracked-check` task in
+     * `taskfiles/content.yml`.
+     */
+    dashboard_only: boolean;
 }
 
 function _parseArgs(argv: readonly string[]): Args {
     let check = false;
+    let mode: DashboardMode = 'tracked';
     let archive = false;
+    let dashboard_only = false;
     let repo_root = process.cwd();
     const emitError = (msg: string): never => {
         process.stderr.write(_usage());
@@ -1241,6 +1262,12 @@ function _parseArgs(argv: readonly string[]): Args {
         } else if (tok === '--check') {
             check = true;
             i += 1;
+        } else if (parseModeToken(tok) !== null) {
+            mode = parseModeToken(tok) as DashboardMode;
+            i += 1;
+        } else if (tok === '--dashboard-only') {
+            dashboard_only = true;
+            i += 1;
         } else if (tok === '--archive') {
             archive = true;
             i += 1;
@@ -1267,7 +1294,10 @@ function _parseArgs(argv: readonly string[]): Args {
         // rather than silently letting one win.
         emitError('argument --archive: not allowed with --check');
     }
-    return { check, archive, repo_root };
+    if (dashboard_only && !check) {
+        emitError('argument --dashboard-only: only meaningful with --check');
+    }
+    return { check, mode, archive, repo_root, dashboard_only };
 }
 
 /**
@@ -1334,13 +1364,10 @@ function main(argv?: readonly string[]): number {
     }
     const roadmaps = collect(roadmap_root);
     const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root);
-    const current = fs.existsSync(target) ? fs.readFileSync(target, { encoding: 'utf-8' }) : '';
     const complete = unarchived_complete(roadmaps);
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
 
-    const _relToRepo = (p: string): string => _relPosix(repo_root, p);
-
     const _warn_merge_gated = (): void => {
         process.stderr.write(
             '⏳  Merge-gated roadmaps (every open item gated on a PR) — ' +
@@ -1357,50 +1384,22 @@ function main(argv?: readonly string[]): number {
     };
 
     if (args.check) {
-        const stale = current !== new_text;
-        if (stale) {
-            process.stderr.write(
-                `❌  ${_relToRepo(target)} is stale. ` +
-                    'Run `node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts` ' +
-                    'to regenerate (or `task roadmap-progress` in Taskfile ' +
-                    'projects).\n',
-            );
-        }
-        if (complete.length) {
-            process.stderr.write(
-                '❌  Completed roadmaps are still in `agents/roadmaps/` — ' +
-                    'move them to `agents/roadmaps/archive/` (per the ' +
-                    '`roadmap-progress-sync` rule):\n',
-            );
-            for (const r of complete) {
-                process.stderr.write(`      - ${r.rel}  (${r.done}/${r.total_active} done)\n`);
-            }
-        }
-        if (pending.length) {
-            process.stderr.write(
-                '❌  Iron Law 3 — roadmaps with unresolved `[~]` deferred ' +
-                    'items must NOT auto-archive. Resolve via `roadmap-management § 4b` ' +
-                    '(spawn follow-up, restore, or cancel):\n',
-            );
-            for (const r of pending) {
-                process.stderr.write(
-                    `      - ${r.rel}  (${r.done}/${r.total_active} done · ` +
-                        `${r.deferred} deferred)\n`,
-                );
-            }
-        }
-        if (gated.length) {
-            _warn_merge_gated();
-        }
-        if (stale || complete.length || pending.length) {
-            return 1;
-        }
-        process.stdout.write(`✅  ${_relToRepo(target)} is up to date.\n`);
-        return 0;
+        const rel = _relPosix(repo_root, target);
+        const r = reportCheckVerdict({
+            verdict: evaluateDashboardOnDisk({ mode: args.mode, target, repo_root, rendered: new_text, rel }),
+            complete,
+            pending,
+            dashboardOnly: args.dashboard_only,
+            warnMergeGated: _warn_merge_gated,
+            gatedCount: gated.length,
+        });
+        if (r.stderr) process.stderr.write(r.stderr);
+        if (r.stdout) process.stdout.write(r.stdout);
+        return r.rc;
     }
     fs.writeFileSync(target, new_text, { encoding: 'utf-8' });
     process.stdout.write(
-        `✅  Wrote ${_relToRepo(target)} · ` +
+        `✅  Wrote ${_relPosix(repo_root, target)} · ` +
             `${roadmaps.length} roadmap(s) · ` +
             `${roadmaps.reduce((s, r) => s + r.done, 0)}/${roadmaps.reduce((s, r) => s + r.total_active, 0)} steps done.\n`,
     );

package/src/config/ci-local-parity.yml

@@ -184,6 +184,27 @@ ci_only:
 # worth remote enforcement, OR it should simply be added to a workflow. Prefer
 # adding it: a local-only gate is the direction that let real defects merge.
 local_only:
+  - id: check_hook_bundle_content
+    class: developer-machine-scoped
+    reason: >
+      Compares `dist/hooks/dispatch.js` — the bundle that ACTUALLY EXECUTES the
+      hooks — against a rebuild from this checkout's sources. `git ls-files
+      dist/hooks/` returns ZERO: the bundle is an untracked local build
+      artefact, so a fresh CI checkout has none and the gate can only report
+      "nothing to compare". Wiring it into a workflow would measure an artefact
+      no CI run has, which is the empty-scope false green this repo's
+      gate-coverage manifest exists to refuse. Declared rather than wired for
+      the same reason `check_single_delivery` below is. The blind spot it
+      closes is real and was measured on 2026-08-21: an edit to the git guard's
+      authorization window was never rebuilt into the bundle and the guard kept
+      enforcing the old value for a full hour. The sibling
+      `check_hook_bundle_freshness` did not miss it — that gate is pre-push and
+      was never run, and an ordinary edit moves the source mtime, so it would
+      have reddened. What it structurally cannot see is the narrower set this
+      gate covers: an mtime-preserving write, a `touch` on the bundle, a `cp -p`
+      restore. Ordering is not equivalence. That asymmetry is the finding: a green
+      CI cannot speak for the bundle a maintainer is running, and only a local
+      gate can. Cost measured, like its neighbours in the pre-push set: 0.27s.
   - id: check_single_delivery
     class: developer-machine-scoped
     reason: >