@event4u/agent-config 9.0.0 → 9.2.0

package/src/config/agent-settings.template.yml

@@ -518,6 +518,34 @@ design:
   #              autonomy setting, roadmap, or standing instruction lifts it).
   fidelity_mode: strict
 
+# --- Cross-source consistency ---
+#
+# When the agent plans, refines, roadmaps, or implements from multiple
+# sources — ticket text, an attached image / mockup / screenshot, the spec,
+# the codebase — it actively checks them AGAINST each other and STOPS to ask
+# before proceeding on a detected discrepancy, instead of silently guessing
+# (even a correct guess). Consumed by the `cross-source-consistency` rule.
+# Catches: (a) ticket text vs an attached image/mockup, (b) a spec silent on
+# a clearly-needed behavior (weekend/holiday shifting, empty/error states),
+# (c) spec vs the codebase, (d) intra-ticket contradiction (AC vs description).
+#
+# The discipline is deliberately subordinate to `ask-when-uncertain` (it folds
+# a detected discrepancy into the same turn's single question — never a second
+# prompt) and defers to `scope-control` for the permission to expand scope.
+consistency:
+  # on | auto | off  (default: on)
+  #
+  # on   = default. Detect discrepancies across sources and surface ONE
+  #        numbered-options question before proceeding. A silent guess on a
+  #        real contradiction is a rule violation, even when the guess is
+  #        correct. An inferred-but-unspecified behavior is a scope expansion:
+  #        ask before implementing it.
+  # auto = detect + surface only HIGH-confidence contradictions; low-confidence
+  #        ones are stated as an assumption and proceed (noise control).
+  # off  = no cross-source checking (legacy: the agent may proceed on its own
+  #        reading of whichever source it happened to read).
+  cross_source: "on"
+
 code_style:
   # minimal | full  (default: minimal)
   #
@@ -604,6 +632,20 @@ subagents:
   # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
   max_parallel: 3
 
+  # Opt-in adversarial-verification-council (subagent-orchestration Mode 9,
+  # ADR-122):  off | ask | on
+  #
+  # off (default) = never runs. ask = offer it on an explicit high-risk change.
+  # on = auto-run on high-risk changes (security, tenant, migration, public API).
+  #
+  # A panel of distinct-model skeptics red-teams a real, already-verified change
+  # for defect FINDING coverage (not a go/no-go decision) and returns an advisory
+  # findings-by-severity verdict. ADVISORY ONLY — it NEVER auto-gates the change
+  # (Hard Floor). The registered claim + high-risk tier use cross-vendor skeptics.
+  # Stays default-off until the adversarial-council-finding-coverage claim is
+  # backed by the two-stage residual-detection benchmark (prove-or-drop).
+  adversarial_council: off
+
 # --- Git worktrees ---
 #
 # Controls how the `using-git-worktrees` skill and `subagent-orchestration`
@@ -761,6 +803,45 @@ commands:
   create_pr:
     preview_description: false
 
+    # Verbosity tier for the generated PR description body.
+    #   min (default) = title + 2-3 sentence what/why/impact + linked ticket.
+    #                   Token-frugal. Critical info (breaking changes,
+    #                   migrations, security, rollback) is ALWAYS included
+    #                   regardless of tier — the tier governs explanatory
+    #                   depth, never whether a critical callout appears.
+    #   med           = min + grouped logical changes + tests note.
+    #   max           = med + how-to-test + edge cases / trade-offs +
+    #                   reviewer guidance (the richest, ~legacy output).
+    detail_level: min
+
+    # JSON request/response examples for API-endpoint changes.
+    #   true (default) = include a fenced example ONLY when it can be
+    #                    grounded in a real source (response DTO/resource,
+    #                    OpenAPI/schema, test fixture, or an actual probe).
+    #                    No grounded source → a one-line pointer, never an
+    #                    invented example (a hallucinated contract misleads
+    #                    reviewers, so it is worse than none).
+    #   false          = never add API examples.
+    api_examples: true
+
+    # Screenshots for frontend changes. Default false (off). Capability-gated:
+    # requires the host to have browser/preview tooling (Playwright / a
+    # dev-server URL). When true + a frontend change + no such tooling, the
+    # agent emits a one-line note and leaves the template placeholder — it
+    # never fails or blocks PR creation, and never claims an embed that did
+    # not happen. Before/after + changed-region highlighting is best-effort.
+    #   false (default) = never attempt screenshots.
+    #   true            = attempt when capable (see command contract).
+    screenshots: false
+
+    # Optional glob lists that make frontend / API-endpoint detection
+    # explicit instead of heuristic. Empty (default) = the command uses a
+    # light path/extension heuristic and fails open (no false enrichment
+    # when the surface is ambiguous). Populate to pin your project's paths,
+    # e.g. ui_paths: ["resources/views/**", "src/pages/**"].
+    ui_paths: []
+    api_paths: []
+
 # --- Memory ---
 #
 # Engineering memory consolidation behaviour. Memory is entirely

package/src/config/gitignore-block.txt

@@ -1,12 +1,9 @@
 # Agent config — tool-scope leftovers (ADR-020 § global-only consumer
 # install). After the Phase-5 migration the entire `.augment/`, `.claude/`,
 # `.cursor/` trees live under `~/.event4u/agent-config/`; consumers carry
-# only `agents/overrides/` + `agents/.event4u-bridge.yml`. The per-tool
-# bridge pointer files for Windsurf / Cline / Gemini-CLI live under
-# `.windsurf/`, `.clinerules/`, `.gemini/` and ARE committed — those
-# directories stay tracked (not listed here). Pre-Phase-5 entries kept
-# as a defence-in-depth ignore list for legacy installs that have not
-# migrated yet — Phase 5 unstages them on first migrate run.
+# only `agents/overrides/`. Pre-Phase-5 entries kept as a defence-in-depth
+# ignore list for legacy installs that have not migrated yet — Phase 5
+# unstages them on first migrate run.
 .augment/skills/
 .augment/commands/
 .augment/guidelines/
@@ -21,6 +18,19 @@
 .claude/CLAUDE.md
 .cursor/rules/
 
+# Agent config — consumer bridge marker + per-tool project anchors.
+# The bridge marker was retired (ADR-020 amendment 2026-07-13): it carried
+# no project-specific data (global_root resolves from `~/.event4u/agent-config`)
+# yet was committed and rewritten by every developer's install. The global
+# root is now the well-known path. The Windsurf / Cline / Gemini-CLI anchors
+# remain (those tools cannot read user scope) but are gitignored — each
+# developer regenerates them on install; they are never shared. The install
+# deletes any legacy committed marker; this entry keeps a stale one ignored.
+/agents/.event4u-bridge.yml
+.windsurf/agent-config.bridge.yml
+.clinerules/agent-config.bridge.yml
+.gemini/agent-config.bridge.yml
+
 # Agent config — Phase 5 migration snapshot (ADR-020). Written by
 # `agent-config migrate-to-global` as a copy-then-move safety net so a
 # migration can be rolled back. Local-only — never commit.

package/src/scripts/_cli/cmd_conformance.ts

@@ -47,7 +47,7 @@ import {
     _run_checks_no_manifest,
     _scan_foreign,
     ArgparseExit,
-    BRIDGE_MARKER_RELATIVE,
+    _is_global_only_consumer,
     STATUS_SYMBOLS,
 } from './cmd_doctor.js';
 
@@ -630,7 +630,7 @@ function main(argv: string[] | null = null): number {
     let doctorChecks: Dict[];
     let drift: Record<string, Dict[]> = { missing: [], modified: [], foreign: [], tag_drift: [] };
     if (manifest === null) {
-        const bridge_present = fs.existsSync(path.join(project_root, BRIDGE_MARKER_RELATIVE));
+        const bridge_present = _is_global_only_consumer(project_root);
         doctorChecks = _run_checks_no_manifest(project_root, bridge_present, null);
     } else {
         const [records, known] = _collect_manifest_entries(project_root, manifest);

package/src/scripts/_cli/cmd_doctor.ts

@@ -100,6 +100,12 @@ import {
 import * as ai_council_clients from '../ai_council/clients.js';
 import * as ai_council_config from '../ai_council/config.js';
 import { review_gate_doctor_signal } from '../ai_team/review_gate.js';
+import {
+    LEGACY_ALL,
+    excludedRuleBasenames,
+    ruleScopeFromSettings,
+    type RuleScope,
+} from '../../install/rule_scope.js';
 
 type Dict = Record<string, unknown>;
 
@@ -738,6 +744,7 @@ const CHECK_IDS = [
     'surface-state',
     'hook-wiring',
     'stale-orphans',
+    'rule-scope-drift',
     'manifest-integrity',
     'lockfile-freshness',
     'bridge-drift',
@@ -764,6 +771,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'surface-state',
     'hook-wiring',
     'stale-orphans',
+    'rule-scope-drift',
     'mcp-mode',
     'mcp-beta-readiness',
     'offline-readiness',
@@ -783,8 +791,20 @@ const MANIFEST_REQUIRED_CHECK_IDS: ReadonlySet<string> = new Set([
     'unsupported-combos',
 ]);
 
-/** Project-root-relative path of the ADR-020 global-only consumer marker. */
-const BRIDGE_MARKER_RELATIVE = 'agents/.event4u-bridge.yml';
+/**
+ * Signals a set-up global-only consumer. The `.event4u-bridge.yml` marker was
+ * retired (ADR-020 amendment 2026-07-13); the durable project-side signal is
+ * the install-mode marker (written on every install) or the `agents/overrides/`
+ * scaffold. Either is sufficient.
+ */
+const INSTALL_MODE_MARKER_RELATIVE = 'agents/.agent-state/install-mode.txt';
+
+function _is_global_only_consumer(project_root: string): boolean {
+    return (
+        isFile(path.join(project_root, INSTALL_MODE_MARKER_RELATIVE)) ||
+        isDir(path.join(project_root, 'agents', 'overrides'))
+    );
+}
 
 /** Repair targets that `--repair <id>` accepts. */
 const REPAIR_IDS = ['wizard-state'] as const;
@@ -1091,15 +1111,16 @@ function _check_global_binary(project_root: string): Dict {
             remedy: 'agent-config upgrade (refresh the global install + plugin)',
         };
     }
-    const bridge = path.join(project_root, 'agents', '.event4u-bridge.yml');
-    const bridge_note = isFile(bridge) ? '' : ' · no project bridge marker';
+    const consumer_note = _is_global_only_consumer(project_root)
+        ? ''
+        : ' · no project install marker';
     return {
         id: 'global-binary',
         status: 'ok',
-        message: `on PATH (${binary}); version ${binary_v || 'unknown'}${bridge_note}`,
-        remedy: !bridge_note
+        message: `on PATH (${binary}); version ${binary_v || 'unknown'}${consumer_note}`,
+        remedy: !consumer_note
             ? ''
-            : 'agent-config refresh --project (scaffold the bridge marker)',
+            : 'agent-config refresh --project (scaffold agents/overrides/)',
     };
 }
 
@@ -1590,6 +1611,130 @@ function _check_stale_orphans(): Dict {
     };
 }
 
+/**
+ * Per-file rule projection trees a consumer install writes (basenames match
+ * the shipped `dist/agent-src/rules` tree). The first one that exists and
+ * holds ≥ 1 `.md` rule is the surface we diff against the consumer's scope.
+ */
+const _RULE_PROJECTION_DIRS: readonly string[] = [
+    '.augment/rules',
+    '.windsurf/rules',
+    '.cursor/rules',
+    '.clinerules',
+];
+
+/**
+ * Rule-scope drift (road-to-request-scoped-rule-load, 9.0 consumer flip).
+ *
+ * After the 9.0 default flip to consumer-scoped rule projection, a consumer
+ * whose settings now exclude maintainer-only workspaces may still carry a
+ * pre-flip FULL/GLOBAL rule projection on disk. This check diffs the scope
+ * the consumer's settings imply against the rules actually projected and
+ * reports the leftover set as an ACTIONABLE diff (not a bare boolean).
+ *
+ * The scope-derived expected set reuses the ONE install-time scoping surface
+ * (`rule_scope.ts`), so doctor's diagnosis can never drift from the install
+ * semantics. `excludedRuleBasenames` returns exactly the rules PRESENT in the
+ * projected tree that the current scope says should NOT arrive.
+ *
+ * Degrades gracefully: `skipped` in the agent-config source repo (the in-repo
+ * `.augment/rules` is the full generated projection, not a consumer surface)
+ * and `skipped` when no projected rule tree is present to inspect.
+ */
+function _check_rule_scope_drift(project_root: string): Dict {
+    if (_is_source_repo(project_root)) {
+        return {
+            id: 'rule-scope-drift',
+            status: 'skipped',
+            message: 'agent-config source repo — no consumer rule projection to inspect',
+            remedy: '',
+        };
+    }
+
+    // Consumer projection scope (absent / empty settings → legacy-all: every
+    // rule ships, so nothing is ever out of scope).
+    let scope: RuleScope = LEGACY_ALL;
+    const settings_file = project_settings_path(project_root);
+    if (isFile(settings_file)) {
+        const loaded = yamlSafeLoad(readText0(settings_file));
+        const raw =
+            typeof loaded === 'object' && loaded !== null && !Array.isArray(loaded)
+                ? (loaded as Dict)
+                : {};
+        scope = ruleScopeFromSettings(raw);
+    }
+
+    // First projected rule tree that exists and holds a `.md` rule.
+    let rules_dir: string | null = null;
+    let found = 0;
+    for (const rel of _RULE_PROJECTION_DIRS) {
+        const cand = path.join(project_root, rel);
+        if (!isDir(cand)) {
+            continue;
+        }
+        let count = 0;
+        try {
+            for (const name of fs.readdirSync(cand)) {
+                if (name.endsWith('.md') && isFile(path.join(cand, name))) {
+                    count += 1;
+                }
+            }
+        } catch {
+            continue;
+        }
+        if (count > 0) {
+            rules_dir = cand;
+            found = count;
+            break;
+        }
+    }
+    if (rules_dir === null) {
+        return {
+            id: 'rule-scope-drift',
+            status: 'skipped',
+            message: 'no projected rule tree found (.augment/rules, .windsurf/rules, …) — nothing to inspect',
+            remedy: '',
+        };
+    }
+
+    let unexpected: string[];
+    try {
+        unexpected = excludedRuleBasenames(rules_dir, scope);
+    } catch (exc) {
+        const rel = relativeTo(rules_dir, project_root) ?? rules_dir;
+        return {
+            id: 'rule-scope-drift',
+            status: 'fail',
+            message: `cannot inspect ${rel}: ${osErrorStr(exc)}`,
+            remedy: 'check read permissions on the projected rule tree',
+        };
+    }
+
+    const rel_dir = relativeTo(rules_dir, project_root) ?? rules_dir;
+    if (unexpected.length === 0) {
+        return {
+            id: 'rule-scope-drift',
+            status: 'ok',
+            message: `rule projection matches scope (${found} rules in ${rel_dir})`,
+            remedy: '',
+        };
+    }
+    const expected = found - unexpected.length;
+    const sample = unexpected.slice(0, 8);
+    const more = unexpected.length - sample.length;
+    const names = sample.join(', ') + (more > 0 ? `, +${more} more` : '');
+    return {
+        id: 'rule-scope-drift',
+        status: 'warn',
+        message:
+            `rule-scope drift in ${rel_dir}: expected ${expected} rules, found ${found} — ` +
+            `${unexpected.length} unexpected (out of scope): ${names}`,
+        remedy:
+            're-run `agent-config init --project` (or `agent-config global`) to re-project rules ' +
+            'under the current scope — these are leftover from a pre-9.0 full/global projection',
+    };
+}
+
 function _check_python_runtime(): Dict {
     // Post-teardown: the package runtime is TypeScript-on-`tsx`. python3 is no
     // longer a runtime dependency, so this check no longer probes for an
@@ -2525,6 +2670,7 @@ function _run_checks(
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
+        'rule-scope-drift': () => _check_rule_scope_drift(project_root),
         'manifest-integrity': () => _check_manifest_integrity(manifest),
         'lockfile-freshness': () => _check_lockfile_freshness(manifest),
         'bridge-drift': () =>
@@ -2582,8 +2728,8 @@ function _check_bridge_drift_no_manifest(bridge_present: boolean): Dict {
         id: 'bridge-drift',
         status: 'skipped',
         message:
-            'no project lockfile and no bridge marker → drift check ' +
-            'not applicable',
+            'no project lockfile and no consumer install marker → drift ' +
+            'check not applicable',
         remedy:
             'run `agent-config init` (project install) or ' +
             '`agent-config refresh --project` (global-only consumer)',
@@ -2604,6 +2750,7 @@ function _run_checks_no_manifest(
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
+        'rule-scope-drift': () => _check_rule_scope_drift(project_root),
         'manifest-integrity': () => _skipped_manifest_check('manifest-integrity'),
         'lockfile-freshness': () => _skipped_manifest_check('lockfile-freshness'),
         'bridge-drift': () => _check_bridge_drift_no_manifest(bridge_present),
@@ -2647,7 +2794,7 @@ function _run_no_manifest(
         print(`  📍  project_root: ${project_root} (origin: ${origin})`);
         if (bridge_present) {
             print(
-                '  ℹ️   global-only consumer: bridge marker present, no ' +
+                '  ℹ️   global-only consumer: install marker present, no ' +
                     'project lockfile (expected under ADR-020)',
             );
             print(
@@ -2655,7 +2802,7 @@ function _run_no_manifest(
                     'to project-local distributed tools',
             );
         } else {
-            eprint(`  ⚠️   no project lockfile and no bridge marker at ${project_root}`);
+            eprint(`  ⚠️   no project lockfile and no consumer install marker at ${project_root}`);
             eprint(
                 '      run `agent-config init` (project install) or ' +
                     '`agent-config refresh --project` (global-only consumer)',
@@ -2998,7 +3145,7 @@ function main(argv: string[] | null = null): number {
     const manifest_pth = installed_tools.manifest_path(project_root);
     const manifest = installed_tools.read_manifest(manifest_pth);
     if (manifest === null) {
-        const bridge_present = isFile(path.join(project_root, BRIDGE_MARKER_RELATIVE));
+        const bridge_present = _is_global_only_consumer(project_root);
         return _run_no_manifest(opts, project_root, origin, bridge_present);
     }
 
@@ -3099,6 +3246,7 @@ export {
     _check_mcp_mode,
     _check_offline_readiness,
     _check_stale_orphans,
+    _check_rule_scope_drift,
     _check_python_runtime,
     _check_humanizer_runtime,
     _check_mcp_beta_readiness,
@@ -3122,7 +3270,8 @@ export {
     CHECK_IDS,
     GLOBAL_CHECK_IDS,
     MANIFEST_REQUIRED_CHECK_IDS,
-    BRIDGE_MARKER_RELATIVE,
+    INSTALL_MODE_MARKER_RELATIVE,
+    _is_global_only_consumer,
     REPAIR_IDS,
     MCP_BETA_GATES,
     STATUS_SYMBOLS,

package/src/scripts/_cli/cmd_refresh.ts

@@ -16,9 +16,11 @@
  *   global root + Claude plugin hooks are rewritten from the
  *   currently-installed package. Idempotent: a second run is a no-op diff.
  * - `--project` — refresh the **minimal** project surface ADR-020 permits for
- *   a consumer: the `agents/.event4u-bridge.yml` marker, an `agents/overrides/`
- *   scaffold, and the managed `agents/` block in `.gitignore`. Writes **no**
- *   distributed content. No wizard.
+ *   a consumer: an `agents/overrides/` scaffold and the managed `agents/`
+ *   block in `.gitignore`, plus cleanup of any legacy
+ *   `agents/.event4u-bridge.yml` (the marker was retired — ADR-020 amendment
+ *   2026-07-13; the global root is resolved from `~/.event4u/agent-config`).
+ *   Writes **no** distributed content. No wizard.
  *
  * Bare `agent-config refresh` (no scope flag) errors — never a silent global
  * default (council 2026-05-30).
@@ -39,17 +41,15 @@
  *   `cannot run <cmd[0]>: <err>` line to stderr and returns 1, mirroring the
  *   Python `except OSError`. The runner is injectable for tests.
  * - `_lib.*` / `scripts.install` / `scripts.sync_gitignore` imports resolve to
- *   the `.ts` twins. `scripts.install._write_consumer_bridge_marker` is
- *   module-private in the install twin (not exported); it is replicated here
- *   byte-for-byte from the install-twin source — its helper chain
- *   (`_format_global_root_for_marker`, the atomic 0644 write, the UTC stamp,
- *   `user_global_paths.event4u_root`) is replicated alongside, keeping the
- *   shared import surface unchanged (same approach as `cmd_update.ts`).
+ *   the `.ts` twins. `scripts.install._remove_legacy_consumer_bridge_marker`
+ *   is module-private in the install twin (not exported); it is replicated
+ *   here — a small `isFile` + `fs.rmSync` guard gated on dev-mode / source
+ *   repo, matching the install-twin source.
  * - `Path(__file__).resolve().parents[3]` → `path.resolve(_HERE_DIR, '..',
  *   '..', '..')`. `.is_file()` / `.is_dir()` / `.exists()` →
  *   `_isFile` / `_isDir` / `_exists`. The `packages/` source-marker glob probe
  *   becomes a `readdirSync` scan of `packages/` (the source-marker dir name is
- *   the `SRC_MARKER_DIR` constant, shared with the bridge-marker guard).
+ *   the `SRC_MARKER_DIR` constant, shared with the marker-cleanup guard).
  * - `print(..., file=out/err)` → an injectable `OutSink` defaulting to
  *   `process.stdout` / `process.stderr`. The Python `out`/`err` kwargs default
  *   to `sys.stdout` / `sys.stderr`.
@@ -60,17 +60,13 @@
  *   `except ImportError` branch wording.
  */
 
-import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import * as installed_lock from '../_lib/installed_lock.js';
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
-import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as sync_gitignore from '../sync_gitignore.js';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
@@ -149,103 +145,30 @@ const CONSUMER_BRIDGE_MARKER_RELPATH = path.join('agents', '.event4u-bridge.yml'
  */
 const SRC_MARKER_DIR = '.agent-src.uncondensed';
 
-/** `Path.resolve()` — absolute, symlink-resolved where possible. */
-function resolvePath(p: string): string {
-    try {
-        return fs.realpathSync(path.resolve(p));
-    } catch {
-        return path.resolve(p);
-    }
-}
-
-function _format_global_root_for_marker(global_root: string): string {
-    const home = resolvePath(os.homedir());
-    const resolved = resolvePath(global_root);
-    const rel = path.relative(home, resolved);
-    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-        return global_root;
-    }
-    return `~/${rel.split(path.sep).join('/')}`;
-}
-
-/** `datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")`. */
-function utcStamp(now?: Date): string {
-    const d = now ?? new Date();
-    const pad = (n: number, w = 2): string => String(n).padStart(w, '0');
-    return (
-        `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}` +
-        `T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}Z`
-    );
-}
-
-function mkdirp(p: string): void {
-    fs.mkdirSync(p, { recursive: true });
-}
-
-/** `tempfile.mkstemp` + write + `os.chmod(0o644)` + `os.replace` (atomic). */
-function atomicWrite0644(target: string, body: string, prefix: string): void {
-    const dir = path.dirname(target);
-    const tmpName = path.join(
-        dir,
-        `${prefix}${process.pid}.${crypto.randomBytes(6).toString('hex')}.yml.tmp`,
-    );
-    let fd: number | null = null;
-    try {
-        fd = fs.openSync(tmpName, 'wx', 0o644);
-        fs.writeFileSync(fd, body, 'utf-8');
-        fs.closeSync(fd);
-        fd = null;
-        fs.chmodSync(tmpName, 0o644);
-        fs.renameSync(tmpName, target);
-    } catch (err) {
-        if (fd !== null) {
-            try {
-                fs.closeSync(fd);
-            } catch {
-                /* fd may already be closed */
-            }
-        }
-        try {
-            fs.unlinkSync(tmpName);
-        } catch {
-            /* best-effort cleanup */
-        }
-        throw err;
-    }
-}
 
 /**
- * Mirrors `install._write_consumer_bridge_marker` (module-private). Returns the
- * written path, or `null` when skipped (dev mode / source repo).
+ * Mirrors `install._remove_legacy_consumer_bridge_marker` (module-private).
+ * The consumer bridge marker was retired (ADR-020 amendment 2026-07-13); the
+ * global root is resolved from the well-known `~/.event4u/agent-config` path.
+ * `refresh --project` deletes any legacy `agents/.event4u-bridge.yml` a prior
+ * install committed. Returns the removed path, or `null` when nothing to do
+ * (no marker / dev mode / source repo).
  */
-function _write_consumer_bridge_marker(
+function _remove_legacy_consumer_bridge_marker(
     project_root: string,
-    installer_version: string,
     env: NodeJS.ProcessEnv | null = null,
-    now: Date | null = null,
 ): string | null {
     const env_map = env ?? process.env;
     if (env_map['AGENT_CONFIG_DEV_MODE'] === '1') return null;
     if (_isDir(path.join(project_root, SRC_MARKER_DIR))) return null;
 
-    const global_root_str = _format_global_root_for_marker(
-        user_global_paths.event4u_root(env_map),
-    );
-    const stamp = utcStamp(now ?? undefined);
-
-    const body =
-        '# event4u/agent-config — consumer bridge marker (auto-written).\n' +
-        '# Spec: docs/contracts/consumer-bridge.md (event4u-bridge/v1).\n' +
-        '# Reader contract: expand ~ against the current $HOME; fail closed\n' +
-        '# when global_root is missing on disk; never write back through it.\n' +
-        'schema: event4u-bridge/v1\n' +
-        `global_root: ${global_root_str}\n` +
-        `installed_at: ${stamp}\n` +
-        `installer_version: ${installer_version}\n`;
-
     const target = path.join(project_root, CONSUMER_BRIDGE_MARKER_RELPATH);
-    mkdirp(path.dirname(target));
-    atomicWrite0644(target, body, '.event4u-bridge.');
+    if (!_isFile(target)) return null;
+    try {
+        fs.rmSync(target);
+    } catch {
+        return null;
+    }
     return target;
 }
 
@@ -292,10 +215,10 @@ function _refresh_global(runner: Runner, out: OutSink, err: OutSink): number {
 /**
  * True when `project_root` is the agent-config package itself.
  *
- * `_write_consumer_bridge_marker` only guards on a root-level
+ * `_remove_legacy_consumer_bridge_marker` only guards on a root-level
  * `.agent-src.uncondensed/`, which the monorepo keeps under `packages/<pkg>/`
- * instead — so the narrow guard misses here and would write a consumer marker
- * into the maintainer tree. This broader check (condensed output, packaged
+ * instead — so the narrow guard misses here and would touch the maintainer
+ * tree. This broader check (condensed output, packaged
  * source, or the package's own `package.json` name) makes `refresh --project`
  * a no-op in any agent-config checkout. Consumers use dev-mode, not refresh.
  */
@@ -350,20 +273,14 @@ function _refresh_project(project_root: string, out: OutSink, err: OutSink): num
         return 0;
     }
 
-    const version = installed_lock.current_package_version() || '0.0.0';
-    const marker = _write_consumer_bridge_marker(project_root, version);
-    if (marker === null) {
-        _print(
-            out,
-            'ℹ️  refresh --project skipped the bridge marker: this is the ' +
-                'agent-config source repo (or AGENT_CONFIG_DEV_MODE=1). Nothing ' +
-                'to scaffold in a maintainer checkout.',
-        );
-        return 0;
+    // Bridge marker retired (ADR-020 amendment 2026-07-13). The global root is
+    // resolved from the well-known `~/.event4u/agent-config` path, so there is
+    // no per-project marker to scaffold — clean up any legacy one instead.
+    const removed = _remove_legacy_consumer_bridge_marker(project_root);
+    if (removed !== null) {
+        _print(out, `✅  removed legacy bridge marker: ${removed}`);
     }
 
-    _print(out, `✅  bridge marker: ${marker}`);
-
     const overrides = path.join(project_root, 'agents', 'overrides');
     fs.mkdirSync(overrides, { recursive: true });
     const keep = path.join(overrides, 'README.md');
@@ -372,8 +289,8 @@ function _refresh_project(project_root: string, out: OutSink, err: OutSink): num
             keep,
             '# Project overrides\n\n' +
                 'Project-local overrides/extensions of shared skills, rules, and ' +
-                'commands. The only project-side agent surface ADR-020 permits ' +
-                'besides the bridge marker. See the `override-management` skill.\n',
+                'commands. The only project-side agent surface ADR-020 permits. ' +
+                'See the `override-management` skill.\n',
         );
     }
     _print(out, `✅  overrides scaffold: ${overrides}`);
@@ -543,7 +460,7 @@ export {
     _is_source_repo,
     _refresh_project,
     _sync_gitignore,
-    _write_consumer_bridge_marker,
+    _remove_legacy_consumer_bridge_marker,
     ArgparseExit,
 };
 export type { Args, Runner };