@event4u/agent-config 9.0.0 → 9.1.0

package/docs/guidelines/agent-infra/api-cost-levers.md

@@ -0,0 +1,126 @@
+# API Cost Levers
+
+Reference material for a downstream AI-coding agent that wants to cut its own
+Claude API dollar bill. Four platform-level billing levers, the exact economics
+of each, and how they interact. Read on demand — not always-loaded.
+
+Facts sourced from the in-repo `claude-api` plugin skill plus platform research
+(2026-07-14). Do not invent an API shape beyond what is stated here.
+
+## The four levers at a glance
+
+| Lever | Cuts | Best for | Watch out for |
+|---|---|---|---|
+| Prompt caching | Repeated input tokens | Stable prefix reused across calls (system prompt, tools, repo map) | Any byte change in the prefix invalidates the rest |
+| Batch API | 50% input + output | Non-interactive bulk work (classification, summarization, evals) | Async, up to 24h, results unordered |
+| Model tiering | Per-token price | Routine work on a cheaper model | Switching model is a cache miss |
+| Effort / output sizing | Thinking + output tokens | Routine turns that don't need deep reasoning | Oversized `max_tokens` risks runaway output |
+
+## 1. Prompt caching
+
+Put the large, byte-**stable** context first — system prompt, tool definitions,
+a corpus or repo map, few-shot examples — behind a
+`cache_control: {type: 'ephemeral'}` breakpoint. Keep volatile content (the
+varying question, timestamps, per-request IDs) **after** the last breakpoint.
+The cache is a **prefix match**: any byte change in the cached prefix
+invalidates everything after it. Render order is tools then system then
+messages.
+
+Caching is GA — **no beta header needed**.
+
+Economics:
+
+- Cache reads cost approximately 0.1x the base input price.
+- Cache writes cost 1.25x (5-minute TTL) or 2x (1-hour TTL).
+- Break-even is after **one** read on the 5-minute TTL.
+
+Constraints:
+
+- The minimum cacheable prefix is model-dependent (approximately 1024–4096
+  tokens). Shorter prefixes silently do not cache.
+- The cache is workspace-isolated (since February 2026).
+
+Verify a hit with `usage.cache_read_input_tokens > 0`.
+
+```json
+{
+  "system": [
+    { "type": "text", "text": "<large stable system prompt>",
+      "cache_control": { "type": "ephemeral" } }
+  ],
+  "messages": [
+    { "role": "user", "content": "<the varying question>" }
+  ]
+}
+```
+
+## 2. Batch API
+
+For **non-interactive, non-latency-sensitive bulk work** — bulk classification,
+mass file summarization, eval runs. Not chatbots or interactive assistants.
+
+- **50% off both input and output tokens.**
+- Async: results within 24h (usually much less), keyed by `custom_id`, arriving
+  **unordered** — key results by `custom_id`, never by position.
+- **Stacks with prompt caching**: a cached-batch input token can reach
+  approximately 0.05x the standard input price.
+
+## 3. Model tiering
+
+Treat models like a team — a cheap model for mechanical or routine work, the
+expensive model only for hard judgment. Approximate input / output price per 1M
+tokens:
+
+| Model | Input | Output |
+|---|---|---|
+| Haiku | $1 | $5 |
+| Sonnet | $3 | $15 |
+| Opus | $5 | $25 |
+| Fable | $10 | $50 |
+
+Opus input is approximately 5x Haiku. Tier by task **difficulty**, not blindly:
+a cheaper model that gives wrong answers on judgment tasks costs correction
+cycles, which erases the saving.
+
+**Interaction with caching.** The prompt cache is keyed by `(model, prefix)`, so
+switching a call to a cheaper model is a cache **miss**. Weigh the downgrade
+saving against the lost cache-read saving before routing a cached call to a
+different model.
+
+## 4. Effort and output right-sizing
+
+- `output_config.effort` (low through max) controls thinking and output depth,
+  and therefore spend. Dial effort **down** on routine turns; reserve high / max
+  for hard reasoning.
+- Right-size `max_tokens` — do not leave a huge ceiling. An unrealistically
+  large `max_tokens` does not cost tokens by itself, but it risks runaway output
+  and defeats pre-flight budgeting.
+
+## When to reach for which
+
+| Situation | Lever |
+|---|---|
+| Same large context reused across many calls | Prompt caching |
+| Thousands of independent, non-urgent jobs | Batch API (+ caching) |
+| Turn is mechanical / narrow / well-specified | Cheaper model tier |
+| Turn is routine and does not need deep thinking | Lower `effort` |
+| Output could balloon unnecessarily | Cap `max_tokens` |
+| Interactive latency matters | Caching + tiering; not Batch |
+
+## Claude Code note
+
+In Claude Code, prompt caching is automatic — resending the same context prefix
+is cheap, so keeping a stable prefix pays off without any explicit
+`cache_control`. The session-level hygiene levers are `/clear` and `/compact` to
+shed accumulated context, plus subagent delegation for verbose output so it
+never lands in the main context window.
+
+## See also
+
+- [`model-recommendation.md`](model-recommendation.md) — tier routing (the
+  capability band behind lever 3).
+- [`size-and-scope.md`](size-and-scope.md) — token discipline for the artifacts
+  that become the cached prefix.
+- The Claude Code `claude-api` plugin skill (external, not vendored here) — the
+  authoritative, versioned API reference these figures derive from; re-check it
+  when Anthropic pricing or the caching/batch surface changes.

package/docs/installation.md

@@ -3,7 +3,8 @@
 **Principle:** Global is the only consumer scope. `init` writes to
 user-scope paths (`~/.event4u/agent-config/`, `~/.claude/`,
 `~/.cursor/`, …); the project tree only gets `agents/overrides/`
-and `agents/.event4u-bridge.yml`. Opt-in `export` if a team wants
+(the bridge marker was retired — ADR-020 amendment 2026-07-13; the
+global root resolves from `~/.event4u/agent-config`). Opt-in `export` if a team wants
 a tool's config committed to a repo. No Task, no Make, no build
 tools required.
 

package/docs/maintainers/dev-mode.md

@@ -23,8 +23,9 @@ With the flag set, the installer:
 1. Allows project-scope writes back into the repo tree (so a
    maintainer can run `task dev:install-global` and iterate on the
    working copy).
-2. **Skips** writing `agents/.event4u-bridge.yml` into the package
-   repo (per `consumer-bridge § Writer contract`). The repo is the
+2. **Skips** consumer-surface writes into the package repo. (The
+   `agents/.event4u-bridge.yml` marker is retired — ADR-020 amendment
+   2026-07-13 — and no longer written at all.) The repo is the
    source, not a consumer of itself.
 3. Treats `~/.event4u/agent-config/` as a peer install — touches are
    limited to the working-copy projection.

package/docs/proof.md

@@ -27,7 +27,7 @@ evidence pointer, or `task check-claims` fails the build.
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
-| 183 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 184 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | A MEASURED-BUT-NOT-SHIPPED experiment — the thin rule projection reduced eager rule load 78,513 → 13,881 GPT-tokens (whole always-loaded projection 98,529 → 33,897, ~65.6%), but FAILED the quality gate (thin win-rate 36.2% vs required 48%) and does not ship; it un-defers only behind `discipline_profile: essential`. Shipped behavior does NOT include this reduction. Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4); quality gate per the Phase-0 paired judge run. | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | The first cross-vendor parity pass (5 orchestration-corpus tasks × 2 vendors × 3 repeats, identical prompts via the council transport, $0.16) measured real per-host finding-count differences — claude-sonnet-4-5 surfaced ~2× the findings of gpt-4o on the multi-file analysis task (median 11 vs 5) while both vendors were identical on the planted hollow-implementation task (2 vs 2) and perfectly silent on the clean-code negative control (0 vs 0, no spurious findings). The per-task `finding_floor` values are calibrated from the cross-host lower envelope and the gate is armed. | quant | `internal/bench/reports/parity-count.json#min over hosts of median` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
@@ -45,7 +45,7 @@ evidence pointer, or `task check-claims` fails the build.
 | On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
 | Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
 | Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
-| 274 skills. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 275 skills. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | Removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries. | qual | `docs/contracts/install-layout.md#JSON-pointer` | ✅ |
 
 **21 backed claim(s)** — all evidence pointers resolve in CI.
@@ -77,11 +77,11 @@ shipping theater; the full per-cell data is committed at
 `internal/bench/reports/persona-placebo.json`.
 
 **Behavioural-eval coverage — the honest baseline.** Skill *quality* is only
-as good as its measurement. Today **42 of 274** skills carry a behavioural
+as good as its measurement. Today **42 of 275** skills carry a behavioural
 `evals.json`; the highest-traffic / highest-cost tiers (default-surface +
 `rich` + routers) are **fully covered (35 of 35)**, the long tail
-(7 of 239) is not. We publish that gap rather than imply
-"274 evaluated skills": coverage is measured per tier
+(7 of 240) is not. We publish that gap rather than imply
+"275 evaluated skills": coverage is measured per tier
 (`./scripts-run src/scripts/skill_eval_coverage`), **CI-ratcheted so it can
 only rise**, and the priority tiers carry a hard **tier floor**: every
 rich / default-surface / router skill MUST have a behavioural eval or an

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "9.0.0",
+    "version": "9.1.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/agent-src/templates/scripts/work_engine/_lib/agent_settings.ts

@@ -252,7 +252,10 @@ const _AGENTS_DIR_MARKERS: readonly string[] = [
     'roadmaps',
     'settings/.ai-council.yml',
     'roadmaps-progress.md',
-    '.event4u-bridge.yml',
+    // `overrides/` is the guaranteed minimal-consumer surface (ADR-020).
+    // Replaced the retired `.event4u-bridge.yml` marker (ADR-020 amendment
+    // 2026-07-13) so a bare consumer `agents/` dir stays anchorable.
+    'overrides',
 ];
 
 /**

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

@@ -761,6 +761,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,