@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/frontier-reasoning-operating-profile.md

@@ -0,0 +1,169 @@
+# Frontier-Grade Reasoning — Operating Profile
+
+> Source dossier for the **Reasoning Discipline Protocol (RDP)** — the durable,
+> sourced rationale behind the RDP gate context, rule, and skills. It documents what a
+> frontier reasoning model (Anthropic's Fable 5 / Mythos 5, June 2026) does that
+> weaker models skip — the **transferable operating discipline** — and the
+> boundary of what is *not* transferable.
+>
+> **User entry point:** for the one-screen "what it does / when it fires / how to
+> turn it off" contract, see
+> [`docs/contracts/reasoning-discipline-protocol.md`](../../contracts/reasoning-discipline-protocol.md).
+> This dossier holds the depth; that contract is where users start.
+>
+> Citation discipline: every catalog row names its source **and its dignity**
+> (Anthropic primary doc · third-party review · customer testimonial · our own
+> derivation). Two independent external model analyses (Claude + GPT) corroborate
+> but are never the primary evidence for a transferable-behavior line. A
+> line-by-line audit (2026-06-13) corrected five rows; the load-bearing claims
+> (over-prescription degrades, reasoning-in-response → refusal) are verbatim in
+> Anthropic's prompting doc and stand.
+
+## The one boundary that frames everything
+
+```
+CAPABILITY DOES NOT TRANSFER. DISCIPLINE DOES.
+```
+
+A frontier model's edge lives in its **weights** — gains spread across the whole
+training stack, with no single copyable prompt (the explicit framing is Nathan
+Lambert / Interconnects [lam]; Anthropic's docs support only the weaker "needs
+less scaffolding" [pf]). No skill, rule, or workflow makes Sonnet/Opus/GPT
+*equal* Fable 5, and anyone promising that is selling the hallucinated analysis
+this suite refuses to produce.
+
+What *does* transfer is the **operating discipline**: the steps a frontier model
+takes on its own that weaker models skip unless forced. On under-specified and
+long-horizon tasks, that discipline gap is the largest part of the *visible*
+quality difference. RDP transplants the discipline; it never claims the
+capability.
+
+> **Background (dates, precise):** Anthropic's own banner dates the **access
+> suspension of Fable 5 / Mythos 5 to 2026-06-12** [an]; the related US
+> export-control directive / Reuters report is **2026-06-13** [re]. Either way
+> the model is currently inaccessible, so we cannot A/B against it — our own
+> falsifiable eval is the only ground truth, which makes the discipline-transplant
+> approach *more* relevant, not less.
+
+## Sources (with dignity)
+
+- **[an]** Anthropic — *Claude Fable 5 and Mythos 5* announcement. Primary, but
+  several quotes on the page are **customer testimonials** (labeled per-row), not
+  Anthropic capability statements.
+- **[pf]** Anthropic docs — *Prompting Claude Fable 5*. Primary; the transferable
+  prompting playbook. Load-bearing claims live here.
+- **[in]** Anthropic docs — *Introducing Fable 5 / Mythos 5*. Primary; adaptive
+  thinking + effort parameter + memory tool + refusals.
+- **[ve]** Vellum — benchmark breakdown. **Third-party**; benchmark numbers are
+  not verifiable in Anthropic prose and must be labeled third-party or pulled to
+  the system card.
+- **[cr]** CodeRabbit model review. **Third-party**; source of the
+  "explore-environment-first" observation (not Anthropic-documented).
+- **[lam]** Nathan Lambert / Interconnects. **Third-party analysis**; "whole
+  training stack, no copyable prompt".
+- **[re]** Reuters — export-control report (2026-06-13).
+- Two external model analyses (Claude + GPT), provenance untracked in
+  `agents/.harvest-local/` — **corroboration only**, never primary.
+
+## Transferable-behavior catalog
+
+Each row: behavior → **source + dignity** → transplant mechanism → carrier.
+
+| Behavior | Source (dignity) | Transplant | Carrier |
+|---|---|---|---|
+| Audit progress against real tool results | **[pf] ✓ primary** | every claim cites a tool result | shipped: `verify-before-complete` |
+| Act when you have enough; no overplanning; outcome-first | **[pf] ✓ primary** | shipped | `direct-answers`, `autonomous-execution` |
+| Pause only when genuinely needed | **[pf] ✓ primary** | shipped | `no-cheap-questions` |
+| No over-refactor / minimal diff (at higher effort) | **[pf] ✓ primary** | shipped | `minimal-safe-diff` |
+| Parallel async subagents, dispatched readily | **[pf] ✓ primary** | default async dispatch | extend `subagent-orchestration` |
+| Fresh-context verifier beats self-critique (for **long-running** tasks) | **[pf] ✓ primary** | verifier subagent on a **structural-complexity** gate (not blanket) | extend `adversarial-review` |
+| Persistent **cross-run** notes (file memory = 3× vs Opus 4.8 on Slay the Spire) | **[an] ✓ primary (direct)** | lessons across runs, one per file | extend memory / `memory-consolidation` |
+| Infer the underlying goal (standard host only) | **[an] testimonial (Lovable); direction note** | infer goal, give **one** recommendation — NO "2–3 framings"; standard host only (a strong-reasoning host self-infers) | extend `improve-before-implement` |
+| Multi-hypothesis / "killing incorrect beliefs" | **[an] testimonial (Sean Ward); "multi-hypothesis" is our framing** | hypotheses + killed-beliefs in the notes file | `notes-first-reasoning` |
+| Adaptive effort (depth scales with hardness) | **[in],[pf] = API knob, not a scaffold** | strong-reasoning host: set `effort: high`; standard host w/o the knob: scaffold the effort/stop discipline | extend `autonomous-execution` (standard-host-only) |
+| Explore the environment first, then build | **[cr] third-party (NOT Anthropic-documented)** | enumerate constraints/tools/info-gaps, close by query/test before designing | extend `think-before-action` |
+| Risk-first decomposition (hardest/load-bearing unknown first) | **OUR DERIVATION — general engineering discipline, NOT Fable-documented** ([pf]'s "top of difficulty range" means **task selection**, not intra-task order) | resolve load-bearing uncertainties before dependent work | new skill `complexity-first-planning` |
+
+Adopted from GPT review (frontier-implicit behaviors; our adoption, corroboration
+only — all cost-gateable notes components):
+
+| Behavior | Source | Transplant | Carrier |
+|---|---|---|---|
+| Prediction tracking (calibration) | GPT review | prediction + confidence + result + lesson in notes | `notes-first` component `prediction_tracking` |
+| Uncertainty budget | GPT review | per-dimension uncertainty score → feeds adaptive effort | `notes-first` component `uncertainty_budget` |
+| Decision ledger | GPT review | decision + alternatives + reason + revisit-if in notes; **escalates to `decision-record`/ADR** when cross-task or structural | `notes-first` component `decision_ledger` |
+
+The ordered chain the orchestrator enforces:
+`ground → intent → notes → gather → audit → verify`.
+
+## Deferred to the Phase-8 audit (likely already covered)
+
+Two transferable [pf] behaviors are **not** given new artifacts up front — the
+Phase-8 de-prescriptivize audit checks existing coverage first and adds only
+verified gaps (HIGH priority):
+
+- **Re-ground the final summary** — write the closing summary for a reader who
+  saw none of the working thread; outcome first; drop working shorthand. Likely
+  covered by `language-and-tone` + `direct-answers`.
+- **Report findings and stop** — when the user is thinking out loud, don't apply
+  a fix. Likely covered by `scope-control`.
+
+## What does NOT transfer (and must not be faked)
+
+- **Raw capability** — vision SOTA, document/chart reasoning, codebase-scale
+  migrations. Benchmark deltas (e.g. SWE-Bench Pro 80.3 vs 69.2) are **[ve]
+  third-party**, not verifiable in Anthropic prose — label third-party or pull to
+  the system card; note "SWE-Bench Pro" is not named in [an] (which cites
+  FrontierCode/Cognition + Hebbia-Finance). These are weights, not prompts.
+- **"Show your work" in the response.** [pf] warns that reasoning-in-response can
+  trigger a `reasoning_extraction` refusal, and that over-prescriptive skills
+  *degrade* strong models. **Both verbatim in [pf] — the gating foundation.** RDP
+  keeps reasoning in notes + verifier subagents, never in the response, and
+  tier-gates prescription.
+- **Pokémon FireRed vision-only harness** — **[an] only** ([pf] does not mention
+  it).
+
+## Cost / benefit by host reasoning strength (the gating lens)
+
+RDP is **not** free — scaffolding costs tokens and, on strong-reasoning hosts,
+*degrades* output. So it engages only where it pays, via **table-free** signals.
+Per **ADR-035** the suite maintains no runtime model→band table, and `model_tier`
+is the *skill's* needed band (lite/medium/high), **not** the host's. Host strength
+is therefore **agent self-assessed**, never looked up (roadmap L10/L17):
+
+| Host / task | Self-coordination | RDP engagement | Why |
+|---|---|---|---|
+| standard host | low | **full** scaffolding | biggest discipline gap → biggest lift |
+| strong-reasoning host | high | **light / off** (use native `effort: high`) | over-scaffolding degrades + wastes tokens |
+| trivial / short task (any host) | n/a | **off** | no discipline gap to close; pure overhead |
+| verifier subagent (any host) | — | **only** on the structural-complexity gate (≥2 of: branching, ≥3 constraints, stateful, irreversibility) + token floor ≥1k | a full extra inference pass — the most expensive primitive |
+
+**One** constraint-light scaffold ships — no heavy/light content variants, since
+two variants would be a hidden model→band table. A standard host **expands it on
+request**. Two gates, both default-on: automatic (task signal + agent
+self-assessment) + the user `reasoning:` settings toggle (global + per-component
++ hard off).
+
+## Notes template grounding
+
+The session-notes template is grounded in Anthropic's **documented cross-run
+lessons memory** [pf] (one lesson per file; corrections + confirmed approaches;
+why they mattered). The in-task sections (`## In-Task Hypothesis Log`,
+`## Predictions`, `## Decisions`, `## Uncertainty`) are a clearly-marked **local
+derivation** for within-task scope — useful, but not claimed as Anthropic-
+documented, and kept on the notes side of the `reasoning_extraction` line.
+
+## Naming
+
+Neutral, no brand/capability claim. Umbrella: **Reasoning Discipline Protocol
+(RDP)**. Artifacts: `reasoning-orchestrator`, `notes-first-reasoning`,
+`complexity-first-planning`, `environment-grounding`. "Fable" / "Mythos" never
+appear in an artifact identifier.
+
+[an]: https://www.anthropic.com/news/claude-fable-5-mythos-5
+[pf]: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5
+[in]: https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5
+[ve]: https://www.vellum.ai/blog/claude-fable-5-and-mythos-5-benchmarks-explained
+[re]: https://www.reuters.com/technology/us-blocks-foreign-access-anthropics-most-advanced-ai-models-axios-reports-2026-06-13/
+[cr]: https://www.coderabbit.ai/blog/fable-5-model-review
+[lam]: https://www.interconnects.ai/p/claude-fable-5-and-new-ai-safety

package/dist/agent-src/guidelines/agent-infra/gate-authoring.md

@@ -0,0 +1,177 @@
+# Gate Authoring — the single path for a new gate
+
+> Lifecycle, gaming-risk block, paired fixtures, ledger obligation, and finding format. Read this BEFORE writing a new `lint_*` / `check_*` / `audit_*` script.
+
+_Origin: `road-to-skill-ecosystem-gate-integrity` Phase 3. It exists because the estate re-learned the same lesson four times at four instances and never wrote the general rule down: a gate that scanned nothing exited green, a budget report printed a share for a dimension it never measured, release gates verified an empty corpus, shape gates ran over frozen corpora. Each was fixed where it was found. This is the authoring surface that stops the fifth._
+
+## The five obligations
+
+A new gate is not done until all five hold. They are ordered by how expensive
+they are to add later — the first two are nearly free at authoring time and
+nearly impossible to retrofit honestly.
+
+### 1. Account for the work — the ledger obligation
+
+Use `src/scripts/_lib/gate_ledger.ts`. Plan every target, then give each one
+exactly one terminal outcome: `complete`, `fail`, `skip(reason)`, or
+`outOfScope(reason)`. `finalize()` throws when a planned target reached none.
+
+```ts
+const ledger = new GateLedger('lint_example');
+ledger.plan(files.map(rel));
+for (const f of files) {
+    if (isGenerated(f)) { ledger.outOfScope(rel(f), 'generated_artifact'); continue; }
+    const finding = check(f);
+    if (finding) ledger.fail(rel(f), finding); else ledger.complete(rel(f));
+}
+ledger.report();   // prints `scanned=N planned=N skipped=N`, throws on unaccounted
+```
+
+Skip reasons come from the closed union in that module. An unlisted reason does
+not typecheck — deliberately, because "excluded dir" / "too big" / "binary?" in
+free prose is not aggregatable, and adding a genuinely new code should be a
+one-line diff a reviewer sees.
+
+A gate that genuinely has no per-target structure (a single scalar probe, a
+watch-list guard) carries `// ledger-exempt: <reason>` on its own line instead.
+`check_gate_completeness` ratchets the un-adopted count; it may only shrink.
+
+**This is not the scan-root guard.** Keep `assertScanned` /
+`assertWatchlistResolves` from `_lib/scan_scope.ts` as well. One covers the root,
+the other the items under it, and a gate wants both.
+
+### 2. Print the denominator on the green path
+
+Success output states what was inspected, not only that nothing was found.
+`ledger.report()` does this; if the gate also carries a floor in
+`src/config/gate-coverage.yml`, emit the machine-read `scanned: <N>` line via
+`reportScanned` or directly.
+
+Publish the number that was **judged**, not the number that was *enumerated*.
+`lint_framework_leakage` published 438 against 368 actually judged until the
+ledger made the honest number the cheap one to emit — a 19% over-report of its
+own coverage, invisible to every consumer of that line.
+
+### 3. Land advisory, promote on empty
+
+```
+A NEW GATE LANDS ADVISORY. ITS FINDINGS ARE CLASSIFIED ON THE REAL CORPUS.
+THE BASELINE SHRINKS TO EMPTY. ONLY THEN IS IT PROMOTED TO ERROR.
+```
+
+The failure this prevents is recorded: a shape gate wired straight to error over
+a frozen corpus produced 8 hits, all 8 unfixable, and could therefore only ever
+block. Running a new gate against the real corpus and classifying every hit
+BEFORE wiring it is the difference between a ratchet and a wall.
+
+Record the promotion condition in the gate's own header comment, in the form
+*"promote to error when `<baseline entry>` reaches 0"*, so the next reader knows
+whether advisory is a stage or a permanent hedge.
+
+Use `checkRatchet` from `_lib/gate_baseline.ts` with an entry in
+`src/config/gate-violation-baselines.json`; it returns a verdict rather than
+printing or exiting, so the gate stays in control of its own output.
+
+### 4. Name one degenerate pass — the gaming-risk block
+
+Every new gate or ratchet carries a `**Gaming risk**` paragraph in its header
+comment naming **at least one** concrete way the metric passes without the
+underlying property holding, plus the mitigation and — honestly — the residual.
+
+If one degenerate pass is nameable at authoring time, it will be found in
+practice. Worked examples from this very roadmap:
+
+| Gate | Degenerate pass | Mitigation | Residual |
+|---|---|---|---|
+| `check_gate_completeness` | sprinkle `// ledger-exempt:` markers with plausible boilerplate | minimum reason length; the marker lands in the diff | cannot judge whether a reason is *true* |
+| `check_suppression_hygiene` | a `falsifier` holding a command that always exits 0 | literal degenerate forms rejected; minimum length | cannot execute the command to prove it discriminates |
+| `_lib/gate_ledger` | mark every target `outOfScope` to reach a clean tally | the report prints skip counts per code beside the scanned count | a reviewer must still read the ratio |
+
+The residual column is the point. A gaming-risk block that claims full coverage
+is itself a false green.
+
+### 5. Ship a paired fixture
+
+A gate with no negative fixture cannot be shown to discriminate. Minimum set:
+
+- the **real repo tree** passes, and the denominator is asserted (not just the
+  exit code — a gate that scanned nothing also exits 0);
+- a **planted violation** fails, and the message names the offender;
+- the **boundary** case, where the gate declares one (exactly-at-cap, exactly-
+  at-minimum);
+- a **dead scan root** fails rather than passing green;
+- `--quiet` changes the output, not the verdict.
+
+Where the gate has a self-test mode (§ Second-order guards below), the
+assertion-count floor is itself asserted: a truncated fixture block must fail
+rather than print success.
+
+## Finding format — the suppression key is in the message
+
+A finding message carries its own suppression key inline, copy-pasteable:
+
+```
+❌  src/skills/example/SKILL.md:42  framework-leakage  /artisan/  …
+    suppress: {"file":"src/skills/example/SKILL.md","anchor":"php artisan migrate","reason":"<why>","falsifier":"<command>"}
+```
+
+Friction in the suppression path is what drives a maintainer to disable the gate
+instead of narrowing it. Make the honest narrow easier than the blunt off-switch.
+
+Prefer a **content anchor** over a line number in any new suppression entry.
+Position-keyed entries re-fire on an insertion nobody made, and this repository
+has already paid for that: 18 of 18 framework-leakage entries are line-keyed,
+and `check_suppression_hygiene` prints that count every run until they migrate.
+
+## Derived pages — render only what was measured
+
+```
+A CATEGORY WITH NO MEASUREMENT RENDERS AS ABSENT OR EXPLICITLY "NOT MEASURED".
+NEVER AS A ZERO. NEVER AS A COMPUTED SHARE.
+```
+
+Any generator that writes a derived page uses `_lib/measured_render.ts`:
+`renderShare` returns `not measured` for an empty denominator instead of
+`0.0%`, and `renderCoverage` prints the **gap list** beside the coverage number.
+
+The recorded failure: the always-budget report printed a share for a dimension
+it counted zero artefacts in. `0 / 0` became `0.0%`, which reads as a
+measurement that came back low — the most confident possible way to say nothing.
+
+Two rules follow from it:
+
+- **A coverage number is published with its gaps.** Naming the un-covered
+  artefacts costs one line and removes the reader's assumption that the
+  remainder is small. When the list is capped for length, the true remainder is
+  still stated — a silently truncated gap list reads as "covered everything"
+  exactly like the bare number it was meant to qualify.
+- **The paired test asserts the NEGATIVE.** Given an unmeasured dimension, the
+  rendered output must contain no `%` at all. Asserting only that it says "not
+  measured" still passes a renderer that helpfully appends `(0.0%)` beside it.
+
+Adoption is a ratchet, not a sweep: `check_gate_completeness` is the worked
+example, and a generator that neither imports the helper nor carries the
+negative assertion is the gap this section exists to close as generators are
+touched.
+
+## Registering the gate
+
+1. Task stanza in `taskfiles/ci-fast.yml`, `cmd: ./scripts-run src/scripts/<id> {{.QUIET_FLAG}}`.
+2. `- task: <name>` in the `ci:` list in `Taskfile.yml`.
+3. `src/config/gate-coverage.yml` entry **if** the gate emits `scanned: <N>` — a
+   test fails the build on an emitting-but-unregistered gate.
+4. Verify under **both** argv forms — bare and the CI-injected `--quiet`. A
+   wrongly-consumed flag has silently become a scan root in this repo before.
+
+Set the coverage floor **below** the live count. A floor pinned at today's exact
+number reds on the very change that legitimately retires one unit, while a floor
+well above zero still catches the collapse that matters.
+
+## See also
+
+- [`false-green.md`](false-green.md) — the catalogue of ways a green result can be false, each with its detection command.
+- `src/scripts/_lib/gate_ledger.ts` — completeness accounting.
+- `src/scripts/_lib/scan_scope.ts` — scan-root and watch-list assertions.
+- `src/scripts/_lib/ratchet_base_ref.ts` — shrink-only against the base ref.
+- `src/scripts/_lib/gate_baseline.ts` — the count ratchet and its staleness expiry.
+- `docs/contracts/ci-green-floor.md` — what CI guarantees, and the local↔remote delta.

package/dist/agent-src/guidelines/agent-infra/guarded-baseline.md

@@ -0,0 +1,39 @@
+# `guarded-baseline` — a sub-state of `[ ]`, never a fifth glyph
+
+> Migrated out of [`roadmap-progress-mechanics`](roadmap-progress-mechanics.md)
+> on 2026-08-31, on arrival: that file measured 15,873 of the 16,000-char
+> depth ceiling, leaving 127 characters, so the section could not live there.
+> The ceiling is a growth ratchet, and hitting it is the signal to split rather
+> than to raise it. The glyph-semantics table there points here.
+
+A step whose `verify:` asserts a property of a mechanism that **does not yet exist** may not close `[x]`: an executable guard proven to go RED under a named sabotage is evidence about the *guard*, not about the *absent mechanism*, and `[x]` would claim the acceptance criterion was satisfied. Such a step keeps its `[ ]` box and carries an annotation plus a structured evidence record (AI council 2026-08-31, 2/2 convergent — `anthropic/claude-sonnet-4-5` + `openai/codex-default`, option C):
+
+~~~md
+- [ ] <!-- roadmap-status: guarded-baseline -->
+      **12.1** …step text…
+      ```yaml
+      guarded_baseline:
+        category: future-mechanism   # or absence-assertion — no other value
+        scope: <surfaces examined>
+        command: <reproducible green command>
+        red_proof: <commit, fixture, or recorded sabotage run>
+        sabotage_model: <exact violation introduced>
+        recheck_when: <mechanism / symbol / path trigger>
+        discharged_ac: <clauses actually completed>
+        pending_ac: <clauses still unexercisable>
+      ```
+~~~
+
+The two categories are the discriminator, not decoration. An **`absence-assertion`** step asserts something directly observable today ("the schema has no field capable of holding prompt text") and MAY close `[x]` once sabotage-verified. A **`future-mechanism`** step asserts a property of something that does not exist ("a probe-resolvable fixture never enters the selector") and is what this sub-state exists for. No third value is accepted, and an absent `category` is a rejection rather than a default.
+
+Tooling, all of it in `guarded_baseline.ts` and enforced by both consumers:
+
+| Behavior | Where |
+|---|---|
+| Counted as **open**, never as done — the canonical box stays `[ ]` | `count_checkboxes` |
+| Reported **separately**: a `## 🛡️ Guarded baselines` dashboard section plus a per-step stderr line | `update_roadmap_progress` |
+| **Rejected** — exit 1, on both `--check` and a plain regen — when `red_proof` is absent, when `category` is absent or illegal, when there is no evidence block, or when the annotation sits on anything but `- [ ]` | `update_roadmap_progress` |
+| Treated as **incomplete**: archival refused and the reason named | `archive_completed_roadmaps` |
+| Marked **stale** once a path-shaped `recheck_when` trigger resolves in the tree. A trigger carrying **no** path token at all is reported as not machine-checkable rather than as not-stale; a trigger carrying at least one path token is decided by that path and is **not** reported, even when a companion symbol token sits beside it — a checked trigger that looks unchecked is the mirror of the failure the report exists to prevent (measured 2026-09-01: 3 of 4 reported lines were already decidable) | `guardedBaselineStaleness` |
+
+Only verification against the real mechanism permits `[x]`. **A baseline that has not demonstrably gone RED is an ordinary open item** and must not carry the annotation at all — the sabotage-and-restore proof is the entry price, not a nice-to-have.

package/dist/agent-src/guidelines/agent-infra/installed-tools-manifest.md

@@ -0,0 +1,142 @@
+# Installed-Tools Manifest
+
+Project-committed bill of materials for AI tooling. Answers the
+question "which AIs does this project use, where do their bridges live,
+and is everyone on the team on the same set?". Canonical schema is
+ADR-008 ([`docs/decisions/ADR-008-installed-tools-manifest.md`](../../decisions/ADR-008-installed-tools-manifest.md)).
+Delivered under the global-first-install roadmap (Phase 3) — see
+`agents/roadmaps/` for current status.
+
+This file lives at **`agents/installed-tools.lock`** — committed,
+machine-managed, and orthogonal to `.agent-project-settings.yml`
+(which owns *behaviour*, not *bill of materials*).
+
+## Schema (v1)
+
+```yaml
+schema_version: 1
+agent_config_version: "2.x.y"          # last package version that wrote the file
+tools:
+  - name: claude-code                  # must match _VALID_TOOLS in scripts/install.ts
+    scope: global                      # one of: global, project
+    bridge_marker: ~/.claude/          # validate checks this path exists
+    installed_at: "2026-05-12"
+  - name: roocode
+    scope: project                     # workspace-wins → must live in repo
+    bridge_marker: .roo/rules/agent-config.md
+    installed_at: "2026-05-12"
+```
+
+| Field | Owner | Notes |
+|---|---|---|
+| `schema_version` | machine | bumps on breaking schema changes |
+| `agent_config_version` | machine | last writer's package version; `validate` flags drift |
+| `tools[]` | machine | append-on-init order preserved (not alphabetised) |
+| `tools[].name` | machine | one of the 17 valid IDs in `scripts/install.ts` |
+| `tools[].scope` | machine | `global` (user-home) or `project` (workspace bridge) |
+| `tools[].bridge_marker` | machine | absolute / `~`-prefixed for global, repo-relative for project |
+| `tools[].installed_at` | machine | ISO date; informational only |
+
+The file is **machine-managed**. Hand-editing is discouraged — every
+mutation goes through `init`, `sync`, or `init --force`.
+
+## Workflow
+
+### Team onboarding (clone → sync → done)
+
+```bash
+git clone <repo>
+cd <repo>
+npx @event4u/agent-config sync
+```
+
+`sync` reads `agents/installed-tools.lock`, checks every listed tool's
+bridge marker, and replays `install.ts --tools=<id>` for each missing
+one. Tools whose marker is already present are skipped — `sync` is
+idempotent and safe to re-run.
+
+### Adding a tool
+
+```bash
+npx @event4u/agent-config init --tools=<id>
+# or --tools=<id1>,<id2>
+```
+
+`init` writes an entry per tool. Existing entry with the same
+`(name, scope)` → no-op. Entry with **different scope** → loud warning
+and refusal until you pass `--force` (see scope migration below).
+
+### Drift detection (CI gate)
+
+```bash
+npx @event4u/agent-config validate
+```
+
+Read-only. Exit code 1 if any drift is found. Surfaces three drift
+kinds; no auto-fix.
+
+| Kind | Trigger | Fix |
+|---|---|---|
+| `marker_missing` | recorded `bridge_marker` does not exist | `agent-config sync` |
+| `scope_divergence` | marker only exists at the *other* scope | `agent-config init --tools=<id> --force` |
+| `version_drift` | manifest's `agent_config_version` ≠ installed package | `agent-config update` then `agent-config init --force` |
+
+`--skip-version-check` suppresses the third kind for repositories that
+intentionally pin an older version of the manifest.
+
+## Scope migration
+
+Under [ADR-020](../../decisions/ADR-020-global-only-consumer-scope.md)
+global is the only consumer scope. Consumers carrying a pre-2.5
+project-scope payload move to global with the one-shot
+`npx @event4u/agent-config migrate` subcommand — it removes the
+legacy project artefacts in one opinionated pass (deletion-over-
+migration policy); the wizard recreates fresh global config on the
+next `agent-config setup`. See
+[docs/contracts/migrate-command.md](../../contracts/migrate-command.md)
+for the full action matrix.
+
+For maintainers running `AGENT_CONFIG_DEV_MODE=1`, project-scope
+re-installs remain available; the installer still detects scope
+conflicts and refuses to rewrite without `--force`. `validate`
+afterwards confirms the new state.
+
+Reasoning: scope is a project-wide decision; flipping it silently
+would surprise other team members who never asked for the change. The
+loud refusal forces an explicit `--force` so the diff is reviewable in
+the next commit.
+
+## Relationship to other files
+
+| File | What it answers | Layer |
+|---|---|---|
+| `agents/installed-tools.lock` | **which AIs?** (this guideline) | bill of materials |
+| `.agent-project-settings.yml` | **how do agents behave?** | layered-settings (team file) |
+| `~/.event4u/agent-config/installed.lock` | **which package version did I install globally?** | per-developer global lockfile (Phase 1; legacy `~/.config/agent-config/installed.lock` read as fallback) |
+| `.agent-settings.yml` | **what are my personal preferences in this project?** | layered-settings (developer file) |
+
+Each file has one job. They never overlap. The two `.lock` files look
+similar by name but answer different questions: `installed.lock` is
+per-developer / cross-project (the package itself), while
+`installed-tools.lock` is per-project / team-shared (which tools are
+expected in *this* repo).
+
+## CI integration
+
+Recommended gate (GitHub Actions / GitLab CI):
+
+```yaml
+- name: Validate installed-tools manifest
+  run: npx @event4u/agent-config validate
+```
+
+Pair it with `agent-config sync` in your dev-setup script so new
+contributors get a working environment without reading the manifest by
+hand.
+
+## References
+
+- [`ADR-008`](../../decisions/ADR-008-installed-tools-manifest.md) — manifest decision and schema.
+- [`ADR-007`](../../decisions/ADR-007-agent-discovery-scopes.md) — global-first install (prerequisite).
+- [`docs/installation.md`](../../installation.md) — team-onboarding flow.
+- [`layered-settings.md`](layered-settings.md) — parallel settings hierarchy (orthogonal to this manifest).