@event4u/agent-config 5.10.1 → 6.0.0

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.

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.