@event4u/agent-config 5.10.1 → 6.1.0

package/docs/decisions/ADR-043-monorepo-collapse-to-src-domains.md

@@ -0,0 +1,128 @@
+---
+adr: 043
+status: accepted
+date: 2026-06-03
+decision: monorepo-collapse-to-src-domains
+supersedes: ADR-017
+superseded_by: —
+phase: v6.0.0 · D structural restructure
+type: decision
+---
+
+# ADR-043 — Collapse `packages/` into `src/domains/` (with boundary safeguards)
+
+## Status
+
+**Accepted** · 2026-06-03. Records the Phase 3 decision gate of
+[`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md)
+(Step 9). Supersedes the per-pack physical layout of
+[`ADR-017`](ADR-017-monorepo-physical-layout.md) for the source tree.
+Decision routed through the AI council (anthropic/claude-sonnet-4-5 +
+openai/gpt-4o, design mode, 2026-06-03).
+
+**Executed** · 2026-06-05. The collapse is now carried out: `packages/` no longer
+exists at the repo root. The uncondensed source container moved to `src/agent-src/`
+([`ADR-051`](ADR-051-uncondensed-source-container-relocation.md)); pack homes moved to
+`src/packs/<id>/` (capability packs + core) and `src/domains/<pack>/` (command-bearing),
+with ops dirs to root `deploy/` ([`ADR-052`](ADR-052-packages-removal-and-pack-home-migration.md)).
+The condensed `.agent-src/` output is byte-identical across the move.
+
+## Context
+
+The decision: collapse the build-time `packages/<pack>/.agent-src.uncondensed/`
+source trees into `src/domains/<pack>/`, OR keep per-pack publishing and nest
+`src/domains/` inside each package.
+
+### Install-pattern evidence (the gate criterion)
+
+1. The suite ships as **one** npm package `@event4u/agent-config`. The published
+   `files` array contains `.agent-src/`, `config/`, `docs/`, `scripts/`,
+   `templates/`, `dist/` — it does **not** contain `packages/`. The per-pack
+   source tree is build-time only and is never shipped to consumers.
+2. **No `packages/*/package.json` exists** — packs are not separately publishable
+   npm packages; they are a build-time source organisation.
+3. Consumers select pack subsets via `install.py --packs a,b,c`, which operates
+   on the discovery projection (`.agent-src/` + discovery manifest) *within* the
+   single published package — not by installing separate npm packages.
+4. After Phase 2, 15 of 17 packs are empty shells (their only content was
+   skills/rules, now in the flat `src/skills/` + `src/rules/` library); commands
+   live in `core` + `pack-fun` and declare ownership via the `pack:` frontmatter.
+
+The expected answer — **no subset installs as separate packages** — holds. The
+physical `packages/` boundary buys nothing at the consumer interface.
+
+## Decision
+
+**COLLAPSE** `packages/<pack>/` into `src/domains/<pack>/`, with the four
+council-mandated boundary safeguards below. The collapse changes only the
+build-time source layout; it does not change the shipped npm package shape.
+
+## Council convergence and the boundary risk
+
+Both members converged on **collapse-with-safeguards**, not an unconditional GO.
+The shared concern: the `packages/` filesystem boundary is a *forcing function*,
+not documentation — collapsing trades compile-time impossibility of cross-pack
+coupling for lint-time detection ("build-time architectural decay"). The GO is
+conditioned on the boundary being enforced by a lint that walks **actual**
+includes, on a re-split proof staying live, on a documented rollback, and on a
+path-stability contract.
+
+### Safeguards (status in this repo)
+
+| # | Council-required safeguard | Status |
+|---|---|---|
+| 1 | One reference extraction re-validated in CI (not all packs every PR) + a documented recipe | **Already in place** — `scripts/prove_pack_extractable.py` + `tests/test_prove_pack_extractable.py` lock laravel's extractability; the recipe is the script's transitive-closure resolver, runnable per pack on demand. |
+| 2 | A dependency lint that walks **actual** includes, not just `pack.yaml` metadata | **Already in place** — `scripts/lint_pack_dependencies.py` (Phase-0 Step 3) compares declared `pack.yaml` deps against the real frontmatter `skills:`/`rules:` includes and asserts the pack-graph DAG is acyclic. |
+| 3 | A documented rollback / kill-switch criterion | **Documented here** (see below). |
+| 4 | A path-stability contract for shipped paths | **Structurally satisfied** — `scripts/_lib/agent_src.py` maps physical `src/domains/<pack>/` and `src/{skills,rules}/` onto stable *logical* paths (`commands/…`, `skills/…`, `rules/…`). The shipped `.agent-src/` logical paths are therefore unchanged by the collapse. The consumer-facing path break of 6.0.0 comes from the root→`src/` move (Step 16) and is carried by `migrate`, not by this collapse. |
+
+The council's central worry — "the lint must walk actual imports, not metadata"
+— is exactly what safeguard #2 already does for this repo's markdown-include
+dependency model (frontmatter `skills:`/`rules:` is the hard dependency axis;
+advisory `see also` links are warnings, per the Step-6 council).
+
+### Rollback / kill-switch criterion (safeguard #3)
+
+Re-split is proven possible (Phase-1 extraction proof), so revert is mechanical,
+not archaeological. The collapse is reverted if **either** holds within one
+release cycle of landing:
+
+- `lint_pack_dependencies.py` or `prove_pack_extractable.py` records a
+  cross-domain dangling reference that cannot be resolved by declaring the
+  dependency (i.e. a genuine boundary violation, not a missing `pack.yaml` line);
+  **and** the violation recurs after one fix attempt.
+- A pack that must ship as a standalone npm package is identified (subset-install
+  demand appears) — at which point per-pack publishing is restored by nesting
+  `src/domains/<pack>/` back into a package using the documented recipe.
+
+Absent either trigger, the collapse stands.
+
+## Consequences
+
+- **Positive.** One source tree reads as the product (`src/domains/<pack>/<verb>/`);
+  the empty-shell packs disappear; the dependency graph is enforced by lint +
+  extraction proof rather than by accident of directory nesting; the consumer
+  install model is unchanged.
+- **Negative / risk.** Architectural discipline now depends on the boundary lint
+  rather than module-resolution impossibility — mitigated by safeguards #1–#2
+  running on every PR and the rollback criterion in #3.
+- **Follow-on.** Step 10 executes the physical move of the `core` + `pack-fun`
+  command sets into `src/domains/<pack>/<verb>/` with pack renames; the
+  meta-pack split and remaining consolidation stay in 6.0.x / 6.1 per the
+  roadmap's scope-line rule.
+
+## Alternatives considered
+
+- **Keep per-pack publishing, nest `src/domains/` inside each package.** Rejected:
+  no evidence of subset installs as separate npm packages; preserves a boundary
+  that buys nothing at the consumer interface while blocking the "tree reads as
+  the product" goal.
+
+## References
+
+- [`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md) Step 9.
+- [`ADR-017`](ADR-017-monorepo-physical-layout.md) — superseded source layout.
+- Council session: anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode,
+  2026-06-03 (collapse-with-safeguards convergence).
+- `scripts/prove_pack_extractable.py`, `scripts/lint_pack_dependencies.py`,
+  `scripts/_lib/agent_src.py`.

package/docs/decisions/ADR-044-command-naming-scheme-hyphenated.md

@@ -0,0 +1,250 @@
+---
+adr: 044
+status: accepted
+date: 2026-06-03
+decision: command-naming-scheme-hyphenated
+supersedes: —
+superseded_by: —
+phase: v6.0.0 · D structural restructure
+type: decision
+---
+
+# ADR-044 — Command naming scheme: `<pack>-<verb>`, hyphenated, no colon namespacing
+
+## Status
+
+**Accepted** · 2026-06-03. Authored as Phase 4b / Step 11 of
+[`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md).
+Builds on [`ADR-041`](ADR-041-controlled-command-verbs.md) (controlled verb
+allowlist — still applies, unchanged) and
+[`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) (the `src/domains/<pack>/`
+collapse that gives each command a pack-physical home). Sits alongside the
+locked-cluster contract ([`command-clusters.md`](../contracts/command-clusters.md)).
+
+## Context
+
+6.0.0-D moves every command into `src/domains/<pack>/<verb>/command.md` — the
+path now carries pack ownership. With ownership in the path, the historical
+**colon cluster syntax** (`feature:plan`, `git:pr`, `git:pr:create`) is no longer
+needed to express grouping, and it actively fights the Claude Code projection.
+
+The naming question was settled by an **authoritative claude-code-guide finding**
+plus the AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-06-03):
+
+1. **Claude Code SHADOWS a bare colon cluster-head** when a same-named
+   subdirectory exists. Observed: with `/create-pr` and
+   `/create-pr:description-only` both present, the bare `/create-pr` head is
+   hidden and only the sub is shown. A cluster head with no default action
+   becomes invisible.
+2. **Claude Code does NOT support two-colon multi-level invocation**
+   (`git:pr:create` ✗). Only a single colon level resolves.
+
+So colon namespacing cannot express the `git/pr/create` depth the domain tree
+now has, and bare cluster heads disappear from the surface anyway.
+
+## Decision
+
+1. **`<pack>-<verb>`, hyphenated.** Every project command is invoked as a flat,
+   hyphenated name. `feature:plan` → `feature-plan`; `git:pr:create` →
+   `git-pr-create`; `git:commit` → `git-commit`. No colon namespacing for
+   project commands.
+
+2. **Cluster heads fold away.** A bare orchestrator command with no default
+   action is not a visible command. Its sub-commands render as standalone flat
+   hyphenated commands. (The *structural* move of head files into the flat layout
+   is Step 13; the *behavioral* folding of N routers into one is staged in 6.0.x
+   per the scope-line rule, not done here.)
+
+3. **A sub-action is a separate command only if it is a distinct workflow** —
+   otherwise it is a **flag** on the parent. `commit --in-chunks`, not
+   `commit-in-chunks`, once the merge evidence (Step 13b) confirms the split is
+   artificial. Sibling variants that differ only in a parameter are flags, never
+   a second command.
+
+4. **The controlled-verb allowlist (ADR-041) still applies, unchanged.** The
+   leading token of every visible command must be drawn from
+   [`src/config/discovery/command-verbs.yml`](../../config/discovery/command-verbs.yml).
+   This ADR governs the *shape* (`<pack>-<verb>`, hyphenated); ADR-041 governs the
+   *verb vocabulary*. They compose.
+
+5. **Same short-descriptive-name discipline for skills and rules.** The flat
+   `src/skills/` and `src/rules/` library is a single global namespace. Names are
+   short, descriptive, and globally unique after normalization (lowercase,
+   `_`→`-`) — enforced by the single-namespace collision lint (Phase 0, Step 4).
+   No skill / rule / command name may collide across the three surfaces.
+
+6. **6.0.0-D is rename + alias only — NO consolidation.** Every renamed command
+   keeps its old invocation working as a deprecation alias (`replaces:` /
+   `superseded_by`, routed by `migrate`). Nothing is removed in 6.0-D. Merging
+   clusters, dropping old aliases, and converting surplus leaf commands to skills
+   are Phase 8 / 6.1 work (their own roadmap).
+
+## Consequences
+
+- **Positive.** The surface reads as a flat, predictable verb vocabulary scoped
+  by pack prefix. Every command resolves under Claude Code (no shadowed heads, no
+  unsupported two-colon depth). The `src/domains/<pack>/<verb>/` path and the
+  `<pack>-<verb>` invocation name line up one-to-one.
+- **Positive.** Rename-with-alias means zero breakage in 6.0-D: old colon
+  invocations keep resolving through the deprecation alias until a later major.
+- **Negative / accepted.** Flat hyphenated names are longer than the colon sub
+  (`git-pr-create` vs `git:pr:create`). The gain — universal resolvability and a
+  single namespace — outweighs the few extra characters.
+- **Negative / accepted.** The fold of cluster heads into flat subs increases the
+  raw command *count* in the tree before 6.1 consolidation shrinks it. This is the
+  cost of "structure first, consolidate second" (the feedback-2 guardrail).
+
+## Amendment — 2026-06-04 · slug-canonicalization mechanism (Step 12)
+
+> **Accepted** · 2026-06-04. Implementing Step 12 surfaced that Decision §1's
+> shorthand "`<pack>-<verb>`" is under-specified and inconsistent with
+> product-surface commands. Routed to the AI council (anthropic/claude-sonnet-4-5
+> + openai/gpt-4o, design + peer-review, 2026-06-04). The council **rejected**
+> frontmatter-as-slug and the hybrid override model as split-brain ("two trust
+> anchors"), and converged on **path = single source of truth** (Reviewer A)
+> **with a pack-scoped namespace policy** (peer-review synthesis). This amendment
+> locks that mechanism before any rename lands.
+
+### A1 — Canonical slug source is the PATH, pack-stripped
+
+The slug a command projects to (`.agent-src/commands/<slug>.md`, then
+`.claude` / `.cursor`) is **derived from the source path**, pack segment
+stripped, remaining subpath hyphenated:
+
+- `src/domains/engineering-base/feature/plan/command.md` → `feature-plan`
+- `src/domains/meta/council/analysis/command.md` → `council-analysis`
+
+Frontmatter `name:` is **display/metadata only — never the slug source**. This
+locks the generator's de-facto behaviour (`_command_path_to_slug`) as the single
+source of truth. There is no frontmatter slug override; relocating a command's
+directory is the only way to change its slug.
+
+### A2 — Decision §1's "`<pack>-<verb>`" is shorthand, not a mechanical rule
+
+The pack name is **not auto-prefixed** into the slug. The real rule is
+"hyphenated subpath within the pack". This is why `meta/council` → `council`
+(NOT `meta-council`) and `meta/research` → `research` — product-surface commands
+keep their bare name. ADR-044 §1's examples (`git-commit`, `feature-plan`) read
+as `<pack>-<verb>` only by coincidence of their paths; the governing rule is the
+subpath, not a pack prefix.
+
+### A3 — Pack-scoped prefix is opt-in via `pack.yaml`
+
+A pack whose bare verbs are generic/ambiguous (`commit`, `pr`, `sync`) MAY
+declare `slug_prefix: <p>` in its `pack.yaml`. Then every command in that pack
+projects as `<p>-<subpath>`:
+
+- `git` pack with `slug_prefix: git` → `git/commit` → `git-commit`,
+  `git/pr/create` → `git-pr-create`.
+- `meta` pack (no `slug_prefix`) → `meta/council` → `council`.
+
+Default = no prefix. This is the council's pack-scoped namespace policy and the
+only sanctioned way to obtain a pack-prefixed slug. No per-command override.
+
+### A4 — Slug uniqueness is GLOBAL
+
+`.agent-src/commands/` is a flat namespace; the Phase-0 single-namespace
+collision lint (Step 4) already enforces global uniqueness across skills /
+rules / commands. `slug_prefix` packs participate in the same global namespace
+(the prefix is part of the unique slug, not a separate scope).
+
+### A5 — Alias mechanism: `replaces:` list, routed by `migrate`
+
+A renamed command carries `replaces: [<old-slug>, …]` listing every prior
+invocation (the legacy colon name for Class A, the pre-rehome name for Class B).
+`migrate` reads these and rewrites old invocations to the new slug. The
+`superseded_by:` **shim** convention is reserved for **true command
+supersession** (one command replaced by a different one) and is NOT used for an
+in-place rename alias — a command never both *is* a slug and *is superseded*.
+One slug per file; `replaces:` carries the history.
+
+### A6 — Three rename classes, distinct sequencing
+
+| Class | Pattern | Example | Lane |
+|---|---|---|---|
+| **A** | colon → hyphen (punctuation only; path-slug already correct) | `feature:plan` → `feature-plan` | **Step 12** — reconcile `name:` display + `replaces:[old-colon]` + refs/evals; no path move |
+| **B1** | pack-prefix (generic verb gains a `slug_prefix` pack) | `commit` → `git-commit` | **Step 12** — gated on the `git` pack + its `slug_prefix`; a directory move into the pack |
+| **B2** | semantic rebrand (taxonomy changed) | `agent-handoff` → `session-handoff` | **Step 13** (pack/taxonomy restructure) — NOT Step 12; it changes pack membership AND name |
+
+Lumping B1 and B2 was the council's named false-dichotomy: B2 is a rebrand of the
+domain, not a rename, and ships with the pack restructure.
+
+### A7 — Pre-flight gates before any rename lands
+
+1. **No-op baseline.** Before touching the divergent commands, prove the
+   path-slug derivation is unchanged for the already-aligned commands (assert the
+   set of projected slugs is byte-identical pre/post the generator's
+   `slug_prefix` support; only the opted-in pack's slugs may change).
+2. **Circular-`replaces:` lint.** Reject any `replaces:` chain that cycles or
+   points at a live slug.
+3. **Global-collision lint** (Phase-0) must stay green after each class.
+4. **Rollback.** Each class is its own commit; a class that fails its gate is
+   reverted without touching the others (move-one-validate-one cadence).
+
+### A8 — `migrate` I/O (the trust-boundary the council flagged)
+
+- **Input:** command frontmatter `replaces:` across `src/domains/**`, producing
+  an `old-slug → new-slug` map. Reads source, not the projected `.agent-src/`.
+- **Output:** rewrites old invocations in the consumer's own artefacts (saved
+  commands, docs) to the new slug; emits the map for audit. It mutates
+  user-facing invocations only — never the package source.
+
+## Amendment — 2026-06-04 · cluster-subs follow their head (Class A → Step 13)
+
+> **Accepted** · 2026-06-04. Routed to the AI council (anthropic/claude-sonnet-4-5
+> + openai/gpt-4o, design mode) when implementing Step 12. Both members converged
+> on a classification tiebreaker the original A6 table missed.
+
+### A9 — A colon-named **cluster sub** follows its HEAD's lane, regardless of
+path-slug status.
+
+A6 classified `feature:plan` → `feature-plan` as **Class A → Step 12** because
+the path-slug is already correct. That reading misses **structural membership**:
+the colon was never decorative punctuation — it encoded cluster membership, and
+every remaining colon-named command in the tree is a tier-2 cluster sub whose
+HEAD move is **Step 13** (Decision §2). Renaming a sub colon→hyphen in Step 12
+while its head moves in Step 13 splits one coherent change across two steps and
+produces a command-scattered intermediate state (hyphenated subs under unmigrated
+heads).
+
+**The tiebreaker:** a Class-A rename that targets a **cluster sub** is performed
+**in Step 13, together with its head's structural move** — per cluster, atomically.
+Two consequences the council named:
+
+1. **Verb governance lands with the head, not before it.** Subs like
+   `video:storyboard` / `analytics:show` / `profile:show` would each force a new
+   ADR-041 verb (`video` / `analytics` / `profile`) just to align a display name.
+   The verb-namespace budget is decided WITH the cluster's head restructure in
+   Step 13, never burned prematurely in Step 12.
+2. **Step 12's delivered scope is therefore B1 (the `git` pack rename) + the
+   `slug_prefix` pipeline** — the only genuinely standalone structural renames.
+   All other KEEP renames are either cluster subs (this A9) or B2 semantic
+   rebrands (A6) — both Step 13.
+
+Standalone (non-cluster-sub) Class-A renames, should any appear, stay in Step 12
+per A6. None exist in the current tree.
+
+## Alternatives considered
+
+- **Frontmatter `name:` as the slug source (council option a).** Rejected: two
+  trust anchors (slug from frontmatter, pack from path), commands become
+  non-relocatable, and `name:` / `replaces:` create a multi-field slug conflict.
+- **Hybrid: optional frontmatter override wins, else path (council option c).**
+  Rejected: institutionalises "sometimes path, sometimes frontmatter" — a
+  permanent split-brain with no north star for new contributors.
+- **Keep colon namespacing (`git:pr:create`).** Rejected: Claude Code does not
+  resolve two-colon depth, and bare heads are shadowed — the syntax cannot
+  express the domain tree.
+- **Single colon level only (`git:commit`, `git-pr-create` for depth-3).**
+  Rejected: mixing colon and hyphen by depth is inconsistent and surprising; a
+  uniform hyphenated scheme is simpler to teach and to lint.
+- **Consolidate while renaming.** Rejected per the feedback-2 hard guardrail:
+  "Erst Strukturbruch. Dann Konsolidierungsroadmap." Doing both at once makes the
+  6.0 break un-reviewable and risky.
+
+## References
+
+- [`ADR-041`](ADR-041-controlled-command-verbs.md) — controlled verb allowlist (composes with this ADR).
+- [`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) — `src/domains/<pack>/` collapse.
+- [`command-clusters.md`](../contracts/command-clusters.md) — locked clusters + sub-command naming + command justification.
+- [`agents/reports/command-classification-6.0.0-d.md`](../../agents/reports/command-classification-6.0.0-d.md) — the 150-command rename worksheet driven by this scheme (Step 12).

package/docs/decisions/ADR-045-src-source-layout-and-profiles-as-views.md

@@ -0,0 +1,111 @@
+---
+adr: 045
+status: accepted
+date: 2026-06-03
+decision: src-source-layout-and-profiles-as-views
+supersedes: ADR-028
+superseded_by: —
+phase: v6.0.0 · D structural restructure
+type: structural
+---
+
+# ADR-045 — `src/`-rooted source layout, profiles-as-views, and the hard-break decision
+
+## 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).
+**Supersedes [`ADR-028`](ADR-028-root-layout.md)** (the "src/ is occupied, defer
+the root→src move" verdict). Composes with
+[`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) (packages→src/domains),
+[`ADR-044`](ADR-044-command-naming-scheme-hyphenated.md) (naming),
+[`ADR-046`](ADR-046-thin-command-principle.md) (thin commands), and
+[`ADR-047`](ADR-047-framework-neutral-stack-adaptive-commands.md) (stack-adaptive).
+Routed through the AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o,
+three deep design rounds, 2026-06-03).
+
+## Context
+
+ADR-028 rejected "move everything not needed at root into `./src/`" on the
+ground that `./src/` was **occupied** by the TypeScript application (CLI · Server
+· UI · shared) per ADR-012/016. That objection is resolved here: the TS app moves
+to `src/app/`, freeing `src/` to be the single source-root for the whole package.
+
+This is the **deliberate hard break** of the 6.0.0 line. The package has
+few/team-internal users; the maintainer's explicit mandate is to optimise for the
+cleanest end-state in one clean major rather than spread a path-invasive cut over
+many versions. The AI council flagged consumer risk on root→src and did **not**
+rubber-stamp the design; the maintainer's hard-break mandate overrides that, and
+the value kept from the council is the **sequencing safeguards**, not "don't break".
+
+## Decision
+
+1. **`src/` is the single source-root.** The end-state tree:
+   - `src/app/` — the TypeScript runtime (today's `src/{cli,server,install,shared,ui}`).
+   - `src/domains/<pack>/<verb>/command.md` — the command surface (ADR-043/044).
+   - `src/skills/` + `src/rules/` — flat, shared, single-namespace.
+   - `src/flows/` — first-class USER-WORK flow artefacts (scaffolded 6.0.0-D, schema 6.1).
+   - `src/profiles/` — profiles-as-views.
+   - `src/config/`, `src/schemas/`, `src/templates/`, `src/docs/`, `src/internal/`.
+   - Root keeps only tooling/agent-host essentials + `src/` + `tests/` + `taskfiles/`.
+
+2. **Profiles are VIEWS, never file holders.** A `src/profiles/<id>.yaml` declares
+   the **command set it surfaces** (by logical command name); the curated tree is
+   rendered, not stored. Built-in profiles are **opinionated templates, immutable
+   in 6.0** (user customisation of built-ins is deferred to 6.1; a custom profile
+   uses a different name). Profiles reference commands by logical name, so they
+   are decoupled from install-time filesystem paths.
+
+3. **Profiles are INTERNAL, not a day-one concept.** The wizard/CLI never says
+   "choose a profile". It asks "What are you doing?" (Software Development /
+   Product & Roadmaps / Content Creation / Finance & Planning) and maps the answer
+   to a profile id, with a Simple (default) vs Advanced toggle.
+
+4. **Hard break, with a migration path.** There is no backward compatibility for
+   the old paths. A first-class `migrate` command (`--dry-run` / `--from 4|5` /
+   `--check`) plus `MIGRATION.md` (linked from the README) carries existing
+   installs across.
+
+5. **Staged execution per the scope-line rule (council sequencing safeguard).**
+   The decision is locked here; the *execution* is staged so failure stays
+   localisable:
+   - **Structural/interface moves** (commands, skills/rules already flat, ADRs,
+     flows, profiles-as-views schema) land in the 6.0.0 break PRs.
+   - **The `scripts/` Python-package move under `src/` is the kill-switch risk**
+     (imported repo-wide as `scripts.*`). It ships in its **own PR** with an
+     import-compatibility shim (install shim → rewrite imports → remove shim),
+     never bundled with unrelated changes. The install-contract rewrite
+     (`package.json` `files`/`bin`/prepack, installer + manifest paths) follows
+     the filesystem move, not before it.
+
+## Consequences
+
+- **Positive.** The repository layout reads as the product: `src/` is the whole
+  package, structured; root is essentials only. ADR-028's "src is occupied"
+  blocker is gone.
+- **Positive.** Profiles-as-views means zero file duplication per profile and a
+  single rendered curated surface; the "choose your workflow" UX hides the
+  profile machinery.
+- **Negative / accepted.** The hard break invalidates every old consumer path.
+  This is intentional and mediated by `migrate` + `MIGRATION.md`.
+- **Negative / accepted.** The root→src move (especially `scripts/`) is high-risk
+  and is therefore staged across PRs with a compat shim, slowing the cut but
+  keeping each PR reviewable and CI-localisable.
+
+## Alternatives considered
+
+- **Keep ADR-028 (defer root→src indefinitely).** Rejected: the maintainer's
+  hard-break mandate + the `src/app/` resolution remove the original blocker.
+- **Big-bang move (everything, one PR).** Rejected per the council: bundling the
+  `scripts/` package move with 11 other changes makes failure localisation
+  impossible. Staged-with-shim is the safeguard.
+- **Profiles as directories of files.** Rejected: duplicates commands per profile
+  and couples profiles to filesystem paths; views over a logical command registry
+  are leaner and path-independent.
+
+## References
+
+- [`ADR-028`](ADR-028-root-layout.md) — superseded root-layout verdict.
+- [`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) — packages→src/domains.
+- [`ADR-044`](ADR-044-command-naming-scheme-hyphenated.md) · [`ADR-046`](ADR-046-thin-command-principle.md) · [`ADR-047`](ADR-047-framework-neutral-stack-adaptive-commands.md).
+- [`road-to-6.0.0-d-structural-restructure`](../../agents/roadmaps/archive/road-to-6.0.0-d-structural-restructure.md) — target structure + scope-line rule.

package/docs/decisions/ADR-046-thin-command-principle.md

@@ -0,0 +1,93 @@
+---
+adr: 046
+status: accepted
+date: 2026-06-03
+decision: thin-command-principle
+supersedes: —
+superseded_by: —
+phase: v6.0.0 · D structural restructure
+type: decision
+---
+
+# ADR-046 — The Thin-Command Principle: commands orchestrate, skills + scripts implement
+
+## 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)
+(feedback-3: "it is an architecture decision, not just structure"). Composes with
+[`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) (the flat `src/skills/` +
+`src/rules/` shared library a command composes from) and
+[`ADR-044`](ADR-044-command-naming-scheme-hyphenated.md) (naming).
+
+## Context
+
+6.0.0-D makes the path the unit of command ownership
+(`src/domains/<pack>/<verb>/command.md`) and keeps skills + rules flat and shared.
+That structure only pays off if commands stay **thin**: a command's `.md` is a
+short orchestration spec, and the heavy logic lives in reusable skills + scripts
+that many commands can compose.
+
+Without this principle, every command re-implements its own workflow inline, the
+`.md` files balloon, logic duplicates across sibling commands, and the "merge N
+commands into one" consolidation planned for 6.1 becomes impossible — there is
+nothing shared to fold into. The thin-command shape is the precondition that
+makes both the flat library (ADR-043) and the future consolidation tractable.
+
+## Decision
+
+1. **A command is a THIN base.** Its `command.md` is a short orchestration spec:
+   it states intent, lists the skills it triggers and the scripts it runs, names
+   the safety gates, and sequences them. It does **not** inline detailed
+   procedure.
+
+2. **Heavy logic lives in `src/skills/` and scripts.** Calculations,
+   multi-step procedures, provider calls, parsing, and orchestration detail
+   belong in a skill (preferably) or a script (TypeScript preferred, Python where
+   the surrounding tooling is Python) — never in the command body.
+
+3. **When commands merge or are cut, the removed pieces become skills.** A
+   consolidation never deletes behavior: the survivor composes the behavior of
+   the folded commands as skills. This is what keeps 6.1 consolidation
+   non-destructive.
+
+4. **Interactivity is an allowed merge mechanism.** A thin command MAY ask ONE
+   short clarifying question to disambiguate instead of splitting into several
+   commands (e.g. `fix-pr-comments` detecting new bot/human comments and asking
+   which to fix). The question must work non-interactively in CI (honor
+   `--yes` / `--json` / explicit flags, detect a non-TTY, fall back to a safe
+   default — destructive defaults are never silent).
+
+5. **The command body never embeds credentials or free-form execution.** Per the
+   tool-safety floor, a command declares the skills/scripts it composes; it does
+   not inline secrets or arbitrary code.
+
+## Consequences
+
+- **Positive.** Command `.md` files stay scannable and reviewable; logic is
+  written once in a skill and reused across every command that needs it.
+- **Positive.** Consolidation (6.1) is a fold, not a rewrite: the behavior is
+  already a composable skill.
+- **Positive.** The flat shared library (ADR-043) has real consumers — commands
+  reference skills by slug, the dependency is declared in `pack.yaml`.
+- **Negative / accepted.** Authoring a new command now means authoring (or
+  reusing) a skill for its logic — a slightly higher up-front cost than inlining,
+  paid back the first time a second command needs the same behavior.
+- **Negative / accepted.** The principle is a discipline, not (yet) a hard lint.
+  A future lint could bound command-body size or flag inlined procedure; until
+  then it is enforced in review.
+
+## Alternatives considered
+
+- **Fat commands (logic inline in `.md`).** Rejected: duplicates logic across
+  siblings, balloons the files, and makes consolidation a rewrite instead of a
+  fold.
+- **Logic in commands, skills as thin pointers.** Rejected: inverts the reuse
+  story — skills are the shared library; commands are the per-pack entry points.
+
+## References
+
+- [`ADR-043`](ADR-043-monorepo-collapse-to-src-domains.md) — flat shared skills/rules library.
+- [`ADR-044`](ADR-044-command-naming-scheme-hyphenated.md) — command naming.
+- [`command-clusters.md`](../contracts/command-clusters.md) — command justification + cluster contract.
+- `tool-safety` / `runtime-safety` rules — no inlined credentials or free-form execution.