@event4u/agent-config 2.26.0 → 3.1.0

package/docs/decisions/ADR-016-installer-architecture.md

@@ -0,0 +1,189 @@
+---
+adr: 016
+status: accepted
+date: 2026-05-21
+decision: installer-architecture
+supersedes: —
+superseded_by: —
+phase: v2.x · monorepo-phase-3-typescript-installer
+type: prospective
+---
+
+# ADR-016 — TypeScript Installer Architecture
+
+## Status
+
+**Accepted** · 2026-05-21 · external AI Council pass (`claude-sonnet-4-5`
++ `gpt-4o`, 2 rounds, `design` lens, actual cost $0.13) on
+[`agents/roadmaps/monorepo-phase-3-typescript-installer.md`](../../agents/roadmaps/monorepo-phase-3-typescript-installer.md).
+Council issued **conditional approval** with five blockers; this ADR
+folds each blocker into the design before Phase 3.1 starts.
+
+Session: [`agents/runtime/council/responses/phase-3-installer-design.json`](../../agents/runtime/council/responses/phase-3-installer-design.json) <!-- council-ref-allowed: ADR decision-trace -->
+
+## Context
+
+Phase 3 of the monorepo plan replaces the shell-based `install.sh` with
+a TypeScript Core Installer that drives interactive TUI, non-interactive
+CI flags, and a structured **agent-mode** JSON protocol over stdio. It
+consumes [`dist/discovery/discovery-manifest.json`](../../dist/discovery/discovery-manifest.json)
+(locked by [ADR-015](ADR-015-discovery-manifest-contract.md)) and
+writes managed files into the consumer's `.augment/` and `.agent-src/`,
+tracked in `agents/agent-config.lock.yml`.
+
+The council raised five architectural risks that, left unaddressed,
+would force post-merge rework in Phase 5 (trust) and Phase 6 (browser
+wizard). This ADR locks the resolution of each.
+
+## Decision
+
+### 1. Lockfile schema v1 records provenance, not just paths
+
+```yaml
+schema_version: 1
+agent_config_version: 2.0.0
+manifest_sha256: <hex>           # sha256 of the consumed discovery-manifest.json
+generated_at: 2026-05-21T12:00:00Z
+workspaces: [engineering, governance]
+packs:
+  - id: pack.laravel
+    version: 2.0.0
+    auto_selected: false
+    required_by: []
+files:
+  - path: .augment/skills/laravel/SKILL.md
+    pack: pack.laravel
+    pack_version: 2.0.0
+    sha256: <hex>
+    manifest_sha256: <hex>       # which manifest sourced this file
+    managed: true
+```
+
+`manifest_sha256` is per-file (not just per-lockfile) so Phase 5 trust
+gates can answer "which manifest claimed this artefact was safe?"
+without needing a lockfile rewrite.
+
+### 2. Overrides live in a separate file the installer never writes
+
+```yaml
+# agents/agent-config.overrides.yml — user-managed, installer reads but never writes
+schema_version: 1
+overrides:
+  - path: agents/overrides/skills/laravel/SKILL.md
+    shadows: .augment/skills/laravel/SKILL.md
+    reason: "Custom prompt for our team's Laravel style"
+```
+
+The lockfile (`.lock.yml`) is **append-only by the installer**;
+overrides (`.overrides.yml`) are **read-only to the installer**.
+`validate` cross-references the two. This resolves the source-of-truth
+ambiguity the council flagged on `managed: false`.
+
+### 3. Merge decision table replaces "three-way merge" handwaving
+
+| Disk    | Lock | Upstream | Override? | Action                               |
+|---------|------|----------|-----------|--------------------------------------|
+| A       | A    | A        | —         | no-op                                |
+| A       | A    | B        | no        | write B, update lock                 |
+| A       | A    | B        | yes       | write B to `.augment/`, leave override |
+| A       | A    | absent   | —         | offer prune                          |
+| X (drift) | A  | A        | —         | warn, suggest `validate --fix`       |
+| X (drift) | A  | B        | no        | error: manual merge required         |
+| X (drift) | A  | B        | yes       | error: override may be stale         |
+| absent  | A    | B        | —         | write B (recreate)                   |
+
+Encoded in `src/sync/merge-strategy.ts`; covered by
+`tests/sync-algorithm.test.ts` with one case per row.
+
+### 4. Agent mode: strict question-ID validation (stateless)
+
+Of the three options the council surfaced (session token, nonce,
+strict sequencing) we adopt **strict sequencing**: the CLI tracks the
+current question id in the manifest of expected answers; any
+`--answer` that does not match the current question id returns:
+
+```json
+{ "status": "error", "protocol_version": 1, "reason": "out_of_order",
+  "expected_question_id": "q1.workspaces", "received": "q2.packs" }
+```
+
+Stateless (no session file), enforceable, and easy to test. Nonces
+can be added later under the same protocol version if the threat model
+hardens.
+
+### 5. Atomic writes via staging directory
+
+Every command that writes to `.augment/`, `.agent-src/`, or the
+lockfile stages changes under `.augment/.agent-config-staging/<uuid>/`,
+verifies sha256s against intended manifest entries, then performs:
+
+1. Atomic rename: `staging/.augment/foo.md` → `.augment/foo.md`
+   (per-file `fs.renameSync` is atomic on POSIX and Windows ≥ 10).
+2. Lockfile written last (so a mid-flight crash leaves the lockfile
+   pointing at the previous-good state, not the partial new state).
+3. Staging directory removed on success.
+
+`init`, `sync`, and `prune` share the same `commitAtomic(staging)`
+helper.
+
+### 6. `protocol_version` field on every agent-mode response
+
+```json
+{ "status": "question", "protocol_version": 1, "id": "q1.workspaces", ... }
+```
+
+Pinned at 1 for Phase 3; bumped to 2 only on breaking change.
+Versioning the schema (not just `next_call`) lets Phase 5 add trust
+banners without breaking existing agents.
+
+## Consequences
+
+**Positive**
+
+- Phase 5 (trust) can add `trust_level` to lockfile packs without a
+  schema migration (already at `schema_version: 1`; trust fields
+  become optional v1 additions).
+- Phase 6 (browser wizard) reuses the same agent-mode JSON shape over
+  a local HTTP server; the strict-sequencing model maps to HTTP
+  request/response naturally.
+- `agents/agent-config.overrides.yml` becomes a Git-tracked
+  declaration of user intent — diffable, reviewable, and never
+  silently overwritten.
+- Atomic writes give `sync` and `prune` crash safety without a
+  rollback subcommand.
+
+**Negative**
+
+- One extra YAML file in the consumer repo (overrides).
+- Strict sequencing means agents must replay the conversation if they
+  lose state mid-call; this is the simplest threat-model resolution
+  but pushes complexity onto agent authors.
+- Per-file `manifest_sha256` adds ~64 bytes per lockfile entry; for a
+  500-file install that's 32 KB. Acceptable.
+
+**Deferred to Phase 5**
+
+- npm package signature verification (SLSA Level 3 / `npm
+  provenance`). Reviewer A's "sign the package, not just the
+  manifest" call. Phase 5 owns trust gates; Phase 3 only records
+  provenance.
+
+## Rejected alternatives
+
+- **Single lockfile with `overrides:` section** — the original spec.
+  Rejected because the installer cannot detect untracked
+  user-authored overrides without either scanning `agents/overrides/`
+  (which a malicious agent could pollute) or trusting user edits to
+  the lockfile (which breaks "lockfile is installer-generated").
+- **Nonce-based agent mode** — overkill for v1. Re-evaluate when
+  agent mode lands on a remote surface.
+- **Rollback subcommand with lockfile history** — atomic writes
+  already give us crash safety; full version history is a Phase 6
+  concern (the browser wizard wants a timeline).
+
+## References
+
+- Roadmap: [`agents/roadmaps/monorepo-phase-3-typescript-installer.md`](../../agents/roadmaps/monorepo-phase-3-typescript-installer.md)
+- Discovery manifest: [ADR-015](ADR-015-discovery-manifest-contract.md)
+- CLI shell precedent: [ADR-012](ADR-012-typescript-cli-shell.md)
+- Council session: [`agents/runtime/council/responses/phase-3-installer-design.json`](../../agents/runtime/council/responses/phase-3-installer-design.json) <!-- council-ref-allowed: ADR decision-trace -->

package/docs/decisions/ADR-017-monorepo-physical-layout.md

@@ -0,0 +1,261 @@
+---
+adr: 017
+status: accepted
+date: 2026-05-21
+decision: monorepo-physical-layout
+supersedes: —
+superseded_by: —
+phase: v2.x · monorepo-phase-4-physical-package-layout
+type: prospective
+---
+
+# ADR-017 — Monorepo Physical Package Layout
+
+## Status
+
+**Accepted** · 2026-05-21 · external AI Council pass (`claude-sonnet-4-5`
++ `gpt-4o`, 2 rounds, `design` lens, actual cost $0.0961) on the Phase 4
+roadmap. Council issued **conditional approval** with four blockers and
+two refinements; this revision folds each into the design before the
+`--apply` step runs.
+
+Session: [`agents/runtime/council/responses/phase-4-physical-layout.json`](../../agents/runtime/council/responses/phase-4-physical-layout.json) <!-- council-ref-allowed: ADR decision-trace -->
+
+Companion artefacts:
+- [`agents/roadmaps/monorepo-phase-4-physical-package-layout.md`](../../agents/roadmaps/monorepo-phase-4-physical-package-layout.md)
+- [`dist/migration/move-plan.json`](../../dist/migration/move-plan.json) (94 moves, 432 core, 0 conflicts)
+- [`dist/migration/pre-move-snapshot.json`](../../dist/migration/pre-move-snapshot.json) (744 files hashed)
+- [`scripts/plan_physical_move.py`](../../scripts/plan_physical_move.py) (plan + apply)
+- [`scripts/verify_physical_move.py`](../../scripts/verify_physical_move.py) (post-move diff vs. snapshot)
+
+## Context
+
+Phases 1–3 produced the artefact metadata (`packs[]`, `workspaces[]`,
+`trust.level`, `install.removable`), the discovery manifest, and the
+TypeScript installer **without** moving a single file. The on-disk
+source tree is still flat:
+
+```text
+.agent-src.uncompressed/
+  rules/        # 72 entries
+  skills/       # 218 entries
+  commands/     # 129 entries
+  personas/     # 24 entries
+  contexts/     # 32 entries
+  templates/    # 24 scaffolds
+  …
+```
+
+This means the metadata says "this skill belongs to `pack.laravel`" but
+the file lives next to a Symfony skill and a finance persona. Consumers
+of the npm release, the consumer-side `.augment/` overlay, and the
+upcoming Phase 5 trust gates would all benefit from physical separation
+that mirrors the manifest. Phase 4 introduces that separation in one PR
+with a deterministic, history-preserving migration.
+
+The four risks the council flagged on Phase 3 (history loss, stale path
+refs, cross-pack drift, hand-edited paths) all bite hardest here.
+
+## Decision
+
+### 1. Layout — one core, one folder per pack
+
+```text
+packages/
+  core/
+    installer/                       # TS CLI (already there post-Phase 3)
+    .agent-src.uncompressed/         # rules + kernel skills + scaffolds
+  pack-php/.agent-src.uncompressed/
+  pack-laravel/.agent-src.uncompressed/
+  …
+  pack-ai-video/.agent-src.uncompressed/
+```
+
+No flag day: every commit between "before" and "after" the move builds
+and ships. The TS installer needs zero behavioural changes — only the
+`manifest-loader.ts` path roots flip.
+
+### 2. Mapping rules (deterministic, lockfile-stable)
+
+Implemented in [`scripts/plan_physical_move.py`](../../scripts/plan_physical_move.py):
+
+1. **Kernel rules** → `packages/core/` (allowlist, sanity-checked against
+   [`docs/contracts/kernel-membership.md`](../contracts/kernel-membership.md) §4).
+   The locked set is 10 entries; `user-interrupt-priority` was admitted
+   post-P2.2 and is included.
+2. **Core-trust artefacts** (`trust.level: core` AND
+   `install.removable: false`) → `packages/core/`.
+3. **Non-frontmatter trees** (`templates/`, `profiles/`, `presets/`,
+   `contexts/`, `user-types/`, `scripts/`, `ghostwriter/`, `packs/`,
+   `personas/`) → `packages/core/` verbatim. These are scaffolding and
+   product internals, not pack-routable artefacts.
+4. **Skill auxiliary files** (`prompts/*.md`, sub-pages inside a skill
+   directory) → inherit the destination of the nearest `SKILL.md` in
+   the parent directory tree. Codified to fix 9 false-positive conflicts
+   on Phase 4 dry-run.
+5. **Pack-routable artefacts** → `packages/pack-<id>/`, where `<id>` is
+   the first entry in `packs[]`. Tie-breaking by alphabetic pack id.
+6. **Quarantined scaffolds** (the 26 entries in
+   [`config/discovery/unassigned-artefacts.yml`](../../config/discovery/unassigned-artefacts.yml))
+   → `packages/core/` with `unassigned scaffold:` reason recorded in the
+   move plan. The top-level `.agent-src.uncompressed/README.md` was added
+   here during dry-run.
+7. **`primary pack: meta`** → `packages/core/` (package-internal
+   scaffolding, not a real pack).
+8. **Unknown / missing pack** → fall back to `packages/core/` AND emit
+   a conflict. `--apply` refuses to run if `conflicts > 0`.
+
+### 3. Mechanic — `git mv` only
+
+Every move uses `git mv` so `git log --follow` keeps working on every
+artefact post-move. The plan script's `--apply` mode is the only entry
+point; it refuses if any conflict remains. No human-edited paths.
+
+### 4. Byte-identity contract
+
+`task sync` + `task build-discovery` after the move must produce
+`.agent-src/`, `.augment/`, and `dist/discovery/discovery-manifest.json`
+byte-identical to the pre-move snapshot **except** for
+`artefacts[].path` values. [`scripts/verify_physical_move.py`](../../scripts/verify_physical_move.py)
+captures a post-move snapshot and diffs against
+`dist/migration/pre-move-snapshot.json`; the only allowed delta is the
+`path` field per artefact.
+
+### 5. Rollback
+
+The whole move is a single PR. `git revert <merge-sha>` restores the
+prior layout in one commit; the next `task sync` round-trip is back to
+the pre-move snapshot. No data migration, no manifest schema change, no
+installer behaviour change.
+
+## Consequences
+
+### Positive
+
+- Metadata-to-disk parity: a consumer can now `cd packages/pack-laravel`
+  and see exactly what `pack.laravel` ships, no manifest indirection.
+- Phase 5 (trust) lands cleanly inside `packages/core/installer/` and
+  reads per-pack metadata from `packages/pack-*/.agent-src.uncompressed/`.
+- Phase 6 (browser wizard) maps packs 1:1 to its left-nav.
+- Cross-pack drift is now lintable (`task lint-pack-boundaries` in
+  Phase 4.4 of the roadmap).
+- `git log --follow` keeps working — no history loss.
+
+### Negative
+
+- One large PR (~526 file moves). Reviewers need the move plan as the
+  primary review artefact, not per-file diff inspection.
+- Editors with the old tree open will hit broken paths until they pull.
+  Mitigated by docs-update in the same PR (`AGENTS.md`, `README.md`,
+  `docs/architecture.md`).
+- Path refs in CI workflows, Taskfile, and the discovery scanner need
+  one-line updates. The roadmap enumerates each.
+
+### Neutral
+
+- The npm tarball shape changes (paths only). The installer copies
+  files by manifest entry, not by source path, so consumers see no
+  difference.
+
+## Alternatives considered
+
+1. **Phased move (one pack per PR).** Rejected: 16 PRs, partial states
+   on disk for weeks, `task sync` invariants harder to enforce.
+2. **Symlink farm.** Rejected: Windows support, npm tarball duplication,
+   and the installer would have to dereference paths.
+3. **Stay flat, lift packs into manifest-only.** Rejected: this is the
+   current state; it forfeits the metadata-to-disk parity that Phase 5
+   and Phase 6 depend on.
+
+## Council resolution (Round 2)
+
+Four blocking items and two refinements raised by the council; each
+resolved before `--apply` runs.
+
+### B1 — Final source location of `.agent-src.uncompressed/`
+
+The council asked whether the source tree nests inside `packages/core/`
+(current design) or becomes a peer `pack-core/`. **Decision: keep
+`packages/core/.agent-src.uncompressed/`.** Three reasons:
+
+1. `packages/core/` is the engine + installer + kernel rules +
+   scaffolding (templates, profiles, presets, contexts, user-types).
+   None of that is pack-routable; making it a "pack" inverts the
+   product mental model.
+2. The installer in `packages/core/installer/` already lives next to
+   the manifest loader; co-locating the rules that bootstrap the
+   installer reduces cross-package import chains.
+3. The TS installer consumes `dist/discovery/discovery-manifest.json`,
+   not source paths, so the "location is privileged" critique does not
+   bite — the manifest is the API.
+
+### B2 — `git mv` rename detection at scale
+
+Default `diff.renameLimit` since git 2.9 is 1000. Plan: 94 explicit
+`git mv` operations + 1 directory rename for `core/`. Each move is
+content-identical (no edits during move). Test gate: after `--apply`,
+run `git diff --name-status HEAD~1` and assert `R100` (100 % rename
+similarity) on every moved file. Verification script enforces this.
+
+### B3 — Consumer-facing output contract
+
+`task sync` writes `.agent-src/` (compressed) and `.augment/` (overlay)
+at repo root — **unchanged** location and structure. The byte-identity
+contract covers exactly these two trees plus the discovery manifest.
+What changes:
+
+- `dist/discovery/discovery-manifest.json` `artefacts[].path` values
+  (path-only delta, enforced by `verify_physical_move.py`).
+- npm tarball internal paths (consumers never touch these; installer
+  uses manifest entries).
+
+What stays identical: `.agent-src/`, `.augment/`, manifest checksums
+of non-path fields, lockfile schema, installer behaviour.
+
+### B4 — Installer dual-layout support
+
+Not required. Consumers install via `npm install
+@event4u/agent-config@<version>`; each version ships a self-consistent
+tarball. There is no "consumer pulls mid-PR" scenario because consumers
+do not consume the source repo — they consume the published tarball.
+Source-tree contributors who pull the merge commit move atomically
+with the layout. The "dual-layout" complexity the council proposed
+exists in code-host-as-CDN ecosystems we do not target.
+
+### R1 — `primary_pack` frontmatter field
+
+`scripts/plan_physical_move.py` already uses `packs[0]` as the
+destination. Round-2 hardening: the plan also reads an explicit
+`primary_pack:` frontmatter field when present and prefers it over
+`packs[0]`. Lint that requires `primary_pack` on every pack-routable
+artefact lands in Phase 4.4 (out of scope for the move itself; the
+move uses today's data and the new fallback).
+
+### R2 — Pre-move pack-boundary lint
+
+The current plan dry-run finds 0 conflicts after the auxiliary-file
+inheritance rule landed. A cross-pack-reference lint (an artefact in
+`pack.laravel` citing one in `pack.symfony` without a declared
+dependency) is deferred to Phase 4.4 — the move itself does not edit
+file contents, so cross-pack references survive the move byte-identical.
+
+## Compliance + verification
+
+- `scripts/plan_physical_move.py` is the only mover. Hand-edited paths
+  fail `task verify-physical-move`.
+- `scripts/verify_physical_move.py` enforces the byte-identity
+  contract.
+- `task ci` runs both as a hard gate post-move.
+- Per-pack lint matrix lands in Phase 4.4 of the roadmap.
+
+## Future work
+
+- Phase 4.4 — per-pack `pack.yaml` + boundary lint.
+- Phase 4.5 — contributor scaffolders (`task new-skill`,
+  `task move-artefact`).
+- Phase 6 (optional) — split distribution per pack as separate npm
+  packages. Specification removed 2026-05-24 (drift audit, finding
+  F-1): the 150-line "documented-only" addendum had zero consumers
+  and ~6 months of unmaintained drift versus the bundled-tarball
+  model. Restore from git history at `d06af2c5` if a real consumer
+  ever asks for a single-pack install path.

package/docs/decisions/ADR-018-trust-and-safety-layer.md

@@ -0,0 +1,159 @@
+---
+adr: 018
+status: accepted
+date: 2026-05-21
+decision: trust-and-safety-layer
+supersedes: —
+superseded_by: —
+phase: v2.x · monorepo-phase-5-trust-safety-layer
+type: prospective
+---
+
+# ADR-018 — Trust & Safety Layer
+
+## Status
+
+**Accepted** · 2026-05-21 · external AI Council pass on the Phase 5
+roadmap (`claude-sonnet-4-5` + `gpt-4o`, `design` lens). Council
+confirmed the closed-enum trust ladder, the per-pack safety-floor
+rule, and the compressor-injected HRR banner; refinement folded into
+the lint script and the installer's confirm copy.
+
+Session: [`agents/runtime/council/responses/phase-5-trust-safety.json`](../../agents/runtime/council/responses/phase-5-trust-safety.json) <!-- council-ref-allowed: ADR decision-trace -->
+
+Companion artefacts:
+- Contract: [`docs/contracts/trust-and-safety.md`](../contracts/trust-and-safety.md)
+- Roadmap: [`agents/roadmaps/monorepo-phase-5-trust-safety-layer.md`](../../agents/roadmaps/monorepo-phase-5-trust-safety-layer.md)
+- Lint: [`scripts/lint_trust_coherence.py`](../../scripts/lint_trust_coherence.py) + [`tests/test_lint_trust_coherence.py`](../../tests/test_lint_trust_coherence.py)
+- Compressor: [`scripts/compress.py`](../../scripts/compress.py) (`_inject_hrr_banner`)
+- Installer: [`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
+
+## Context
+
+[`ADR-013`](ADR-013-discovery-frontmatter-contract.md) added the three
+trust fields (`trust.level`, `trust.confidence`,
+`trust.human_review_required`) as the discovery-frontmatter contract
+in Phase 1 of the monorepo migration. Phase 2's discovery manifest
+([`ADR-015`](ADR-015-discovery-manifest-contract.md)) rolled them up
+into `packs[].trust_summary`. Phases 3 and 4 wired the TypeScript
+installer ([`ADR-016`](ADR-016-installer-architecture.md)) and moved
+sources into `packages/` ([`ADR-017`](ADR-017-monorepo-physical-layout.md)).
+
+After Phase 4 we had the **metadata** end-to-end but **no enforcement**:
+
+- Installer treated all packs identically — no surface for advisory
+  content, no confirm step before opting into legally-flavoured
+  finance / strategy material.
+- Compressor preserved frontmatter but did not propagate the
+  `human_review_required` signal into the compiled artefact, so the
+  runtime had no parser-stable hook to gate output on.
+- Domain-specific safety floors (finance, founder-strategy,
+  engineering) existed only as drafts under
+  `agents/tmp/refactor-package.txt`; they were not first-class
+  artefacts shipped with their packs.
+- No lint existed to catch drift between declared trust level and
+  the absence of the matching guardrail rule.
+
+The existing universal floors (`non-destructive-by-default`,
+`commit-policy`, `scope-control § git-ops`, `security-sensitive-stop`)
+covered the **action** surface — destruction, push, secrets, prod —
+but said nothing about **output** quality on advisory domains
+(investment calls, valuation verdicts, strategic recommendations).
+Without a Phase 5, a user installing `pack-finance-basic` could
+receive a final "yes, invest" answer with no review banner and no
+sensitivity required.
+
+## Decision
+
+Ship a four-piece trust & safety layer:
+
+1. **Closed-enum trust ladder.** `core` · `professional` · `advisory`
+   · `restricted` · `experimental`. Authoritative table and meaning
+   live in [`trust-and-safety § 1`](../contracts/trust-and-safety.md#-1--trust-levels).
+2. **HRR banner injection.** The compressor scans frontmatter and
+   prepends `<!-- agent-config:human-review-banner -->\n> HUMAN REVIEW
+   REQUIRED · trust: <level> · owner: <domain>` to any artefact with
+   `trust.human_review_required: true`. Idempotent on re-compression.
+3. **Per-pack safety-floor rules.** `core` ships
+   `engineering-safety-floor.md`; `pack-finance-basic` ships
+   `finance-safety-floor.md`; `pack-founder-strategy` ships
+   `strategy-safety-floor.md`. Each is itself `advisory` +
+   `human_review_required: true`, so it carries the banner and loads
+   automatically with the pack.
+4. **Installer confirm + lockfile escalation.** The pack picker shows
+   the trust mix per pack; selecting an advisory/restricted pack
+   triggers a confirm prompt (or `--accept-advisory=<pack-id>` in
+   non-interactive mode). Accepted trust counts are recorded in
+   `.agent-config.lock.json`. Subsequent `sync` runs that find an
+   escalation re-confirm before applying.
+5. **Coherence lint.** `scripts/lint_trust_coherence.py` enforces:
+   (a) safety-floor presence per advisory/restricted pack;
+   (b) HRR banner presence in compiled output;
+   (c) kernel rules declare `trust.level: core`. Wired into
+   `ci-fast` and `ci-full`.
+
+## Consequences
+
+### Good
+
+- **Single source of trust truth.** The frontmatter field is the
+  one input; the installer, compressor, lint, and runtime all read
+  it. No parallel registry, no duplicated copy.
+- **Banner is parser-stable.** The HTML-comment marker survives every
+  downstream surface (Augment, Claude, Cursor, Windsurf) because it is
+  Markdown comment syntax, not prose. Runtime detection greps the
+  marker, never the human-readable line.
+- **Coherence is enforceable in CI.** A pack that ships advisory
+  content without its safety-floor rule fails the build. A kernel
+  rule downgraded to advisory fails the build. A
+  `human_review_required` artefact whose compiled output drifted
+  fails the build.
+- **Lockfile catches drift across releases.** An upgrade that
+  escalates a previously-`professional` artefact to `advisory`
+  re-confirms with the user instead of silently applying.
+
+### Trade-offs
+
+- **One more lint** (~200 LOC + 7 tests) added to `ci-fast`. Live
+  manifest run is sub-second; budget impact negligible.
+- **Closed enum** means new trust levels (e.g. a future `regulated`)
+  require a follow-on ADR. Accepted as the price for stable lint
+  invariants.
+- **Banner is visible in compiled output**, so users browsing
+  `.agent-src/` will see "HUMAN REVIEW REQUIRED" on advisory rules.
+  Treated as a feature, not a leak: the banner is the gate.
+
+### Rejected alternatives
+
+- **Per-user permission system.** Considered and rejected: trust is a
+  property of artefacts, not users. The installer's once-per-install
+  confirm is the gate; a runtime per-action authorisation would
+  duplicate the universal floors (`non-destructive-by-default` etc.)
+  without adding signal.
+- **Re-declaring the Iron-Law floors here.** The four floors stay
+  where they live (`kernel-membership`, `safety-model`); this ADR
+  references them, never restates them. Avoids contradictory edits.
+- **Open-ended trust enum.** A free-form string would let packs invent
+  their own levels and bypass the lint. Closed enum keeps the
+  contract enforceable.
+
+## Open questions
+
+- A future `regulated` level for healthcare / regulated-finance content
+  is anticipated but not in scope; will follow `pack-healthcare` or
+  similar.
+- Per-artefact `owner` field is currently derived (first pack id).
+  Future ADR may promote `trust.owner` to an explicit frontmatter
+  key when more than one pack ships the same artefact under different
+  ownership stories.
+
+## References
+
+- Contract: [`docs/contracts/trust-and-safety.md`](../contracts/trust-and-safety.md)
+- Roadmap: [`agents/roadmaps/monorepo-phase-5-trust-safety-layer.md`](../../agents/roadmaps/monorepo-phase-5-trust-safety-layer.md)
+- Predecessors: [`ADR-013`](ADR-013-discovery-frontmatter-contract.md)
+  · [`ADR-015`](ADR-015-discovery-manifest-contract.md)
+  · [`ADR-016`](ADR-016-installer-architecture.md)
+  · [`ADR-017`](ADR-017-monorepo-physical-layout.md)
+- Sibling: [`safety-model`](../contracts/safety-model.md) ·
+  [`kernel-membership`](../contracts/kernel-membership.md)