@event4u/agent-config 8.13.0 → 9.1.0

package/docs/benchmark.md

@@ -453,7 +453,7 @@ covers only 14/89 rules (operator hand-labelling), a separate gap.
 - Runner: `src/scripts/bench_quality_run.ts` (`--dry-run` free / live is
   API-gated); gate: `src/scripts/check_quality_regression.ts` (inert until a
   `quality-run.json` — gitignored — exists locally).
-- Roadmap: `agents/roadmaps/road-to-token-saving.md` Phase 0.
+- Roadmap: `agents/roadmaps/later/road-to-token-saving.md` Phase 0.
 
 ## Length-neutral judge RERUN (2026-07-12) — SECOND INCONCLUSIVE, gate CLOSED-BY-DIAGNOSIS
 
@@ -492,4 +492,69 @@ anchor-scoring against `must_include`/`must_not`, not pairwise LLM judging).
 
 - Runner: `src/scripts/bench_quality_rerun.ts` (design-pinned constants:
   band ±15%, κ floor 0.60, ρ flag 0.3, effect floor 10pp; `--max-usd` guard).
-- Roadmap: `agents/roadmaps/road-to-opt-measurement-unblock.md` Phase 1.
+- Roadmap: `agents/roadmaps/archive/road-to-opt-measurement-unblock.md` Phase 1.
+
+## Cross-model parity count (2026-07-12) — PASS, `finding_floor` armed
+
+The most-deferred portfolio item (cross-model parity eval, deferred across 4+
+roadmaps) landed in its re-scoped form: council-transport execution instead of
+an in-host subagent harness (`docs/design/cross-model-parity-eval.md`). Each
+orchestration-corpus task is rendered self-contained (fixture files inlined)
+and dispatched identically to two vendors; the output contract forces a
+numbered findings list (or `NO FINDINGS`), counted with the **same**
+`_count_findings` the `finding_floor` eval gate uses.
+
+| Task | sonnet median | gpt-4o median | Calibrated floor |
+|---|---|---|---|
+| orch-01 multi-file analysis | 11 | 5 | 5 |
+| orch-02 ordered refactor | 5 | 3 | 3 |
+| orch-03 competitive impl | 3 | 0 | 1 (clamp) |
+| pv-01 hollow detection | 2 | 2 | 2 |
+| pv-02 negative control | 0 | 0 | — (control, excluded) |
+
+Signal, honestly stated:
+
+- **Real cross-vendor gap** — sonnet surfaces ~2× gpt-4o's findings on the
+  multi-file analysis task. A floor calibrated on sonnet alone would
+  systematically fail gpt-4o; the cross-host lower envelope
+  (`max(1, min over hosts of median)`) is the correct floor shape.
+- **Planted defect is vendor-stable** — both vendors cite the hollow
+  `charge.ts` (2 findings each, zero variance across repeats).
+- **Negative control perfect** — 0 findings from both vendors on clean code
+  across all repeats; the counting contract does not reward spurious findings.
+
+Cost: $0.16 actual (30 calls; ceiling $8 authorized). `finding_floor` is now an
+**enforcing** gate (comment flipped in `run_skill_evals.ts`); calibration data
+in `internal/bench/reports/parity-count.json`.
+
+- Runner: `src/scripts/bench_parity_count.ts` (pre-registered: 3 repeats,
+  2 vendors, envelope floor rule, controls excluded, `--max-usd` abort).
+- Roadmap: `agents/roadmaps/archive/road-to-opt-measurement-unblock.md` Phase 3.
+
+## Non-Claude lift replication, second vendor host (2026-07-12) — HONEST NULL
+
+The `discipline_profile: auto` flip gate required a replicated lift on a
+non-Claude host. Executed per the parked design (paired vanilla vs
+`rules-kernel-dc` = the essential cut, 30 tasks × 3 seeds) on the codex CLI
+host with `gpt-5.5` (ChatGPT account).
+
+- **Capability:** 92% → 89% (McNemar p = 1.0) — no effect.
+- **Discipline:** 1.000 → 0.892 (Δ = −0.108, Wilcoxon p = 0.0225 on 7
+  non-zero pairs) — no lift; directionally **negative** on this host.
+- **Verdict:** NO replicated lift. `discipline_profile` keeps its
+  vendor-granular default (`unknown_defaults`, no `auto` flip) — consistent
+  with the 2026-07-10 two-host precedent (claude strong-host ceilings) and
+  the earlier gpt-5-mini replication failure on the same injection surface.
+
+Limitations, published: the ChatGPT-account usage limit rejected 100 of 180
+runs mid-corpus (plus 2 timeouts), leaving n = 37 valid pairs — the
+truncation is **balanced across arms** (50/52), so it weakens power but does
+not bias the comparison. An earlier same-day fire misfired entirely (model
+pin omitted → all runs API-rejected, $0) and is excluded as a harness error,
+not evidence. Raw report is local-only by design
+(`internal/bench/reports/ab-v2/` is gitignored); this section + the roadmap
+notes are the durable record. Re-open path: a full uncapped 180-run
+replication on a per-token-billed key.
+
+- Runner: `src/scripts/bench_ab_v2_run.ts --host codex` (checkpoint-resumable).
+- Roadmap: `agents/roadmaps/archive/road-to-opt-measurement-unblock.md` Phase 2.

package/docs/catalog.md

@@ -569,11 +569,11 @@ are excluded.
 | command | [`team-knowledge`](../dist/agent-src/commands/team-knowledge.md) | cluster: team-knowledge | Team-knowledge orchestrator — routes to consolidate and bootstrap |
 | command | [`team-knowledge-bootstrap`](../dist/agent-src/commands/team-knowledge/bootstrap.md) | cluster: team-knowledge | One-shot deterministic seed for a fresh project's knowledge layer — stages template pages from real config/directory detection, never LLM-invented claims. Review-then-commit. |
 | command | [`team-knowledge-consolidate`](../dist/agent-src/commands/team-knowledge/consolidate.md) | cluster: team-knowledge | Review pending typed knowledge-observation events and file them into agents/knowledge/ pages as a human-reviewed batch — never writes without approval. |
-| command | [`team`](../dist/agent-src/commands/team.md) | cluster: team | Team orchestrator — cross-model depth review (one strong model builds, a second reviews the real diff); routes to review, adversarial, delegate, status |
+| command | [`team`](../dist/agent-src/commands/team.md) | cluster: team | Team orchestrator — governed cross-model access layer (a second strong model reviews the real diff; read-only multi-host fallback); routes to review, adversarial, delegate, status |
 | command | [`team-adversarial`](../dist/agent-src/commands/team/adversarial.md) | cluster: team | Thin wrapper — adversarial cross-model review on a named focus via the official plugin (/codex:adversarial-review). Escalation rung above the single-model adversarial-review skill. |
 | command | [`team-delegate`](../dist/agent-src/commands/team/delegate.md) | cluster: team | Thin wrapper — hand a task to the second model as a native worker via the official plugin (/codex:rescue). The only write-access wrapper; double-gated behind ai_team.allow_delegate. |
 | command | [`team-review`](../dist/agent-src/commands/team/review.md) | cluster: team | Thin wrapper — cross-model review of the current diff via the official plugin (/codex:review). Gated on ai_team.enabled; fails closed when the plugin is absent. |
-| command | [`team-status`](../dist/agent-src/commands/team/status.md) | cluster: team | Thin wrapper — plugin job status via /codex:status plus a ledger line with today's cli_call_budget openai count. Gated on ai_team.enabled; fails closed when the plugin is absent. |
+| command | [`team-status`](../dist/agent-src/commands/team/status.md) | cluster: team | Thin wrapper — plugin job status via /codex:status plus a quota block showing the shared openai counter against both ceilings (team + council). Gated on ai_team.enabled; fails closed when the plugin… |
 | command | [`tests`](../dist/agent-src/commands/tests.md) | cluster: tests | Tests orchestrator — routes to create, execute, e2e-plan, e2e-heal |
 | command | [`tests-create`](../dist/agent-src/commands/tests/create.md) | cluster: tests | Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …) |
 | command | [`tests-e2e-heal`](../dist/agent-src/commands/tests/e2e-heal.md) | cluster: tests | Find, debug, and fix failing Playwright E2E tests |

package/docs/command-flows.md

@@ -7,7 +7,7 @@
 
 > Every command is classified in `src/flows/surface-map.yaml` (coverage enforced by `scripts/lint_command_flow_coverage.py`). The four user-work flows carry rich definitions in `src/flows/<flow>.yaml`.
 
-**183 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
+**184 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
 
 ## User-work flows
 

package/docs/contracts/agents-layout.md

@@ -100,7 +100,7 @@ After `agent-config migrate`, a consumer project's `agents/` contains only:
 | Entry | Rationale |
 |---|---|
 | `overrides/` | Per-project skill/rule customisation |
-| `.event4u-bridge.yml` | ADR-020 bridge marker (global-only install) |
+| `.event4u-bridge.yml` | Retired (ADR-020 amendment 2026-07-13); global root resolves from `~/.event4u/agent-config`. Legacy leftover only — deleted by installer / `refresh --project`. |
 | `.gitkeep` | Keeps `agents/` in the tree |
 | `knowledge/` | Optional: curated project-specific knowledge pages |
 | `memory/` | Optional: promotion pipeline (intake gitignored, curated YAML committed) |

package/docs/contracts/ai-council-config.md

@@ -787,11 +787,18 @@ error) when any of these hold:
 
 ## Migration footprint (Phase 0)
 
+> Historical record of the Step-2 consolidation. **The project-local file
+> described below is no longer read** — ADR-104 (superseding ADR-093) moved
+> the council config to the user-global location documented at the top of
+> this contract. A `.ai-council.yml` under any project `agents/` tree is
+> ignored. Read this section for provenance only, not for placement.
+
 - `.agent-settings.yml` → 14-key inventory under `ai_council:` removed
   after a one-line breadcrumb comment is in place pointing at this
   contract.
 - `.agent-settings.template.yml` → same removal.
-- New file `agents/settings/.ai-council.yml` checked in with two enabled
+- New file `agents/settings/.ai-council.yml` checked in with two enabled <!-- council-config-allowed -->
   providers (anthropic + openai) and three disabled
   (gemini + xai + perplexity). Models pre-filled from the Phase 0
-  default set; comments mirror this contract.
+  default set; comments mirror this contract. *(This project-tracked file
+  was later removed; per ADR-104 the config is user-global only.)*

package/docs/contracts/ai-team-config.md

@@ -47,6 +47,9 @@ ai_team:
   allow_delegate: <bool>          # second opt-in for the write path, default false
   max_calls_per_day: <int >= 0>   # default 50; counts into the shared openai bucket
   suppress_setup_hint: <bool>     # default false; cosmetic wizard-hint suppression
+  review_gate:                    # managed governance of the plugin's Stop-hook Review Gate
+    managed: <bool>               # default false = byte-identical pre-Phase-4 behavior
+    max_consecutive_blocks: <int >= 1>  # default 3; circuit-breaker loop bound
 ```
 
 | Key | Type | Default | Semantics |
@@ -56,6 +59,8 @@ ai_team:
 | `allow_delegate` | bool | `false` | Second opt-in for the **only** wrapper that delegates write access (`/team:delegate`). Refuses with an enable pointer until BOTH `enabled` and `allow_delegate` are `true`. |
 | `max_calls_per_day` | int ≥ 0 | `50` | Per-day ceiling on team calls, read against the **shared** `cli_call_budget` openai bucket (see § Quota). `0` blocks all team calls. |
 | `suppress_setup_hint` | bool | `false` | Suppress the one-line wizard/init recommendation to install the codex plugin on Claude-Code hosts. Cosmetic only. |
+| `review_gate.managed` | bool | `false` | Managed governance of the codex plugin's Stop-hook Review Gate (Phase 4). `false` = no counting, no circuit breaker — the Stop path is byte-identical to pre-Phase-4 dispatch. `true` = consecutive BLOCK verdicts are counted per session (first-line `ALLOW:`/`BLOCK:` contract of the gate transcript; anything else is honestly `UNKNOWN` and never counted) and the circuit breaker trips at the bound. |
+| `review_gate.max_consecutive_blocks` | int ≥ 1 | `3` | Circuit-breaker bound. At this many CONSECUTIVE BLOCKs in one session a visible notice is injected **exactly once** and the managed layer stops re-blocking — the user decides, never an infinite Claude↔Codex loop. An ALLOW verdict resets the counter. Unknown keys inside `review_gate` are rejected fail-closed, same as the parent block. |
 
 ### Why `model: 'auto'` instead of a pinned ID
 
@@ -68,10 +73,14 @@ default, and only the codex CLI knows what that currently is. `'auto'`
 therefore delegates the choice to the CLI; a set value is a user pin and
 passes through verbatim — the loader never rewrites or "corrects" it.
 
-**Future keys:** `review_gate` (managed, loop-bound governance of the
-plugin's Stop-hook Review Gate) is reserved for a later team-mode phase
-(Phase 4). Do not add it — or any other key — ahead of its phase; the
-loader rejects unknown keys today by design.
+**`review_gate` (Phase 4, shipped):** the loop-bound governance block is
+live — module `src/scripts/ai_team/review_gate.ts` (counter state under
+`agents/runtime/state/team-review-gate.json`, ledger under
+`agents/runtime/team/events.log`, one `team.gate: BLOCK 2/3` /
+`ALLOW reset` line per gate verdict). The gate itself stays upstream's;
+upstream's own warning applies while it is enabled unmanaged: "The
+review gate can create a long-running Claude/Codex loop and may drain
+usage limits quickly." Any other key stays rejected fail-closed.
 
 ## Role semantics — the council-verdict design constraint
 
@@ -141,6 +150,30 @@ same *counter*: whichever path a call takes, it increments the one shared
 bucket, and each surface enforces its own configured cap against that
 shared count.
 
+**Worked example — two ceilings, one counter.** Council ceiling
+`cli_call_budget.max_calls_per_day.openai: 100`, team ceiling
+`ai_team.max_calls_per_day: 50`, shared counter at 45 openai calls today:
+both paths are open. Five team calls later the counter reads 50 — team
+calls are now blocked (50 >= 50) while council CLI calls continue until
+the counter reaches 100. Whichever path fires a call, the same counter
+moves; each surface only decides where *its* ceiling sits on that shared
+count. `/team status` renders exactly this state: the live counter, both
+ceilings, and which path (if any) is currently blocked.
+
+### Team-review envelope
+
+Every `/team:review` return — plugin path and multi-host fallback alike — is emitted in the
+team-review status envelope (`src/skills/subagent-orchestration/schemas/team-review-status.json`),
+which extends the `subagent-status.json` frame: `status` (`DONE | DONE_WITH_CONCERNS |
+NEEDS_CONTEXT | BLOCKED`), `findings[]` (`severity`/`evidence`/`suggested_fix`/`location?`),
+`reviewed_ref` (HEAD sha of the bundle), `model` (`'auto'` = codex CLI default), and
+`quota` (`{used, ceiling}` on the shared `cli_call_budget` openai bucket); unparseable model
+output is preserved verbatim in `raw` with status `DONE_WITH_CONCERNS` — never silently dropped.
+Plugin text is summarized INTO the envelope and preserved verbatim beneath — never rewritten.
+<!-- PLACEHOLDER: the team-review-envelope subsection (review-gate ledger
+     line format `team.gate: BLOCK n/N` read by /team status) is inserted
+     here by the orchestrator in a later step. Do not remove this marker. -->
+
 ## Validation rules (fail-closed)
 
 `load_ai_team_config` / `build_ai_team_config`

package/docs/contracts/consumer-bridge.md

@@ -1,81 +1,73 @@
 ---
-stability: beta
-keep-beta-until: 2026-08-21
+stability: stable
 ---
 
-# Consumer Bridge Marker
+# Consumer Bridge Marker (retired)
 
-**Status:** Proposed — road-to-global-only-install Phase 4.1.
+**Status:** Retired — [`ADR-020 § Amendment 2026-07-13`](../decisions/ADR-020-global-only-consumer-scope.md#amendment--2026-07-13--bridge-marker-retired).
 **Pairs with:** [`ADR-020 — global-only consumer scope`](../decisions/ADR-020-global-only-consumer-scope.md), [`ADR-007 § Amendment 2026-05-13`](../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only).
 
-## Purpose
-
-After Phase 3 of `road-to-global-only-install` lands, a consumer
-project carries **only** `agents/overrides/` plus this bridge marker.
-Every other agent artefact (rules, skills, commands, personas,
-settings, user identity) is read from `~/.event4u/agent-config/`. The
-bridge marker is the single, declarative pointer that lets per-tool
-adapters (Windsurf, Cline, Gemini-CLI, the Augment workspace
-projector) locate the global root from inside the repo.
-
-## File
-
-`agents/.event4u-bridge.yml` at the consumer project root. <!-- ref-ignore -->
-Written by `scripts/install.py` on every successful consumer install
-(global scope). Idempotent — same file, refreshed `installed_at`.
-
-## Schema
+## Why it was retired
+
+The bridge marker `agents/.event4u-bridge.yml` was a per-project file that
+pointed at the global install. It carried **no project-specific data**:
+`global_root` is always the well-known `~/.event4u/agent-config` (one global
+install per machine), and nothing in the codebase ever read the field — the
+loader, doctor, and conformance checks all derive the global root independently
+via `user_global_paths.event4u_root()`. Yet the marker was **committed** to the
+shared project tree and rewrote its volatile `installed_at` / `installer_version`
+fields on every install, so each developer's install produced a diff and
+overwrote every other developer's committed copy. A file whose scope (global)
+did not match its location (per-project, committed) — pure churn.
+
+It is retired: the global root is resolved directly from the well-known path.
+
+## What replaced it
+
+- **Global-root resolution** — `user_global_paths.event4u_root()` returns
+  `~/.event4u/agent-config` (overridable via `EVENT4U_CONFIG_HOME`). Readers fail
+  closed when that path is missing on disk. No per-project pointer is consulted.
+- **Migration-idempotency sentinel** — moved to
+  `agents/.agent-state/install-mode.txt` (written on every full / minimal
+  install), which the installer's legacy-detection and the doctor's
+  "global-only consumer" branch key on. `agents/overrides/` is an equivalent
+  signal.
+- **Project anchor** — a bare consumer `agents/` directory is anchored on
+  `agents/overrides/` (the guaranteed minimal-consumer surface), not the marker.
+- **Cleanup** — the installer and `agent-config refresh --project` delete any
+  legacy `agents/.event4u-bridge.yml` a prior install committed; the managed
+  `.gitignore` block also ignores it so a stale copy is never re-committed.
+
+## Per-tool anchor strategy (still active)
+
+Some AI tools only load rules when an anchor file is **inside** the workspace
+(Windsurf, Cline, Gemini-CLI). For those IDs the installer plants a thin pointer
+file under the tool's per-project directory:
 
 ```yaml
 schema: event4u-bridge/v1
+tool: windsurf
 global_root: ~/.event4u/agent-config
-installed_at: 2026-05-23T14:00:00Z
-installer_version: 2.4.0
+installed_at: 2026-07-13T00:00:00Z
 ```
 
-### Fields
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `schema` | string | yes | Must equal `event4u-bridge/v1`. Bumped on breaking field changes. |
-| `global_root` | string | yes | Absolute path or `~`-prefixed path to the global install. Readers MUST expand `~` against the current user's `$HOME`. |
-| `installed_at` | string (ISO-8601 UTC) | yes | Timestamp of the last successful install or refresh. |
-| `installer_version` | string (semver) | yes | Version of `@event4u/agent-config` that produced the marker. |
-
-Unknown fields are ignored by `v1` readers (forward-compat).
-
-## Reader contract
-
-Per-tool adapters MUST:
-
-1. Read `agents/.event4u-bridge.yml` from the project root. <!-- ref-ignore -->
-2. Reject `schema != event4u-bridge/v1` with a clear error pointing at this contract.
-3. Expand `~` in `global_root` against the **current process's** `$HOME` (not the writer's).
-4. Fail closed if `global_root` is missing on disk — never silently fall back to project-local lookup.
-5. Treat the marker as **read-only data**. Adapters MUST NOT write back through it.
-
-## Writer contract
-
-`scripts/install.py` MUST:
-
-1. Write the marker atomically (temp file + rename) so a crash never leaves a half-formed pointer.
-2. Refresh `installed_at` + `installer_version` on every consumer-scope install.
-3. Use `0644` permissions (world-readable, owner-writable). The marker contains no secrets.
-4. Skip the write under `AGENT_CONFIG_DEV_MODE=1` — maintainer dev installs never lay the bridge into the source repo (this repo's `agents/` directory is the project surface, not a consumer surface).
-
-The marker is (re-)written by the consumer install, by the wizard's apply step, and by `agent-config refresh --project` — which also scaffolds `agents/overrides/` and syncs the managed `agents/` block in `.gitignore` (the full minimal project surface, no wizard). `refresh --project` no-ops inside an agent-config checkout (same source-repo guard as rule 4).
-
-## Per-tool anchor strategy
-
-Some AI tools only load rules when an anchor file is **inside** the workspace (Windsurf, Cline, Gemini-CLI). For those IDs, Phase 4.3 plants a thin pointer file under the tool's per-project directory whose body resolves to the bridge marker. Tools that load purely from user-scope (Claude Code, Cursor, Augment) read the marker once and need no per-tool file.
+- Files: `.windsurf/agent-config.bridge.yml`, `.clinerules/agent-config.bridge.yml`,
+  `.gemini/agent-config.bridge.yml`.
+- `global_root` is the well-known path (readers expand `~` against the current
+  `$HOME`, never the writer's). There is no `bridge:` back-pointer — the retired
+  marker no longer exists to point at.
+- These anchors are **gitignored**: each developer regenerates them on install,
+  so they never churn in version control. Tools that load purely from user scope
+  (Claude Code, Cursor, Augment) need no per-tool file.
 
-## Out of scope
+## Legacy reader note
 
-- Cross-machine sync of `~/.event4u/agent-config/` (the marker is local-only).
-- Editing the marker by hand to swap installs (use `agent-config init --global-root=…` instead, once that flag ships in Phase 5).
-- Multi-tenant `global_root` (one marker = one global install per project).
+A `v1` marker left in an un-migrated consumer repo still parses as before
+(`schema: event4u-bridge/v1`, `~`-expanded `global_root`). Do not add new readers
+of it — resolve the global root from the well-known path instead. The next
+install removes it.
 
 ## References
 
-- [`ADR-020`](../decisions/ADR-020-global-only-consumer-scope.md) — global-only consumer scope; cites the in-flight roadmap for Phase 4 surface design + Phase 5 migration order.
+- [`ADR-020`](../decisions/ADR-020-global-only-consumer-scope.md) — global-only consumer scope + the 2026-07-13 retirement amendment.
 - [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md) — scope precedence and the global-default amendment.

package/docs/contracts/install-layout.md

@@ -72,7 +72,7 @@ run writes only the subset for the selected scope + tools.
 |---|---|---|
 | `<root>/agents/settings/.agent-settings.yml` | deployed | canonical YAML settings (ADR-038) |
 | `<root>/.agent-settings.yml` | deployed | legacy fallback; migrated then removed on first run |
-| `<root>/agents/.event4u-bridge.yml` | bridge | project → `~/.event4u/agent-config/` pointer; schema `event4u-bridge/v1` |
+| `<root>/agents/.event4u-bridge.yml` | retired | Retired (ADR-020 amendment 2026-07-13); no longer written. Global root resolves from `~/.event4u/agent-config`; installer / `refresh --project` delete any legacy leftover. |
 | `<root>/agents/.agent-state/install-mode.txt` | marker | `minimal\n` or `full\n` |
 
 Minimal-install scaffold (override layer): `agents/overrides/{rules,skills,commands}/.gitkeep`,

package/docs/contracts/migrate-command.md

@@ -178,7 +178,7 @@ intentionally **outside** the unified `migrate` command:
 | Write a fresh `.agent-settings.yml` | wizard (`agent-config setup`) | Same as above — the wizard is the source of truth for new project config. |
 | Run the perms gate (`lint_global_paths.py`) | `agent-config doctor` | Migration deletes project-local state; the perms audit is a separate diagnostic on the global tree. |
 | `.legacy-pre-global-only/<stamp>/` snapshot | (removed) | Snapshot-and-rollback was a `migrate-to-global` semantic. The deletion path needs no snapshot — git history is the rollback surface. |
-| `agents/.event4u-bridge.yml` bridge marker write | `install.py` | Bridge marker is an install-time artefact, not a migration concern. |
+| `agents/.event4u-bridge.yml` legacy marker removal | `install.py` | Marker is retired (ADR-020 amendment 2026-07-13); install now deletes any legacy leftover instead of writing it. Global root resolves from `~/.event4u/agent-config`. |
 | `settings:migrate` (read-only copy of project YAML into global) | (removed; superseded by wizard) | The read-only copy was a stepping stone for the destructive move. With the deletion policy, neither step survives. |
 
 ## Exit codes

package/docs/contracts/prelaunch-diagnostics.md

@@ -0,0 +1,151 @@
+# Pre-Launch Diagnostics — finding IDs, epistemics, regression gate
+
+> Contract for the consumer-facing launch diagnostic
+> (road-to-ecosystem-harvest-prelaunch-diagnostics, Source L — a
+> production-readiness diagnostic skill; provenance in the harvest index).
+> The consumer-side sibling of the suite's own claims-ledger: a "ready"
+> verdict cannot be reached by assertion.
+>
+> Schema: [`prelaunch-report.schema.json`](../../src/scripts/schemas/prelaunch-report.schema.json) ·
+> Area vocabulary: [`prelaunch-areas.yml`](../../src/config/prelaunch-areas.yml) ·
+> Tooling: [`prelaunch_diagnostics.ts`](../../src/scripts/prelaunch_diagnostics.ts) ·
+> Skill surface: [`launch-readiness`](../../src/skills/launch-readiness/SKILL.md).
+
+## 1 — Finding-ID grammar (immutable, diff-stable)
+
+```
+AC-<AREA>-NNN        e.g. AC-AUTH-003, AC-RBK-001
+```
+
+- `<AREA>` — the uppercase code of a coverage area from
+  [`prelaunch-areas.yml`](../../src/config/prelaunch-areas.yml). The vocabulary
+  is **append-only**: codes are never renamed or re-used.
+- `NNN` — zero-padded, monotonically assigned per area, **never re-assigned**.
+  A finding that is retitled, re-scoped, or resolved keeps its ID forever; a
+  genuinely new problem gets the next number. Resolved findings stay in the
+  report with a flipped `status` — the entry never disappears, so baselines
+  diff cleanly across months.
+- The **ID is the diff key**. Titles, evidence, and severity are mutable
+  metadata; two runs are compared by ID set + per-ID state, never by prose.
+
+## 2 — Epistemics (Pass needs evidence; Unknown ≠ Pass)
+
+Every coverage area carries exactly one state:
+
+| State | Meaning | Requirement |
+|---|---|---|
+| `pass` | Diagnosed clean | **Cited evidence required** — file:line, command output, run URL. A pass without evidence fails validation: that is assertion, not diagnosis. |
+| `finding` | At least one open finding | The finding IDs live in `findings[]`. |
+| `unknown` | Not diagnosed | The honest default. **Absence of findings is `unknown`, never an automatic `pass`.** An area missing from the report entirely is `unknown` by definition. |
+| `not-applicable` | Does not exist on this surface | **Reason required** ("no DB → no migrations"). |
+
+Verdict rule (the launch gate):
+
+```
+ANY OPEN P0 FINDING → NOT READY, REGARDLESS OF EVERY OTHER AREA.
+ANY OPEN P1, OR A launch_gate AREA NOT AT pass/not-applicable → NOT READY.
+READY IS THE RESIDUAL STATE, NEVER THE DEFAULT.
+```
+
+`launch_gate: true` areas (auth, migrations, secrets, rollback) block the
+verdict while `unknown`; non-gate areas (observability, agent-governance)
+surface as unknowns + questions but do not block alone.
+
+## 3 — Coverage backbone
+
+The area vocabulary is deliberately pruned to the stacks this suite targets:
+**auth · migrations · secrets · observability · rollback · agent-governance**.
+It is not a generic compliance matrix — new areas enter by appending to
+`prelaunch-areas.yml` with a maintainer-reviewed `launch_gate` decision.
+
+Every report may carry a `questions` list — **questions that would change the
+diagnosis** ("is the admin panel exposed on the same origin?"). Questions are
+the actionable rendering of unknowns; the next run should convert them into
+evidence or findings.
+
+## 4 — Regression gate (findings diff)
+
+`prelaunch_diagnostics.ts diff <baseline.json> <current.json>` compares two
+reports **by ID**:
+
+- **new** — ID in current, not in baseline.
+- **resolved** — open in baseline, `fixed` in current.
+- **regressed** — a `launch_gate` area that was `pass` in the baseline and is
+  `finding`/`unknown` in current (Pass→Finding flip).
+- **retitled findings do not appear in the diff** — the ID survives the
+  rename (acceptance-tested).
+
+`--ci` mode exits non-zero when the diff contains a **new open P0/P1** or a
+**Pass→Finding flip in a launch-gate area** — the consumer-side sibling of the
+suite's claims-ledger CI. Everything else (new P2/P3, resolved findings,
+question churn) reports informationally and exits 0.
+
+## 5 — Suppression (evidence-backed, never silent)
+
+A consumer may suppress a finding via the project-local suppression file
+`agents/settings/prelaunch-suppressions.yml`:
+
+```yaml
+schema_version: prelaunch-suppressions-v1
+suppressions:
+  - id: AC-OBS-002
+    reason: "Dashboards land with the Q3 observability epic; alerting for the launch path exists."
+    evidence: "agents/evidence/prelaunch/obs-alerting.png"
+```
+
+- A finding with `status: suppressed-with-evidence` MUST have a matching
+  suppression entry carrying **both** `reason` and `evidence` — validation
+  fails otherwise.
+- Suppressed findings are excluded from the `--ci` triggers but **render in a
+  collapsible "suppressed" section** of the report output — the same
+  transparency contract as the review cluster's dropped-false-positives list.
+  Suppression hides nothing; it moves the item behind a fold with its receipt.
+- Suppressing a P0 does not restore a ready verdict — P0 caps the verdict
+  regardless (§ 2).
+
+## 6 — Consumer recipe (opt-in CI gating)
+
+1. Run the diagnostic (via `launch-readiness` § epistemics) and save the
+   report to `agents/evidence/prelaunch/baseline.json`. Commit it.
+2. Before a launch, produce a fresh `current.json` and run
+   `prelaunch_diagnostics.ts diff baseline.json current.json --ci` in the
+   pipeline — red on a new P0/P1 or a launch-gate Pass→Finding flip.
+3. After the launch settles, promote `current.json` to the new committed
+   baseline (a reviewed diff, like any lockfile bump).
+
+## 7 — Fix-loop discipline (Phase 3)
+
+- Rank open findings by severity, then by launch-gate membership.
+- Propose the **safest first approval batch** — explicitly the first *safe*
+  batch (reversible, small blast radius), not the full backlog. Approval is
+  the user's; the diagnostic never self-authorizes fixes
+  ([`autonomous-execution`](../../src/rules/autonomous-execution.md) and the
+  reversibility floor govern, unrestated).
+- Per-finding status vocabulary (schema-enforced): `open · fixed ·
+  accepted-risk · deferred-with-reason · suppressed-with-evidence ·
+  not-applicable` — everything except open/fixed carries a `reason`.
+- **Rescore whenever evidence changes** — a fix, a new probe, or an answered
+  question re-runs the affected area, never the memory of it.
+
+## 8 — Read-only guarantee
+
+The diagnostic **never mutates a consumer project**: the tooling reads
+reports and writes nothing outside its own output. Fixes flow through the
+normal approval-gated engines, not through this contract.
+
+## 9 — Score: council-locked (do not add)
+
+The pass-1 council **dropped the 0–100 readiness score** (gameable false
+precision). A severity-capped, never-published internal-ordering variant is
+**surfaced for council re-evaluation in the roadmap's revisit note — not
+adopted**. Until that revisit resolves: no numeric score field in the schema,
+no score in any rendered output, no score in CI messages. The ID scheme,
+epistemics, diff gate, and suppression above stand on their own.
+
+## See also
+
+- [`launch-readiness`](../../src/skills/launch-readiness/SKILL.md) — the skill
+  surface that produces the report.
+- [`docs/proof.md`](../proof.md) — the suite-side claims-ledger this mirrors.
+- `road-to-ecosystem-harvest-reliability-measurement` (archived) — measures the
+  *suite itself*; this contract measures the *consumer's launch surface*.

package/docs/contracts/release-pr-gating.md

@@ -81,6 +81,7 @@ the feature-PR floor by adding:
 | `release-validation.yml` (Phase B) | `changelog-entry` | CHANGELOG carries an entry matching the head-branch version |
 | `release-validation.yml` (Phase B) | `version-consistency` | `package.json` / `marketplace.json` / pack manifests agree on the version |
 | `consumer-matrix.yml` | `consumer-matrix` · `publish-dry-run` · `mcp-worker-dry-run` · `plugin-bootstrap` | pack-based consumer E2E + pre-tag dry-runs of the release-adjacent workflows — see the exemption note below |
+| (maintainer-local) | `task smoke-host-loadability REQUIRE=1` | real-host loadability — `claude plugin validate` + temp-home plugin install + metadata cross-consistency (marketplace ↔ plugin dirs ↔ docs). Optional in CI (runners lack the claude CLI, the step self-skips); **required before a release is cut** — `REQUIRE=1` turns a missing CLI into a failure |
 
 ## Consumer-matrix exemption — the tarball window
 

package/docs/customization.md

@@ -332,6 +332,28 @@ Per-invocation overrides (no settings change required):
 existing carve-out — `verbosity.offer_council_in_delivery` does not
 re-enable it. Use `/council diff:<base>..<head>` separately.
 
+#### PR description content — tier + enrichments
+
+The `commands.create_pr.*` block controls how much the generated PR
+**description body** carries. Defaults are tuned for token frugality: the
+description defaults to `min`, and the two enrichments are additive and
+self-limiting (grounded / capability-gated), so `min` stays genuinely
+minimal without ever dropping a critical callout.
+
+| Setting | Values | Default | Description |
+|---|---|---|---|
+| `commands.create_pr.detail_level` | `min`, `med`, `max` | `min` | Verbosity tier of the Description section. `min` = title + 2-3 sentence what/why/impact + linked ticket; `med` = `min` + grouped changes + tests note; `max` = `med` + how-to-test + edge cases + reviewer guidance. Critical info (breaking changes, migrations, security, rollback) is included at **every** tier — the tier governs explanatory depth, never whether a critical callout appears. |
+| `commands.create_pr.api_examples` | `true`, `false` | `true` | Add a fenced JSON request/response example for API-endpoint changes. `true` = include **only** when grounded in a real source (DTO/resource, OpenAPI, test fixture, or an actual probe); otherwise a one-line pointer, never an invented example. `false` = never. |
+| `commands.create_pr.screenshots` | `true`, `false` | `false` | Capture frontend screenshots for UI changes. `false` = never. `true` = attempt when the host has browser/preview tooling and the diff touches a frontend surface; capability-gated (emits a one-line note and leaves the placeholder when tooling is absent, never fails or blocks the PR). Before/after + region-highlighting is best-effort; byte-embedding into the PR body is not possible via the GitHub API (host image-upload or manual attach). |
+| `commands.create_pr.ui_paths` | glob list | `[]` | Optional globs that make frontend detection explicit (e.g. `["resources/views/**", "src/pages/**"]`). Empty = a light path/extension heuristic that fails open. |
+| `commands.create_pr.api_paths` | glob list | `[]` | Optional globs that make API-endpoint detection explicit (e.g. `["app/Http/Controllers/Api/**", "src/pages/api/**"]`). Empty = a light heuristic that fails open. |
+
+These flags are read once at the top of the `/create-pr` run and cached; the
+content flags feed `/create-pr:description-only` generation. `min` is the
+default precisely because a shorter description costs fewer output tokens on
+every PR — turn it up per-project (or per-invocation via the settings file)
+when reviewers want the richer context.
+
 #### Script-output level — env-var overrides
 
 `verbosity.script_output` is read by `scripts/_lib/script_output.py`.
@@ -395,7 +417,6 @@ Consumer projects can maintain their own agent documentation:
 ```
 agents/
 ├── overrides/               ← Skill/rule/command overrides (required after migrate)
-├── .event4u-bridge.yml      ← Global-only bridge marker (ADR-020)
 ├── knowledge/               ← Optional: curated project-specific knowledge pages
 ├── memory/                  ← Optional: memory promotion pipeline
 ├── roadmaps/                ← Optional: project-local roadmaps

package/docs/decisions/ADR-020-global-only-consumer-scope.md

@@ -126,6 +126,40 @@ This amendment narrows ADR-020's wording; the global-only **consumer install**
 decision (distributed content writes only to `~/.event4u/agent-config/`) is
 unchanged.
 
+## Amendment — 2026-07-13 · bridge marker retired
+
+The 2026-05-30 amendment restated `agents/.event4u-bridge.yml` as a mandated
+consumer metadata artefact. Field use showed the marker was a design mistake:
+it was **committed** to the shared project tree yet carried **no
+project-specific data**. `global_root` is always the well-known
+`~/.event4u/agent-config` (one global install per machine), and no code ever
+read the field — the loader, doctor, and conformance checks resolve the global
+root independently via `user_global_paths.event4u_root()`. Its only volatile
+content (`installed_at`, `installer_version`) meant every developer's install
+produced a diff and overwrote every other developer's committed copy. Scope
+(global) did not match location (per-project, committed).
+
+AI-council-converged (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-07-13,
+2-round debate): **Option B — eliminate the project marker; resolve the global
+root from the well-known path.** Changes:
+
+- The installer and `agent-config refresh --project` no longer write
+  `agents/.event4u-bridge.yml`; they **delete** any legacy committed copy. The
+  managed `.gitignore` block ignores it so a stale copy is never re-committed.
+- The global root is resolved from `~/.event4u/agent-config`
+  (`EVENT4U_CONFIG_HOME`-overridable), failing closed when absent.
+- Migration idempotency moved from the marker's presence to
+  `agents/.agent-state/install-mode.txt` (written on every install);
+  project-anchor detection keys on `agents/overrides/`.
+- The Windsurf / Cline / Gemini-CLI per-tool anchors stay (those tools cannot
+  read user scope) but now resolve the well-known path directly (no `bridge:`
+  back-pointer) and are **gitignored** — regenerated per-install, never shared.
+
+The single project-local agent surface is now **`agents/overrides/`** alone.
+This narrows the 2026-05-30 amendment; the global-only **consumer install**
+decision is unchanged. See [`consumer-bridge`](../contracts/consumer-bridge.md)
+(retired) for the reader/writer detail.
+
 ## Alternatives considered
 
 - **Status quo (project default + global opt-in).** Keeps the drift