vgxness 1.5.1 → 1.5.2

package/docs/mcp.md

@@ -0,0 +1,144 @@
+# MCP tools
+
+VGXNESS exposes 38 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
+
+Tools are exposed under the `vgxness_*` prefix. Some MCP hosts strip the prefix and accept the short form (`sdd_status`, `memory_save`, etc.). The schema accepts both.
+
+All tools:
+
+- Are read-only or auditable on the VGXNESS side. The only state-mutating tools are the ones explicitly named `*_save`, `*_update`, `*_start`, `*_checkpoint`, `*_finalize`, `*_accept_artifact`, `*_set`, `*_append_activity`, `*_close`, `*_record_*`.
+- Validate input with `zod` before dispatching to the service layer.
+- Return either a typed result or a `VgxMcpError` with a `code` and `message`.
+- Do not require the agent to import or instantiate anything; pass JSON, get JSON.
+
+## SDD workflow (10)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_sdd_status` | Report per-phase artifact presence and the next ready missing phase. | `project`, `change` | |
+| `vgxness_sdd_next` | Recommend the next phase decision for a change. | `project`, `change` | |
+| `vgxness_sdd_ready` | Check whether a specific phase is ready. | `project`, `change`, `phase`; optional `runId`, `agentId` | Returns structured `SddReadiness` with `blockedPrerequisites`. |
+| `vgxness_sdd_get_readiness` | Same as `ready` with explicit output shape. | same as `ready` | |
+| `vgxness_sdd_save_artifact` | Persist phase content under canonical topic key `sdd/{change}/{phase}`. | `project`, `change`, `phase`, `content` | Saving does not imply acceptance. |
+| `vgxness_sdd_accept_artifact` | Record explicit human acceptance for a phase. | `project`, `change`, `phase`, `acceptedBy` (`{type:"human", id, displayName?}`); optional `acceptedAt`, `note`, `notes`, `rationale`, `runId`, `agentId` | `acceptedBy.type` must be `"human"`. Runtime rejects agent or anonymous acceptance. |
+| `vgxness_sdd_get_artifact` | Read one full artifact. | `project`, `change`, `phase`; optional `payloadMode` (`compact`/`verbose`) | |
+| `vgxness_sdd_list_artifacts` | List all artifacts for a change in canonical phase order. | `project`, `change`; optional `payloadMode` | |
+| `vgxness_sdd_cockpit` | Aggregate per-phase status, blockers, and recommended next action. | `project`, `change` | Returns `SddCockpit` with `aggregateBlockers` of kinds `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. |
+| `vgxness_governance_report` | Build a redacted governance report for a project/change/run. | `project`; optional `change`, `runId`, `workflow`, `phase`, `agentId`, `agent` (with `id`, `name`, `mode`, `scope`), `payloadMode` | See [Safety model](./safety.md) for redaction rules. |
+
+## Memory (4)
+
+| Tool | Purpose | Required inputs |
+|---|---|---|
+| `vgxness_memory_save` | Upsert memory observation. | `project`, `type` (`architecture`/`decision`/`bugfix`/`pattern`/`config`/`discovery`/`learning`/`preference`/`manual`), `title`, `content`; optional `scope` (`project`/`personal`), `topicKey` |
+| `vgxness_memory_search` | FTS5 search over memory. | `limit` (1–100); optional `project`, `scope`, `type`, `topicKey`, `query` |
+| `vgxness_memory_get` | Read one observation by id. | `id` |
+| `vgxness_memory_update` | Patch an existing observation. | `id`; optional `type`, `title`, `content`, `topicKey` |
+
+`topicKey` is the durable upsert key: re-saving with the same key updates the existing observation rather than creating a duplicate.
+
+## Sessions (5)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_session_start` | Begin a session record. | `project`; optional `id`, `directory` | If `id` is omitted, the runtime generates one. |
+| `vgxness_session_append_activity` | Append a structured event to a session. | `sessionId`, `actor`, `kind` (`prompt`/`tool_call`/`artifact`/`summary`/`error`), `payloadJson` | `payloadJson` is a stringified JSON value, validated before append. |
+| `vgxness_session_close` | Close a session with a summary. | `sessionId`, `actor`, `summary` (non-empty, trimmed) | |
+| `vgxness_session_restore` | Read the latest restorable session for a project/directory. | `project`; optional `directory` | One signal — not authoritative. Prefer `vgxness_context_cockpit`. |
+| `vgxness_context_cockpit` | Read-only cockpit: recent sessions, bounded memory previews, last restorable session. | `project`; optional `directory`, `limit` | Does not trace, mutate state, run preflight, or write provider config. |
+
+## Agents, profile, skills (5)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_agent_resolve` | Rank registered agents/subagents for a task. | `project`, `scope?`, `taskDescription` or `intent`; optional `desiredCapabilities`, `workflow`, `phase`, `providerAdapter`, `mode` (`agent`/`subagent`) | Deterministic rule-based ranking. No model call. |
+| `vgxness_agent_activate` | Build an activation envelope for the resolved agent. | `project`, `agentId` or `name`; optional `scope`, `workflow`, `phase`, `providerAdapter`, `mode`, `workspaceRoot`, `maxSourceBytes`, `payloadMode` | Default `payloadMode` is `compact`. |
+| `vgxness_manager_profile_get` | Read the manager profile overlay. | `project`; optional `scope`, `managerName` | |
+| `vgxness_manager_profile_set` | Upsert a manager profile overlay. | input shape from `SaveManagerProfileOverlayInput` | Requires explicit human authorization in the harness prompt. |
+| `vgxness_skill_payload` | Resolve and build a provider-agnostic skill injection payload. | `agentId`/`name`+`project`+`scope`, `workflow`, `phase`, `providerAdapter`; `workspaceRoot`; optional `maxSourceBytes`, `mode` | `mode` defaults to `compact`. See [Code runtime](./code-runtime.md) for how the runtime consumes this. |
+
+## OpenCode preview (2)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_opencode_manager_payload` | Build the OpenCode manager payload envelope. | `OpenCodeManagerPayloadInput` shape (project, scope, agent, workflow/phase, workspaceRoot, maxSourceBytes, payloadMode) | `installable: false`, `readOnly: true`. |
+| `vgxness_opencode_handoff_preview` | Compose a full handoff preview: provider artifacts + skill diagnostics + SDD status + provider status + safety flags. | `project`; optional `scope`, `agentId`, `agentName`, `workspaceRoot`, `maxSourceBytes`, `change`, `phase` | Read-only preview. Does not execute OpenCode, install hooks, or write provider config. |
+
+## Runs (8)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_run_list` | List runs with filters. | `limit`; optional `project`, `status` (one of the 8 `RunStatus` values) | |
+| `vgxness_run_get` | Read a run with `events`, `checkpoints`, `approvals`, `operationAttempts`. | `id` | |
+| `vgxness_run_start` | Create a run record. | `CreateRunInput` shape | |
+| `vgxness_run_checkpoint` | Append a resumable JSON state. | `AppendRunCheckpointInput` shape | |
+| `vgxness_run_finalize` | Finalize a run with `outcome` and `outcomeReason`. | `FinalizeRunInput` shape | `outcome` must match a terminal `status`. Re-finalization is rejected. |
+| `vgxness_run_preflight` | Run policy evaluation and return the decision + planned execution isolation strategy. | `PreflightRunOperationInput` shape | May create a pending approval when the decision is `ask`. Does not invoke an executor. |
+| `vgxness_run_resume_inspect` | Plan-only resume advisory. | `runId` | Returns `RunResumeOrchestrationPlan` with blockers and `nextAction` (`resolve-approval`/`inspect-run`/`retry-check`/`manual-recovery`/`no-action`). |
+| `vgxness_run_resume_gate` | Evaluate retry policy for an approval without executing. | `approvalId`; optional `policy` | Default policy is `never`. See [Safety model](./safety.md) for the policy table. |
+
+Run `status` accepts the full 8-state vocabulary: `created`, `planned`, `running`, `needs-human`, `completed`, `failed`, `blocked`, `cancelled`. `outcome` is one of `success`, `partial`, `failure`, `blocked`, `cancelled`.
+
+## Providers (3)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_provider_status` | Report provider health for a project/scope. | `ProviderHealthInput` shape (project, scope, workspaceRoot, providerAdapter) | Read-only. |
+| `vgxness_provider_doctor` | Run provider health checks with structured JSON output. | same as `status` | |
+| `vgxness_provider_change_plan` | Compose a read-only provider config change plan. | `ProviderChangePlanInput` shape (`provider`: `opencode`/`claude`/`antigravity`/`custom`; `changeType`: `opencode-mcp-install`/`setup`/`install`/`config-preparation`; `workspaceRoot`; `payloadMode`) | Does not write provider config. See [Providers](./providers.md). |
+
+## Verification (1)
+
+| Tool | Purpose | Required inputs |
+|---|---|---|
+| `vgxness_verification_plan` | Recommend a verification plan for a change type. | `changeType` (`docs-only`/`test-only`/`cli`/`mcp`/`sdd-storage`/`provider-setup`/`package-release`/`workflow-runs`) |
+
+## Usage patterns
+
+Starting, resuming, and ending a session:
+
+```text
+vgxness_session_start           { project: "vgxness", directory: "/path" }
+vgxness_session_append_activity { sessionId, actor, kind, payloadJson }
+vgxness_session_close           { sessionId, actor, summary }
+```
+
+Inspecting SDD before doing any work:
+
+```text
+vgxness_sdd_cockpit    { project: "vgxness", change: "new-flow" }
+vgxness_sdd_get_readiness { project: "vgxness", change: "new-flow", phase: "proposal" }
+```
+
+The cockpit returns `aggregateBlockers`; if any are `unaccepted-phase`, the agent should not run the next phase until a human accepts the prerequisite.
+
+Recording a phase with explicit human acceptance:
+
+```text
+vgxness_sdd_save_artifact    { project, change, phase: "proposal", content: "..." }
+# human opens the harness and runs:
+vgxness_sdd_accept_artifact  { project, change, phase: "proposal", acceptedBy: { type: "human", id: "uziel" }, rationale: "Reviewed proposal." }
+```
+
+Running a planned operation:
+
+```text
+vgxness_run_start       { project, userIntent, workflow: "sdd", phase: "apply-progress", selectedAgentId, providerAdapter, model }
+vgxness_run_preflight   { runId, category: "edit", operation: "apply_patch", workspaceRoot, targetPath, payload }
+# if decision is "ask", wait for human approval; on approval, the harness resumes via run_resume_inspect + run_resume_gate.
+vgxness_run_checkpoint  { runId, label: "after-step-1", state: {...} }
+vgxness_run_finalize    { runId, outcome: "success", outcomeReason: "..." }
+```
+
+## Safety boundary
+
+MCP tools do not:
+
+- Write provider config (`.opencode/`, `.claude/`, `opencode.json`, `CLAUDE.md`).
+- Execute providers (`opencode`, `claude`, etc.).
+- Install global memory.
+- Create `openspec/`.
+- Bypass permission policy.
+- Mutate other tools' state outside the VGXNESS SQLite store.
+
+Tools that would normally mutate external state (provider install, shell, network) are split into a plan/preview step and an explicit `apply` step. The apply step requires an MCP-side `apply` flag or a separate `vgxness` CLI command (e.g. `vgxness setup apply --yes`).

package/docs/prd.md

@@ -128,18 +128,7 @@ Minimum MCP capabilities:
 
 Candidate MCP tools:
 
-```text
-vgxness_sdd_status
-vgxness_sdd_next
-vgxness_sdd_ready
-vgxness_sdd_save_artifact
-vgxness_run_start
-vgxness_run_checkpoint
-vgxness_run_request_approval
-vgxness_agent_resolve
-vgxness_skill_payload
-vgxness_profile_get
-```
+The current MCP surface covers SDD status and artifacts, memory read/write, sessions, agent resolution and activation, skill payload, OpenCode manager payload, run lifecycle (start, list, get, preflight, checkpoint, finalize, resume inspect, resume gate), provider status/doctor/change-plan, verification plan, governance report, and context cockpit. The full, current list lives in [MCP tools](./mcp.md) and in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth.
 
 #### CLI
 
@@ -213,8 +202,8 @@ The same flow must be available through CLI flags for automation and CI-friendly
 
 Initial integration targets:
 
-- OpenCode
-- Claude Code
+- OpenCode — primary supported provider. The configurator plane renders OpenCode MCP config and manager/SDD agent definitions; the code runtime speaks to any OpenAI-compatible endpoint, including OpenCode's local bridge.
+- Claude Code — preview/manual only as of v1.5.1. The canonical agent manifest declares Claude support as `preview` with an explicit reason: VGXNESS does not install Claude or write `.claude/` or `CLAUDE.md`. Owners of Claude-only workflows must run setup themselves.
 
 Pi/`gentle-pi` is a design reference and future adapter target, not part of the first integration target list unless the MVP scope is explicitly expanded.
 
@@ -358,15 +347,23 @@ The MVP is successful when an advanced individual developer can:
 
 ## Open questions
 
-- What is the first integration adapter: OpenCode or Claude Code?
-- Should memory storage be per-repo by default, with global memory in a user-level directory?
-- What config format should define agents/subagents?
-- What config format should define skills and skill versions?
-- Which skill improvement proposals should require approval versus automatic rejection?
-- Which commands form the first public CLI surface?
-- Which TUI framework should be used for the first implementation?
-- Should the MCP server run only over stdio for MVP, or also support local HTTP later?
-- What is the safest default install command and update channel?
-- What privacy/export guarantees are required before public release?
-- What is the first sandbox strategy: normal workspace, git worktree, or process/container isolation?
-- What trace format should be used for local inspection and future cloud sync?
+Many of the early PRD questions are resolved in v1.5.1. Tracking them here keeps the historical record.
+
+| Question | Resolved as of v1.5.1 |
+|---|---|
+| First integration adapter | OpenCode primary; Claude is preview/manual. |
+| Memory storage scopes | Project memory and personal/global memory live in separate SQLite stores; `--db` flag and `VGXNESS_DB_PATH` env var override. |
+| Agent config format | Provider-neutral schema in `src/agents/schema.ts`; canonical manifest with validation in `src/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, code, opencode}`. See [CLI reference](./cli.md). |
+| First TUI framework | OpenTUI (`@opentui/core`) for the main menu and setup screens; legacy tui-kit screens still in tree for backwards compatibility. |
+| MCP transport | Local stdio for MVP; HTTP deferred. |
+| Default install command | `npm install -g vgxness` ships both `vgxness` and `vgx` bins; Bun 1.3.14+ is the canonical installed runtime. |
+| Sandbox strategy | Planning-only in v1.5.1 (`src/runs/sandbox-worktree-planning.ts`); real sandbox/worktree execution is follow-up. Approval-gated edits/shell happen through the code runtime's executors. |
+
+Still open:
+
+- Privacy/export guarantees required before public release (depends on release scope).
+- Distributed multi-worker execution model (post-MVP).
+- Web/hosted console surface (post-MVP).

package/docs/providers.md

@@ -0,0 +1,123 @@
+# Providers
+
+VGXNESS is provider-agnostic at the core: the registry stores provider-neutral definitions and adapters translate them into provider-specific config and runtime behavior. This document covers the two adapter layers: the **control-plane adapter** (OpenCode renderer today, with a Claude preview renderer in the tree) and the **code-runtime provider adapter** (OpenAI-compatible + fake).
+
+## Status (v1.5.1)
+
+| Provider | Control plane | Code runtime | Notes |
+|---|---|---|---|
+| OpenCode | `managed` | n/a (target) | Primary supported provider. The configurator renders OpenCode MCP config and manager/SDD agent definitions into the chosen scope. |
+| Claude Code | `preview/manual` | n/a | The canonical agent manifest declares Claude support as `preview` with an explicit reason: VGXNESS does not install Claude or write `.claude/` or `CLAUDE.md`. Owners of Claude-only workflows must run setup themselves. |
+| Antigravity | `placeholder` | n/a | Listed in the TUI Installation surface as coming-soon. |
+| Custom / future | `extension` | extension point | Per the [Architecture](./architecture.md) decision, anything not OpenCode or Claude is a custom extension. |
+| OpenAI-compatible | n/a | `openai-compatible-provider-adapter.ts` | Real adapter used by `vgxness code`. Speaks to any OpenAI-compatible endpoint. |
+| Fake | n/a | `fake-provider-adapter.ts` | Deterministic, offline; for unit tests and CI. |
+
+## Control-plane adapter contract
+
+The control-plane adapter takes a root agent plus optional registered subagents and returns previewable artifacts. It does not mutate the registry, write provider config, or call providers.
+
+| Type | Purpose |
+|---|---|
+| `ProviderRenderer` | Named renderer for one output format/provider. |
+| `ProviderRenderInput` | A root agent plus optional registered subagents. |
+| `ProviderRenderResult` | Generated artifacts, provider name, `installable: false`, warnings. |
+| `ProviderRenderArtifact` | Relative path, content type, and generated contents. |
+
+### OpenCode renderer
+
+`src/agents/renderers/opencode-renderer.ts` renders a single OpenCode config preview with `$schema` and an `agent` object. Top-level agents default to `primary`; subagents render as `subagent`. Agent keys are sanitized deterministically from registry names, and rendering rejects key collisions instead of overwriting generated config.
+
+```bash
+vgxness agents render --provider opencode --project vgxness --name apply-agent
+```
+
+The output is previewable JSON; the renderer does not write to `.opencode/`, `.claude/`, or any user/global provider config.
+
+### JSON renderer
+
+`src/agents/renderers/json-renderer.ts` produces a debug/export shape. It includes the matching `adapters.json` as `selectedAdapter` so downstream consumers can replay the same rendering deterministically.
+
+```bash
+vgxness agents render --provider json --project vgxness --name apply-agent
+```
+
+### Claude renderer (preview)
+
+`src/agents/renderers/claude-renderer.ts` exists in the tree as a preview renderer. The shape of an install-safe Claude artifact is not yet finalized, so the renderer is not enabled for end-to-end install flows.
+
+### OpenCode injection preview
+
+`OpenCodeInjectionPreviewService` (in `src/providers/opencode/`) composes existing read-only outputs into a single envelope:
+
+| Output | Source |
+|---|---|
+| `providerArtifacts` | OpenCode renderer for the selected agent and registered subagents. |
+| `skillPayload` | Skill registry payload builder for the selected SDD phase and OpenCode adapter. |
+| `sdd` | SDD workflow status and readiness for the selected project/change/phase. |
+| `context` and `safety` | OpenCode preview layer metadata for future OpenCode/MCP/hook callers. |
+
+The envelope is always `installable: false` and `readOnly: true`. It does not execute OpenCode, install hooks, create MCP servers, create runs, record skill usage, or touch provider/user/global config. Future live injection should build on this contract only after a separate approved change defines execution, hook, or MCP safety rules.
+
+```bash
+vgxness opencode preview --provider opencode --agent apply-agent --project vgxness --change checkout-flow --phase apply-progress
+```
+
+## Code-runtime provider adapter
+
+The code runtime speaks to a model through `CodeProviderAdapter` (`src/code/providers/provider-adapter.ts`):
+
+```ts
+export interface CodeProviderAdapter {
+  readonly id: string;
+  readonly displayName: string;
+  readonly capabilities: ProviderCapabilities;
+  createResponse(request: ProviderRequest): Promise<ProviderResponse>;
+  streamResponse?(request: ProviderRequest): AsyncIterable<ProviderStreamEvent>;
+  countTokens?(input: ProviderTokenInput): Promise<TokenUsageEstimate>;
+  diagnostics?(model: string): Promise<ProviderDiagnostics>;
+}
+```
+
+Errors are surfaced through `CodeProviderError` with a `code` of `missing_credentials`, `blocked_credentials`, `provider_error`, or `retryable_provider_error`. The `retryable` flag tells callers whether a transient retry is meaningful.
+
+### `openai-compatible-provider-adapter.ts`
+
+The real adapter. Speaks to any OpenAI-compatible endpoint; credentials come from environment references, never embedded in prompts or reports. The adapter streams responses through `stream-normalizer.ts` and maps messages with `message-mapper.ts`.
+
+### `fake-provider-adapter.ts`
+
+Deterministic, offline. Used by `test/code/` and `bun run smoke:opentui-code` to keep CI hermetic. The fake adapter is intentionally thin — it does not model provider quirks, only the contract.
+
+### Adding a new code-runtime provider
+
+1. Implement `CodeProviderAdapter` and a `CodeProviderError`-throwing path. The interface is small; most of the work is in the request/response shape and the stream normalizer.
+2. Add credentials handling in `src/code/providers/credentials.ts`. Do not embed secrets; accept environment references only.
+3. Add a smoke test under `test/code/providers.test.ts` that exercises `createResponse`, `streamResponse`, and `countTokens` (where applicable).
+4. If the new provider has a different default tool shape, add a normalizer. If the stream events are different, extend `stream-normalizer.ts`.
+5. Update [Code runtime](./code-runtime.md) and this document with the new adapter id and capabilities.
+
+## 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:
+
+- `vgxness mcp install opencode --plan` — read-only plan; never writes config.
+- `vgxness mcp install opencode --yes` — explicit write path; creates a backup first.
+- `vgxness mcp doctor opencode` — JSON report of provider health.
+- `vgxness provider status` / `vgxness provider doctor` (planned CLI) — same shape through the operator surface.
+- `vgxness setup rollback --backup <path>` — restores a previous OpenCode config byte-for-byte after validation.
+
+Writes happen only through `apply` with explicit consent. Plans, status, doctor, change-plan, and previews are read-only by contract.
+
+## Safety boundary
+
+Adapters and renderers must not:
+
+- Write provider config (`.opencode/`, `.claude/`, `opencode.json`, `CLAUDE.md`).
+- Call providers (`opencode`, `claude`, etc.) during preview or status.
+- Install global memory.
+- Create `openspec/`.
+- Bypass permission policy.
+- Mutate other tools' state outside the VGXNESS SQLite store.
+
+Adapter code is reviewed against the safety boundary tests in `test/mcp/` and `test/agents/provider-renderer.test.ts` before merge.

package/docs/roadmap.md

@@ -0,0 +1,88 @@
+# Roadmap
+
+This document tracks planned work that is not yet shipped. The [Architecture](./architecture.md) document describes what is built; this is what is next. Items are grouped by area and ordered roughly by impact and dependency.
+
+## Runtime execution
+
+The lifecycle, policy recording, approval records, and retry policy are all in place. What is still test-only is the actual executor that turns a reserved attempt into a real-world side effect.
+
+- **Real provider/tool executor.** The current `RunService.executeOperation(...)` takes an injected `RunOperationExecutor`; production code still uses fake/deterministic executors in tests. The plan is to ship a sandboxed executor that respects the `ExecutionIsolationPlan` (`workspace`/`git-worktree`/`process-sandbox`) and the SDD phase permission matrix.
+- **CLI/MCP orchestration for `resume-after-approval`.** Once the executor is real, the `vgxness_run_resume_inspect` and `vgxness_run_resume_gate` tools need an `apply` partner that calls the executor only after a human resolves the pending approval.
+- **Sandbox/worktree execution strategies.** `src/runs/sandbox-worktree-planning.ts` produces a plan; the plan needs to materialize into a real worktree or sandbox. Symlink and realpath hardening is already in the policy evaluator; the next step is wiring it to a runner.
+- **Richer verification evidence summaries.** Verification currently records `pass`/`fail`/`skipped`; the next step is to summarize per-task verification into the run, task list, and SDD cockpit so blocked phases have concrete evidence.
+
+## Code runtime
+
+The four modes (`inspect`/`plan`/`craft-preview`/`craft`) and the 19 tools are in. What is left is provider coverage, ergonomics, and the OpenTUI shell promotion.
+
+- **Native Anthropic provider.** The code runtime speaks to any OpenAI-compatible endpoint. A native Anthropic adapter would remove the need to route Claude through an OpenAI-compatible bridge.
+- **More providers.** The adapter contract is small and provider-neutral; additional adapters (Anthropic, Google, local model servers) can be added incrementally.
+- **`vgxcode` OpenTUI shell promotion.** The shell is currently root-owned during development. To promote it, we need: deterministic event contracts, snapshot tests, and a packaging path that does not require `bun src/cli/tui/opentui/code/index.ts`.
+- **Workspace-executor for the `craft` mode.** Workspace mutations (`apply_patch`, `create_file`, `update_file`, `delete_file`) currently use the `WorkspaceToolExecutor` with policy gating. The next step is a real file-system backend with rollback on failure.
+- **Repair loop.** The `--verification repair` option exists in the CLI but is not wired to a loop in the runtime.
+
+## SDD governance
+
+The hard acceptance gate and the cockpit blockers are in. The remaining work is mostly UX and stronger cross-linking.
+
+- **Verification evidence linked to the cockpit.** The cockpit currently returns blockers; surfacing the per-phase verification evidence (pass/fail/skipped counts, last-run timestamps) would make "why is this blocked" answers more useful.
+- **Per-phase model/profile routing in the cockpit.** The manager profile overlay exists. The cockpit should recommend a model for the next phase based on the active overlay.
+- **Migration of `openspec/`-style workflows.** Some users bring artifacts from other tools. A formal `import` path through the artifact portability service would help, but it should not silently convert external artifacts into accepted SDD phases.
+
+## Skills and agents
+
+The registries, version model, payloads, and improvement-proposal lifecycle are in.
+
+- **Skill evaluation harness.** `013_skill_evaluation_scenarios.sql` is the storage; the runtime that runs scenarios against a proposed skill version is not yet built.
+- **Skill improvement suggestion agent.** Skill proposals today are user-driven. A trace-driven candidate detector is planned but explicitly out of scope per the "no silent skill mutation" rule.
+- **Canonical manifest v7.** v6 is in the tree (WIP commit). v7 would address the uncommitted `canonical-agent-manifest.ts` and `canonical-agent-projection.ts` work and ship a stable, validated manifest as the source of truth.
+
+## Storage and portability
+
+SQLite, scopes, migrations, and the run snapshot export are in.
+
+- **`import` path for SDD artifacts.** The `ArtifactPortabilityService` exports; an import path that re-creates acceptance records with explicit human re-acceptance is planned.
+- **Sensitive-data redaction during export.** `src/export/redaction.ts` exists. Wiring it as a default into the export path and a CLI flag (`--redact`) is the next step.
+- **Database upgrade tooling.** Forward-only migrations work; downgrade requires a snapshot. A small CLI helper for "is my DB on the latest migration?" would be useful for support.
+
+## TUI
+
+The main menu and setup screens are in via OpenTUI. The dashboard directory is empty in the current tree.
+
+- **TUI dashboard screen.** Real-time view of active runs, pending approvals, and SDD blockers. Should match the cockpit surface from MCP.
+- **TUI runs screen.** Run list, drill into a run, see events/approvals/attempts, with read-only safe actions.
+- **TUI approvals screen.** Resolve pending approvals directly from the TUI, with the same audit trail as `vgxness_sdd_accept_artifact`.
+
+## Observability and evaluation
+
+95 test files cover the eval targets in v1.5.1.
+
+- **Eval gate.** A `vgxness verify --evals` runner that orchestrates a quality gate beyond `bun run verify`. The architecture document lists 11 eval targets; lifting them into a single runner would close the loop.
+- **Token/cost tracking.** A nice-to-have that the trace model already supports structurally (`ProviderTokenInput`).
+- **Timeline export.** `RunSnapshotPackageV1` exists. A `runs timeline <id> --format html|md|json` CLI would make sharing easier.
+
+## Provider coverage
+
+- **Claude Code install path.** Preview/manual only today. The renderer exists; an install-safe Claude artifact shape is the blocker.
+- **Antigravity and other custom adapters.** Listed as placeholders; a real adapter would unblock those workflows.
+- **Provider doctor upgrades.** Doctor checks could surface real config drift, not just existence of expected files.
+
+## Out of scope (still)
+
+These remain future expansion areas per the [PRD](./prd.md):
+
+- Cloud sync across machines.
+- Team/shared memory spaces.
+- Hosted web console.
+- Distributed agent workers.
+- Hosted observability and evaluation UI.
+- Skill marketplace or shared skill catalog.
+
+## How work gets into this list
+
+When the architecture drifts from the code, or when a real product gap is identified, the right path is:
+
+1. Open an SDD change with `vgxness sdd status --project <project> --change <id>` (or a fresh change id).
+2. Move the item from here to an `explore` artifact.
+3. Walk the SDD phases: `explore → proposal → spec → design → tasks → apply-progress → verify → archive`.
+4. Once shipped, retire the item from this roadmap and update [Architecture](./architecture.md) and the [CHANGELOG](../../CHANGELOG.md) to reflect the new state.

package/docs/safety.md

@@ -0,0 +1,147 @@
+# Safety model
+
+VGXNESS treats safety as a core domain, not as adapter-specific behavior. This document describes the three layers that make up the safety model: the **policy evaluator** for the control plane, the **per-SDD-phase permission matrix**, and the **code runtime approval flow** with redactors.
+
+If a tool, surface, or new provider wants to take an action, the action must:
+
+1. Be classified into a permission category.
+2. Resolve through the policy evaluator or the per-SDD-phase matrix.
+3. If the decision is `ask`, surface an approval prompt through the configured approval channel.
+4. Record the decision in the run event stream regardless of outcome.
+
+## Permission categories
+
+The category list lives in `src/permissions/schema.ts` (`permissionCategories`). The default policy (`defaultPermissionPolicy` in `src/permissions/policy-evaluator.ts`) defines the baseline decision for each.
+
+| Category | Default | Risky | Notes |
+|---|---|---|---|
+| `read` | `allow` | no | Files, memory, artifacts. Allowed only when path stays inside `workspaceRoot`. |
+| `edit` | `ask` | yes | Write/patch/modify files. |
+| `implementation-edit` | `ask` | yes | Edits tied to a SDD `apply-progress` phase. |
+| `spec-write` | `ask` | yes | Writes to a spec artifact. |
+| `design-write` | `ask` | yes | Writes to a design artifact. |
+| `task-write` | `ask` | yes | Writes to a task artifact. |
+| `shell` | `ask` | yes | Commands, scripts, package managers. |
+| `test-run` | `ask` | yes | Test execution. |
+| `install` | `ask` | yes | Dependency installation mutates local state. |
+| `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. |
+| `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. |
+
+The risky categories (`isRiskyPermissionCategory`) get a forced `ask` even when an agent override would otherwise allow the category.
+
+## Decisions
+
+Every permission request resolves to one of three decisions:
+
+- `allow` — execute and record `succeeded` or `failed`.
+- `ask` — create a pending approval record, record `pending-approval`, and pause until the approval is resolved.
+- `deny` — record `blocked` and do not invoke the executor.
+
+In addition, the SDD-phase permission matrix uses four `PermissionMode` values:
+
+- `allow` — pass through.
+- `audit` — log and pass through.
+- `require-preflight` — must run preflight and receive an `allow` decision before the operation executes.
+- `deny` — block.
+
+## Per-SDD-phase permission matrix
+
+The matrix (`sddPhasePermissionMatrix`, version `sdd-phase-permissions-v1`) gives every (phase, category) pair a mode. The matrix version is exported as a constant so consumers can compare.
+
+| 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`. |
+| `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`. |
+
+Workspace reads are allowed only when the target path stays inside `workspaceRoot`. The evaluator resolves the real path with `realpathSync` to defeat symlink escapes and refuses to relax workspace boundary denials through agent overrides.
+
+## Code runtime approval flow
+
+The code runtime layers a second, finer-grained decision on top of the policy evaluator. Per-tool definitions declare whether a tool is `read`, `confirm`, or `restricted` (see [Code runtime](./code-runtime.md)). The approval coordinator (`src/code/runtime/approval-coordinator.ts`) wires that to a broker and a gateway.
+
+```text
+tool call
+   │
+   ▼
+PolicyApprovalBroker  ──►  ConservativePermissionGateway.evaluate(tool, mode, context)
+   │                              │
+   │                              ├── allow  → execute, emit CodeRuntimeEvent(succeeded)
+   │                              ├── ask    → ApprovalPrompt
+   │                              │            ├── stdio channel: read line from stdin
+   │                              │            └── auto channel:   injected broker (e.g. MCP client)
+   │                              └── deny   → emit CodeRuntimeEvent(blocked), return error
+   ▼
+CodeRuntimeEventSink  (stream JSONL to consumer; OpenTUI shell, scripts, tests)
+```
+
+The gateway is conservative by default: a non-`read` tool in a non-`apply-progress` phase defaults to `ask`. Even with `--approval-policy allow`, the gateway can re-promote to `ask` for risky categories or workspace boundary issues.
+
+## Redaction
+
+`src/code/reporting/redaction.ts` ships three helpers used by every consumer that emits prompts, reports, checkpoints, transcripts, or memory saves.
+
+| Helper | What it does |
+|---|---|
+| `redactSecrets(value: string): string` | Replaces secret-shaped substrings with `[REDACTED]`. Patterns include `*TOKEN=...`, `*SECRET=...`, `*KEY=...`, `*PASSWORD=...`, `sk_*`/`pk_*` keys, `Bearer ...` headers, and PEM private keys. |
+| `redactJson(value: JsonValue): JsonValue` | Recursively walks JSON, redacts string values, and replaces values whose key matches `(token\|secret\|password\|api.?key\|authorization\|credential)` with the literal `"[REDACTED]"`. |
+| `omitSensitiveCommandOutput<T extends JsonValue>(value: T): JsonValue` | For tool results that include `stdout`/`stderr`, replaces those fields with `"[omitted by default]"` unless the consumer explicitly opts in. |
+
+These helpers are deterministic and are the only place secret-shaped values should be stripped. Tool results that include shell output must use `omitSensitiveCommandOutput` before they are recorded into the run event stream or rendered into a checkpoint.
+
+## Approval lifecycle
+
+Approvals are first-class records linked to a permission-decision event:
+
+```text
+executeOperation(...)
+   │
+   ▼
+evaluate permission
+   │
+   ├── allow  → no approval record, executor runs
+   ├── deny   → no approval record, executor blocked
+   └── ask    → pending approval record + reserved operation attempt
+                    │
+                    ▼
+              human resolves approval (approved | rejected | cancelled)
+                    │
+                    ▼
+              resumeApprovedOperation({ approvalId, executor })
+                    │
+                    ▼
+              reserved attempt → succeeded | failed | abandoned
+```
+
+Retry policy evaluation is separate from execution. `vgxness_run_resume_gate` evaluates the policy and returns an `OperationRetryDecision` (`allowed`/`reasonCode`/`reason`/attempt metadata). The default policy is `never`, so any prior `reserved`/`succeeded`/`failed`/`abandoned` attempt blocks later resume before the executor is invoked.
+
+| Policy | Allows a new attempt after | Always blocks |
+|---|---|---|
+| `never` | No previous attempt only | `reserved`, `succeeded`, `failed`, `abandoned` |
+| `after-abandoned` | latest attempt is `abandoned` | active `reserved`, `succeeded`, `failed` |
+| `after-failure` | latest attempt is `failed` | active `reserved`, `succeeded`, `abandoned` |
+| `after-failure-or-abandoned` | latest attempt is `failed` or `abandoned` | active `reserved`, `succeeded` |
+
+`RunService.abandonReservedOperationAttempt({ attemptId, actor, reason })` is recovery-only: it transitions a stuck attempt to `abandoned` and appends an `operation-execution` audit event. It does not call an executor or retry.
+
+## Safety boundaries (enforced everywhere)
+
+- Read-only/preview commands must stay non-mutating: setup plans, MCP setup previews, OpenCode previews, workflow previews, status views, and the natural-language orchestrator preview never write provider config, call providers, or install global memory.
+- Provider config writes (`opencode.json`, `.opencode/`, `.claude/`, `CLAUDE.md`) require explicit consent (`--yes` or an equivalent confirmed flow) plus backup/rollback behavior.
+- The control plane and the code runtime do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys.
+- Human acceptance is distinct from artifact presence: `vgxness_sdd_accept_artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
+- Unrelated user work is preserved. Workspace boundary denials cannot be relaxed by agent or subagent overrides.
+
+## Tests
+
+The policy and approval flow are covered by:
+
+- `test/permissions/policy-evaluator.test.ts` — decisions, defaults, workspace boundary, SDD phase matrix.
+- `test/runs/` — approval records, reserved attempts, retry policy, abandonment, resume inspect/gate.
+- `test/code/` — approval broker, tool definitions, runtime approval flow.