vgxness 1.5.1 → 1.6.0

package/dist/sdd/sdd-workflow-service.js

@@ -21,7 +21,9 @@ export class SddWorkflowService {
         if (!validated.ok)
             return validated;
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases);
+        if (!phases.ok)
+            return phases;
+        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value);
         return {
             ok: true,
             value: {
@@ -36,20 +38,27 @@ export class SddWorkflowService {
         if (!validated.ok)
             return validated;
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return statusFromPhases(validated.value.change, phases);
+        if (!phases.ok)
+            return phases;
+        return statusFromPhases(validated.value.change, phases.value);
     }
     getNext(input) {
         const validated = validateProjectAndChange(input.project, input.change);
         if (!validated.ok)
             return validated;
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return ok(nextDecisionFromStatuses(validated.value.change, phases));
+        if (!phases.ok)
+            return phases;
+        return ok(nextDecisionFromStatuses(validated.value.change, phases.value));
     }
     getCockpit(input) {
         const validated = validateProjectAndChange(input.project, input.change);
         if (!validated.ok)
             return validated;
-        const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
+        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
+        if (!snapshot.ok)
+            return snapshot;
+        const phases = snapshot.value.phases;
         const next = nextDecisionFromStatuses(validated.value.change, phases);
         const cockpitPhases = phases.map((phaseStatus) => {
             const readiness = {
@@ -57,9 +66,7 @@ export class SddWorkflowService {
                 phase: phaseStatus.phase,
                 ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases),
             };
-            const artifact = phaseStatus.present
-                ? this.artifactSummaryForPhase(validated.value.project, validated.value.change, phaseStatus.phase, phaseStatus.topicKey)
-                : undefined;
+            const artifact = phaseStatus.present ? cockpitArtifactSummaryFromSnapshotItem(phaseStatus) : undefined;
             const blockers = cockpitBlockersForPhase(phaseStatus, readiness);
             return {
                 phase: phaseStatus.phase,
@@ -100,6 +107,39 @@ export class SddWorkflowService {
         };
         return ok(cockpit);
     }
+    getGovernanceSnapshot(input) {
+        const validated = validateProjectAndChange(input.project, input.change);
+        if (!validated.ok)
+            return validated;
+        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
+        if (!snapshot.ok)
+            return snapshot;
+        const phases = snapshot.value.phases;
+        const status = statusFromPhases(validated.value.change, phases);
+        if (!status.ok)
+            return status;
+        const warnings = [];
+        const artifacts = phases.flatMap((phase) => {
+            if (phase.artifact === undefined)
+                return [];
+            const envelope = normalizeSddArtifact(phase.artifact);
+            warnings.push(...envelope.warnings);
+            if ((input.payloadMode ?? 'compact') === 'compact') {
+                const compactArtifact = compactGovernanceArtifact(envelope.artifact);
+                return [
+                    {
+                        phase: phase.phase,
+                        topicKey: phase.topicKey,
+                        artifact: compactArtifact,
+                        envelope: { ...envelope, artifact: compactArtifact },
+                    },
+                ];
+            }
+            return [{ phase: phase.phase, topicKey: phase.topicKey, artifact: phase.artifact, envelope }];
+        });
+        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases) };
+        return ok({ status: status.value, artifacts, ...(readiness === undefined ? {} : { readiness }), warnings });
+    }
     saveArtifact(input) {
         const validated = this.validatePhaseInput(input);
         if (!validated.ok)
@@ -161,12 +201,33 @@ export class SddWorkflowService {
         if (input.payloadMode !== 'compact')
             return artifact;
         const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses)));
+        if (!statuses.ok)
+            return statuses;
+        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value)));
     }
     listArtifacts(input) {
         const validated = validateProjectAndChange(input.project, input.change);
         if (!validated.ok)
             return validated;
+        if (input.payloadMode === 'compact') {
+            const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
+            if (!snapshot.ok)
+                return snapshot;
+            return ok({
+                project: validated.value.project,
+                change: validated.value.change,
+                artifacts: snapshot.value.phases.flatMap((phase) => {
+                    if (phase.artifact === undefined)
+                        return [];
+                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases))];
+                }),
+                fullRetrieval: {
+                    tool: 'vgxness_sdd_list_artifacts',
+                    payloadMode: 'verbose',
+                    input: { project: validated.value.project, change: validated.value.change },
+                },
+            });
+        }
         const listed = this.memory.listArtifactsByTopicPrefix(validated.value.project, `sdd/${validated.value.change}/`, this.context);
         if (!listed.ok)
             return listed;
@@ -174,22 +235,7 @@ export class SddWorkflowService {
         const artifacts = sddPhases
             .map((phase) => artifactsByTopicKey.get(sddTopicKey(validated.value.change, phase)))
             .filter((artifact) => artifact !== undefined);
-        if (input.payloadMode !== 'compact')
-            return ok({ project: validated.value.project, change: validated.value.change, artifacts });
-        const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        return ok({
-            project: validated.value.project,
-            change: validated.value.change,
-            artifacts: artifacts.map((artifact) => {
-                const phase = isSddPhase(artifact.phase) ? artifact.phase : phaseFromTopicKey(validated.value.change, artifact.topicKey);
-                return compactArtifactProjection(artifact, validated.value.change, phase, getReadinessFromStatuses(validated.value.change, phase, statuses));
-            }),
-            fullRetrieval: {
-                tool: 'vgxness_sdd_list_artifacts',
-                payloadMode: 'verbose',
-                input: { project: validated.value.project, change: validated.value.change },
-            },
-        });
+        return ok({ project: validated.value.project, change: validated.value.change, artifacts });
     }
     validatePhaseInput(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -200,31 +246,38 @@ export class SddWorkflowService {
         return { ok: true, value: { ...validated.value, phase: input.phase } };
     }
     getPhaseStatuses(project, change) {
-        return sddPhases.map((phase) => {
+        const snapshot = this.loadPhaseSnapshot(project, change);
+        if (!snapshot.ok)
+            return snapshot;
+        return ok(snapshot.value.phases.map(({ artifact, acceptance, createdAt, updatedAt, warnings, ...status }) => status));
+    }
+    loadPhaseSnapshot(project, change) {
+        const listed = this.memory.listArtifactsByTopicPrefixNoTrace(project, `sdd/${change}/`);
+        if (!listed.ok)
+            return listed;
+        const artifactsByTopicKey = new Map(listed.value.map((artifact) => [artifact.topicKey, artifact]));
+        const phases = sddPhases.map((phase) => {
             const topicKey = sddTopicKey(change, phase);
-            const artifact = this.memory.getArtifact(project, topicKey, this.context);
-            if (!artifact.ok)
-                return { phase, topicKey, present: false, state: 'missing', accepted: false, legacy: false };
-            return phaseStatusFromArtifact(phase, topicKey, artifact.value);
+            const artifact = artifactsByTopicKey.get(topicKey);
+            if (artifact === undefined)
+                return { phase, topicKey, present: false, state: 'missing', accepted: false, legacy: false, warnings: [] };
+            const envelope = normalizeSddArtifact(artifact);
+            return {
+                phase,
+                topicKey,
+                present: true,
+                state: envelope.metadata.status,
+                accepted: envelope.metadata.status === 'accepted',
+                legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
+                artifactId: artifact.id,
+                artifact,
+                ...(envelope.metadata.acceptance === undefined ? {} : { acceptance: envelope.metadata.acceptance }),
+                createdAt: artifact.createdAt,
+                updatedAt: artifact.updatedAt,
+                warnings: envelope.warnings,
+            };
         });
-    }
-    artifactSummaryForPhase(project, change, phase, topicKey) {
-        const artifact = this.memory.getArtifact(project, topicKey, this.context);
-        if (!artifact.ok)
-            return undefined;
-        const envelope = normalizeSddArtifact(artifact.value);
-        return {
-            phase,
-            topicKey,
-            present: true,
-            accepted: envelope.metadata.status === 'accepted',
-            legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
-            state: envelope.metadata.status,
-            artifactId: artifact.value.id,
-            ...(envelope.metadata.acceptance === undefined ? {} : { acceptance: envelope.metadata.acceptance }),
-            createdAt: artifact.value.createdAt,
-            updatedAt: artifact.value.updatedAt,
-        };
+        return ok({ project, change, phases });
     }
 }
 export function nextDecisionFromStatuses(change, phases) {
@@ -336,18 +389,6 @@ function getReadinessFromStatuses(change, phase, phases) {
         blockedPrerequisites,
     };
 }
-function phaseStatusFromArtifact(phase, topicKey, artifact) {
-    const envelope = normalizeSddArtifact(artifact);
-    return {
-        phase,
-        topicKey,
-        present: true,
-        state: envelope.metadata.status,
-        accepted: envelope.metadata.status === 'accepted',
-        legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
-        artifactId: artifact.id,
-    };
-}
 function compactArtifactProjection(artifact, change, phase, readiness) {
     const envelope = normalizeSddArtifact(artifact);
     const summary = summarizePayloadContent(artifact.content);
@@ -370,6 +411,35 @@ function compactArtifactProjection(artifact, change, phase, readiness) {
         updatedAt: artifact.updatedAt,
     };
 }
+function cockpitArtifactSummaryFromSnapshotItem(item) {
+    if (item.artifact === undefined || item.artifactId === undefined || item.createdAt === undefined || item.updatedAt === undefined)
+        return undefined;
+    return {
+        phase: item.phase,
+        topicKey: item.topicKey,
+        present: true,
+        accepted: item.accepted === true,
+        legacy: item.legacy === true,
+        state: item.state ?? 'draft',
+        artifactId: item.artifactId,
+        ...(item.acceptance === undefined ? {} : { acceptance: item.acceptance }),
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+    };
+}
+function compactGovernanceArtifact(artifact) {
+    return {
+        id: artifact.id,
+        project: artifact.project,
+        topicKey: artifact.topicKey,
+        phase: artifact.phase,
+        observationId: artifact.observationId,
+        createdAt: artifact.createdAt,
+        updatedAt: artifact.updatedAt,
+        contentLength: artifact.content.length,
+        contentOmitted: true,
+    };
+}
 function cockpitBlockersForPhase(status, readiness) {
     const blockers = [];
     if (!status.present)

package/dist/setup/providers/claude-setup-adapter.js

@@ -3,24 +3,29 @@ import { noWriteActionSafety } from './provider-setup-adapter.js';
 export const claudeSetupAdapter = {
     id: 'claude',
     displayName: 'Claude',
-    supportLevel: 'preview-only',
-    capabilities: ['mcp-preview', 'manual-guidance'],
-    targets: [{ kind: 'manual', label: 'Claude MCP config snippet', writableBySetup: false }],
+    supportLevel: 'supported-secondary',
+    capabilities: ['mcp-preview', 'mcp-install-plan', 'cli-mcp-plan', 'agent-preview', 'doctor', 'manual-guidance'],
+    targets: [
+        { kind: 'project-config', label: 'Project .mcp.json', path: '.mcp.json', writableBySetup: false },
+        { kind: 'project-config', label: 'Project Claude agents', path: '.claude/agents/*.md', writableBySetup: false },
+        { kind: 'project-config', label: 'Project Claude memory', path: 'CLAUDE.md', writableBySetup: false },
+        { kind: 'user-config', label: 'User Claude agents', path: '~/.claude/agents/*.md', writableBySetup: false },
+    ],
     getStatus(context) {
         return {
             providerId: 'claude',
-            status: 'preview-only',
-            summary: 'Claude setup is preview-only with manual MCP guidance.',
+            status: 'supported-secondary',
+            summary: 'Claude is supported as a secondary, non-default provider for CLI MCP registration planning/apply, project .mcp.json compatibility, and project/user agent planning; explicit guarded apply is required for writes or CLI execution.',
             evidence: context.databasePath !== undefined
                 ? ['Claude MCP preview can be generated from the selected database path.']
                 : ['Claude MCP preview uses a placeholder until a database path is selected.'],
-            guidance: ['Copy snippets manually after reviewing them. The TUI does not install or apply Claude config.'],
+            guidance: ['Use `vgxness mcp install claude --scope local|project|user --yes --run-id <id>` for explicit guarded apply. VGXNESS may write project-root CLAUDE.md only through confirmed, preflighted Claude project install; it never manually writes ~/.claude.json or .claude/CLAUDE.md. Read-only setup/status surfaces do not execute Claude Code.'],
             actions: [
                 {
                     id: 'claude-manual-guidance',
-                    label: 'Review Claude MCP snippet',
+                    label: 'Review guarded Claude install guidance',
                     kind: 'manual-guidance',
-                    description: 'Manual preview guidance only; no install/apply action is available.',
+                    description: 'Supported secondary guidance only in setup status; writes are available only through the guarded mcp install claude flow with run preflight metadata.',
                     safety: noWriteActionSafety,
                 },
             ],

package/dist/setup/setup-plan.js

@@ -1,4 +1,5 @@
 import { join, resolve } from 'node:path';
+import { planClaudeCodeMcpInstall } from '../mcp/client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from '../mcp/client-install-opencode-contract.js';
 import { resolveMemoryDatabasePath } from '../memory/storage-paths.js';
 import { vgxnessSetupDefaults } from './setup-defaults.js';
@@ -45,8 +46,66 @@ export function createSetupPlan(input) {
             },
         };
     }
+    if (provider === 'claude') {
+        const claude = planClaudeCodeMcpInstall({
+            cwd: input.workspaceRoot,
+            databasePath: database.value.path,
+            databasePathSource: database.value.planSource,
+            ...(input.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.overwriteVgxness }),
+        });
+        const targetPath = claude.targetPath;
+        if (claude.status === 'refused') {
+            return {
+                ok: true,
+                value: {
+                    ...common,
+                    provider: 'claude',
+                    db: { mode: database.value.mode, path: database.value.path, source: database.value.source },
+                    status: 'conflict',
+                    actions: [],
+                    conflicts: [
+                        {
+                            id: claude.reason,
+                            severity: 'blocking',
+                            message: claude.message,
+                            targetPath,
+                            recovery: claude.reason === 'malformed_claude_project_memory' || claude.reason === 'conflicting_claude_project_memory' ? 'Manually reconcile the VGXNESS markers in project-root CLAUDE.md, then rerun `vgxness setup plan --provider claude`.' : 'Inspect the Claude project config, resolve the conflict, then rerun `vgxness setup plan --provider claude`.',
+                        },
+                    ],
+                    backupsPlanned: [],
+                    nextCommands: ['vgxness mcp install claude --plan --scope project', 'Resolve the reported Claude project conflict before guarded apply.'],
+                },
+            };
+        }
+        return {
+            ok: true,
+            value: {
+                ...common,
+                provider: 'claude',
+                db: { mode: database.value.mode, path: database.value.path, source: database.value.source },
+                status: 'ready',
+                actions: [
+                    {
+                        id: 'claude-guarded-install',
+                        description: `Review supported secondary Claude plan for CLI MCP registration, .mcp.json compatibility, ${claude.agentNames.length} .claude/agents/*.md file(s), and guarded project-root CLAUDE.md managed block; apply only with vgxness mcp install claude --scope project --yes --run-id <id>.`,
+                        mutating: false,
+                        targetPath,
+                        backupRequired: claude.backupRequired,
+                    },
+                ],
+                conflicts: [],
+                backupsPlanned: claude.targets
+                    .filter((target) => target.kind !== 'cli-mcp-registration' && ((target.kind === 'project-memory' && target.backupRequired) || target.action === 'merge' || target.action === 'update-vgxness'))
+                    .map((target) => ({
+                    targetPath: target.path,
+                    reason: target.kind === 'project-memory' ? 'A future guarded Claude apply would create a managed VGXNESS backup before appending or updating the project-root CLAUDE.md managed block.' : 'A future guarded Claude apply would create a managed VGXNESS backup before merging or updating Claude project configuration.',
+                })),
+                nextCommands: ['vgxness mcp install claude --plan --scope project', 'vgxness mcp install claude --scope project --yes --run-id <id>', 'OpenCode remains the default/primary provider.'],
+            },
+        };
+    }
     if (provider !== 'opencode')
-        return { ok: false, error: { code: 'validation_failed', message: 'Provider must be opencode or none for the setup plan.' } };
+        return { ok: false, error: { code: 'validation_failed', message: 'Provider must be opencode, claude, or none for the setup plan.' } };
     const opencode = planOpenCodeMcpInstall({
         cwd: input.workspaceRoot,
         databasePath: database.value.path,

package/docs/architecture.md

@@ -1,10 +1,12 @@
 # vgxness Architecture
 
+> **Scope:** this document describes the v1.5.1 architecture as it is actually built. It is the source of truth for how the product works today. Planned work that is not yet shipped lives in [Roadmap](./roadmap.md); historical planning context that no longer reflects reality has been retired. Where this doc disagrees with code, code wins — file a doc-sync task against the relevant module.
+
 `vgxness` is a local-first, provider-agnostic, Gentle-AI-like harness for agentic development. Its core architecture separates the product domain from provider-specific tooling so agents, skills, memory, SDD workflows, runs, and traces can work across OpenCode, Claude Code, and future adapters such as Pi.
 
-The architectural goal is not only to install better prompts or agent configs. `vgxness` should combine an ecosystem configurator with a runtime control plane: configured agents may execute the work, but the product keeps explicit state for phase readiness, artifacts, runs, approvals, checkpoints, and audit evidence.
+The architectural goal is not only to install better prompts or agent configs. `vgxness` combines an ecosystem configurator with a runtime control plane and a native code runtime: configured agents may execute the work, the control plane keeps explicit state for phase readiness, artifacts, runs, approvals, checkpoints, and audit evidence, and the code runtime performs bounded agentic work in the local workspace with explicit permission decisions.
 
-The user-facing shape is deliberately three-surface: **MCP for agents**, **CLI for scriptable operator control**, and **TUI for guided setup and visual local operations**. All three must call the same core services instead of reimplementing workflow rules.
+The user-facing shape is deliberately four-surface: **MCP for agents**, **CLI for scriptable operator control**, **TUI for guided setup and visual local operations**, and **code runtime (`vgxness code`)** for bounded agentic work in the workspace. All four call the same core services instead of reimplementing workflow rules.
 
 ## Architecture decision summary
 
@@ -14,9 +16,9 @@ The user-facing shape is deliberately three-surface: **MCP for agents**, **CLI f
 | Reference model | Similar product surface to Gentle-AI/`gentle-pi`: agent setup, SDD orchestration, memory wiring, skills, profiles, permissions, verification. |
 | Differentiator | Verifiable runtime state engine: SDD phases, artifacts, runs, approvals, checkpoints, and audit trails are queryable product state, not prompt-only convention. |
 | Core workflow | SDD-first canonical state: explore → proposal → spec → design → tasks → apply-progress → verify → archive. |
-| Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows. |
+| Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows, and `vgxness code` runtime for bounded workspace work. |
 | Installation UX | Step-based guided setup with doctor checks, dry-run support, and no manual provider JSON editing on the happy path. |
-| Provider strategy | Provider-agnostic domain model with OpenCode and Claude Code first; Pi/`gentle-pi` compatibility is a future adapter/reference target. |
+| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for CLI MCP registration, project `.mcp.json` compatibility, guarded project-root `CLAUDE.md` managed memory, and project/user agent planning. Claude scopes are `local`, `project`, and `user` (`personal`/`global` map to `user`). Read-only status/doctor/change-plan never execute Claude Code or inspect private Claude config, and VGXNESS never manually mutates `~/.claude.json` or `.claude/CLAUDE.md`. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
 | Memory | Project memory plus personal/global memory, backed locally. |
 | Agents | Agents/subagents are registered in a neutral schema, then rendered into provider-specific config. |
 | Skills | Skills are first-class, versioned, attachable to agents/workflows/adapters, and improved through reviewable proposals. |
@@ -98,7 +100,7 @@ Gentle-AI/`gentle-pi` are strong references for the configurator and agent-behav
 | Project | Repo-specific memory, SDD artifacts, run history, adapter config, project agents/skills. | `.vgx/` or project-local SQLite store. |
 | Personal/global | User preferences, reusable skills, cross-project patterns, global agents. | User-level config/data directory. |
 
-The exact path format is still open, but the architectural rule is fixed: **project data and personal data must not be collapsed into one scope**.
+The exact path format is still open, but the architectural rule is fixed: **project data and personal data must not be collapsed into one scope**. See [Storage](./storage.md) for schema, migration layout, and lifecycle.
 
 ## SDD workflow engine
 
@@ -116,18 +118,20 @@ Current phase artifacts use one canonical topic key each:
 sdd/{change}/{phase}
 ```
 
-Readiness is based on artifact presence only:
+Readiness is a combination of prerequisite phase artifacts, explicit human acceptance, and aggregate blockers — artifact presence alone is not enough:
 
-| Phase | Required artifacts |
-|---|---|
-| `explore` | none |
-| `proposal` | `explore` |
-| `spec` | `proposal` |
-| `design` | `proposal`, `spec` |
-| `tasks` | `proposal`, `spec`, `design` |
-| `apply-progress` | `tasks` |
-| `verify` | `apply-progress` |
-| `archive` | `verify` |
+| Phase | Required prerequisites | Acceptance required |
+|---|---|---|
+| `explore` | none | no |
+| `proposal` | `explore` | yes (on `explore`) |
+| `spec` | `proposal` | yes (on `proposal`) |
+| `design` | `proposal`, `spec` | yes (on `proposal`, `spec`) |
+| `tasks` | `proposal`, `spec`, `design` | yes (on `proposal`, `spec`, `design`) |
+| `apply-progress` | `tasks` | yes (on `tasks`) |
+| `verify` | `apply-progress` | yes (on `apply-progress`) |
+| `archive` | `verify` | yes (on `verify`) |
+
+`SddWorkflowService.getReady(...)` returns a structured `SddReadiness` with `blockedPrerequisites`, while `getCockpit(...)` aggregates `SddCockpitBlocker`s of kind `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, or `readiness`. Acceptance is recorded only by a human actor (`acceptedBy.type === 'human'`); the runtime rejects agent or anonymous acceptance.
 
 Current service API:
 
@@ -409,7 +413,7 @@ NO silent mutation of active skills. Eso es una línea roja.
 
 ## Provider adapter contract
 
-Adapters render registry definitions into provider artifacts without changing the registry model.
+Adapters render registry definitions into provider artifacts without changing the registry model. The full adapter contract, render API, and how to add a new provider live in [Providers](./providers.md); this section is a high-level map.
 
 Current contract:
 
@@ -435,7 +439,7 @@ vgxness agents render --provider opencode --project vgxness --name apply-agent
 Rendering is intentionally read-only: it returns generated content in the CLI response. It does **not** write `.opencode/`, `.claude/`, or any user/global provider config.
 OpenCode agent keys are sanitized deterministically from registry names, and rendering rejects key collisions instead of overwriting generated config.
 
-Claude Code rendering remains follow-up work after its exact install-safe artifact shape is specified.
+Claude Code install planning/apply is supported through the guarded MCP install path. Rendering remains read-only; confirmed project compatibility writes are limited to `.mcp.json`, `.claude/agents/*.md`, and the project-root `CLAUDE.md` managed block with run preflight metadata. Local/user MCP registration is represented through Claude CLI argv after confirmation/preflight, not private config mutation.
 
 ### OpenCode injection preview
 
@@ -462,15 +466,15 @@ The checked-in OpenCode default config and `seeds/agents/agent-seed-v1.json` def
 
 ## Run lifecycle
 
-A run is the core unit of execution. The current foundation stores local, provider-neutral run records in SQLite; deeper orchestration and approval enforcement are follow-up work.
-
-Current terminal lifecycle rules:
+A run is the core unit of execution. Run records are stored locally in SQLite and stay provider-neutral. The lifecycle is complete in v1.5.1:
 
 ```text
-created → completed | failed | blocked | cancelled
+created → planned → running → needs-human
+                                      ↓
+                              completed | failed | blocked | cancelled
 ```
 
-The broader planned lifecycle still includes `planned`, `running`, and `needs-human`, but this slice only enforces safe finalization: terminal runs cannot be finalized again, and final outcomes must match the terminal status.
+All eight statuses are first-class on `RunStatus` (`src/runs/schema.ts:1`). The control plane exposes lifecycle operations through `vgxness_run_start`, `vgxness_run_checkpoint`, `vgxness_run_finalize`, and the read-only `vgxness_run_resume_inspect` and `vgxness_run_resume_gate` tools. Finalize is safe by default: terminal runs cannot be finalized again, and the final `outcome` must match the terminal `status` (`success`/`partial`/`failure`/`blocked`/`cancelled`).
 
 Current run fields:
 
@@ -556,14 +560,13 @@ runService.appendCheckpoint({
 });
 ```
 
-Follow-up runtime work:
+Open follow-up for run execution lives in [Roadmap](./roadmap.md). The remaining work is:
+
+- real provider/tool invocation behind sandboxed executors (the lifecycle and policy recording are stable; the actual executor is still test-only)
+- CLI/MCP orchestration for `resume-after-approval` once a safe executor exists outside tests
+- richer verification evidence summaries that link runs, tasks, and verifications
 
-- active state transitions for `planned`, `running`, and `needs-human`
-- real provider/tool invocation behind sandboxed executors
-- CLI or adapter orchestration for resume-after-approval once a safe executor exists outside tests
-- operator UX for retry admission and retry execution, with clear separation between reservation and actual execution
-- sandbox/worktree execution strategies after decision recording is stable
-- richer verification evidence summaries
+What is already shipped: 8-state lifecycle, approval records, reserved attempts, retry policy evaluation with `never`/`after-abandoned`/`after-failure`/`after-failure-or-abandoned`, run insights with debug summary, run snapshot export (`RunSnapshotPackageV1`), and a `runs retry-check --approval <id> [--policy <json>]` operator command.
 
 ## Trace model
 
@@ -584,9 +587,7 @@ Minimum trace events:
 
 ## Permission model
 
-Permissions must be defined in `vgxness` first, then mapped to adapters.
-
-Minimum categories:
+Permissions are defined in `vgxness` first, then mapped to adapters through the neutral `permissions` field on agents and subagents. The full safety model, including approval flow, redactors, and runtime gates, is in [Safety model](./safety.md). Categories:
 
 | Category | Examples |
 |---|---|
@@ -600,15 +601,9 @@ Minimum categories:
 | `provider-tool` | opaque adapter/provider tool calls |
 | `secrets` | environment variables, credentials, tokens |
 
-Operations can resolve to:
-
-- `allow`
-- `ask`
-- `deny`
-
-Default stance for destructive or external operations: **ask or deny**, never implicit allow.
+Operations resolve to `allow`, `ask`, or `deny`. Destructive or external operations default to **ask or deny**, never implicit allow.
 
-Current foundation API: `evaluatePermission(request)` in `src/permissions/` returns `allow`, `ask`, or `deny` with a reason. Defaults are intentionally conservative:
+Current foundation API: `evaluatePermission(request)` in `src/permissions/policy-evaluator.ts` returns `allow`, `ask`, or `deny` with a reason. Defaults are intentionally conservative:
 
 - workspace reads are allowed only when the target path stays inside `workspaceRoot`
 - edits, shell, git, network, memory writes/searches, and provider-specific tools ask by default
@@ -616,84 +611,31 @@ Current foundation API: `evaluatePermission(request)` in `src/permissions/` retu
 - destructive, external, privileged, or ambiguous requests require ask even when an agent override would otherwise allow the category
 - workspace boundary denials cannot be relaxed by agent/subagent overrides
 
-Agent and subagent registry definitions keep neutral `permissions` such as `{ "shell": "ask", "provider-tool": "deny" }`. Provider names and tool details remain opaque metadata; enforcement and sandbox execution are follow-up runtime work.
+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`; `PolicyApprovalBroker`, `StdioApprovalBroker`, and `ConservativePermissionGateway` (in `src/code/runtime/approval-coordinator.ts`) wire approval prompts to the runtime event stream. See [Code runtime](./code-runtime.md) for the workspace-side contract.
 
-## Future interface surface
+## Interface surface (current)
 
-Current and near-term CLI surface should build on the plural domain commands documented in `docs/cli.md`. Future shortcuts can be added later, but they should not imply separate singular command families:
+CLI surface groups are documented in [CLI reference](./cli.md). The plural form is canonical — singular shortcuts are not added.
 
-```bash
-vgxness init
-vgxness memory search|get|save|update
-vgxness agents list|register|get|resolve|render
-vgxness skills list|register|propose|approve-proposal|apply-proposal
-vgxness sdd status|next|ready|save-artifact|accept-artifact|list-artifacts
-vgxness runs list|get|timeline|debug|resume-inspect|resume-gate
-vgxness mcp doctor|install
-vgxness opencode preview
-```
-
-Representative MCP tools mirror the same core services for agent use. For the current exact tool names, use `SUPPORTED_VGX_MCP_TOOL_NAMES`:
-
-```text
-vgxness_sdd_status
-vgxness_sdd_next
-vgxness_sdd_ready
-vgxness_sdd_save_artifact
-vgxness_sdd_get_artifact
-vgxness_sdd_list_artifacts
-vgxness_memory_search
-vgxness_memory_get
-vgxness_memory_save
-vgxness_memory_update
-vgxness_run_start
-vgxness_run_list
-vgxness_run_get
-vgxness_run_preflight
-vgxness_run_checkpoint
-vgxness_run_finalize
-vgxness_agent_resolve
-vgxness_agent_activate
-vgxness_manager_profile_get
-vgxness_manager_profile_set
-vgxness_skill_payload
-vgxness_opencode_manager_payload
-```
-
-The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations are the execution/configuration plane.
+MCP tools mirror the same core services for agent use. The full, current list of 38 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations and the code runtime sit on the execution plane.
 
 ## Evaluation strategy
 
-Minimum eval/test targets:
-
-- Agent resolution selects the expected agent.
-- Skill resolution injects the expected skill.
-- Adapter rendering produces valid provider config.
-- Permission rules block unsafe operations.
-- SDD artifact chains remain complete.
-- Memory upserts preserve revisions.
-- Run resume restores expected state.
-- Skill improvement proposals are versioned and require approval.
-- MCP tools call the same core services as CLI/TUI and return actionable blocked states.
-- TUI setup screens expose loading, empty, error, success, blocked, and permission states.
+Minimum eval/test targets (asserted through `node:test` files under `test/`, totaling 95 files as of v1.5.1):
+
+- Agent resolution selects the expected agent (`test/agents/agent-resolver.test.ts`).
+- Skill resolution injects the expected skill (`test/skills/`).
+- Adapter rendering produces valid provider config (`test/agents/provider-renderer.test.ts`).
+- Permission rules block unsafe operations (`test/permissions/policy-evaluator.test.ts`).
+- SDD artifact chains remain complete and human acceptance is enforced (`test/sdd/sdd-workflow-service.test.ts`).
+- Memory upserts preserve revisions (`test/memory/`).
+- Run resume restores expected run state and respects retry policies (`test/runs/`).
+- Skill improvement proposals are versioned and require approval (`test/skills/`).
+- MCP tools call the same core services as CLI/TUI and return actionable blocked states (`test/mcp/`).
+- Code runtime behavior across inspect, plan, craft-preview, and craft modes (`test/code/`).
+- OpenCode config rendering and drift detection (`test/mcp/opencode-agent-config-drift.test.ts`).
 - Installation dry-run reports the exact provider config changes before mutation.
 
-## Immediate implementation recommendation
-
-The next SDD change should be `harness-runtime-foundation`.
-
-Scope:
-
-- define schemas for agents, skills, runs, traces, permissions, and adapters
-- add local persistence for these entities where missing
-- add adapter validation/render skeleton
-- add CLI/MCP/TUI interface boundaries for validation, inspection, and guided setup
-- add tests for schema validation, permission decisions, and adapter rendering
-
-Out of scope:
+## Future work
 
-- cloud sync
-- team collaboration
-- web console
-- distributed workers
-- fully autonomous skill mutation
+Planned work that is not yet shipped lives in [Roadmap](./roadmap.md). This document stays focused on the architecture as built; the roadmap is the place to track what is next and what is explicitly deferred.