@event4u/agent-config 2.25.0 → 3.0.0

package/docs/decisions/ADR-004-rule-governance-pruning.md

@@ -35,7 +35,7 @@ analytic passes ran:
 
 **5.4** AI Council R3 (claude-sonnet-4-5 + gpt-4o, 2 rounds, prompt
 mode) walked the candidate list. Council convergence and host
-verdicts are recorded in `agents/reports/auto-rules-audit.md`
+verdicts are recorded in `agents/runtime/reports/auto-rules-audit.md`
 § Phase 5.4. The dominant council insight:
 
 > *"Rarity ≠ redundancy. Low corpus hits often indicate a
@@ -192,11 +192,11 @@ documentation rewrite for marginal additional savings.
   governance pass; the stub-cost / body-cost ratio changes
   drastically.
 - Auto-rule count grows by ≥ 5 (history check via
-  `agents/.augment-budget-history.jsonl`) → repeat the audit
+  `agents/runtime/.augment-budget-history.jsonl`) → repeat the audit
   with the same three-pass methodology.
 - A retained rule (`upstream-proposal`, `slash-command-routing-policy`,
   `analysis-skill-routing`'s sibling skill) shows a 30-day window
-  with zero documented activation in `agents/council-sessions/` →
+  with zero documented activation in `agents/runtime/council/sessions/` →
   open a follow-up ADR demoting it.
 
 ## Alternatives considered
@@ -224,13 +224,13 @@ documentation rewrite for marginal additional savings.
 ## References
 
 - `agents/roadmaps/archive/road-to-augment-limit-fit.md` § Phase 5
-- `agents/reports/auto-rules-audit.md` (full audit findings,
+- `agents/runtime/reports/auto-rules-audit.md` (full audit findings,
   council walk, host verdicts)
-- `agents/reports/auto-rules-overlap.json` (Phase 5.2 data)
-- `agents/reports/auto-rules-likelihood.json` (Phase 5.3 data)
-- `agents/council-questions/augment-limit-fit-rule-governance.md` <!-- council-ref-allowed: ADR decision trace -->
+- `agents/runtime/reports/auto-rules-overlap.json` (Phase 5.2 data)
+- `agents/runtime/reports/auto-rules-likelihood.json` (Phase 5.3 data)
+- `agents/runtime/council/questions/augment-limit-fit-rule-governance.md` <!-- council-ref-allowed: ADR decision trace -->
   (Phase 5.4 prompt)
-- `agents/council-responses/augment-limit-fit-rule-governance.json` <!-- council-ref-allowed: ADR decision trace -->
+- `agents/runtime/council/responses/augment-limit-fit-rule-governance.json` <!-- council-ref-allowed: ADR decision trace -->
   (Phase 5.4 R3 raw debate)
 - `docs/decisions/ADR-rule-kernel-and-router.md` (kernel-membership
   contract — Phase 5 changes leave kernel untouched per Lever C lock)

package/docs/decisions/ADR-006-skill-tools-python-pilot.md

@@ -29,7 +29,7 @@ Python tools for skill / persona corpus maintenance:
 
 The pilot was gated by **iter-1 AI-Council verdict** (members:
 claude-sonnet-4-5 + gpt-4o · 2 rounds · 2026-05-01) <!-- council-ref-allowed: ADR decision trace -->
-([`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md)) <!-- council-ref-allowed: ADR decision trace -->
+([`block-d-python-tools-pilot-verdict`](../../agents/runtime/council/responses/block-d-python-tools-pilot-verdict.md)) <!-- council-ref-allowed: ADR decision trace -->
 under strict invariants: stdlib-only (internal package imports
 allowed), ≤ 200 LOC per tool, machine-readable output (`--json`),
 embedded `_SAMPLE`, blind-labelled eval corpora, and a kill-switch if
@@ -37,9 +37,9 @@ embedded `_SAMPLE`, blind-labelled eval corpora, and a kill-switch if
 
 ## Eval Outcome (D5)
 
-Corpora at `agents/eval-corpora/block-d/`. Runner:
+Corpora at `agents/evidence/eval-corpora/block-d/`. Runner:
 `scripts/skill_tools/run_block_d_eval.py`. Report:
-[`agents/eval-corpora/block-d/report.json`](../../agents/eval-corpora/block-d/report.json).
+[`agents/evidence/eval-corpora/block-d/report.json`](../../agents/evidence/eval-corpora/block-d/report.json).
 
 | Tool | Target | Result | Verdict |
 |---|---|---|---|
@@ -106,9 +106,9 @@ dir, and the `lint-skill-tools` task entry. Mark this ADR
 ## References
 
 - Roadmap: [`road-to-better-skills-and-profiles`](../../agents/roadmaps/archive/road-to-better-skills-and-profiles.md) Block D.
-- Council: [`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md). <!-- council-ref-allowed: ADR decision trace -->
+- Council: [`block-d-python-tools-pilot-verdict`](../../agents/runtime/council/responses/block-d-python-tools-pilot-verdict.md). <!-- council-ref-allowed: ADR decision trace -->
 
 - Tools: [`scripts/skill_tools/`](../../scripts/skill_tools/).
 - Linter: [`scripts/lint_skill_tools.py`](../../scripts/lint_skill_tools.py).
-- Corpora + report: [`agents/eval-corpora/block-d/`](../../agents/eval-corpora/block-d/).
+- Corpora + report: [`agents/evidence/eval-corpora/block-d/`](../../agents/evidence/eval-corpora/block-d/).
 - Tests: `tests/test_lint_skill_tools.py`, `tests/test_score_skill_relevance.py`, `tests/test_audit_persona_coverage.py`, `tests/test_suggest_skill_for_task.py`.

package/docs/decisions/ADR-007-agent-discovery-scopes.md

@@ -31,7 +31,7 @@ phase: post-v2.1.0 · simplicity-and-everywhere
 Originates from user ask: "Es macht keinen Sinn, das paket nicht
 global zu installieren." Validated through AI Council (2 + 1 rounds,
 2026-05-12 · members claude-sonnet-4-5 + gpt-4o). Council session:
-[`agents/council-sessions/2026-05-12-global-first-strategy/`](../../agents/council-sessions/2026-05-12-global-first-strategy/). <!-- council-ref-allowed: ADR decision trace -->
+[`agents/runtime/council/sessions/2026-05-12-global-first-strategy/`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/). <!-- council-ref-allowed: ADR decision trace -->
 
 ## Context
 
@@ -110,8 +110,8 @@ differ.
 | 3 (targeted resolution) | same | $0.0252 | **3/4 convergence** |
 
 Full responses:
-[`responses.json`](../../agents/council-sessions/2026-05-12-global-first-strategy/responses.json), <!-- council-ref-allowed: ADR decision trace -->
-[`responses-round3.json`](../../agents/council-sessions/2026-05-12-global-first-strategy/responses-round3.json). <!-- council-ref-allowed: ADR decision trace -->
+[`responses.json`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/responses.json), <!-- council-ref-allowed: ADR decision trace -->
+[`responses-round3.json`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/responses-round3.json). <!-- council-ref-allowed: ADR decision trace -->
 
 ## Decision
 
@@ -350,7 +350,7 @@ Out of scope for this ADR. Sequencing target for a separate roadmap:
 ## References
 
 - Council session:
-  [`agents/council-sessions/2026-05-12-global-first-strategy/`](../../agents/council-sessions/2026-05-12-global-first-strategy/) <!-- council-ref-allowed: ADR decision trace -->
+  [`agents/runtime/council/sessions/2026-05-12-global-first-strategy/`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/) <!-- council-ref-allowed: ADR decision trace -->
 - User-scope discovery matrix sources: agent vendor official docs
   (Claude, Cursor, Windsurf, Cline, Augment, Copilot, Gemini, Aider,
   Codex) accessed 2026-05-12.

package/docs/decisions/ADR-008-installed-tools-manifest.md

@@ -20,7 +20,7 @@ Projektebene festhalten, welche Agents wir initialisiert haben, damit
 bei jedem Sync das Verzeichnis aktualisiert werden kann?" Validated
 through AI Council Round 1 (claude-sonnet-4-5 + gpt-4o, $0.0298 actual,
 both converged on "yes, separate file"). Council session:
-[`agents/council-sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/council-sessions/2026-05-12-project-settings-and-v1-v2/). <!-- council-ref-allowed: ADR decision trace -->
+[`agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/). <!-- council-ref-allowed: ADR decision trace -->
 
 ## Context
 
@@ -156,5 +156,5 @@ for this ADR.
 
 - [`ADR-007`](ADR-007-agent-discovery-scopes.md) — global-first install (this ADR depends on it).
 - [`agents/roadmaps/road-to-global-first-install.md`](../../agents/roadmaps/road-to-global-first-install.md) Phase 3.
-- [`agents/council-sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/council-sessions/2026-05-12-project-settings-and-v1-v2/) — full council transcripts. <!-- council-ref-allowed: ADR decision trace -->
+- [`agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/) — full council transcripts. <!-- council-ref-allowed: ADR decision trace -->
 - [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md) — the existing 4-layer settings precedence; this ADR adds a parallel file outside that hierarchy.

package/docs/decisions/ADR-010-profile-pack-preset-boundary.md

@@ -14,7 +14,7 @@ phase: v2.x · step-15 Phase 1 prerequisite
 
 **Proposed** · 2026-05-16 · pending Phase 1 of
 [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md).
-Council v3 action #2 (`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`): <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+Council v3 action #2 (`agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json`): <!-- council-ref-allowed: ADR decision-trace to originating council response -->
 **"Profile / Pack / Preset boundary is undefined; Phase 2 will duplicate
 Phase 1 abstractions"**. Promoted from Phase 2 to Phase 1 prerequisite —
 the profile loader (Phase 1 item 1) cannot ship without the boundary.
@@ -129,4 +129,4 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
 
 - [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `cost_profile` contract this ADR explicitly does **not** touch.
 - [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 items 1, 4 and Phase 2 item 7.
-- [`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/council-responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+- [`agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->

package/docs/decisions/ADR-011-domain-pack-readiness.md

@@ -14,7 +14,7 @@ type: prospective
 ## Status
 
 **Accepted** · 2026-05-17 · one-round council pass complete
-(`agents/council-responses/adr-011-domain-pack-readiness.json/debate-round-1.json`, actual spend $0.0300). <!-- council-ref-allowed: ADR decision trace; convergence summary inline in §Council-debate-trace -->
+(`agents/runtime/council/responses/adr-011-domain-pack-readiness.json/debate-round-1.json`, actual spend $0.0300). <!-- council-ref-allowed: ADR decision trace; convergence summary inline in §Council-debate-trace -->
 Split verdict — Anthropic accepted *with* tightened trigger; OpenAI
 accepted as written. The host folded Anthropic's structural critique
 into the trigger and added the escape clause both members' reasoning
@@ -88,7 +88,7 @@ no path changes, no symlink relocation, no namespace prefix:
   recorded in `persona-governance`)
 - `.agent-src.uncompressed/commands/video/{from-script,scene,storyboard,stitch}.md`
 - `scripts/ai-video/` (the 5 adapter scripts + `lib/`)
-- `agents/policies/media/` (Phase 2 output — already structured as
+- `agents/settings/policies/media/` (Phase 2 output — already structured as
   a project-local policy directory, *not* a pack)
 
 ### (ii) The trigger that flips this decision
@@ -148,7 +148,7 @@ for ambiguity:
   `higgsfield`, `sora`) — stay in `scripts/ai-video/`.
 - The two remaining video personas — stay in `.agent-src.uncompressed/personas/`.
 - The `/video:*` command cluster — stays in `.agent-src.uncompressed/commands/video/`.
-- The `media-governance-routing` rule + `agents/policies/media/`
+- The `media-governance-routing` rule + `agents/settings/policies/media/`
   policy files — stay where Phase 2 placed them.
 - The provider-lifecycle contract + the `provider-lifecycle-discipline`
   rule — stay where Phase 3 placed them.
@@ -185,7 +185,7 @@ treats as a smell.
 ## Council-debate trace
 
 One round · 2 members · actual spend $0.0300 · raw responses at
-[`agents/council-responses/adr-011-domain-pack-readiness.json/debate-round-1.json`](../../agents/council-responses/adr-011-domain-pack-readiness.json/debate-round-1.json). <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+[`agents/runtime/council/responses/adr-011-domain-pack-readiness.json/debate-round-1.json`](../../agents/runtime/council/responses/adr-011-domain-pack-readiness.json/debate-round-1.json). <!-- council-ref-allowed: ADR decision-trace to originating council response -->
 
 | Member | Pick | Core argument | Folded back? |
 |---|---|---|---|

package/docs/decisions/ADR-012-typescript-cli-shell.md

@@ -0,0 +1,162 @@
+---
+adr: 012
+status: accepted
+date: 2026-05-19
+decision: typescript-cli-shell
+supersedes: —
+superseded_by: —
+phase: v2.x · typescript-cli-and-local-gui-foundation
+type: prospective
+---
+
+# ADR-012 — TypeScript CLI Shell & Local Fastify Server
+
+## Status
+
+**Accepted** · 2026-05-19 · in-session council (8 items) +
+external `claude-sonnet-4-5` + `gpt-4o` pass (5 items, cost $0.16) on
+`agents/roadmaps/typescript-cli-and-local-gui-foundation.md`. All 13
+items folded into Phase 0–5a or carved with rationale below.
+
+## Context
+
+`@event4u/agent-config` is distributed as an npm package and consumed
+via `npx`. The current public entry point is `scripts/agent-config` —
+a 955-LOC Bash dispatcher that delegates to `scripts/_cli/cmd_*.py`.
+Two downstream roadmaps (`unified-setup-and-settings-gui`,
+`explainability-v2-explain-last`) need an embedded local HTTP server
+and a static UI bundle. Bash is the wrong substrate for that surface;
+Node is on every consumer's machine already because `npx` itself
+runs on Node.
+
+This ADR locks the dependency surface, the source layout, and the
+npm-package shape **before** any TypeScript is written. The Python
+engine, lint scripts, hooks, and `scripts/work_engine/` stay where
+they are — the TS layer is a thin distribution + UX shell that
+subprocess-invokes Python for heavy work.
+
+Related ADRs:
+
+- [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md)
+- [ADR-010 — Profile/Pack/Preset Boundary](ADR-010-profile-pack-preset-boundary.md)
+- [ADR-011 — Domain-Pack Readiness](ADR-011-domain-pack-readiness.md)
+
+## Decision
+
+### Runtime dependencies (frozen)
+
+| Package | Why chosen |
+|---|---|
+| `commander@^12` | Argv parsing; small footprint, zero transitive deps. |
+| `fastify@^5` | HTTP server; fast cold start, schema-first request validation. Bumped from v4 during Phase 1 install: v4 transitive `fast-uri` carries 5 high-sev advisories that block the `npm audit --audit-level=high` security gate. |
+| `@fastify/static@^9` | Static-file plugin for the built UI bundle. v9 fixes the `@fastify/static` path-traversal + route-guard-bypass advisories present in v7/v8. |
+| `open@^10` | Cross-platform "open URL in browser"; single function, near-zero deps. |
+| `zod@^3` | Runtime schema for IPC; reused by R2 GUI for settings validation. |
+| `execa@^9` | Subprocess wrapper around Python; stream pass-through, Windows-safe escaping, predictable exit-code propagation. |
+| `js-yaml@^4` | Read `.agent-settings.yml` from TS before delegating to Python. |
+
+### Dev dependencies (frozen)
+
+`typescript@^5.5`, `tsx@^4`, `vite@^5`, `vitest@^2`, `eslint@^9`,
+`@typescript-eslint/eslint-plugin@^8`, `@typescript-eslint/parser@^8`,
+`@types/node@^20`, `@types/js-yaml@^4`. No `ts-node`, no `nodemon`,
+no `webpack`, no direct `rollup`.
+
+### Forbidden in this roadmap
+
+`inquirer`, `prompts`, `chalk`, `ora`, `boxen`, anything that emits
+colour codes outside a TTY, anything pulling > 5 transitive deps.
+Rationale: keep the binary light enough for `npx` first-run feel.
+
+### Decision matrix
+
+| Concern | Candidates | Chosen | Why rejected (others) |
+|---|---|---|---|
+| Argv parser | commander · yargs · meow · native | **commander** | yargs: 13 transitive deps; meow: ESM-only quirks; native: too verbose. |
+| HTTP server | fastify · express · koa · native | **fastify** | express: legacy middleware shape, slower cold start; koa: smaller community for plugins we need; native: schema validation would be hand-rolled. |
+| Open in browser | open · opn (deprecated) | **open** | opn unmaintained. |
+| Subprocess | execa · node:child_process | **execa** | child_process: Windows escape tax + manual stream wiring; execa cost (~70 KB) is acceptable per roadmap Open Question 3, revisit on measurement. |
+| Schema | zod · joi · ajv-direct | **zod** | joi: heavier; ajv: lower-level; zod is shared with R2 GUI. |
+| Settings parse | js-yaml · yaml | **js-yaml** | yaml: stricter spec but slower for our shape; js-yaml is the de-facto standard. |
+| UI build | vite · esbuild · rollup | **vite** | esbuild lacks HTML entry; rollup needs hand-wired HTML plugin; vite handles `index.html` + `<script type="module">` natively. |
+
+### Source layout
+
+```
+src/
+  cli/
+    agent-config.ts            # bin entry (#!/usr/bin/env node)
+    paths.ts                   # package-root walk-up, src/dist resolver
+    commands/                  # one .ts per Tier-0/1/2 subcommand
+    python/
+      runPython.ts             # execa wrapper, stdio inherit
+      resolvePython.ts         # python3 / py / python detection
+    settings/readSettings.ts   # .agent-settings.yml (read-only)
+    log/logger.ts              # leveled logger, NO chalk
+  server/
+    app.ts                     # Fastify instance + route registration
+    port.ts                    # free-port picker (41000–41999)
+    auth/token.ts              # per-process token in ~/.event4u/agent-config/
+    routes/
+      ping.ts                  # GET /api/v1/ping
+  ui/
+    index.html                 # mount point only
+    main.ts                    # bundle entry (Vite)
+dist/
+  cli/                         # tsc output of src/cli + src/server
+  ui/                          # vite build output of src/ui
+```
+
+No `src/index.ts` god-file. No `src/utils.ts`. Path aliases via
+`baseUrl: "./src"` and `paths: { "@cli/*": ["cli/*"], "@server/*": ["server/*"] }`.
+
+### npm-package shape
+
+- `"bin"` points at `dist/cli/agent-config.js` — but **only** after
+  Phase 5b ships. This ADR lands with `"bin"` still pointing at the
+  Bash file; the TS binary is shipped alongside for shadow mode.
+- `"files"` adds `dist/`; keeps `scripts/agent-config`.
+- `"engines": { "node": ">=20.11.0" }` — Node 20 LTS minimum.
+- npm scripts: `build:cli`, `build:ui`, `build`, `typecheck`,
+  `lint:ts`, `test:ts`, `prepack` (runs `build` + asserts
+  `dist/cli/agent-config.js` exists and is executable). No
+  `postinstall`.
+
+### Local server security floor
+
+Per council `security-engineer` lens, `127.0.0.1` bind is necessary
+but not sufficient. Mandated controls:
+
+1. Bind only to `127.0.0.1` — any non-loopback attempt fails contract test.
+2. Reject `Host` headers other than `127.0.0.1:<port>` or `localhost:<port>` (status `421`).
+3. `Origin` allow-list: same-origin only (`null`, `127.0.0.1:<port>`, `localhost:<port>`).
+4. Per-process token written to `~/.event4u/agent-config/local-server.token` (mode `0600`), required as `Authorization: Bearer <token>` on every `/api/*` route. `/ping` is exempt for liveness probes.
+5. `npm audit --omit=dev --audit-level=high` runs in `task lint-ts` and blocks on regressions.
+
+## Consequences
+
+**Positive**
+
+- TS entry surface gives R2 (GUI) and R4 (explain) a real substrate.
+- Python becomes optional for Tier-0 commands (`versions`, `doctor`-fast-checks). Narrows the "Python required" surface to advanced subcommands.
+- Frozen dep list resists casual scope creep.
+- Token + Origin guard means the local server is safe even on a multi-user host.
+
+**Negative**
+
+- Node 20 LTS becomes a hard requirement for the published binary (Bash shim survives one minor cycle for users on Node < 20).
+- +400 KB tarball budget (compiled JS + Vite output).
+- Shadow-mode rollout (Phase 5a → 5b) costs one release cycle of dual-shipping.
+
+**Accepted as risk**
+
+- Embedding Fastify inside the CLI binary vs. splitting to a separate `@event4u/agent-config-ui` package (external reviewer's pushback). Rationale: ADR-012 + roadmap goal lock the embedded design as infrastructure reuse for R2/R4; revisit if R2 surfaces real integration friction.
+- `execa` install weight (~70 KB) over `node:child_process`. Decide via measurement in Phase 1, not now.
+
+## Council debate trace
+
+In-session (2026-05-18): `backend-architect`, `security-engineer`,
+`frontend-engineer`, `critical-challenger` — 8 items, all folded.
+External pass: `agents/runtime/council/responses/2026-05-18T*-r1-ts-cli-foundation/`
+— 5 items, all folded. Roadmap §"Council TODOs" lists every item
+with its target phase.

package/docs/decisions/ADR-013-discovery-frontmatter-contract.md

@@ -0,0 +1,210 @@
+---
+adr: 013
+status: accepted
+date: 2026-05-19
+decision: discovery-frontmatter-contract
+supersedes: —
+superseded_by: —
+phase: v2.x · automated-pack-workspace-and-skill-discovery Phase 0
+type: prospective
+---
+
+# ADR-013 — Discovery Frontmatter Contract
+
+## Status
+
+**Accepted** · 2026-05-19 · in-session + external AI Council pass complete
+(`agents/runtime/council/responses/2026-05-18T*-r3-automated-discovery/`). Cost: $0.19.
+The 5 external CRITICAL/HIGH items have been folded into Phases 1, 2, 3, 5
+of `agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md`
+(archived 2026-05-19, status: completed).
+
+## Context
+
+`event4u/agent-config` ships 218 skills, 72 rules, 129 commands, and 141
+templates as of `2.26.0`. Three downstream surfaces — the setup wizard
+(`unified-setup-and-settings-gui`), the agent-mode installer (`--agent`),
+and the strategic-visibility positioning lint
+(`strategic-visibility-mcp-topics-positioning`) — need to know **which
+workspaces and packs each artefact belongs to** without anyone manually
+maintaining the list.
+
+A release-time scan over artefact frontmatter is the cheapest source of
+truth. The scan emits a single `dist/discovery/discovery-manifest.json`
+shipped inside the npm tarball; every downstream surface reads from that
+file and from nothing else. This ADR locks the **frontmatter shape**, the
+**closed vocabularies**, and the **non-overlap rule** that keeps the new
+keys from colliding with the existing `cost_profile` / `profile.id` axes
+(ADR-010).
+
+### Why a closed vocabulary
+
+Free-form `domain:` (existing today) has 6 distinct values across 218
+skills — usable, but unenforced. Free-form `workspaces:` / `packs:`
+would degenerate into 30+ near-duplicate strings within one release
+cycle. The vocabulary is closed; amendments require an ADR-013
+amendment and a `lint_discovery_vocabulary.py` update in the same PR.
+
+### Why additive, not renaming
+
+`domain:` and `recommended_for_user_types:` exist on every annotated
+skill today. Renaming would force every consumer (router, skill linter,
+analysis pipeline) to retag at the same time. The new keys are
+**additive**: `workspaces:` and `packs:` live alongside `domain:`,
+the migration is mechanical (Phase 4 of the implementing roadmap), and
+no existing reader breaks.
+
+## Decision
+
+### Frontmatter shape — additive block
+
+```yaml
+# ── existing keys stay ──
+name: <slug>
+description: <one-liner>
+source: package
+domain: <existing free-form>   # untouched
+
+# ── new keys (additive; optional Phases 1–3, required Phase 4+) ──
+workspaces:
+  - engineering
+  - product
+packs:
+  - engineering-base
+lifecycle: active           # active | deprecated | experimental | archived
+trust:
+  level: core               # core | professional | experimental | advisory | restricted
+  confidence: high          # high | medium | low
+  human_review_required: false
+install:
+  default: true
+  removable: true
+```
+
+### Closed vocabulary — `workspaces:`
+
+| id | label | one-line definition |
+|---|---|---|
+| `engineering` | Engineering | Code, tests, CI, reviews, architecture. |
+| `product` | Product | Discovery, roadmaps, prioritisation, AC tightening. |
+| `finance` | Finance / CFO | Cashflow, forecasting, DCF, board reporting. |
+| `founder` | Founder | Strategy, fundraising, vision, board narrative. |
+| `gtm` | Go-to-Market | Sales pipeline, marketing, positioning, launch. |
+| `ops` | Operations | Hiring, comp, perf, org design, runbooks. |
+| `small-business` | Small Business | Self-employed / SMB-shaped owner workflows. |
+| `construction` | Construction | Trade-business workflows (planning, quotes). |
+| `agent-config-maintainer` | Maintainer | Skills/rules/commands that maintain *this* package. |
+
+Amendments to the workspace list require an ADR-013 amendment.
+
+### Closed vocabulary — `packs:`
+
+| id | description |
+|---|---|
+| `engineering-base` | Framework-neutral engineering hygiene (git, tests, reviews). |
+| `php` | PHP-language patterns (framework-free). |
+| `laravel` | Laravel framework; advisory hint depends on `php`, `engineering-base`. |
+| `symfony` | Symfony framework; advisory hint depends on `php`, `engineering-base`. |
+| `javascript` | JavaScript-language patterns. |
+| `typescript` | TypeScript-language patterns. |
+| `react` | React framework patterns. |
+| `nextjs` | Next.js framework patterns. |
+| `python` | Python-language patterns. |
+| `product-basic` | Core PO/PM artefacts (ticket refinement, AC, estimation). |
+| `product-discovery` | JTBD, interviews, VoC, hypothesis testing. |
+| `finance-basic` | Cashflow, runway, basic forecasting. |
+| `finance-advanced` | DCF, scenario modelling, comp banding. |
+| `gtm-sales` | Pipeline, MEDDIC, forecast accuracy. |
+| `gtm-marketing` | Positioning, messaging, editorial, content funnel. |
+| `ops-people` | Hiring loops, onboarding programs, comp banding. (Renamed from `ops` to honour the non-overlap rule against `profile.id: ops`.) |
+| `founder-strategy` | Vision, fundraising narrative, competitive moat. (Renamed from `founder` to honour the non-overlap rule against `profile.id: founder`.) |
+| `small-business` | SMB-shaped owner workflows. |
+| `construction` | Trade-business workflows. |
+| `ai-video` | AI video pipeline (per ADR-011, the only heavyweight domain). |
+| `meta` | Artefacts that maintain *this* package (`agent-config` itself). |
+
+Amendments to the pack list require an ADR-013 amendment and the
+matching `config/discovery/packs.yml` row in the same PR.
+
+### Non-overlap rule (ADR-010 alignment)
+
+- `cost_profile` values (`minimal`, `balanced`, `full`, `custom`) are
+  **not** pack ids. The scanner hard-fails on overlap.
+- `profile.id` values (`founder`, `developer`, `content_creator`,
+  `agency`, `finance`, `ops`) are **not** pack ids. The scanner
+  hard-fails on overlap. (Note: `founder`, `finance`, `ops` are
+  **workspace ids**; the collision check is against pack ids.)
+- `lint_discovery_vocabulary.py` enforces both checks at PR time.
+
+### Migration rule
+
+- **Phases 1–3** (implementing roadmap): artefacts without the new keys
+  are accepted; the scanner emits `unassigned[]` warnings; CI logs but
+  does not fail.
+- **Phase 4**: every artefact under
+  `.agent-src.uncompressed/{skills,rules,commands,templates}` either
+  declares the new keys, or sits in `config/discovery/unassigned-artefacts.yml`
+  with a one-line reason.
+- **Phase 4+**: CI flips strict; missing annotation is a fail.
+
+### Trust-root allow-list (security-engineer council fold-in)
+
+The scanner honours frontmatter only on files under the trusted roots:
+`.augment/`, `.claude/`, `.agent-src.uncompressed/`, `.agent-src/`.
+Files under `agents/`, `tmp/`, or any consumer-writable path **cannot**
+claim ownership of a workspace or pack. Phase 2 enforces.
+
+### Release-only manifest (external council CRITICAL fold-in)
+
+The manifest is built on `main` post-merge, never in PR CI. PR CI
+asserts the manifest is **absent** from the working tree, preventing a
+contributor from smuggling a pre-built manifest claiming
+`trust.level: core`. Phase 5 enforces.
+
+### Signing (security-engineer council fold-in)
+
+Phase 6 emits `discovery-manifest.json.sha256` alongside the manifest.
+The CLI verifies on first read; verification failure aborts before any
+discovery-driven action.
+
+## Consequences
+
+### Positive
+
+- One source of truth for workspaces/packs across wizard, agent-mode,
+  CLI, server route, and positioning lint.
+- Manifest extraction is mechanical when ADR-011's trigger flips; no
+  refactor of artefact bodies needed at that time.
+- Vocabulary drift is caught by lint, not by review-by-eye.
+
+### Negative
+
+- Every artefact author must learn 4 new keys (`workspaces`, `packs`,
+  `lifecycle`, `trust`, `install`). Mitigation: defaults documented in
+  Phase 4 mapping rules; one ADR amendment per new vocabulary entry.
+- A future "extract video into its own npm package" decision (ADR-011
+  trigger flip) inherits the manifest as scaffolding. Mitigation: the
+  manifest declares *labels*, not directory boundaries; extraction is
+  still a separate roadmap.
+
+### Risks accepted
+
+- **Free-form `domain:` stays alongside `workspaces:`.** Duplication
+  is intentional during the additive migration; a follow-up roadmap
+  may collapse them.
+- **`requires_hint:` on packs is advisory only.** The runtime does
+  not act on it. Acceptable for v1 per the council's "MEDIUM" note.
+
+## Cross-references
+
+- [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md):
+  the manifest path resolves against the **active scope** (project vs.
+  global), not against `cwd` alone.
+- [ADR-010 — Profile / Pack / Preset Boundary](ADR-010-profile-pack-preset-boundary.md):
+  this ADR touches the **pack axis only**; the non-overlap rule keeps
+  the other three axes intact.
+- [ADR-011 — Domain-Pack Readiness](ADR-011-domain-pack-readiness.md):
+  packs are **labels on in-repo artefacts**, not separately-installable
+  npm packages. Extraction stays blocked until ADR-011's trigger flips.
+- [Implementing roadmap (archived, status: completed)](../../agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md).
+- Schema artefact: [`docs/contracts/discovery-manifest.schema.json`](../contracts/discovery-manifest.schema.json).