vgxness 1.14.0 → 1.14.1

package/README.md

@@ -8,7 +8,7 @@ This package is proprietary software. The npm package ships inspectable JavaScri
 
 OpenCode is the primary supported provider. Claude setup support is secondary. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
 
-VGXNESS v1.10.x has a current project health audit describing the implemented CLI/MCP/SDD control plane, OpenCode health, known docs drift, interrupted runs, and the remaining execution/recovery gaps. See [Project health audit v1.10.x](./docs/project-health-audit-v1.10.x.md) for the current system snapshot; [v1.9.1](./docs/project-health-audit-v1.9.1.md) remains historical validation evidence for that release.
+VGXNESS v1.14.x has a current project health audit describing the implemented CLI/MCP/SDD control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps. See [Project health audit v1.14.x](./docs/project-health-audit-v1.14.x.md) for the current system snapshot; [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
 
 ## Requirements
 
@@ -256,6 +256,7 @@ Remove any user-global OpenCode/Claude config entries and local/global VGXNESS d
 ## More docs
 
 - [CLI reference](./docs/cli.md)
+- [Project health audit v1.14.x](./docs/project-health-audit-v1.14.x.md)
 - [Project health audit v1.10.x](./docs/project-health-audit-v1.10.x.md)
 - [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md)
 - [Architecture](./docs/architecture.md)

package/dist/skills/skill-resolver.js

@@ -100,8 +100,13 @@ export class SkillResolver {
         });
     }
     resolveAgent(input) {
-        if (input.agentId !== undefined)
-            return this.agents.getById(input.agentId);
+        if (input.agentId !== undefined) {
+            const byId = this.agents.getById(input.agentId);
+            if (byId.ok || input.project === undefined)
+                return byId;
+            const byName = this.agents.getByName(input.project, input.scope ?? 'project', input.agentId);
+            return byName.ok ? byName : byId;
+        }
         if (input.agentName === undefined)
             return ok(undefined);
         if (input.project === undefined)

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # vgxness Architecture
 
-> **Scope:** this document describes the current v1.10.x architecture as it is actually built. It is the source of truth for how the product works today, with the latest health snapshot captured in [Project health audit v1.10.x](./project-health-audit-v1.10.x.md). 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.
+> **Scope:** this document describes the current v1.14.x architecture as it is actually built. It is the source of truth for how the product works today, with the latest health snapshot captured in [Project health audit v1.14.x](./project-health-audit-v1.14.x.md). 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.
 
@@ -387,12 +387,13 @@ Skill improvement proposals are the current controlled foundation for self-impro
 CLI examples:
 
 ```bash
-vgxness skills register --project vgxness --name sdd-apply --description "Applies SDD tasks"
-vgxness 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
-vgxness skills attach --project vgxness --name sdd-apply --target-type workflow-phase --target-key sdd:apply
-vgxness skills resolve --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
-vgxness skills payload --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
-vgxness 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"
+vgxness skills get --project vgxness --name vgxness-sdd-apply
+vgxness skills resolve --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
+vgxness skills payload --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
+vgxness skills register --project vgxness --name team-review-guidance --description "Team-specific review guidance"
+vgxness skills add-version --project vgxness --name team-review-guidance --version 1.0.0 --source-kind inline --inline-metadata '{"content":"Check product risk, review size, and rollback notes."}' --activate
+vgxness skills attach --project vgxness --name team-review-guidance --target-type intent-signal --target-key review-size
+vgxness skills propose --project vgxness --name team-review-guidance --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Revised team guidance."}' --rationale "Repeated correction from trace"
 vgxness skills submit-proposal --proposal <proposal-id> --actor uziel
 vgxness skills approve-proposal --proposal <proposal-id> --actor uziel --reason "Reviewed diff"
 vgxness skills apply-proposal --proposal <proposal-id> --actor uziel
@@ -470,7 +471,7 @@ The envelope is always `installable:false` and `readOnly:true`. It does **not**
 
 ### 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.
+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 provider-native skill files; optional guidance should live in VGXNESS registry assets unless a future provider-native integration is explicitly designed.
 
 ## Run lifecycle
 

package/docs/cli.md

@@ -577,7 +577,7 @@ This seed file is repo-only in v1.3.0 package contents. If installed-package wor
 
 The command prints an `AgentSeedLoadSummary` JSON payload with `created`, `updated`, `agents`, `subagents`, and `warnings`. Re-running the same seed is safe: records are upserted by the current project, scope, and name, so existing seed records are updated in place instead of duplicated.
 
-The checked-in `vgxness-manager` and SDD subagents are self-contained: their seed instructions describe the MCP-first orchestration contract inline and do not require installing `~/.config/opencode/skills/sdd-*`. SDD skills can still be registered and attached as optional registry assets when a project wants extra reusable guidance.
+The checked-in `vgxness-manager` and SDD subagents are self-contained: their seed instructions describe the MCP-first orchestration contract inline and do not require external provider-native skill directories. SDD skills can still be registered and attached as optional VGXNESS registry assets when a project wants extra reusable guidance.
 
 Seed loading preserves user-created agents that are absent from the manifest. It only writes to the selected local registry database (`--db`, `VGXNESS_DB_PATH`, or the global default); it does **not** create `.opencode/`, `.claude/`, provider config, or user/global OpenCode configuration.
 
@@ -592,20 +592,18 @@ The render command returns preview artifacts only and keeps provider config unto
 
 ## Skill examples
 
-Register an optional provider-agnostic skill, add an active version, attach it to a workflow phase, and record a simple run outcome. These examples are registry-managed enhancements, not requirements for the checked-in OpenCode manager/subagents:
+Inspect the built-in VGXNESS registry/context skills and resolve the context that would be available to a workflow phase. These examples are registry-managed guidance only; they do not install provider-native OpenCode skills or write provider config:
 
 ```bash
-bun run cli:bun -- skills register --project vgxness --name sdd-apply --description "Applies focused SDD slices"
-bun run cli:bun -- 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
-bun run cli:bun -- skills attach --project vgxness --name sdd-apply --target-type workflow-phase --target-key sdd:apply
-bun run cli:bun -- skills record-usage --project vgxness --name sdd-apply --outcome helped --run-id <run-id> --target-type workflow-phase --target-key sdd:apply
+bun run cli:bun -- skills get --project vgxness --name vgxness-sdd-apply
+bun run cli:bun -- skills payload --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
 ```
 
 Resolve the skills that would be available to a runtime context:
 
 ```bash
-bun run cli:bun -- skills resolve --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
-bun run cli:bun -- skills resolve --agent apply-agent --project vgxness --phase apply --run <run-id> --record-usage selected
+bun run cli:bun -- skills resolve --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
+bun run cli:bun -- skills resolve --project vgxness --workflow plan --phase pr --intent-signals workflow-selection,pull-request --provider opencode
 ```
 
 `skills resolve` is read-only by default. It combines matching skill attachments plus the agent definition `skills` field, returns active/current versions only, and includes source metadata plus inline `summary`/`content` when available. It records `selected` or `injected` usage only when both `--run` and `--record-usage` are explicit.
@@ -619,10 +617,13 @@ bun run cli:bun -- skills status --project vgxness --scope project --provider op
 
 `skills status` prints deterministic JSON with `kind: "skills-status"` and `version: 1`. It includes project/scope/provider context, registry skill counts and current-version status, declared/resolved/missing skills for matching agents or subagents, resolver diagnostics, and safety markers. The command is read-only: it does not repair, install, or write provider configuration and does not record skill usage. A missing `--agent` match returns valid JSON with a warning diagnostic instead of crashing.
 
-Create and review a skill improvement proposal without activating it:
+Register and review an optional project-local registry skill without activating provider-native OpenCode skill loading:
 
 ```bash
-bun run cli:bun -- skills propose --project vgxness --name sdd-apply --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Updated skill body"}' --rationale "Repeated correction from trace" --source-signal '{"kind":"trace-failure"}'
+bun run cli:bun -- skills register --project vgxness --name team-review-guidance --description "Team-specific review guidance"
+bun run cli:bun -- skills add-version --project vgxness --name team-review-guidance --version 1.0.0 --source-kind inline --inline-metadata '{"content":"Check product risk, review size, and rollback notes."}' --activate
+bun run cli:bun -- skills attach --project vgxness --name team-review-guidance --target-type intent-signal --target-key review-size
+bun run cli:bun -- skills propose --project vgxness --name team-review-guidance --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Revised team guidance."}' --rationale "Repeated correction from trace" --source-signal '{"kind":"trace-failure"}'
 bun run cli:bun -- skills proposals --status draft
 bun run cli:bun -- skills get-proposal --proposal <proposal-id>
 ```
@@ -640,7 +641,7 @@ Rejected or cancelled proposals cannot be applied. These commands store reviewab
 Build an injection-ready payload without mutating provider config:
 
 ```bash
-bun run cli:bun -- skills payload --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
+bun run cli:bun -- skills payload --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
 ```
 
 `skills payload` resolves the same active skills and returns payload v1 JSON: skill identity/version, source kind, available content or an unavailable reason, attachment reasons, and ordering metadata. Inline `content` is included directly. Local `path` sources are loaded read-only only when they resolve inside the current workspace root. URL sources are never fetched in v1 and return `url_fetch_disabled`. The command does **not** write `.opencode/`, `.claude/`, provider prompts, or external skill files.
@@ -648,7 +649,7 @@ bun run cli:bun -- skills payload --agent apply-agent --project vgxness --workfl
 `skills get` returns the current version, all versions, attachments, and usage records:
 
 ```bash
-bun run cli:bun -- skills get --project vgxness --name sdd-apply
+bun run cli:bun -- skills get --project vgxness --name vgxness-sdd-apply
 bun run cli:bun -- skills list --project vgxness
 ```
 
@@ -676,7 +677,7 @@ Use `--file` when a definition has permissions, memory, workflows, skills, or ad
   "permissions": { "read": "allow", "edit": "ask", "shell": "ask" },
   "memory": { "scopes": ["project"] },
   "workflows": ["sdd"],
-  "skills": ["sdd-apply"],
+  "skills": ["vgxness-sdd-apply"],
   "adapters": { "opencode": { "model": "openai/gpt-5.5" } }
 }
 ```

package/docs/project-health-audit-v1.10.x.md

@@ -1,5 +1,7 @@
 # Auditoría de salud del proyecto VGXNESS v1.10.x
 
+> Historical snapshot: this document records the v1.10.x health review and should not be treated as current status. See [Project health audit v1.14.x](./project-health-audit-v1.14.x.md) for the current system snapshot.
+
 ## Resumen ejecutivo
 
 VGXNESS v1.10.x está en un punto avanzado como **CLI/MCP control plane local-first** para SDD, memoria, runs, permisos, agentes, skills y setup de OpenCode. La base de producto es sólida: hay workflow SDD canónico, storage SQLite local, superficies read-only/advisory, provider doctor, agent manifest canónico y verificación Bun-first.

package/docs/project-health-audit-v1.14.x.md

@@ -0,0 +1,79 @@
+# Auditoría de salud del proyecto VGXNESS v1.14.x
+
+## Resumen ejecutivo
+
+VGXNESS v1.14.x está avanzado como **CLI/MCP control plane local-first** para SDD, memoria, runs, permisos, agentes, skills y setup de OpenCode. La base de producto es sólida: el flujo SDD canónico existe como estado SQLite-backed, OpenCode es el provider primario, los drafts y la aceptación humana están separados, y la ruta oficial de verificación es Bun-first.
+
+No debe tratarse como “versión final cerrada” hasta resolver la brecha de ejecución/recovery productiva. El sistema gobierna, audita, planea y guía mejor de lo que ejecuta efectos reales de forma autónoma: el executor real, `resume-after-approval`, materialización de sandbox/worktree y evidencia integrada en cockpit siguen siendo trabajo planificado.
+
+Esta auditoría es una foto de release-readiness v1.14.x basada en inspección del repositorio, subauditorías internas y verificación local de release candidate. No publica artefactos ni sustituye la aprobación humana explícita de publicación.
+
+## Evidencia observada
+
+| Área | Evidencia | Estado |
+|---|---|---|
+| Package | `package.json` declara `version: 1.14.1` y expone los binarios `vgxness`/`vgx` desde `dist/cli/bun-bin.js`. | Implementado |
+| Release history | `CHANGELOG.md` contiene `v1.14.1 — 2026-06-17` para el cierre de release-readiness posterior al tag `v1.14.0`. | Implementado |
+| Runtime/tooling | `package.json` codifica la ruta oficial `bun run verify`: typecheck, tests Node, tests Bun storage-backed, Bun SQLite y evidencia de paquete. | Implementado |
+| Release candidate verification | La ruta completa `verify:typecheck`, `verify:test`, `verify:test:bun-storage`, `verify:bun-sqlite` y `package:bun:evidence -- --require-pass` pasó localmente; package evidence reportó `releaseReadiness.status: pass` y `publicationAttempted: false`. | Validado |
+| CI | `.github/workflows/node22.yml` ahora ejecuta también `bun run verify:test:bun-storage`, alineando el gate principal con `package.json`. | Alineado |
+| CLI/MCP | README y docs describen CLI para bootstrap/diagnóstico/recovery y MCP para trabajo diario dentro de OpenCode. | Implementado |
+| SDD | Fases canónicas `explore → proposal → spec → design → tasks → apply-progress → verify → archive`; aceptación humana separada de presencia de artifact. | Implementado |
+| Providers | OpenCode es primario; Claude es secundario/guarded; Antigravity/custom son placeholder/extensión. | Implementado con límites |
+| Code runtime | El runtime experimental `vgxness code` y la superficie principal OpenTUI están removidos temporalmente. | Fuera de release |
+| Docs | README, architecture, providers, roadmap y auditorías históricas apuntan a este snapshot v1.14.x como actual. | Alineado |
+
+## Estado por superficie
+
+### CLI y MCP
+
+La CLI está madura para setup, status, recuperación, SDD, runs, permisos, agentes, skills, MCP y verificación. La superficie MCP es la ruta diaria recomendada para trabajar desde OpenCode con subagentes SDD ocultos. Los comandos preview/status/plan mantienen el contrato no mutante respecto a provider config; las escrituras de config requieren consentimiento explícito.
+
+### SDD governance
+
+La fortaleza principal del producto es que SDD no depende solo de prompts: fases, artifacts, readiness, aceptación humana, runs y eventos viven como estado consultable. La aceptación humana sigue siendo un gate separado; guardar drafts no implica aceptación.
+
+### Release y paquete
+
+El release gate debe ser Bun-first:
+
+```bash
+bun run verify:typecheck
+bun run verify:test
+bun run verify:test:bun-storage
+bun run verify:bun-sqlite
+bun run package:bun:evidence -- --require-pass
+```
+
+CI debe permanecer alineado con esa ruta. La publicación sigue siendo una operación separada, explícita y humana; esta auditoría no aprueba ni intenta publicación.
+
+### Ejecución y recovery
+
+El mayor gap de producto sigue siendo operacional: `docs/roadmap.md` marca como pendiente el executor real, `resume-after-approval`, materialización sandbox/worktree y mejores resúmenes de evidencia de verificación. Hasta cerrar eso, VGXNESS es muy fuerte como control plane y guía de workflow, pero no como runtime autónomo final.
+
+## Riesgos principales
+
+| Riesgo | Impacto | Recomendación |
+|---|---|---|
+| Release tag pendiente | Riesgo de publicar contenido sin tag/release note correspondiente. | Taggear/publicar solo después de revisar diff final y con aprobación humana explícita. |
+| Execution/resume gap | El producto puede dejar al usuario en recuperación manual para runs complejos. | Priorizar executor real, checkpoints útiles y `resume-after-approval`. |
+| Cockpit sin evidencia rica | “Por qué está bloqueado” puede requerir inspección adicional. | Integrar pass/fail/skipped, timestamp y evidencia por fase. |
+| Provider wording drift | Usuarios pueden asumir paridad completa fuera de OpenCode. | Mantener OpenCode como primario y Claude/otros con límites explícitos. |
+| TUI/code-runtime removidos | Puede haber expectativas viejas de `vgxness code`. | Mantener docs claras: la ruta diaria es OpenCode + MCP; CLI es fallback/diagnóstico. |
+
+## Próximo paso recomendado
+
+Para cerrar un release candidate v1.14.x:
+
+1. Revisar el diff final y commit/tag de release si corresponde.
+2. Confirmar que CI reproduce la cadena oficial completa en la rama remota.
+3. No publicar hasta que la evidencia de paquete reporte `releaseReadiness.status: pass` y exista aprobación humana explícita.
+
+Para avanzar hacia “versión final” de producto, abrir un cambio SDD separado para **final-product readiness hardening** con foco en executor/recovery/cockpit evidence.
+
+## Fuera de alcance de esta auditoría
+
+- No se publicó ni se contactó un registry.
+- No se mutó provider config.
+- No se aceptó ningún artifact SDD.
+- No se creó tag de release.

package/docs/project-health-audit-v1.9.1.md

@@ -1,6 +1,6 @@
 # Auditoría de salud del proyecto VGXNESS v1.9.1
 
-> Historical snapshot: this document records validated v1.9.1 evidence and should not be treated as current v1.10.x status. See [Project health audit v1.10.x](./project-health-audit-v1.10.x.md) for the current system snapshot.
+> Historical snapshot: this document records validated v1.9.1 evidence and should not be treated as current status. See [Project health audit v1.14.x](./project-health-audit-v1.14.x.md) for the current system snapshot.
 
 ## Resumen v1.9.1
 

package/docs/providers.md

@@ -4,7 +4,7 @@ VGXNESS is provider-agnostic at the core: the registry stores provider-neutral d
 
 ## Status
 
-Current as of the v1.10.x documentation snapshot.
+Current as of the v1.14.x documentation snapshot.
 
 | Provider | Control plane | Workspace runtime | Notes |
 |---|---|---|---|

package/docs/roadmap.md

@@ -41,7 +41,7 @@ SQLite, scopes, migrations, and the run snapshot export are in.
 
 ## TUI
 
-The principal code surface is in via OpenTUI. The legacy interactive setup surfaces and dashboard directory are absent in the current tree.
+The previous principal OpenTUI code surface is temporarily unavailable. The legacy interactive setup surfaces and dashboard directory are absent in the current tree; future TUI work should be rebuilt around the current MCP/CLI control-plane boundaries rather than the removed runtime.
 
 - **TUI dashboard screen.** Real-time view of active runs, pending approvals, and SDD blockers. Should match the cockpit surface from MCP.
 - **TUI runs screen.** Run list, drill into a run, see events/approvals/attempts, with read-only safe actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {