@event4u/agent-config 5.10.1 → 6.0.0

package/docs/decisions/ADR-049-configuration-trust-boundary.md

@@ -0,0 +1,114 @@
+---
+adr: 049
+status: accepted
+date: 2026-06-03
+decision: configuration-trust-boundary
+supersedes: —
+superseded_by: —
+phase: v6.0.0 · settings-scope hardening
+type: decision
+---
+
+# ADR-049 — Configuration trust boundary: the user-global whitelist is a security boundary
+
+## Status
+
+**Accepted** · 2026-06-03. Locks the AI-council convergence
+(anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode + peer-review,
+2026-06-03) on where the source of truth for personal preferences and AI-council
+configuration lives. Refines [`ADR-020`](ADR-020-global-only-consumer-scope.md)
+(global-only consumer scope) and sits alongside
+[`ADR-038`](ADR-038-canonical-settings-path.md) (canonical project settings
+path) and the resolver cascade in `scripts/_lib/agent_settings.py`.
+
+## Context
+
+[`ADR-020`](ADR-020-global-only-consumer-scope.md) framed its consequences as
+"one source of truth for `personal.*`, `agent_council.*`, and `personas:`",
+which read as a mandate to push personal preferences, council configuration, and
+personas into the **user-global** layer (`~/.event4u/agent-config/`). The
+implementation never did this: the loader's user-global layer is **whitelist-
+filtered** to a small curated set (`MERGEABLE_KEYS` = `name`, `ide`,
+`rule_loading_tier`, `memory.cadence`, `personal.bot_icon`, `personal.autonomy`,
+`telegraph.speak_scope`); everything else in a user-global file is silently
+ignored. `ai_council` is not on the whitelist, and council configuration lives
+project-local in `agents/settings/.ai-council.yml` (per
+[`ai-council-config`](../contracts/ai-council-config.md), the Phase-0 single
+source of truth).
+
+The maintainer questioned whether that project-local placement is a bug. The AI
+council was asked to decide and **converged** that it is **not** a bug — the
+whitelist is a deliberate **security trust boundary**, and ADR-020's
+"everything global" framing was aspirational overreach the implementation
+correctly rejected. The decisive argument is the **untrusted-project escalation
+test**: if `ai_council` or arbitrary `personal.*` keys cascaded from any layer a
+project repo controls, a cloned repo could set `personal.autonomy: full` or point
+a provider key at an attacker endpoint and have it silently inherited into the
+user's scope. Only a whitelist that filters what a project may escalate survives
+that test. Two further arguments hold even under this package's team-internal,
+all-repos-trusted reality: workflow configuration (council member selection,
+personas, rule tier) **belongs in version control**, and onboarding stays clean
+(`clone → install → correct config`) without out-of-band global state.
+
+## Decision
+
+1. **The `MERGEABLE_KEYS` whitelist is a security trust boundary**, not a feature
+   gate. Project-controlled layers (repo-root, intermediate, CWD, and the
+   user-global file *when populated from an untrusted source*) may only escalate
+   the curated identity keys on the whitelist into the merged settings. Every
+   other key resolves **project-local**.
+
+2. **Council configuration and personas stay project-local.** The canonical home
+   for council config is `agents/settings/.ai-council.yml`
+   ([`ai-council-config`](../contracts/ai-council-config.md)); personas live in
+   the project surface. Neither is a user-global concern.
+
+3. **Only secrets and the curated identity whitelist are global.** Provider API
+   keys already live global in `~/.event4u/agent-config/<provider>.key` (0600);
+   the whitelist carries cross-project user identity (`name`, `ide`, autonomy,
+   bot icon, rule tier, memory cadence, telegraph scope). This is the complete
+   global surface.
+
+4. **Expanding the whitelist requires a threat model, not just product
+   rationale.** Any future PR that adds a key to `MERGEABLE_KEYS` must state, in
+   an ADR, why an untrusted project escalating that key into user scope is safe.
+
+## Consequences
+
+- **Positive.** The untrusted-project escalation hole is closed by construction.
+  Council config and personas are diffable and reviewable in git. The
+  global surface stays minimal and auditable (`~/.event4u/agent-config/`).
+- **Naming.** ADR-020's `agent_council.*` is corrected to `ai_council` and
+  dropped from the "global" list — see the ADR-020 amendment. `ai_council` is the
+  single canonical key; the standalone `.ai-council.yml` file is its canonical
+  home; the `ai_council:` block in `.agent-settings.yml` is the Phase-0
+  one-line breadcrumb only.
+- **No code change required.** The loader already implements this boundary; this
+  ADR documents it as load-bearing so a future contributor does not "fix" the
+  whitelist by widening it without a threat pass.
+- **Dev-mode is unaffected.** `AGENT_CONFIG_DEV_MODE=1` treats the package repo
+  as its own project surface; project-local council/persona files there are the
+  test fixtures, not a workaround — see the ADR-038 amendment.
+
+## Alternatives considered
+
+- **Make `ai_council` + `personal.*` global (implement ADR-020 literally).**
+  Rejected by the council: reintroduces the untrusted-project escalation hole and
+  moves version-controllable workflow config out of git. Even under a fully
+  trusted team-internal scope the version-control and onboarding arguments stand.
+- **Split identity vs workflow into two new files
+  (`.agent-identity.yml` / `.agent-workflow.yml`).** Rejected: the whitelist
+  already is the boundary; new filenames add migration debt and a "which file do
+  I edit?" cognitive load without closing any gap the whitelist leaves open.
+- **Status quo, undocumented.** Rejected: the gap between ADR-020's wording and
+  the implementation is exactly what triggered the "is this a bug?" question; an
+  undocumented boundary invites a future well-meaning widening.
+
+## References
+
+- AI-council convergence: anthropic/claude-sonnet-4-5 + openai/gpt-4o, design
+  mode + peer-review, 2026-06-03 (hybrid / security-bounded model).
+- [`ADR-020`](ADR-020-global-only-consumer-scope.md) — global-only consumer scope; this ADR refines its "global source of truth" wording.
+- [`ADR-038`](ADR-038-canonical-settings-path.md) — canonical project settings path; dev-mode amendment added there.
+- [`ai-council-config`](../contracts/ai-council-config.md) — `.ai-council.yml` as the Phase-0 single source of truth for council config.
+- `scripts/_lib/agent_settings.py` — `MERGEABLE_KEYS` whitelist and the resolver cascade this ADR locks.

package/docs/decisions/ADR-050-workspace-vs-package-root-boundary.md

@@ -0,0 +1,121 @@
+---
+adr: 050
+status: accepted
+date: 2026-06-05
+decision: workspace-vs-package-root-boundary
+supersedes: —
+superseded_by: —
+phase: v6.0.0 · D structural restructure · Step 16 closure
+type: structural
+---
+
+# ADR-050 — Workspace-vs-package root boundary (Step 16 closure)
+
+## Status
+
+**Accepted** · 2026-06-05. Closes Step 16 of
+[`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md).
+**Refines** [`ADR-045`](ADR-045-src-source-layout-and-profiles-as-views.md): ADR-045's
+profiles-as-views and hard-break decisions stand unchanged; this ADR refines
+ADR-045's stated *root inventory* against the executed reality. Routed through the
+AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode, 2026-06-05;
+converged 2-round) which both members signed off on the trust-boundary framing.
+
+## Context
+
+ADR-045 specified an end-state where `src/` is "the whole package, structured" and
+"root keeps only tooling/agent-host essentials + `src/` + `tests/` + `taskfiles/`",
+with `src/app/` holding the TS runtime and `src/internal/` holding maintainer infra.
+Step 16's remaining work (`internal/`, `hooks/`, the maintainer `agents/` workspace)
+forced a re-examination, and three facts emerged that ADR-045's diagram did not
+account for:
+
+1. **The repo is a dual-artifact workspace, not a monolith.** It ships an npm
+   package (`src/`) *and* hosts a maintainer workspace (CI, evals, benchmarks,
+   council runtime, roadmaps, settings). These have different lifecycles, trust
+   boundaries, and consumers. Forcing workspace tooling under `src/` implies it is
+   a package internal when it is a workspace peer of `.github/`.
+2. **`hooks/hooks.json` is pinned to the plugin root by an external convention.**
+   Claude Code plugins auto-discover hooks at `<plugin-root>/hooks/hooks.json`
+   (`condense.generate_plugin_hooks()` writes `PROJECT_ROOT/hooks/hooks.json`;
+   `.claude-plugin/marketplace.json` ships it). Moving it under `src/` silently
+   breaks plugin hook discovery in every marketplace-install consumer — a coupling
+   invisible to static grep (the council rated `hooks/` "1 ref, trivial" without it).
+3. **`src/app/` was never created; flat `src/{cli,server,install,shared,ui}` is the
+   executed reality** and is *more* correct for a dual-artifact repo than the false
+   `src/app/` module boundary the diagram assumed.
+
+The council's converged verdict: the value of Step 16 was structural clarity for the
+*package*; that is achieved. The remaining dirs have design blockers, not
+implementation laziness, and the honest disposition is a documented trust boundary
+plus deferral — not contorting workspace tooling to fit a diagram drawn for the
+wrong repo shape.
+
+## Decision
+
+1. **Two root tiers, by trust boundary.**
+   - **Package source — `src/`** (shipped via npm `files[]`): `app`-equivalent
+     entrypoints (`cli/`, `server/`, `install/`, `shared/`, `ui/` — kept flat under
+     `src/`, *not* under a `src/app/` wrapper), `domains/`, `skills/`, `rules/`,
+     `flows/`, `profiles/`, `config/`, `templates/`, `scripts/`, `schemas/`.
+   - **Workspace tooling + external-convention anchors — root** (not shipped as
+     package source): `internal/`, `agents/`, `.github/`, `taskfiles/`, `docs/`,
+     `hooks/`.
+
+2. **Kept-at-root exception set (final for 6.0.0), with rationale per dir.**
+
+   | Dir | Class | Why it stays at root |
+   |---|---|---|
+   | `docs/` | external convention | GitHub renders `docs/`, npm `files[]`, ~386 cross-refs + 5 generator/verifier scripts hardcode it (decided 2026-06-05, pre-this-ADR). |
+   | `hooks/` | external convention | Claude Code plugin spec auto-discovers `<plugin-root>/hooks/hooks.json`; moving it breaks consumer hook discovery. |
+   | `internal/` | workspace tooling | `bench/ docker/ evals/ schemas/ workers/` — never shipped; 117 repo-local refs; a workspace peer of `.github/`, not a package internal. |
+   | `agents/` | workspace tooling + namespace | Maintainer roadmaps/settings/runtime; 443 refs; `agents/settings/.agent-settings.yml` is read at runtime by `_lib/agent_settings.py` (self-referential move hazard); collides conceptually with the consumer-facing `agents/` convention the package ships. **Deferred — see below.** |
+
+3. **`src/app/` is not created.** Flat `src/{cli,server,install,shared,ui}` is the
+   accepted layout. ADR-045's `src/app/` line is refined away as a false abstraction
+   for a dual-artifact repo.
+
+4. **Deferred to a follow-up structural roadmap** (not 6.1 behavioral consolidation):
+   - **`packages/` dual-tree collapse.** 308 tracked files still coexist with
+     `src/domains/` and remain in CI (`packages/core/installer/**`,
+     `packages/<PACK>/.agent-src.uncondensed/`). Step 10 ("move remaining packs")
+     copied command surfaces but did not remove `packages/`. Completing the collapse
+     is its own roadmap — it is bigger than Step 16 and touches the install/CI
+     contract.
+   - **`agents/` namespace + runtime-coupling resolution.** Resolve the
+     maintainer-vs-consumer `agents/` collision and the settings-loader
+     self-reference before any move; requires a pre-flight path test, not a
+     bundled file move.
+
+## Consequences
+
+- **Positive.** Step 16 closes honestly: package source is structured under `src/`;
+  root carries only essentials + the two tiers above, each with a stated reason.
+- **Positive.** No high-blast-radius move (443-ref `agents/`, 117-ref `internal/`,
+  plugin-pinned `hooks/`) is executed in an autonomous run, avoiding the kill-switch
+  the roadmap warned about.
+- **Negative / accepted.** The root is not reduced to the minimal inventory ADR-045
+  diagrammed; the dual-artifact reality means workspace tooling stays at root by
+  design. The acceptance criteria are amended to record this (see the roadmap).
+- **Negative / accepted.** `packages/` still exists; the "root contains only
+  essentials" goal is met *modulo* the documented dual-tree pending its own roadmap.
+
+## Alternatives considered
+
+- **Move `hooks/` under `src/` (the council's first-pass verdict).** Rejected on a
+  fact the council lacked: the Claude plugin spec pins `hooks/hooks.json` to the
+  plugin root. Moving it breaks consumer hook auto-discovery.
+- **Move `internal/` + `agents/` under `src/` to satisfy ADR-045's diagram.**
+  Rejected: violates the workspace-vs-package trust boundary and (for `agents/`)
+  risks a self-referential runtime break; pure churn with negative value.
+- **Keep Step 16 open until every dir moves.** Rejected: the remaining moves have
+  design blockers, not effort gaps; closing with a documented boundary + a scoped
+  follow-up is more honest than an open-ended step.
+
+## References
+
+- [`ADR-045`](ADR-045-src-source-layout-and-profiles-as-views.md) — `src/` source
+  layout + profiles-as-views (refined here on the root inventory only).
+- [`ADR-028`](ADR-028-root-layout.md) — earlier root-layout verdict (superseded by ADR-045).
+- [`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md) — Step 16 + amended acceptance criteria.
+- AI council, design mode, 2026-06-05 (anthropic/claude-sonnet-4-5 + openai/gpt-4o) — converged on the trust-boundary closure.

package/docs/decisions/ADR-051-uncondensed-source-container-relocation.md

@@ -0,0 +1,114 @@
+---
+adr: 051
+status: accepted
+date: 2026-06-05
+decision: uncondensed-source-container-relocation
+supersedes: —
+superseded_by: —
+phase: v6.0.x · workspace structural cleanup · Phase 1 sub-phase 1a
+type: structural
+---
+
+# ADR-051 — Relocate the uncondensed source container to `src/agent-src/`
+
+## Status
+
+**Accepted** · 2026-06-05. Lands sub-phase **1a** of
+[`road-to-6.0.x-workspace-structural-cleanup`](../../agents/roadmaps/archive/road-to-6.0.x-workspace-structural-cleanup.md).
+**Builds on** [`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) (commands →
+`src/domains/`) and [`ADR-045`](ADR-045-src-source-layout-and-profiles-as-views.md)
+(the flat `src/skills` + `src/rules` library). Routed through the AI council
+(`claude-sonnet-4-5` + `gpt-4o`, 2026-06-05).
+
+## Context
+
+The 6.0.0-D restructure moved **skills** → `src/skills/`, **rules** →
+`src/rules/`, and **commands** → `src/domains/<pack>/<verb>/command.md`, but
+left every other uncondensed artefact category (contexts, personas, templates,
+profiles, presets, user-types, ghostwriter, scripts, packs — ~221 files) under
+`packages/core/.agent-src.uncondensed/`. That directory was therefore **still
+the live uncondensed source** for those categories — `condense.py` (via
+`_lib/agent_src.py::_root_specs()` / `artefact_roots()`) walked
+`packages/*/.agent-src.uncondensed/` to find it. It was not a dead duplicate.
+
+Collapsing `packages/` (the roadmap's goal) thus requires first giving those
+~221 source files a `src/` home and repointing the generator — a real
+source-of-truth move, not a delete.
+
+## Decision
+
+Relocate the remaining uncondensed categories into a single container
+**`src/agent-src/`** (prefix `""`, original per-category subdir names), and
+register it in `_root_specs()` (leaf view) and `artefact_roots()` (container
+view, ordered **before** `src/` so the three categories that also exist under
+`src/` as a *different* concern — `src/templates` = workspace TS templates,
+`src/profiles` = runtime profile-views, `src/scripts` = Python tooling — resolve
+to the uncondensed source first, exactly the precedence
+`packages/core/.agent-src.uncondensed/` held).
+
+A **collision guard** in `_root_specs()` now raises if two roots emit the same
+non-empty logical prefix (silent overwrite of one category's condensed output
+by another's was the council's named #1 failure mode).
+
+### Council convergence and the execution refinement
+
+The council converged on **per-category `src/<category>` roots** with logical
+prefixes (Option A), mirroring `src/skills`→`skills/`. Execution refined that
+to the **single `src/agent-src/` container** because per-category physical
+names collide with the three pre-existing `src/` dirs above, which would break
+six `artefact_roots()`+category-append consumers (the profile loader and five
+test conftests resolving `root / "templates" / "scripts"`, `root / "scripts"`,
+`root / "profiles"`). The container delivers the council's stated #1 priority —
+no generated-tree corruption, no collision — with **zero consumer edits**,
+keeps the source under `src/` (the council rejected a root-level
+`.agent-src.uncondensed/` for reverting the at-`src/` direction), and preserves
+logical identity exactly.
+
+## Consequences
+
+- The condensed `.agent-src/` output is **byte-identical** before/after the
+  move (the decisive correctness gate; verified by snapshot diff). Consumers
+  see no change.
+- `generate_pack_manifests` collects the **core** pack's artefacts from both
+  `packages/core/.agent-src.uncondensed/` and `src/agent-src/`, so the core
+  pack manifest stays byte-stable — the move is metadata-neutral.
+- Gate path-integrity (`check_gate_paths`) now asserts targets resolve under
+  the **source tree** (`src/` / `packages/`) rather than `packages/core/`; the
+  four gates it guards (`lint_agents_md`, `audit_command_surface`,
+  `audit_initial_context`, `inventory_abstraction_budget`) were repointed to
+  the new homes. `audit_command_surface` was additionally repointed from its
+  pre-existing Step-10 silent-no-op (it read the evals-only `packages` commands
+  dir) onto the real `src/domains/` command surface — now audits 161 commands.
+
+## What this ADR does NOT do — the deferred blocker
+
+Sub-phase 1a relocates the **artefact source only**. It does **not** remove
+`packages/`, because `packages/` also hosts a **live pack-home / manifest
+layer**: `pack.yaml` + `README.md` (+ `FIRST_WIN.md`) for 11 capability packs
+(finance, gtm, founder-strategy, ops-people, and the language packs) that are
+**not** in `src/domains/`, plus `packages/core/installer/` (superseded by
+`src/cli`+`src/install`+`src/server`), `packages/core/deploy/`, and
+`packages/cloud/telemetry-worker/`. These are not mirrored elsewhere; deleting
+them would violate the roadmap's acceptance criterion ("no skill/rule/command
+deleted beyond duplicates proven already-mirrored").
+
+**Where the 13 pack homes + installer + deploy + cloud worker migrate is an
+open design decision** (e.g. `src/domains/<pack>/` homes vs a dedicated
+`src/packs/` home; the semantics of capability-packs-as-domains) and is routed
+to a follow-up council session + its own staged PR — consistent with the
+roadmap's Goal that Phase 1 and Phase 2 ship as separate, never-bundled PRs.
+
+## Alternatives considered
+
+- **Per-category `src/<category>` roots (council Option A)** — rejected at
+  execution for the six-consumer collision breakage above.
+- **Root-level `.agent-src.uncondensed/`** — rejected by the council for
+  reverting the at-`src/` flat-library direction.
+- **Add `packs:` frontmatter to ~180 shared artefacts** — rejected as invasive
+  and orthogonal; the container preserves attribution without touching content.
+
+## References
+
+- [`road-to-6.0.x-workspace-structural-cleanup`](../../agents/roadmaps/archive/road-to-6.0.x-workspace-structural-cleanup.md)
+- [`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) · [`ADR-045`](ADR-045-src-source-layout-and-profiles-as-views.md) · [`ADR-050`](ADR-050-workspace-vs-package-root-boundary.md)
+- `src/scripts/_lib/agent_src.py` — `_root_specs()`, `artefact_roots()`, collision guard.

package/docs/decisions/ADR-052-packages-removal-and-pack-home-migration.md

@@ -0,0 +1,86 @@
+---
+adr: 052
+status: accepted
+date: 2026-06-05
+decision: packages-removal-and-pack-home-migration
+supersedes: —
+superseded_by: —
+phase: v6.0.x · workspace structural cleanup · Phase 1 sub-phase 1b
+type: structural
+---
+
+# ADR-052 — Remove `packages/`; migrate pack homes to `src/packs/` + ops dirs to `deploy/`
+
+## Status
+
+**Accepted** · 2026-06-05. Completes Phase 1 (Steps 2–3) of
+[`road-to-6.0.x-workspace-structural-cleanup`](../../agents/roadmaps/archive/road-to-6.0.x-workspace-structural-cleanup.md);
+builds on [`ADR-051`](ADR-051-uncondensed-source-container-relocation.md) (sub-phase 1a) and executes
+[`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md)'s collapse. Routed through the AI council
+(`claude-sonnet-4-5` + `gpt-4o`, 2026-06-05, two rounds incl. a tie-break).
+
+## Context
+
+After 1a relocated the uncondensed artefact source to `src/agent-src/`, the remaining `packages/`
+content was **not** dead duplication:
+
+- **11 manifest-only capability packs** (`pack-finance-*`, `pack-gtm-sales`, `pack-founder-strategy`,
+  `pack-ops-people`, `pack-{php,python,react,symfony,typescript,nextjs}`) — `pack.yaml` + `README.md`
+  (+ some `FIRST_WIN.md`); 0 commands; artefacts are flat `src/skills`/`src/rules` grouped by
+  frontmatter `packs:`. (Their old manifests were silently **empty** — `artefact_count: 0` — because
+  the generator rglob'd a non-existent `.agent-src.uncondensed/` under each.)
+- **`packages/core/`** — pack manifest + `installer/` + `deploy/`.
+- **`packages/cloud/`** — a vestigial `pack.yaml`/`README` + a Cloudflare `telemetry-worker/`.
+
+## Decision
+
+| Item | Destination | Mode |
+|---|---|---|
+| 11 capability packs | `src/packs/<id>/` | `flat` (frontmatter `packs:`) |
+| `core` pack | `src/packs/core/` manifest; artefacts collected from the full `src/agent-src/` container | `core` |
+| `installer/python/` workspace modules (8 `.py`) | `src/cli/python/` | runtime |
+| `installer/` (TS entry, package.json) | **deleted** (superseded by `src/cli`+`src/install`+`src/server`) | — |
+| `deploy/` (Dockerfile, compose) | root `deploy/` | build artefact |
+| `cloud/telemetry-worker/` | root `deploy/telemetry-worker/` | deployable |
+| `cloud` pack registration | **dropped** (a deployable is not an installable pack) | — |
+
+`generate_pack_manifests._pack_homes()` now resolves homes from `src/packs/` + `src/domains/`
+(+ legacy `packages/` for back-compat), with a 3-way collection mode (`core` / `flat` / `physical`).
+The pack subsystem (`validate_pack_yaml`, `lint_pack_dependencies`, `lint_pack_first_win`,
+`check_release_pr_shape`, `release.py`) was repointed off `packages/*`.
+
+### Council convergence and the execution refinements
+
+Round 1 converged on `src/packs/<id>/` for the 11 packs (Option B) — **not** `src/domains/`, to avoid
+the *activation-gate inversion* (a command-less domain home would let a downstream installer that
+greps for `command.md` silently skip the pack). The tie-break round resolved **core → `src/agent-src/`**
+(home == artefact root). Execution **refined core to `src/packs/core/`** instead, because
+`src/agent-src/` is a **condense source root** (prefix `""`) — a `pack.yaml`/`README.md` placed there
+would leak into the condensed `.agent-src/` output (the README would overwrite the real source README
+once `packages/` was gone). The silent-data-loss risk that drove the council to `src/agent-src/` does
+**not** apply: `_collect_core()` rglobs the *entire* `src/agent-src/` container (no whitelist), so a
+future category is auto-included.
+
+## Consequences
+
+- `packages/` no longer exists at repo root; `package.json files:` never shipped it, so the published
+  package is unaffected.
+- Condensed `.agent-src/` output stays **byte-identical** (1a's snapshot guard, re-verified).
+- The 11 capability-pack manifests now list their **real** artefacts (previously empty) — a correction,
+  surfaced by the per-pack manifest snapshot guard, not silent drift.
+- The `installer/python/` workspace modules (`workspace_*`, `knowledge_ingest`) — live runtime + test
+  dependencies, **not** part of the superseded TS installer — were preserved at `src/cli/python/`.
+
+## Alternatives considered
+
+- **Pack homes under `src/domains/`** — rejected (activation-gate inversion).
+- **core manifest at `src/agent-src/`** (tie-break winner) — rejected at execution (condense-source
+  pollution).
+- **Keeping `packages/` as a thin shim** — rejected; the roadmap goal is its removal, and nothing in
+  `files:` or the build depends on it.
+
+## References
+
+- [`road-to-6.0.x-workspace-structural-cleanup`](../../agents/roadmaps/archive/road-to-6.0.x-workspace-structural-cleanup.md)
+- [`ADR-051`](ADR-051-uncondensed-source-container-relocation.md) · [`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md)
+- `src/scripts/generate_pack_manifests.py` — `_pack_homes()`, `_collect_core()`.

package/docs/decisions/ADR-053-agents-namespace-dual-role-resolution.md

@@ -0,0 +1,132 @@
+---
+adr: 053
+status: accepted
+date: 2026-06-05
+decision: agents-namespace-dual-role-resolution
+supersedes: —
+superseded_by: —
+phase: v6.0.x · workspace structural cleanup · Phase 2 (Step 4 design gate)
+type: structural
+---
+
+# ADR-053 — The maintainer `agents/` namespace is the dogfooded consumer convention (collision resolution)
+
+## Status
+
+**Accepted** · 2026-06-05. Resolves the deferred Step-4 design gate of the
+6.0.x workspace-structural-cleanup roadmap, closing the `agents/`-namespace
+remainder that [`ADR-050`](ADR-050-workspace-vs-package-root-boundary.md)
+explicitly deferred.
+Routed through the AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o,
+design mode, 2-round debate, 2026-06-05). Both members converged independently
+on Option B in round 1; the round-2 adversarial pass steel-manned Option A and is
+recorded under *Alternatives considered* with the reason it does not hold.
+
+## Context
+
+ADR-050 kept the maintainer `agents/` workspace at repo root ("workspace tooling
++ namespace") and deferred two coupled questions to this roadmap:
+
+1. Resolve the **maintainer-vs-consumer `agents/` collision** — the directory
+   `agents/` in this repo is simultaneously the maintainer workspace AND the
+   consumer-facing convention the package ships.
+2. Resolve the **settings-loader self-reference** — `agents/settings/.agent-settings.yml`
+   is read at runtime by `src/scripts/_lib/agent_settings.py`, so a naive move of
+   the workspace could brick the loader mid-move.
+
+Three facts, verified against the codebase on 2026-06-05, define the decision space:
+
+- **`agents/` is one name with two roles by design.** This repo's `agents/`
+  (`roadmaps/`, `settings/`, `runtime/`, `decisions/`) is a *compliant instance*
+  of the `agents/` tree the package installs into consumer projects
+  (`agents/settings/`, `agents/overrides/`, `agents/roadmaps/`, `.event4u-bridge.yml`).
+  The maintainer workspace and the shipped convention are the same directory name
+  because the package dogfoods its own convention.
+- **The loader is coupled to the convention, not to a maintainer-special path.**
+  `agent_settings.py` keys on `LOCAL_PROJECT_SUBDIR = ("agents", "settings")`,
+  anchors on a directory named `agents/` carrying any of `_AGENTS_DIR_MARKERS`
+  (`roadmaps/`, `settings/.ai-council.yml`, `roadmaps-progress.md`,
+  `.event4u-bridge.yml`), and defaults `MODULES_DEFAULTS["agent_folder"] = "agents"`.
+  These are *convention* identifiers — the same strings a consumer project carries.
+- **Reference scale.** 1106 tracked files outside `agents/` and `internal/`
+  reference `agents/` (~511 `src/`, ~260 generated `.agent-src/`, ~220 `docs/`,
+  ~93 `tests/`). The majority describe the *consumer convention* (templates,
+  generators, skills, docs), not this repo's workspace.
+
+## Decision
+
+1. **Keep `agents/` at repo root. The "collision" is conceptual, not structural,
+   and is resolved by naming the dual role — not by moving the directory.** The
+   maintainer workspace *is* a dogfooded instance of the shipped `agents/`
+   convention; that overlap is intentional and is the forcing function that keeps
+   the convention usable. There is nothing to physically separate.
+
+2. **Add an explicit, reviewable marker.** A tracked
+   [`agents/.maintainer-workspace.md`](../../agents/.maintainer-workspace.md)
+   names the dual role at the directory itself, so a reviewer encountering the
+   overlap sees the intent in place rather than inferring a mistake.
+
+3. **The loader needs no structural change; its relocation-safety is locked by a
+   pre-flight test.** `agent_settings.py` already resolves the project root from
+   `AGENT_CONFIG_PROJECT_ROOT` / `--root` / an anchor walk / `.git`, and reads
+   settings via a cascade. A regression test
+   (`tests/test_agent_settings_relocation_resilience.py`) proves the loader
+   resolves a settings file at an arbitrary relocated root with the default
+   location absent, and degrades to defaults (never bricks) when the file is gone.
+
+4. **No mass ref repoint.** Because the directory name does not change, the ~1106
+   `agents/` references stay valid. Step 6's "execute the disposition" reduces to
+   landing the marker + ADR + loader test; the full path-audit surface is
+   unchanged by this decision.
+
+## Consequences
+
+- **Positive.** The collision is resolved at the lowest defensible blast radius:
+  zero ref churn, zero loader fork, dogfooding integrity preserved, and the dual
+  role is now explicit rather than tribal knowledge.
+- **Positive.** Consistent with ADR-050 (which already placed `agents/` at root)
+  and with the package's "dogfood the convention" posture.
+- **Negative / accepted.** A reviewer must understand the dual role; the marker
+  file and this ADR are the mitigation. New contributors are pointed at both.
+- **Negative / accepted.** The maintainer workspace can never diverge in *name*
+  from the consumer convention without forking the loader — which is the point:
+  the constraint keeps the shipped convention honest.
+
+## Alternatives considered
+
+- **Option A — rename the maintainer workspace (`agents/` → `.agents/` /
+  `internal/agents/`).** Steel-manned in the round-2 debate as breaking a
+  "circular dogfooding" dependency and claimed to need only ~47 maintainer-tooling
+  ref changes with "no loader change". **Rejected** because the claim is
+  self-refuting: `agents/settings/` *is* the convention path the loader hardcodes
+  (`LOCAL_PROJECT_SUBDIR`), so moving the maintainer settings either (a) requires
+  dual-path loader logic ("maintainer ⇒ `.agents/`, consumer ⇒ `agents/`") — which
+  both members rejected in round 1 as strictly worse — or (b) leaves
+  `agents/settings/` in place, which does not resolve the collision it set out to
+  fix. Renaming a directory does not resolve a clash between that directory and a
+  *shipped convention of the same name*.
+- **Option C — relocate `agents/` contents to typed root homes
+  (`roadmaps/`, `settings/`, `runtime/`).** Rejected: removes the `agents/`
+  umbrella, breaks the loader anchor and the dogfooded convention, and forces a
+  doc/template rewrite for the largest blast radius of the three.
+
+## Inversion check
+
+This verdict flips only if external consumer projects are shown to organize their
+`agents/` tree identically to this maintainer workspace (project ADRs in
+`agents/decisions/`, runtime logs in `agents/runtime/`) — which would make the
+dual role convention-native rather than maintainer-specific and *strengthen* B —
+**or** if a consumer integration is shown to require a maintainer-distinct
+directory name, which would reopen A. Absent either, B stands.
+
+## References
+
+- [`ADR-050`](ADR-050-workspace-vs-package-root-boundary.md) — kept `agents/` at
+  root and deferred this collision + loader self-reference to here.
+- [`ADR-020`](ADR-020-global-only-consumer-scope.md) — the
+  `.event4u-bridge.yml` consumer anchor that the loader keys on.
+- [`agents/.maintainer-workspace.md`](../../agents/.maintainer-workspace.md) — the
+  explicit dual-role marker landed by this decision.
+- AI council, design mode, 2-round debate, 2026-06-05 (anthropic/claude-sonnet-4-5
+  + openai/gpt-4o) — round-1 convergence on Option B; round-2 adversarial pass
+  recorded above.