@event4u/agent-config 9.7.0 → 9.9.0

package/docs/decisions/ADR-109-subagent-v1-contract.md

@@ -1,246 +0,0 @@
----
-adr: 109
-status: accepted
-date: 2026-07-04
-decision: subagent-v1-contract
-supersedes: —
-superseded_by: —
-phase: road-to-final-state-and-market-readiness
-type: standing
----
-
-# ADR-109 — The `subagent-v1` contract (new discovery category, default-off, static projection)
-
-## Status
-
-**Accepted** · 2026-07-04 · maintainer decision after an AI-council debate
-(claude-sonnet-4-5 + gpt-4o, 2 rounds). Track A keystone (A1) of
-`road-to-final-state-and-market-readiness.md`.
-
-## Context
-
-Track A adds a **capability** layer: named subagent units that a host can invoke
-as distinct, tool-scoped execution contexts (Claude Code's `.claude/agents/`).
-The wedge — `production-validator` — already ships hand-written in that native
-format. A1 turns that one hand-written file into a governed, projected artifact
-type without breaching the no-runtime identity floor (no daemon, no auto-write,
-no in-process swarm, no dispatch we enforce).
-
-The council was asked to converge the contract shape. Both members agreed on the
-category and the schema completeness; the residual dissent was a documentation
-nuance (don't over-claim cross-host equivalence), folded in below.
-
-## Decision
-
-### 1. A new discovery category `subagent` (not `agent`, not a persona subtype)
-
-- **Name `subagent`.** `agent` is overloaded (the host is "the agent"; this
-  package is "agent-config"). `subagent` = a subordinate, delegated, addressable
-  execution context.
-- **A distinct category, not a persona subtype.** Personas are reference lenses
-  projected as *context* for a single session; a subagent is an *addressable
-  execution context* with its own tool manifest and model. Folding subagents into
-  personas would force every persona to grow a `tools` field it ignores, or add
-  subtype-specific projection logic (a parallel schema inside one category). The
-  categories today are `['skill', 'rule', 'command', 'template']`; `subagent`
-  becomes the 5th.
-
-### 2. Source schema `subagent-v1` (governance fields REQUIRED, not optional)
-
-```yaml
-schema_version: subagent-v1
-name: <handle>                      # REQUIRED — matches filename stem, addressable
-description: <one line>             # REQUIRED — user-facing summary
-model_tier: high|medium|lite|inherit  # REQUIRED — reuses model_tier.ts; `inherit` is a
-                                      #   documented passthrough sentinel (→ CC `model: inherit`),
-                                      #   NOT a new tier→model mapping
-tools: [Read, Grep, Glob, Bash, …]  # REQUIRED — enum-validated against the CC tool set
-trust: {level, confidence, human_review_required}  # REQUIRED — mirrors the skill trust block (ADR-013)
-lifecycle: active|deprecated|experimental|archived # REQUIRED — reuse the existing lifecycle enum
-discovery:
-  visible: false                    # REQUIRED — default-off; linter enforces `false`
-  requires_capability: <cap>        # REQUIRED — host-capability gate (e.g. claude_subagents)
-  categories: [<tag>, …]            # OPTIONAL — pack-include tags
-```
-
-Body: a free-form Markdown system prompt (like personas). Governance fields are
-**required** — optional governance would create a two-tier system (governed
-legacy artifacts vs. ungoverned subagents), which breaks trust filtering and the
-"governed config layer" promise. The source carries governance metadata that
-does **not** project to `.claude/agents/` (CC has no such fields) but does drive
-discovery filtering, docs generation, and cross-host warnings.
-
-**Banned fields (would imply runtime we do not have):** `auto_invoke_on`,
-`max_iterations`, `timeout`, `cost_limit`, `memory_strategy`, `delegates_to`.
-
-### 3. Native-Claude-Code translation
-
-Projected file: `.claude/agents/<name>.md` with frontmatter `{name, description,
-tools, model}` + the body. `model` is derived from `model_tier` by **reusing**
-`src/scripts/_lib/model_tier.ts` (`TIER_TO_CLAUDE_MODEL`: high→opus, medium→sonnet,
-lite→haiku); `model_tier: inherit` projects to `model: inherit` (passthrough).
-No new mapping is invented (ADR-034/035 stands).
-
-### 4. Cross-host degradation (host-agnostic, honestly limited)
-
-Only Claude Code has native subagents. Elsewhere a subagent projects to a
-**loadable context file**, gated by `requires_capability`:
-
-| Host | Projection | Invocation |
-|---|---|---|
-| Claude Code | `.claude/agents/<name>.md` | `@<name>` (host-native) |
-| Cursor / Windsurf / Cline | context file the host can load on intent | manual — **no `@`-dispatch** |
-| Copilot / Gemini | skipped (no context surface) | — |
-
-**Honest limitation (published, per the package's own honesty floor):** on
-non-Claude-Code hosts the artifact degrades to *passive reference* — the system
-prompt is available, but there is no host-native dispatch. This is **governance
-parity, not feature parity**: trust / lifecycle / model-tier apply uniformly; the
-automation does not. We do not fake dispatch (that would need a runtime we refuse
-to add).
-
-**Implementation (`generate_subagent_host_contexts`, condense.ts).** The non-CC
-projection emits a passive-reference context file carrying the honest no-dispatch
-banner + a governance block (trust level / lifecycle / model tier / tools) + the
-body verbatim, reaper-safe per host:
-
-- Cursor → `.cursor/subagents/<name>.md`; Windsurf → `.windsurf/subagents/<name>.md`
-  (dedicated subdir with its own reaper — no collision with the aggressive
-  `_clean_modern_dir` rule reapers).
-- Cline → `.clinerules/<name>.subagent.md` (a real file; that dir's reaper only
-  unlinks symlinks, so it survives).
-- Copilot / Gemini → skipped (no per-file context surface).
-
-Council (claude-sonnet-4-5 + gpt-4o, 2026-07-05) converged on *project the file*
-over honest-null: the body is ~95% reusable review discipline and ~5% dispatch
-syntax, so an advanced user loads it on intent and applies the discipline
-manually. No ADR amendment was needed — this realises the §4 table as written.
-
-### 5. Default-off + non-dispatch (mechanical)
-
-- **Default-off** = `discovery.visible: false` (required; linter enforces the
-  value is `false`). No glob pulls subagents; a pack opts in explicitly via
-  `include: ["subagent:<name>"]` or `include: ["subagent:category:<tag>"]`.
-- **Non-dispatch is free.** We have no runtime; we only project a file. The host
-  (or the user via `@<name>`) decides invocation. No `auto_dispatch` flag exists
-  (it would imply `true` is possible — it is not).
-
-### 6. Determinism / lint guarantees (part of A1)
-
-- `tools` validated against the CC tool enum — build-time failure, never a broken
-  `.claude/agents/` YAML in the user's IDE.
-- `model_tier` validated against `model_tier.ts` (+ the `inherit` sentinel).
-- `name` globally unique within the `subagent` category (projection-path
-  collision guard), matching the filename stem.
-- `discovery.visible` must be present and `false`.
-
-### 7. Explicitly cut from v1
-
-Multi-subagent orchestration (`delegates_to`), custom tool definitions, and
-per-artifact `supported_hosts` lists (use `requires_capability` + a central
-capability matrix instead). Revisit only in a `subagent-v2` if evidence demands.
-
-## Consequences
-
-- A 5th discovery category, one new schema, one source location (`src/subagents/`),
-  a translation step, and lint rules — all additive; existing categories untouched.
-- `production-validator` becomes the first `src/` subagent unit and the single
-  source of truth for the wedge (the hand-written `docs/wedge/` copy is superseded
-  by projection).
-- **Gate A still governs shipping:** a unit is default-off and ships as
-  recommended-opt-in **only** if the A3 eval (on `internal/bench/orchestration/`)
-  beats both baselines at acceptable token cost; otherwise it stays in `src/` as a
-  documented honest-null. This ADR defines the *contract*, not a promotion.
-
-## Alternatives considered
-
-- **Persona subtype** — rejected: semantic dilution + schema creep (tools field on
-  all personas, or subtype-specific projection).
-- **Optional governance fields** — rejected: creates ungoverned-by-default
-  artifacts, breaking the trust model (council round 2, decisive).
-- **CC-only (no degradation)** — rejected: violates host-agnostic positioning; a
-  CC-locked artifact is Claude Code config that wandered into the repo.
-- **Faked dispatch on non-CC hosts** — rejected: runtime cosplay we cannot honor.
-
-## Amendment 1 (2026-07-04) — discovery-manifest integration = Option B
-
-The original decision left *how* subagents join the discovery manifest open. A
-follow-up council (claude-sonnet-4-5 + gpt-4o, 2 rounds) surfaced the concrete
-gap: the manifest's `_classify` requires `workspaces` / `packs` / `install`,
-which this contract's minimal schema deliberately omits. Both members converged
-on **Option B**:
-
-- Add `subagent` to `_CATEGORY_VALUES` + `_CATEGORY_SCHEMA` + the `_iter_artefacts`
-  glob (`src/subagents/*.md`), and give `_classify` a **subagent branch** that
-  derives the manifest payload from the subagent-v1 fields:
-  `install: {default: false, removable: true}` (default-off), `packs: []`,
-  `workspaces: []`, plus `lifecycle` + `trust`.
-- **`packs: []` is legitimate** — "recommended for no pack; included only via
-  `include: ["subagent:<name>"]`". The "every artefact belongs to ≥1 pack"
-  invariant becomes "every artefact **except subagents**". Verified safe: every
-  manifest consumer of `.packs` already guards against empty
-  (`check_condensation`, `install`, `condense`, `lint_trust_coherence`), and
-  `lint_artefact_frontmatter` does not scan `src/subagents/`.
-- The `discovery-manifest.schema.json` `category` enum + `by_category` gain
-  `subagent`; the `workspaces`/`packs` `minItems: 1` is relaxed to a documented
-  note (non-emptiness for real categories stays enforced by `_classify`).
-
-**Rejected:** Option A (extend the schema with workspaces/packs/install →
-duplicate visibility source, de-facto ADR reversal) and Option C (keep subagents
-out of the manifest + a parallel name-resolver → duplicate load/parse/validate
-pipeline; LSP/tooling would need two discovery paths). "5th discovery category"
-is manifest terminology, so Option B satisfies A1 literally.
-
-The manifest (`dist/discovery/discovery-manifest.json`) is a **gitignored** build
-artifact — CI rebuilds it fresh, so this is a generator + schema change, not a
-committed-data change.
-
-## Amendment 2 (2026-07-05) — consumer distribution = wedge-only (A2)
-
-How subagents reach **consumers** (as opposed to the in-repo `.claude/agents/`
-projection): a fresh council (**claude-fable-5 + gpt-4o**, 2 rounds) converged on
-**wedge-only distribution**, reversing an earlier "synthesis" lean once the
-implementation blast-radius evidence was in hand.
-
-- **Decision:** subagents reach consumers ONLY via the wedge
-  (`docs/wedge/<name>/<name>.md`, shipped in npm `files[]` via `docs/`, installed
-  by a 30-second `curl` into `.claude/agents/`). They are **not** condensed to
-  `dist/`, **not** in the install bundle, and **not** in the shared source
-  enumeration (`_root_specs()` / `iter_all_sources` / `resolve_logical`).
-- **Why not ship in dist (the rejected synthesis):** `condense.cleanup_stale()`
-  deletes any `dist/agent-src/` file that does not round-trip through
-  `resolve_logical()`, so shipping subagents in dist requires teaching the shared
-  `_root_specs()` about them — a cross-cutting change to ~10 consumers
-  (`build_discovery_manifest`, three frontmatter/pack linters, namespace checks,
-  …). Exclusion-based containment would produce a **shipped-but-ungoverned**
-  executable-prompt class — for a *governed* config layer, worse than the blast
-  radius it hides. Marginal consumer value at n=1 unit ≈ one fewer curl for an
-  opt-in, high-trust artifact — not worth it. Revisit only at n≥3 units **and** a
-  documented curl-distribution failure signal.
-- **The wedge doc is now a projection of `src/subagents/`** (superseding the
-  hand-written copy), regenerated from `generate_claude_subagents()` so the two
-  channels cannot drift.
-
-**A2 install-completeness gate** (`tests/scripts/subagent_distribution.test.ts`):
-wedge↔src projection fidelity (no drift); coverage (every unit has a wedge doc);
-and negative-wiring locks — `resolve_logical('subagents/…')` is null, no
-`subagents/` path in `iter_all_sources`, the installer references no
-`dist/agent-src/subagents`, and `dist/agent-src/subagents/` does not exist. No
-byte-budget check (an arbitrary threshold on a system prompt is cargo-cult).
-
-*(Council side-fix: `AnthropicClient` extracted only `content[0].text`, dropping
-extended-thinking models' output — claude-fable-5 returned 3191 output tokens as
-empty text. Fixed to join all text-type blocks.)*
-
-## References
-
-- Council debate 2026-07-04 (claude-sonnet-4-5 + gpt-4o, 2 rounds).
-- Amendment-2 council 2026-07-05 (claude-fable-5 + gpt-4o, 2 rounds) — consumer distribution = wedge-only.
-
-- Council debate 2026-07-04 (claude-sonnet-4-5 + gpt-4o, 2 rounds).
-- Amendment-1 council 2026-07-04 (claude-sonnet-4-5 + gpt-4o, 2 rounds) — manifest integration = Option B.
-- ADR-034 / ADR-035 — `model_tier` → native model mapping (reused, not replaced).
-- `docs/contracts/subagent-boundary.md` — what a subagent owns vs. never owns.
-- `src/skills/subagent-orchestration/SKILL.md` — the in-session orchestration modes.
-- `road-to-final-state-and-market-readiness.md` — Track A (A1 keystone; A2 pipeline
-  proof; A3 eval gate).

package/docs/decisions/ADR-110-discipline-profile-resolution-locus.md

@@ -1,110 +0,0 @@
----
-adr: 110
-status: accepted
-date: 2026-07-07
-decision: discipline-profile-resolution-locus
-supersedes: —
-superseded_by: —
-phase: road-to-discipline-profile-tiering
-type: standing
----
-
-# ADR-110 — `discipline_profile` resolves at runtime (agent-in-the-loop); projection stays configuration-independent
-
-## Status
-
-**Accepted** · 2026-07-07 · maintainer decision implementing two same-day
-AI-council verdicts (claude-sonnet-4-5 + gpt-4o, 2-round debates each):
-weak-host-lift tiering (`agents/settings/contexts/weak-host-lift-tiering-verdict.md`)
-and token-program integration (`agents/settings/contexts/token-program-integration-verdict.md`).
-
-## Context
-
-The cost-factor sweep (`docs/benchmark.md § Cost-factor sweep`) established
-that the package's weak-host discipline lift survives at ~3.3x tokens
-(kernel + `downstream-changes`) with no significant residual from the full
-~11.7x load, and that hosts differ: `claude-sonnet-4-6` is a measured NULL
-(discipline ceiling). The councils converged on ONE runtime knob —
-`discipline_profile: auto | off | essential | full` — with `auto` gating the
-lift layer per host via an evidence-gated NULL-lift disable-list.
-
-The open design question this ADR records: **where does `auto` resolve?**
-Projection is static per project, but the host model is a *runtime* fact — a
-project is opened by Haiku one session and Fable the next, across vendors
-(Claude, GPT, Gemini, open-source). Candidates considered:
-
-1. **Runtime resolution (agent-in-the-loop)** — the agent resolves the knob
-   at session start against `src/config/host-capabilities.yml`.
-2. **Per-tool projection variants** — emit per-model projections; the host
-   picks one. Rejected: no host tool selects projections by model; N×M
-   projection matrix; violates the ADR-040 principle that trigger semantics
-   stay configuration-independent.
-3. **Hook-based rewrite** — a session-start hook mutates the loaded surface.
-   Rejected: hooks are deny/warn-only in the cross-host v1 contract (no
-   transparent rewrite); Claude-only mechanisms are forbidden here.
-
-## Decision
-
-1. **`discipline_profile` is a runtime knob, resolved agent-in-the-loop** —
-   the same enforcement model as `provider-lifecycle-discipline` (the agent
-   reads a declared fact at run time and applies the obligation; CI guards
-   the facts, not the runtime). Resolution semantics live in ONE function,
-   `resolve_discipline_profile()`
-   (`src/agent-src/templates/scripts/work_engine/_lib/agent_settings.ts`):
-   explicit value wins → `auto` checks the session model id against
-   `host-capabilities.yml` (prefix match; measured-NULL → `off`, otherwise →
-   `essential` under `unknown_default: lift_enabled`) → absent key maps from
-   legacy `rule_loading_tier` (minimal→off, balanced→essential, full→full,
-   custom→custom) → both absent → `essential`.
-2. **`host-capabilities.yml` is an evidence-gated disable-list, never a
-   taxonomy.** Entries name only models with a MEASURED null lift, each with
-   `measured:` provenance (date · pinned report · N) or an explicit
-   `extrapolated: true` maintainer flag. Unknown models resolve fail-safe to
-   the lift (`essential`). Vendor-neutral by construction: any model id can
-   be measured onto the list.
-3. **Projection is unchanged by this ADR.** Bodies still project per
-   `lean_projection.mode` (eager-all today); the knob governs which
-   discipline tiers the agent honours at runtime — exactly the semantics the
-   legacy `rule_loading_tier` already had. The *physical* per-host token
-   saving lands when thin projection un-defers (as a sub-mechanism of
-   `essential`, re-swept, per the token-program-integration verdict), at
-   which point `lean_projection.mode` is absorbed. This keeps ADR-040's
-   guarantee: trigger semantics are configuration-independent.
-4. **`discipline_profile` joins `MERGEABLE_KEYS`** (user-global cascade), as
-   the successor of the already-mergeable `rule_loading_tier`.
-5. **Defaults are evidence-gated.** *(Amended 2026-07-07 after both gates
-   ran — original wording: ship commented-out until P1 + P2 pass, flip
-   target `auto`.)* P1 passed family-scoped; P2 FAILED on the first
-   non-Claude weak host (`docs/benchmark.md § P2 gate`). Per the P2-verdict
-   council, the installer presets fill the key per profile (minimal→off,
-   balanced→`auto`, full→full) and `auto` resolves vendor-granularly
-   (measured-null → off; unmeasured Claude-family → essential; unmeasured
-   non-Claude → off) — the lift enables only where measured. Evidence trail:
-   `agents/roadmaps/archive/road-to-discipline-profile-tiering.md`.
-
-## Consequences
-
-- One resolution function, unit-tested, shared by scripts and documented for
-  agents — no per-tool drift in mapping semantics.
-- Strong hosts get an honest `off` the moment their null is *measured*, never
-  by vendor folklore; the disable-list only grows by measurement.
-- Until thin projection lands, `auto`/`essential` on an eager-projection host
-  changes which rules the agent honours, not the loaded bytes — the cost
-  claims in the settings docs say so explicitly (the measured 3.3x applies
-  where loading is physical: sysprompt injection today, thin projection
-  later).
-- The legacy `rule_loading_tier` stays readable indefinitely; the wizard and
-  presets migrate when the `balanced` cut is retired (roadmap Phase 2).
-
-## Alternatives
-
-Per-tool projection variants and hook rewrites (rejected above); a maintained
-strong/weak model registry (explicitly rejected by the tiering council —
-speculative, unmaintainable at model-release cadence).
-
-## References
-
-- `agents/settings/contexts/weak-host-lift-tiering-verdict.md`
-- `agents/settings/contexts/token-program-integration-verdict.md`
-- `docs/benchmark.md § Cost-factor sweep`
-- ADR-040 (projection-time filtering), ADR-002 (kernel budget)

package/docs/decisions/ADR-111-canonical-glama-listing.md

@@ -1,97 +0,0 @@
----
-adr: 111
-status: accepted
-date: 2026-07-07
-decision: canonical-glama-listing
-supersedes: —
-superseded_by: —
-phase: road-to-mcp-full-power
-type: standing
----
-
-# ADR-111 — the kernel stdio server is the canonical Glama listing; the turnkey server stays unlisted
-
-## Status
-
-**Accepted** · 2026-07-07 · maintainer decision, Phase 2 of
-`road-to-mcp-full-power.md`.
-
-## Context
-
-The package now ships two distinct stdio MCP servers with different
-audiences and capability shapes:
-
-1. **Kernel stdio server** (`src/scripts/mcp_server/`, started via
-   `agent-config mcp:run`) — requires a repo checkout (or the glama build
-   step), exposes 430 prompts / 232 resources / 27 catalogued tools (9
-   implemented as of Phase 1/4 of this roadmap). This is the server glama.ai
-   currently indexes and lists at
-   `glama.ai/mcp/servers/event4u-app/agent-config`.
-2. **Turnkey stdio-lite server** (`src/cli/mcp/`, started via
-   `agent-config mcp-server`) — zero-setup, reads the bundled
-   `dist/agent-src/` + `docs/guidelines/` directly from the installed npm
-   package, no repo clone required. Read-only by design (ADR-085): zero
-   tools, prompts/resources only.
-
-`road-to-glama-registry-listing.md` (archived) already converged on listing
-only the stdio server for a contributor/agent-developer audience, before the
-turnkey server existed in its current form. This ADR re-confirms that choice
-now that both servers are live, and records why a second listing is not
-added.
-
-## Decision
-
-1. **Glama lists the kernel server only.** `glama.json` and the committed
-   `internal/glama/{build,run}` scripts continue to target
-   `src/scripts/mcp_server/__main__.ts`. No change to the glama admin
-   configuration.
-2. **The turnkey server is not submitted to glama.** Rationale:
-   - Glama's value proposition (repo-aware introspection, contributor
-     discovery) matches the kernel server's audience — people extending or
-     debugging the package itself.
-   - The turnkey server's audience (end users who `npx @event4u/agent-config
-     mcp-server` for zero-setup client config) is served better by direct
-     per-IDE config snippets (`docs/setup/mcp-client-config.md`,
-     `docs/getting-started-local-stdio.md`) than by a registry listing that
-     would advertise a read-only, tool-less server next to the fuller
-     kernel listing under the same package name — a likely source of
-     consumer confusion ("why does the glama listing show tools I don't
-     get?").
-   - Glama's schema (`glama.ai/mcp/schemas/server.json`) supports exactly one
-     manifest field (`maintainers`); there is no per-listing scoping
-     mechanism to distinguish two servers from the same repo without a
-     second, separately-hosted manifest — not worth the maintenance surface
-     for a zero-tool server.
-3. **Revisit trigger.** Reopen this decision if either: (a) the turnkey
-   server gains tools (Phase 6 of this roadmap may bundle the kernel tool
-   surface into the npm package, per the ADR-085 revisit), making its
-   capability shape worth discovering separately; or (b) a named consumer
-   asks to discover the turnkey server via a registry specifically (not
-   just via npm/README).
-
-## Consequences
-
-- No glama configuration change required by this roadmap.
-- `docs/mcp-registries.md` and `docs/setup/mcp-client-config.md` document
-  both entry points, but only one (the kernel server) appears in the glama
-  registry — this asymmetry is intentional, not an oversight.
-- Official MCP-registry submission (Phase 2 Step 5 of this roadmap) is
-  free to list either or both servers, since that registry's schema is not
-  glama's single-manifest-per-repo constraint — evaluated separately.
-
-## Alternatives
-
-- **List both as separate glama entries.** Rejected — no such thing as
-  "the second manifest field" in glama's schema for this repo; would need a
-  second cloned/forked registration, disproportionate for a read-only
-  zero-tool server.
-- **Drop the kernel listing, list only turnkey.** Rejected — the kernel
-  server's tool surface is the entire reason glama's introspection is
-  valuable here; a tool-less listing loses that value.
-
-## References
-
-- `road-to-glama-registry-listing.md` (archived) — original listing decision.
-- `road-to-mcp-stdio-end-user-packaging.md` (archived) — turnkey server origin, ADR-085.
-- `agents/settings/contexts/mcp-tool-tier-map.md` — capability-shape evidence for both servers.
-- `internal/glama/README.md` — the build/run scripts this decision keeps unchanged.

package/docs/decisions/ADR-112-stdio-lite-stays-read-only.md

@@ -1,92 +0,0 @@
----
-adr: 112
-status: accepted
-date: 2026-07-07
-decision: stdio-lite-stays-read-only
-supersedes: —
-superseded_by: —
-phase: road-to-mcp-full-power
-type: standing
----
-
-# ADR-112 — the turnkey stdio-lite server stays read-only; tool users route to the kernel server
-
-## Status
-
-**Accepted** · 2026-07-07 · maintainer decision, Phase 6 of
-`road-to-mcp-full-power.md`. Resolves the ADR-085 revisit trigger
-("full-kernel bundling deferred — no demand"), which fired via this
-roadmap's named consumer ask.
-
-## Context
-
-ADR-085 shipped `agent-config mcp-server` (stdio-lite, `src/cli/mcp/`) as
-a read-only, zero-setup surface: prompts + resources from the bundled
-`dist/agent-src/` + `docs/guidelines/`, `tools/list` empty, execution
-deferred until demand existed. Demand now exists — but for the *kernel*
-server: Phases 4–5 of this roadmap shipped 18 implemented tools
-(write-tier + one shell-exec pilot) on `src/scripts/mcp_server/`, all
-requiring a repo checkout and the full script tree
-(`src/agent-src/scripts/`, `src/scripts/_cli/`, the council pricing
-stack, the exec safety envelope).
-
-The A1 option (bundle the kernel tool surface into the npm package so
-`agent-config mcp-server` gains tools) was re-evaluated against that
-shipped reality.
-
-## Decision
-
-1. **Stdio-lite stays read-only.** `agent-config mcp-server` keeps its
-   ADR-085 shape: prompts + resources, zero tools, zero setup. No kernel
-   bundling.
-2. **Tool users route to the kernel server** (`agent-config mcp:run` on a
-   repo checkout). The per-IDE docs present this as the explicit
-   trade-off: zero-setup content surface vs. checkout-required execution
-   surface.
-3. **Rationale:**
-   - The Phase 4/5 handlers import live repo modules (dashboard
-     regenerator, archival sweep, doctor/conformance internals, council
-     pricing, the exec envelope). Bundling them means shipping and
-     version-locking effectively the whole `src/` tree inside the npm
-     tarball — the "turnkey" story would inherit the kernel's full
-     dependency and drift surface while losing its one virtue:
-     nothing-to-break simplicity.
-   - The tools mutate the consumer's `agents/` tree and spawn vitest.
-     A zero-setup binary that writes and executes on first contact is
-     the wrong default posture for the entry-level surface; the kernel
-     path's checkout requirement is a natural consent step.
-   - Maintaining one execution surface (kernel) instead of two keeps the
-     A0 contract, the test suite, and the telemetry story single-homed.
-4. **Revisit trigger:** a named end-user ask for MCP tools *without* a
-   repo checkout (e.g. a Claude Desktop user who wants `memory_signal`
-   but will not clone). That reopens A1 as its own roadmap with a fresh
-   council round — not a silent scope creep on this ADR.
-
-## Consequences
-
-- `docs/setup/mcp-client-config.md`'s two-entry-point table stays
-  accurate as written (local turnkey = read-only content; tools =
-  kernel).
-- ADR-111 (Glama lists the kernel only) is reinforced — the listed
-  server is also the only tool-bearing one.
-- The Worker remains read-only per `docs/contracts/mcp-cloud-scope.md`;
-  nothing in this ADR changes cloud scope.
-
-## Alternatives
-
-- **A1 full-kernel bundling** — rejected above (dependency surface,
-  write/exec-by-default posture, dual maintenance).
-- **Partial bundling (read-only tools only in stdio-lite)** — rejected:
-  splits the tool catalog across two servers with different subsets,
-  making `implemented_on` client-visible behaviour diverge per entry
-  point; the discovery-first catalog would need a third transport
-  dimension for marginal gain.
-
-## References
-
-- ADR-085 — original stdio-lite shape (read-only, execution deferred).
-- ADR-111 — canonical Glama listing (kernel only).
-- `agents/decisions/mcp-write-exec-cut-2026-07-07.md` — the tool cut that
-  created the demand this ADR routes.
-- `docs/contracts/mcp-phase-1-scope.md` § Amendment — the execution
-  surface this decision keeps single-homed.