@event4u/agent-config 3.0.0 → 3.1.0

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)

package/docs/decisions/ADR-019-router-json-dist-location.md

@@ -0,0 +1,124 @@
+---
+adr: 019
+status: accepted
+date: 2026-05-23
+decision: router-json-dist-location
+supersedes: —
+superseded_by: —
+phase: v2.x · post-monorepo cleanup
+type: retrospective
+---
+
+# ADR-019 — `router.json` relocated to `dist/router.json`
+
+## Status
+
+**Accepted** · 2026-05-23. Moves the compiled router-kernel artefact
+from the repo root to `dist/router.json`, aligning it with the
+existing `dist/discovery/` build-artefact slot established by
+ADR-015.
+
+Companion artefacts:
+- Contract: [`docs/contracts/rule-router.md`](../contracts/rule-router.md)
+- Compiler: [`scripts/compile_router.py`](../../scripts/compile_router.py)
+- ADR-rule-kernel-and-router: [`ADR-rule-kernel-and-router.md`](ADR-rule-kernel-and-router.md)
+- Tier ADR: [`docs/adrs/router/0001-three-tier-routing.md`](../adrs/router/0001-three-tier-routing.md)
+
+## Context
+
+`router.json` was emitted at the repo root by the original
+kernel-and-router shipping (ADR-rule-kernel-and-router, P3.2). The
+root location pre-dated the `dist/` convention; once
+ADR-015 codified `dist/discovery/` as the build-artefact slot and
+ADR-012 introduced `dist/cli/` for the TS shell, the router
+artefact's root location became the outlier — visually equivalent
+to hand-edited project files like `AGENTS.md` or
+`.agent-settings.yml`, even though it is regenerated from rule
+frontmatter on every `task compile-router` / `task sync` run.
+
+The artefact is still a **public contract**: external host agents
+(Claude.ai bundle, Skills API per
+[`package-self-orientation`](../contracts/package-self-orientation.md))
+read it once per session to resolve the always-loaded kernel and the
+tier-1/2 routing tables. Moving it is therefore a one-time breaking
+change for consumers — they update the read path or fail to resolve
+rules at session start.
+
+## Decision
+
+**Compile to `dist/router.json` and ship the file tracked in git
+under a `!/dist/router.json` allowlist exception.** `dist/` remains
+gitignored; only the router artefact is committed.
+
+Rationale:
+
+1. **Slot consistency.** Build outputs live under `dist/`. Two
+   pre-existing slots (`dist/discovery/`, `dist/cli/`) already
+   commit selected artefacts via `.gitignore` allowlists. The
+   router follows the same pattern.
+2. **Thin-Root contract.** `AGENTS.md` and the repo root are
+   pointer-heavy and human-curated; generated artefacts at the root
+   create review noise on every regen.
+3. **Single read path.** Host agents already read
+   `dist/discovery/discovery-manifest.json`; adding the router to
+   the same parent dir collapses the "where does the package emit
+   its public contracts" answer to a single directory.
+
+## Trade-offs accepted
+
+- **Breaking change for consumers.** Pinned external readers (the
+  Claude.ai bundle, any Skills API caller, third-party tooling
+  reading the kernel) must update their read path from
+  `<root>/router.json` to `<root>/dist/router.json`. No deprecation
+  shim — the path is in the artefact body for one
+  release window, surfaced via the changelog, and that is the
+  contract update.
+- **Allowlist drift risk.** A future `dist/` purge that forgets the
+  `!/dist/router.json` line will silently regress the public
+  contract. The `task release-prepare` and `task ci` runs both call
+  `compile_router.py`, which re-creates the file before any
+  packaging step that would notice its absence.
+
+## Implementation footprint
+
+- **Compiler / CLI.** `scripts/compile_router.py`,
+  `scripts/lint_trust_coherence.py`, `scripts/_cli/cmd_explain.py`,
+  `scripts/_cli/explain_last/route.py` — output path constants
+  point at `dist/router.json`.
+- **Smoke.** `scripts/smoke/kernel.sh`, `scripts/smoke/router.sh`
+  read from the new path; `.github/workflows/smoke.yml` path-trigger
+  globs updated via `docs/contracts/smoke-contracts.md`.
+- **Tests.** `tests/test_lint_trust_coherence.py`,
+  `tests/test_cmd_explain.py`, `tests/cli/explain_last/conftest.py`
+  patch the new constants; `tests/test_one_liner_entrypoints.sh`
+  stages `dist/router.json` (not the whole `dist/`, to avoid pulling
+  in the TS-compiled CLI which needs `node_modules`).
+- **`.gitignore`.** `/dist/` stays ignored; `!/dist/router.json`
+  allowlist exception added.
+- **Docs.** `AGENTS.md`, `docs/architecture.md`,
+  `docs/customization.md`, `docs/contracts/{rule-router,
+  namespace, trust-and-safety, smoke-contracts, kernel-membership}.md`,
+  `docs/contracts/explain-trace.schema.json`,
+  `docs/adrs/router/0001-three-tier-routing.md`,
+  `docs/adrs/smoke/0001-per-tier-smoke-scripts.md`.
+- **Source rules.** Uncompressed rule sources referencing the path
+  (`caveman-speak.md`, `git-history-discipline.md`) updated and
+  re-projected.
+
+## Reversal cost
+
+Two-edit revert: move the file back, flip the constants, drop the
+allowlist line. `git mv` history is preserved through the rename,
+so a `git revert` of the commit suffices. The contract update would
+be a second breaking change for any consumer that adopted the new
+path — so reversal is **possible but expensive after first
+external uptake**.
+
+## References
+
+- [`docs/contracts/rule-router.md`](../contracts/rule-router.md) — frontmatter + read-path contract.
+- [`docs/contracts/kernel-membership.md`](../contracts/kernel-membership.md) — kernel cap.
+- [`dist/router.json`](../../dist/router.json) — compiled output.
+- [`scripts/compile_router.py`](../../scripts/compile_router.py) — compiler.
+- [`ADR-015-discovery-manifest-contract.md`](ADR-015-discovery-manifest-contract.md) — precedent for `dist/` allowlist.
+- [`ADR-rule-kernel-and-router.md`](ADR-rule-kernel-and-router.md) — original kernel-and-router decision.

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

@@ -0,0 +1,123 @@
+---
+adr: 020
+status: accepted
+date: 2026-05-23
+decision: global-only-consumer-scope
+supersedes: —
+superseded_by: —
+phase: v3.x · global-only install rollout
+type: forward-looking
+---
+
+# ADR-020 — Global-only consumer scope
+
+## Status
+
+**Accepted** · 2026-05-23. Phases 1-5 of
+`road-to-global-only-install` shipped (Setup-Wizard, consumer scope
+gate, surface + bridge, migration tooling). Phase 6 (docs sweep)
+in progress. The ADR locks the decision; the roadmap locks the
+mechanics.
+
+Companion artefacts:
+- Roadmap: [`agents/roadmaps/road-to-global-only-install.md`](../../agents/roadmaps/road-to-global-only-install.md)
+- Bridge contract: [`docs/contracts/consumer-bridge.md`](../contracts/consumer-bridge.md)
+- Wizard contract: [`docs/contracts/gui-wizard.md`](../contracts/gui-wizard.md)
+- Predecessor ADR: [`ADR-007`](ADR-007-agent-discovery-scopes.md) — scope precedence, global-default amendment
+- Perms entry-gate: [`scripts/lint_global_paths.py`](../../scripts/lint_global_paths.py)
+- Payload schema: [`schemas/wizard-apply-payload.schema.json`](../../schemas/wizard-apply-payload.schema.json)
+
+## Context
+
+ADR-007 (2025-Q4) established that the agent-config consumer can run
+in two scopes — **project** (`<repo>/.augment/`, `<repo>/.claude/`, …)
+or **global** (`~/.claude/`, `~/.cursor/`, `~/.augment/`, …) — and
+that newly-onboarded consumers default to **global**. Six months of
+field use surfaced three structural problems:
+
+1. **Settings drift.** Per-project `.agent-settings.yml` files
+   accumulate stale `personal.*` keys that disagree with the user's
+   real preferences. Multi-repo developers ship the wrong
+   `personal.autonomy` into PRs.
+2. **Onboarding fragmentation.** New users land in `wizard.md` from
+   one tool, `getting-started-by-role.md` from another, and a
+   project-local `.agent-user.md` from a third. Three near-identical
+   surfaces, each subtly inconsistent.
+3. **Update lag.** Consumer projects pin an installer version in
+   `package.json`. Skill / rule / command edits ship to the package
+   but never reach the consumer until someone manually bumps.
+
+The amendment in ADR-007 (2026-05-13) flipped the **default** to
+global for Augment. This ADR finishes the job: the consumer surface
+becomes **global-only** end-to-end. The project tree retains exactly
+one piece of agent state — `agents/overrides/` plus the bridge marker
+documented in [`consumer-bridge`](../contracts/consumer-bridge.md).
+
+## Decision
+
+Consumer installations of `@event4u/agent-config` write **only** to
+`~/.event4u/agent-config/` (global root) and `agents/.event4u-bridge.yml`
+(in-repo marker). The Setup-Wizard and the legacy Installer-GUI
+converge on a single `/api/apply` endpoint behind a `schema_version`
+discriminator. Per-tool adapters resolve their rules / skills /
+commands by reading the bridge marker, expanding `global_root`, and
+fanning out from there.
+
+The single project-local exception is `agents/overrides/`, which
+remains the canonical place to override or extend a shared skill /
+rule / command per [override-management](../../.agent-src.uncompressed/skills/override-management/SKILL.md).
+
+The maintainer-side dev experience is preserved by the
+`AGENT_CONFIG_DEV_MODE=1` environment gate documented in
+[`docs/maintainers/dev-mode.md`](../maintainers/dev-mode.md). With the
+flag set, `scripts/install.py` treats the package repo as both source
+and project surface (Phase 3 contract).
+
+## Alternatives considered
+
+- **Status quo (project default + global opt-in).** Keeps the drift
+  problem; multi-repo developers continue to ship stale
+  `personal.*` keys. Rejected.
+- **Dual-endpoint `/api/apply` (one per payload shape).** Doubles
+  the CSRF + idle-timer surface with no observability gain. Rejected;
+  see `gui-wizard § D12`.
+- **Per-project bridge YAML pointing to multiple global roots.**
+  Enables team-shared globals via NFS but introduces a tenancy model
+  the rest of the system is not designed for. Deferred to a future
+  ADR; v1 of the bridge marker is single-root.
+
+## Consequences
+
+**Positive.**
+- One source of truth for `personal.*`, `agent_council.*`, and `personas:`.
+- New skills / rules / commands reach every consumer the moment they
+  install or run `task dev:install-global` — no per-repo bump.
+- The onboarding wizard becomes the only authoring surface for
+  `.agent-user.md`. Three duplicate flows collapse into one.
+
+**Negative.**
+- Phase 3 SCOPE_SUPPORT flip is breaking for any tool that still
+  hard-codes a project-local lookup. Migration order is locked in
+  the roadmap (Phase 5) — `agent-config migrate-to-global` runs the
+  perms entry-gate, copies, verifies, then deletes the project
+  shadow.
+- The bridge marker is a new failure mode: a stale `global_root` on
+  disk yields a fail-closed error instead of a silent project-local
+  fallback. The trade-off is intentional; silent fallback is what
+  produced the drift in the first place.
+
+**Operational.**
+- `scripts/lint_global_paths.py` becomes a required precondition for
+  `migrate-to-global`. Wrong perms (e.g. `0755` on the global root
+  when `0700` is expected) abort the migration before any write.
+- The Augment, Claude, and Cursor adapters get free-form-tested by
+  the maintainer dev install every CI run, so a regression in the
+  bridge-resolver surfaces immediately instead of at consumer time.
+
+## References
+
+- [`ADR-007`](ADR-007-agent-discovery-scopes.md) — discovery scope precedence and the 2026-05-13 global-default amendment.
+- [`ADR-018`](ADR-018-trust-and-safety-layer.md) — trust levels and HRR banner; unchanged by this decision.
+- [`road-to-global-only-install`](../../agents/roadmaps/road-to-global-only-install.md) — phased rollout, cross-phase gates A1-A7.
+- [`consumer-bridge`](../contracts/consumer-bridge.md) — bridge marker schema and reader contract.
+- [`gui-wizard § Apply payload`](../contracts/gui-wizard.md#apply-payload--versioning-handshake-road-to-global-only-install-phase-04--d12) — payload discriminator.

package/docs/decisions/ADR-021-deployment-shape.md

@@ -0,0 +1,153 @@
+---
+adr: 021
+status: accepted
+date: 2026-05-24
+decision: deployment-shape
+supersedes: —
+superseded_by: —
+phase: v3.x · internal-AI-OS deployment Phase 1
+type: forward-looking
+---
+
+# ADR-021 — Deployment shape (internal AI OS, Phase 1)
+
+## Status
+
+**Accepted** · 2026-05-24. Phase 1 of
+[`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
+ships the container image + Compose topology + host binding +
+healthcheck. Phases 2–5 (identity, central policy, team context,
+connectors) are tracked but **not yet implemented**; their ADRs
+(022–025) are reserved but unwritten.
+
+Companion artefacts:
+
+- Roadmap: [`agents/roadmaps/road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
+- Artefacts: [`packages/core/deploy/`](../../packages/core/deploy/)
+- Env contract: [`docs/deploy/env-vars.md`](../deploy/env-vars.md)
+- Council question (drafted, not invoked — no keys): [`agents/tmp/council-question-deployment-shape.md`](../../agents/tmp/council-question-deployment-shape.md)
+- Predecessor ADR: [`ADR-016`](ADR-016-installer-architecture.md) — installer architecture (agent-mode protocol the GUI server wraps).
+
+## Context
+
+For the first two years `@event4u/agent-config` shipped as a
+developer-local tool: `npx @event4u/agent-config init` writes files
+into the consumer repo, the wizard runs on `127.0.0.1`, no state
+persists beyond the lockfile. Field signal (multiple companies asking
+"can we host this for the team?") motivates a second shape: a
+**single deployed instance per organization**, hosting wizard +
+Council + memory for 5–50 engineers behind their SSO.
+
+Three structural questions had to settle before code:
+
+1. **Topology** — bare Compose vs Helm vs both.
+2. **Process shape** — single Node container vs Node + Python sidecar.
+3. **Boot-time safety** — what happens when the operator inevitably
+   flips `127.0.0.1:8787` to `0.0.0.0:8787` before authentication
+   lands in Phase 2.
+
+## Decision
+
+### 1. Topology — Compose-first, Helm deferred
+
+A single `docker-compose.yml` under `packages/core/deploy/` is the
+shipped artefact. Three services: `agent-config` (the Node image),
+`redis`, `postgres`. Three named volumes for runtime state, Postgres
+data, and the per-user `~/.event4u/agent-config/` mount.
+
+Helm / k8s manifests are **deferred** to a future v2 deployment
+roadmap. Compose covers the 5–50-person band; larger teams author
+their own chart using this Compose as the reference until v2 ships.
+
+### 2. Process shape — single-process Node
+
+The GUI server (`packages/core/installer/src/gui/server.ts`) is the
+only long-running process. The Python install supervisor is spawned
+per-install, not a sidecar. The Compose image stays Node-only to keep
+the budget under 600 MB compressed and the surface area minimal.
+
+If Phase 2+ needs a separate identity-broker process, it lands in a
+separate service in the same Compose; the agent-config container stays
+single-process.
+
+### 3. Host binding — `127.0.0.1` default, `0.0.0.0` opt-in with safety gate
+
+`startGuiServer` accepts `host` + `allowedHosts` options. CLI
+exposes `--host` and `--allowed-hosts`; container defaults
+`BIND_HOST=0.0.0.0` + `ALLOWED_HOSTS=localhost:8787,127.0.0.1:8787`.
+
+**Hard rule**: non-loopback bind without `allowedHosts` refuses to
+boot. Enforced at the CLI surface (`commands/gui.ts`) and at the
+server entry (`gui/server.ts`). This is the structural mitigation
+against operators flipping the host port mapping before Phase 2 SSO
+ships.
+
+### 4. Health endpoint — `/api/v1/health`, read-only, rate-limited
+
+CSRF-exempt, GET-only. Returns `status`, `version`, `pack_version`,
+`uptime_seconds`, `storage_mode`, `session_backend`, and
+`manifest_sha256`. No secrets, no auth state, no PII.
+
+Rate-limited to 1 request per second per remote IP via an in-memory
+token bucket. Wide margin over the docker-default 10 s healthcheck
+cadence; resilient to spoofed probes (the bucket map is bounded at
+1024 entries and self-prunes).
+
+### 5. Redis + Postgres in compose but unwired in Phase 1
+
+Both services ship in the Compose topology with healthchecks and named
+volumes, but the agent-config code does **not** read them in Phase 1:
+
+- `STORAGE_MODE=postgres` is documented but the implementation still
+  uses filesystem.
+- `SESSION_BACKEND=redis` is documented but the implementation still
+  uses in-memory state.
+
+Surfacing both connection strings in `/api/v1/health` lets operators
+verify connectivity *before* Phase 2 wires Postgres and Phase 3 wires
+Redis.
+
+### 6. No TLS in the container
+
+The reverse-proxy (nginx / Caddy / Traefik / ALB) owns TLS
+termination. The container speaks plain HTTP on the bound interface.
+Out-of-scope for this ADR; documented in `packages/core/deploy/README.md`.
+
+## Consequences
+
+**Positive**
+
+- Operators can `docker compose up` and reach a working wizard
+  without writing infrastructure.
+- The shape locks before Phases 2–5 add auth / policy / connectors —
+  those phases extend the topology without rewriting it.
+- `ALLOWED_HOSTS` gate eliminates the DNS-rebinding class of
+  vulnerability at the boot layer.
+
+**Negative**
+
+- Teams already on k8s need to translate Compose to their own
+  charts. Mitigated by the README pointing at the Compose as the
+  reference.
+- Postgres + Redis run unused in Phase 1, adding 60–80 MB RAM idle
+  to the deployment footprint. Mitigated by being able to remove
+  both services from the Compose if Phase 1 is the only phase the
+  operator wants.
+
+**Reversal cost** — low. Compose → Helm migration is mechanical once
+the v2 deployment roadmap kicks off; the agent-config image itself is
+orchestrator-agnostic.
+
+## Open questions (council-deferred)
+
+The accompanying council question file
+[`agents/tmp/council-question-deployment-shape.md`](../../agents/tmp/council-question-deployment-shape.md)
+has not yet been run (no provider keys configured). A maintainer with
+keys should run it and either ratify or supersede this ADR.
+
+## Cross-references
+
+- Phase 1 artefacts: [`packages/core/deploy/`](../../packages/core/deploy/)
+- Env contract: [`docs/deploy/env-vars.md`](../deploy/env-vars.md)
+- Installer architecture: [`ADR-016`](ADR-016-installer-architecture.md)
+- Global-only consumer scope: [`ADR-020`](ADR-020-global-only-consumer-scope.md) (orthogonal — local install model)

package/docs/decisions/INDEX.md

@@ -18,6 +18,13 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-012](ADR-012-typescript-cli-shell.md) | Typescript Cli Shell | accepted | 2026-05-19 | — |
 | [ADR-013](ADR-013-discovery-frontmatter-contract.md) | Discovery Frontmatter Contract | accepted | 2026-05-19 | — |
 | [ADR-014](ADR-014-gui-framework-choice.md) | Gui Framework Choice | accepted | 2026-05-20 | — |
+| [ADR-015](ADR-015-discovery-manifest-contract.md) | Discovery Manifest Contract | accepted | 2026-05-21 | — |
+| [ADR-016](ADR-016-installer-architecture.md) | Installer Architecture | accepted | 2026-05-21 | — |
+| [ADR-017](ADR-017-monorepo-physical-layout.md) | Monorepo Physical Layout | accepted | 2026-05-21 | — |
+| [ADR-018](ADR-018-trust-and-safety-layer.md) | Trust And Safety Layer | accepted | 2026-05-21 | — |
+| [ADR-019](ADR-019-router-json-dist-location.md) | Router Json Dist Location | accepted | 2026-05-23 | — |
+| [ADR-020](ADR-020-global-only-consumer-scope.md) | Global Only Consumer Scope | accepted | 2026-05-23 | — |
+| [ADR-021](ADR-021-deployment-shape.md) | Deployment Shape | accepted | 2026-05-24 | — |
 
 ## Unnumbered (legacy)