vgxness 0.1.0

package/docs/architecture.md

@@ -0,0 +1,698 @@
+# vgxness Architecture
+
+`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 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.
+
+## Architecture decision summary
+
+| Area | Decision |
+|---|---|
+| Product shape | Local-first harness for advanced individual developers first; team/cloud features later. |
+| 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. |
+| 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. |
+| 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. |
+| Runtime | Every meaningful operation is captured as an auditable run with traces, artifacts, memory ops, approvals, and verification evidence. |
+| Safety | Permissions and sandbox boundaries are core domain concepts, not provider-specific afterthoughts. |
+
+## System boundaries
+
+```text
+Human operator                     AI coding tool / agent
+      │                                      │
+      ├───────────────┐                      │
+      ▼               ▼                      ▼
+ CLI (`vgx`)          TUI (`vgx`)       MCP server (`vgx mcp start`)
+      │               │                      │
+      └───────────────┴──────────┬───────────┘
+                                 ▼
+                        vgxness service layer
+                                 │
+              ┌──────────────────┴──────────────────┐
+              ▼                                     ▼
+      Configurator plane                    Runtime control plane
+        ├─ install/sync                       ├─ SDD workflow engine
+        ├─ asset rendering                    ├─ Run runtime
+        ├─ profile rendering                  ├─ Artifact service
+        ├─ config verify                      ├─ Permission policy engine
+        └─ backup/rollback                    └─ Trace/observability service
+              │                                     │
+              └──────────────────┬──────────────────┘
+                                 ▼
+                        vgxness core domain
+                          ├─ Agent registry
+                          ├─ Skill registry
+                          ├─ Memory service
+                          ├─ Adapter contracts
+                          └─ Evaluation/verification contracts
+                                 │
+              ┌──────────────────┴──────────────────┐
+              ▼                                     ▼
+      Provider adapter layer                  Local storage
+        ├─ OpenCode adapter                     ├─ Project store
+        ├─ Claude Code adapter                  └─ Personal/global store
+        └─ Future adapters such as Pi
+```
+
+This split is the key product boundary:
+
+- The **configurator plane** makes external AI tools usable: managed prompts, agents, skills, model profiles, permissions, and safe config rendering.
+- The **runtime control plane** makes SDD auditable: phase state, readiness gates, artifacts, approvals, checkpoints, traces, and run history.
+- The **interface layer** exposes the same capabilities through MCP, CLI, and TUI. MCP is agent-facing; CLI and TUI are human/operator-facing.
+
+Gentle-AI/`gentle-pi` are strong references for the configurator and agent-behavior side. `vgxness` should borrow those proven patterns while ensuring the runtime control plane remains explicit and provider-neutral.
+
+## Core domain model
+
+| Entity | Responsibility |
+|---|---|
+| `Agent` | Defines who executes work: role, instructions, capabilities, model preference, permissions, and compatible workflows. |
+| `Subagent` | Specialized agent intended for delegated/focused work with constrained scope and tools. |
+| `Skill` | Reusable knowledge/procedure that can be attached to agents, workflows, phases, or adapters. |
+| `Workflow` | A named process such as SDD, with ordered phases, gates, artifacts, and verification expectations. |
+| `Run` | Auditable execution record for an agentic operation. |
+| `Profile` | Model assignment strategy for orchestrators, agents, subagents, or SDD phases. |
+| `ManagedAsset` | Prompt, skill, command, chain, permission template, or config fragment rendered/synced into an external tool. |
+| `McpTool` | Agent-facing operation exported by the MCP server, backed by core services and permission policy. |
+| `DoctorCheck` | Health check for install/config/runtime readiness with actionable recovery guidance. |
+| `Trace` | Structured event stream describing what happened during a run. |
+| `Memory` | Durable observations, decisions, artifacts, preferences, and learnings. |
+| `Artifact` | Structured output such as PRD, spec, design, task list, apply progress, verify report, or archive report. |
+| `Adapter` | Translator between the neutral `vgxness` model and a provider-specific config/runtime. |
+| `PermissionPolicy` | Rules defining what an agent may do, what requires approval, and what must be denied. |
+
+## Storage model
+
+`vgxness` should keep local storage split by scope.
+
+| Scope | Purpose | Example location |
+|---|---|---|
+| 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**.
+
+## SDD workflow engine
+
+### Current implementation boundary
+
+SDD is the default workflow for substantial changes. The current workflow engine is provider-agnostic and local-first: it tracks phase artifact presence, readiness, and artifact persistence in SQLite only.
+
+```text
+explore → proposal → spec → design → tasks → apply-progress → verify → archive
+```
+
+Current phase artifacts use one canonical topic key each:
+
+```text
+sdd/{change}/{phase}
+```
+
+Readiness is based on artifact presence only:
+
+| Phase | Required artifacts |
+|---|---|
+| `explore` | none |
+| `proposal` | `explore` |
+| `spec` | `proposal` |
+| `design` | `proposal`, `spec` |
+| `tasks` | `proposal`, `spec`, `design` |
+| `apply-progress` | `tasks` |
+| `verify` | `apply-progress` |
+| `archive` | `verify` |
+
+Current service API:
+
+| API | Purpose |
+|---|---|
+| `getWorkflow(change)` | Return canonical phases, topic keys, and prerequisites. |
+| `getStatus({ project, change })` | Report present/missing phase artifacts and the next ready missing phase. |
+| `getReady({ project, change, phase })` | Report whether a phase is ready, satisfied prerequisites, and missing topic keys. |
+| `saveArtifact({ project, change, phase, content })` | Persist non-empty content under the canonical SDD topic key. |
+| `getArtifact({ project, change, phase })` | Read one full artifact from the local SQLite `artifacts` table by canonical topic key. |
+| `listArtifacts({ project, change })` | List matching artifacts from the local SQLite `artifacts` table in canonical phase order. |
+
+Artifact read/list surfaces use the full-content `artifacts` table in the selected local SQLite memory store. They do **not** read Engram search previews, and they do **not** create or modify `openspec/` paths.
+
+The CLI exposes the same boundary through `npm run cli -- sdd status|ready|save-artifact|get-artifact|list-artifacts`. These commands do **not** execute providers, continue phases automatically, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
+
+### Target architecture
+
+Long term, SDD orchestration must combine two mechanisms:
+
+1. **Agent behavior** — orchestrator prompts, SDD subagents/chains, skills, per-phase models, and strict TDD instructions rendered into tools such as OpenCode, Claude Code, or Pi.
+2. **Product state** — workflow definitions, prerequisites, artifacts, approvals, runs, checkpoints, verification results, and archive status stored locally and queried before advancing.
+
+The first mechanism makes agents effective. The second makes the workflow enforceable and inspectable. `vgxness` should not rely on either one alone.
+
+## Configurator and profile plane
+
+To be comparable with Gentle-AI-like systems, `vgxness` needs a configurator plane that can install, sync, render, and verify managed assets for supported tools without taking ownership of user files blindly.
+
+Planned responsibilities:
+
+| Responsibility | Purpose |
+|---|---|
+| Asset catalog | Know which prompts, skills, SDD agents, commands, chains, and permission templates are managed. |
+| Safe rendering | Generate provider-specific artifacts from neutral definitions without mutating source registries. |
+| Profile management | Assign models per orchestrator, agent, subagent, or SDD phase. |
+| File merge strategy | Inject managed blocks without clobbering user-owned config. |
+| Backup/rollback | Snapshot affected config before sync/install and provide restore metadata. |
+| Config verification | Report missing assets, invalid provider config, stale versions, and unsupported adapter capabilities. |
+
+This plane should remain separate from runtime execution. Rendering OpenCode, Claude Code, or Pi assets is not the same thing as running an SDD phase.
+
+## Interface surfaces
+
+`vgxness` exposes the same local core through three surfaces. This prevents the product from becoming three separate implementations of the same rules.
+
+| Surface | Primary user | Job | Must not |
+|---|---|---|---|
+| MCP server | AI coding tools and agents | Query/update workflow state, resolve agents/skills, record runs/checkpoints, request approvals. | Bypass permission policy or mutate provider config directly. |
+| CLI | Human operators, scripts, CI-friendly automation | Initialize, inspect, doctor, sync/render assets, manage MCP installs, inspect SDD/runs/profiles. | Hide dangerous changes or require manual JSON editing for the happy path. |
+| TUI | Humans during setup and local operation | Guide installation, show health/status, configure profiles, inspect SDD progress, surface blockers. | Become a decorative dashboard without next actions. |
+
+### Natural-language planning seam
+
+`NaturalLanguagePlanner` is the provider-agnostic front-door classifier for operator text. It maps an intent to exactly one preview flow: `direct`, `plan`, `sdd`, or `diagnose`, with confidence, reasons, signals, safety notes, and preview-only next actions.
+
+The CLI exposes this through:
+
+```bash
+npm run cli -- orchestrator preview --project vgxness --intent "..." [--change <id>] [--db <path>]
+```
+
+This seam is intentionally non-executing. It may read SDD status/next context for a supplied change from the selected local SQLite store, but it does not call providers, invoke run preflight, edit code, write provider config, create run records, install global memory, or create `openspec/`. Future live orchestration must build on this explicit preview contract instead of bypassing it with prompt-only routing.
+
+### MCP server boundary
+
+The MCP server is the agent-facing control plane. It should expose typed, narrow tools backed by the same service APIs used by CLI and TUI.
+
+Current MCP operator verification uses two short-lived CLI commands before connecting a client:
+
+```bash
+npm run cli -- mcp setup --preview --provider opencode --db <path>
+npm run cli -- mcp setup --preview --provider claude --db <path>
+npm run cli -- mcp doctor --db <path> --project vgxness --change manual-smoke
+```
+
+`mcp setup --preview` returns copyable stdio client snippets only. It is read-only and must not write `.opencode/`, `.claude/`, or provider config. `mcp doctor` verifies local readiness with JSON checks and may prepare/use the selected SQLite DB, but it does not mutate provider configuration.
+
+Current MCP tool groups are defined in source by `SUPPORTED_VGX_MCP_TOOL_NAMES`; the table below is representative, not exhaustive:
+
+| Group | Example tools | Purpose |
+|---|---|---|
+| SDD | `vgxness_sdd_status`, `vgxness_sdd_next`, `vgxness_sdd_ready`, `vgxness_sdd_save_artifact`, `vgxness_sdd_get_artifact`, `vgxness_sdd_list_artifacts` | Let agents ask what can happen next and retrieve local SQLite SDD artifacts without guessing from prompts. |
+| Runs | `vgxness_run_start`, `vgxness_run_list`, `vgxness_run_get`, `vgxness_run_preflight`, `vgxness_run_checkpoint`, `vgxness_run_finalize` | Keep execution history, safety preflight, and resumability explicit. |
+| Resolution/profile/payload | `vgxness_agent_resolve`, `vgxness_agent_activate`, `vgxness_manager_profile_get`, `vgxness_manager_profile_set`, `vgxness_skill_payload`, `vgxness_opencode_manager_payload` | Give agents the correct role, skills, model/profile context, and read-only OpenCode manager previews. Payload/profile preview tools do not execute providers or mutate provider config by default. |
+
+MVP transport should prefer local stdio because it matches common MCP host expectations and avoids opening a network port. A local HTTP transport can be added later for dashboard or background-daemon use cases.
+
+### CLI boundary
+
+The CLI is the scriptable operator surface. It should be predictable, dry-run friendly, and explicit about whether a command only inspects state or mutates local/provider config.
+
+Command shape should stay verb-first and grouped by product concept:
+
+```bash
+vgx init
+vgx doctor
+vgx status
+vgx mcp install opencode
+vgx mcp status
+vgx sdd status <change>
+vgx sdd next <change>
+vgx profiles list
+vgx profiles set apply <model>
+```
+
+### TUI boundary
+
+The TUI is the guided human surface. It should optimize for the next meaningful decision:
+
+| Screen | Main decision/action |
+|---|---|
+| Setup | Select tools, inspect provider readiness, review copy-only external setup guidance, and run doctor-style checks. |
+| Workflows | Understand available workflow paths and safe next actions. |
+| Runs | Inspect run history, current run state, blockers, and resumable execution. |
+| Approvals | Review pending permission requests and safety gates. |
+| Agents | Inspect registered agents/subagents, attached skills, model/profile routing, and provider compatibility. |
+| SDD | See active changes, missing artifacts, next ready phase, blockers, and resumable runs. |
+| Doctor | Fix broken config, missing MCP integration, memory issues, and stale assets. |
+| Settings | Review local preferences and configuration status without silent provider writes. |
+
+Every TUI screen must define loading, empty, error, success, blocked, and permission states. The dashboard TUI is read-only: provider config writes/install/apply are external-only, require explicit confirmation outside the dashboard, and are not run by dashboard flows.
+
+### Installation flow
+
+The happy path should be guided and step-based:
+
+```text
+1. Install binary
+2. Run `vgx`
+3. Select AI tools
+4. Install MCP integration
+5. Configure memory
+6. Choose SDD mode/profile
+7. Run doctor
+8. Open the AI tool and start working
+```
+
+The same flow must be automatable through CLI flags and dry-run output so users can preview provider config changes before applying them.
+
+## Agent and subagent registry
+
+The registry stores provider-neutral definitions.
+
+Minimum schema:
+
+```yaml
+name: code-reviewer
+description: Reviews code for maintainability, bugs, and security issues
+mode: subagent
+instructions:
+  kind: path
+  value: ./prompts/code-reviewer.md
+capabilities:
+  - code-review
+  - security-review
+permissions:
+  read: allow
+  edit: deny
+  shell: ask
+memory:
+  scopes:
+    - project
+    - personal
+skills:
+  - code-review
+  - secure-coding
+adapters:
+  opencode:
+    model: anthropic/claude-sonnet-4-20250514
+  claude-code:
+    model: sonnet
+```
+
+Provider-specific fields are allowed only under adapter overrides.
+
+First implementation slice stores this neutral model locally in SQLite through the `AgentRegistryService` API:
+
+| API | Purpose |
+|---|---|
+| `registerAgent(input)` | Upsert a top-level agent by `project + scope + name`. |
+| `registerSubagent(input)` | Upsert a subagent with a required same-project/same-scope parent agent. |
+| `getAgent(id)` / `getAgentByName(project, scope, name)` | Read full provider-neutral configuration. |
+| `listAgents(filters)` / `listSubagents(parentAgentId)` | Read summaries for discovery and delegation relationships. |
+| `resolveAgents(input)` | Rank registered agents/subagents for a task using transparent metadata rules. |
+
+Adapter-specific options stay under `adapters.{adapterName}` and are treated as opaque neutral JSON by the core registry.
+
+Harness tools expose the same registry through `createAgentRegistryToolHandlers(...)` for tool-facing JSON-ish payloads:
+
+| Handler | Purpose |
+|---|---|
+| `registerAgent(input)` / `registerSubagent(input)` | Validate tool payloads and upsert provider-neutral definitions. |
+| `getAgent({ id })` / `getAgentByName({ project, scope, name })` | Read full definitions for execution or adapter rendering. |
+| `listAgents(filters)` / `listSubagents({ parentAgentId })` | Discover available agents and parent-child relationships. |
+
+The minimal CLI exposes this same registry for local terminal use through `npm run cli -- agents register|list|get` and `npm run cli -- subagents register|list|get`. It stays thin: flag/JSON-file parsing, SQLite opening, and JSON formatting only; registry rules remain in the service/tool boundary.
+
+Current agent resolution v1 is provider-agnostic, deterministic, and rule-based. It accepts project/scope, task text or intent, desired capabilities, workflow/phase, provider adapter, and optional `agent`/`subagent` mode. Resolution reads existing agent definitions only, then scores compatible candidates with transparent reasons:
+
+- capability matches
+- workflow/phase matches such as `sdd`, `apply`, or `sdd:apply`
+- provider adapter compatibility, with empty adapter maps treated as provider-neutral
+- skill-name matches from the agent definition `skills` field
+- task text matches against agent name, description, capabilities, skills, and workflows
+- mode and subagent parent relationship signals
+
+Incompatible definitions are returned under `skipped` with reasons such as project/scope mismatch, mode mismatch, provider adapter mismatch, workflow mismatch, or capability mismatch. Ties are stable: higher score first, then top-level agents before subagents, then agent name/id.
+
+```bash
+npm run cli -- agents resolve --project vgxness --capabilities implementation,typescript --workflow sdd --phase apply --provider opencode --task "Implement the next SDD apply slice"
+npm run cli -- agents resolve --project vgxness --mode subagent --capabilities review --workflow sdd --phase verify
+```
+
+Resolution v1 does **not** call an AI/model ranker, execute agents, mutate provider config, install tools, choose a model dynamically, or create/update provider files. Future orchestration can use these ranked candidates as one explicit input, but current behavior is explainable metadata matching only.
+
+## Skill registry and self-improvement
+
+Skills are versioned assets registered independently from agents and provider config. The current v1 foundation is provider-agnostic and local-first: it stores skill identity, versions, source metadata, compatibility hints, attachments, and simple usage outcomes in SQLite.
+
+Current v1 APIs:
+
+| API | Purpose |
+|---|---|
+| `registerSkill(input)` | Upsert a skill by `project + scope + name`. |
+| `addSkillVersion(input)` / `listSkillVersions(skillId)` | Store version metadata, source info, compatibility hints, and optionally activate the version as current. |
+| `attachSkill(input)` / `detachSkill(...)` | Attach a skill to an agent, subagent, workflow phase, or provider adapter without mutating provider files. |
+| `getSkill(...)` / `getSkillByName(...)` / `getSkillDetails(id)` / `listSkills(filters)` | Read skills, current version, versions, attachments, and usage records. |
+| `resolveSkills(input)` | Resolve active skill versions for an agent/runtime context. |
+| `buildSkillPayload(input, options)` | Resolve skills and return provider-agnostic injection payload v1 without writing provider config. |
+| `recordSkillUsage(input)` | Record whether a skill was selected/injected or later helped, failed, or was neutral during a run. |
+| `createSkillImprovementProposal(input)` | Create a reviewable proposed skill version from trace/failure/correction/memory signals without changing the active skill. |
+| `submit/approve/reject/cancel/applySkillImprovementProposal(...)` | Gate the proposal lifecycle and activate only an approved proposal when apply is explicit. |
+
+Source metadata is descriptive at registration time: `path`, `url`, and `inline` sources are stored without installing or rewriting provider files. Payload building can materialize injection-ready content from inline metadata and from safe local paths only.
+
+Current skill resolution v1 is provider-agnostic and deterministic. It accepts an agent id or agent name/project/scope, workflow/phase, provider adapter, and optional run id. Resolution checks the agent definition `skills` field first, then matching agent/subagent attachments, workflow-phase attachments such as `sdd:apply` or `apply`, and provider-adapter attachments such as `opencode`. Duplicate skills are returned once in first-seen order with all attachment sources preserved. Only active versions are returned: explicit attachment versions must be active, otherwise the skill current version must exist and be active. Missing skills, no-current-version skills, draft/deprecated/archived versions, and missing attachment versions are reported in `skipped` instead of failing the whole resolution.
+
+The resolver returns enough data for payload building: skill id/name, version id/version, source metadata, inline `summary`/`content` when present, and attachment reason/source. If a run id and explicit resolution outcome are supplied, it records `selected` or `injected` usage for audit. Payload v1 turns resolved skills into deterministic provider-agnostic items with identity, source kind, content availability, attachment reasons, and ordering metadata. Inline content is available directly. URL sources remain metadata-only with `url_fetch_disabled`. Local path sources are read-only and only loaded when the path resolves inside the supplied workspace root; missing, unsafe, non-file, or oversized paths return deterministic unavailable reasons instead of throwing.
+
+Payload v1 does **not** inject into a live provider, write `.opencode/`, `.claude/`, or user/global config, fetch networks/URLs, evaluate quality, or propose autonomous skill changes.
+
+Skill improvement proposals are the current controlled foundation for self-improvement. A proposal stores the target skill, base version, proposed source/compatibility metadata, rationale, source signal, and deterministic diff summary. Proposal creation and approval do **not** mutate the active skill. Only `applySkillImprovementProposal(...)` on an `approved` proposal creates a new skill version and makes it current/active, with actor/reason audit fields on the proposal. Rejected or cancelled proposals cannot be applied.
+
+CLI examples:
+
+```bash
+npm run cli -- skills register --project vgxness --name sdd-apply --description "Applies SDD tasks"
+npm run cli -- skills add-version --project vgxness --name sdd-apply --version 1.0.0 --source-kind path --source-path .config/opencode/skills/sdd-apply/SKILL.md --activate
+npm run cli -- skills attach --project vgxness --name sdd-apply --target-type workflow-phase --target-key sdd:apply
+npm run cli -- skills resolve --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
+npm run cli -- skills payload --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
+npm run cli -- skills propose --project vgxness --name sdd-apply --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Updated skill"}' --rationale "Repeated correction from trace"
+npm run cli -- skills submit-proposal --proposal <proposal-id> --actor uziel
+npm run cli -- skills approve-proposal --proposal <proposal-id> --actor uziel --reason "Reviewed diff"
+npm run cli -- skills apply-proposal --proposal <proposal-id> --actor uziel
+```
+
+V1 does **not** autonomously detect trace patterns, mutate skill files, activate autonomous updates, evaluate proposed quality, or write external skill/provider configuration. Proposal creation is reviewable, and activation is gated by explicit approval plus explicit apply.
+
+Minimum lifecycle:
+
+```text
+draft → active → proposed-update → approved → active
+                    └────────────→ rejected
+active → deprecated → archived
+```
+
+Self-improvement must be controlled:
+
+1. Observe traces, failures, corrections, and repeated patterns.
+2. Detect a candidate skill improvement.
+3. Generate a reviewable diff/version proposal.
+4. Run relevant evaluations.
+5. Ask for human approval.
+6. Activate approved version with rollback history.
+
+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.
+
+Current contract:
+
+| 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`, and warnings. |
+| `ProviderRenderArtifact` | Relative path, content type, and generated contents. |
+
+Renderers currently include:
+
+| Provider | Preview artifact | Notes |
+|---|---|---|
+| `json` | `rendered/json/...` | Export/debug shape; includes matching `adapters.json` as `selectedAdapter`. |
+| `opencode` | `rendered/opencode/<project>/<scope>/<agent>/opencode.json` | Single config preview with `$schema` and `agent` object. Top-level agents default to `primary`; subagents render as `subagent`. |
+
+```bash
+npm run cli -- agents render --provider json --project vgxness --name apply-agent
+npm run cli -- 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.
+
+### OpenCode injection preview
+
+The current OpenCode integration also exposes a preview-only composition seam through `OpenCodeInjectionPreviewService` and the thin CLI command:
+
+```bash
+npm run cli -- opencode preview --provider opencode --agent apply-agent --project vgxness --change checkout-flow --phase apply-progress
+```
+
+This preview lives in the provider adapter/preview layer, not in provider-agnostic core services. It composes existing read-only outputs:
+
+| Output | Source boundary |
+|---|---|
+| `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, write `.opencode/`, write `.claude/`, or touch user/global provider config. Future live injection should build on this contract only after a separate approved change defines execution, hook, or MCP safety rules.
+
+### OpenCode manager orchestration
+
+The checked-in OpenCode default config and `seeds/agents/agent-seed-v1.json` define `vgxness-manager` as an MCP-first orchestrator. The manager should use `vgxness_session_restore` with the project and workspace directory when starting, resuming, or recovering context, then use SDD artifact/status tools, memory tools, agent resolution, run/preflight tools, and read-only payload/profile previews before delegating substantial phase work to exact SDD subagents. Before ending, pausing, handing off, or compacting, it should call `vgxness_session_close` with the current session id, actor `manager`, and an actionable summary; if no current session id is available, it must not invent one and should preserve the summary in its final response. Its OpenCode `permission.task` remains deny-by-default: `*` is denied and only the canonical `vgxness-sdd-*` subagent names are allowed explicitly. The seed/default prompts are self-contained and do not require external `~/.config/opencode/skills/sdd-*` files; such skills are optional registry assets if a project registers them separately.
+
+## 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:
+
+```text
+created → 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.
+
+Current run fields:
+
+- run id
+- user intent
+- project identity
+- workflow and phase
+- selected agent/subagent id
+- provider adapter
+- model
+- status, outcome, and outcome reason
+- latest checkpoint id
+- created/updated/completed timestamps
+
+Timeline events store audit entries such as tool calls, permission decisions, approvals, memory operations, artifact references, and verification evidence. Events may reference memory observation IDs or artifact IDs, but run state remains separate from long-term memory and SDD artifacts.
+
+Current operation enforcement is safe-by-default and executor-injected: `RunService.executeOperation(...)` evaluates permission, records the `permission-decision`, then either blocks or calls the supplied `RunOperationExecutor`.
+
+Execution isolation is currently **planning-only**. `planExecutionIsolation(...)` and `RunService.planOperationExecution(...)` produce an auditable plan before any real executor exists; they do not create worktrees, launch sandboxes, run shell commands, call providers, or mutate files.
+
+| Operation shape | Current planned strategy | Current behavior |
+|---|---|---|
+| In-workspace read | `workspace` | Allowed when permission policy allows it; filesystem plans require realpath/symlink hardening before any future execution. |
+| Edit, git, destructive mutation | `git-worktree` | Planned as isolated mutation work, but still asks/blocks according to permission policy. No worktree is created yet. |
+| Shell, network, provider tool, privileged operation | `process-sandbox` | Planned as sandboxed process/provider work, but approval is still required by default. No sandbox is launched yet. |
+| External directory or out-of-workspace path | `process-sandbox` or blocked workspace plan | Denied by default or requires explicit stronger future approval conditions; external paths are not allowed by current plans. |
+
+Every plan includes path constraints, required approvals/conditions, whether realpath hardening must happen before execution, and limitations that state the future boundary. Real sandbox/worktree executors are follow-up work after this planner is connected to a safe execution backend.
+
+| Decision | Current behavior |
+|---|---|
+| `deny` | Records an `operation-execution` event with `status: "blocked"`; executor is not invoked. |
+| `ask` | Creates a pending approval, records enough pending operation metadata to resume later, and records `status: "pending-approval"`; executor is not invoked. |
+| `allow` | Invokes the injected executor once and records `status: "succeeded"` or `status: "failed"`. |
+
+When the decision is `ask`, the runtime creates a first-class pending approval record linked to the permission-decision event. `allow` and `deny` decisions do not create approvals. Approval records can be listed per run, fetched by id, and resolved once as `approved`, `rejected`, or `cancelled` with actor, reason, and timestamp.
+
+Approved operation resume is available only through the service API and an injected executor:
+
+```ts
+runService.resumeApprovedOperation({
+  approvalId,
+  executor: fakeOrSandboxedExecutor,
+});
+```
+
+Resume does **not** re-run policy. Before calling the injected executor, the runtime creates a durable operation attempt reservation linked to the approval id, original permission-decision event, original pending execution event, operation metadata, executor name, attempt sequence, and `reserved` status. The storage model now supports multiple ordered attempts per approval, but active `reserved` attempts remain exclusive.
+
+After the executor returns, the attempt is finalized as `succeeded` or `failed`, then the runtime appends the `operation-execution` event with `policyReevaluated: false` and the attempt id. If appending that event fails, the finalized attempt still prevents duplicate execution on retry.
+
+Stuck `reserved` attempts can be explicitly abandoned through `RunService.abandonReservedOperationAttempt({ attemptId, actor, reason })`. Abandonment is recovery-only: it changes the attempt to `abandoned`, appends an `operation-execution` audit event with the actor, reason, approval id, attempt id, and `executorInvoked: false`, and does **not** call an executor or retry anything.
+
+Retry admission is storage/admission only. `RunService.admitOperationRetryAttempt(...)` can reserve the next ordered attempt after an earlier terminal attempt only when explicit retry policy evaluation allows the latest status. It appends an audit event with `retryAdmission: true`, `executorInvoked: false`, and `operationExecuted: false`; it does **not** execute the operation, launch a sandbox, call a provider, or invoke an executor. Without a policy, the default remains `never`, so admission is blocked.
+
+Resume is safe by default: `RunService.resumeApprovedOperation(...)` uses the `never` retry policy, so any existing `reserved`, `succeeded`, `failed`, or `abandoned` attempt blocks later resume calls before executor invocation. `RunService.evaluateOperationRetry(...)` can evaluate explicit policies without executing anything:
+
+| 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` |
+
+The retry decision returns `allowed`, `reasonCode`, a human-readable `reason`, evaluated attempt count, retryable statuses, and latest/active attempt metadata for audit. The CLI exposes this only as `runs retry-check --approval <id> [--policy <json>]`; it is a read-only operator check and does not append events, reserve attempts, invoke executors, or retry. Mutation/admission CLI, explicit retry execution, timeout detection, and sandboxed execution are follow-up work.
+
+```ts
+runService.executeOperation({
+  runId,
+  operation: { category: 'read', operation: 'preview-file', workspaceRoot, targetPath: 'src/index.ts' },
+  executor: fakeOrSandboxedExecutor,
+});
+```
+
+`getRun(...)` includes `operationAttempts` beside events, checkpoints, and approvals so callers can audit reservations even if final event recording failed. `evaluatePermissionForRun(...)` remains available when the caller only wants the audit decision and pending approval record. Approvals created without a pending `executeOperation(...)` event are not resumable because they lack deterministic operation metadata. Real shell/filesystem/network/provider execution is still future work. The current enforcement and resume boundary is intentionally testable with fake or deterministic executors only.
+
+Checkpoints store resumable JSON state per run:
+
+```ts
+runService.appendCheckpoint({
+  runId,
+  label: 'after-plan',
+  state: { nextTask: 'implement-runtime', completed: ['schema'] },
+});
+```
+
+Follow-up runtime work:
+
+- 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
+
+## Trace model
+
+Traces make the harness inspectable.
+
+Minimum trace events:
+
+- run started/stopped
+- phase started/stopped
+- agent invoked
+- skill injected
+- memory read/write
+- artifact read/write
+- tool call requested/completed/failed
+- permission requested/approved/denied
+- verification command started/completed
+- error/blocker recorded
+
+## Permission model
+
+Permissions must be defined in `vgxness` first, then mapped to adapters.
+
+Minimum categories:
+
+| Category | Examples |
+|---|---|
+| `read` | files, memory, artifacts |
+| `edit` | write, patch, modify files |
+| `shell` | commands, scripts, package managers |
+| `git` | status, diff, branch, commit, push |
+| `network` | web fetch, API calls, package downloads |
+| `memory` | create/update/delete/search memory |
+| `external-directory` | access outside project/user-approved roots |
+| `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.
+
+Current foundation API: `evaluatePermission(request)` in `src/permissions/` 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
+- secrets and external directory access deny by default
+- 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.
+
+## Future interface surface
+
+Candidate future CLI surface beyond the current minimal local CLI documented in `docs/cli.md`:
+
+```bash
+vgx init
+vgx memory search|get|save|update
+vgx agent list|add|validate|render
+vgx skill list|add|propose|approve|reject
+vgx sdd new|continue|status|archive
+vgx run list|show|resume
+vgx adapter doctor|render
+```
+
+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.
+
+## 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.
+- 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:
+
+- cloud sync
+- team collaboration
+- web dashboard
+- distributed workers
+- fully autonomous skill mutation