@event4u/agent-config 2.26.0 → 3.1.0

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

@@ -0,0 +1,234 @@
+---
+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.
+
+## 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.uncompressed/{skills,rules,commands,templates}` by
+[`scripts/lint_artefact_frontmatter.py`](../../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).
+
+## 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

@@ -0,0 +1,136 @@
+---
+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

@@ -0,0 +1,146 @@
+---
+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
+> und Pack untersucht werden, so dass das für den Installer gespeichert
+> wird und zur Verfügung steht. Es soll keine manuelle Package &
+> Workspace Liste gepflegt werden.
+
+**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.uncompressed/`, **not** `.agent-src/`.
+The Phase-2 roadmap text §Phase 2 says "the compressed canonical tree"
+— that is a documentation slip. `augment-source-of-truth` rule states
+that uncompressed is canonical; the compressed 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.