@event4u/agent-config 5.10.1 → 6.1.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,144 @@
+---
+adr: 088
+status: accepted
+date: 2026-06-11
+decision: no-external-runtime-federation
+supersedes: —
+superseded_by: —
+phase: external-runtime-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
+("external-runtime coexistence bridge") as superseded.
+
+## Context
+
+An external multi-agent runtime 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 an "external-runtime 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_external` + `coexist`/`skip` mode + dispatcher skip-gate** — detect
+   the external runtime, 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 `external-runtime-bridge` pack** (`external-runtime-routing` rule +
+   `external-runtime-orchestration` skill) documenting the external runtime's MCP-tool surface and a
+   persona→agent-type map so the host agent can **drive the external runtime's swarm**.
+4. **A coexistence contract + an 8-phase roadmap** (later phases: shared
+   cross-tool memory, collision namespacing, git-layer enforcement of the external runtime's
+   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 —
+  the external runtime included. The original hook-collision motivation is solved without
+  anything external-runtime-specific.
+- **(B) An "external-runtime adoption" decision was recorded** (cross-vendor council,
+  claude-sonnet-4-5 + gpt-4o, 2026-05-06; see an internal parity record (local-only)).
+  Verdict: harvest only **portable** patterns from the external runtime (ADR methodology,
+  cost-tracker, HMAC signing) and **explicitly do not couple to the external runtime's
+  runtime / swarm / MCP tools** — wording used: "out of suite identity".
+  Candidates requiring the external 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 `external-runtime-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 an external-runtime-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 (an external runtime +
+   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 the external runtime (or any neighbour) get hook
+  coexistence for free via plugin scope; they do not get agent-config-driven
+  external-runtime 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_external` + 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: external-runtime coexistence bridge" (closed as superseded, 2026-06-11).
+- An internal parity record (local-only) — external-runtime parity verdict
+  (all patterns mechanism-covered; no runtime coupling).
+- An internal parity record (local-only) — 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/ADR-090-visibility-command-frontmatter-field.md

@@ -0,0 +1,95 @@
+---
+adr: 090
+status: accepted
+date: 2026-06-13
+decision: visibility-command-frontmatter-field
+supersedes: —
+superseded_by: —
+phase: command-surface-refactor-residuals
+type: structural
+---
+
+# ADR-090 — First-class `visibility:` command-frontmatter field
+
+## Status
+
+**Accepted** · 2026-06-13. Decided by AI council (anthropic/claude-sonnet-4-5
++ openai/gpt-4o, peer-review, deep) — converged on **Option A** with execution
+refinements. Council necessity-gate: borderline (3 necessary / 3 unnecessary);
+proceeded on the standing reviewer ask plus design-intent evidence already in
+the codebase (the `visibilityLabel(tier)` helper and the
+`# Proxy until the 'visibility:' field lands` comment).
+
+## Context
+
+A reviewer repeatedly asked for a real
+`visibility: visible | advanced | internal` command-frontmatter field instead of
+overloading the integer `tier:` (`0/1/2`) as the visibility proxy
+(`docs/contracts/command-surface-tiers.md`). All 150 command sources under
+`src/domains/<pack>/<verb>/command.md` carry `tier:`; no `visibility:` field
+existed.
+
+Design-intent evidence already in the tree:
+
+- `src/cli/commands/commands.ts` has `visibilityLabel(tier) →
+  {0:'visible',1:'advanced',2:'internal'}` and a `--visible` filter on
+  `VISIBLE_TIERS={0,1}`. The consumer surface already speaks "visibility",
+  derived from the integer.
+- `src/scripts/audit_command_surface.py` carries a standing comment:
+  `# Proxy until the 'visibility:' field lands (6.0.0-C Step 4b)`.
+
+`tier:` was always a backend integer encoding; "visibility" is the correct
+domain concept for a classification surface consumed by humans and LLM routers.
+Keeping the integer as the contract source of truth is a reversed abstraction.
+
+## Decision
+
+**Option A — `visibility:` becomes the classifier source of truth; `tier:`
+stays as a derived, back-compat alias.**
+
+1. Add an optional `visibility:` enum (`visible | advanced | internal`) to the
+   command frontmatter schema. Keep `tier:` (`0/1/2`) in the schema as a
+   back-compat alias.
+2. Backfill `visibility:` on all 150 command sources, derived from the current
+   `tier:` mapping: `0 → visible`, `1 → advanced`, `2 → internal`. Scripted +
+   auditable (one diff, reviewable).
+3. Repoint every reader to **prefer `visibility:`, fall back to `tier:`**:
+   `commands.ts` (ls/explain), `audit_command_surface.py` (per-pack
+   visible-command budget), `build_discovery_manifest.py`.
+4. The discovery manifest is a **published data contract**. To avoid a silent
+   breaking change for external consumers that read the integer `tier` key, the
+   manifest **dual-emits** both `tier` and `visibility` during the deprecation
+   window.
+5. Validation is **backfill-first, then enforce**: once every command carries
+   `visibility:`, the existing tier lint (`lint_command_tiers.py`) is extended
+   to require `visibility:` present + a valid enum + consistent with `tier:`
+   when both are set. No new standalone script; the check rides the existing
+   lint that already runs in CI.
+
+### Rejected alternatives
+
+- **Option B — hard rename `tier:` → `visibility:`, drop `tier:`.** Cleanest
+  end-state but largest blast radius and a hard break of the published manifest
+  contract with no migration window. Deferred; may follow once the deprecation
+  window closes.
+- **Option C — keep `tier:` authoritative, add `visibility:` only as a
+  validate-when-present label (category-field precedent).** Lowest blast radius
+  but fails the phase acceptance criterion ("`visibility:` … is the classifier's
+  source of truth").
+
+## Consequences
+
+- Two fields encode the same concept during the deprecation window → drift risk,
+  mitigated by the lint consistency check (when both present, they must agree)
+  and the scripted single-source backfill.
+- External manifest consumers keep working (dual-emit); migration to read
+  `visibility` can proceed on their own schedule.
+- A future ADR may drop `tier:` (Option B end-state) once readers and the
+  manifest have fully migrated; `tier:` removal is out of scope here.
+
+## References
+
+- `agents/roadmaps/archive/road-to-command-surface-refactor-residuals.md` — Phase 1.
+- `docs/contracts/command-surface-tiers.md` — tier contract this field supersedes
+  as the human-facing source of truth.
+- ADR-048 — the `category:` validate-when-present precedent weighed against here.