@event4u/agent-config 5.10.1 → 6.1.0

package/docs/decisions/ADR-047-framework-neutral-stack-adaptive-commands.md

@@ -0,0 +1,94 @@
+---
+adr: 047
+status: accepted
+date: 2026-06-03
+decision: framework-neutral-stack-adaptive-commands
+supersedes: —
+superseded_by: —
+phase: v6.0.0 · D structural restructure
+type: decision
+---
+
+# ADR-047 — Framework-neutral global commands; stack-adaptive resolution for engineering
+
+## Status
+
+**Accepted** · 2026-06-03. Authored as Phase 7 / Step 20 of
+[`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md).
+Codifies, as an architecture decision, the floor already enforced by the
+[`framework-neutrality-in-generic-skills`](../../src/rules/framework-neutrality-in-generic-skills.md)
+rule and the "stack-adaptive set" resolved in the
+[`command-classification worksheet`](../../agents/reports/command-classification-6.0.0-d.md).
+
+## Context
+
+The suite ships **global** commands that run against any consumer project,
+whatever its stack. A naive design produces one of two failure modes:
+
+1. **Framework leakage** — a generic command hardcodes a single stack's tooling
+   (`php artisan test`, `vendor/bin/phpunit`, `FormRequest`), so it silently
+   misbehaves on a Next.js or Python project.
+2. **Per-stack command explosion** — `php-test-run`, `jest-test-run`,
+   `pytest-run`, … one command per toolchain, multiplying the surface for what
+   is conceptually one action.
+
+Both are wrong. The right shape is a single framework-neutral command whose
+implementation **detects** the toolchain and runs the right tool.
+
+## Decision
+
+1. **Generic commands are framework-neutral.** A global command never mandates a
+   specific framework. Stack specifics live in carve-out artefacts
+   (`laravel-*`, `nextjs-*`, `pest-*`, …) the neutral command composes — never
+   inlined. This is the existing
+   [`framework-neutrality-in-generic-skills`](../../src/rules/framework-neutrality-in-generic-skills.md)
+   rule, now ratified as architecture.
+
+2. **A bounded stack-adaptive set, scoped to engineering.** The commands that
+   DETECT the toolchain and dispatch are: `test-run`, `test-create`,
+   `quality-fix` (`fix-quality`), `review-changes`, and `work`. A resolver
+   detects the stack (phpunit / pest / playwright / vitest / jest / pytest / …)
+   and runs the matching tool. There is **no per-stack command explosion**.
+
+3. **Monorepo guard.** Stack-adaptive test/quality commands default to the FAST
+   path; `--include-slow` / `--include-e2e` opts into the heavy runs.
+   `--all`-style "run everything" is a monorepo footgun and is not the default.
+
+4. **Non-interactive by construction.** Detection-based commands must work in CI:
+   detect a non-TTY, honor explicit flags (`--php`, `--json`, `--yes`), and never
+   block on a prompt. A prompt that hangs CI is "provably wrong for CI/CD".
+
+5. **Genuinely stack-locked commands stay locked.** A command that only makes
+   sense for one stack (e.g. `update-form-request-messages` for Laravel
+   FormRequests) stays in that stack's pack and is not forced neutral. The
+   resolver is for the bounded engineering set, not a universal mandate.
+
+## Consequences
+
+- **Positive.** One command per action, correct on every stack; the surface does
+  not multiply per toolchain.
+- **Positive.** The neutrality rule gains an architectural backing decision, so
+  the lint is not "just a style check" but the enforcement of a recorded contract.
+- **Negative / accepted.** The resolver carries detection logic that must stay
+  current as toolchains evolve; per-stack run skills it composes are the units
+  that change, not the command.
+- **Negative / accepted.** Detection can be ambiguous in mixed-stack repos; the
+  monorepo guard (fast-default + explicit opt-in) and the `--<stack>` narrowing
+  flag are the escape hatches.
+
+## Alternatives considered
+
+- **Per-stack commands.** Rejected: `php-test-run` / `jest-test-run` is the bad
+  world — surface explosion for one conceptual action.
+- **One neutral command with stack hardcoded to the maintainer's stack.**
+  Rejected: that is framework leakage; it breaks on every other consumer.
+- **Universal stack-adaptive (every command detects).** Rejected: only the
+  engineering set benefits; forcing detection onto genuinely stack-locked
+  commands adds complexity for no gain.
+
+## References
+
+- [`framework-neutrality-in-generic-skills`](../../src/rules/framework-neutrality-in-generic-skills.md) — the enforcing rule.
+- [`agents/reports/command-classification-6.0.0-d.md`](../../agents/reports/command-classification-6.0.0-d.md) — the stack-adaptive set + monorepo-guard resolution.
+- [`ADR-046`](ADR-046-thin-command-principle.md) — thin commands compose per-stack skills.
+- [`ADR-044`](ADR-044-command-naming-scheme-hyphenated.md) — naming scheme.

package/docs/decisions/ADR-048-command-justification-rule.md

@@ -0,0 +1,106 @@
+---
+adr: 048
+status: accepted
+date: 2026-06-03
+decision: command-justification-rule
+supersedes: —
+superseded_by: —
+phase: v6.0.0 · D structural restructure
+type: decision
+---
+
+# ADR-048 — Command justification: a command earns a top-level slot in exactly three cases
+
+## Status
+
+**Accepted** · 2026-06-03. Authored as Phase 7 / Step 20b of
+[`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md)
+(feedback-5/7: "the rule that ends every future discussion"). **Locks** the
+"Command justification" section already captured in
+[`command-clusters.md`](../contracts/command-clusters.md#command-justification--a-command-must-earn-a-top-level-slot)
+— the contract text itself defers its dedicated ADR to "the 6.0.0-D structural
+rollout"; this is that ADR. Composes with
+[`ADR-041`](ADR-041-controlled-command-verbs.md) (a new verb still needs an ADR)
+and [`ADR-046`](ADR-046-thin-command-principle.md) (demoted behavior survives as
+a skill).
+
+## Context
+
+The command surface re-bloats one well-meaning addition at a time. Across the
+6.0.0-D council passes (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-06-03)
+two failure modes were named: **125 commands overwhelms** (no one can find the
+daily five) and **~29 commands buries features** (product-surfaces like `council`
+/ `research` vanish as skills and lose discoverability). The defensible target is
+a small, justified set — every top-level command earns its slot or becomes a
+skill the agent triggers by task.
+
+## Decision
+
+A new command earns a top-level slot in **exactly three** cases. Everything else
+is a **skill**.
+
+1. **Flow-entry** — a daily starting point of a flow the user TYPES to begin
+   work: `work`, `git-commit`, `git-pr-create`, `ticket-implement`,
+   `feature-plan`, `review-changes`, `fix-ci`, `test-run`, `bug-fix`.
+
+2. **State-query** — a read-only check typed many times a day: `agent-status`,
+   `session-status`, `project-health`, `profile-show`, `analytics-show`.
+
+3. **Product-surface** — a FEATURE the user starts deliberately (not daily, but
+   consciously): `council`, `challenge-me`, `research`, `roadmap`,
+   `video-storyboard`. Burying these as skills destroys discoverability; a skill
+   is `code-review` / `git-workflow` / `testing`, never `council` / `research`.
+
+If none of the three applies, it is a **skill**. Skills trigger automatically by
+task, so each of the following does NOT need a top-level command:
+
+- a **sub-action** of a flow (a phase, not a front door);
+- a **one-off / setup-once** operation;
+- a **pipeline stage**;
+- a **destructive op** — a skill **with a mandatory confirmation gate**
+  (destructive ≠ command; the confirm covers the mis-parse risk);
+- a **system / admin op** — the `agent-admin` platform surface, which is **NOT a
+  flow** (it is system administration, not user work).
+
+Two corollaries:
+
+- **Sibling variants become a flag, never a second command** — `git-commit
+  --in-chunks` not `git-commit-in-chunks`; `roadmap --step` not a separate
+  `roadmap-process-step`. `roadmap` with no scope defaults to processing the
+  WHOLE roadmap (that is why you write one).
+- **A new verb still needs an ADR** per ADR-041. This ADR governs *whether*
+  something is a command; ADR-041 governs *what verb* it may use.
+
+**Sweet spot ≈ 40–50 visible commands** (≈15 workflow + ≈10 status/admin +
+≈15–20 product features) — not 125, not ~29.
+
+## Consequences
+
+- **Positive.** "Should X be a command?" has a deterministic answer: run the
+  three-case test; if it fails, X is a skill. A proposed `jira-comment` — not
+  flow-entry, not state-query, not a product-surface — is a skill. Done.
+- **Positive.** Product-surface features stay discoverable as commands; pure
+  implementation helpers stay out of the surface as task-triggered skills.
+- **Negative / accepted.** Aggressive demotion to skills depends on reliable
+  task→skill routing; that is handled at conversion time (6.1) via a confirmation
+  gate on each new skill, not by a telemetry wait. Nothing is lost — a demoted
+  command's behavior stays reachable as a task-triggered skill.
+- **Negative / accepted.** "Daily" and "deliberately started" are judgement
+  calls; the contract + this ADR set the frame, review applies it.
+
+## Alternatives considered
+
+- **No justification rule (additive surface).** Rejected: that is the 125-command
+  bloat the rebuild exists to undo.
+- **Maximally aggressive (~29 commands, everything else a skill).** Rejected:
+  buried real product-surface features and hurt discoverability (feedback-7).
+- **A precision-admin command category for destructive ops.** Rejected (maintainer
+  line): a destructive op is a skill with a mandatory confirmation gate; the
+  confirm covers mis-parse risk, so it does not need a top-level slot.
+
+## References
+
+- [`command-clusters.md` § Command justification](../contracts/command-clusters.md#command-justification--a-command-must-earn-a-top-level-slot) — the locked contract text.
+- [`ADR-041`](ADR-041-controlled-command-verbs.md) — controlled verb allowlist (a new verb needs an ADR).
+- [`ADR-046`](ADR-046-thin-command-principle.md) — demoted behavior survives as a composed skill.
+- [`agents/reports/command-classification-6.0.0-d.md`](../../agents/reports/command-classification-6.0.0-d.md) — the 150-command classification applying this rule.

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()`.