vgxness 1.5.0 → 1.5.2

package/docs/harness-gap-analysis.md

@@ -1,243 +0,0 @@
-# Historical Harness Systems Gap Analysis
-
-> **Status:** historical planning note. This document predates much of the v1 runtime foundation. Use `docs/architecture.md`, `docs/prd.md`, and `docs/cli.md` as the current product references. Keep this file for design context, not as a live gap checklist.
-
-## Current interpretation after v1.3.0
-
-Several items below now exist as v1 foundations: local run records, preflight/approval planning, SDD artifacts, memory-backed storage, agent/subagent registries, provider setup previews, package evidence, and MCP control-plane tools.
-
-The remaining strategic gaps are narrower:
-
-- real provider/executor dispatch instead of planning-only run execution;
-- stronger SDD governance gates that combine artifact presence, human acceptance, verification evidence, and blockers;
-- operational TUI screens for SDD, runs, approvals, doctor, and settings;
-- sandbox/worktree enforcement beyond advisory planning;
-- export/import/redaction and upgrade/rollback evidence for beta readiness.
-
-This research compares current agent harness patterns against the `vgxness` PRD and identifies what the product still needs before it can become a serious local-first SDD harness.
-
-## Executive summary
-
-The current PRD has the right product direction: local-first, provider-agnostic, memory-backed, SDD-first, and agent/subagent aware.
-
-What is still missing is the **runtime contract**: permissions, sandboxing, run state, provider adapters, observability, evaluation, and artifact portability. Without these, `vgxness` risks becoming “memory + prompts” instead of a real harness.
-
-## Systems reviewed
-
-| System | Relevant lessons for `vgxness` |
-|---|---|
-| Anthropic agent patterns | Keep workflows simple and composable; distinguish predictable workflows from autonomous agents; invest heavily in tool design and transparency. |
-| Claude Code subagents | Subagents need isolated context, explicit tools, permissions, model selection, memory scopes, lifecycle hooks, and clear delegation descriptions. |
-| OpenCode agents | Provider/tool configuration should support primary agents, subagents, per-agent permissions, model routing, task permissions, and markdown/JSON definitions. |
-| OpenAI Agents SDK | Useful primitives: agents, handoffs, agents-as-tools, guardrails, sessions, human-in-the-loop, tracing, MCP, sandbox agents, and resumable workspaces. |
-| LangGraph | Durable execution, checkpoints, streaming, human-in-the-loop, stateful workflows, memory, and deep traces matter for long-running agents. |
-| AutoGen | Multi-agent systems benefit from layers: simple AgentChat, lower-level event-driven Core, extensions, distributed runtimes, and UI/studio tooling. |
-| CrewAI | Productized multi-agent systems commonly include agents, crews, flows, tasks, memory, knowledge, guardrails, observability, persistence, and resume. |
-
-## What the PRD already covers well
-
-- Local-first memory.
-- Project and personal/global memory scopes.
-- SDD-first workflow.
-- Agent and subagent registry from the MVP.
-- Provider-agnostic model with OpenCode/Claude Code adapters.
-- CLI for setup/configuration and integrations for day-to-day usage.
-- Cloud sync and team workflows correctly deferred until later.
-
-## Missing or underdefined areas
-
-### 1. Runtime/run model
-
-`vgxness` needs a first-class concept of a **run**.
-
-Minimum fields:
-
-- run id
-- project id/path
-- user intent
-- phase/workflow
-- selected agent/subagent
-- provider adapter
-- model
-- tool calls
-- artifacts read/written
-- memory reads/writes
-- approvals
-- verification evidence
-- final status
-
-Why it matters: without runs, the harness cannot resume, debug, audit, or explain agent behavior.
-
-### 2. Permission and sandbox model
-
-The PRD mentions agents and integrations, but not the security boundary.
-
-Needed capabilities:
-
-- Read/write/shell/network/git/memory permission categories.
-- Per-agent and per-tool permissions.
-- Human approval gates for destructive, external, or privileged operations.
-- Workspace boundary enforcement.
-- Optional sandbox/worktree strategy for implementation agents.
-
-This is NOT optional. A harness that can run agents without strong permissions is a loaded weapon.
-
-### 3. Provider adapter contract
-
-Provider-agnostic intent is correct, but the PRD needs an adapter interface.
-
-Each adapter should declare:
-
-- supported agent definition fields
-- supported permissions
-- supported memory injection modes
-- supported subagent/task model
-- supported hooks/lifecycle events
-- config file locations
-- limitations
-- export/render format
-
-This prevents `vgxness` from pretending all tools support the same features.
-
-### 4. Agent definition schema
-
-The agent registry needs a neutral schema, not just “store agents”.
-
-Suggested minimum schema:
-
-- name
-- description/delegation trigger
-- role/system instructions
-- mode: primary/subagent/workflow-phase
-- capabilities
-- allowed tools
-- denied tools
-- model preference
-- memory scopes
-- SDD phases supported
-- max steps/turns
-- required approvals
-- adapter overrides
-
-### 5. Tool/ACI design
-
-Agent-computer interface design is a product feature.
-
-Needed:
-
-- Tool descriptions optimized for model usage.
-- Safe input schemas.
-- Examples and edge cases per tool.
-- Clear boundaries between similar tools.
-- Tool-level tests/evals to catch misuse.
-
-Bad tools create bad agents. This is where a lot of harnesses quietly fail.
-
-### 6. Durable execution and resume
-
-SDD creates long-running work. Long-running work needs checkpoints.
-
-Needed:
-
-- run checkpoints
-- phase checkpoints
-- apply-progress merge rules
-- resumable interrupted runs
-- idempotency expectations for tools
-- failure classification: blocked, failed, needs-human, cancelled, completed
-
-### 7. Observability and debugging
-
-The product needs traces, not just logs.
-
-Minimum trace entities:
-
-- run
-- phase
-- agent/subagent invocation
-- tool call
-- memory operation
-- artifact operation
-- approval decision
-- verification command/result
-
-Nice-to-have later:
-
-- token/cost tracking
-- model latency
-- failure heatmap
-- timeline UI/export
-
-### 8. Evaluation and quality gates
-
-The PRD has success criteria, but not evals.
-
-Needed MVP evals:
-
-- agent resolution chooses the expected agent
-- SDD artifact chain remains complete
-- memory upsert/revision behavior is durable
-- provider adapter renders valid config
-- permission model blocks unsafe operations
-- resume restores the expected run state
-
-### 9. Artifact portability
-
-Memory-only artifacts are fast, but PRD/review workflows need portability.
-
-Needed:
-
-- export SDD artifacts to markdown/json
-- import artifacts back into memory
-- snapshot a run for debugging or sharing
-- redact sensitive data during export
-
-### 10. CLI surface definition
-
-The PRD says CLI, but the first command set is still open.
-
-Candidate MVP commands:
-
-- `vgx init`
-- `vgx memory search|get|save|update`
-- `vgx agent list|add|render|validate`
-- `vgx sdd new|continue|status|archive`
-- `vgx run list|show|resume`
-- `vgx adapter doctor|render`
-
-## Recommended MVP additions to PRD
-
-Add these as explicit MVP requirements:
-
-1. **Run lifecycle model** — every agentic operation is captured as a resumable/auditable run.
-2. **Permission model** — per-agent tool permissions with human approval gates.
-3. **Provider adapter contract** — adapters translate neutral `vgxness` definitions into provider-specific configs.
-4. **Agent schema** — neutral registry schema for agents/subagents/workflow-phase agents.
-5. **Trace model** — structured trace records for runs, tools, memory, artifacts, approvals, and verification.
-6. **Artifact export/import** — SDD and memory artifacts can be exported for review/debugging.
-7. **Evaluation harness** — tests/evals for agent resolution, adapters, permissions, memory, and resume.
-
-## Suggested next SDD change
-
-Create a new SDD change named `harness-runtime-foundation`.
-
-Scope it narrowly:
-
-- define run lifecycle schema
-- define agent registry schema
-- define permission categories
-- define provider adapter interface
-- add CLI validation/render skeleton
-- add tests for schemas and adapter rendering
-
-Do **not** implement full cloud sync, distributed agents, web UI, or team workflows yet.
-
-## Sources
-
-- Anthropic: Building effective agents
-- Claude Code: subagents documentation
-- OpenCode: agents documentation
-- OpenAI Agents SDK documentation
-- LangGraph overview
-- Microsoft AutoGen documentation
-- CrewAI documentation

package/docs/vgxcode.md

@@ -1,87 +0,0 @@
-# VGXNESS Code OpenTUI shell (`vgxcode`)
-
-Experimental Bun/OpenTUI coding interface for VGXNESS Code.
-
-**Naming rule:** `VGXNESS Code` is the public product/runtime surface (`vgxness code ...`; `vgx code ...` remains a compatibility alias). `vgxcode` is the internal root-owned OpenTUI shell that renders and drives that runtime during repository development.
-
-## Why this is root-owned
-
-VGXNESS ships the existing `vgxness`/`vgx` CLI bins while the OpenTUI coding interface remains an internal root-owned surface. The repository root owns `@opentui/core`, the Bun lockfile, and verification.
-
-This keeps the shipped `vgxness`/`vgx` CLI stable while letting us build the OpenTUI experience directly from root source.
-
-## Run
-
-Prerequisite: install Bun.
-
-```bash
-bun src/cli/tui/opentui/code/index.ts
-```
-
-Interactive mode starts in read-only `inspect`. Type a task/question and press `Enter`; `vgxcode` runs the root Bun CLI bridge as one of:
-
-```bash
-bun run cli:bun -- code inspect "<your prompt>" --events-jsonl
-bun run cli:bun -- code plan "<your prompt>" --events-jsonl
-bun run cli:bun -- code craft-preview "<your prompt>" --events-jsonl
-bun run cli:bun -- code craft "<your prompt>" --events-jsonl --approval-channel stdio
-```
-
-The OpenTUI shell uses `bun run --silent cli:bun -- ...` internally so Bun lifecycle output does not pollute the JSONL event stream.
-
-The prompt defaults to `inspect`. Press `Tab` to toggle between `inspect` and `plan`, or prefix a prompt with `/inspect`, `/plan`, `/craft-preview`, or `/craft`:
-
-```text
-/plan outline a safe implementation
-/inspect summarize the current architecture
-/craft-preview show the diff you would make
-/craft apply the smallest approved fix
-```
-
-After submit, the prompt input is cleared and the submitted prompt remains visible as `Last submitted`. The UI shows explicit `idle`, `running`, `completed`, and `error` states.
-
-`vgxcode` does not own mutation policy. `inspect`, `plan`, and `craft-preview` are read-only/preview paths. `/craft` is approval-capable and may mutate only through the VGXNESS Code runtime and its explicit approval channel; the OpenTUI shell only renders pending approvals and writes approve/deny decisions to the live runtime process.
-
-To replay real read-only runtime events without spawning the root CLI, pipe the root Bun CLI JSONL bridge into `vgxcode`:
-
-```bash
-bun run cli:bun -- code inspect "What is this project?" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
-bun run cli:bun -- code plan "Plan a safe change" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
-bun run cli:bun -- code craft-preview "Preview a safe change" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
-```
-
-Use `bun run cli:bun -- ...` for OpenTUI-adjacent local testing. `npm run cli -- ...` uses Node/tsx and can fail when a path loads `@opentui/core`.
-
-Press `Ctrl+C` to exit.
-
-## Current scope
-
-The shell reads newline-delimited `CodeRuntimeEvent` JSON from stdin when piped. If stdin has events or parse errors, `vgxcode` renders that stream and does not spawn the root CLI. If stdin is a TTY, the OpenTUI entrypoint opens the interactive prompt and uses `inspect` by default through the JSONL bridge.
-
-Errors are shown in the Activity panel when JSONL parsing fails, unsupported runtime events appear, npm/lifecycle banners appear in the stream, or the spawned root CLI exits non-zero.
-
-## Checks
-
-```bash
-npm run check:bun-lock          # from the repository root; read-only/advisory
-bun run verify:typecheck
-node --import tsx --test test/cli/tui/opentui-code.test.ts
-bun run smoke:opentui-code
-```
-
-The root `npm run check:bun-lock` command compares root `package.json`
-dependency specifiers with the root `bun.lock` without installing Bun or
-mutating `node_modules`. The root lockfile is the repository dependency
-authority; package evidence is validated by `bun run package:bun:evidence`.
-
-Manual interactive check:
-
-```bash
-bun src/cli/tui/opentui/code/index.ts
-# type: What is this project?
-# press Enter
-```
-
-## Safety rule
-
-`vgxcode` renders state and user decisions. It must not execute tools directly, bypass approvals, or own mutation policy. Runtime, approvals, verification, SDD, and memory stay in the VGXNESS core runtime.

package/docs/vgxness-code.md

@@ -1,48 +0,0 @@
-# VGXNESS Code Readiness Notes
-
-VGXNESS Code is the native VGXNESS coding CLI/runtime. It is not an OpenCode wrapper, fork, compatibility layer, config format, prompt copy, or branded re-skin. Provider adapters translate VGXNESS-native requests only.
-
-`vgxcode` is the internal root-owned OpenTUI shell for VGXNESS Code development. Public commands stay under `vgxness code ...`; the OpenTUI shell should render runtime state and approval decisions without becoming a separate mutation policy layer.
-
-## Commands
-
-- `vgxness code inspect "<question>"` — read-only repository investigation.
-- `vgxness code plan "<task>"` — read-only implementation planning.
-- `vgxness code craft "<task>"` — bounded edit-capable work with approval gates.
-- `vgxness code sdd <change> <phase>` — SDD-backed phase work; use `--save-artifact` only when persistence is intended.
-
-Useful controls: `--provider`, `--model`, `--stream`, `--json`, `--max-source-bytes`, `--approval-policy ask|allow|deny`, `--verification none|suggest|run|repair`, `--transcript off|summary|full`, and `--memory off|ask|auto`.
-
-## Configuration and Reporting
-
-Safe defaults are local and conservative: fake provider, read-only posture, approval policy `ask`, verification `suggest`, transcript `summary`, memory `off`, bounded prompt/context size, and no repair loop unless explicitly enabled.
-
-Transcript modes:
-- `off`: no transcript in the final summary.
-- `summary`: checkpoint labels/timestamps only.
-- `full`: sanitized checkpoints and tool summaries; command stdout/stderr are omitted by default.
-
-Memory modes:
-- `off`: never save learnings.
-- `ask`: prepare a sanitized memory-save checkpoint but do not persist.
-- `auto`: save sanitized learnings only through a configured memory gateway.
-
-## Safety Model
-
-VGXNESS Code routes edits, shell, network, git mutation, SDD persistence, and memory saves through explicit policy decisions. External workspace edits are denied, destructive commands require approval, git mutation is blocked by default unless explicitly approved, and network access requires approval. Prompts, reports, checkpoints, transcripts, and memory saves redact secret-like values.
-
-## SDD Mode
-
-SDD mode loads existing artifacts for the requested change/phase and exposes phase-appropriate tools. Non-implementation phases stay read/artifact oriented. `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools. Artifact saves require explicit persistence intent.
-
-## Verification and Provider Setup
-
-Project detection reports repository root, stack hints, config files, and verification presets such as `npm run typecheck` or `npm run test` when package scripts exist. The fake provider is deterministic for local tests. OpenAI-compatible providers are credential-gated by environment references; secret values are not inserted into prompts or reports.
-
-## Rollout Checklist
-
-- Config: safe defaults documented; transcript/memory/provider controls exposed.
-- Safety: external edits, destructive shell, git mutation, network, secrets, and unrelated user work covered by tests.
-- Verification: detected presets reported; verification results are honest pass/fail/skipped evidence.
-- Reporting: transcripts are configurable and sanitized; sensitive command output is omitted by default.
-- Provider behavior: core runtime remains provider-neutral and native VGXNESS Code.