@event4u/agent-config 9.8.0 → 9.9.0

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

@@ -1,124 +0,0 @@
----
-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`](../../src/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.** Uncondensed rule sources referencing the path
-  (`telegraph-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`](../../src/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

@@ -1,213 +0,0 @@
----
-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`](../../src/scripts/lint_global_paths.py)
-- Payload schema: [`internal/schemas/wizard-apply-payload.schema.json`](../../internal/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.uncondensed/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).
-
-## Amendment — 2026-05-30 · user-content exception
-
-The original decision named `agents/overrides/` as "the single
-project-local exception". Field work on the global-only hook path
-(`road-to-self-update-and-global-hook-resolution`) clarified that a
-consumer also legitimately carries two **metadata** artefacts the
-tooling writes and maintains:
-
-- `agents/.event4u-bridge.yml` — the bridge marker (already mandated by
-  this ADR's Decision; restated here for completeness).
-- managed `agents/` entries in the project `.gitignore` — so runtime
-  artefacts under `agents/runtime/` stay untracked.
-
-These, together with `agents/overrides/`, are **user content +
-metadata pointers**, not distributed content. The global-only
-constraint applies to **distributed content** — skills, rules,
-commands, hooks, adapters, `.augment/`, `.claude/` — which is never
-written into a consumer repo. Consumer tooling (`agent-config
-refresh --project` and the wizard's apply step) may create and refresh
-the user-content / metadata surface without violating global-only.
-
-Forbidden, unchanged: writing any distributed content into the
-consumer repo outside `AGENT_CONFIG_DEV_MODE=1`.
-
-## Amendment — 2026-06-03 · settings-scope correction (ADR-049)
-
-The original Consequences bullet "one source of truth for `personal.*`,
-`agent_council.*`, and `personas:`" overstated the global surface and used a
-key name that never existed in code. [`ADR-049`](ADR-049-configuration-trust-boundary.md)
-(AI-council-converged, anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-06-03)
-corrects this:
-
-- The global surface is **secrets** (provider keys, already global) plus the
-  curated identity **whitelist** (`MERGEABLE_KEYS`) — not all of `personal.*`,
-  not council config, not personas.
-- **Council config is NOT on the `MERGEABLE_KEYS` whitelist.** _(Placement
-  amended: per [ADR-093](ADR-093-ai-council-config-user-global.md) →
-  [ADR-104](ADR-104-ai-council-config-global-only.md) the council config
-  is now **user-global** at `~/.event4u/agent-config/settings/.ai-council.yml`,
-  never project-local — but it is its own dedicated `.ai-council.yml`, not a
-  merged `.agent-settings.yml` key, so it stays off this whitelist.)_ Personas
-  stay project-local (version-controlled). The `MERGEABLE_KEYS` whitelist is a
-  **security trust boundary**: an untrusted project repo must not be able to
-  escalate arbitrary `personal.*` into user scope. Widening the whitelist now
-  requires a threat model.
-- The council config key name is **`ai_council`** (canonical), never
-  `agent_council`. It lives in the user-global `.ai-council.yml` (ADR-104),
-  not under `.agent-settings.yml`.
-
-This amendment narrows ADR-020's wording; the global-only **consumer install**
-decision (distributed content writes only to `~/.event4u/agent-config/`) is
-unchanged.
-
-## Amendment — 2026-07-13 · bridge marker retired
-
-The 2026-05-30 amendment restated `agents/.event4u-bridge.yml` as a mandated
-consumer metadata artefact. Field use showed the marker was a design mistake:
-it was **committed** to the shared project tree yet carried **no
-project-specific data**. `global_root` is always the well-known
-`~/.event4u/agent-config` (one global install per machine), and no code ever
-read the field — the loader, doctor, and conformance checks resolve the global
-root independently via `user_global_paths.event4u_root()`. Its only volatile
-content (`installed_at`, `installer_version`) meant every developer's install
-produced a diff and overwrote every other developer's committed copy. Scope
-(global) did not match location (per-project, committed).
-
-AI-council-converged (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-07-13,
-2-round debate): **Option B — eliminate the project marker; resolve the global
-root from the well-known path.** Changes:
-
-- The installer and `agent-config refresh --project` no longer write
-  `agents/.event4u-bridge.yml`; they **delete** any legacy committed copy. The
-  managed `.gitignore` block ignores it so a stale copy is never re-committed.
-- The global root is resolved from `~/.event4u/agent-config`
-  (`EVENT4U_CONFIG_HOME`-overridable), failing closed when absent.
-- Migration idempotency moved from the marker's presence to
-  `agents/.agent-state/install-mode.txt` (written on every install);
-  project-anchor detection keys on `agents/overrides/`.
-- The Windsurf / Cline / Gemini-CLI per-tool anchors stay (those tools cannot
-  read user scope) but now resolve the well-known path directly (no `bridge:`
-  back-pointer) and are **gitignored** — regenerated per-install, never shared.
-
-The single project-local agent surface is now **`agents/overrides/`** alone.
-This narrows the 2026-05-30 amendment; the global-only **consumer install**
-decision is unchanged. See [`consumer-bridge`](../contracts/consumer-bridge.md)
-(retired) for the reader/writer detail.
-
-## Alternatives considered
-
-- **Status quo (project default + global opt-in).** Keeps the drift
-  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 the curated cross-project identity keys
-  (`MERGEABLE_KEYS`) and provider secrets. _(Amended 2026-06-03 — the original
-  wording named `personal.*`, `agent_council.*`, and `personas:` as global; see
-  the settings-scope correction below and [`ADR-049`](ADR-049-configuration-trust-boundary.md): council config + personas stay project-local; the key is `ai_council`.)_
-- 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

@@ -1,153 +0,0 @@
----
-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/old/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 condensed 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/old/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/ADR-022-daily-workspace-decomposition.md

@@ -1,140 +0,0 @@
----
-adr: 022
-status: accepted
-date: 2026-05-24
-decision: daily-workspace-decomposition
-supersedes: —
-superseded_by: —
-phase: v3.x · employee-product-and-external-proof Phase 4
-type: forward-looking
----
-
-# ADR-022 — Daily workspace — decomposition
-
-## Status
-
-**Accepted** · 2026-05-24. Phase 4 Step 1 of
-[`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md).
-Records the council's verdict on the original "workspace shape"
-question — that the question was malformed — and replaces a single
-chrome decision with three sequenced sub-decisions.
-
-The numeric reservation note in
-[`ADR-021`](ADR-021-deployment-shape.md) (ADRs 022–025 held for the
-internal-AI-OS-deployment roadmap) is retired: that roadmap is
-archived ([`agents/roadmaps/archive/road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/archive/road-to-internal-ai-os-deployment.md))
-and the active strategy after release `3.1.1` is the
-employee-product / external-proof roadmap. ADR-022 claims the
-number under the new strategy.
-
-Companion artefacts:
-
-- Roadmap: [`agents/roadmaps/archive/road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md)
-- Council question: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
-- Council verdict: `agents/runtime/council/responses/daily-workspace-shape.json` (gitignored) <!-- council-ref-allowed: ADR decision trace -->
-- Predecessor ADRs: [`ADR-014`](ADR-014-gui-framework-choice.md) (installer chrome), [`ADR-016`](ADR-016-installer-architecture.md) (installer architecture), [`ADR-020`](ADR-020-global-only-consumer-scope.md) (consumer scope).
-
-## Context
-
-Phase 4 of the post-`3.1.1` roadmap proposes a persistent daily
-workspace — left rail (role + task launcher), centre pane (active
-conversation with the host agent), right rail (knowledge sources +
-explain-trace) — as the missing daily-use surface for non-developer
-roles (galabau owner, content creator, consultant).
-
-The original Step 1 framed the decision as a four-way chrome pick:
-extend the GUI installer · separate Electron/Tauri app · browser tab
-· TUI-first. The council was asked to choose one.
-
-## What the council said
-
-Both council members (claude-sonnet-4-5, gpt-4o) **rejected the
-question as malformed** after a two-round debate. The convergent
-verdict, in their own words:
-
-> *"The ADR masquerades as a UI choice when it is actually three
-> entangled, unsequenced decisions: (1) the protocol boundary to
-> host agents, (2) the v0 feature scope that validates 'non-developers
-> prefer this', (3) the chrome that wraps that scope."*
-> — Anthropic
-
-> *"Without a stable, documented protocol between the workspace and
-> host agents, the ADR's proposition lacks substance and could be
-> shelved until a reliable, documented, and tested protocol is
-> defined."* — OpenAI
-
-The load-bearing critique is that the workspace contract requires
-two capabilities the host agents (Claude Code, Augment, Cursor,
-Cline, Windsurf) have not been confirmed to expose:
-
-1. A stable RPC / IPC surface for **launching a conversation with a
-   pre-filled prompt + pre-selected skill** (not just CLI flags that
-   drift per Hyrum's Law).
-2. Structured **explain-trace emission** (not "parse stdout and hope").
-
-Until both are proven for at least one host agent, no chrome option
-can be implemented — each inherits the same fatal coupling risk.
-
-## Decision
-
-Split Phase 4 Step 1 into three sequential sub-decisions, each its
-own ADR:
-
-1. **ADR-023 — Host-agent protocol contract** *(blocking)*. Inventory
-   the surface each named host agent exposes today, name the
-   fallback for missing surfaces, write `docs/contracts/host-agent-protocol.md`.
-   Status today: **drafted, not started**.
-2. **ADR-024 — Workspace v0 feature floor** *(depends on ADR-023)*.
-   Define the minimum viable shell that recruit-session participants
-   can evaluate. Pare back from "left rail + centre pane + right rail"
-   to whatever the protocol from ADR-023 can actually drive end-to-end.
-3. **ADR-025 — Workspace chrome** *(depends on ADR-024)*. The original
-   four-way pick (installer-extension · Electron/Tauri · browser tab ·
-   TUI), narrowed by what ADR-024 needs and what ADR-023 makes
-   feasible.
-
-The roadmap is updated accordingly: Phase 4 grows two new gating
-steps (ADR-023 + ADR-024) ahead of the chrome decision. The
-"≤ 6 weeks for one engineer" budget assumption from the original
-roadmap is preserved as a working figure — both council members
-flagged it as ambitious. ADR-024 will tighten it.
-
-## Consequences
-
-**Positive**
-
-- The blocking risk (host-agent protocol feasibility) is surfaced
-  as its own ADR with its own go/no-go gate, not buried under a
-  chrome debate.
-- Phase 4 cannot accidentally ship a chrome built on an unproven
-  integration substrate.
-- Recruit sessions (Phase 1) get a clearer signal of *what* to
-  validate: "does the v0 feature floor solve the daily-use gap?"
-  rather than "do you prefer this UI?"
-
-**Negative**
-
-- Phase 4 ships two additional ADRs before any code lands. Adds
-  governance overhead; the autonomous-execution rule narrows the
-  ask-tax but doesn't remove it.
-- The chrome decision (ADR-025) is deferred at least one council
-  round behind ADR-023 + ADR-024.
-
-**Reversal cost** — low. If ADR-023 proves the protocol is trivially
-stable, ADR-024 can collapse to a one-line "we re-adopt the
-original v1 scope" decision and ADR-025 proceeds against the
-original four-way pick.
-
-## Open questions (next-ADR-deferred)
-
-- Whether the host-agent protocol investigation should be
-  council-gated again or treated as a research artefact (ADR-023
-  will say).
-- Whether "host agent" remains plural or narrows to one supported
-  host for v0 (ADR-024 will say).
-
-## Cross-references
-
-- Council question file: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
-- Role identity scaffolds (Phase 3 output): [`agents/roles/`](../../agents/roles/)
-- Knowledge-ingestion contract (Phase 2 input): [`docs/contracts/local-knowledge-ingestion.md`](../contracts/local-knowledge-ingestion.md)