@event4u/agent-config 9.8.0 → 9.9.0

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

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

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

@@ -1,144 +0,0 @@
----
-adr: 088
-status: accepted
-date: 2026-06-11
-decision: no-external-runtime-federation
-supersedes: —
-superseded_by: ADR-124 (engine-adoption interpretation only)
-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

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

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