@event4u/agent-config 9.8.0 → 9.9.0

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

@@ -1,213 +0,0 @@
----
-adr: 011
-status: accepted
-date: 2026-05-17
-decision: domain-pack-readiness
-supersedes: —
-superseded_by: —
-phase: v2.x · universal-platform-refinement Phase 6
-type: prospective
----
-
-# ADR-011 — Domain-Pack Readiness
-
-## Status
-
-**Accepted** · 2026-05-17 · one-round council pass complete
-(`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
-implied. Trace under §Council-debate-trace.
-
-## Context
-
-`event4u/agent-config` shipped its first heavyweight domain capability
-in PR #176 (AI Video Pipeline, merged at `2.24.0`): 5 provider
-adapters, 3 personas, 5 skills, the `/video:*` command cluster, a
-Banana-Arc pixel-similarity regression harness, secret redaction at
-every adapter boundary, and 50 roadmap steps clean. The strategic
-review that followed gave the work `8.9 / 10` overall (engineering
-`9.7`, governance `9.2`, UX `10`) but flagged scope discipline at
-`6.8 / 10` and named a `8.9 → 9.6` target delta. The named gap is
-*not* engineering — it is the positioning / role-guide / rule-layer
-surface that did not catch up to the new capability. The current
-roadmap (`universal-platform-refinement`) closes that gap in Phases
-1–5; Phase 6 records the *non-extraction* decision so the deferral is
-auditable.
-
-The pressure to extract video into a separately-installable
-"domain pack" comes from three places:
-
-1. The strategic review's `8.9 → 9.6` argument — "make the future
-   audio / image / docs / exports domains land cheaply". Cited at
-   `agents/roadmaps/universal-platform-refinement.md` lines 19 and 132.
-2. PR #176's scope-discipline score (`6.8 / 10`) — the load-bearing
-   data point against premature extraction. Cited at line 19, 117.
-3. The predecessor council's explicit rejection of milestone-split
-   shipping of the video pipeline. Trace:
-   [`archive/ai-video-pipeline.md` § Divergences (no consensus)](../../agents/roadmaps/archive/ai-video-pipeline.md#L162-L164):
-   *"Single-PR vs. milestone split — Reviewer B recommended splitting
-   into milestone PRs; Sonnet R3 and GPT-4o final pass both reject
-   this, citing the roadmap's explicit single-PR iron constraint and
-   the dead-code risk of partial states. Host: the iron constraint
-   stands."* Same reasoning applies one level up: extracting video
-   today creates a domain-pack abstraction with no peer to share with
-   and a dead-code risk in the not-yet-built domains.
-
-The repository currently has exactly **one** heavyweight domain
-(video). Audio, image, docs, and exports are named future concerns —
-none is built. An abstraction whose only consumer is the abstraction
-itself is a structural liability, not an asset.
-
-## Decision
-
-> **The platform stays thin-root and ships future domains (audio,
-> image, docs, exports) as in-repo capability bundles, not as
-> separately-installable packs, until at least two independent
-> domains exist with overlapping execution surfaces.**
-
-"Overlapping execution surfaces" means shared code beyond the kernel
-+ router — e.g. two adapters that both implement the four-method
-shell contract, two skill clusters that both consume the
-`media-governance-routing` rule, two domains that both need
-provider-lifecycle tiering. The video adapters alone do not satisfy
-this — they are a single execution surface.
-
-## Consequences
-
-### (i) What stays under `.agent-src.uncondensed/` today
-
-The complete video capability stays in the existing flat layout —
-no path changes, no symlink relocation, no namespace prefix:
-
-- `.agent-src.uncondensed/skills/{character-consistency,motion-choreographer,pixar-storyteller,scene-expander,video-director}/`
-- `.agent-src.uncondensed/personas/{ai-video-technical-director,hollywood-director}.md`
-  (the third video persona, `pixar-storyboard-artist`, was folded
-  into `skills/pixar-storyteller/` per the persona-cap council pass
-  recorded in `persona-governance`)
-- `.agent-src.uncondensed/commands/video/{from-script,scene,storyboard,stitch}.md`
-- `scripts/ai-video/` (the 5 adapter scripts + `lib/`)
-- `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
-
-The non-extraction stance is **falsifiable**. The trigger is split
-into a *design gate* (fires before domain 2 is built) and two
-*confirmation gates* (fire after domain 2 ships) — sequenced this way
-to avoid the "two-domain monolith" trap the council flagged in
-round 1 (Anthropic, Option 2): if condition 1 only fires *after*
-domain 2 is built, the shared infrastructure is already entangled
-and extraction is materially harder than predicting overlap in
-advance.
-
-**Design gate (fires BEFORE domain 2 implementation starts):**
-
-1. **Overlap-prediction document.** Before the first commit on a
-   second heavyweight domain (audio, image, docs, exports, or other),
-   write `docs/contracts/domain-pack-overlap-inventory.md` listing
-   ≥ 3 structural patterns *predicted* to be shared between video
-   and the new domain (e.g. shared adapter contract, shared
-   governance routing, shared provider-lifecycle declaration, shared
-   persona-cap policy). Each prediction includes a falsifiable test
-   that confirms or refutes it after domain 2 ships. If ≥ 3 testable
-   predictions cannot be written, the domain is not yet a candidate
-   for shared abstraction — build it in-repo, revisit when patterns
-   emerge.
-
-**Confirmation gates (fire AFTER domain 2 ships):**
-
-2. **Heavyweight-domain landing.** A second domain has landed in
-   `main` matching the PR #176 shape: adapter cluster + skill
-   cluster + command cluster + governance rule + policy directory.
-   One-skill additions do not count.
-3. **Shared-abstraction stability.** The patterns named in the
-   prediction document have shipped without breaking changes for at
-   least one minor release. Stability proves the predictions were
-   real, not refactoring churn.
-
-**Escape clause (Anthropic round-1 critique, folded back):** if all
-three gates fire and extraction is then judged "too expensive" by
-the team, **this decision was wrong**. Re-open the ADR and record
-the failure mode — the trigger structure is one-way unless this
-clause is honoured. Without it, the ADR becomes a one-way door
-disguised as a two-way door.
-
-The placeholder roadmap
-[`agents/roadmaps/domain-pack-extraction-when-triggered.md`](../../agents/roadmaps/domain-pack-extraction-when-triggered.md)
-holds the marker; status `draft` keeps it dashboard-suppressed until
-the design gate fires.
-
-### (iii) What is **not** extracted today
-
-Explicitly enumerated so a future reader does not mistake silence
-for ambiguity:
-
-- The five video adapters (`gemini-veo`, `kling`, `openai-images`,
-  `higgsfield`, `sora`) — stay in `scripts/ai-video/`.
-- The two remaining video personas — stay in `.agent-src.uncondensed/personas/`.
-- The `/video:*` command cluster — stays in `.agent-src.uncondensed/commands/video/`.
-- 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.
-- The three Phase 4 test files (`tests/test_ai_video_blueprint_schema.py`,
-  `test_prompt_optimization.py`, `test_ai_video_adapter_contract.py`)
-  — stay in the root `tests/` tree.
-
-## Alternatives Considered
-
-### A) Extract video into `agents/domain-packs/ai-video/` today
-
-Rejected. The extraction creates an abstraction with no peer, so the
-shape of the pack interface is determined by exactly one consumer.
-When the second domain arrives, the interface is likely wrong (cited
-predecessor council reasoning on milestone-split: dead-code risk of
-partial states). The strategic review's `8.9 → 9.6` argument is
-**real** but **not unlocked by extracting today** — see roadmap §Notes
-line 132.
-
-### B) Ship the placeholder roadmap as `proposed` instead of `draft`
-
-Rejected. A `proposed` roadmap appears in the dashboard and creates
-implicit pressure to schedule it. A `draft` marker keeps the trigger
-visible to future maintainers without scheduling work that depends
-on conditions that do not yet hold.
-
-### C) Pin a date for re-evaluation
-
-Rejected. The trigger is structural (two domains + overlap inventory),
-not temporal. Pinning a date (e.g. "review 2027-Q1") replaces a
-condition-based gate with a calendar-based one, which `no-roadmap-references`
-treats as a smell.
-
-## Council-debate trace
-
-One round · 2 members · actual spend $0.0300 · raw responses at
-[`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? |
-|---|---|---|---|
-| `anthropic/claude-sonnet-4-5` | **Option 2** (accept with tightened trigger) | Trigger as originally written is waterfall-sequenced (build → discover → stabilise) — condition 1 only fires *after* domain 2 is built, creating the "two-domain monolith" trap. Fix: move overlap-prediction to a *design gate* before domain 2 implementation, plus add an escape clause naming the failure mode when extraction is later judged too expensive. | **Yes** — Consequences §(ii) split into design gate + confirmation gates; escape clause added verbatim. |
-| `openai/gpt-4o` | **Option 1** (accept as written) | Triggers are structural, not temporal — appropriate guard against premature abstraction. Secondary signal worth tracking: developer-sentiment / community feedback on perceived lack of shared infrastructure. | **Partial** — host did not promote qualitative signals to gates (would conflict with the "structural, not temporal" principle both members affirmed), but the escape clause covers the team-cost case Anthropic named and OpenAI implied. |
-
-### Host verdict
-
-Anthropic's structural critique is load-bearing: the original trigger
-was sequenced as a waterfall where the gating condition could not be
-checked until after the gate had implicitly been passed. The fix —
-moving overlap-prediction to a design-stage document — is a strict
-improvement that costs nothing today (no domain 2 exists; no design
-gate to clear). Folding the escape clause closes the one-way-door
-risk both members' reasoning pointed at, even though only Anthropic
-named it explicitly.
-
-OpenAI's qualitative-signal point is noted but not promoted to a
-gate: every "is the lack of shared infrastructure slowing us down?"
-question is answerable by writing the overlap-prediction document
-and seeing whether ≥ 3 testable predictions emerge. The design gate
-absorbs the qualitative signal into a structural check.
-
-Status: `proposed → accepted` with the council-driven trigger
-revision and escape clause in place.

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

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