vgxness 1.20.4 → 1.20.6

package/docs/architecture.md

@@ -93,11 +93,11 @@ Gentle-AI/`gentle-pi` are strong references for the configurator and agent-behav
 
 ### Agent registry self-healing
 
-The canonical agent manifest in `src/agents/canonical-agent-manifest.ts` is the source of truth for built-in agents (1 manager + 10 SDD subagents). At every CLI/MCP boot, `src/agents/boot-upgrade.ts` reconciles the live `agents` table with that manifest via `src/agents/agent-seed-upgrade-service.ts`: missing rows are created, drifted rows (changed `vgxnessPromptContractVersion`, instructions, adapters, or description) are overwritten, and matches are recorded as noop. Each non-noop outcome is appended to the `agent_seed_history` table for audit. Operators can opt out with `VGXNESS_SKIP_AGENT_SEED_AUTO_UPGRADE=1`. This eliminates the long-standing drift between the canonical prompt contract and stored agent rows after a version bump.
+The canonical agent manifest in `src/domain/agents/canonical-agent-manifest.ts` is the source of truth for built-in agents (1 manager + 10 SDD subagents). At every CLI/MCP boot, `src/application/agents/boot-upgrade.ts` reconciles the live `agents` table with that manifest via `src/application/agents/agent-seed-upgrade-service.ts`: missing rows are created, drifted rows (changed `vgxnessPromptContractVersion`, instructions, adapters, or description) are overwritten, and matches are recorded as noop. Each non-noop outcome is appended to the `agent_seed_history` table for audit. Operators can opt out with `VGXNESS_SKIP_AGENT_SEED_AUTO_UPGRADE=1`. This eliminates the long-standing drift between the canonical prompt contract and stored agent rows after a version bump. The old `src/agents/*` paths remain compatibility facades during the migration window.
 
 ### Manager overlay parity across providers
 
-A user-saved `manager_profile_overlay` flows to both providers symmetrically. OpenCode consults the overlay inside `OpenCodeManagerPayloadService.applyManagerOverlayWhenAvailable` (`src/providers/opencode/manager-payload.ts:152-156`), which calls `ManagerProfileOverlayService.resolveEffectiveManager` before producing the OpenCode manager payload. Claude Code was previously canonical-only; the fix routes the overlay through `withEffectiveManagerInstructions` (`src/agents/canonical-agent-projection.ts`) into the render path (`expectedClaudeCodeRenderedAgents` / `expectedClaudeCodeRenderedUserAgents`), with the caller (`mcp install claude` in `src/cli/commands/mcp-dispatcher.ts`) computing the effective instructions via `computeEffectiveManagerInstructions(database)` and passing them into `installClaudeCodeMcpClient`. As a result, `vgxness mcp install claude` writes the user's customized instructions into the user-global `~/.claude/agents/vgxness-manager.md` instead of silently falling back to canonical; project-local Claude agent files remain external/manual diagnostics.
+A user-saved `manager_profile_overlay` flows to both providers symmetrically. OpenCode consults the overlay while building the manager payload, and Claude Code routes the overlay through `withEffectiveManagerInstructions` (`src/application/agents/canonical-agent-projection.ts`) into the render path (`expectedClaudeCodeRenderedAgents` / `expectedClaudeCodeRenderedUserAgents`), with the caller (`mcp install claude` in `src/interfaces/cli/commands/mcp-dispatcher.ts`) computing the effective instructions via `computeEffectiveManagerInstructions(database)` and passing them into `installClaudeCodeMcpClient`. As a result, `vgxness mcp install claude` writes the user's customized instructions into the user-global `~/.claude/agents/vgxness-manager.md` instead of silently falling back to canonical; project-local Claude agent files remain external/manual diagnostics.
 
 ## Storage model
 

package/docs/glossary.md

@@ -32,7 +32,7 @@ The canonical installed CLI/MCP runtime and verification path. Required `>= 1.3.
 
 ## Canonical agent manifest
 
-The built-in, validated manifest that defines the manager agent and the SDD subagents (`vgxness-sdd-explore`, `vgxness-sdd-propose`, `vgxness-sdd-spec`, `vgxness-sdd-design`, `vgxness-sdd-tasks`, `vgxness-sdd-apply`, `vgxness-sdd-verify`, `vgxness-sdd-archive`, plus `init` and `onboard`). Lives in `src/agents/canonical-agent-manifest.ts`. `promptContractVersion` increments on breaking contract changes.
+The built-in, validated manifest that defines the manager agent and the SDD subagents (`vgxness-sdd-explore`, `vgxness-sdd-propose`, `vgxness-sdd-spec`, `vgxness-sdd-design`, `vgxness-sdd-tasks`, `vgxness-sdd-apply`, `vgxness-sdd-verify`, `vgxness-sdd-archive`, plus `init` and `onboard`). Lives in `src/domain/agents/canonical-agent-manifest.ts` with old-path compatibility through `src/agents/canonical-agent-manifest.ts`. `promptContractVersion` increments on breaking contract changes.
 
 ## Change (SDD)
 

package/docs/mcp.md

@@ -47,7 +47,7 @@ Use memory for durable, future-relevant facts that are reusable beyond the curre
 - **Good:** personal-scoped `preference` — "Prefer concise SDD apply summaries with changed files and verification evidence."
 - **Bad:** full phase artifacts, full transcripts, raw large logs, hidden reasoning, secrets, credentials, or sensitive user data.
 
-Memory is advisory only: it never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables and governance state. Active-work memory remains advisory and should point to current context without replacing artifacts or runs. `memory-write` is a durable governed action; use preflight or explicit consent whenever policy marks it governed/risky.
+Memory is advisory only: it never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables and governance state. Active-work memory remains advisory and should point to current context without replacing artifacts or runs. Ordinary qualifying `memory-write` operations are agent-decided and audit-only so the manager can preserve durable decisions, architecture choices, reusable project conventions, workflow preferences, and non-obvious gotchas without duplicate confirmation. Ask first when the content is sensitive, ambiguous, user-personal beyond stated preferences, or the user explicitly says not to persist it.
 
 Lifecycle responses may include `memoryCapture` metadata for review-first memory candidates, such as session close summaries, run finalization outcomes, and SDD acceptance/archive references. These candidates are advisory only and are never persisted automatically: there is no durable candidate queue, and callers must make a separate explicit `vgxness_memory_save` or `vgxness_memory_update` decision under the same durable memory policy. `memoryCapture` must not include full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, sensitive data, or other protected content, and it is not proof of SDD acceptance, readiness, verification, approval, or authorization.
 

package/docs/module-boundaries.md

@@ -0,0 +1,114 @@
+# Module Boundaries
+
+`vgxness` is organized around a provider-neutral control plane with multiple interfaces. Source layout should make that architecture obvious: product rules live in domain/application modules, storage details live in storage modules, provider details live in adapters, and CLI/MCP/TUI code stays at the edge.
+
+## Target Layout
+
+```text
+src/domain/<area>/          # schemas, contracts, invariants, pure policy
+src/application/<area>/     # use-case services and orchestration
+src/storage/<area>/         # repositories and store-specific code
+src/adapters/<provider>/    # OpenCode, Claude Code, future providers
+src/interfaces/cli/         # command parsing and human rendering
+src/interfaces/mcp/         # MCP schemas, tool handlers, stdio server
+src/interfaces/tui/         # Ink/TUI state and visual components
+```
+
+## Ownership Rules
+
+| Layer | Owns | Must Not Own |
+|---|---|---|
+| `domain` | Types, schemas, invariants, pure policy decisions | SQLite calls, filesystem writes, CLI formatting, MCP transport |
+| `application` | Use-case services and orchestration across domain/storage/adapters | Command-line parsing, terminal rendering, direct provider config file formats |
+| `storage` | Repositories, migrations access, persistence-specific mapping | Product workflow rules or provider behavior |
+| `adapters` | Provider-specific projections, config formats, external integration details | Provider-neutral workflow semantics |
+| `interfaces/cli` | Args, command dispatch, human-readable output | Business rules not exposed by application services |
+| `interfaces/mcp` | MCP schemas, tool handlers, stdio/server transport | Provider install semantics or duplicated service logic |
+| `interfaces/tui` | Visual state and rendering | Product rules not available through shared services |
+
+## Import Rules
+
+1. Interface modules call application services; they should not reach into repositories directly.
+2. Application modules may use domain contracts, storage repositories, and adapters.
+3. Domain modules must be pure and should not import application, storage, adapters, or interfaces.
+4. Storage modules may import domain contracts for mapping, but must not make workflow decisions.
+5. Adapter modules may import domain/application contracts needed for projection, but provider-specific behavior must not leak into domain modules.
+6. Public barrels/facades should be intentional. Avoid exporting every internal file by default.
+
+## Compatibility Facades
+
+During migration, existing public entrypoints may remain as facades that re-export or delegate to the new location. A compatibility facade is allowed when it:
+
+- preserves existing imports during a reviewable slice;
+- contains no duplicated business logic;
+- clearly points maintainers to the new canonical module;
+- has a planned removal or stabilization decision before the migration is archived.
+
+Stable compatibility candidates include:
+
+```text
+src/mcp/index.ts
+src/mcp/schema.ts
+src/mcp/validation.ts
+src/mcp/control-plane.ts
+src/mcp/stdio-server.ts
+src/permissions/index.ts
+src/verification/index.ts
+src/setup/index.ts
+src/cli/commands/index.ts
+```
+
+After the structure reorganization, migrated compatibility paths are expected to
+remain implementation-free facades unless they are deliberate executable
+entrypoints such as `src/cli/index.ts` and `src/cli/bun-bin.ts`. Canonical code
+now lives under the target layout below:
+
+| Compatibility path | Canonical owner |
+|---|---|
+| `src/runs/*` | `src/domain/runs`, `src/application/runs`, `src/storage/runs` |
+| `src/cli/*` | `src/interfaces/cli/*` |
+| `src/mcp/index.ts`, `src/mcp/schema.ts`, `src/mcp/validation.ts`, `src/mcp/control-plane.ts`, `src/mcp/stdio-server.ts` | `src/interfaces/mcp/*` plus canonical application/adapter exports |
+| `src/skills/*` | `src/domain/skills`, `src/application/skills`, `src/storage/skills` |
+| `src/sdd/*` | `src/domain/sdd`, `src/application/sdd` |
+| `src/agents/*` | `src/domain/agents`, `src/application/agents`, `src/storage/agents`, `src/adapters/*` |
+| `src/application/agents/renderers/*` | `src/adapters/*` |
+| `src/memory/*` | `src/domain/memory`, `src/application/memory`, `src/storage/memory` |
+
+Obsolete narrow MCP facades were removed after audit. Provider install helpers
+now live only under `src/adapters/opencode/install/*` and
+`src/adapters/claude/install/*`; provider setup helpers live under
+`src/application/provider-setup/*`; nested MCP interface subfacades such as
+`src/mcp/contracts/*`, `src/mcp/schemas/*`, and `src/mcp/validation/*` were
+deleted because active source/tests/docs do not import them.
+
+## Migration Map
+
+| Current Area | Target Area | Migration Notes |
+|---|---|---|
+| `src/runs` | `src/domain/runs`, `src/application/runs`, `src/storage/runs` | Split lifecycle, approvals, checkpoints, grants, repositories |
+| `src/mcp` | `src/interfaces/mcp`, `src/application/provider-setup`, `src/adapters/*` | Keep tool names stable; separate transport from provider setup |
+| `src/cli` | `src/interfaces/cli` | Dispatch/render only; call application services for behavior |
+| `src/skills` | `src/domain/skills`, `src/application/skills`, `src/storage/skills` | Separate schema, resolver, registry service, repository |
+| `src/sdd` | `src/domain/sdd`, `src/application/sdd` | Keep workflow contracts separate from state service |
+| `src/agents` | `src/domain/agents`, `src/application/agents`, `src/adapters/*` | Keep neutral agent model separate from provider projections |
+| `src/memory` | `src/domain/memory`, `src/application/memory`, `src/storage/memory` | Keep SQLite and import/export mapping out of domain rules |
+| `src/providers` | `src/adapters/*` | Provider-specific implementations move under adapter ownership |
+| `src/setup` | `src/application/setup`, `src/adapters/*` | Setup lifecycle is application logic; provider writes stay adapter-specific |
+| `src/verification` | `src/domain/verification`, `src/application/verification` | Plans/reports use shared contracts across CLI/MCP |
+| `src/governance` | `src/domain/governance`, `src/application/governance` | Risk and report contracts should remain provider-neutral |
+| `src/workflows` | `src/domain/workflows`, `src/application/workflows` | Workflow definitions and executor orchestration should be split |
+
+## Review Strategy
+
+This migration should be implemented as stacked PRs to `main`. Each PR should be independently typecheckable and revertible.
+
+Recommended order:
+
+1. boundary docs and compatibility rules;
+2. `runs` pilot;
+3. `mcp` pilot;
+4. CLI/interface migration;
+5. remaining domain migrations and provider adapter extraction;
+6. final verification, facade audit, and architecture documentation sync.
+
+Each slice should run the smallest targeted tests that cover moved behavior plus `tsc --noEmit`. Bun-specific storage/runtime tests remain required for slices touching SQLite-backed behavior or package/runtime boundaries.

package/docs/prd.md

@@ -353,7 +353,7 @@ Many early PRD questions were resolved by the v1.5.1 milestone. Tracking them he
 |---|---|
 | First integration adapter | OpenCode primary/default; Claude is supported secondary for user-global explicit apply. Project-local provider files are external/manual diagnostics only. |
 | Memory storage scopes | Project and personal/global data are separated by explicit scope. The selected SQLite store is resolved by `--db`, `VGXNESS_DB_PATH`, or the global default. |
-| Agent config format | Provider-neutral schema in `src/agents/schema.ts`; canonical manifest with validation in `src/agents/canonical-agent-manifest.ts`. |
+| Agent config format | Provider-neutral schema in `src/domain/agents/schema.ts`; canonical manifest with validation in `src/domain/agents/canonical-agent-manifest.ts`. |
 | Skill config format | Versioned skills with source metadata (`path`/`url`/`inline`); active version gating in `src/skills/skill-registry-service.ts`. |
 | Skill improvement approval | All proposals require explicit human approval before activation; rejected/cancelled proposals cannot be applied. |
 | First public CLI surface | `vgxness {init, setup, doctor, mcp, sdd, agents, skills, memory, runs, opencode}`. See [CLI reference](./cli.md). |

package/docs/project-health-audit-v1.10.x.md

@@ -19,7 +19,7 @@ Esta auditoría es una foto de salud v1.10.x basada en inspección read-only del
 | CLI | `src/cli/dispatcher.ts` centraliza comandos para status, next, resume, setup, agents, skills, SDD, runs, permissions, MCP y verification. | Implementado |
 | MCP | `src/mcp/stdio-server.ts` y `src/mcp/schema.ts` exponen herramientas tipadas; el estado observado durante v1.10.x reportó 41 MCP tools. | Implementado |
 | SDD | `src/sdd/sdd-workflow-service.ts` y `docs/architecture.md` definen `explore → proposal → spec → design → tasks → apply-progress → verify → archive`. | Implementado |
-| Storage | `src/memory/sqlite/*` y migraciones en `src/memory/sqlite/migrations/*.sql`; runtime real depende de `bun:sqlite`. | Implementado |
+| Storage | `src/storage/memory/sqlite/*` y migraciones en `src/storage/memory/sqlite/migrations/*.sql`; runtime real depende de `bun:sqlite`. | Implementado |
 | Providers | OpenCode es primario; Claude está soportado/guarded; Antigravity/custom son extensiones futuras/placeholders. | Mixto |
 | Provider health | `vgxness_provider_doctor` para OpenCode pasó 12/12 checks, sin warnings/errors y sin escribir provider config. | Saludable |
 | Git | `git status --short --branch` reportó `## main...origin/main`; `git diff --stat` y cached diff sin cambios antes de esta auditoría. | Limpio antes del cambio |

package/docs/providers.md

@@ -76,7 +76,7 @@ Manual/opt-in runtime validation checklist (not normal CI):
 
 ### OpenCode injection preview
 
-`OpenCodeInjectionPreviewService` (in `src/providers/opencode/`) composes existing read-only outputs into a single envelope:
+Provider-specific preview/rendering code lives under `src/adapters/*`. `OpenCodeInjectionPreviewService` composes existing read-only outputs into a single envelope:
 
 | Output | Source |
 |---|---|
@@ -97,7 +97,7 @@ The experimental `vgxness code` runtime, its OpenAI-compatible/fake providers, a
 
 ## OpenCode provider install and doctor
 
-Provider install and doctor flows live in `src/mcp/client-install-opencode.ts` and `src/mcp/provider-doctor.ts` and are exposed through the MCP server and the CLI:
+Provider install and doctor flows live in `src/adapters/opencode/install/client-install-opencode.ts` and `src/application/provider-setup/provider-doctor.ts` and are exposed through the MCP server and the CLI:
 
 - `vgxness mcp install opencode --plan` — plan that never writes provider config; local VGXNESS store initialization may occur when the selected SQLite store is needed.
 - `vgxness mcp install opencode --yes` — explicit write path; creates a backup first.

package/docs/safety.md

@@ -27,8 +27,8 @@ The category list lives in `src/permissions/schema.ts` (`permissionCategories`).
 | `network` | `ask` | yes | Web fetch, API calls, package downloads. |
 | `git` | `ask` | yes | Status, diff, branch, commit. |
 | `git-write` | `ask` | yes | Push, merge, branch mutation. |
-| `memory` | `ask` | yes | Memory read/write/search. |
-| `memory-write` | `ask` | yes | Memory upsert/update. |
+| `memory` | `audit` | no | Memory read/search and ordinary qualifying memory writes are audited but non-blocking. |
+| `memory-write` | `audit` | no | Agent-decided memory upsert/update for durable, scoped, non-sensitive observations; ask only when content is sensitive, ambiguous, or explicitly non-persistent. |
 | `external-directory` | `deny` | yes | Access outside project/user-approved roots. Cannot be relaxed by agent overrides. |
 | `provider-tool` | `ask` | yes | Opaque adapter/provider tool calls. |
 | `secrets` | `deny` | yes | Environment variables, credentials, tokens. |
@@ -56,7 +56,7 @@ The matrix (`sddPhasePermissionMatrix`, version `sdd-phase-permissions-v1`) give
 
 | Phase | Distinctive modes (vs. the planning baseline) |
 |---|---|
-| `explore`, `proposal`, `spec`, `design`, `tasks`, `archive` | Planning baseline. Reads allowed; edits denied; spec/design/task writes, shell, install, network, git, memory all `require-preflight`; provider-tool `audit`; external-directory and secrets `deny`. |
+| `explore`, `proposal`, `spec`, `design`, `tasks`, `archive` | Planning baseline. Reads allowed; edits denied; spec/design/task writes, shell, install, network, and git are `require-preflight`; memory and provider-tool are `audit`; external-directory and secrets `deny`. |
 | `apply-progress` | Edits and `implementation-edit` are `require-preflight` (instead of `deny`). Shell and `test-run` are `require-preflight`. |
 | `verify` | Edits and `implementation-edit` stay `deny`. Shell and `test-run` are `require-preflight`. |
 

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

@@ -0,0 +1,122 @@
+# Apply Progress: Ambitious Structure Reorganization
+
+## Completed Tasks
+
+- [x] 1.1 Created `docs/module-boundaries.md` with target layout, ownership rules, import rules, and migration map.
+- [x] 1.2 Added compatibility policy for old barrels/facades and deprecation criteria.
+- [x] 1.3 Identified stable public entrypoint candidates, including `src/mcp/index.ts`, `src/mcp/schema.ts`, `src/mcp/validation.ts`, `src/permissions/index.ts`, `src/verification/index.ts`, `src/setup/index.ts`, and `src/cli/commands/index.ts`.
+- [x] 2.1 Created target folders for `src/domain/runs`, `src/application/runs`, and `src/storage/runs`.
+- [x] 2.2 Moved run application services behind compatibility facades while preserving public imports.
+- [x] 2.3 Moved run repositories under the storage layer while preserving old imports.
+- [x] 2.4 Verified the runs pilot with typecheck and test execution.
+- [x] 3.1 Created `src/interfaces/mcp` for MCP contracts, schemas, validation, control-plane handlers, and stdio server.
+- [x] 3.3 Preserved MCP tool names and `SUPPORTED_VGX_MCP_TOOL_NAMES` behavior through old-path facades.
+- [x] 3.4 Verified the MCP interface pilot with typecheck and targeted MCP tests.
+- [x] 3.2 Moved provider setup/status services into `src/application/provider-setup` with old-path facades.
+- [x] 4.1 Moved CLI command parsing/rendering modules into `src/interfaces/cli` with old-path facades while preserving executable entrypoints.
+- [x] 4.2a Moved `skills` into `src/domain/skills`, `src/application/skills`, and `src/storage/skills` with old-path facades.
+- [x] 4.2b Moved `sdd` into `src/domain/sdd` and `src/application/sdd` with old-path facades.
+- [x] 4.2c Moved `agents` into `src/domain/agents`, `src/application/agents`, and `src/storage/agents` with old-path facades.
+- [x] 4.2d Moved `memory` into `src/domain/memory`, `src/application/memory`, and `src/storage/memory` with old-path facades.
+- [x] 4.3 Moved provider renderer/projection implementations into `src/adapters/*` with old-path facades.
+- [x] 5.1 Ran final local verification and queued remote Bun CI-equivalent verification for the final cleanup PR.
+- [x] 5.2 Audited migrated compatibility facades and documented remaining non-facade legacy provider-install paths.
+- [x] 5.3 Updated architecture/module-boundary docs with final structure and deprecated-path notes.
+
+## Files Changed
+
+| File | Action | What Changed |
+|---|---|---|
+| `docs/module-boundaries.md` | Created | Documents target layered layout, ownership rules, import rules, compatibility facades, migration map, and stacked PR strategy. |
+| `docs/sdd/ambitious-structure-reorganization/tasks.md` | Updated | Records completed Phase 1, Phase 2, and MCP interface pilot tasks. |
+| `src/domain/runs/schema.ts` | Moved | Establishes the domain boundary for run contracts and stable types. |
+| `src/application/runs/*` | Moved | Houses run use-case services, execution planning, retry, insights, snapshot export, sandbox planning, and grant service code. |
+| `src/storage/runs/repositories/*` | Moved | Houses SQLite-backed run and task-scoped command grant repositories. |
+| `src/runs/*` | Modified | Compatibility facades re-export the new canonical modules for existing imports. |
+| `src/interfaces/mcp/*` | Moved | Houses MCP contracts, schemas, validation, control-plane handlers/types, and stdio server. |
+| `src/mcp/*` | Modified | Compatibility facades re-export moved MCP interface modules while provider setup/status modules stay in place. |
+| `test/mcp/validation.test.ts` | Modified | Reads canonical MCP validation/control-plane sources from `src/interfaces/mcp`. |
+| `src/application/provider-setup/*` | Moved | Houses provider status, doctor, change-plan, and provider health contracts. |
+| `src/mcp/provider-*.ts` | Modified | Compatibility facades re-export provider setup modules from the application layer. |
+| `src/interfaces/cli/*` | Moved | Canonical CLI command dispatchers, renderers, TUI helpers, and CLI support modules. |
+| `src/cli/*` | Modified | Compatibility facades for old CLI imports; executable `index.ts` and `bun-bin.ts` remain real entrypoints for package/runtime tests. |
+| `test/cli/tui-zero-import-gate.test.ts` | Modified | Allows canonical `src/interfaces/cli` Ink bridge paths while retaining old path compatibility. |
+| `src/domain/skills/schema.ts` | Moved | Canonical skill domain contracts and types. |
+| `src/application/skills/*` | Moved | Canonical skill registry, resolver, seed, status, index, payload, export, and boot/personal skill services. |
+| `src/storage/skills/repositories/*` | Moved | Canonical skill repository implementations. |
+| `src/skills/*` | Modified | Compatibility facades for old skill imports. |
+| `src/domain/sdd/*` | Moved | Canonical SDD domain contracts, cockpit types, phases, and normalization helpers. |
+| `src/application/sdd/*` | Moved | Canonical SDD workflow, continuation, cockpit read model, and artifact portability services. |
+| `src/sdd/*` | Modified | Compatibility facades for old SDD imports. |
+| `src/domain/agents/*` | Moved | Canonical agent contracts and canonical manifest constants. |
+| `src/application/agents/*` | Moved | Canonical agent registry, resolver, activation, seed/upgrade, projection, overlay, model routing, and renderer services. |
+| `src/storage/agents/repositories/*` | Moved | Canonical agent and manager overlay repository implementations. |
+| `src/agents/*` | Modified | Compatibility facades for old agent imports. |
+| `src/domain/memory/*` | Moved | Canonical memory contracts, capture schema, and active-work topic parsing. |
+| `src/application/memory/*` | Moved | Canonical memory service, active-work preview, capture service, search, and import workflow modules. |
+| `src/storage/memory/*` | Moved | Canonical memory repositories, SQLite database, storage path helpers, and migrations. |
+| `src/memory/*` | Modified | Compatibility facades for old memory imports. |
+| `scripts/copy-migrations.mjs` | Modified | Copies migrations from/to the new storage-layer paths. |
+| `src/adapters/*` | Created | Canonical provider renderer/projection adapter implementations and shared provider-renderer contract. |
+| `src/application/agents/renderers/*` | Modified | Compatibility facades and registry wiring for adapter-owned renderers. |
+| `src/mcp/client-install-*` | Modified | Imports shared adapter sync contracts from the adapter boundary. |
+| `docs/module-boundaries.md` | Updated | Adds post-migration compatibility facade audit and remaining deferred legacy provider-install paths. |
+| `docs/architecture.md` | Updated | Points agent and manager-overlay sections at canonical domain/application/interface paths. |
+| `docs/providers.md`, `docs/prd.md`, `docs/glossary.md` | Updated | Replaces stale provider/agent source paths with the new layered structure. |
+
+## Deviations from Design
+
+- Runs pilot preserved compatibility by moving the full run service/application modules first rather than deeply splitting `RunService` internals into lifecycle/checkpoint/approval submodules in that PR.
+- MCP pilot moved the interface/control-plane boundary first. Provider setup/status services now live under `application/provider-setup`; deeper OpenCode/Claude adapter extraction remains a later cleanup opportunity.
+- Provider adapter extraction in task 4.3 focused on provider renderer/projection code and shared adapter sync contracts; full install workflow moves can remain a future cleanup if needed.
+
+## Issues Found
+
+- The MCP registry sync test read old `src/mcp/validation.ts` and `src/mcp/control-plane.ts` implementation files directly. It was updated to inspect the new canonical `src/interfaces/mcp` sources.
+- Local development environment does not have `bun`; Bun CI-equivalent verification is supplied by the GitHub checks on the final cleanup PR.
+
+## Verification
+
+- [x] `npx biome check --write --unsafe src/application/runs src/domain/runs src/storage/runs src/runs`
+- [x] `npx tsc --noEmit`
+- [x] `node scripts/run-node-tests.mjs test/runs` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/interfaces/mcp src/mcp test/mcp/validation.test.ts`
+- [x] `npx tsc --noEmit`
+- [x] `node scripts/run-node-tests.mjs test/mcp` — passed 516 tests, 513 pass, 3 skipped
+- [x] `git diff --check`
+- [x] `npx tsc --noEmit` after provider setup migration
+- [x] `node scripts/run-node-tests.mjs test/mcp` after provider setup migration — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/interfaces/cli src/cli test/cli/tui-zero-import-gate.test.ts`
+- [x] `npx tsc --noEmit` after CLI interface migration
+- [x] `node scripts/run-node-tests.mjs test/cli` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/domain/skills src/application/skills src/storage/skills src/skills`
+- [x] `npx tsc --noEmit` after skills migration
+- [x] `node scripts/run-node-tests.mjs test/skills` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/domain/sdd src/application/sdd src/sdd`
+- [x] `npx tsc --noEmit` after SDD migration
+- [x] `node scripts/run-node-tests.mjs test/sdd` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/domain/agents src/application/agents src/storage/agents src/agents`
+- [x] `npx tsc --noEmit` after agents migration
+- [x] `node scripts/run-node-tests.mjs test/agents` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/domain/memory src/application/memory src/storage/memory src/memory scripts/copy-migrations.mjs scripts/probe-bun-package-evidence.mjs scripts/probe-bun-sqlite.mjs test/package/installable-cli.test.ts test/scripts/probe-bun-package-evidence.test.ts`
+- [x] `npx tsc --noEmit` after memory migration
+- [x] `npm run build` after migration copy path update
+- [x] `node scripts/run-node-tests.mjs test/memory test/package/installable-cli.test.ts test/scripts/probe-bun-package-evidence.test.ts` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx biome check --write --unsafe src/adapters src/application/agents/renderers src/agents/renderers src/mcp/client-install-opencode-contract.ts src/mcp/client-install-claude-code-contract.ts src/mcp/client-install-opencode.ts src/mcp/client-install-claude-code.ts test/mcp/client-install-opencode-contract.test.ts`
+- [x] `npx tsc --noEmit` after provider adapter extraction
+- [x] `node scripts/run-node-tests.mjs test/agents test/mcp/client-install-opencode-contract.test.ts` — passed 516 tests, 513 pass, 3 skipped
+- [x] `npx tsc --noEmit` final cleanup verification
+- [x] `npm run build` final cleanup verification
+- [x] `node scripts/run-node-tests.mjs` final cleanup 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
+
+Next recommended work unit: SDD verify/archive after the final cleanup PR lands.
+
+## Workload / PR Boundary
+
+- Mode: stacked PR slice
+- Current work unit: Final structure verification and cleanup
+- Boundary: final local verification, compatibility facade audit, and architecture documentation sync; no behavior changes
+- Estimated review budget impact: medium; full migration remains high

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

@@ -0,0 +1,61 @@
+# Archive Report: Ambitious Structure Reorganization
+
+## Archive Summary
+
+- Change: `ambitious-structure-reorganization`
+- Archive date: 2026-06-26
+- Source artifact mode: filesystem SDD artifacts under `docs/sdd/`
+- Archived to: `docs/sdd/archive/2026-06-26-ambitious-structure-reorganization/`
+- 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 implementation tasks checked |
+| `apply-progress.md` | Present |
+| `verify-report.md` | Present |
+
+## Task Completion Gate
+
+PASS. `tasks.md` has no unchecked implementation tasks:
+
+- Phase 1 complete
+- Phase 2 complete
+- Phase 3 complete
+- Phase 4 complete
+- Phase 5 complete
+
+## Specs Synced
+
+No `openspec/` tree exists in this repository, so there are no delta specs to merge into main OpenSpec specs. The source of truth for this change is the archived filesystem SDD packet plus the updated architecture/module-boundary documentation already merged to `main`.
+
+## Source of Truth Updated
+
+The following shipped docs now reflect the new structure:
+
+- `docs/module-boundaries.md`
+- `docs/architecture.md`
+- `docs/providers.md`
+- `docs/prd.md`
+- `docs/glossary.md`
+
+## 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 on final merged cleanup commit `2e2fb85` — PASS, run `28272288089`
+
+## Remaining Follow-Up Candidates
+
+- Provider install helpers under `src/mcp/client-install-*`, `src/mcp/claude-code-*`, and `src/mcp/opencode-*` remain deferred migration candidates.
+- A future SDD can remove or stabilize compatibility facades after downstream imports are migrated.
+
+## SDD Cycle Complete
+
+The change has been proposed, specified, designed, implemented through stacked PR slices, verified, and archived. The active change folder can be removed from `docs/sdd/` in favor of the dated archive copy.

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

@@ -0,0 +1,66 @@
+# Design: Ambitious Structure Reorganization
+
+## Technical Approach
+
+Use an incremental architecture migration: introduce the target layout and compatibility rules first, then move domains through reviewable slices. The migration is structural only; existing CLI/MCP/runtime behavior remains stable.
+
+## Architecture Decisions
+
+### Decision: Layer by architectural role, not current feature folders
+
+**Choice**: Target `src/domain`, `src/application`, `src/storage`, `src/adapters`, and `src/interfaces`.
+**Alternatives considered**: Keep current top-level feature folders and only split large files.
+**Rationale**: The documented architecture already distinguishes domain, service layer, provider adapters, storage, and interfaces. Matching folders to that model improves maintainability for humans and agents.
+
+### Decision: Keep compatibility facades during migration
+
+**Choice**: Old public files such as `src/mcp/index.ts`, `src/permissions/index.ts`, and service entrypoints stay as delegating facades until consumers are migrated.
+**Alternatives considered**: Rename all imports in one PR.
+**Rationale**: Facades reduce import churn, keep PRs reviewable, and make rollback possible.
+
+### Decision: Pilot before whole-repo migration
+
+**Choice**: Start with `runs` and `mcp`, then apply the learned pattern to `cli`, `skills`, `sdd`, `agents`, `memory`, and remaining areas.
+**Alternatives considered**: Big-bang move across all areas.
+**Rationale**: `runs` and `mcp` are high-complexity and expose common pressures: service bloat, handler contracts, repositories, permissions, and tests.
+
+## Target Layout
+
+```text
+src/domain/<area>/          # schemas, contracts, invariants, pure policy
+src/application/<area>/     # use-case services and orchestration
+src/storage/<area>/         # repositories and store-specific code
+src/adapters/<provider>/    # OpenCode, Claude Code, future providers
+src/interfaces/cli/         # command parsing and human rendering
+src/interfaces/mcp/         # MCP schemas, tool handlers, stdio server
+src/interfaces/tui/         # Ink/TUI state and visual components
+```
+
+## Migration Map
+
+| Current Area | Target Area | Notes |
+|---|---|---|
+| `src/runs` | `domain/runs`, `application/runs`, `storage/runs` | First pilot; split lifecycle, approvals, checkpoints, grants |
+| `src/mcp` | `interfaces/mcp`, `application/provider-setup`, `adapters/*` | Separate MCP transport/tools from provider setup logic |
+| `src/cli` | `interfaces/cli` | Dispatch/render only; no product rules |
+| `src/skills` | `domain/skills`, `application/skills`, `storage/skills` | Split schema, registry, resolver, repository |
+| `src/sdd` | `domain/sdd`, `application/sdd` | Workflow contracts vs state service |
+| `src/agents` | `domain/agents`, `application/agents`, `adapters/*` | Neutral agent model separate from provider projection |
+| `src/memory` | `domain/memory`, `application/memory`, `storage/memory` | SQLite details under storage |
+
+## Testing Strategy
+
+| Layer | What to Test | Approach |
+|---|---|---|
+| Type contracts | Facades and moved imports | `tsc --noEmit` |
+| Unit | Extracted domain/application functions | Targeted Node tests |
+| Integration | MCP/CLI behavior remains stable | Existing `test/mcp`, `test/cli`, `test/runs` |
+| Runtime | Bun storage-backed paths | CI Bun storage suites |
+
+## Migration / Rollout
+
+No data migration required. Roll out via chained PRs: docs/facades, `runs` pilot, `mcp` pilot, CLI/interface move, domain-by-domain cleanup.
+
+## Open Questions
+
+- [ ] Confirm whether final public import paths should remain compatibility-first or move consumers entirely to the new layout before release.

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

@@ -0,0 +1,79 @@
+# Proposal: Ambitious Structure Reorganization
+
+## Intent
+
+Reorganize `vgxness` so the physical folder structure matches the product architecture: provider-neutral domain, application services, storage/repositories, provider adapters, and interfaces (`cli`, `mcp`, `tui`). The goal is maintainability: future agents and humans should know where behavior belongs, avoid duplicating rules across interfaces, and review large changes in clear architectural slices.
+
+## Scope
+
+### In Scope
+- Define the target module layout and ownership rules.
+- Rename/reorganize folders across all major areas: `mcp`, `cli`, `runs`, `sdd`, `skills`, `agents`, `memory`, `providers`, `setup`, `permissions`, `verification`, `workflows`, and `governance`.
+- Keep compatibility facades/barrels for existing imports during migration.
+- Split oversized services into cohesive domain/application/repository modules.
+- Align tests with the new boundaries and reduce brittle UI-copy assertions.
+
+### Out of Scope
+- Product behavior changes, MCP tool renames, SDD phase changes, provider install semantics, or storage schema redesign.
+- Big-bang deletion of old public import paths without a deprecation bridge.
+- New features beyond structural migration.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- None at product-contract level. This is an internal architecture and maintainability change.
+
+## Approach
+
+Adopt a layered target structure:
+
+```text
+src/domain/<area>/          # pure contracts, invariants, policy
+src/application/<area>/     # use-case services
+src/storage/<area>/         # repositories and migrations access
+src/adapters/<provider>/    # OpenCode, Claude, future providers
+src/interfaces/cli/         # CLI parsing/rendering only
+src/interfaces/mcp/         # MCP schemas/handlers/server only
+src/interfaces/tui/         # TUI rendering/state only
+```
+
+Migration should happen in reviewable phases:
+1. Add `docs/module-boundaries.md` with naming/import rules.
+2. Create compatibility facades for current public entrypoints.
+3. Move one vertical slice per PR, starting with `runs` and `mcp`, then `cli`, `skills`, `sdd`, and remaining domains.
+4. Split large files behind stable facades before renaming directories.
+5. Verify each slice with typecheck, targeted tests, and Bun CI.
+
+## Affected Areas
+
+| Area | Impact | Description |
+|---|---|---|
+| `docs/` | New | Boundary guide and migration map |
+| `src/*` | Modified | Folder renames and module extraction across all areas |
+| `src/*/index.ts` | Modified | Compatibility facades and intentional exports |
+| `test/*` | Modified | Test paths aligned to domain/interface boundaries |
+| `.github/workflows/` | Modified | CI may need path/test grouping updates |
+
+## Risks
+
+| Risk | Likelihood | Mitigation |
+|---|---:|---|
+| Huge diff becomes unreviewable | High | Use staged PRs with a migration checklist |
+| Import churn breaks consumers | Medium | Keep old barrels until migration completes |
+| Behavior changes sneak into refactor | Medium | Require no behavior changes per slice and run targeted tests |
+| Tests overfit new layout | Medium | Prefer public-contract tests over file-location tests |
+
+## Rollback Plan
+
+Each slice must be independently revertible. Because compatibility facades remain, rollback should restore moved modules without changing public behavior. If a slice destabilizes CI, revert that slice and keep only documentation/checklist updates.
+
+## Success Criteria
+
+- [ ] Target structure and ownership rules are documented.
+- [ ] All major areas have an assigned target location.
+- [ ] Existing public imports continue working during migration.
+- [ ] At least one high-complexity pilot area is reorganized successfully.
+- [ ] Typecheck, targeted tests, and CI pass after each slice.

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

@@ -0,0 +1,67 @@
+# Spec: Ambitious Structure Reorganization
+
+## Requirements
+
+### Requirement: Layered Module Boundary Map
+
+The system MUST define a target source layout that separates domain contracts, application services, storage, provider adapters, and user-facing interfaces.
+
+#### Scenario: Target layout is documented
+
+- GIVEN a maintainer needs to add or move code
+- WHEN they read the SDD artifacts or module-boundary docs
+- THEN they can identify the correct target layer for domain, service, storage, adapter, CLI, MCP, and TUI code
+
+#### Scenario: All major areas are mapped
+
+- GIVEN existing areas such as `mcp`, `cli`, `runs`, `sdd`, `skills`, `agents`, and `memory`
+- WHEN migration planning is reviewed
+- THEN every area has a target owner layer and target folder
+
+### Requirement: Compatibility During Migration
+
+The system MUST preserve existing public import paths through facades or barrels until each migration slice explicitly removes a deprecated path.
+
+#### Scenario: Existing consumers keep compiling
+
+- GIVEN a module is moved to a new folder
+- WHEN typecheck runs during the migration slice
+- THEN imports through existing public entrypoints still compile
+
+#### Scenario: Deprecated paths are intentional
+
+- GIVEN an old barrel remains after migration
+- WHEN maintainers inspect the facade
+- THEN it clearly delegates to the new module location and does not contain duplicated business logic
+
+### Requirement: Behavior Preservation
+
+The reorganization MUST NOT change product behavior, MCP tool names, SDD phase semantics, provider install semantics, or storage schema behavior unless a later SDD explicitly proposes that change.
+
+#### Scenario: Refactor slice preserves behavior
+
+- GIVEN a structural slice is implemented
+- WHEN targeted tests and CI run
+- THEN observable behavior remains equivalent to the pre-refactor baseline
+
+#### Scenario: Behavior change is discovered
+
+- GIVEN a structural slice requires a behavior change
+- WHEN the change is identified
+- THEN that behavior change is split into a separate SDD or explicitly rejected from the slice
+
+### Requirement: Reviewable Migration Slices
+
+The migration MUST be planned as ordered, reviewable slices rather than one unbounded rewrite.
+
+#### Scenario: High-risk migration is split
+
+- GIVEN the total reorganization spans most of `src/`
+- WHEN tasks are created
+- THEN the work is divided into chained PR-sized units with clear verification per unit
+
+#### Scenario: Pilot validates the pattern
+
+- GIVEN the new structure is proposed
+- WHEN implementation starts
+- THEN one high-complexity area such as `runs` or `mcp` is migrated first before applying the pattern everywhere