vgxness 1.20.4 → 1.20.6

package/docs/sdd/archive/2026-06-26-ambitious-structure-reorganization/tasks.md

@@ -0,0 +1,63 @@
+# Tasks: Ambitious Structure Reorganization
+
+## Review Workload Forecast
+
+| Field | Value |
+|---|---|
+| Estimated changed lines | 2,000–5,000+ across full migration |
+| 400-line budget risk | High |
+| Chained PRs recommended | Yes |
+| Suggested split | Docs/facades → runs pilot → mcp pilot → cli/interfaces → remaining domains |
+| Delivery strategy | auto-chain |
+| Chain strategy | stacked-to-main |
+
+Decision needed before apply: No
+Chained PRs recommended: Yes
+Chain strategy: stacked-to-main
+400-line budget risk: High
+
+### Suggested Work Units
+
+| Unit | Goal | Likely PR | Notes |
+|---|---|---|---|
+| 1 | Boundary docs and compatibility rules | PR 1 | No code moves except optional facades |
+| 2 | `runs` pilot | PR 2 | Split service/repository/lifecycle first |
+| 3 | `mcp` pilot | PR 3 | Separate MCP interface from provider setup |
+| 4 | CLI/interface migration | PR 4 | Move dispatch/render into `interfaces/cli` |
+| 5 | Remaining domains | PR 5+ | `skills`, `sdd`, `agents`, `memory`, cleanup |
+
+## Phase 1: Boundary Foundation
+
+- [x] 1.1 Create `docs/module-boundaries.md` with target layout, ownership rules, import rules, and migration map.
+- [x] 1.2 Add compatibility policy for old barrels/facades and deprecation criteria.
+- [x] 1.3 Identify public entrypoints that must remain stable: `src/mcp/index.ts`, `src/permissions/index.ts`, domain `index.ts` files.
+
+## Phase 2: Runs Pilot
+
+- [x] 2.1 Create target folders for `domain/runs`, `application/runs`, and `storage/runs`.
+- [x] 2.2 Move run application services behind compatibility facades while preserving public imports.
+- [x] 2.3 Move run repositories under the storage layer while preserving old imports.
+- [x] 2.4 Run targeted `test/runs` and typecheck.
+
+## Phase 3: MCP Pilot
+
+- [x] 3.1 Create `interfaces/mcp` for schemas, stdio server, handlers, and validation boundaries.
+- [x] 3.2 Move provider setup/status logic toward `application/provider-setup` and `adapters/opencode|claude`.
+- [x] 3.3 Keep MCP tool names and `SUPPORTED_VGX_MCP_TOOL_NAMES` behavior unchanged.
+- [x] 3.4 Run targeted `test/mcp` and Bun storage-backed MCP suites.
+
+## Phase 4: CLI and Remaining Domains
+
+- [x] 4.1 Move CLI command parsing/rendering to `interfaces/cli` with services behind application modules.
+- [x] 4.2 Migrate `skills`, `sdd`, `agents`, and `memory` into domain/application/storage slices.
+  - [x] 4.2a Migrate `skills` into domain/application/storage slices with old-path facades.
+  - [x] 4.2b Migrate `sdd` into domain/application/storage slices.
+  - [x] 4.2c Migrate `agents` into domain/application/storage slices.
+  - [x] 4.2d Migrate `memory` into domain/application/storage slices.
+- [x] 4.3 Move provider-specific projections into `adapters/*`.
+
+## Phase 5: Verification and Cleanup
+
+- [x] 5.1 Run `tsc --noEmit`, targeted tests, and Bun CI-equivalent suites.
+- [x] 5.2 Remove duplicated logic from facades; keep only exports/delegation.
+- [x] 5.3 Update architecture docs with final structure and remaining deprecated paths.

package/docs/sdd/archive/2026-06-26-ambitious-structure-reorganization/verify-report.md

@@ -0,0 +1,71 @@
+# Verify Report: Ambitious Structure Reorganization
+
+## Verdict
+
+PASS.
+
+## Change
+
+- Change: `ambitious-structure-reorganization`
+- Mode: filesystem SDD artifacts under `docs/sdd/`
+- Verification date: 2026-06-26
+- Verified head before archive: `2e2fb85 docs(structure): finalize boundary cleanup (#363)`
+
+## Task Completeness
+
+| Area | Status | Evidence |
+|---|---|---|
+| Phase 1 Boundary Foundation | PASS | `tasks.md` marks 1.1-1.3 complete. |
+| Phase 2 Runs Pilot | PASS | `tasks.md` marks 2.1-2.4 complete. |
+| Phase 3 MCP Pilot | PASS | `tasks.md` marks 3.1-3.4 complete. |
+| Phase 4 CLI and Remaining Domains | PASS | `tasks.md` marks 4.1, 4.2a-d, and 4.3 complete. |
+| Phase 5 Verification and Cleanup | PASS | `tasks.md` marks 5.1-5.3 complete. |
+
+No unchecked implementation tasks remain in `tasks.md`.
+
+## Requirement Compliance Matrix
+
+| Requirement | Scenarios | Status | Evidence |
+|---|---|---|---|
+| Layered Module Boundary Map | Target layout is documented; all major areas are mapped | PASS | `docs/module-boundaries.md` documents target layout, ownership rules, import rules, migration map, compatibility facade owners, and remaining deferred legacy paths. |
+| Compatibility During Migration | Existing consumers keep compiling; deprecated paths are intentional | PASS | Old paths remain as facades for migrated areas; `npx tsc --noEmit` passed; facade audit documented in `docs/module-boundaries.md`. |
+| Behavior Preservation | Refactor slice preserves behavior; behavior changes rejected/split | PASS | Full Node test suite passed; prior PR Bun CI checks passed on the merged slices; no product-contract changes recorded. |
+| Reviewable Migration Slices | High-risk migration split; pilot validates pattern | PASS | Work landed through chained PRs #343, #345, #347, #349, #351, #353, #355, #357, #359, #361, and #363. |
+
+## Design Coherence
+
+| Design Decision | Status | Evidence |
+|---|---|---|
+| Layer by architectural role | PASS | Canonical folders now exist under `src/domain`, `src/application`, `src/storage`, `src/adapters`, and `src/interfaces`. |
+| Keep compatibility facades during migration | PASS | Migrated old paths remain compatibility facades; remaining non-facade provider-install paths are explicitly documented as future cleanup candidates. |
+| Pilot before whole-repo migration | PASS | `runs` and `mcp` landed first, followed by CLI, provider setup, skills, SDD, agents, memory, adapters, and final cleanup. |
+
+## Runtime Evidence
+
+| Command / Evidence | Result |
+|---|---|
+| `npx tsc --noEmit` | PASS |
+| `npm run build` | PASS |
+| `node scripts/run-node-tests.mjs` | PASS — 516 tests, 513 pass, 3 skipped, 0 fail |
+| `git diff --check` | PASS |
+| Local Bun verification | SKIPPED — local environment reports `bun-not-installed` |
+| GitHub Bun Runtime CI for final cleanup | PASS — run `28272288089`, commit `2e2fb85`, workflow `Bun Runtime CI` |
+
+## Issues
+
+### Critical
+
+None.
+
+### Warnings
+
+- Local environment does not have `bun`, so local Bun commands could not run. Required GitHub Bun Runtime CI passed for the final merged cleanup commit and earlier structural slices.
+- Some provider-install helpers under `src/mcp/client-install-*`, `src/mcp/claude-code-*`, and `src/mcp/opencode-*` remain non-facade deferred migration candidates rather than complete adapter extractions. This is documented as future cleanup and does not block this SDD because task 4.3 intentionally focused on renderer/projection adapters and shared sync contracts.
+
+### Suggestions
+
+- Consider a follow-up SDD to migrate provider install helpers into `src/adapters/*` / `src/application/provider-setup/*` and then tighten facade removal criteria.
+
+## Final Verdict
+
+PASS WITH WARNINGS. The implementation satisfies the SDD requirements, all persisted tasks are complete, runtime verification passes, and no critical issues block archive.

package/docs/sdd/archive/2026-06-26-legacy-facade-cleanup/apply-progress.md

@@ -0,0 +1,68 @@
+# Apply Progress: Legacy Facade Cleanup
+
+## Completed Tasks
+
+- [x] 1.1 Created proposal, spec, design, and tasks.
+- [x] 1.2 Generated static inventory of legacy facades and internal imports.
+- [x] 1.3 Decided keep/delete set for provider-install paths.
+- [x] 2.1 Updated source and tests away from `src/mcp/client-install-*`, `src/mcp/claude-code-*`, and `src/mcp/opencode-*` per-file facades.
+- [x] 2.2 Deleted obsolete provider-install facade files.
+- [x] 2.3 Ran targeted provider/MCP tests and typecheck.
+- [x] 3.1 Updated source/tests away from obsolete `src/mcp/provider-*.ts` per-file facades where safe.
+- [x] 3.2 Deleted unused provider setup facade files.
+- [x] 3.3 Ran targeted provider/control-plane tests and typecheck.
+- [x] 3.4 Removed unused nested MCP interface subfacades (`src/mcp/contracts/*`, `src/mcp/schemas/*`, `src/mcp/validation/*`, and `src/mcp/control-plane/handlers/*`) after confirming source/test/docs had no imports outside the files themselves.
+- [x] 4.1 Updated `docs/module-boundaries.md` with the final retained and removed legacy surface.
+- [x] 4.2 Ran final local typecheck, build, and full Node suite; PR CI will provide remote Bun verification.
+- [x] 4.3 Added verify/archive reports and archived the SDD packet.
+
+## Audit Findings
+
+| Path Set | Decision | Reason |
+|---|---|---|
+| `src/mcp/client-install-opencode*.ts` | Delete | One-line facades; source/tests now use `src/adapters/opencode/install/*` or `src/mcp/index.ts`. |
+| `src/mcp/opencode-*.ts` | Delete | One-line facades; canonical OpenCode helpers are under `src/adapters/opencode/install/*`. |
+| `src/mcp/client-install-claude-code*.ts` | Delete | One-line facades; source/tests now use `src/adapters/claude/install/*` or `src/mcp/index.ts`. |
+| `src/mcp/claude-code-*.ts` | Delete | One-line facades; canonical Claude helpers are under `src/adapters/claude/install/*`. |
+| `src/mcp/index.ts` | Keep | Intentional stable MCP barrel, now re-exporting canonical adapter/application modules directly. |
+| `src/mcp/provider-change-plan.ts`, `provider-doctor.ts`, `provider-health-types.ts`, `provider-status.ts` | Delete | One-line application facades; source/tests now use `src/application/provider-setup/*` or `src/mcp/index.ts`. |
+| Archived SDD references | Keep | Historical audit trail, not active import paths. |
+
+## Files Changed
+
+| File | Action | What Changed |
+|---|---|---|
+| `src/mcp/client-install-*`, `src/mcp/opencode-*`, `src/mcp/claude-code-*` | Deleted | Removed obsolete one-line compatibility facades. |
+| `src/mcp/index.ts` | Modified | Re-exports provider-install symbols directly from canonical adapter modules. |
+| `src/mcp/doctor.ts` | Modified | Imports OpenCode install target resolver from canonical adapter module. |
+| `src/mcp/provider-*.ts` | Deleted | Removed obsolete one-line application provider setup facades. |
+| `src/mcp/contracts/*`, `src/mcp/schemas/*`, `src/mcp/validation/*`, `src/mcp/control-plane/handlers/*` | Deleted | Removed unused nested interface subfacades; top-level stable MCP facades remain. |
+| `src/interfaces/*`, `src/adapters/*`, `test/mcp/*` | Modified | Provider setup imports now point to `src/application/provider-setup/*`. |
+| `src/mcp/provider-canonical-agent-manifest.ts` | Modified | Uses provider health contracts from application provider setup. |
+| `test/mcp/*`, `test/agents/agent-seed-service.test.ts` | Modified | Tests import canonical provider adapter helpers where they were asserting per-file legacy paths. |
+| `docs/providers.md`, `AGENTS.md` | Modified | Documentation now references canonical adapter paths. |
+
+## Deviations from Design
+
+None — `src/mcp/index.ts` remains as the intentional stable barrel, while narrow per-file provider-install facades were removed.
+
+## Issues Found
+
+- `src/mcp/doctor.ts` still imported the deleted OpenCode contract facade; updated it to the adapter owner.
+- `src/mcp/provider-canonical-agent-manifest.ts` still imported the deleted provider health facade; updated it to the application owner.
+- Nested MCP interface facades were not imported by source/tests/docs; they were safe to delete while keeping top-level `src/mcp/schema.ts`, `validation.ts`, `control-plane.ts`, and `stdio-server.ts`.
+
+## Verification
+
+- [x] `npx biome check --write --unsafe ...` for touched source/tests/docs
+- [x] `npx tsc --noEmit`
+- [x] `node scripts/run-node-tests.mjs test/mcp/client-install-opencode.test.ts test/mcp/client-install-opencode-contract.test.ts test/mcp/client-install-claude-code.test.ts test/mcp/provider-status.test.ts test/mcp/provider-doctor.test.ts test/agents/agent-seed-service.test.ts` — passed 516 tests, 513 pass, 3 skipped
+- [x] `node scripts/run-node-tests.mjs test/mcp/provider-change-plan.test.ts test/mcp/provider-status.test.ts test/mcp/provider-doctor.test.ts test/mcp/control-plane.test.ts test/mcp/opencode-handoff-preview.test.ts` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx tsc --noEmit` after nested facade deletion
+- [x] Final `npx tsc --noEmit`
+- [x] Final `npm run build`
+- [x] Final `node scripts/run-node-tests.mjs` — passed 516 tests, 513 pass, 3 skipped
+
+## Remaining Tasks
+
+No implementation tasks remain; SDD is ready for archive.

package/docs/sdd/archive/2026-06-26-legacy-facade-cleanup/archive-report.md

@@ -0,0 +1,61 @@
+# Archive Report: Legacy Facade Cleanup
+
+## Archive Summary
+
+- Change: `legacy-facade-cleanup`
+- Archive date: 2026-06-26
+- Source artifact mode: filesystem SDD artifacts under `docs/sdd/`
+- Archived to: `docs/sdd/archive/2026-06-26-legacy-facade-cleanup/`
+- Verification verdict: PASS WITH WARNINGS; no critical issues.
+
+## Source Artifacts
+
+| Artifact | Status |
+|---|---|
+| `proposal.md` | Present |
+| `spec.md` | Present |
+| `design.md` | Present |
+| `tasks.md` | Present; all tasks checked |
+| `apply-progress.md` | Present |
+| `verify-report.md` | Present |
+
+## Task Completion Gate
+
+PASS. `tasks.md` has no unchecked implementation tasks.
+
+## Removed Legacy Surface
+
+- `src/mcp/client-install-*`
+- `src/mcp/opencode-*`
+- `src/mcp/claude-code-*`
+- `src/mcp/provider-*.ts`
+- `src/mcp/contracts/*`
+- `src/mcp/schemas/*`
+- `src/mcp/validation/*`
+- `src/mcp/control-plane/handlers/*`
+- `src/mcp/control-plane/types.ts`
+
+## Retained Stable Surface
+
+- `src/mcp/index.ts`
+- `src/mcp/schema.ts`
+- `src/mcp/validation.ts`
+- `src/mcp/control-plane.ts`
+- `src/mcp/stdio-server.ts`
+- implementation MCP services: `doctor.ts`, `client-setup-preview.ts`, `control-plane-snapshot-service.ts`, `resume-context-gate-service.ts`, and `provider-canonical-agent-manifest.ts`
+
+## Source of Truth Updated
+
+- `docs/module-boundaries.md` documents the final retained/removed MCP legacy surface.
+
+## Verification Evidence
+
+- `npx tsc --noEmit` — PASS
+- `npm run build` — PASS
+- `node scripts/run-node-tests.mjs` — PASS, 516 tests / 513 pass / 3 skipped / 0 fail
+- `git diff --check` — PASS
+- GitHub Bun Runtime CI — required PR checks for the archive PR
+
+## SDD Cycle Complete
+
+The change has been planned, implemented in stacked cleanup slices, verified, and archived.

package/docs/sdd/archive/2026-06-26-legacy-facade-cleanup/design.md

@@ -0,0 +1,43 @@
+# Design: Legacy Facade Cleanup
+
+## Technical Approach
+
+Audit the legacy compatibility layer before deleting. Remove facades only after all source/test imports are migrated to canonical owners and verification passes.
+
+## Architecture Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Keep `src/mcp/index.ts` initially | Retain as stable barrel | Many tests and consumers use it as a package-like MCP API surface. |
+| Delete narrow per-file facades | Remove when imports migrate | These files add noise and duplicate path choices without runtime value. |
+| Prefer canonical imports in source | `interfaces`, `application`, `adapters` | Keeps ownership aligned with `docs/module-boundaries.md`. |
+
+## File Changes
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/mcp/client-install-*`, `src/mcp/claude-code-*`, `src/mcp/opencode-*` | Delete candidate | One-line provider-install facades after import migration. |
+| `src/mcp/provider-*.ts` | Delete candidate | One-line application facades if direct imports can move. |
+| `src/mcp/schema.ts`, `validation.ts`, `control-plane.ts`, `stdio-server.ts` | Keep candidate | Stable MCP edge facades unless proven unnecessary. |
+| `test/*` | Modify | Update import paths away from deleted facades. |
+
+## Interfaces / Contracts
+
+No product contract changes. The cleanup affects internal source import paths. If package-level API compatibility is required later, `src/mcp/index.ts` can continue to export canonical modules.
+
+## Testing Strategy
+
+| Layer | What to Test | Approach |
+|-------|-------------|----------|
+| Static | Missing imports | `npx tsc --noEmit` |
+| Package | Build output | `npm run build` |
+| Regression | Existing behavior | `node scripts/run-node-tests.mjs` |
+| Runtime matrix | Bun/package evidence | GitHub Actions checks |
+
+## Migration / Rollout
+
+No data migration required. Implement as stacked cleanup PRs so each deletion set is independently revertible.
+
+## Open Questions
+
+None.

package/docs/sdd/archive/2026-06-26-legacy-facade-cleanup/proposal.md

@@ -0,0 +1,61 @@
+# Proposal: Legacy Facade Cleanup
+
+## Intent
+
+Remove obsolete compatibility facades and dead legacy paths after the structure/provider-install migrations. The goal is to reduce tool sprawl, avoid misleading public-looking paths, and keep canonical ownership obvious.
+
+## Scope
+
+### In Scope
+- Audit compatibility facades under `src/mcp/*`, especially one-line re-export files created during migration.
+- Update internal source and tests to canonical imports under `src/interfaces/*`, `src/application/*`, and `src/adapters/*`.
+- Delete legacy files that are no longer used by source, tests, package runtime, or documented stable entrypoints.
+- Preserve intentional barrels/entrypoints such as `src/mcp/index.ts` only where they remain useful.
+
+### Out of Scope
+- Behavior changes to CLI or MCP tools.
+- Removing runtime MCP transport/schema modules that are still canonical or package-facing.
+- Large unrelated migrations outside the audited legacy surface.
+
+## Capabilities
+
+### New Capabilities
+None.
+
+### Modified Capabilities
+None — pure refactor/cleanup with behavior preservation.
+
+## Approach
+
+Use static import search, typecheck, build, full Node tests, and GitHub Bun CI to prove removals are safe. Prefer small stacked PRs: planning, one or more deletion/update slices, final archive.
+
+## Affected Areas
+
+| Area | Impact | Description |
+|------|--------|-------------|
+| `src/mcp/*` | Removed/Modified | Delete obsolete compatibility facades; keep intentional MCP edge modules. |
+| `src/interfaces/*` | Modified | Replace old imports with canonical owners. |
+| `src/application/*` | Modified | Replace old imports with canonical owners. |
+| `test/*` | Modified | Stop testing obsolete import paths unless explicitly testing a kept barrel. |
+| `docs/module-boundaries.md` | Modified | Document what remains and what was removed. |
+
+## Risks
+
+| Risk | Likelihood | Mitigation |
+|------|------------|------------|
+| Removing an import path external consumers use | Medium | Keep stable barrels or document explicit breaking/internal cleanup. |
+| Hidden runtime import missed by static search | Low | Run build, full Node suite, package evidence CI. |
+
+## Rollback Plan
+
+Revert the cleanup PR; all changes are source/test/doc edits with no data migration.
+
+## Dependencies
+
+- Existing SDD archives for structure reorganization and provider-install adapter boundary.
+
+## Success Criteria
+
+- [ ] Obsolete one-line facades are deleted or explicitly justified.
+- [ ] Source and tests use canonical imports for removed paths.
+- [ ] `tsc`, build, full Node tests, and remote Bun CI pass.

package/docs/sdd/archive/2026-06-26-legacy-facade-cleanup/spec.md

@@ -0,0 +1,31 @@
+# Spec: Legacy Facade Cleanup
+
+## Requirements
+
+### Requirement: Safe Legacy Removal
+
+The system MUST remove only legacy files proven unused by current source, tests, docs, and package verification.
+
+#### Scenario: Obsolete facade is unused
+
+- GIVEN a one-line compatibility facade has a canonical replacement
+- WHEN static import search finds no required internal consumers after migration
+- THEN the facade MAY be deleted
+- AND tests MUST import the canonical owner or an intentional stable barrel instead.
+
+#### Scenario: Facade remains intentional
+
+- GIVEN a compatibility path is still a stable public barrel or executable edge
+- WHEN cleanup audits the file
+- THEN the file MUST remain
+- AND docs SHOULD explain why it is intentionally retained.
+
+### Requirement: Behavior Preservation
+
+The system MUST preserve CLI and MCP runtime behavior while removing legacy import paths.
+
+#### Scenario: Cleanup completes
+
+- GIVEN legacy files were removed or imports changed
+- WHEN typecheck, build, full Node tests, and remote Bun CI run
+- THEN all checks MUST pass with no behavior-contract changes.

package/docs/sdd/archive/2026-06-26-legacy-facade-cleanup/tasks.md

@@ -0,0 +1,27 @@
+# Tasks: Legacy Facade Cleanup
+
+## Phase 1: Audit and Planning
+
+- [x] 1.1 Create proposal, spec, design, and tasks.
+- [x] 1.2 Generate static inventory of legacy facades and internal imports.
+- [x] 1.3 Decide keep/delete set for each legacy path.
+
+## Phase 2: Provider Install Facade Removal
+
+- [x] 2.1 Update source and tests away from `src/mcp/client-install-*`, `src/mcp/claude-code-*`, and `src/mcp/opencode-*` per-file facades.
+- [x] 2.2 Delete obsolete provider-install facade files.
+- [x] 2.3 Run targeted provider/MCP tests and typecheck.
+
+## Phase 3: Provider Setup Facade Removal
+
+- [x] 3.1 Update source/tests away from obsolete `src/mcp/provider-*.ts` per-file facades where safe.
+- [x] 3.2 Delete unused provider setup facade files or document retained ones.
+- [x] 3.3 Run targeted provider/control-plane tests and typecheck.
+
+- [x] 3.4 Remove unused nested MCP interface subfacades (`contracts/`, `schemas/`, `validation/`, `control-plane/handlers/`) after confirming no source/test/docs imports.
+
+## Phase 4: Final Verification and Archive
+
+- [x] 4.1 Update module-boundary docs with final retained/removed legacy surface.
+- [x] 4.2 Run typecheck, build, full Node tests, and remote Bun CI.
+- [x] 4.3 Add apply-progress, verify-report, archive-report, and archive the SDD.

package/docs/sdd/archive/2026-06-26-legacy-facade-cleanup/verify-report.md

@@ -0,0 +1,58 @@
+# Verify Report: Legacy Facade Cleanup
+
+## Verdict
+
+PASS WITH WARNINGS.
+
+## Change
+
+- Change: `legacy-facade-cleanup`
+- Mode: filesystem SDD artifacts under `docs/sdd/`
+- Verification date: 2026-06-26
+
+## Task Completeness
+
+| Phase | Status | Evidence |
+|---|---|---|
+| Phase 1 Audit and Planning | PASS | Tasks 1.1-1.3 checked. |
+| Phase 2 Provider Install Facade Removal | PASS | Tasks 2.1-2.3 checked. |
+| Phase 3 Provider Setup / Nested Facade Removal | PASS | Tasks 3.1-3.4 checked. |
+| Phase 4 Final Verification and Archive | PASS | Tasks 4.1-4.3 checked. |
+
+No unchecked tasks remain.
+
+## Requirement Compliance Matrix
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| Safe Legacy Removal | PASS | Static searches found no active source/test/docs imports for deleted provider install, provider setup, or nested interface facade paths outside historical SDD/audit notes. |
+| Intentional Facades Retained | PASS | Remaining one-line MCP facades are only top-level stable entrypoints: `src/mcp/schema.ts`, `validation.ts`, `control-plane.ts`, and `stdio-server.ts`; `src/mcp/index.ts` remains the stable barrel. |
+| Behavior Preservation | PASS | Typecheck, build, full Node suite, and PR CI checks passed during each slice. |
+
+## Runtime Evidence
+
+| Command / Evidence | Result |
+|---|---|
+| `npx tsc --noEmit` | PASS |
+| `npm run build` | PASS |
+| `node scripts/run-node-tests.mjs` | PASS — 516 tests, 513 pass, 3 skipped, 0 fail |
+| `git diff --check` | PASS |
+| Local Bun verification | SKIPPED — local environment reports `bun-not-installed`; GitHub Actions covers Bun Runtime matrix |
+
+## Issues
+
+### Critical
+
+None.
+
+### Warnings
+
+- Local environment does not have `bun`; required GitHub PR checks provide Bun Runtime and package evidence validation.
+
+### Suggestions
+
+- Future cleanup can evaluate non-MCP compatibility barrels (`src/cli/*`, `src/runs/*`, etc.) with the same audit pattern, but they were outside this SDD scope.
+
+## Final Verdict
+
+PASS WITH WARNINGS. The cleanup removed obsolete legacy MCP facades and retained only intentional stable top-level MCP entrypoints.

package/docs/sdd/archive/2026-06-26-provider-install-adapter-boundary/apply-progress.md

@@ -0,0 +1,65 @@
+# Apply Progress: Provider Install Adapter Boundary
+
+## Completed Tasks
+
+- [x] 1.1 Created `docs/sdd/provider-install-adapter-boundary/proposal.md`.
+- [x] 1.2 Created `docs/sdd/provider-install-adapter-boundary/spec.md`.
+- [x] 1.3 Created `docs/sdd/provider-install-adapter-boundary/design.md` and `tasks.md`.
+- [x] 2.1 Moved `src/mcp/client-install-opencode*.ts` to `src/adapters/opencode/install/` with old-path facades.
+- [x] 2.2 Moved OpenCode helper modules (`opencode-default-agent-config`, `opencode-handoff-preview`, `opencode-visibility`) to `src/adapters/opencode/install/` with old-path facades.
+- [x] 2.3 Updated canonical OpenCode imports in application/setup/interface code and ran targeted provider tests.
+- [x] 3.1 Moved `src/mcp/client-install-claude-code*.ts` to `src/adapters/claude/install/` with old-path facades.
+- [x] 3.2 Moved Claude helper modules (`claude-code-agent-config`, CLI/config/memory/scope/user config helpers) to `src/adapters/claude/install/`.
+- [x] 3.3 Updated canonical Claude imports in application/setup/interface code and ran targeted provider tests.
+- [x] 4.1 Updated `docs/module-boundaries.md` so provider install helper paths are documented as compatibility facades.
+- [x] 4.2 Ran final local typecheck, build, and full Node test suite; PR CI will provide remote Bun verification.
+- [x] 4.3 Added verify/archive reports and archived the SDD packet.
+
+## Files Changed
+
+| File | Action | What Changed |
+|---|---|---|
+| `src/adapters/opencode/install/client-install-opencode.ts` | Created | Canonical OpenCode MCP install apply implementation. |
+| `src/adapters/opencode/install/client-install-opencode-contract.ts` | Created | Canonical OpenCode install planning/contracts. |
+| `src/adapters/opencode/install/opencode-default-agent-config.ts` | Created | Canonical OpenCode default agent and permission helpers. |
+| `src/adapters/opencode/install/opencode-handoff-preview.ts` | Created | Canonical OpenCode handoff preview service. |
+| `src/adapters/opencode/install/opencode-visibility.ts` | Created | Canonical OpenCode visibility report helper. |
+| `src/mcp/client-install-opencode*.ts`, `src/mcp/opencode-*.ts` | Modified | Compatibility facades re-export the canonical adapter modules. |
+| `src/application/provider-setup/*`, `src/setup/*`, `src/interfaces/*` | Modified | OpenCode-specific imports point at the adapter boundary where practical. |
+| `docs/sdd/provider-install-adapter-boundary/tasks.md` | Updated | Marks Phase 2 OpenCode, Phase 3 Claude, and Phase 4 cleanup tasks complete. |
+| `docs/module-boundaries.md` | Updated | Documents provider-install MCP paths as compatibility facades with canonical adapter owners. |
+| `src/adapters/claude/install/*` | Created | Canonical Claude Code install contract/apply, config, memory, scope, and CLI helper modules. |
+| `src/mcp/client-install-claude-code*.ts`, `src/mcp/claude-code-*.ts` | Modified | Compatibility facades re-export the canonical Claude adapter modules. |
+
+## Deviations from Design
+
+- OpenCode helpers were grouped under `src/adapters/opencode/install/` even when they are read-only preview/visibility helpers. This keeps the OpenCode install slice cohesive and can be split further later if needed.
+- Tests continue to import old `src/mcp/*` paths where they exercise compatibility; application/setup/interface internals now prefer the canonical adapter path.
+
+## Issues Found
+
+None.
+
+## Verification
+
+- [x] `npx biome check --write --unsafe src/adapters/opencode/install src/mcp/client-install-opencode.ts src/mcp/client-install-opencode-contract.ts src/mcp/opencode-default-agent-config.ts src/mcp/opencode-handoff-preview.ts src/mcp/opencode-visibility.ts src/interfaces/cli/commands/mcp-dispatcher.ts src/interfaces/cli/commands/setup-dispatcher.ts src/interfaces/cli/cli-flags.ts src/interfaces/mcp/control-plane.ts src/interfaces/mcp/control-plane/types.ts src/setup/providers/opencode-setup-adapter.ts src/setup/setup-plan.ts src/application/provider-setup`
+- [x] `npx tsc --noEmit`
+- [x] `node scripts/run-node-tests.mjs test/mcp/client-install-opencode.test.ts test/mcp/client-install-opencode-contract.test.ts test/mcp/opencode-visibility.test.ts test/mcp/opencode-handoff-preview.test.ts test/mcp/provider-status.test.ts test/mcp/provider-doctor.test.ts test/mcp/opencode-agent-config-drift.test.ts test/agents/agent-seed-service.test.ts` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/adapters/claude/install src/mcp/client-install-claude-code.ts src/mcp/client-install-claude-code-contract.ts src/mcp/claude-code-agent-config.ts src/mcp/claude-code-cli.ts src/mcp/claude-code-config.ts src/mcp/claude-code-project-memory.ts src/mcp/claude-code-scope.ts src/mcp/claude-code-user-config.ts src/mcp/claude-code-user-memory.ts src/interfaces/cli/commands/mcp-dispatcher.ts src/setup/providers/claude-setup-adapter.ts src/setup/setup-plan.ts src/application/provider-setup`
+- [x] `npx tsc --noEmit` after Claude move
+- [x] `node scripts/run-node-tests.mjs test/mcp/client-install-claude-code.test.ts test/setup/providers/claude-setup-adapter.test.ts test/mcp/provider-status.test.ts test/mcp/provider-doctor.test.ts` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx tsc --noEmit` final verification
+- [x] `npm run build` final verification
+- [x] `node scripts/run-node-tests.mjs` final verification — passed 516 tests, 513 pass, 3 skipped
+- [x] Bun CI-equivalent suites: to be verified by PR checks (`Bun verify` and `Bun package evidence` on ubuntu/macos/windows)
+
+## Remaining Tasks
+
+No implementation tasks remain; ready for archive.
+
+## Workload / PR Boundary
+
+- Mode: stacked PR slice
+- Current work unit: Final cleanup and archive
+- Boundary: final docs update, verification evidence, and archive; no behavior changes
+- Estimated review budget impact: low

package/docs/sdd/archive/2026-06-26-provider-install-adapter-boundary/archive-report.md

@@ -0,0 +1,53 @@
+# Archive Report: Provider Install Adapter Boundary
+
+## Archive Summary
+
+- Change: `provider-install-adapter-boundary`
+- Archive date: 2026-06-26
+- Source artifact mode: filesystem SDD artifacts under `docs/sdd/`
+- Archived to: `docs/sdd/archive/2026-06-26-provider-install-adapter-boundary/`
+- Verification verdict: PASS WITH WARNINGS; no critical issues.
+
+## Source Artifacts
+
+| Artifact | Status |
+|---|---|
+| `proposal.md` | Present |
+| `spec.md` | Present |
+| `design.md` | Present |
+| `tasks.md` | Present; all tasks checked |
+| `apply-progress.md` | Present |
+| `verify-report.md` | Present |
+
+## Task Completion Gate
+
+PASS. `tasks.md` has no unchecked implementation tasks:
+
+- Phase 1 SDD planning complete
+- Phase 2 OpenCode adapter slice complete
+- Phase 3 Claude Code adapter slice complete
+- Phase 4 cleanup and verification complete
+
+## Specs Synced
+
+No `openspec/` tree exists in this repository. The source of truth for this change is the archived filesystem SDD packet plus updated current-state docs.
+
+## Source of Truth Updated
+
+- `docs/module-boundaries.md` now documents provider install MCP paths as compatibility facades and names `src/adapters/opencode/install/*` and `src/adapters/claude/install/*` as canonical owners.
+
+## Verification Evidence
+
+- `npx tsc --noEmit` — PASS
+- `npm run build` — PASS
+- `node scripts/run-node-tests.mjs` — PASS, 516 tests / 513 pass / 3 skipped / 0 fail
+- `git diff --check` — PASS
+- GitHub Bun Runtime CI — required PR checks for the archive PR
+
+## Remaining Follow-Up Candidates
+
+- Optional future removal of MCP compatibility facades after public import consumers are migrated or the API decision is made.
+
+## SDD Cycle Complete
+
+The change has been planned, implemented in provider slices, verified, and archived.