@event4u/agent-config 9.28.0 → 9.30.0

package/dist/ui/index.html

@@ -27,7 +27,7 @@
                 document.documentElement.setAttribute('data-theme', theme);
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-DmR0mbk4.js"></script>
+      <script type="module" crossorigin src="/assets/index-B5qGYOJo.js"></script>
       <link rel="stylesheet" crossorigin href="/assets/index-jSfMW8_t.css">
     </head>
     <body>

package/docs/contracts/settings-classes.md

@@ -22,14 +22,26 @@ raise a spend ceiling, empty an allowlist, or switch off a gate.
 | **B — consent** | the agent, but only after ONE just-in-time ask that the user answered | **once**, then persisted with provenance. |
 | **C — guarded** | the GUI's write route or a hand-edit, by a human | never asked by the agent; **every agent write path refuses it.** |
 
+### The provenance sidecar's record shape
+
+"Persisted with provenance" means one record per dotted key in
+`settings/.agent-settings.provenance.json`, written by `settings:set` beside
+the value: `{ "source": "auto-detected" | "jit-answer" | "manual" | "gui",
+"at": "<ISO timestamp>" }`. For a class-B key the `at` stamp IS the grant
+time — the consent reader (`consentVerdict`) grants on `jit-answer` / `gui` /
+`manual` provenance, so source + timestamp together are the audit record of
+who consented and when. `expires_at` / `revoked_at` / contract-version fields
+stay deliberately unbuilt until a reader needs them — a field nothing reads is
+surface without a consumer.
+
 ## What the fence covers — and what it does not
 
 **It governs writes, not reads.** Every class is readable by everything. A C
 class does not hide a value; it refuses to let a non-human change it.
 
-**It governs writes, not asks.** Six settings ship an `ask` value in their own
-enum (`tokens.rich_skills`, `subagents.auto`, `subagents.budget_routing`,
-`subagents.adversarial_council`, `worktrees.mode`, `decision_engine.on_block`).
+**It governs writes, not asks.** Four settings ship an `ask` value in their own
+enum (`tokens.rich_skills`, `subagents.adversarial_council`, `worktrees.mode`,
+`decision_engine.on_block`).
 Those are C-class here, and that is not a contradiction: the class says who may
 *persist* a new value; the `ask` value says what happens *at runtime* when the
 setting is already set to `ask`. A C-class key set to `ask` still produces a
@@ -129,18 +141,51 @@ larger set; it is the set that passes both halves.
 | `personal.canary_name` | un-inferrable, and answering arms the session-degradation canary; one keypress to accept the prefill | `""` (canary dark) |
 | `memory.learn_on_session_end` | it turns on automatic memory writes at the end of every session — a standing write the user should authorise | `false` |
 
+## The one exception — `emergency.orchestration_halt`
+
+The always-on-orchestration doctrine (subagents, council, team) deletes every
+per-layer on/off setting: `subagents.enabled`, `subagents.auto`, and
+`subagents.host_capabilities` are gone from the template, and the layer
+activates on any capable host with an EMPTY settings file. One switch survives
+that deletion on purpose, and it is not the same shape wearing a different
+name.
+
+```
+ON-BY-DEFAULT, NOT OFF-BY-DEFAULT. ABSENT OR false MEANS THE STACK RUNS.
+ARMING THE HALT IS CEREMONY-FREE — INCIDENTS ARE URGENT.
+DISARMING IT REQUIRES A NON-EMPTY orchestration_halt_justification.
+INCIDENT-RESPONSE USE ONLY.
+```
+
+**Enforcement, stated honestly (`enforced_by: none`).** The settings file is
+hand-edited YAML — no machine sits on the write path, so the
+justification-on-disarm rule and any per-transition telemetry are
+MODEL-CARRIED conventions, not checked gates (the same honesty stance as
+`security-sensitive-stop`). What IS checked: readers treat only strict
+`true` as halted, and the `no-activation-gates` lint prevents the switch
+from ever growing activation siblings. An agent editing this key follows
+the convention; a human editing it is the owner exercising it.
+
+The distinguishing test against "an activation gate under a new name": an
+activation gate is symmetric — flipping it either way costs the same nothing,
+and its purpose is to let a capability sit unused by default. This switch is
+asymmetric by convention — cheap to arm during an incident, costed (a stated
+reason) to disarm, never a silent preference. `subagents.downshift`, `subagents.quota_arbitrage`, and
+`subagents.model_map` are unaffected by the deletion — they tune HOW a
+dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
+
 ## Counts
 
 | Class | Keys |
 |---|---|
 | A — preference | 27 |
 | B — consent | 3 |
-| C — guarded | 110 |
-| **Total** | **140** |
+| C — guarded | 111 |
+| **Total** | **141** |
 
 The total is every leaf in the template, where *leaf* means anything that is not
-a **non-empty** map. An empty map (`subagents.host_capabilities: {}`) is a real
-configurable value with a real default, so it is a leaf here — one row more than
+a **non-empty** map. An empty map (like the former `subagents.host_capabilities: {}`) is a real
+configurable value with a real default, so such keys count as leaves here — one row more than
 the template↔schema parity test walks, deliberately, because a key with no
 class is exactly what this contract exists to prevent.
 
@@ -229,27 +274,25 @@ Rows follow template order, so a diff against the template reads straight down.
 | `screenshots.forbid_terminal_capture` | C | `true` | kill-switch over the highest-leak capture path |
 | `screenshots.data_bearing_gate` | C | `"on"` | the human-confirmation gate over a published egress |
 | `code_style.docblocks` | A | `minimal` | code convention |
-| `subagents.enabled` | C | `true` | kill-switch for the whole subagent layer |
-| `subagents.auto` | C | `"on"` | dispatches work without asking |
 | `subagents.downshift` | C | `true` | routes to another model tier, which is spend and quality |
-| `subagents.budget_routing` | C | `ask` | the budget-aware routing gate |
 | `subagents.quota_arbitrage` | C | `true` | spends from a separate quota pool |
 | `subagents.model_map.lite` | C | `""` | names an external model endpoint |
 | `subagents.model_map.medium` | C | `""` | names an external model endpoint |
 | `subagents.model_map.high` | C | `""` | names an external model endpoint |
-| `subagents.host_capabilities` | C | `{}` | overrides the host capability manifest |
 | `subagents.implementer_model` | C | `""` | names an external model endpoint |
 | `subagents.judge_model` | C | `""` | names an external model endpoint |
+| `subagents.model_ceiling` | C | `""` | session-wide subagent model cap (exported as `CLAUDE_CODE_SUBAGENT_MODEL` by suite-owned CLI spawn wrappers), which is spend and quality |
 | `subagents.max_parallel` | C | `3` | parallelism cap, and therefore a spend rate |
 | `subagents.adversarial_council` | C | `"off"` | governs a paid verification step |
 | `worktrees.mode` | C | `ask` | standing permission for autonomous worktree creation |
-| `ai_team.enabled` | C | `false` | authorises paid external CLI calls |
 | `ai_team.model` | C | `auto` | names an external model |
 | `ai_team.allow_delegate` | C | `false` | grants an external tool write access to the repository |
 | `ai_team.max_calls_per_day` | C | `50` | quota cap on a shared budget |
 | `ai_team.suppress_setup_hint` | A | `false` | hint cosmetics |
 | `ai_team.review_gate.managed` | C | `false` | governs an upstream review gate |
 | `ai_team.review_gate.max_consecutive_blocks` | C | `3` | circuit-breaker threshold |
+| `emergency.orchestration_halt` | C | `false` | the one audited incident switch over the always-on orchestration stack — see § The one exception above |
+| `emergency.orchestration_halt_justification` | C | `""` | required non-empty before the halt may be lifted; an audit-trail field |
 | `onboarding.onboarded` | C | `false` | flipping it bypasses the onboarding gate |
 | `commands.auto_detect` | C | `enabled` | kill-switch for orchestrator auto-detection |
 | `commands.suggestion.enabled` | A | `true` | a convenience layer; governs no gate and no spend |
@@ -282,6 +325,9 @@ Rows follow template order, so a diff against the template reads straight down.
 | `hooks.rtk_wrap.enabled` | C | `false` | configures code that runs on every tool call |
 | `hooks.design_slop.enabled` | C | `false` | configures code that runs on every tool call |
 | `hooks.code_graph.enabled` | C | `false` | configures code that runs on every tool call |
+| `hooks.turn_end_gate.enabled` | C | `false` | arms the only concern that can REFUSE a turn-end; an agent must never be able to switch its own delivery gate on |
+| `hooks.turn_end_gate.promissory` | C | `true` | which refusal the turn-end gate may raise; inert while the master switch is off |
+| `hooks.turn_end_gate.language` | C | `true` | which refusal the turn-end gate may raise; inert while the master switch is off |
 | `decision_engine.surface_traces` | C | `false` | the decision engine’s own black box; the agent must not be able to close it |
 | `decision_engine.min_confidence` | C | `"off"` | the confidence gate |
 | `decision_engine.block_on_risk` | C | `"off"` | the risk-class gate |

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.28.0",
+    "version": "9.30.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

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

@@ -0,0 +1,312 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config gates` — the open decisions that need the user, as actions.
+ *
+ * The dashboard (`update_roadmap_progress`) already parses every `## Blockers`
+ * entry and already counts them per roadmap. What it does not do is separate
+ * the blockers the *user* must resolve from the ones the maintainer or an
+ * external party owns: the count links into a per-roadmap breakdown, so
+ * answering "what do I have to do" means opening every anchor and filtering
+ * `Owner:` by hand across the whole file. The fields exist, are CI-enforced by
+ * `lint_roadmap_blockers`, and never reach the user in a form they can act on.
+ *
+ * This command is that missing projection, and nothing more: same parser
+ * (`parse_blockers` / `collect`, imported — never re-implemented), filtered by
+ * owner, ordered by how much each blocker unblocks, rendered action-first.
+ *
+ * Deliberately NOT a gate: it exits 0 whether or not decisions are pending.
+ * Blocking a pipeline on "the user has an open decision" would turn a
+ * visibility aid into a second thing to fight.
+ *
+ * Invocation (from project root):
+ *   ./agent-config gates            # decisions owned by the user
+ *   ./agent-config gates --all      # every open blocker, grouped by owner
+ *   ./agent-config gates --json     # machine-readable
+ */
+
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+import {
+    collect,
+    blocker_needs_user as needsUser,
+    type Blocker,
+} from './update_roadmap_progress.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Hard wrap for the rendered body — keeps output readable in a narrow pane. */
+const WIDTH = 78;
+
+interface Entry {
+    blocker: Blocker;
+    roadmapRel: string;
+    /** Open steps in the roadmap this blocker sits in — the "unblocks" weight. */
+    openSteps: number;
+}
+
+/**
+ * Rejoin wrapped continuation lines into one step each.
+ *
+ * `parse_blockers` returns `todo` as raw stripped lines, so a step that wraps
+ * over three source lines arrives as three entries. A new step starts at an
+ * ordered marker (`1.`, `2)`) or a bullet; everything else continues the one
+ * before it.
+ */
+function regroupTodo(todo: readonly string[]): string[] {
+    const steps: string[] = [];
+    for (const line of todo) {
+        const startsStep = /^(\d+[.)]|[-*+])\s/.test(line);
+        if (startsStep || steps.length === 0) {
+            steps.push(line);
+        } else {
+            steps[steps.length - 1] = `${steps[steps.length - 1] as string} ${line}`;
+        }
+    }
+    return steps;
+}
+
+/** Wrap `text` to `width`, indenting every line after the first by `indent`. */
+function wrap(text: string, width: number, indent: string): string[] {
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+        return [];
+    }
+    const lines: string[] = [];
+    let cur = '';
+    for (const w of words) {
+        const candidate = cur === '' ? w : `${cur} ${w}`;
+        if (candidate.length > width && cur !== '') {
+            lines.push(cur);
+            cur = w;
+        } else {
+            cur = candidate;
+        }
+    }
+    if (cur !== '') {
+        lines.push(cur);
+    }
+    return lines.map((l, i) => (i === 0 ? l : indent + l));
+}
+
+/**
+ * Column width for the label gutter — sized to the longest label in use
+ * (`Blocked until:`, 14 chars) plus one separating space, so no value ever
+ * runs flush against its own label.
+ */
+const LABEL_W = 15;
+
+/** A labelled block: `  Label:  value`, wrapped and hanging-indented. */
+function field(label: string, value: string): string[] {
+    const pad = '  ' + label.padEnd(LABEL_W);
+    const indent = ' '.repeat(pad.length);
+    const lines = wrap(value, WIDTH - pad.length, indent);
+    if (lines.length === 0) {
+        return [];
+    }
+    return [pad + lines[0], ...lines.slice(1)];
+}
+
+function collectEntries(roadmapRoot: string): Entry[] {
+    const entries: Entry[] = [];
+    for (const r of collect(roadmapRoot)) {
+        for (const b of r.open_blockers) {
+            entries.push({ blocker: b, roadmapRel: r.rel, openSteps: r.open_ });
+        }
+    }
+    // Most-unblocking first; ties broken deterministically so two runs on an
+    // unchanged tree print byte-identical output.
+    entries.sort(
+        (a, b) =>
+            b.openSteps - a.openSteps ||
+            a.roadmapRel.localeCompare(b.roadmapRel) ||
+            a.blocker.id.localeCompare(b.blocker.id),
+    );
+    return entries;
+}
+
+/**
+ * The parser's legacy fallback synthesises one blocker per `> Blocked until …`
+ * note under the fixed id `legacy`. That id is an implementation detail and
+ * says nothing to a reader, and its text is a *condition* ("blocked until X"),
+ * not an imperative — so both the heading and the field label are renamed for
+ * this one parser-defined case rather than dressed up as a step list.
+ */
+function isLegacy(b: Blocker): boolean {
+    return b.id === 'legacy';
+}
+
+function renderEntry(e: Entry, index: number): string[] {
+    const head = `${index} · ${isLegacy(e.blocker) ? 'blocked-until note' : e.blocker.id}`;
+    const tail =
+        e.openSteps > 0 ? `unblocks: ${e.openSteps} step${e.openSteps !== 1 ? 's' : ''}` : '';
+    const dashes = Math.max(3, WIDTH - head.length - tail.length - 6);
+    const out: string[] = [
+        '',
+        `── ${head} ${'─'.repeat(dashes)} ${tail}`.trimEnd(),
+        ...field('Roadmap:', e.roadmapRel),
+        ...field('Blocks:', e.blocker.blocks),
+    ];
+
+    const doLabel = isLegacy(e.blocker) ? 'Blocked until:' : 'Do this:';
+    const steps = regroupTodo(e.blocker.todo);
+    if (steps.length === 0) {
+        out.push(
+            ...field(
+                doLabel,
+                '(no steps recorded — the blocker entry in the roadmap needs a ' +
+                    '**What to do:** list)',
+            ),
+        );
+    } else {
+        out.push(...field(doLabel, steps[0] as string));
+        for (const s of steps.slice(1)) {
+            // Steps 2..n have no label of their own — align them under the
+            // first step's text, i.e. the same gutter `field()` produces.
+            const indent = ' '.repeat(LABEL_W + 2);
+            const lines = wrap(s, WIDTH - LABEL_W - 2, indent);
+            out.push(...lines.map((l, i) => (i === 0 ? indent + l : l)));
+        }
+    }
+    out.push(...field('Done when:', e.blocker.resolvedWhen));
+    return out;
+}
+
+function render(entries: readonly Entry[], all: boolean): string {
+    const mine = entries.filter((e) => needsUser(e.blocker.owner));
+    const others = entries.filter((e) => !needsUser(e.blocker.owner));
+    const shown = all ? entries : mine;
+    const lines: string[] = [];
+
+    if (mine.length === 0) {
+        lines.push(
+            others.length === 0
+                ? 'No open blockers at all.'
+                : `Nothing is waiting on you. ${others.length} open blocker` +
+                      `${others.length !== 1 ? 's' : ''} sit with maintainer/external` +
+                      `${all ? '' : ' — see --all'}.`,
+        );
+    } else {
+        const head =
+            `${mine.length} decision${mine.length !== 1 ? 's' : ''} need${mine.length === 1 ? 's' : ''} you`;
+        const rest =
+            others.length > 0
+                ? ` · ${others.length} more with maintainer/external${all ? '' : ' (--all)'}`
+                : '';
+        lines.push(head + rest);
+    }
+
+    let n = 0;
+    for (const e of shown) {
+        n += 1;
+        lines.push(...renderEntry(e, n));
+    }
+    if (shown.length > 0) {
+        lines.push('');
+    }
+    return lines.join('\n') + '\n';
+}
+
+function renderJson(entries: readonly Entry[], all: boolean): string {
+    const pick = all ? entries : entries.filter((e) => needsUser(e.blocker.owner));
+    return (
+        JSON.stringify(
+            {
+                needsYou: entries.filter((e) => needsUser(e.blocker.owner)).length,
+                other: entries.filter((e) => !needsUser(e.blocker.owner)).length,
+                blockers: pick.map((e) => ({
+                    id: e.blocker.id,
+                    roadmap: e.roadmapRel,
+                    owner: e.blocker.owner,
+                    needsYou: needsUser(e.blocker.owner),
+                    blocks: e.blocker.blocks,
+                    unblocksSteps: e.openSteps,
+                    todo: regroupTodo(e.blocker.todo),
+                    resolvedWhen: e.blocker.resolvedWhen,
+                })),
+            },
+            null,
+            2,
+        ) + '\n'
+    );
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Same repo-root resolution as the dashboard: honour the cwd when it holds
+ * `agents/roadmaps`, otherwise fall back to the git toplevel (monorepo
+ * sub-project support).
+ */
+function _resolveRepoRoot(start: string): string {
+    if (_isDir(path.join(start, 'agents', 'roadmaps'))) {
+        return start;
+    }
+    try {
+        const r = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: start,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        const top = (r.stdout || '').trim();
+        if (r.status === 0 && top !== '' && _isDir(path.join(top, 'agents', 'roadmaps'))) {
+            return top;
+        }
+    } catch {
+        /* not a git repo / git missing — keep the cwd default */
+    }
+    return start;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const all = args.includes('--all');
+    const json = args.includes('--json');
+
+    const repoRoot = _resolveRepoRoot(process.cwd());
+    const roadmapRoot = path.join(repoRoot, 'agents', 'roadmaps');
+    if (!_isDir(roadmapRoot)) {
+        process.stdout.write(
+            json ? '{"needsYou":0,"other":0,"blockers":[]}\n' : 'No roadmaps directory — nothing to report.\n',
+        );
+        return 0;
+    }
+
+    const entries = collectEntries(roadmapRoot);
+    process.stdout.write(json ? renderJson(entries, all) : render(entries, all));
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvPath = path.resolve(process.argv[1]);
+    if (import.meta.url === pathToFileURL(argvPath).href) {
+        return true;
+    }
+    // A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
+    // macOS /var → /private/var) makes the raw URLs differ: import.meta.url is
+    // the resolved real path while argv[1] keeps the symlink. Compare realpaths
+    // so the entry guard still fires through the projection.
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(argvPath);
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}
+
+export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson };
+export type { Entry };

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

@@ -398,14 +398,32 @@ function _blockerField(slice: string, label: string): string | null {
     return parts.length ? parts.join(' ') : null;
 }
 
-/** Lines under `- **What to do:**` up to the next `- **Field:**` marker. */
+/**
+ * The `- **What to do:**` text: the remainder of the marker line, plus every
+ * line under it up to the next `- **Field:**` marker.
+ *
+ * The marker line's own remainder is load-bearing and used to be dropped.
+ * Authors write both shapes — a numbered list under the marker, and prose that
+ * starts inline (`- **What to do:** the build work is done; only real …`) —
+ * and every *other* blocker field reads the inline part via `_blockerField`.
+ * Skipping it here truncated instructions mid-sentence in both the dashboard
+ * and `agent-config gates`, which is precisely the content those surfaces
+ * exist to deliver.
+ */
 function _blockerTodo(slice: string): string[] {
     const lines = _splitlines(slice);
-    const startIdx = lines.findIndex((l) => /^-[ \t]*\*\*What to do:\*\*/i.test(_strip(l)));
+    const markerRe = /^-[ \t]*\*\*What to do:\*\*[ \t]*(.*)$/i;
+    const startIdx = lines.findIndex((l) => markerRe.test(_strip(l)));
     if (startIdx === -1) {
         return [];
     }
     const out: string[] = [];
+    const inline = _stripComment(
+        (markerRe.exec(_strip(lines[startIdx] as string))?.[1] as string) ?? '',
+    );
+    if (inline) {
+        out.push(inline);
+    }
     for (let i = startIdx + 1; i < lines.length; i++) {
         const trimmed = _strip(lines[i] as string);
         if (BLOCKER_FIELD_RE.test(trimmed) || trimmed.startsWith('#')) {
@@ -458,18 +476,56 @@ function parse_blockers(raw_text: string): Blocker[] {
     }
     const legacyMatch = LEGACY_BLOCKED_UNTIL_RE.exec(text);
     if (legacyMatch) {
+        // The legacy note is a blockquote and routinely wraps over several
+        // `> ` lines. The regex captures one line, so the continuation used to
+        // be dropped and the instruction ended mid-sentence — the same defect
+        // `_blockerTodo` carried above. Walk the following quoted lines until
+        // the quote block ends.
+        const parts = [_strip(legacyMatch[1] as string)];
+        const allLines = _splitlines(text);
+        const noteIdx = allLines.findIndex((l) => LEGACY_BLOCKED_UNTIL_RE.test(_strip(l)));
+        for (let i = noteIdx + 1; noteIdx !== -1 && i < allLines.length; i++) {
+            const quoted = /^>[ \t]?(.*)$/.exec(_strip(allLines[i] as string));
+            if (!quoted) {
+                break;
+            }
+            const cont = _strip(quoted[1] as string);
+            if (cont === '') {
+                break;
+            }
+            parts.push(cont);
+        }
         blockers.push({
             id: 'legacy',
             status: 'open',
             owner: 'user',
             blocks: 'entire roadmap',
-            todo: [_strip(legacyMatch[1] as string)],
+            todo: [parts.join(' ')],
             resolvedWhen: 'condition described above clears',
         });
     }
     return blockers;
 }
 
+/**
+ * Does this blocker need the human at the keyboard, rather than the maintainer
+ * or an external party?
+ *
+ * Owner values in the wild are not the clean `user | maintainer | external`
+ * enum the template comment suggests — real entries carry qualifiers
+ * (`user (billable spend)`, `user / maintainer`, `maintainer (security role)`).
+ * Word-boundary matching on `user` keeps the qualified forms and rejects
+ * `maintainer`. A shared `user / maintainer` blocker deliberately counts as the
+ * user's: showing one decision too many costs a line, hiding one costs the wait.
+ *
+ * Lives here rather than in `roadmap_gates` because it is owner *semantics*,
+ * not presentation — the dashboard header and `agent-config gates` must agree
+ * on the split, and two copies of this regex would drift.
+ */
+function blocker_needs_user(owner: string): boolean {
+    return /\buser\b/i.test(owner);
+}
+
 function parse_roadmap(p: string, roadmap_root: string): RoadmapStats | null {
     const text = fs.readFileSync(p, { encoding: 'utf-8' });
     const phase_matches: Array<{ start: number; end: number; g2: string; g3: string | undefined }> =
@@ -674,6 +730,14 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
     const total_open_blockers = roadmaps.reduce((s, r) => s + r.open_blockers.length, 0);
+    // The count alone answers "is something blocked", never "is it on me" —
+    // and the per-roadmap anchors make the owner split a manual read across the
+    // whole file. Name the user's share here and point at the command that
+    // renders those entries as actions.
+    const user_open_blockers = roadmaps.reduce(
+        (s, r) => s + r.open_blockers.filter((b) => blocker_needs_user(b.owner)).length,
+        0,
+    );
     const lines: string[] = [];
     lines.push('# Roadmap Progress\n');
     const header_meta =
@@ -682,7 +746,10 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
         ' · [roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · ' +
         '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)' +
         (total_open_blockers > 0
-            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}`
+            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}` +
+              (user_open_blockers > 0
+                  ? `, **${user_open_blockers}** need you → \`agent-config gates\``
+                  : '')
             : '') +
         '\n';
     lines.push(
@@ -1074,6 +1141,7 @@ export {
     is_roadmap_candidate,
     count_checkboxes,
     parse_blockers,
+    blocker_needs_user,
     parse_roadmap,
     bar,
     collect,

package/src/agent-src/templates/AGENTS.md

@@ -1,6 +1,6 @@
 # {{project_name}}
 
-<!-- Fill placeholders or run `/agents init`; delete after. Capability bullets, not paths. Recipes: `.augment/contexts/contracts/agents-md-anatomy.md`. -->
+<!-- Fill placeholders or run `/agents init`; delete after. Recipes: `.augment/contexts/contracts/agents-md-anatomy.md`. -->
 
 > {{project_description}}
 
@@ -8,8 +8,8 @@
 
 | Layer | Location | Edits |
 |---|---|---|
-| Installed package | `.augment/`, `dist/agent-src/` | hands-off — managed by `event4u/agent-config` |
-| Project layer | `agents/`, `agents/overrides/`, `.agent-settings.yml` | your customizations and config |
+| Installed package | `.augment/`, `dist/agent-src/` | managed by `event4u/agent-config` |
+| Project layer | `agents/`, `agents/overrides/`, `.agent-settings.yml` | your customizations |
 
 ## Pointers
 
@@ -18,7 +18,7 @@
 - **Skills (on-demand expertise)** — domain skills surfaced by description, invoked on trigger match: [`.augment/skills/`](.augment/skills/).
 - **Commands (workflows)** — slash-commands the agent runs end-to-end (`/work`, `/create-pr`, …): [`.augment/commands/`](.augment/commands/).
 - **Project-specific docs** — your own architecture notes, roadmaps, sessions, contexts: [`agents/`](agents/).
-- **Delegation & review** — dispatch independent-slice tasks to subagents instead of serial work; a mutating session ends after a neutral cross-model review: [`delegation-policy`](.augment/rules/delegation-policy.md).
+- **Delegation & review** — dispatch independent-slice tasks to subagents instead of serial work; in a team (host-flag gated) the lead coordinates, teammates implement; a mutating session ends after a neutral cross-model review: [`delegation-policy`](.augment/rules/delegation-policy.md).
 
 ## Emergency triage — read this when nothing else is reachable