@event4u/agent-config 3.0.0 → 3.1.1

package/docs/contracts/installer-agent-mode.md

@@ -0,0 +1,137 @@
+---
+stability: beta
+keep-beta-until: 2026-08-19
+---
+
+# Installer agent-mode protocol — JSON-over-stdio contract
+
+> Companion to [ADR-016](../decisions/ADR-016-installer-architecture.md)
+> § 4 and § 6. The ADR is the decision; this file is the worked-example
+> reference that agents (Claude, Cursor, GPT, …) and the installer
+> CLI share at runtime.
+
+## Source of truth
+
+The agent-mode state machine lives in
+[`packages/core/installer/src/agent-mode/machine.ts`](../../packages/core/installer/src/agent-mode/machine.ts).
+Envelope construction and `--answer` parsing live in
+[`protocol.ts`](../../packages/core/installer/src/agent-mode/protocol.ts).
+Both are unit-tested under
+[`packages/core/installer/tests/agent-mode-*.test.ts`](../../packages/core/installer/tests/).
+
+## Design constraints
+
+- **Stateless across invocations** — the installer keeps no
+  server-side session. Every turn carries the full conversation as
+  repeated `--answer key=value` flags. An agent may re-issue from
+  scratch at any time.
+- **Strict question-id sequencing** — answers must arrive in the
+  order the installer asks them (`q1.workspaces`, then `q2.packs`,
+  then optional `q3.confirm`). Out-of-order or unknown ids return
+  an `error` envelope, exit code 2.
+- **Single-line JSON per turn** — stdout emits exactly one
+  newline-terminated JSON object per invocation; stderr is reserved
+  for diagnostics and is not part of the contract.
+- **`protocol_version: 1`** — every envelope carries it; agents
+  refusing the version negotiate by aborting.
+
+## Envelope shapes
+
+### `question`
+
+The installer is waiting for the next answer.
+
+```json
+{
+  "status": "question",
+  "protocol_version": 1,
+  "id": "q1.workspaces",
+  "prompt": "Which workspaces does this project need? (multi, comma-separated)",
+  "choices": [
+    { "value": "engineering", "label": "Engineering" },
+    { "value": "product", "label": "Product" }
+  ],
+  "multi": true,
+  "next_call": "init --agent --answer q1.workspaces=<value>"
+}
+```
+
+- `id` — the canonical question identifier; the agent echoes it as
+  `--answer <id>=<value>`.
+- `multi: true` — comma-separated values allowed; `multi: false` —
+  exactly one value.
+- `next_call` — the literal command the agent should issue next,
+  with `<value>` (and prior answers) substituted in.
+
+### `done`
+
+Terminal success; no further calls needed.
+
+```json
+{
+  "status": "done",
+  "protocol_version": 1,
+  "summary": { "files_written": 83, "lockfile_sha256": "c45b3035…" }
+}
+```
+
+### `error`
+
+Terminal failure; exit code 2.
+
+```json
+{
+  "status": "error",
+  "protocol_version": 1,
+  "reason": "out_of_order",
+  "expected_question_id": "q1.workspaces",
+  "received": "q2.packs"
+}
+```
+
+Defined `reason` values: `answer_malformed`, `out_of_order`,
+`unknown_workspace`, `unknown_pack`, `aborted_by_agent`.
+
+## Turn-by-turn worked example
+
+```bash
+# Turn 1 — discover workspaces
+$ installer init --agent
+{"status":"question","id":"q1.workspaces", … "next_call":"… --answer q1.workspaces=<value>"}
+
+# Turn 2 — answer workspaces, discover packs
+$ installer init --agent --answer q1.workspaces=engineering
+{"status":"question","id":"q2.packs", … "next_call":"… --answer q1.workspaces=engineering --answer q2.packs=<value>"}
+
+# Turn 3 — answer packs, install completes
+$ installer init --agent --answer q1.workspaces=engineering --answer q2.packs=engineering-base
+{"status":"done","summary":{"files_written":83,"lockfile_sha256":"c45b3035…"}}
+```
+
+When the pack selection pulls in extras via `requires_hint`, the
+installer inserts a `q3.confirm` turn before completing:
+
+```bash
+$ installer init --agent --answer q1.workspaces=engineering --answer q2.packs=symfony
+{"status":"question","id":"q3.confirm", "prompt":"Auto-added packs: php. Continue?", "choices":[{"value":"yes","label":"yes"},{"value":"no","label":"no"}], "multi":false, … }
+```
+
+`q3.confirm=no` returns `reason: "aborted_by_agent"`.
+
+## Flags relevant to agent mode
+
+- `--manifest <path>` — override the manifest location (defaults to
+  walking up for `dist/discovery/discovery-manifest.json`).
+- `--project-root <path>` — destination project root.
+- `--dry-run` — resolve and emit the `done` envelope without
+  touching disk; used by agents that want a plan preview.
+
+## Failure modes guarded against
+
+- **Agent loops** — `protocol_version` mismatch on any side aborts
+  immediately; no implicit version negotiation.
+- **State drift between turns** — the installer never reads
+  workdir state to recover answers; every fact must be carried in
+  `--answer` flags.
+- **Silent partial install** — on any error after `q2.packs`,
+  exit code 2 with no disk writes (atomic via `StagingSession`).

package/docs/contracts/kernel-membership.md

@@ -231,7 +231,7 @@ that fires on every action decision. Swap proposal: `agent-authority`
 the 9-rule set through P2.2. Re-evaluation trigger fires at P3.2
 once the router schema and compiler ship; at that point
 `agent-authority`'s routing role becomes redundant (each kernel rule
-carries its own band as frontmatter, compiled into `router.json`),
+carries its own band as frontmatter, compiled into `dist/router.json`),
 clearing the way for the swap under a fresh ADR.
 
 ## § 6 — Abort criteria for P2.2

package/docs/contracts/mcp-tool-inventory.md

@@ -23,12 +23,12 @@ keep-beta-until: 2026-08-14
 
 | Tool | Side-effect | Transports | Catalog | Handler |
 |---|---|---|---|---|
-| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.py:510`](../../scripts/mcp_server/tools.py#L510) |
-| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.py:535`](../../scripts/mcp_server/tools.py#L535) |
-| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.py:571`](../../scripts/mcp_server/tools.py#L571) |
-| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.py:590`](../../scripts/mcp_server/tools.py#L590) |
+| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.py:521`](../../scripts/mcp_server/tools.py#L521) |
+| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.py:546`](../../scripts/mcp_server/tools.py#L546) |
+| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.py:586`](../../scripts/mcp_server/tools.py#L586) |
+| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.py:606`](../../scripts/mcp_server/tools.py#L606) |
 | `memory_signal` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:75`](../../scripts/mcp_server/consumer_tool_catalog.json#L75) | _stub-only_ |
-| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.py:617`](../../scripts/mcp_server/tools.py#L617) |
+| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.py:633`](../../scripts/mcp_server/tools.py#L633) |
 | `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:98`](../../scripts/mcp_server/consumer_tool_catalog.json#L98) | _stub-only_ |
 | `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:114`](../../scripts/mcp_server/consumer_tool_catalog.json#L114) | _stub-only_ |
 | `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:129`](../../scripts/mcp_server/consumer_tool_catalog.json#L129) | _stub-only_ |
@@ -38,11 +38,11 @@ keep-beta-until: 2026-08-14
 | `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:186`](../../scripts/mcp_server/consumer_tool_catalog.json#L186) | _stub-only_ |
 | `run_tests` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:200`](../../scripts/mcp_server/consumer_tool_catalog.json#L200) | _stub-only_ |
 | `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:214`](../../scripts/mcp_server/consumer_tool_catalog.json#L214) | _stub-only_ |
-| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.py:631`](../../scripts/mcp_server/tools.py#L631) |
-| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.py:644`](../../scripts/mcp_server/tools.py#L644) |
-| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.py:657`](../../scripts/mcp_server/tools.py#L657) |
+| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.py:647`](../../scripts/mcp_server/tools.py#L647) |
+| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.py:660`](../../scripts/mcp_server/tools.py#L660) |
+| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.py:673`](../../scripts/mcp_server/tools.py#L673) |
 | `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:248`](../../scripts/mcp_server/consumer_tool_catalog.json#L248) | _stub-only_ |
-| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.py:670`](../../scripts/mcp_server/tools.py#L670) |
+| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.py:686`](../../scripts/mcp_server/tools.py#L686) |
 
 ## Glossary
 

package/docs/contracts/namespace.md

@@ -5,8 +5,8 @@ stability: stable
 # Namespace contract — skills, rules, commands, personas
 
 > Every artefact name is a **stable identifier**: routed to from
-> `router.json`, cited from skills, surfaced in `/help`, embedded in
-> command paths, and back-referenced in test fixtures. Drift breaks
+> `dist/router.json`, cited from skills, surfaced in `/help`, embedded
+> in command paths, and back-referenced in test fixtures. Drift breaks
 > all five surfaces silently.
 >
 > **Source:** Step-11 Phase 5 Step 1
@@ -43,7 +43,7 @@ permitted when the stem already encodes both (`commit`, `eloquent`,
 | `claude-memories` | Reserved for the `~/.claude/CLAUDE.md` shape — host-agent state, not a package artefact. |
 | `default` | Ambiguous with profile / mode defaults; collides with `.agent-settings.yml` keys. |
 | `index` | Reserved for auto-generated INDEX.md files. |
-| `router` | Reserved for `router.json` and the router contract. |
+| `router` | Reserved for `dist/router.json` and the router contract. |
 
 Reserved names apply at the **top level** of each artefact type. A
 sub-verb under a namespaced group (e.g. `council/default.md` →
@@ -97,8 +97,8 @@ python3 scripts/lint_namespace.py
 ```
 
 If the candidate fails, the linter prints the rule it violated.
-**Renames after release are expensive** — touch router.json, every
-skill citing the old name, the bench corpus, and consumer settings.
+**Renames after release are expensive** — touch `dist/router.json`,
+every skill citing the old name, the bench corpus, and consumer settings.
 Pay the naming cost once, upfront.
 
 ## 6. Relationship to the frontmatter contract
@@ -111,7 +111,7 @@ the regex string.
 
 ## 7. Why this exists
 
-`router.json` resolves `<kind>:<id>` strings at session start. Any
+`dist/router.json` resolves `<kind>:<id>` strings at session start. Any
 artefact rename breaks every routing entry pointing at the old name
 without compile-time error. The linter catches the rename at the PR
 boundary, not at runtime in a consumer.

package/docs/contracts/provider-lifecycle.md

@@ -7,7 +7,7 @@ keep-beta-until: 2026-08-15
 
 > **Status:** active · **Stability:** beta · **Owner:** universal-platform-refinement Phase 3
 > · **Linter:** none (declarative contract; enforced agent-in-the-loop via [`provider-lifecycle-discipline`](../../.agent-src/rules/provider-lifecycle-discipline.md))
-> · **Source-of-truth template:** [`agents/.ai-video.xml.example`](../../agents/.ai-video.xml.example)
+> · **Source-of-truth template:** [`agents/templates/.ai-video.xml.example`](../../agents/templates/.ai-video.xml.example)
 
 Locks the lifecycle tagging used on every adapter under
 `scripts/ai-video/adapters/` (and future `scripts/ai-image/`,
@@ -42,7 +42,7 @@ the human noticing.
    surface (`submit / poll / fetch / dry-run` *or* `run / dry-run`)
    matches `scripts/ai-video/lib/adapter-contract.md` verbatim.
 
-A maintainer flipping the tier in `agents/.ai-video.xml.example`
+A maintainer flipping the tier in `agents/templates/.ai-video.xml.example`
 **and** the adapter header comment is the promotion event. There is
 no separate registry — the example file is the registry.
 
@@ -67,7 +67,7 @@ When the agent picks a provider for a `/video:*` / `/image:*` /
 
 1. **Read** the `provider_lifecycle` tag from the adapter's header
    comment **and** the matching `<provider id="…">` block in
-   `agents/.ai-video.xml.example` (or the operator's
+   `agents/templates/.ai-video.xml.example` (or the operator's
    `agents/.ai-video.xml`).
 2. **Refuse-and-surface** if the operator's resolved default is a
    non-`stable` tier — name the tier and the path to this contract
@@ -103,7 +103,7 @@ so the agent surfaces the tier and asks before proceeding — the
 human is the policy decision point.
 
 The `<default-image-provider>` and `<default-video-provider>`
-entries in `agents/.ai-video.xml.example` remain unchanged
+entries in `agents/templates/.ai-video.xml.example` remain unchanged
 (`openai-images` and `gemini-veo`). The tier tag does not change
 defaults; it changes whether the agent silently honours them.
 
@@ -118,5 +118,5 @@ snapshot — older snapshots live in git history, not in this file.
 
 - [`provider-lifecycle-discipline`](../../.agent-src/rules/provider-lifecycle-discipline.md) — the tier-2 routing rule that surfaces this contract when a provider is touched.
 - [`scripts/ai-video/lib/adapter-contract.md`](../../scripts/ai-video/lib/adapter-contract.md) — the four-method shell contract every adapter implements.
-- [`agents/.ai-video.xml.example`](../../agents/.ai-video.xml.example) — operator-facing provider configuration template (carries the tier tag inline).
+- [`agents/templates/.ai-video.xml.example`](../../agents/templates/.ai-video.xml.example) — operator-facing provider configuration template (carries the tier tag inline).
 - [`agents/settings/policies/media/README.md`](../../agents/settings/policies/media/README.md) — the agent-in-the-loop enforcement model this contract participates in.

package/docs/contracts/rule-router.md

@@ -83,8 +83,8 @@ whose body is fully covered by an existing architectural contract.
 ## Compiled output — `router.json`
 
 `scripts/compile_router.py` reads every rule frontmatter and emits
-`router.json` at the repo root, used by host agents at session start.
-Deterministic key order, sorted lists, stable across runs.
+`dist/router.json` (tracked in git), used by host agents at session
+start. Deterministic key order, sorted lists, stable across runs.
 
 ```json
 {
@@ -110,7 +110,7 @@ Generated alongside `marketplace.json` during `task generate-tools`.
 
 ## Activation semantics
 
-The host agent reads `router.json` once per session. Per turn:
+The host agent reads `dist/router.json` once per session. Per turn:
 
 1. Always evaluate kernel rules.
 2. If `profile = minimal` → stop after kernel.
@@ -151,4 +151,4 @@ start, the router lookup is keyword/phrase/path/intent matching only.
 - This file: schema specification.
 - `kernel-membership.md` § 4: kernel locked count + SHAs.
 - `rule-classification.md`: per-rule tier + disposition pre-Phase-4.
-- `router.json` (generated): runtime artifact, never hand-edited.
+- `dist/router.json` (generated): runtime artifact, never hand-edited.

package/docs/contracts/settings-api.md

@@ -48,8 +48,22 @@ Response (200):
 
 ### `GET /api/v1/settings`
 
-Reads `<projectRoot>/.agent-settings.yml` and returns the parsed values
-plus the freshness token for optimistic locking.
+Returns the **three-layer merged** settings tree plus the freshness
+token for optimistic locking. Merge order (per **ADR-020** + roadmap
+`road-to-global-only-install` § Phase 2.2):
+
+```text
+defaults (config/agent-settings.template.yml)
+  < global (~/.event4u/agent-config/settings/.agent-settings.yml)
+    < project (<projectRoot>/settings/.agent-settings.yml, optional)
+```
+
+Defaults come from the package template with `__COST_PROFILE__` /
+`__USER_TYPE__` placeholders substituted for their permissive defaults
+(`balanced` / `""`). Global and project layers are read with the typed
+subdir preferred over the legacy flat path. The route mirrors
+`scripts/install.py::read_layered_settings` 1:1 so the Python installer
+and the Fastify GUI cannot drift.
 
 Response (200):
 
@@ -57,13 +71,28 @@ Response (200):
 {
     "values":       { "cost_profile": "balanced", "...": "..." },
     "lastModified": 1747749791842,
-    "path":         ".agent-settings.yml"
+    "path":         "settings/.agent-settings.yml",
+    "legacyHints":  { "user_name": "Matze" }
 }
 ```
 
-Errors: **404** when the file is missing (the SPA should redirect to
-`/#/wizard/Welcome`); **500** with `code=YAML_PARSE` when YAML parsing
-fails (body includes the line/column).
+`legacyHints` is an out-of-band sidecar carrying values that have moved
+out of `settingsSchema` but still live in a pre-v2 file on disk. Keys
+are omitted when empty, never `null`. Current hints:
+
+| Key         | Source (legacy)        | New home                                |
+| ----------- | ---------------------- | --------------------------------------- |
+| `user_name` | `personal.user_name`   | `.agent-user.md` &rarr; `identity.name` |
+
+The wizard consumes hints on first run only — when `.agent-user.md`
+does not yet exist — to pre-fill the merged identity field. Subsequent
+PUTs strip the legacy keys (Zod-unknown), so the next read returns no
+hints.
+
+Errors: **404** when **neither** the global nor the project file
+exists (defaults alone are not an "installed" state — the SPA should
+redirect to `/#/wizard/Welcome`); **500** with `code=YAML_PARSE` when
+either layer is on disk but unparseable (body includes the line/column).
 
 ### `POST /api/v1/settings/diff`
 
@@ -139,6 +168,24 @@ Errors: **500** with `code=TXN_PARTIAL` when the marker survives a crash
 (client should redirect the user to a "your last save is being
 recovered" screen and refetch state).
 
+## CLI: `agent-config settings migrate`
+
+Companion to the layered reader (ADR-020). Lifts an existing
+project-local `.agent-user.yml` / `.agent-settings.yml` into
+`~/.event4u/agent-config/`. Idempotent — refuses to overwrite a
+non-empty global file without `--force`. Order matches Phase 5
+amendment A2 (`copy → verify`; the destructive `move` step is owned by
+`migrate-to-global`, not this subcommand).
+
+Flags:
+
+- `--from <path>` — project root to read from (default: `cwd`).
+- `--force` — overwrite a non-empty global file.
+- `--dry-run` — list intended copies; zero writes; exit 0.
+
+Exit codes: `0` on success or no-op; `1` on validation failure or a
+non-empty global file without `--force`.
+
 ## Status codes summary
 
 | Code | Meaning                                              |

package/docs/contracts/smoke-contracts.md

@@ -34,8 +34,8 @@ the paths touched in the PR:
 
 | Tier | Globs that trigger | Script |
 |---|---|---|
-| kernel | `.agent-src.uncompressed/rules/**`, `.agent-src/rules/**`, `router.json`, `scripts/measure_rule_budget.py` | `scripts/smoke/kernel.sh` |
-| router | `router.json`, `.agent-src.uncompressed/rules/**`, `.agent-src.uncompressed/skills/**`, `docs/contracts/**`, `docs/guidelines/**` | `scripts/smoke/router.sh` |
+| kernel | `.agent-src.uncompressed/rules/**`, `.agent-src/rules/**`, `dist/router.json`, `scripts/measure_rule_budget.py` | `scripts/smoke/kernel.sh` |
+| router | `dist/router.json`, `.agent-src.uncompressed/rules/**`, `.agent-src.uncompressed/skills/**`, `docs/contracts/**`, `docs/guidelines/**` | `scripts/smoke/router.sh` |
 | schema | `.agent-src.uncompressed/skills/**`, `.agent-src.uncompressed/rules/**`, `scripts/schemas/**`, `scripts/skill_linter.py`, `scripts/validate_frontmatter.py` | `scripts/smoke/schema.sh` |
 | skills | `.agent-src.uncompressed/skills/**` | `scripts/smoke/skills.sh` |
 
@@ -131,7 +131,7 @@ the final baseline line) for CI summary parsing.
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | `kernel.sh` reports > 9 missing fences | Kernel rule lost its Iron Law block during edit | Restore the fence; update `EXEMPT_FROM_FENCE` only for new dispatch indexes |
-| `router.sh` reports > 0 broken pointers | `router.json` references an id without a rule file | Add the rule or remove the route — never edit the smoke baseline up |
+| `router.sh` reports > 0 broken pointers | `dist/router.json` references an id without a rule file | Add the rule or remove the route — never edit the smoke baseline up |
 | `schema.sh` reports FAILs | A skill / rule lost a required field | Restore via [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json) |
 | `skills.sh` 5/5 random sample fails | Hand-edit broke frontmatter or renamed directory without updating `name:` | Restore filename ↔ slug coupling |
 

package/docs/contracts/trust-and-safety.md

@@ -0,0 +1,144 @@
+---
+stability: beta
+keep-beta-until: 2026-08-21
+---
+
+# Trust & Safety Layer — Phase 5 of the monorepo migration
+
+> **Status:** active · **Stability:** beta · **Owner:** monorepo-phase-5
+> · **Authoritative ADR:** [`ADR-018`](../decisions/ADR-018-trust-and-safety-layer.md)
+
+Phase 1 stamped every artefact with `trust.level`,
+`trust.confidence`, and `trust.human_review_required`. Phase 5
+**enforces** those fields: the installer surfaces them at selection
+time, the compressor injects banners into compiled output, the
+runtime gates `human_review_required: true` artefacts before final
+output, and a lint catches drift. This contract is what those four
+consumers depend on.
+
+## § 1 — Trust levels
+
+A closed enum on `trust.level`:
+
+| level         | meaning                                                              |
+|---------------|----------------------------------------------------------------------|
+| `core`        | Iron-Law / structural. Cannot be downgraded. Kernel rules sit here.  |
+| `professional`| Domain expertise the user opted into; no human-review floor.         |
+| `advisory`    | High-impact judgement. Installer **must** confirm; banner injected.  |
+| `restricted`  | Reserved for future legal / regulated content. Same surface as advisory, stricter copy. |
+| `experimental`| Pre-stable. May be removed without ADR.                              |
+
+`trust.confidence` is a parallel signal (`high` · `medium` · `low`)
+used by the manifest's summary; it does **not** gate behaviour.
+
+`trust.human_review_required: true` is the per-artefact banner gate.
+Independent of `trust.level` so a `professional` artefact can still
+demand review on its specific surface.
+
+## § 2 — HRR banner
+
+The compressor (`scripts/compress.py`) prepends every artefact whose
+frontmatter declares `trust.human_review_required: true` with:
+
+```text
+<!-- agent-config:human-review-banner -->
+> HUMAN REVIEW REQUIRED · trust: <level> · owner: <domain>
+
+<original body>
+```
+
+- The HTML comment is the parser-stable marker
+  (`_HRR_BANNER_MARKER` in `scripts/compress.py`). Runtime detection
+  greps for this string, never the prose line.
+- Idempotent: re-compressing a file that already carries the marker
+  leaves it unchanged.
+- `<domain>` is the first pack id that ships the artefact (e.g.
+  `finance-basic`, `founder-strategy`); falls back to `core` for
+  unscoped artefacts.
+
+## § 3 — Domain safety floors
+
+Each pack that ships any `advisory`/`restricted` artefact MUST also
+ship at least one rule whose logical filename contains
+`safety-floor`. The current set:
+
+| pack                    | safety-floor rule                                  |
+|-------------------------|----------------------------------------------------|
+| `core` (universal)      | `rules/engineering-safety-floor.md`                |
+| `pack-finance-basic`    | `rules/finance-safety-floor.md`                    |
+| `pack-finance-advanced` | inherits `finance-safety-floor` from `pack-finance-basic` |
+| `pack-founder-strategy` | `rules/strategy-safety-floor.md`                   |
+
+A safety-floor rule:
+
+- Carries `trust.level: advisory` and `trust.human_review_required: true`
+  itself — it ships with the banner.
+- Names what the agent must **not** issue (final investment call, binding
+  legal advice, single-path strategic verdict) and what it must surface
+  instead (alternatives, sensitivity, assumptions, jurisdiction).
+- Loads automatically alongside the rest of the pack — no opt-in.
+
+## § 4 — Installer flow
+
+[`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
+implements the gate:
+
+1. **Display.** The pack picker reads `packs[].trust_summary` from
+   `dist/discovery/discovery-manifest.json` and renders one line per pack:
+   `Finance basic: 3 advisory · 3 professional · human-review on 1`.
+2. **Confirm.** Selecting a pack with any `advisory`/`restricted`
+   artefact triggers a confirm prompt. Non-interactive mode (CI,
+   agent-mode) requires `--accept-advisory=<pack-id>[,<pack-id>...]`
+   explicitly; absence aborts with a non-zero exit.
+3. **Agent-mode.** Emits a structured `confirm` question type with the
+   trust counts inline; the host agent must relay it verbatim per
+   `command-suggestion-policy`.
+4. **Lockfile.** `.agent-config.lock.json` records the accepted trust
+   counts per pack at install time. A later `sync` that finds the
+   manifest's `trust_summary` has **escalated** (more advisory /
+   restricted artefacts than were accepted) re-runs the confirm step
+   before applying.
+
+## § 5 — Coherence lint
+
+`scripts/lint_trust_coherence.py` (wired into `ci-fast` and `ci-full`)
+asserts three invariants over `dist/discovery/discovery-manifest.json`:
+
+1. **Safety-floor presence.** Every pack with
+   `trust_summary.advisory + trust_summary.restricted > 0` ships at
+   least one artefact whose logical path contains `safety-floor`.
+2. **Banner presence.** Every artefact with
+   `trust.human_review_required: true` has its compiled output under
+   `.agent-src/<logical>` and that output contains
+   `<!-- agent-config:human-review-banner -->`.
+3. **Kernel trust floor.** Every rule listed in `dist/router.json` `kernel[]`
+   declares `trust.level: core`. No escalation (advisory blocks the
+   Iron-Law floor) and no demotion (experimental cannot guarantee it).
+
+Exits 0 clean, 1 on any violation. Tests in
+`tests/test_lint_trust_coherence.py` lock the seven failure modes.
+
+## § 6 — What this contract does **not** do
+
+- **Per-user permissions.** Trust is a property of artefacts, not of
+  users. The installer confirms once at install / sync time; there is
+  no runtime per-action authorisation.
+- **Rewriting the Iron Law floor.** `non-destructive-by-default`,
+  `commit-policy`, `scope-control § git-ops`, `security-sensitive-stop`
+  keep their universal scope — this contract references them, never
+  re-declares them. See [`safety-model`](safety-model.md) and
+  [`kernel-membership`](kernel-membership.md).
+- **Versioning the trust enum.** A new level (e.g. a future
+  `regulated`) requires a follow-on ADR; this contract enumerates the
+  current closed set.
+
+## § 7 — References
+
+- ADR: [`ADR-018 — Trust & Safety Layer`](../decisions/ADR-018-trust-and-safety-layer.md)
+- Compressor implementation: [`scripts/compress.py`](../../scripts/compress.py)
+  (`_inject_hrr_banner`, `_HRR_BANNER_MARKER`)
+- Installer implementation: [`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
+- Lint implementation: [`scripts/lint_trust_coherence.py`](../../scripts/lint_trust_coherence.py)
+- Sibling contracts: [`safety-model`](safety-model.md) ·
+  [`kernel-membership`](kernel-membership.md) ·
+  [`ADR-013` — discovery frontmatter](../decisions/ADR-013-discovery-frontmatter-contract.md)

package/docs/customization.md

@@ -205,7 +205,7 @@ if the key file's permissions drift.
 `cost_profile` is the master switch for rule-tier loading. The kernel
 (always-loaded Iron-Law floor, ≤ 26k chars across 9 rules) ships in every
 profile. Tier-1 and tier-2 rules are gated by profile and resolved at
-session start from `router.json` (compiled by `scripts/compile_router.py`).
+session start from `dist/router.json` (compiled by `scripts/compile_router.py`).
 
 | Profile | Rule tiers loaded | Token footprint | Best for |
 |---|---|---|---|
@@ -218,7 +218,7 @@ The kernel-and-router architecture is documented in
 [`docs/contracts/rule-router.md`](contracts/rule-router.md) and
 [`docs/contracts/kernel-membership.md`](contracts/kernel-membership.md).
 Tier flags live in each rule's frontmatter (`tier: kernel | tier-1 | tier-2`);
-the router compiles them into `router.json` deterministically.
+the router compiles them into `dist/router.json` deterministically.
 
 All profiles except `custom` ship with `pipelines.skill_improvement: true`,
 so the agent captures learnings after meaningful tasks by default. Set it

package/docs/decisions/ADR-007-agent-discovery-scopes.md

@@ -262,6 +262,18 @@ maintainer manifest).
   road-to-simplicity-and-everywhere" is **never built**. Roadmap
   entry should be updated to point at `export` instead.
 
+## Amendment 2026-05-23 — Global-only consumer scope (ADR-020)
+
+[`ADR-020`](ADR-020-global-only-consumer-scope.md) finishes the job
+this ADR started: the consumer surface becomes **global-only**
+end-to-end. The project-default in this ADR is therefore historical;
+new installs land at `~/.event4u/agent-config/` only. The project
+tree retains exactly two artefacts — `agents/overrides/` and
+`agents/.event4u-bridge.yml` — both written by
+`scripts/install.py`. Maintainer-only project scope survives behind
+`AGENT_CONFIG_DEV_MODE=1` (see
+[`docs/maintainers/dev-mode.md`](../maintainers/dev-mode.md)).
+
 ## Amendment 2026-05-13 — Augment global-only
 
 **Status:** Accepted · 2026-05-13 · signed off by Matze.

package/docs/decisions/ADR-013-discovery-frontmatter-contract.md

@@ -195,6 +195,30 @@ discovery-driven action.
 - **`requires_hint:` on packs is advisory only.** The runtime does
   not act on it. Acceptable for v1 per the council's "MEDIUM" note.
 
+## Amendments
+
+### 2026-05-21 — Monorepo Phase 1 closure (enforcement live)
+
+The five required keys (`workspaces`, `packs`, `lifecycle`, `trust`,
+`install`) are now **strictly enforced** across every artefact under
+`.agent-src.uncompressed/{skills,rules,commands,templates}` by
+[`scripts/lint_artefact_frontmatter.py`](../../scripts/lint_artefact_frontmatter.py),
+wired into `task lint-artefact-frontmatter`, `task ci`, and the opt-in
+combined pre-commit hook (`./agent-config hooks:install`). The migration
+rule's "Phase 4+" strict flip described above is therefore in effect.
+
+Worked examples per artefact type live in
+[`docs/contracts/frontmatter-contract.md`](../contracts/frontmatter-contract.md);
+roundtrip stability across the `task sync` pipeline is guarded by
+`tests/test_frontmatter_roundtrip.py`.
+
+The Phase-1 roadmap initially proposed splitting the contract into a
+separate `ADR-014-frontmatter-v2-contract.md`. That split was dropped —
+this ADR remains the single source of truth and absorbed the worked
+examples instead. No ADR-014 issued.
+
+Driven by [`agents/roadmaps/monorepo-phase-1-frontmatter-metadata.md`](../../agents/roadmaps/monorepo-phase-1-frontmatter-metadata.md).
+
 ## Cross-references
 
 - [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md):