@event4u/agent-config 9.8.0 → 9.10.0

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

@@ -1,342 +0,0 @@
----
-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 `rule_loading_tier` / `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). |
-| `legal` | Legal | In-house legal — contract/NDA/DPA review, privacy, legal triage (EU/DE scope). |
-| `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. |
-| `legal` | In-house legal — EU/DE-scoped contract/NDA/DPA review and legal triage; procedure-only, attorney-review draft output. |
-| `ai-video` | AI video pipeline (per ADR-011, the only heavyweight domain). |
-| `fun` | Non-essential social/fun workflows (prediction-pool tips, etc.). Optional under the `small-business` workspace; `experimental` trust. |
-| `meta` | Artefacts that maintain *this* package (`agent-config` itself). |
-| `git` | Git workflow — commit, pull requests, branch sync. Carries `slug_prefix: git` (ADR-044 §A3); `requires: engineering-base`. Added 2026-06-04 for 6.0.0-D Step 12 Class B1 (`commit`→`git-commit`, `create-pr`→`git-pr-create`). |
-| `frontend-design` | Grounded design intelligence — design-knowledge corpus + BM25 grounding engine, design tokens, stack best-practice and chart/typography knowledge. `requires: engineering-base`; `suggests: react, nextjs`. Added 2026-06-07 (ADR-061). |
-| `analysis-workbench` | RCA, post-mortem, premortem, decision-review as an integrated learning loop. `requires: engineering-base`; opt-in under the `engineering` workspace. Added 2026-06-15 (ADR-096). |
-| `brand` | Brand as a first-class UX layer — archetype/voice/identity grounding corpus, brand→token derivation, and consistency governance that constrains UI. `requires: frontend-design`; `suggests: ai-image`; opt-in under the `engineering` workspace. Added 2026-06-16 (road-to-image-brand-typography Phase B). |
-
-Amendments to the pack list require an ADR-013 amendment and the
-matching `src/config/discovery/packs.yml` row in the same PR.
-
-### Non-overlap rule (ADR-010 alignment)
-
-- `rule_loading_tier` 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.uncondensed/{skills,rules,commands,templates}` either
-  declares the new keys, or sits in `src/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.uncondensed/`, `.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.
-
-## Amendments
-
-### 2026-05-21 — Monorepo Phase 1 closure (enforcement live)
-
-The five required keys (`workspaces`, `packs`, `lifecycle`, `trust`,
-`install`) are now **strictly enforced** across every artefact under
-`.agent-src.uncondensed/{skills,rules,commands,templates}` by
-[`scripts/lint_artefact_frontmatter.py`](../../src/scripts/lint_artefact_frontmatter.py),
-wired into `task lint-artefact-frontmatter`, `task ci`, and the opt-in
-combined pre-commit hook (`./agent-config hooks:install`). The migration
-rule's "Phase 4+" strict flip described above is therefore in effect.
-
-Worked examples per artefact type live in
-[`docs/contracts/frontmatter-contract.md`](../contracts/frontmatter-contract.md);
-roundtrip stability across the `task sync` pipeline is guarded by
-`tests/test_frontmatter_roundtrip.py`.
-
-The Phase-1 roadmap initially proposed splitting the contract into a
-separate `ADR-014-frontmatter-v2-contract.md`. That split was dropped —
-this ADR remains the single source of truth and absorbed the worked
-examples instead. No ADR-014 issued.
-
-Driven by [`agents/roadmaps/monorepo-phase-1-frontmatter-metadata.md`](../../agents/roadmaps/monorepo-phase-1-frontmatter-metadata.md).
-
-### 2026-05-27 — Additive advisory `cluster:` key on packs
-
-Pack entries in [`src/config/discovery/packs.yml`](../../config/discovery/packs.yml)
-may carry an optional `cluster: <language-id>` field. It groups a framework
-pack under a programming-language tile in the setup wizard's capability-packs
-step (e.g. `laravel: cluster: php`, `react: cluster: typescript`). Like
-`requires_hint`, it is **advisory only** — the installer does not act on it; it
-drives the wizard UI's collapsible language→framework grouping. The value must
-be a known pack id (and not self-referential), enforced by
-[`scripts/lint_discovery_vocabulary.py`](../../src/scripts/lint_discovery_vocabulary.py)
-and emitted into the discovery manifest. Additive, no vocabulary rename.
-
-Driven by [`agents/roadmaps/road-to-wizard-ux-improvements.md`](../../agents/roadmaps/road-to-wizard-ux-improvements.md) § Phase 4 (AI-council-resolved: reuse `packs.yml` as the single source of truth rather than a second mapping file).
-
-### 2026-05-27 — Additive advisory `example_roles:` key on workspaces
-
-Workspace entries in [`src/config/discovery/workspaces.yml`](../../config/discovery/workspaces.yml)
-may carry an optional `example_roles: [<title>, …]` list of illustrative job
-titles (e.g. `engineering: [Developer, CTO]`, `finance: [CFO]`). The wizard's
-roles step shows the workspace as the *area* and these titles as examples under
-it. **Advisory and free-form** — NOT a closed vocabulary: the stored
-`.agent-user.yml` `role[]` is the workspace id, never these examples; nothing
-acts on the strings beyond display. Emitted into the discovery manifest;
-allowed by [`discovery-manifest.schema.json`](../contracts/discovery-manifest.schema.json).
-Additive, no vocabulary rename. (Same change cleaned the `finance` label from
-"Finance / CFO" to "Finance".)
-
-### 2026-06-01 — New `fun` pack
-
-Added pack id `fun` to the closed vocabulary (Non-essential social/fun
-workflows — prediction-pool tip optimization, etc.). Mirrored in
-[`src/config/discovery/packs.yml`](../../config/discovery/packs.yml) and the
-`ADR_PACKS` frozenset in
-[`scripts/lint_discovery_vocabulary.py`](../../src/scripts/lint_discovery_vocabulary.py).
-Optional under the `small-business` workspace (alongside `ai-video`);
-`trust_level_default: experimental`, `install.default: false`. First
-artefacts: the `/prediction-pool` command + `prediction-pool-optimizer` skill in
-`packages/pack-fun/`. Additive, no rename; non-overlap with cost-profile
-and `profile.id` reservations holds.
-
-### 2026-06-07 — New `frontend-design` pack
-
-Added pack id `frontend-design` to the closed vocabulary (grounded design
-intelligence — design-knowledge corpus + BM25 grounding engine, design tokens,
-stack best-practice and chart/typography knowledge, adopted from the MIT
-an external reference corpus per ADR-061). Mirrored in
-[`src/config/discovery/packs.yml`](../../src/config/discovery/packs.yml) and the
-`ADR_PACKS` frozenset in
-[`scripts/lint_discovery_vocabulary.py`](../../src/scripts/lint_discovery_vocabulary.py).
-`workspaces: [engineering]`, `requires: [engineering-base]`,
-`suggests: [react, nextjs]` (the corpus is stack-agnostic data — React is
-suggested, never required), `trust_level_default: professional`,
-`size_class: medium`. Council-resolved 2026-06-07 (anthropic/claude-sonnet-4-5 +
-openai/gpt-4o, converged A2: opt-in pack over inflating `engineering-base`
-with ~1 MB of design data). Additive, no rename; non-overlap with
-cost-profile and `profile.id` reservations holds.
-
-### 2026-06-16 — New `brand` pack
-
-Added pack id `brand` to the closed vocabulary (brand as a first-class UX layer
-— archetype/voice/identity grounding corpus, brand→token derivation, and
-consistency governance that constrains UI). Mirrored in
-[`src/config/discovery/packs.yml`](../../src/config/discovery/packs.yml) and the
-`ADR_PACKS` frozenset in
-[`scripts/lint_discovery_vocabulary.py`](../../src/scripts/lint_discovery_vocabulary.py).
-`workspaces: [engineering]`, `requires: [frontend-design]`, `suggests:
-[ai-image]` (pack-brand exports tokens, pack-ai-image consumes them — B → A),
-`trust_level_default: professional`, `size_class: medium`. Council-resolved
-2026-06-13 (road-to-image-brand-typography Phase B). Additive, no rename;
-non-overlap with cost-profile and `profile.id` reservations holds.
-
-### 2026-06-24 — New `legal` workspace + `legal` pack
-
-Added workspace id `legal` and pack id `legal` to the closed vocabularies
-(in-house legal — EU/DE-scoped contract/NDA/DPA review and legal triage;
-procedure-only, no default legal positions; every output a draft for attorney
-review). Mirrored in
-[`src/config/discovery/workspaces.yml`](../../src/config/discovery/workspaces.yml),
-[`src/config/discovery/packs.yml`](../../src/config/discovery/packs.yml), and the
-`ADR_WORKSPACES` + `ADR_PACKS` sets in
-[`src/scripts/lint_discovery_vocabulary.ts`](../../src/scripts/lint_discovery_vocabulary.ts).
-`workspaces: [legal]`, `domain: legal`, `size_class: medium`,
-`trust_level_default: experimental`, `surface_tier: lab` (gated lab-tier until the
-Gate-2 maintenance owner + external qualification is confirmed —
-road-to-legal-pack Phase 0.2). Council-resolved across three rounds 2026-06-24
-(road-to-legal-pack). Additive, no rename; non-overlap with cost-profile and
-`profile.id` reservations holds.
-
-### 2026-06-24 — Rename `legal` → `legal-review-prep` (workspace + pack)
-
-Renamed the workspace id and pack id `legal` → `legal-review-prep` in both
-closed vocabularies, the schema enums, and all artefacts (`src/domains/legal/`
-→ `src/domains/legal-review-prep/`, the five skill frontmatters, the
-`legal-safety-floor` rule). Driven by a deep AI-council (3 rounds,
-anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-06-24) + ~8 external
-7.1.0 reviewers: the name `legal` reads as "legal advice" and undermines the
-not-legal-advice positioning; `legal-review-prep` names the actual capability
-(prepare for attorney review). The `domain: legal` classifier and the `legal`
-user-type are a different axis and are unchanged. Rename, not additive;
-non-overlap reservations still hold. See `road-to-legal-review-prep` Phase 0.
-
-## 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).

package/docs/decisions/ADR-014-gui-framework-choice.md

@@ -1,136 +0,0 @@
----
-adr: 014
-status: accepted
-date: 2026-05-20
-decision: gui-framework-choice
-supersedes: —
-superseded_by: —
-phase: v2.x · unified-setup-and-settings-gui Phase 0
-type: prospective
----
-
-# ADR-014 — GUI Framework Choice (Preact + Signals)
-
-## Status
-
-**Accepted** · 2026-05-20 · in-session council recommendation folded.
-External AI Council pass on the implementing roadmap
-(`agents/roadmaps/unified-setup-and-settings-gui.md`) did not contest
-the framework choice; it focused on data integrity (atomic writes,
-optimistic locking) which is orthogonal to the rendering layer.
-
-## Context
-
-`unified-setup-and-settings-gui.md` introduces the first browser-facing
-surface of `@event4u/agent-config` — a local UI that doubles as a
-first-run wizard and a settings editor. The package is distributed via
-`npx`, so every byte of UI ships in the npm tarball and re-downloads on
-every fresh install. The wizard has **at most 8 screens**; the settings
-editor renders **one zod-derived form tree**. There is no router-driven
-deep navigation, no SSR, no SEO surface, no offline-first concern.
-
-Picking a heavyweight framework here would inflate the tarball with no
-proportional benefit and would make hand-off audits (a maintainer
-opening `src/ui/` cold) substantially harder. The choice is locked
-**now**, in this ADR, because Phase 2 onwards depends on the form
-primitives being written against a stable rendering API.
-
-## Decision
-
-**Preact 10 + `@preact/signals` for state.** Vite as the build tool
-(already in `package.json`). No router beyond a 1 KB hash-route
-helper. Plain CSS files with design tokens, no CSS-in-JS, no UI kit.
-
-### Decision matrix
-
-| Framework | Hello-world + 5 fields + wizard (gzip) | Forms ecosystem | TS support | Mental model | Verdict |
-|---|---|---|---|---|---|
-| **Preact + signals** | **~6 KB** | Manual primitives, ergonomic | Excellent | React-compatible | **Chosen** |
-| Svelte 5 (runes) | ~10 KB | Built-in form bindings | Good | Single-file components | Rejected: compiler magic harder to audit; smaller community for form libs vs Preact |
-| lit-html / Lit | ~7 KB | None — manual | Good | Web Components, shadow DOM | Rejected: shadow DOM complicates token-driven styling and a11y |
-| Vanilla + uhtml + mfsv | ~3 KB | None — bring your own | Manual | Tagged-template HTML | Rejected: 8 screens + multi-step form is the threshold where "bring your own" costs more than the saved KB |
-| React 18 + RSC-disabled | ~45 KB | Best-in-class | Excellent | Industry default | Rejected: 7× the bundle for the same JSX surface; over-spec for an `npx`-shipped UI |
-
-### Forbidden adds
-
-- **Routers heavier than `wouter-preact` / `preact-router`** (≤ 1 KB
-  gzipped). The UI has ≤ 8 screens; a 40 KB router is over-spec.
-- **CSS frameworks** — Tailwind, MUI, Chakra, Mantine, shadcn-ui.
-  Shipping 50 KB+ of CSS into an `npx`-installed binary is poor
-  stewardship. We ship hand-written CSS using design tokens (see
-  `src/ui/tokens.css`).
-- **State libraries beyond signals** — no Redux, no Zustand, no Jotai.
-  Signals are a built-in reactive primitive; the wizard's partial
-  state lives server-side in `wizard-state.json` anyway.
-- **SSR / streaming frameworks** — Next.js, Remix, SolidStart, Astro.
-  The server is local Fastify; the UI is a static bundle mounted
-  under `/`. No SSR concern exists.
-
-### Reactive state pattern
-
-```ts
-import { signal, computed } from '@preact/signals';
-
-const settings = signal<SettingsValues | null>(null);
-const isDirty = computed(() => /* compare against load-time snapshot */ false);
-```
-
-- **`signal`** holds the editable form values; component subtrees
-  re-render only on the signals they read.
-- **`computed`** derives the dirty flag, the diff preview, and the
-  per-field error map without prop-drilling.
-- No `useState` for cross-component shared state; only for local
-  ephemera (open/closed of a single modal, focus rings).
-
-### Build target
-
-- **ES2022**, native modules, no transpilation to ES5. The UI runs
-  in the developer's browser, which is always evergreen.
-- Vite builds emit `dist/ui/assets/*.js` + `*.css`; the Fastify
-  static handler serves them under `/`.
-- Bundle budget: **≤ 35 KB gzip** total (the wizard + the settings
-  editor combined). Enforced by `tests/ui/bundle-budget.test.ts` in
-  Phase 2. Breach is a CI fail, not a warning.
-
-### Testing stack
-
-- **Vitest 2.x** (already in `package.json`) + **happy-dom** for UI
-  unit tests. No Jest. No React Testing Library (Preact has
-  `@testing-library/preact` but we keep the primitives small enough
-  that direct DOM assertions suffice).
-
-## Consequences
-
-### Positive
-
-- Tarball stays under control: the entire GUI ships in < 50 KB gzip
-  of `dist/ui/` regardless of how many screens accumulate.
-- React-shaped JSX means contributors familiar with React onboard in
-  hours, not weeks.
-- Signals eliminate the prop-drilling overhead Form state would
-  otherwise require.
-- Zero CSS-in-JS keeps Vite's output predictable and lets a maintainer
-  grep `.css` files for token usage at audit time.
-
-### Negative
-
-- Preact's smaller ecosystem means **some** React-only libraries
-  (e.g. `react-hook-form`) cannot be reused without a shim. Mitigation:
-  we hand-write form primitives anyway per the "no UI kit" rule, so
-  the gap is theoretical for this scope.
-- Contributors who only know Vue or Svelte must learn Preact's
-  JSX-flavoured API. Mitigation: documented in `docs/architecture.md`
-  alongside the existing TS-CLI onboarding notes.
-
-### Risks accepted
-
-- **No React migration path is preserved**. If a future roadmap needs
-  RSC, streaming, or React-only libraries, the UI is rewritten end-to-
-  end. Acceptable because the UI is feature-bounded (wizard + settings)
-  and any RSC-shaped future is a different product.
-
-## Cross-references
-
-- [Implementing roadmap](../../agents/roadmaps/unified-setup-and-settings-gui.md).
-- [ADR-012 — TypeScript CLI Shell](ADR-012-typescript-cli-shell.md): the host server that mounts this UI.
-- [ADR-013 — Discovery Frontmatter Contract](ADR-013-discovery-frontmatter-contract.md): the discovery manifest the GUI reads to render workspace / pack pickers in a future phase.

package/docs/decisions/ADR-015-discovery-manifest-contract.md

@@ -1,146 +0,0 @@
----
-adr: 015
-status: accepted
-date: 2026-05-21
-decision: discovery-manifest-contract
-supersedes: —
-superseded_by: —
-phase: v2.x · monorepo-phase-2-virtual-packs-discovery Phase 1
-type: prospective
----
-
-# ADR-015 — Discovery Manifest Contract
-
-## Status
-
-**Accepted** · 2026-05-21 · in-session AI Council pass. Folds the Phase-2
-intake invariant (`agents/tmp/refactor-package.txt`, last paragraph) and
-the additive-vs-rewrite call into the schema. Phase-1 prerequisite for
-[`monorepo-phase-2-virtual-packs-discovery`](../../agents/roadmaps/monorepo-phase-2-virtual-packs-discovery.md).
-
-## Context
-
-[ADR-013](ADR-013-discovery-frontmatter-contract.md) locked the five
-per-artefact frontmatter keys. The release pipeline now needs a single
-JSON contract — `dist/discovery/discovery-manifest.json` — that the
-TypeScript installer (Phase 3), the browser wizard (Phase 6), the docs
-site, and any third-party consumer read instead of walking the source
-tree. The invariant from the founder intake:
-
-> Beim Erstellen eines Releases müssen alle Skills, etc. nach Workspace  <!-- md-language-check: ignore -->
-> und Pack untersucht werden, so dass das für den Installer gespeichert  <!-- md-language-check: ignore -->
-> wird und zur Verfügung steht. Es soll keine manuelle Package &  <!-- md-language-check: ignore -->
-> Workspace Liste gepflegt werden.  <!-- md-language-check: ignore -->
-
-**No manual list. Ever.** The pack and workspace shape grows by stamping
-frontmatter, not by editing a list.
-
-A v1 manifest schema already lives at
-[`docs/contracts/discovery-manifest.schema.json`](../contracts/discovery-manifest.schema.json)
-(carried over from the archived R3 discovery roadmap). The Phase-2
-roadmap §"Manifest shape" sketched an *ideal* shape that differs from
-the on-disk schema in several places (per-artefact `checksum`,
-optional `requires`, a `stats` block). The decision is whether to
-rewrite the schema or extend it additively.
-
-## Decision
-
-**Extend the v1 schema additively.** Three changes, no removals, no
-field renames, version stays `1`:
-
-1. **`artefact.checksum`** — `sha256:<hex>`, REQUIRED. Computed over the
-   on-disk file bytes after frontmatter normalization (sorted keys,
-   trailing newline). Drift detector for the Phase-3 installer.
-2. **`artefact.requires`** — `array<pack_id>`, OPTIONAL. Pack-level
-   dependency edges resolved by the installer; empty/absent means the
-   artefact has no extra pack requirements beyond its own `packs[]`.
-3. **`stats`** — REQUIRED top-level object. `total_artefacts`,
-   `by_category`, `by_lifecycle`, `by_trust_level`. Cheap sanity surface
-   for `task discovery-stats` + downstream dashboards.
-
-The Phase-2 roadmap's example also mentioned `id`, `owner`, and
-`install.managed`. **Not adopted.** The path is the canonical artefact
-identity (matches ADR-013), ownership is already encoded in
-`workspaces[]` + `packs[]`, and `install.managed` adds a third
-install-axis without a current consumer. Re-evaluate in Phase 5.
-
-### Source-of-truth tree
-
-The generator walks `.agent-src.uncondensed/`, **not** `.agent-src/`.
-The Phase-2 roadmap text §Phase 2 says "the condensed canonical tree"
-— that is a documentation slip. `source-of-truth` rule states
-that uncondensed is canonical; the condensed tree is a build output
-and may be regenerated. Manifest pipelines that read build outputs are
-fragile to bootstrap order.
-
-### No git in the manifest
-
-The roadmap example included `source_commit`. **Not adopted.** The
-existing `scanner_version` (first 12 hex of `sha256(build_discovery_manifest.py)`)
-already pins generator identity. Embedding `git rev-parse HEAD` breaks
-hermetic determinism tests in environments without a git checkout
-(CI shallow clones, vendor tarballs). A consumer that needs the commit
-can pin from the surrounding release artefact (changelog, tag).
-
-## Consequences
-
-### Positive
-
-- Existing consumers (the Phase-1 linter, the round-trip test, the
-  `lint_discovery_manifest.py` validator) keep working — top-level
-  `version` stays `1`, all v1 fields stay required.
-- Per-artefact `checksum` makes the Phase-3 installer drift-detection
-  trivial — one hash compare per file.
-- `requires` is opt-in: artefacts that don't need cross-pack deps cost
-  zero extra bytes.
-- Stats are computed from the artefact list — no second walk of the
-  tree, no risk of stats/list desync.
-
-### Negative
-
-- Every artefact entry grows by ~80 bytes (the checksum). For ~420
-  artefacts, the manifest grows ~33 KB. Acceptable.
-- The first build after this ADR rewrites every artefact entry; the
-  diff is large. Reviewed once and committed.
-
-### Neutral
-
-- `version` stays `1`. A future breaking change (rename `packs` to
-  `pack_ids`, drop `unassigned`, etc.) bumps to `2`. This ADR sets the
-  precedent that **additive** changes do not bump.
-
-## Determinism contract
-
-Two builds of the same source tree MUST produce byte-identical JSON
-when `generated_at` is normalized. Specifically:
-
-- All arrays sorted (`artefacts` by `path`, `workspaces`/`packs` in
-  vocabulary order, `requires`/`workspaces[]`/`packs[]` per-entry sorted).
-- JSON serialized with `sort_keys=True`, `indent=2`, trailing newline.
-- The global `checksum` covers the manifest minus `generated_at` and
-  itself (zeroed during hash input).
-- Per-artefact `checksum` covers the file content with frontmatter
-  normalized (sorted keys, trailing newline, no trailing whitespace).
-
-## Failure modes guarded against
-
-- **Manual drift** — no pack list to hand-edit; new packs/workspaces
-  enter via frontmatter stamps on artefacts.
-- **Stale manifest in release** — Phase 3 ships `task validate-discovery-manifest`
-  which re-builds to a tempdir and `diff`s against the committed file.
-- **Checksum collision with content edits** — per-artefact `checksum`
-  surfaces any file mutation; the installer can refuse to overwrite a
-  user-modified artefact (Phase 3).
-- **`version: 1` reused for breaking changes** — this ADR explicitly
-  scopes `version: 1` to additive evolutions; breaking → bump + new ADR.
-
-## References
-
-- [ADR-013](ADR-013-discovery-frontmatter-contract.md) — frontmatter
-  contract (the input side of this manifest).
-- [`docs/contracts/discovery-manifest.schema.json`](../contracts/discovery-manifest.schema.json)
-  — the locked schema.
-- [`docs/contracts/discovery-manifest.md`](../contracts/discovery-manifest.md)
-  — worked examples + consumer guide.
-- [`agents/roadmaps/monorepo-phase-2-virtual-packs-discovery.md`](../../agents/roadmaps/monorepo-phase-2-virtual-packs-discovery.md)
-  — the implementing roadmap.