@event4u/agent-config 12.1.0 → 14.0.0

package/dist/agent-src/rules/ui-audit-gate.md

@@ -14,8 +14,13 @@ triggers:
   - file_pattern: "*.tsx"
   - file_pattern: "*.jsx"
   - file_pattern: "*.blade.php"
-  - keyword: "component"
-  - keyword: "design token"
+  # `keyword: "component"` and `keyword: "design token"` removed 2026-08-17 as an
+  # AUTHORING decision — road-to-mixed-trigger-activation-cost Phase 2, amendment
+  # option (b), narrowed to the two path-dominant per-edit rules. This is the
+  # escape the mixed-triggers guard's own comment names: with no non-path trigger
+  # left the emitter restores `paths:`, so the rule loads on UI file contact
+  # instead of in every session. The obligation is unchanged — an audit is owed
+  # before a component is written, and a component is written in a file.
 routes_to:
   - "skill:existing-ui-audit"
   - "skill:iconography"
@@ -25,8 +30,11 @@ packs: [frontend-design]
 enforced_by:
   - "none"
 collision_ok:
-  "component": "no new component without audit findings — its core subject"
-  "design token": "same surface, opposite side: this inventories tokens before the write, design-review-after-ui-write reviews what the write emitted"
+  # The "component" and "design token" entries were removed with their triggers
+  # (2026-08-17): a collision note for a trigger that no longer exists is an
+  # own-orphan, and `minimal-safe-diff` § Own-orphan cleanup requires the diff that
+  # stopped referencing them to remove them too. The path-keyed notes below are
+  # unchanged — both halves of the UI loop still fire on the same paths.
   "resources/views/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "resources/js/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "components/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
@@ -114,17 +122,31 @@ consultation latched this session.
 It is a **parallel** mechanism, not a consumer of the triggers above — the
 distinction matters and the earlier wording here got it wrong. The concern
 decides "is this a UI surface" from `src/scripts/_lib/ui_surface.ts`; nothing
-in the tree parses this frontmatter at session time, so the `keyword:` triggers
-still have no runtime consumer at all, and the two sets can drift. What holds
-them together is a test, not a dependency: `ui_rule_triggers.test.ts` asserts
-every `file_pattern` declared here is accepted by that predicate. The predicate
+in the tree parses this frontmatter at session time, and the two sets can drift.
+What holds them together is a test, not a dependency:
+`ui_rule_triggers.test.ts` asserts every `file_pattern` declared here is
+accepted by that predicate.
+
+**This rule carries no `keyword:` trigger any more (2026-08-17).** It used to,
+and the observation those keywords had no runtime consumer is what made removing
+them cheap: no host activation surface reads a keyword — Cursor and Windsurf
+activate on `globs` plus the description, Claude on `paths:`. What the keywords
+did do was expensive, and only on Claude: one non-path trigger makes the emitter
+write **no** `paths:` at all, which is why this rule loaded in every session from
+12.1.0 until the removal. It is path-scoped again, so the obligation now arrives
+on UI file contact — see `road-to-mixed-trigger-activation-cost` Phase 2. The predicate
 is deliberately wider (it also covers `.css`, `.scss`, `.astro`), because a
 measurement denominator and a routing trigger are not the same population.
 
-Warn-only, capped at two per session, default-OFF, bound only where a
-`pre_tool_use` slot exists. A reminder that can be ignored is not a gate, so
-`enforced_by:` stays `none`. Run `agent-config hooks:status` for the host you
-are on rather than trusting this sentence.
+Warn-only, capped at two per session, default-OFF, and bound only in the three
+`platforms:` rows that carry a `pre_tool_use` key — augment, claude, cowork
+(**clarified 2026-08-17**: "where a slot exists" read as a host property, and it
+is a manifest one; three further hosts alias a native pre-tool event without a
+binding, and only claude honours a deny at all — the four states are tabulated
+in [`hook-architecture-v1 § Which hosts carry pre_tool_use`](../docs/contracts/hook-architecture-v1.md)).
+None of that changes the verdict here: a reminder that can be ignored is not a
+gate, so `enforced_by:` stays `none`. Run `agent-config hooks:status` for the
+host you are on rather than trusting this sentence.
 
 ## Failure modes
 

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

@@ -403,6 +403,38 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
     }
 }
 
+/**
+ * Rebuild the archive index after a move, when the builder is present.
+ *
+ * The sweep is the one operation that changes what `agents/roadmaps/archive/`
+ * contains, so it is the one operation that can leave the generated index
+ * stale — and the drift gate on that index runs in the same PR the sweep runs
+ * in. Regenerating here keeps the two from disagreeing by construction rather
+ * than by remembering.
+ *
+ * `build_archive_index` is package-internal (`src/scripts/`), while this sweep
+ * is projected into consumer installs that carry no such script. Absent
+ * builder → nothing to regenerate, and that is a normal consumer state, not a
+ * failure. The spawn is best-effort for the same reason `_regen_dashboard` is:
+ * a sweep that archived correctly must not report failure because a
+ * regeneration could not run.
+ */
+function _regen_archive_index(root: string, dry_run: boolean): void {
+    if (dry_run) {
+        return;
+    }
+    const script = path.join(root, 'src', 'scripts', 'build_archive_index.ts');
+    if (!_isFile(script)) {
+        return;
+    }
+    _runTwin(root, script);
+    for (const rel of ['agents/roadmaps/archive/INDEX.md', 'agents/roadmaps/archive/index.json']) {
+        if (_isFile(path.join(root, rel))) {
+            _run(['git', 'add', '--', rel], 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
@@ -491,6 +523,7 @@ function main(argv?: readonly string[]): number {
         return 0;
     }
     _regen_dashboard(root, ns.dry_run);
+    _regen_archive_index(root, ns.dry_run);
     const verb = ns.dry_run ? 'Would archive' : 'Archived';
     for (const rec of archived) {
         process.stdout.write(

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

@@ -0,0 +1,395 @@
+/**
+ * `agent-config gates --execute <id>` — the acting half of the gate layer.
+ *
+ * `gates` renders decisions. This resolves the ones that were never decisions:
+ * a class-0 gate is a command whose OUTPUT IS THE UNBLOCK, and leaving it for a
+ * human to type is the couriering `road-to-gate-autonomy` exists to remove.
+ *
+ * ## Deliberately thin, on the sweep's own number
+ *
+ * Step 1.2 pre-registered that at least 40 % of open blockers would be class 0
+ * or 1 and measured **24.5 %** (`agents/evidence/analysis/gate-class-sweep-2026-08-17.md`).
+ * The roadmap's honest-null clause then fixes this module's size: it ships for
+ * the six class-0 entries and the render path, and it is not the lever that
+ * drains the estate. Building a general execution engine against a premise the
+ * evidence weakened would be the over-build the null exists to prevent.
+ *
+ * ## What it will not do
+ *
+ *   - **No sweep.** One blocker per invocation, named explicitly. A blanket
+ *     `--execute` over the estate would run N authored commands on one keypress,
+ *     and the blast radius of a misclassification would be the whole tree
+ *     instead of one entry.
+ *   - **No resolve on failure.** A non-zero exit reports and changes nothing.
+ *     A gate marked resolved by a command that failed is worse than an open one.
+ *   - **No invented ledger.** Class 1 needs a standing budget, and the shape of
+ *     that budget is an OPEN maintainer decision (`b-gate-budget-preauth`).
+ *     Until it is taken there is no ledger, so class 1 takes the
+ *     render-instead-of-run path — which is the behaviour the blocker itself
+ *     prescribes for a missing ledger, not a stub of the decision.
+ *   - **No class-3 change.** The class-3 branch executes nothing and writes
+ *     nothing, so `agent-config gates` renders a class-3 entry exactly as it did
+ *     before this module existed. `--execute` on one returns a one-line notice
+ *     and points back at that renderer; it does not call it.
+ *   - **No run without `--confirm`.** `Run:` is arbitrary shell read out of a
+ *     markdown field. Without the flag the command is echoed and refused, so
+ *     the operator sees the exact string first — the this-turn, names-the-object
+ *     confirmation `non-destructive-by-default` requires. A command carrying a
+ *     Hard-Floor action is refused even WITH the flag: class 0 means reversible,
+ *     so such an entry is misclassified rather than merely dangerous.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { collect, blocker_class, type Blocker } from './update_roadmap_progress.js';
+
+/**
+ * Where a class-1 receipt ledger would live once the budget decision is taken.
+ *
+ * Named here so the absent-ledger branch has something concrete to report, and
+ * deliberately NOT created: the path is a consequence of the decision, and
+ * writing it now would answer a question that is still the maintainer's.
+ */
+const LEDGER_REL = path.join('agents', 'runtime', 'state', 'gate-budget-ledger.jsonl');
+
+type Outcome = 'resolved' | 'failed' | 'rendered' | 'not-found';
+
+interface ExecuteResult {
+    outcome: Outcome;
+    /** Human-facing report — always populated, always the whole answer. */
+    report: string;
+    /** Exit code for the CLI: 0 unless the gate was named and could not run. */
+    code: number;
+}
+
+interface Located {
+    blocker: Blocker;
+    /** Absolute path of the roadmap holding it. */
+    file: string;
+    rel: string;
+}
+
+function locate(roadmapRoot: string, id: string): Located | null {
+    for (const r of collect(roadmapRoot)) {
+        for (const b of r.open_blockers) {
+            if (b.id === id) {
+                // `r.path` is the absolute path the collector already resolved.
+                // Rebuilding it from `basename(r.rel)` discarded the directory,
+                // so a roadmap in any subdirectory the collector does not
+                // exclude was either written to a same-named top-level file or
+                // threw — and either way AFTER the authored command had run.
+                return { blocker: b, file: r.path, rel: r.rel };
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Commands a class-0 gate may never carry, whatever the entry claims.
+ *
+ * Class 0 is defined as deterministic, free and **reversible**. A command that
+ * pushes, merges, deploys, or deletes is none of those, so its presence is a
+ * misclassification — and the right answer to a misclassification is refusal,
+ * not a confirmation prompt that makes the operator the last line of defence.
+ * These are Hard-Floor actions under `non-destructive-by-default`, which no
+ * setting, roadmap or flag lifts.
+ *
+ * A denylist is the wrong shape for a *security boundary* and the right shape
+ * for a *classification check*, which is what this is: the tree's roadmap files
+ * are reviewed content, so this catches the authoring mistake rather than an
+ * attacker. The blast-radius control is `--confirm` below, not this list.
+ */
+const HARD_FLOOR_RE =
+    /(^|[;&|]\s*)(git\s+(?:push|merge|reset\s+--hard|rebase)\b|gh\s+(?:pr\s+merge|release)\b|terraform\s+apply\b|kubectl\s+apply\b|npm\s+publish\b|rm\s+-[rRf]+|DROP\s+TABLE\b|TRUNCATE\b)/i;
+
+function hardFloorReason(command: string): string | null {
+    const m = HARD_FLOOR_RE.exec(command);
+    return m ? (m[2] as string).trim() : null;
+}
+
+/** Strip the backticks an authored `Run:` field carries. */
+function commandOf(b: Blocker): string {
+    const raw = b.run.trim();
+    const fenced = /^`([^`]+)`$/.exec(raw);
+    return (fenced ? (fenced[1] as string) : raw).trim();
+}
+
+/**
+ * The class-2 consent line — one question, its recommendation, its default.
+ *
+ * This is a FEED, not a surface: `road-to-user-out-of-the-loop` Phase 1 owns
+ * the decision sheet, and this roadmap only hands it a line. Keeping the shape
+ * to one line is the contract — a class-2 gate that cannot state a one-line
+ * question and a default is reclassified to 3, never verbosified.
+ */
+function consentLine(b: Blocker, why?: string): string {
+    const head = why ? `${b.id} — ${why}` : b.id;
+    const rec = b.recommendation.trim();
+    const q = b.question.trim();
+    const lines = [`CONSENT · ${head}`];
+    // An entry with no `Question:` has no question, and borrowing `Blocks:`
+    // silently put a "what this holds up" sentence in the "what is being
+    // decided" slot — two different facts. Say which one is on screen.
+    lines.push(
+        q !== ''
+            ? `  Question:       ${q}`
+            : `  Question:       (none authored — this is the Blocks line) ${b.blocks.trim()}`,
+    );
+    lines.push(
+        `  Recommendation: ${rec || '(none recorded — ask for one before deciding)'}`,
+    );
+    // The default is derived, not constant: an entry carrying a recommendation
+    // has one, an entry without one has nothing to default TO, and printing
+    // the same sentence for both told the reader nothing either way.
+    lines.push(
+        rec !== ''
+            ? '  Default if you say nothing: the recommendation above is NOT applied; the gate stays open.'
+            : '  Default if you say nothing: the gate stays open, and no recommendation exists to fall back on.',
+    );
+    // Risk 5 of the roadmap, made observable rather than merely written down:
+    // the defect being fixed is reading load, and a mechanism that emits
+    // paragraphs recreates it under a new name. The remedy the taxonomy names
+    // is reclassification to 3, never a longer line — so the overflow is
+    // reported at the entry rather than silently rendered.
+    if (rec.length > PARAGRAPH_CHARS) {
+        lines.push(
+            `  note: this recommendation is ${rec.length} chars — a class-2 gate that ` +
+                'cannot state a one-line question and a default is reclassified to 3, ' +
+                'not verbosified.',
+        );
+    }
+    return lines.join('\n') + '\n';
+}
+
+/**
+ * Where "one line" stops being one line.
+ *
+ * A stated default, not a measured optimum: two full terminal lines at the 78
+ * column the rest of this command wraps to. *Revisit-if* a real decision sheet
+ * lands and its own width contradicts this.
+ */
+const PARAGRAPH_CHARS = 156;
+
+/**
+ * Append the run's evidence under the blocker and flip its status.
+ *
+ * In-file, at the blocker, which is the done-note discipline every phase in
+ * this tree already uses — an unblock recorded anywhere else is an unblock the
+ * next reader of the roadmap cannot see.
+ */
+function appendEvidence(file: string, id: string, command: string, output: string, when: string): boolean {
+    const text = fs.readFileSync(file, 'utf-8');
+    // The id is regex-escaped: ids are parsed with `(.+?)`, so a metacharacter
+    // is legal in the tree and an unescaped interpolation threw an uncaught
+    // SyntaxError — after the authored command had already run.
+    const head = new RegExp(`^###[ \\t]+blocker:[ \\t]*${escapeRe(id)}[ \\t]*$`, 'im');
+    const m = head.exec(text);
+    if (!m) {
+        return false;
+    }
+    const bodyStart = m.index + m[0].length;
+    // The body ends at the next blocker OR the next `##` section. Bounding it
+    // only at the next `### blocker:` made the LAST blocker's body run to the
+    // end of the file — the common shape, since `## Blockers` is followed by
+    // `## Risk Register` — so the evidence bullet landed after the risk table
+    // instead of under the blocker, which is the opposite of what this
+    // function's whole point is.
+    const rest = text.slice(bodyStart);
+    const nextHead = /^###[ \t]+blocker:/im.exec(rest);
+    const nextSection = /^##[ \t]+\S/m.exec(rest);
+    const ends = [nextHead?.index, nextSection?.index].filter((i): i is number => i !== undefined);
+    const bodyEnd = ends.length ? bodyStart + Math.min(...ends) : text.length;
+    const body = text.slice(bodyStart, bodyEnd);
+
+    const statusRe = /^-[ \t]*\*\*Status:\*\*[ \t]*.*$/im;
+    if (!statusRe.test(body)) {
+        return false;
+    }
+    const firstLine = output.split(/\r?\n/).find((l) => l.trim() !== '') ?? '(no output)';
+    const flipped = body.replace(
+        statusRe,
+        `- **Status:** resolved ${when} — class-0 auto-run`,
+    );
+    const evidence =
+        `- **Unblock evidence (${when}):** ran \`${command}\` — exit 0. ` +
+        `First line of output: ${firstLine.trim()}\n`;
+    const withEvidence = flipped.replace(/\s*$/, '\n') + evidence;
+    fs.writeFileSync(file, text.slice(0, bodyStart) + withEvidence + text.slice(bodyEnd), 'utf-8');
+    return true;
+}
+
+/** `YYYY-MM-DD` for the evidence note. Injected so tests are deterministic. */
+function today(now: Date): string {
+    return now.toISOString().slice(0, 10);
+}
+
+function escapeRe(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+interface ExecuteOptions {
+    /**
+     * Actually run the class-0 command.
+     *
+     * Default false, and that default is the control. `Run:` is an arbitrary
+     * shell string read out of a markdown file; without this flag the command
+     * is ECHOED and refused, so the operator sees exactly what would run before
+     * anything runs. `non-destructive-by-default` requires the confirmation to
+     * be this-turn and to name the exact object, and the echoed command is that
+     * object.
+     */
+    confirm?: boolean;
+}
+
+function execute(
+    roadmapRoot: string,
+    id: string,
+    now: Date,
+    opts: ExecuteOptions = {},
+): ExecuteResult {
+    const found = locate(roadmapRoot, id);
+    if (!found) {
+        return {
+            outcome: 'not-found',
+            report: `No open blocker with id '${id}'. Run \`agent-config gates --all\` for the list.\n`,
+            code: 1,
+        };
+    }
+    const { blocker, file, rel } = found;
+    const cls = blocker_class(blocker);
+
+    if (cls === '3') {
+        // Byte-identical to today by construction: nothing is executed and
+        // nothing is written. The gate is rendered by the caller.
+        return {
+            outcome: 'rendered',
+            report: `${id} is class 3 — human-only. Nothing to execute; see \`agent-config gates\`.\n`,
+            code: 0,
+        };
+    }
+    if (cls === '2') {
+        return { outcome: 'rendered', report: consentLine(blocker), code: 0 };
+    }
+    if (cls === '1') {
+        const ledger = path.join(path.dirname(path.dirname(roadmapRoot)), LEDGER_REL);
+        if (!fs.existsSync(ledger)) {
+            // The blocker's own prescription for a missing ledger: render the
+            // consent line INSTEAD of running. Not a degraded mode — the
+            // budget shape is an open decision and this is what open means.
+            return {
+                outcome: 'rendered',
+                report: consentLine(
+                    blocker,
+                    'class 1 with no budget ledger, so it renders instead of running',
+                ),
+                code: 0,
+            };
+        }
+        return {
+            outcome: 'rendered',
+            report:
+                `${id} is class 1 and a ledger exists at ${LEDGER_REL}, but spend execution ` +
+                'is gated on `b-gate-budget-preauth`, which is open. Rendering instead of running.\n',
+            code: 0,
+        };
+    }
+
+    const command = commandOf(blocker);
+    if (command === '') {
+        // Unreachable through a linted tree — `lint_roadmap_blockers` fails a
+        // class-0 entry with no `Run:` — but reachable through an unlinted one,
+        // and guessing a command here is the one thing that must not happen.
+        return {
+            outcome: 'failed',
+            report: `${id} is class 0 but carries no **Run:** command. Nothing was executed.\n`,
+            code: 1,
+        };
+    }
+
+    const floor = hardFloorReason(command);
+    if (floor !== null) {
+        // Refused outright, not offered for confirmation. Class 0 is defined
+        // as reversible; a push, merge, deploy or delete is not, so this is a
+        // misclassified entry and the fix is to re-author the class — making
+        // the operator wave it through would move a Hard Floor onto a keypress.
+        return {
+            outcome: 'failed',
+            report:
+                `${id} is class 0 but its **Run:** command contains \`${floor}\`, which is a ` +
+                'Hard-Floor action under non-destructive-by-default. Class 0 means ' +
+                'deterministic, free and REVERSIBLE, so this entry is misclassified. ' +
+                'Nothing was executed; re-author the class.\n',
+            code: 1,
+        };
+    }
+
+    if (opts.confirm !== true) {
+        // Echo-before-run. The command is arbitrary shell read out of a
+        // markdown field, so the operator sees the exact string before it runs
+        // and the confirmation is this-turn rather than implied by the id.
+        return {
+            outcome: 'rendered',
+            report:
+                `${id} is class 0 and would run, from the repo root:\n\n` +
+                `    ${command}\n\n` +
+                'Nothing has been executed. Re-run with `--confirm` to execute it and ' +
+                'record the evidence at the blocker.\n',
+            code: 0,
+        };
+    }
+
+    const r = spawnSync(command, {
+        shell: true,
+        encoding: 'utf-8',
+        cwd: path.dirname(path.dirname(roadmapRoot)),
+        timeout: 120_000,
+    });
+    const output = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+    if (r.error !== undefined || r.status !== 0) {
+        // `r.error` is read, not just the status: a spawn failure or a
+        // maxBuffer overflow leaves status null with empty output, and
+        // "exited null" with no diagnostic is illegible on the one path in
+        // this command that writes.
+        const why =
+            r.error !== undefined
+                ? `could not run (${r.error.message})`
+                : `exited ${r.status ?? 'null'}`;
+        return {
+            outcome: 'failed',
+            report:
+                `${id}: \`${command}\` ${why}. The gate is unchanged — ` +
+                'a blocker resolved by a failed command is worse than an open one.\n' +
+                output.split(/\r?\n/).slice(0, 10).join('\n') +
+                '\n',
+            code: 1,
+        };
+    }
+    const when = today(now);
+    if (!appendEvidence(file, id, command, output, when)) {
+        return {
+            outcome: 'failed',
+            report:
+                `${id}: \`${command}\` succeeded, but its entry in ${rel} could not be ` +
+                'rewritten (no Status field found). Nothing was changed.\n',
+            code: 1,
+        };
+    }
+    return {
+        outcome: 'resolved',
+        report:
+            `${id} resolved. Ran \`${command}\` (exit 0); evidence appended in ${rel} ` +
+            `and the status flipped to resolved ${when}.\n` +
+            // The dashboard is derived from the file this just rewrote, so it
+            // is now stale. Saying so is the same follow-up `renderResumed`
+            // already prints for its own file-move suggestion.
+            'Run `agent-config roadmap:progress` — the dashboard is derived from the ' +
+            'file this rewrote and is now stale.\n',
+        code: 0,
+    };
+}
+
+export { execute, consentLine, commandOf, locate, appendEvidence, LEDGER_REL };
+export type { ExecuteResult, Outcome };