vgxness 1.5.1 → 1.5.2

package/docs/code-runtime.md

@@ -0,0 +1,218 @@
+# VGXNESS Code runtime (`vgxness code`)
+
+`vgxness code` is the native VGXNESS coding CLI/runtime. It is not a wrapper around OpenCode, a fork, a compatibility layer, a config format, a prompt copy, or a branded re-skin. Provider adapters translate VGXNESS-native requests only.
+
+`vgxcode` is the experimental OpenTUI shell that renders `vgxness code` runtime events. It is currently root-owned during development; promoted surfaces will move to the standard `vgxness`/`vgx` bins.
+
+## Commands
+
+```bash
+vgxness code inspect "<question>"          # read-only repository investigation
+vgxness code plan "<task>"                 # read-only implementation planning
+vgxness code craft-preview "<task>"        # show the diff you would make
+vgxness code craft "<task>"                # bounded edit-capable work with approval gates
+vgxness code sdd <change> <phase>          # SDD-backed phase work
+```
+
+Common flags across modes:
+
+| Flag | Effect |
+|---|---|
+| `--provider <id>` | `openai-compatible` (default in real use) or `fake` (deterministic for tests). |
+| `--model <id>` | Provider model id. |
+| `--stream` | Emit JSONL runtime events as they happen. |
+| `--json` | Final response as JSON. |
+| `--max-source-bytes <bytes>` | Bound on sources loaded into the prompt. |
+| `--approval-policy ask\|allow\|deny` | Default `ask`. |
+| `--approval-channel stdio\|auto` | `stdio` reads decisions from stdin; `auto` uses the configured broker. |
+| `--verification none\|suggest\|run\|repair` | Verification posture. Default `suggest`. |
+| `--transcript off\|summary\|full` | Final summary contents. Default `summary`. |
+| `--memory off\|ask\|auto` | Memory save posture. Default `off`. |
+| `--events-jsonl` | Output only the JSONL event stream (used for piping into the OpenTUI shell). |
+
+`vgxness code sdd <change> <phase>` accepts:
+
+| Flag | Effect |
+|---|---|
+| `--save-artifact` | Persist the phase artifact when explicit persistence is intended. |
+| `--change-id <id>` | Override change id. |
+| `--approval-policy`, `--approval-channel`, `--memory` | Same as the other modes. |
+
+## Modes
+
+### `inspect`
+
+Read-only repository investigation. The runtime exposes only the `read` tool group: `list_files`, `read_file`, `search_content`, `inspect_project`, `git_status`, `git_diff`, `git_log`. No mutations, no shell, no network, no git writes.
+
+### `plan`
+
+Read-only implementation planning. Same read tool group as `inspect`. The runtime can summarize architecture, propose safe approaches, and produce implementation outlines without touching the workspace.
+
+### `craft-preview`
+
+Show the diff the runtime would apply. The runtime may call read tools and run planning-style reasoning, but does not write. Output is a unified diff that the user can review before approving the actual mutation.
+
+### `craft`
+
+Approval-gated, bounded edit-capable work. Adds the workspace mutation group (`apply_patch`, `create_file`, `update_file`, `delete_file`), the shell/verification group (`run_shell_command`, `run_verification_command`, `network_request`, `git_mutation`), and SDD persistence tools if `--save-artifact` is set. Each mutation routes through `evaluatePermission(...)`; the `ApprovalBroker` either auto-resolves per `--approval-policy` or surfaces a prompt through the configured `approval-channel`.
+
+## Tool groups (19 tools)
+
+The runtime's tool set is defined in `src/code/tools/tool-definitions.ts` and is composed per mode.
+
+### Read-only (7)
+
+| Tool | Category | Notes |
+|---|---|---|
+| `list_files` | `read` | Repository files within the workspace. |
+| `read_file` | `read` | Bounded text read. |
+| `search_content` | `read` | Text content search. |
+| `inspect_project` | `read` | Project metadata: package scripts, config files. |
+| `git_status` | `git` | Inspection only. |
+| `git_diff` | `git` | Inspection only. |
+| `git_log` | `git` | Inspection only. |
+
+### Workspace mutations (4, all confirm-gated)
+
+| Tool | Tier | Notes |
+|---|---|---|
+| `apply_patch` | `confirm`, audit | Bounded unified patch inside the workspace. |
+| `create_file` | `confirm`, audit | New file inside the workspace. |
+| `update_file` | `confirm`, audit | Existing file update. |
+| `delete_file` | `restricted`, audit | Destructive; tighter gate. |
+
+### Shell, verification, network, git mutation (4, confirm-gated)
+
+| Tool | Category | Notes |
+|---|---|---|
+| `run_shell_command` | `shell` | Non-destructive commands; permission-gated. |
+| `run_verification_command` | `shell` | Routed through the permission-aware shell executor. |
+| `network_request` | `network` | Bounded; explicit approval required. |
+| `git_mutation` | `git` | Denied by default unless policy explicitly allows it. |
+
+### SDD reads (5)
+
+| Tool | Notes |
+|---|---|
+| `sdd_status` | Read SDD change status for the active change. |
+| `sdd_get_readiness` | Read readiness for the active phase; does not mutate artifacts. |
+| `sdd_read_artifact` | Read one artifact for the active change. |
+| `sdd_next_phase` | Recommended next phase. |
+| `governance_report` | Redacted SDD governance report snapshot. |
+
+### SDD persistence (3, confirm-gated)
+
+| Tool | Notes |
+|---|---|
+| `sdd_save_artifact` | Saves only when explicit persistence was requested. |
+| `sdd_mark_ready` | Marks the phase ready; only when explicit persistence was requested. |
+| `sdd_accept_artifact` | Records human-only acceptance; agents must not auto-accept. |
+
+The SDD tool set is composed per phase: `apply-progress` exposes edit + shell + verification + persistence; `verify` exposes verification shell tools; other phases stay read/artifact oriented.
+
+## Providers
+
+The runtime is provider-neutral. Adapters implement `CodeProviderAdapter` (`src/code/providers/provider-adapter.ts`):
+
+| Adapter | Status | Notes |
+|---|---|---|
+| `openai-compatible` | Real | Speaks to any OpenAI-compatible endpoint; credentials come from environment references, never embedded. |
+| `fake` | Tests | Deterministic, offline; for unit tests and CI. |
+
+There is no native Anthropic provider in the runtime as of v1.5.1. OpenCode exposes an OpenAI-compatible bridge for Claude models; users who want Claude through `vgxness code` go through that bridge. Adding a native Anthropic provider is tracked in [Roadmap](./roadmap.md).
+
+## Approval flow
+
+`PolicyApprovalBroker`, `StdioApprovalBroker`, and `ConservativePermissionGateway` (in `src/code/runtime/approval-coordinator.ts`) wire approval decisions to the runtime event stream.
+
+```text
+tool call requested
+   │
+   ▼
+PolicyApprovalBroker  ──►  ConservativePermissionGateway.evaluate(...)
+   │                              │
+   │                              ├── allow  → execute, record event
+   │                              ├── ask    → ApprovalPrompt
+   │                              │            ├── stdio channel: read line from stdin
+   │                              │            └── auto channel:   call injected broker
+   │                              └── deny   → record blocked event, return error
+   ▼
+CodeRuntimeEventSink (stream JSONL to consumer)
+```
+
+The `vgxcode` OpenTUI shell is one consumer of the event sink. When `craft` requests approval, the shell renders the prompt and writes the human decision back through the live process.
+
+## Configuration and reporting
+
+Safe defaults are local and conservative:
+
+- Provider: `fake` for offline/CI smoke; `openai-compatible` for real use.
+- Posture: read-only by default unless the mode is `craft` or `craft-preview` was previewed.
+- Approval policy: `ask`.
+- Verification: `suggest`.
+- Transcript: `summary` (checkpoint labels/timestamps only).
+- Memory: `off` (never auto-save learnings).
+- Bounded prompt/context size; 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.
+
+Prompts, reports, checkpoints, transcripts, and memory saves redact secret-like values through `omitSensitiveCommandOutput`, `redactJson`, and `redactSecrets` (`src/code/reporting/redaction.ts`).
+
+## SDD mode
+
+`vgxness code sdd <change> <phase>` 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 `--save-artifact` (or the equivalent runtime flag); passing it is the only way persistence is triggered.
+
+## Project detection
+
+`detectProject()` (in `src/code/runtime/project-detection.ts`) 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.
+
+## OpenTUI shell (`vgxcode`)
+
+The shell reads newline-delimited `CodeRuntimeEvent` JSON from stdin. If stdin has events or parse errors, `vgxcode` renders that stream and does not spawn the CLI. If stdin is a TTY, the OpenTUI entrypoint opens the interactive prompt and uses `inspect` by default.
+
+```bash
+bun src/cli/tui/opentui/code/index.ts
+```
+
+Interactive controls: `Tab` toggles between `inspect` and `plan`; prefix with `/inspect`, `/plan`, `/craft-preview`, or `/craft` to switch. Press `Enter` to submit; `Ctrl+C` to exit. The prompt input is cleared after submit and the submitted prompt remains visible as `Last submitted`. The UI shows explicit `idle`, `running`, `completed`, and `error` states.
+
+Replay real read-only runtime events without spawning the root CLI:
+
+```bash
+bun run cli:bun -- code inspect "What is this project?" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
+```
+
+`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 runtime and its explicit approval channel; the OpenTUI shell only renders pending approvals and writes approve/deny decisions to the live runtime process.
+
+## 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.
+- Network access requires approval.
+- Secret-like values are redacted from prompts, reports, checkpoints, transcripts, and memory saves.
+- Unrelated user work is preserved (no glob expansion outside the workspace, no `.` rewrites, no recursive deletes without explicit operator intent).
+
+The full contract — categories, approval flow, redactors, retry policy — is in [Safety model](./safety.md).
+
+## Rollout checklist
+
+For projects adopting `vgxness code`:
+
+- **Config**: safe defaults documented; transcript/memory/provider controls exposed (`--transcript`, `--memory`, `--provider`).
+- **Safety**: external edits, destructive shell, git mutation, network, secrets, and unrelated user work are covered by tests under `test/code/`.
+- **Verification**: detected presets reported by `detectProject()`; 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, not a wrapper around any specific provider.

package/docs/contributing.md

@@ -0,0 +1,120 @@
+# Contributing
+
+VGXNESS is an alpha local-first control plane. The repository follows a few rules that keep the product safe, predictable, and reviewable. This document is for humans and AI assistants who want to change the code, the docs, or both.
+
+## Repository layout
+
+```
+src/
+  agents/         # agent + subagent registry, resolver, canonical manifest
+  cli/            # CLI dispatch, command modules, TUI, OpenTUI
+  code/           # native code runtime (vgxness code)
+  export/         # redaction and export helpers
+  governance/     # governance report builder, overlay fingerprint
+  harness/        # harness-side tool handlers
+  mcp/            # MCP server, schemas, control plane, doctor, OpenCode install
+  memory/         # memory service, SQLite database, migrations
+  orchestrator/   # natural-language planner (preview only)
+  payload/        # payload summary helpers
+  permissions/    # policy evaluator, schemas
+  providers/      # OpenCode provider adapter
+  runs/           # run lifecycle, execution planning, retry, snapshot export
+  sdd/            # SDD workflow service, schema, artifact portability
+  setup/          # setup defaults, plan, lifecycle, backup-rollback
+  skills/         # skill registry, resolver, payload, improvement proposals
+  verification/   # verification plan + report services
+  workflows/      # workflow registry, executor, allowlist adapter
+
+test/             # node:test files mirroring src/ structure
+seeds/            # shipped skill/agent seed assets
+scripts/          # repo-level helper scripts
+docs/             # human-facing documentation
+```
+
+## Runtime and toolchain
+
+- Bun `>= 1.3.14` is the installed CLI/MCP runtime and the canonical CI verification path. It is also the only supported storage runtime (`bun:sqlite`).
+- Node.js `>= 22` is development/build/test tooling for TypeScript, `node:test`, and selected helper scripts.
+- TypeScript is ESM/NodeNext and strict, with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. Prefer explicit `undefined` over loose optional properties.
+- Tests use the built-in `node:test` runner with `node:assert/strict`, not Jest/Vitest.
+
+Install dependencies with `bun install --frozen-lockfile` when reproducing CI. When `package.json` dependency specifiers change, refresh and review `bun.lock` intentionally. Use `bun run check:bun-lock` to detect drift without mutating `node_modules`.
+
+## Verification order
+
+CI runs the verification chain in this order:
+
+```bash
+bun install --frozen-lockfile
+bun run check:bun-lock
+bun run verify:typecheck
+bun run verify:test
+bun run verify:test:bun-storage
+bun run verify:bun-sqlite
+bun run verify:package       # which is bun run package:bun:evidence
+bun run package:bun:evidence -- --require-pass
+```
+
+The full chain is wrapped in `bun run verify`. For release-readiness, the package evidence run must pass explicitly with `--require-pass`.
+
+`bun run verify:bun-sqlite` is the SQLite runtime release gate. It copies the source migrations into a temporary directory, applies them against a temporary database, and checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup.
+
+## Product boundaries
+
+VGXNESS is a local-first CLI/MCP control plane. The same domain services should back CLI, TUI, and MCP. Avoid reimplementing workflow, setup, or storage rules in only one surface.
+
+The configurator/setup plane (rendering/installing provider config) is separate from the runtime control plane (executing SDD phases, recording runs, gating approvals). They are wired by services, not by side effects.
+
+## Safety conventions
+
+These rules are non-negotiable. The harness is loaded with capability; do not remove these guards.
+
+- Read-only/preview commands must stay non-mutating. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views must not write provider config or call providers.
+- Provider config writes require explicit consent (`--yes` or equivalent confirmed flow) plus backup/rollback behavior.
+- Do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys `sdd/{change}/{phase}`.
+- Human acceptance is distinct from artifact presence. Do not infer acceptance from generated content or saved drafts. The runtime rejects `acceptedBy.type !== 'human'`.
+- Workspace boundary denials cannot be relaxed by agent or subagent overrides. The policy evaluator uses `realpathSync` to defeat symlink escapes.
+- Secrets and external directory access deny by default. Redaction helpers in `src/code/reporting/redaction.ts` and `src/export/redaction.ts` are the only place secret-shaped values should be stripped.
+
+## Style
+
+- TypeScript strict, ESM/NodeNext, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`.
+- Prefer explicit `undefined` over loose optional properties. Use the existing `MemoryResult<T>` / `MemoryResult<...>` style for fallible operations instead of throwing across module boundaries.
+- Domain entities live in their module's `schema.ts`. Tool-facing payloads live in `src/mcp/schema.ts` (or a sibling) and are validated with `zod` before dispatch.
+- Tests are colocated by module under `test/`. Use `node:test` and `node:assert/strict`. Each test file should set up its own `MemoryDatabase` (see existing files for the pattern).
+- Public CLI/setup language is English unless existing docs explicitly say otherwise.
+
+## Doc-sync discipline
+
+The docs are the user-facing contract. When the code drifts, the docs must catch up — not the other way around.
+
+- When you add, rename, or remove an MCP tool, update `SUPPORTED_VGX_MCP_TOOL_NAMES` in `src/mcp/schema.ts` and the table in [MCP tools](./mcp.md). They must stay in sync.
+- When you add a new CLI command, document it in [CLI reference](./cli.md).
+- When you change a permission category, default, or phase mode, update [Safety model](./safety.md).
+- When you add a migration, append it to the table in [Storage](./storage.md).
+- When you add or change a provider, update [Providers](./providers.md) and the [Code runtime](./code-runtime.md) tool list.
+
+## Pull request process
+
+VGXNESS is shipped as a proprietary package. The npm publication step is a separate, explicit, human-approved process. PRs that change published artifacts must:
+
+1. Run `bun run verify` locally and confirm all steps pass.
+2. Include or update tests for any behavioral change.
+3. Update docs that reference the changed surface.
+4. Not change the publication path. `npm publish`, `bun publish`, registry dry-runs, provenance upload, release creation, and dist-tag mutation are not part of normal PR flow.
+5. Not change `engines.bun` or remove the `bin`/`files` whitelist without a separate, documented decision.
+
+PRs that touch safety gates, permission categories, default policies, the run lifecycle, or the SDD acceptance gate are reviewed by a maintainer who can answer "does this still match the safety model?" without consulting the diff. If you are unsure, open the PR as a draft and ask.
+
+## Commit conventions
+
+- Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, `build:`, `ci:`).
+- No `Co-Authored-By` lines for AI assistants. Do not add AI attribution to commits.
+- One logical change per commit. Squash fixups locally before pushing.
+
+## AI assistants in this repo
+
+`AGENTS.md` at the repository root carries the working instructions for AI assistants. The two non-negotiables are:
+
+- Do not write to `openspec/`.
+- Do not infer SDD acceptance from generated content. The runtime will reject it, but the rejection costs a run.

package/docs/glossary.md

@@ -0,0 +1,211 @@
+# Glossary
+
+Terms used across the VGXNESS docs and codebase. The product surface is small enough that most of these are first-class concepts in `src/` rather than incidental vocabulary.
+
+## Acceptance
+
+A human-only action that records explicit approval of a SDD phase artifact. `vgxness_sdd_accept_artifact` requires `acceptedBy.type === 'human'`; the runtime rejects agent or anonymous acceptance. Acceptance is distinct from artifact presence — saving a draft never implies acceptance.
+
+## Adapter
+
+A translator between VGXNESS's provider-neutral domain and a specific provider. The control plane uses renderers (OpenCode, JSON, Claude preview). The code runtime uses `CodeProviderAdapter` implementations (`openai-compatible`, `fake`).
+
+## Agent
+
+A provider-neutral definition of who executes work. Carries role, instructions, capabilities, model preference, permissions, and compatible workflows. Subagents are specialized agents intended for delegated, scoped work with constrained tools.
+
+## Approval record
+
+A first-class record linked to a permission-decision event. Created when a permission request resolves to `ask`; resolved once as `approved`, `rejected`, or `cancelled` with actor, reason, and timestamp. Approvals drive `resumeApprovedOperation(...)`.
+
+## Attempt
+
+A reserved operation execution linked to an approval. Attempts transition through `reserved` → `succeeded` | `failed` | `abandoned`. Multiple ordered attempts are allowed per approval, but only one is `reserved` at a time.
+
+## Blockers (SDD cockpit)
+
+Aggregated reasons a SDD phase is not ready. Kinds: `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. Surfaced through `vgxness_sdd_cockpit`.
+
+## Bun
+
+The canonical installed CLI/MCP runtime and verification path. Required `>= 1.3.14`. The only supported storage runtime (via `bun:sqlite`).
+
+## Canonical agent manifest
+
+The built-in, validated manifest that defines the manager agent and the SDD subagents (`vgxness-sdd-explore`, `vgxness-sdd-propose`, `vgxness-sdd-spec`, `vgxness-sdd-design`, `vgxness-sdd-tasks`, `vgxness-sdd-apply`, `vgxness-sdd-verify`, `vgxness-sdd-archive`, plus `init` and `onboard`). Lives in `src/agents/canonical-agent-manifest.ts`. `promptContractVersion` increments on breaking contract changes.
+
+## Change (SDD)
+
+The unit of SDD work. Identified by a project-scoped `change` id. Artifacts are stored under canonical topic keys `sdd/{change}/{phase}`.
+
+## Checkpoint
+
+A labeled, ordered JSON blob attached to a run that lets work resume. Append through `vgxness_run_checkpoint`. Checkpoints are part of the run; they are not the same as memory observations.
+
+## Cockpit
+
+A read-only SDD aggregate view. `vgxness_sdd_cockpit` returns per-phase status, blockers, and a recommended next action. The TUI should eventually mirror this surface.
+
+## Code runtime
+
+The native workspace runtime exposed through `vgxness code` (`inspect` / `plan` / `craft-preview` / `craft` / `sdd`). Provider-neutral; speaks to any OpenAI-compatible endpoint through `openai-compatible-provider-adapter.ts`.
+
+## Configurator plane
+
+The part of VGXNESS that renders provider-specific artifacts (OpenCode config, agent JSON) without mutating the registry. Separate from the runtime control plane.
+
+## Control plane
+
+The part of VGXNESS that owns workflow state, runs, approvals, checkpoints, and audit evidence. Exposed through CLI, TUI, and MCP.
+
+## Decision
+
+A permission resolution: `allow`, `ask`, or `deny`. For SDD-phase gating the matrix uses four modes: `allow`, `audit`, `require-preflight`, `deny`.
+
+## Dry-run
+
+A read-only preview. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views are dry-runs by contract — they must not write provider config or call providers.
+
+## Eval target
+
+A testable property of the harness. The 11 eval targets live in [Architecture](./architecture.md) and are covered by `node:test` files under `test/`.
+
+## Execution isolation plan
+
+A planned strategy for executing a reserved operation: `workspace`, `git-worktree`, or `process-sandbox`. Produced by `planExecutionIsolation(...)`. The actual executor is still test-only in v1.5.1.
+
+## Governance report
+
+A redacted, structured report over SDD state, runs, and approvals. Surfaced through `vgxness_governance_report`. Useful for review before promotion.
+
+## MCP
+
+Model Context Protocol. The agent-facing transport. VGXNESS exposes 38 typed tools over stdio through `vgxness mcp start`. The tool list lives in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`) and is documented in [MCP tools](./mcp.md).
+
+## Memory observation
+
+A durable record in the SQLite store. Identified by `id`; upserted by `topicKey`. Types: `architecture`, `decision`, `bugfix`, `pattern`, `config`, `discovery`, `learning`, `preference`, `manual`. Project or personal scope.
+
+## Natural-language planner
+
+The provider-agnostic front-door classifier for operator text. Maps an intent to exactly one preview flow: `direct`, `plan`, `sdd`, or `diagnose`. Non-executing by design.
+
+## OpenCode
+
+The primary supported provider for the control plane. The configurator renders OpenCode MCP config and manager/SDD agent definitions. Claude Code is preview/manual only.
+
+## Operation attempt
+
+See **Attempt**.
+
+## Payload mode
+
+A knob that controls how much context a payload returns. `compact` (default for the manager) keeps tokens bounded; `verbose` returns the full content. Applies to `vgxness_agent_activate`, `vgxness_skill_payload`, `vgxness_sdd_get_artifact`, `vgxness_sdd_list_artifacts`, `vgxness_governance_report`.
+
+## Pending approval
+
+An approval record that has not been resolved yet. Created when a permission request resolves to `ask`. Visible in the run details.
+
+## Permission
+
+A category of action. Categories: `read`, `edit`, `implementation-edit`, `spec-write`, `design-write`, `task-write`, `shell`, `test-run`, `install`, `network`, `git`, `git-write`, `memory`, `memory-write`, `external-directory`, `provider-tool`, `secrets`. See [Safety model](./safety.md).
+
+## Phase (SDD)
+
+A canonical stage in the SDD lifecycle: `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, `archive`. Each phase has prerequisites and an acceptance requirement.
+
+## Policy evaluator
+
+The function that resolves a permission request. Returns `allow`, `ask`, or `deny` with a reason. Conservative defaults; workspace boundary denials cannot be relaxed by agent overrides.
+
+## Preflight
+
+A permission decision plus execution isolation plan produced before a reserved operation. `vgxness_run_preflight` may create a pending approval when the decision is `ask`.
+
+## Project (scope)
+
+One of two memory scopes. `project` is repo-specific; `personal` is user-global. Scopes live in the same database, separated by columns.
+
+## Provider adapter
+
+See **Adapter**.
+
+## Readiness
+
+Whether a SDD phase can advance. Combines prerequisite artifacts, human acceptance of prerequisites, and aggregate blockers. Surfaced through `vgxness_sdd_ready`, `vgxness_sdd_get_readiness`, and `vgxness_sdd_cockpit`.
+
+## Redaction
+
+Stripping secret-shaped values before they leave the runtime. `redactSecrets`, `redactJson`, and `omitSensitiveCommandOutput` live in `src/code/reporting/redaction.ts` and `src/export/redaction.ts`.
+
+## Reserved attempt
+
+An operation attempt in the `reserved` state. Exclusive per approval. Finalized to `succeeded` or `failed` after the executor returns; recovery-only `abandoned` for stuck attempts.
+
+## Retry policy
+
+The policy that decides whether a new attempt is allowed after a prior one. `never`, `after-abandoned`, `after-failure`, `after-failure-or-abandoned`. Default is `never`. Evaluated by `vgxness_run_resume_gate`.
+
+## Run
+
+The auditable unit of execution. Has 8 statuses: `created`, `planned`, `running`, `needs-human`, `completed`, `failed`, `blocked`, `cancelled`. Carries events, checkpoints, approvals, and operation attempts.
+
+## Run snapshot export
+
+A versioned JSON package containing the full run, its events, checkpoints, approvals, and attempts. Useful for review and debugging. `RunSnapshotPackageV1`.
+
+## Scope
+
+`project` or `personal`. Memory, agents, skills, and manager profile overlays all carry a scope.
+
+## SDD
+
+Spec-Driven Development. The canonical workflow `explore → proposal → spec → design → tasks → apply-progress → verify → archive`. See [PRD](./prd.md) for the principles and [Architecture](./architecture.md) for the engine.
+
+## Session
+
+A scoped record of work in progress. Started with `vgxness_session_start`, appended to with `vgxness_session_append_activity`, closed with `vgxness_session_close`. The latest restorable session is read through `vgxness_session_restore` or, more reliably, `vgxness_context_cockpit`.
+
+## Skill
+
+A versioned, reusable knowledge/procedure that can be attached to an agent, workflow, phase, or provider adapter. Skill improvement proposals must be approved by a human before activation.
+
+## Skill improvement proposal
+
+A reviewable, versioned change to a skill. Goes through `draft` → `submitted` → `approved`/`rejected`/`cancelled` → `applied`. Only `approved` proposals can be applied.
+
+## SddCockpitBlocker
+
+A typed blocker surfaced by the SDD cockpit. Kinds: `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. See [Safety model](./safety.md) and [Architecture](./architecture.md).
+
+## SddPrerequisiteBlocker
+
+A typed blocker for a missing or unaccepted prerequisite phase. Reasons: `missing`, `draft`, `legacy`, `rejected`, `superseded`.
+
+## Subagent
+
+See **Agent**.
+
+## Topic key
+
+The durable upsert key for memory observations and SDD artifacts. For SDD, the canonical form is `sdd/{change}/{phase}`.
+
+## Trace event
+
+A structured event in a run's timeline. Kinds: `timeline`, `evidence`, `memory-operation`, `artifact-reference`, `tool-call`, `permission-decision`, `execution-plan`, `operation-execution`, `approval`, `verification`.
+
+## TUI
+
+Terminal UI. OpenTUI (`@opentui/core`) is the framework for the main menu and setup screens.
+
+## Verification plan
+
+A recommended set of verification steps for a change type. `vgxness_verification_plan` takes a `changeType` (`docs-only`, `test-only`, `cli`, `mcp`, `sdd-storage`, `provider-setup`, `package-release`, `workflow-runs`) and returns the recommended plan.
+
+## Worktree (planned)
+
+A planned execution isolation strategy. `git-worktree` plans produce a plan to mutate inside an isolated worktree; the actual worktree creation is follow-up.
+
+## Workspace boundary
+
+The set of paths inside `workspaceRoot`. The policy evaluator uses `realpathSync` to defeat symlink escapes and refuses to relax boundary denials.