@event4u/agent-config 14.6.0 → 14.7.0

package/dist/agent-src/rules/source-confidentiality.md

@@ -3,13 +3,6 @@ type: "auto"
 tier: "mechanical-already"
 description: "Naming an external repo this package copied/harvested/compared against — keep the tracked tree source-anonymous"
 alwaysApply: false
-triggers:
-  - path_prefix: "src/skills/"
-  - path_prefix: "src/rules/"
-  - path_prefix: "src/domains/"
-  - path_prefix: "docs/"
-  - path_prefix: "agents/evidence/"
-  - path_prefix: "agents/roadmaps/"
 validator_ignore:
   - type: "substring"
     pattern: "external_sources_denylist"
@@ -96,6 +89,43 @@ runs in the package CI pipeline and fails the build on any denied source token
 in a non-carve-out tracked file. The linter is a deterministic net, not a
 substitute for not writing the attribution in the first place.
 
+## Why this rule is not path-scoped
+
+Under [ADR-236](../docs/decisions/ADR-236-one-artefact-one-layer.md) this rule is
+delivered by the PROJECT layer only — it exists to maintain this package, so the
+global layer no longer carries an unscoped twin of it. A `paths:`-scoped rule is
+**not re-injected after `/compact`** (ADR-227:79-80), so scoping it would mean the
+obligation silently disappears mid-session with nothing left to reload it.
+
+It is therefore delivered unconditionally, and the path triggers were removed
+rather than worked around. **This section is the shared record for all four such
+rules** — `no-roadmap-references`, `rule-type-governance` and `skill-quality` carry
+the same change and no note of their own. Two reasons: four copies of the rationale
+cost more standing context than the decision they explain, and the other three are
+migrated POINTER stubs held at their pointer's size by
+`check_rule_stub_ceiling` — prose added there is prose in the wrong place by that
+gate's own contract, which is what caught the first attempt to duplicate it.
+
+AI council 2026-08-20, 2/2 convergent on this option over three alternatives, with
+two independent decisive arguments. First: the obligation governs an **authoring
+decision**, which happens before any file exists for a path trigger to match — so
+path-scoping fails at greenfield creation whether or not a compaction ever occurs.
+Second: the measured cost is small against what the partition returns. Keeping an
+unscoped global copy was rejected because it re-creates the duplication the
+partition exists to remove; splitting the four by "has a CI gate" was rejected by
+both seats as the wrong axis — a validator observes an outcome, it does not hold an
+obligation during the session, and `rule-type-governance` has no gate at all.
+
+**Cost, measured and corrected.** An earlier revision of this note claimed 1,754
+tokens (1.8 % of the partition's 96,584-token saving). That figure was a
+`chars / 4` proxy over the projected files and **understated the real cost by about
+half**: `check_rule_activation_census`, which counts with the exact BPE tokenizer,
+measures the unconditional corpus growing **108,130 → 111,642, i.e. +3,512 tokens
+(3.6 %)** — and that number includes this rationale, which is why it lives in one
+place instead of four. The verdict does not depend on the figure: one seat argued
+the token axis was the wrong one entirely, the other that cost is a legitimate axis
+which simply loses this particular comparison. Both readings survive 3.6 %.
+
 ## See also
 
 - [`source-of-truth`](source-of-truth.md) — edit `src/`, never the projections.

package/dist/agent-src/scripts/archival_sweep.ts

@@ -0,0 +1,117 @@
+/**
+ * Archival-sweep spawner for the roadmap dashboard.
+ *
+ * Split out of `update_roadmap_progress.ts` rather than authored there: that
+ * file sits at the 1500-line source ceiling `check_source_size_budget`
+ * ratchets, and the sweep plus its contract is the newest and most separable
+ * thing in it. The contract below is that text, moved intact.
+ *
+ * `--archive` (opt-in; wired into `task roadmap-progress` and
+ * `agent-config roadmap:progress`) runs the archival sweep before rendering
+ * instead of printing "Completed roadmaps not yet archived" and leaving the
+ * work to a human who has been ignoring the line for weeks. It is a flag rather
+ * than the default because the PostToolUse hook re-runs the WRITE path once per
+ * turn on every roadmap edit, and a hook that silently `git mv`s files mid-work
+ * is a bigger problem than the warning it would remove. `--check` never
+ * archives — see `run_archival_sweep`.
+ *
+ * WHY the warning existed at all, since this is the one place a reader of the
+ * flag will look: the sweep's own default is `--changed-only`, so a PR archives
+ * exactly the roadmaps it completed. A roadmap completed by a PR whose sweep did
+ * not run is then complete, on the trunk, and OUTSIDE every later branch's
+ * history — no `--changed-only` sweep finds it again. Measured 2026-08-20: six
+ * such roadmaps, with every regen reprinting the warning at whoever ran it.
+ * `/create-pr` § 1c keeps `--changed-only`; repo-wide reconciliation is this
+ * flag's job and nothing else's.
+ *
+ * This layout is deliberate rather than convenient: the prose homes for it are
+ * both at their ceilings (`roadmap-progress-mechanics.md` sits 122 chars under
+ * the 16,000-char depth ceiling, and `roadmap-management/SKILL.md` tips
+ * `skill_too_large` on any prose block), so the contract lives with the code it
+ * governs. Moving it out means making room first.
+ *
+ * AI council 2026-08-20 (anthropic + openai, blind peer review): both seats
+ * converged on explicit opt-in + `--all` scope + hook archival-free, and both
+ * independently required the `--check` exclusion, the archive-before-render
+ * order, and that a failed sweep must not render. RECORDED DISSENT: one seat
+ * argued for flipping the sweep's own default to `--all` instead. Rejected —
+ * that makes every PR a potential estate-wide cleanup, which is exactly what
+ * `--changed-only` exists to prevent.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Same directory as `update_roadmap_progress.ts`, so the `path.dirname` below
+// resolves the sweep script exactly as it did before the split.
+const _HERE = fileURLToPath(import.meta.url);
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Run the archival sweep for every complete roadmap, in-place.
+ *
+ * Spawned rather than imported: `archive_completed_roadmaps.ts` imports
+ * `collect` from `update_roadmap_progress.ts`, so a static import back would close a cycle, and
+ * `main()` is synchronous so a dynamic `await import()` is not available either.
+ * The sweep is the same twin `_regen_dashboard` already spawns in the other
+ * direction, so the spawn shape is the established one in this pair.
+ *
+ * No recursion: the sweep re-runs this script with NO flags, so its inner
+ * dashboard pass has archival off and terminates at depth 2.
+ *
+ * `--all`, not the sweep's `--changed-only` default. The default exists so a PR
+ * archives exactly the roadmaps it completed; here the caller asked the
+ * repo-wide dashboard to reconcile the estate, and the roadmaps that leak are
+ * by construction the ones NOT in this branch's history — six had accumulated
+ * on the trunk while the warning printed every regen. A roadmap the sweep
+ * refuses (open blockers) stays put and is still reported below.
+ */
+export function run_archival_sweep(root: string): SweepResult {
+    const script = path.join(path.dirname(_HERE), 'archive_completed_roadmaps.ts');
+    if (!_isFile(script)) {
+        // A consumer install without the sweep script: nothing to run, and that
+        // is a normal state — the warning below still reports the roadmaps.
+        return { ran: false, ok: true, stdout: '', stderr: '' };
+    }
+    const argv = [script, '--all', '--repo-root', root];
+    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)) {
+            return _sweepResult(spawnSync(candidate, argv, { cwd: root, encoding: 'utf-8' }));
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return _sweepResult(spawnSync('npx', ['tsx', ...argv], { cwd: root, encoding: 'utf-8' }));
+}
+
+export interface SweepResult {
+    ran: boolean;
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+
+function _sweepResult(r: ReturnType<typeof spawnSync>): SweepResult {
+    return {
+        ran: true,
+        ok: r.status === 0,
+        stdout: String(r.stdout ?? ''),
+        stderr: String(r.stderr ?? ''),
+    };
+}
+

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

@@ -31,6 +31,7 @@
  *     ./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
+ *     ./scripts-run src/scripts/archive_completed_roadmaps --repo-root /path/to/proj
  *
  * --- Parity notes (ADR-200) ---
  *
@@ -462,19 +463,21 @@ function _runTwin(root: string, script: string): void {
 const _PROG = 'archive_completed_roadmaps.py';
 
 function _usage(): string {
-    return `usage: ${_PROG} [-h] [--all] [--base BASE] [--dry-run]\n`;
+    return `usage: ${_PROG} [-h] [--all] [--base BASE] [--dry-run] [--repo-root REPO_ROOT]\n`;
 }
 
 interface Args {
     all: boolean;
     base: string;
     dry_run: boolean;
+    repo_root: string | null;
 }
 
 function _parseArgs(argv: readonly string[]): Args {
     let all = false;
     let base = 'origin/main';
     let dry_run = false;
+    let repo_root: string | null = null;
     const emitError = (msg: string): never => {
         process.stderr.write(_usage());
         process.stderr.write(`${_PROG}: error: ${msg}\n`);
@@ -502,17 +505,30 @@ function _parseArgs(argv: readonly string[]): Args {
         } else if (tok.startsWith('--base=')) {
             base = tok.slice('--base='.length);
             i += 1;
+        } else if (tok === '--repo-root') {
+            const val = argv[i + 1];
+            if (val === undefined) {
+                emitError('argument --repo-root: expected one argument');
+            }
+            repo_root = val as string;
+            i += 2;
+        } else if (tok.startsWith('--repo-root=')) {
+            repo_root = tok.slice('--repo-root='.length);
+            i += 1;
         } else {
             emitError(`unrecognized arguments: ${tok}`);
         }
     }
-    return { all, base, dry_run };
+    return { all, base, dry_run, repo_root };
 }
 
 function main(argv?: readonly string[]): number {
     const ns = _parseArgs(argv ?? process.argv.slice(2));
 
-    const root = _repo_root();
+    // An explicit `--repo-root` wins over the `git rev-parse` resolution. The
+    // dashboard generator passes it so a monorepo sub-project sweep cannot walk
+    // up to the enclosing repo and archive the PARENT's roadmaps.
+    const root = ns.repo_root ?? _repo_root();
     const archived = archive_completed(root, {
         changed_only: !ns.all,
         base: ns.base,

package/dist/agent-src/scripts/gate_budget.ts

@@ -0,0 +1,282 @@
+/**
+ * gate_budget — the class-1 spend bound and its append-only receipt ledger
+ * (`road-to-gate-autonomy` Phase 2, blocker `b-gate-budget-preauth`).
+ *
+ * WHY THIS EXISTS. Class 1 of the gate taxonomy is "billable or long-running
+ * but reversible; the human ingredient is *spend consent*, not judgment".
+ * `gate_execute.ts` shipped without it on purpose — "no invented ledger",
+ * because the budget SHAPE was an open maintainer decision. That decision is
+ * now taken (option (a): a per-run cap AND a rolling-window cap, with an
+ * append-only receipt ledger as the audit surface), so this module supplies
+ * exactly the shape that was decided and nothing more.
+ *
+ * WHAT THIS IS NOT. It is **not** a consent bypass. `gates --execute` still
+ * requires `--confirm` on every class-1 run, so the this-turn,
+ * names-the-exact-object confirmation `non-destructive-by-default` asks for is
+ * unchanged. The caps bound the SIZE of an authorised spend; they never
+ * manufacture the authorisation. A ledger under `agents/runtime/state/` is
+ * agent-writable, so a mechanism that read an "authorisation" out of it would
+ * be an agent consenting on the user's behalf — which is precisely the threat
+ * model the live-trigger-eval terminal abort exists for. That is why the
+ * receipt records CONSUMPTION only, and why step 2.3's bypass flag is not
+ * built on top of this file.
+ *
+ * A per-run cap alone is not a spend bound — it bounds one mistake, not a week
+ * of them — which is the whole reason the decision carries two numbers.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Ledger location, relative to the workspace root.
+ *
+ * The name is the one already present in `gate_execute.ts` as the
+ * absent-ledger placeholder, kept verbatim so the path a class-1 entry has
+ * been REPORTING since Phase 2 is the path it now reads. `agents/runtime/state/`
+ * is this tree's state convention (`run_checkpoint`, `unattended_guard`,
+ * `recycle_envelope_paths` all live there); a bare `agents/state/` is not.
+ */
+export const GATE_BUDGET_LEDGER_REL = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'gate-budget-ledger.jsonl',
+);
+
+/**
+ * Build the absolute ledger path.
+ *
+ * Callers import THIS rather than joining {@link GATE_BUDGET_LEDGER_REL}
+ * themselves: a bare relative constant is the shape that goes silently dead
+ * when the location moves, because nothing joins it any more and nothing
+ * complains.
+ */
+export function gateBudgetLedgerPath(workspaceRoot: string): string {
+    return path.join(workspaceRoot, GATE_BUDGET_LEDGER_REL);
+}
+
+/** The two caps decided by option (a). Both are USD. */
+export interface GateBudgetCaps {
+    maxCostPerRunUsd: number;
+    maxCostPerRolling7dUsd: number;
+}
+
+/**
+ * One append-only ledger line.
+ *
+ * The five fields the decision names — blocker, authorization, estimated and
+ * actual cost, timestamp — plus the single-use marker. `authorization` records
+ * HOW the spend was consented to; today the only value a run can honestly
+ * write is `confirm-flag`, because `--confirm` is the consent. A future
+ * human-only authorisation surface would add its own value here rather than
+ * reinterpreting this one.
+ */
+export interface GateBudgetReceipt {
+    kind: 'consumption';
+    blocker: string;
+    authorization: 'confirm-flag';
+    estimated_usd: number;
+    actual_usd: number | null;
+    at: string;
+    single_use: true;
+}
+
+/** Rolling window, in days, that `maxCostPerRolling7dUsd` bounds. */
+export const ROLLING_WINDOW_DAYS = 7;
+
+function _num(value: unknown): number | null {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    return null;
+}
+
+function _dig(settings: unknown, keys: readonly string[]): unknown {
+    let cursor: unknown = settings;
+    for (const k of keys) {
+        if (cursor === null || typeof cursor !== 'object' || Array.isArray(cursor)) {
+            return undefined;
+        }
+        cursor = (cursor as Record<string, unknown>)[k];
+    }
+    return cursor;
+}
+
+/**
+ * Read the caps out of an already-merged settings dict.
+ *
+ * Returns `null` when either cap is absent or non-numeric — deliberately NOT a
+ * fallback to the template numbers. An install whose settings do not carry the
+ * caps has not authorised a standing budget, and inventing one from the
+ * template default would authorise spend nobody configured. The caller renders
+ * the consent line instead.
+ */
+export function readGateBudgetCaps(settings: unknown): GateBudgetCaps | null {
+    const perRun = _num(_dig(settings, ['roadmap', 'gate_budget', 'max_cost_per_run_usd']));
+    const rolling = _num(
+        _dig(settings, ['roadmap', 'gate_budget', 'max_cost_per_rolling_7d_usd']),
+    );
+    if (perRun === null || rolling === null) {
+        return null;
+    }
+    return { maxCostPerRunUsd: perRun, maxCostPerRolling7dUsd: rolling };
+}
+
+/**
+ * Parse a USD figure out of a blocker's `Budget:` field.
+ *
+ * An explicit currency marker (`$` or `USD`) is REQUIRED. Without it a field
+ * like "~50 queries per run" would be read as fifty dollars, and a spend bound
+ * derived from a misread is worse than no bound: it would let a large run
+ * through under a small number. Returns `null` when no USD figure is stated.
+ */
+export function parseBudgetUsd(field: string): number | null {
+    const text = field.trim();
+    if (text === '') {
+        return null;
+    }
+    const dollar = /\$\s*([0-9]+(?:[.,][0-9]+)?)/.exec(text);
+    if (dollar) {
+        return Number.parseFloat(dollar[1]!.replace(',', '.'));
+    }
+    const usd = /([0-9]+(?:[.,][0-9]+)?)\s*(?:usd|dollars?)\b/i.exec(text);
+    if (usd) {
+        return Number.parseFloat(usd[1]!.replace(',', '.'));
+    }
+    return null;
+}
+
+/** Read every well-formed receipt. A malformed line is skipped, never fatal. */
+export function readGateBudgetLedger(workspaceRoot: string): GateBudgetReceipt[] {
+    const file = gateBudgetLedgerPath(workspaceRoot);
+    if (!fs.existsSync(file)) {
+        return [];
+    }
+    const out: GateBudgetReceipt[] = [];
+    for (const line of fs.readFileSync(file, 'utf-8').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            continue;
+        }
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(trimmed);
+        } catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== 'object') {
+            continue;
+        }
+        const rec = parsed as Record<string, unknown>;
+        if (rec['kind'] !== 'consumption' || typeof rec['blocker'] !== 'string') {
+            continue;
+        }
+        out.push({
+            kind: 'consumption',
+            blocker: rec['blocker'],
+            authorization: 'confirm-flag',
+            estimated_usd: _num(rec['estimated_usd']) ?? 0,
+            actual_usd: _num(rec['actual_usd']),
+            at: typeof rec['at'] === 'string' ? rec['at'] : '',
+            single_use: true,
+        });
+    }
+    return out;
+}
+
+/** Append one receipt. Append-only by construction — nothing here rewrites. */
+export function appendGateBudgetReceipt(
+    workspaceRoot: string,
+    receipt: GateBudgetReceipt,
+): void {
+    const file = gateBudgetLedgerPath(workspaceRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(receipt)}\n`, 'utf-8');
+}
+
+/**
+ * Spend inside the rolling window.
+ *
+ * `actual_usd` when the run reported one, the estimate otherwise — an
+ * unreported actual must not read as zero spend. A receipt with an unparseable
+ * timestamp counts as IN the window, because dropping it would understate the
+ * total and the cap is meant to fail closed.
+ */
+export function rollingSpendUsd(records: readonly GateBudgetReceipt[], now: Date): number {
+    const cutoff = now.getTime() - ROLLING_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+    let total = 0;
+    for (const r of records) {
+        const stamp = Date.parse(r.at);
+        if (Number.isFinite(stamp) && stamp < cutoff) {
+            continue;
+        }
+        total += r.actual_usd ?? r.estimated_usd;
+    }
+    return total;
+}
+
+export type GateBudgetRefusal =
+    | 'no_caps'
+    | 'no_estimate'
+    | 'over_per_run'
+    | 'over_rolling_7d';
+
+export type GateBudgetVerdict =
+    | { ok: true; estimateUsd: number; rollingUsd: number }
+    | { ok: false; reason: GateBudgetRefusal; detail: string };
+
+/**
+ * Decide whether a class-1 run fits inside the standing budget.
+ *
+ * Every refusal path renders rather than runs — the blocker's own prescription
+ * for a missing ledger, generalised to every way the budget can say no.
+ */
+export function evaluateGateBudget(opts: {
+    caps: GateBudgetCaps | null;
+    records: readonly GateBudgetReceipt[];
+    estimateUsd: number | null;
+    now: Date;
+}): GateBudgetVerdict {
+    const { caps, records, estimateUsd, now } = opts;
+    if (caps === null) {
+        return {
+            ok: false,
+            reason: 'no_caps',
+            detail:
+                'no standing class-1 budget is configured ' +
+                '(`roadmap.gate_budget.max_cost_per_run_usd` and ' +
+                '`roadmap.gate_budget.max_cost_per_rolling_7d_usd`)',
+        };
+    }
+    if (estimateUsd === null) {
+        return {
+            ok: false,
+            reason: 'no_estimate',
+            detail:
+                'the entry states no USD estimate in its **Budget:** field, so no cap ' +
+                'can be compared against it',
+        };
+    }
+    if (estimateUsd > caps.maxCostPerRunUsd) {
+        return {
+            ok: false,
+            reason: 'over_per_run',
+            detail:
+                `the estimate ($${estimateUsd.toFixed(2)}) exceeds the per-run cap ` +
+                `($${caps.maxCostPerRunUsd.toFixed(2)})`,
+        };
+    }
+    const spent = rollingSpendUsd(records, now);
+    if (spent + estimateUsd > caps.maxCostPerRolling7dUsd) {
+        return {
+            ok: false,
+            reason: 'over_rolling_7d',
+            detail:
+                `$${spent.toFixed(2)} is already receipted in the last ` +
+                `${String(ROLLING_WINDOW_DAYS)} days and this run would add ` +
+                `$${estimateUsd.toFixed(2)}, over the rolling cap ` +
+                `($${caps.maxCostPerRolling7dUsd.toFixed(2)})`,
+        };
+    }
+    return { ok: true, estimateUsd, rollingUsd: spent };
+}