@event4u/agent-config 5.10.1 → 6.0.0

package/docs/decisions/ADR-086-read-only-cross-agent-mcp-discovery-helper.md

@@ -0,0 +1,171 @@
+---
+adr: 086
+status: rejected
+date: 2026-06-11
+decision: read-only-cross-agent-mcp-discovery-helper
+supersedes: —
+superseded_by: —
+phase: mcp-onboarding · discovery-first
+type: structural
+---
+
+# ADR-086 — Read-only cross-agent MCP discovery helper (defer auto-install)
+
+## Status
+
+**Rejected at its own Phase-0 gate** · 2026-06-11. The proposal to *build* the
+read-only discovery helper was not adopted: the Phase-0 demand gate in
+`road-to-mcp-discovery-helper` (which this ADR was pending) resolved to **STOP per
+Option C**. The defer-auto-install half of the decision stands (auto-install remains
+deferred to a future security-first ADR). Originally proposed 2026-06-10, routed
+through the AI council (claude-sonnet-4-5 + gpt-4o, design mode, 2026-06-10 —
+converged on the proposal); the build was then rejected at the gate by a second
+council round (claude-sonnet-4-5 + gpt-4o, design mode, 2026-06-11 — converged STOP).
+
+**Why rejected (verified at the gate, 2026-06-11):**
+
+- **Existing tooling covers it.** Smithery's CLI already does cross-client *install*
+  (read-write — the harder capability) for **5 of our 6 target agents** (Claude Code,
+  Cursor, Windsurf, Cline, VS Code/Copilot; verified in `src/config/clients.ts`,
+  `VALID_CLIENTS`, 23 clients). The lone gap is **Augment**. A read-only discovery
+  tool for the same 5 agents is strictly weaker — this trips ADR-086 Step 2's own
+  "if Smithery covers our full set read-write, reassess whether discovery is
+  non-duplicative" criterion.
+- **No demand signal.** Zero responses to the demand probe (shipped to the CHANGELOG
+  `[Unreleased]` notes → GitHub Discussions). ADR-086 made "weak signal → stop" the
+  gate condition.
+- **Surviving value is doc-shaped, not tool-shaped.** Registry-agnostic coverage is a
+  comparison matrix, not a 500-line CLI. Building the CLI would also create sunk-cost
+  bias toward reimplementing (rather than wrapping) Smithery in any future phase.
+
+**Verified registry facts (live-checked 2026-06-11, recorded for any future reopen):**
+both registries are queryable read-only with **no API key** — official
+`GET registry.modelcontextprotocol.io/v0/servers?search=&limit=&cursor=` (200, returns
+`server.json` records + `nextCursor`) and Glama
+`GET glama.ai/api/mcp/v1/servers?first=&after=` (200; resolves ADR-086's open
+"does Glama need a key?" question — it does not).
+
+**Follow-up — resolved 2026-06-11 (AI council, claude-sonnet-4-5 + gpt-4o, design
+mode; split → tie-break → converged C-only):** the surviving value is captured as a
+reference doc, [`docs/mcp-registries.md`](../mcp-registries.md) — the three-registry
+comparison plus a per-agent install path (Smithery covers 5/6; Augment via manual
+Import-from-JSON). An automated **Smithery → Augment** contribution is **deferred, not
+filed**: Augment's writable surface is undocumented/nested and there is no demand
+signal, so a PR or issue would externalise risk for zero proven benefit. Reopen only
+if all three hold: ≥ 3 independent user requests, Augment documents its `settings.json`
+MCP schema as stable, and the Smithery maintainers pre-approve the approach (mirrored
+in the doc footer).
+
+**Reopen criteria:** 5+ demand responses citing a concrete need Smithery cannot serve,
+OR Smithery registry-locks / declines Augment support / shuts down. Any reopen is a new
+ADR (security-first if it touches auto-install).
+
+## Context
+
+`event4u/agent-config` is a tool-agnostic skill/rule/command suite whose core
+competency is **projection**: one canonical source in `src/` is generated into
+per-tool trees (`.claude/`, `.cursor/`, `.augment/`, `.windsurfrules`,
+`.clinerules/`, `.github/copilot-instructions.md`). Today users wire up MCP
+servers manually, separately per agent. The package publishes its own read-only
+MCP server (Glama-indexed) but offers no help installing other people's servers.
+
+A deep-dive (2026-06-10, cite-checked) established:
+
+- **An official, vendor-neutral MCP registry exists** —
+  `registry.modelcontextprotocol.io`, public API `/v0/servers`, canonical
+  `server.json` schema. `server.json` carries `name` (reverse-DNS), `packages[]`
+  (`registryType` npm/pypi/oci/mcpb/nuget/cargo, `identifier`, `transport`
+  stdio/streamable-http/sse, `runtimeHint`, `packageArguments`,
+  `environmentVariables` with `isSecret` flags), `remotes[]`, `repository`. It is
+  a **discovery/catalog** spec — it does **not** write per-client config.
+- **Glama is a superset** of the official registry (~32k servers, +quality/safety
+  scoring, sandbox testing). API `glama.ai/api/mcp/v1/servers/{ns}/{name}` returns
+  `environmentVariablesJsonSchema`, `repository`, `spdxLicense`, `tools`. A
+  commercial third party; its "score" is not a verified security property.
+- **Smithery already does cross-client install** (`smithery install X --client …`)
+  — but its coverage of *our* agent set (Augment / Windsurf / Cline / Copilot) is
+  **unverified**; only `claude` and `cursor` are confirmed.
+
+The council split the question into two surfaces with opposite risk/value:
+
+| Surface | Risk | Value |
+|---|---|---|
+| **Discovery** ("which servers exist, what do they need") | low (read-only) | high, undisputed |
+| **Installation** ("write config into every agent") | high (secrets, supply-chain, no rollback) | disputed, demand unproven |
+
+Three convergent objections to building auto-install now:
+
+1. **Demand unproven.** No evidence that a meaningful share of users run multiple
+   agents *simultaneously* and feel config-sync pain. Measure before building.
+2. **Secrets + trust gate absent.** Auto-writing configs that contain API keys
+   without a trust model is negligent. The official registry has no central
+   vetting; Glama's score may be popularity, not safety.
+3. **Kill-switch paradox.** A feature that auto-writes configs has no
+   *non-centralized* rollback; a phone-home kill-switch contradicts the package's
+   tool-agnostic model. The only safe shape (staging + manual apply) collapses the
+   auto-install value.
+
+A fourth concern: MCP config may be **runtime state**, not portable source —
+forcing it into `src/` would create user-vs-project split complexity. This stays
+open and is explicitly out of scope for the discovery helper.
+
+## Decision
+
+Ship a **read-only, registry-agnostic MCP discovery helper** and **defer**
+auto-install (cross-agent config writes) to a future, security-first ADR.
+
+The helper:
+
+- Queries the **official MCP registry** as the primary source and **Glama** as an
+  optional enrichment source (quality/safety signals, env-var schema), behind a
+  registry-agnostic interface — **no hard coupling to any single registry**.
+- Normalizes results to the official `server.json` shape.
+- Renders, per matched server: name, description, declared `environmentVariables`
+  (marking `isSecret`), supported transports, and the **copy-paste install snippet
+  for each supported agent** — the user pastes it (and any secrets) themselves.
+- **Writes nothing** to any agent config file. Zero secrets touch disk via the
+  tool.
+
+Its adoption is the demand test for whether auto-install is ever worth building.
+
+## Consequences
+
+**Positive**
+- Solves the real pain (discovery) at zero security risk; no secrets handling.
+- Honors tool-agnosticism — one canonical shape, optional registries, no vendor lock.
+- Doubles as a falsifiable demand signal for the deferred auto-install question.
+- Small first slice — registry query + normalizer + per-agent snippet renderer.
+
+**Negative / accepted**
+- Users still copy-paste per agent (the auto-install toil is *not* eliminated).
+- A network dependency on external registries at query time (read-only, cacheable).
+- If demand proves high, a second, harder design cycle (trust gate, secret
+  handling, rollback) is still required before any auto-write.
+
+**Neutral**
+- Whether MCP config belongs in `src/` projection stays an open question, revisited
+  only if/when auto-install is reconsidered.
+
+## Alternatives considered
+
+- **A — MCP-config-as-projection on the official spec (auto-write all agents).**
+  Rejected *now*: demand unproven, secrets/trust/rollback unsolved. Remains the
+  natural successor *if* the discovery helper shows strong adoption — under a new
+  security-first ADR.
+- **B — Couple to Glama or delegate to Smithery's CLI.** Rejected: coupling a
+  tool-agnostic package to a single commercial registry contradicts its own
+  portability doctrine; Smithery's coverage of our agent set is unverified and
+  would add a third-party runtime dependency.
+- **C (pure) — Skip entirely.** Rejected: leaves the low-risk, high-value
+  discovery win on the table and forgoes the demand signal.
+
+## References
+
+- AI council convergence, design mode, 2026-06-10 (claude-sonnet-4-5 + gpt-4o):
+  Option C with a read-only discovery carve-out; verify Smithery coverage; gate on
+  a demand survey.
+- Official MCP registry `server.json` schema —
+  `static.modelcontextprotocol.io/schemas/.../server.schema.json`.
+- `src/skills/mcp/SKILL.md` — existing MCP tool-usage skill.
+- `internal/glama/README.md` — the package's own Glama-indexed MCP server (distinct
+  concern: we are *listed*, this ADR is about *consuming* registries).

package/docs/decisions/ADR-087-installer-e2e-test-strategy.md

@@ -0,0 +1,111 @@
+---
+adr: 087
+status: accepted
+date: 2026-06-11
+decision: installer-e2e-test-strategy
+supersedes: —
+superseded_by: —
+phase: installer-hardening · wizard-apply
+type: structural
+---
+
+# ADR-087 — Installer e2e test strategy: HTTP-API container e2e now, browser-driven Playwright deferred
+
+## Status
+
+**Accepted** · 2026-06-11. Lands with the fix for the browser-wizard
+"Finish writes nothing" bug and the first containerized installer e2e.
+
+## Context
+
+A consumer ran `npx -y @event4u/agent-config@latest init`, clicked through the
+browser wizard, saw only a "migration not available" notice, and **nothing was
+installed**. The headless CLI form (`init --global --tools=all …`) worked.
+
+Root cause (reproduced): the wizard server spawns
+`python3 install.py --apply-payload` with **no `PYTHONPATH`**
+(`src/server/routes/wizard.ts`), whereas the bash dispatcher always sets
+`PYTHONPATH=$PACKAGE_ROOT/src` (`src/scripts/_dispatch.bash`). For a consumer
+that already has a legacy tool dir (`.claude/` — every Claude Code user has
+one), the global-scope apply triggers migrate-to-global, whose
+`importlib.import_module("scripts._cli.cmd_migrate")` then raised
+`ImportError: No module named 'scripts'` → `warn("migrate unavailable")` →
+`return 1` → `install_global` never ran → an empty tree. (Fix: `install.py`
+self-bootstraps `sys.path` for that import, and the wizard spawn helpers seed
+`PYTHONPATH` for parity. Covered by `tests/test_install_wizard_wiring.py` and
+`tests/server/wizard.applySse.test.ts`.)
+
+The class of bug — the installer behaving differently depending on the spawn
+environment — is invisible to in-process unit tests that inherit the test
+runner's `sys.path`/`PYTHONPATH`. It only surfaces in a pristine process with no
+host leakage. That argues for a **container** e2e that runs the real installer
+end-to-end, including the real wizard HTTP apply path.
+
+The open question was the **wizard test depth**: drive the real SPA in a
+headless browser (Playwright, full UX) versus drive the wizard's HTTP API (the
+exact routes the SPA calls) inside a container.
+
+## Decision
+
+1. **Ship an HTTP-API-level container e2e now** —
+   `tests/fixtures/installer-e2e.Dockerfile` builds a pristine `node:20` +
+   `python3` image and `tests/fixtures/installer-e2e/run-scenarios.sh` runs two
+   scenarios, asserting a populated tree (`installed.lock` + terminal `done`
+   frame) lands on disk:
+   - **A.** `install.py --apply-payload` in a clean env (no `PYTHONPATH`,
+     legacy `.claude/` present) — the exact field condition.
+   - **B.** The real `createApp` wizard server, driven over HTTP via
+     `POST /api/v1/wizard/apply` — the exact path that spawns the installer.
+
+   Driven by `tests/test_e2e_container_install.py`, gated opt-in behind
+   `AGENT_CONFIG_E2E_DOCKER=1` (`task test-installer-e2e`) so the multi-minute
+   image build never runs in the default `task test` suite (and never per
+   xdist worker).
+
+2. **Defer browser-driven (Playwright UI) installer e2e** — do not add a
+   containerized full-browser walkthrough of the wizard that asserts a real
+   install. Document the deferral here; it can be added later.
+
+## Consequences
+
+- The regression that shipped to a consumer is now pinned at three layers:
+  Python (`--apply-payload`, no-`PYTHONPATH`), TypeScript (spawn env carries
+  `PYTHONPATH`), and a container e2e exercising both the CLI apply and the real
+  wizard HTTP apply in a clean process.
+- The container test is opt-in: contributors and CI run it deliberately
+  (`task test-installer-e2e`), not on every `task test`. The wiring into the
+  required CI gate is a follow-up decision, kept out of scope here.
+- `.dockerignore` now also excludes `internal/bench` (~145 MB) so the build
+  context stays lean.
+
+## Alternatives considered
+
+- **Full browser-driven Playwright installer e2e (rejected for now).**
+  `@playwright/test` is already a devDependency and
+  `tests/e2e/setup-wizard-9-steps.spec.ts` already drives the wizard's HTTP API
+  via `request.newContext()` (no browser binary) — but in dry-run, asserting
+  **zero** writes. A real-install browser walkthrough would add: a Chromium
+  layer to the image (heavier build), UI-rendering flakiness (selectors,
+  timing) on a path whose actual risk surface is the **apply** step, and
+  duplicate coverage of the state machine already covered in dry-run. The
+  apply/install logic is fully exercised at the HTTP level, which is where the
+  bug lived. The cost/benefit favours HTTP-API depth first.
+- **Why it can be added later.** The pieces exist: the Playwright config + the
+  9-step spec, plus the now-proven `createApp` boot harness
+  (`tests/fixtures/installer-e2e/boot-wizard.mjs`). A future browser e2e would
+  add a `--with-chromium` image variant and a `*.spec.ts` that walks the SPA to
+  "Finish" against a real (non-dry-run) backend, reusing the same write-root
+  assertions. Trigger to revisit: a UI-layer regression that the HTTP-API
+  e2e cannot catch (e.g. a frontend step that never posts the apply payload).
+
+## References
+
+- `tests/fixtures/installer-e2e.Dockerfile`,
+  `tests/fixtures/installer-e2e/run-scenarios.sh`,
+  `tests/fixtures/installer-e2e/boot-wizard.mjs`
+- `tests/test_e2e_container_install.py` · `task test-installer-e2e`
+- `tests/test_install_wizard_wiring.py` (no-`PYTHONPATH` apply regression)
+- `tests/server/wizard.applySse.test.ts` (spawn env carries `PYTHONPATH`)
+- `src/scripts/install.py::_run_migrate_to_global`,
+  `src/server/routes/wizard.ts::installerSpawnEnv`
+- `tests/fixtures/hermetic-smoke.Dockerfile` (prior container-test pattern)

package/docs/decisions/ADR-088-no-external-runtime-federation.md

@@ -0,0 +1,145 @@
+---
+adr: 088
+status: accepted
+date: 2026-06-11
+decision: no-external-runtime-federation
+supersedes: —
+superseded_by: —
+phase: ruflo-coexistence
+type: structural
+---
+
+# ADR-088 — agent-config does not bridge to external tool runtimes; federation needs its own explicit decision
+
+## Status
+
+**Accepted** · 2026-06-11. Lands with the closure of PR #262
+("ruflo coexistence bridge") as superseded.
+
+## Context
+
+[`ruvnet/ruflo`](https://github.com/ruvnet/ruflo) is a multi-agent
+orchestration **runtime** (swarms, persistent memory / RAG, an MCP server,
+a hooks system, background workers). It also writes `.claude/` lifecycle
+hooks, so it shares a Claude Code project's `.claude/` directory with
+`event4u/agent-config`.
+
+PR #262 (authored 2026-05-27) proposed a "ruflo coexistence bridge" with four
+parts:
+
+1. **Plugin-scope hook delivery** — ship agent-config's Claude hooks via the
+   plugin (`hooks/hooks.json`) instead of the shared `.claude/settings.json`
+   hooks array, to stop colliding with neighbour tools' hook arrays.
+2. **`detect_ruflo` + `coexist`/`skip` mode + dispatcher skip-gate** — detect
+   ruflo, offer a one-time choice, optionally skip agent-config's own
+   dispatcher so the two tools' hooks don't double-fire.
+3. **A detection-gated `ruflo-bridge` pack** (`ruflo-routing` rule +
+   `ruflo-orchestration` skill) documenting ruflo's MCP-tool surface and a
+   persona→agent-type map so the host agent can **drive ruflo's swarm**.
+4. **A coexistence contract + an 8-phase roadmap** (later phases: shared
+   cross-tool memory, collision namespacing, git-layer enforcement of ruflo
+   swarm commits, docs).
+
+Two things happened on `main` after the PR was authored:
+
+- **(A) Part 1 landed independently.** Plugin-scope hook delivery is on `main`
+  (`hooks/hooks.json` generated from `src/scripts/hook_manifest.yaml`;
+  `ensure_claude_bridge` writes only `enabledPlugins`, canonical id
+  `agent-config@event4u`). agent-config no longer owns the `settings.json`
+  hooks array, so it coexists with *any* neighbour tool's hooks generically —
+  ruflo included. The original hook-collision motivation is solved without
+  anything ruflo-specific.
+- **(B) A "ruflo adoption" decision was recorded** (cross-vendor council,
+  claude-sonnet-4-5 + gpt-4o, 2026-05-06; see archived
+  `road-to-ruflo-adoption` and [`docs/parity/ruflo.md`](../parity/ruflo.md)).
+  Verdict: harvest only **portable** patterns from ruflo (ADR methodology,
+  cost-tracker, HMAC signing) and **explicitly do not couple to ruflo's
+  runtime / swarm / MCP tools** — wording used: "out of suite identity".
+  Candidates requiring ruflo's runtime (`observe-trace`, `test-gaps`) were
+  dropped for that reason; an MCP/HTTP-bridge was only "deferred-with-trigger".
+
+PR #262's parts 2–4 are precisely the runtime coupling decision (B) rejected.
+They also drifted structurally out of the tree (`packages/core/` removed,
+`scripts/` → `src/scripts/`, `.agent-src.uncondensed/` → `src/`), so a 1:1
+finish was no longer viable regardless.
+
+The "finish & merge" question was re-routed through the AI council
+(design lens, deep). Cross-vendor transport was degraded to anthropic-only by a
+local CLI-adapter incompatibility (the `codex` and `gemini` CLI adapters pass
+flags the installed CLI versions reject), but the verdict converges with the
+2026-05-06 cross-vendor decision: close as superseded, and record the boundary
+so it is not re-litigated. The council's sharpest framing: PR #262 is an
+**unsanctioned strategic pivot** from "skill suite for AI coding tools" to
+"federation platform that orchestrates orchestrators" — a strategic decision,
+not a feature, smuggled in via an incremental PR.
+
+## Decision
+
+1. **agent-config does not bridge to, or drive, external tool runtimes.**
+   It is a **content suite** (skills, rules, commands) for AI coding tools —
+   not a runtime coordinator. It ships no `ruflo-orchestration`,
+   `cursor-orchestration`, `aider-routing`, `windsurf-bridge`, or equivalent
+   artifact that calls another tool's runtime / swarm / MCP surface. This is a
+   **category** boundary, not a ruflo-specific one. Consistent with the
+   "no app runtime" identity in
+   [`package-self-orientation`](../contracts/package-self-orientation.md).
+
+2. **Cross-tool coexistence is handled generically at the plugin / protocol
+   layer, never via tool-specific content.** Plugin-scope hook delivery (A)
+   already lets agent-config coexist with any neighbour's `settings.json`
+   hooks. Any future cross-tool coordination need must be solved the same way —
+   protocol-level (e.g. metadata in `hooks.json`), generic (any neighbour, not
+   one named vendor), opt-in, and demand-driven (a documented user pain), not
+   as a skill / rule / pack.
+
+3. **Federation is a separate, explicit decision.** If agent-config should ever
+   expand from skill-suite to a "federation platform" that orchestrates
+   external orchestrators, that requires its **own** ADR answering, at minimum:
+   (a) should the suite take on that identity; (b) the generic design (ruflo +
+   Cursor + Copilot + Windsurf, not one vendor); (c) the maintenance model for
+   N external bridges; (d) the trust contract — who validates an external
+   runtime's output, and how agent-config's safety floors
+   (`non-destructive-by-default`, `commit-policy`, `verify-before-complete`)
+   are enforced across the boundary. Until such an ADR is accepted, runtime
+   coupling is **out of scope**.
+
+4. **PR #262 is closed as superseded** under this boundary. Reopen only if the
+   federation decision in (3) is made.
+
+## Consequences
+
+- agent-config's identity stays clean: portable content, no dependence on any
+  neighbour tool's installation, version, or MCP-tool stability.
+- The maintenance surface does not grow by one bridge per orchestrator, and
+  behaviour does not vary by which neighbours are installed.
+- Users who run both agent-config and ruflo (or any neighbour) get hook
+  coexistence for free via plugin scope; they do not get agent-config-driven
+  ruflo orchestration.
+- Future "let's just add detection / a bridge for tool X" PRs have a recorded
+  boundary to point at, preventing re-litigation. They are redirected to the
+  generic, protocol-level, ADR-gated path in (2)–(3).
+
+## Alternatives considered
+
+- **Finish & merge PR #262 as-is** — rejected: reintroduces the runtime
+  coupling decision (B) dropped, across an unvalidated trust boundary, and
+  enacts a strategic pivot without an explicit decision.
+- **Repurpose to the defensive sliver only** (`detect_ruflo` + dispatcher
+  skip-gate + a generalised neighbour-coexistence contract) — rejected as the
+  default: the council found it wrong-layer (coordination belongs at the
+  protocol layer, not in tool-specific detection code) and redundant given (A),
+  with no documented user pain. The generic, protocol-level path in decision
+  (2) remains available if real pain is later documented.
+- **Keep PR #262 parked as a draft** — rejected: it had drifted structurally
+  out of the tree and its premise was superseded; an open draft on a dead
+  premise is maintenance debt, not optionality.
+
+## References
+
+- PR #262 — "feat: ruflo coexistence bridge" (closed as superseded, 2026-06-11).
+- [`docs/parity/ruflo.md`](../parity/ruflo.md) — ruflo parity verdict
+  (all patterns mechanism-covered; no runtime coupling).
+- Archived `road-to-ruflo-adoption` — the 2026-05-06 cross-vendor council
+  decision: harvest portable patterns, "out of suite identity" for the runtime.
+- [`package-self-orientation`](../contracts/package-self-orientation.md) —
+  "no app runtime" identity.

package/docs/decisions/ADR-089-lean-local-plugin-install.md

@@ -0,0 +1,111 @@
+---
+adr: 089
+status: accepted
+date: 2026-06-12
+decision: lean-local-plugin-install
+supersedes: —
+superseded_by: —
+phase: plugin-distribution-hygiene
+type: structural
+---
+
+# ADR-089 — Lean local plugin installs via git-worktree source; marketplace restructure rejected
+
+## Status
+
+**Accepted** · 2026-06-12.
+
+## Context
+
+The Claude Code plugin `agent-config@event4u-agent-config`
+([`.claude-plugin/marketplace.json`](../../.claude-plugin/marketplace.json))
+declares `source: "./"` — the repo root is the plugin root. Two channels
+consume it:
+
+- **GitHub (official, documented):** Claude Code `git clone`s the repo →
+  committed files only → lean (`git archive HEAD` ≈ 27 MB).
+- **Local path** (`claude plugin marketplace add <repo>`): Claude Code
+  **raw-copies the entire `source` dir verbatim** — neither `.gitignore`
+  nor `.claudeignore` is honored (verified empirically, 2026-06-12) — so
+  untracked dev trees (`.venv`, `.venv-mcp`, `node_modules`,
+  `internal/bench/ab/clones`) come along: **~1.5 GB per snapshot**,
+  regrown on every `claude plugin update`.
+
+Additionally, whenever the plugin source contains a `package.json`,
+Claude Code runs a full `npm install` (devDependencies included) into the
+cache during install — ~180 MB of `@babel`/`@eslint`/`@esbuild` the plugin
+never uses at runtime (hooks delegate to the global binary; skills are
+markdown). This is unavoidable on any source that carries the package
+manifest.
+
+A failed/never-registered local-path install on this machine left a
+1.1 GB orphan under `~/.claude/plugins/cache/event4u-agent-config/` that
+surfaced a stale, pre-rename `commit-in-chunks` skill alongside the
+current `git-commit-in-chunks`. Cleaning it + registering the plugin
+properly exposed the bloat as a local-path-channel artifact.
+
+The forcing question: can the local-path channel be made lean so a
+maintainer can dogfood plugin changes without a 1.5 GB snapshot?
+
+## Decision
+
+**Keep `source: "./"`. Do not restructure the marketplace source.** For
+lean local installs, point the marketplace at a **dedicated git worktree**
+of the repo instead of the live working tree:
+
+- `git worktree add <path> <ref>` → a checkout of committed files only
+  (~27 MB), with the 146 symlinked command-skills resolving because the
+  full tracked tree is present.
+- `claude plugin marketplace add <worktree-path>` → Claude Code copies
+  only the ~45 MB worktree (tracked files; no `.venv`/`internal` clones),
+  then `npm install`s the manifest deps → **~224 MB total** (vs 1.5 GB).
+- Test local plugin edits: commit on the worktree's branch +
+  `claude plugin update` (snapshots key on commit SHA, so a commit is
+  required either way; no push needed).
+
+This is operational, not a contract change — `source`, the skill-path
+shape, the two marketplace linters, and the GitHub channel are all
+untouched.
+
+## Consequences
+
+- Local install drops 1.5 GB → ~224 MB (−85 %) **and** keeps local-change
+  testing, with zero risk to the consumer-facing marketplace contract or
+  the GitHub channel. The residual ~180 MB is Claude Code's auto
+  `npm install`; eliminating it would require a `package.json`-free
+  assembled source — i.e. the rejected restructure below.
+- Maintainer keeps one extra worktree dir; to test a branch's plugin,
+  `git -C <worktree> checkout <branch>` + `claude plugin update`.
+- No content duplication, no generator/linter churn, no stale generated
+  tree to drift.
+- The 1.5 GB cost is simply avoided by never installing from the live
+  working tree.
+
+## Alternatives
+
+- **Restructure `source` to a self-contained lean plugin root**
+  (e.g. `source: ".claude-plugin"` or an assembled `dist/plugin/`) —
+  **rejected.** The 373 plugin skills are layout-spread: 227 are real
+  files under `dist/agent-src/skills/`, and 146 under
+  `.claude-plugin/skills/` are **symlinks pointing out of the dir**
+  (`../../../src/domains/…`, `dist/agent-src/commands/`). A lean source
+  would dangle all 146 symlinks and drop the 227. Making it work needs a
+  new assembly step that materializes all 373 skills as real files into a
+  committed plugin dir — generator rewrite, committed content
+  duplication, both marketplace linters, both-channel re-verification —
+  for a **disk-only** benefit (the GitHub channel is already 27 MB).
+  Cost/risk far exceeds the gain.
+- **`.claudeignore` allowlist** — rejected: not honored for local-path
+  copies (verified).
+- **GitHub-source-only install** — rejected as the primary dev loop:
+  lean, but cannot test local commits without pushing to the shared
+  remote first.
+- **Leave the live-working-tree local install** — rejected: 1.5 GB per
+  snapshot, regrown every update.
+
+## References
+
+- [`.claude-plugin/marketplace.json`](../../.claude-plugin/marketplace.json) — `source: "./"` unchanged by this decision.
+- [`docs/contracts/skill-distribution-channels.md`](../contracts/skill-distribution-channels.md) — git-consumed marketplace channel.
+- [`src/scripts/condense.py`](../../src/scripts/condense.py) — `generate_plugin_hooks`; skill projection into `.claude-plugin/skills/` (the symlinks).
+- ADR-085 (MCP stdio distribution shape), ADR-088 (no external runtime federation) — sibling distribution-shape decisions.

package/docs/decisions/INDEX.md

@@ -44,6 +44,55 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-038](ADR-038-canonical-settings-path.md) | Canonical Settings Path | — | — | — |
 | [ADR-039](ADR-039-claude-skills-untracked.md) | Claude Skills Untracked | accepted | 2026-06-01 | — |
 | [ADR-040](ADR-040-execution-model-projection-time-filtering.md) | Execution Model Projection Time Filtering | accepted | 2026-06-02 | — |
+| [ADR-041](ADR-041-controlled-command-verbs.md) | Controlled Command Verbs | accepted | 2026-06-03 | — |
+| [ADR-042](ADR-042-runtime-resolver-decision-gate.md) | Runtime Resolver Decision Gate | accepted | 2026-06-03 | — |
+| [ADR-043](ADR-043-monorepo-collapse-to-src-domains.md) | Monorepo Collapse To Src Domains | accepted | 2026-06-03 | ADR-017 |
+| [ADR-044](ADR-044-command-naming-scheme-hyphenated.md) | Command Naming Scheme Hyphenated | accepted | 2026-06-03 | — |
+| [ADR-045](ADR-045-src-source-layout-and-profiles-as-views.md) | Src Source Layout And Profiles As Views | accepted | 2026-06-03 | ADR-028 |
+| [ADR-046](ADR-046-thin-command-principle.md) | Thin Command Principle | accepted | 2026-06-03 | — |
+| [ADR-047](ADR-047-framework-neutral-stack-adaptive-commands.md) | Framework Neutral Stack Adaptive Commands | accepted | 2026-06-03 | — |
+| [ADR-048](ADR-048-command-justification-rule.md) | Command Justification Rule | accepted | 2026-06-03 | — |
+| [ADR-049](ADR-049-configuration-trust-boundary.md) | Configuration Trust Boundary | accepted | 2026-06-03 | — |
+| [ADR-050](ADR-050-workspace-vs-package-root-boundary.md) | Workspace Vs Package Root Boundary | accepted | 2026-06-05 | — |
+| [ADR-051](ADR-051-uncondensed-source-container-relocation.md) | Uncondensed Source Container Relocation | accepted | 2026-06-05 | — |
+| [ADR-052](ADR-052-packages-removal-and-pack-home-migration.md) | Packages Removal And Pack Home Migration | accepted | 2026-06-05 | — |
+| [ADR-053](ADR-053-agents-namespace-dual-role-resolution.md) | Agents Namespace Dual Role Resolution | accepted | 2026-06-05 | — |
+| [ADR-054](ADR-054-rule-adherence-decay-triggered-restate.md) | Rule Adherence Decay Triggered Restate | proposed | 2026-06-05 | — |
+| [ADR-055](ADR-055-flow-layer-data-model.md) | Flow Layer Data Model | proposed | 2026-06-06 | — |
+| [ADR-056](ADR-056-unvalidated-video-adapters-disposition.md) | Unvalidated Video Adapters Disposition | accepted | 2026-06-06 | — |
+| [ADR-057](ADR-057-consolidation-evidence-gate-outcomes.md) | Consolidation Evidence Gate Outcomes | proposed | 2026-06-06 | — |
+| [ADR-058](ADR-058-condensed-output-relocation-to-dist.md) | Condensed Output Relocation To Dist | accepted | 2026-06-06 | — |
+| [ADR-059](ADR-059-render-resume-filesystem-as-state.md) | Render Resume Filesystem As State | accepted | 2026-06-07 | — |
+| [ADR-060](ADR-060-comfyui-sandbox-model.md) | Comfyui Sandbox Model | accepted | 2026-06-07 | — |
+| [ADR-061](ADR-061-corpus-grounding-layer.md) | Corpus Grounding Layer | accepted | 2026-06-07 | — |
+| [ADR-062](ADR-062-encrypt-at-rest-store-architecture.md) | Encrypt At Rest Store Architecture | accepted | 2026-06-08 | — |
+| [ADR-063](ADR-063-append-jsonl-encryption-deferred.md) | Append Jsonl Encryption Deferred | accepted | 2026-06-08 | — |
+| [ADR-064](ADR-064-append-jsonl-per-record-encryption.md) | Append Jsonl Per Record Encryption | accepted | 2026-06-08 | — |
+| [ADR-065](ADR-065-tier3-inbox-handoff-v0.md) | Tier3 Inbox Handoff V0 | accepted | 2026-06-08 | — |
+| [ADR-066](ADR-066-skill-body-prerendering.md) | Skill Body Prerendering | accepted | 2026-06-08 | — |
+| [ADR-067](ADR-067-glama-registry-listing.md) | Glama Registry Listing | proposed | 2026-06-08 | — |
+| [ADR-068](ADR-068-host-tier-detection.md) | Host Tier Detection | accepted | 2026-06-08 | — |
+| [ADR-069](ADR-069-prompt-renderer.md) | Prompt Renderer | accepted | 2026-06-08 | — |
+| [ADR-070](ADR-070-tier1-drive-loop.md) | Tier1 Drive Loop | accepted | 2026-06-08 | — |
+| [ADR-071](ADR-071-launch-drive-integration.md) | Launch Drive Integration | accepted | 2026-06-08 | — |
+| [ADR-072](ADR-072-codex-gemini-drive-configs.md) | Codex Gemini Drive Configs | accepted | 2026-06-08 | — |
+| [ADR-073](ADR-073-drive-health-kill-switch.md) | Drive Health Kill Switch | accepted | 2026-06-08 | — |
+| [ADR-074](ADR-074-drive-kill-switch-auto-recovery.md) | Drive Kill Switch Auto Recovery | accepted | 2026-06-08 | — |
+| [ADR-075](ADR-075-workspace-gui-drive.md) | Workspace Gui Drive | accepted | 2026-06-08 | — |
+| [ADR-076](ADR-076-workspace-multi-turn.md) | Workspace Multi Turn | accepted | 2026-06-09 | — |
+| [ADR-077](ADR-077-workspace-followup-gui.md) | Workspace Followup Gui | accepted | 2026-06-09 | — |
+| [ADR-078](ADR-078-drive-health-panel.md) | Drive Health Panel | accepted | 2026-06-09 | — |
+| [ADR-079](ADR-079-workspace-host-picker.md) | Workspace Host Picker | accepted | 2026-06-09 | — |
+| [ADR-080](ADR-080-host-session-expired-410.md) | Host Session Expired 410 | accepted | 2026-06-09 | — |
+| [ADR-081](ADR-081-drive-health-reset-and-410-affordance.md) | Drive Health Reset And 410 Affordance | accepted | 2026-06-09 | — |
+| [ADR-082](ADR-082-410-one-click-relaunch.md) | 410 One Click Relaunch | accepted | 2026-06-09 | — |
+| [ADR-083](ADR-083-session-thread-and-arbitrary-continuation.md) | Session Thread And Arbitrary Continuation | accepted | 2026-06-09 | — |
+| [ADR-084](ADR-084-drive-health-refresh-on-drive.md) | Drive Health Refresh On Drive | accepted | 2026-06-09 | — |
+| [ADR-085](ADR-085-mcp-stdio-end-user-distribution-shape.md) | Mcp Stdio End User Distribution Shape | accepted | 2026-06-10 | — |
+| [ADR-086](ADR-086-read-only-cross-agent-mcp-discovery-helper.md) | Read Only Cross Agent Mcp Discovery Helper | rejected | 2026-06-11 | — |
+| [ADR-087](ADR-087-installer-e2e-test-strategy.md) | Installer E2E Test Strategy | accepted | 2026-06-11 | — |
+| [ADR-088](ADR-088-no-external-runtime-federation.md) | No External Runtime Federation | accepted | 2026-06-11 | — |
+| [ADR-089](ADR-089-lean-local-plugin-install.md) | Lean Local Plugin Install | accepted | 2026-06-12 | — |
 
 ## Unnumbered (legacy)
 

package/docs/deploy/small-team-recipe.md

@@ -1,7 +1,7 @@
 # Small-Team Recipe — 3–10 people, no code change
 
 > **Status** · v0 · 2026-05-24. Phase 9 of
-> [`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md).
+> [`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md).
 > The recipe relies entirely on **existing primitives**. No new
 > code, no new server, no shared backend. Each user runs the
 > workspace locally; the team shares the inputs.

package/docs/deploy/team-deployment-posture.md

@@ -1,7 +1,7 @@
 # Team Deployment Posture
 
 > **Status** · v0 · 2026-05-24. Phase 9 of
-> [`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md).
+> [`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md).
 > Codifies what is shipped today, what stays cancelled-with-reason,
 > and what is reachable via existing primitives — so feedback rounds
 > 9+ asking "team SSO when?" land on a written answer.