@osovv/vv-opencode 0.35.15 → 0.35.17

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## <small>0.35.17 (2026-06-14)</small>
+
+### Summary
+
+This release improves the accuracy of automatically generated changelog summaries by feeding the full textual diff of each commit into the summary generation prompt, so the model can ground its output in the actual file changes rather than relying solely on commit titles and metadata. This means release notes are now more faithful to what was really modified, reducing the risk of invented or misleading descriptions in the changelog.
+
+* fix(release): include commit diffs in summaries ([f1c930c](https://github.com/osovv/vv-opencode/commit/f1c930c))
+
+## <small>0.35.16 (2026-06-14)</small>
+
+### Summary
+
+This release introduces lifecycle statuses for skills specs and plans, giving users clearer visibility into the state of their skill workflows—whether a spec is being drafted, reviewed, or finalized, and whether a plan is in progress, completed, or blocked—making it easier to track progress and identify next steps in skills-based automation.
+
+* feat(skills): add spec and plan lifecycle statuses ([5c7c095](https://github.com/osovv/vv-opencode/commit/5c7c095))
+* chore: add typecheck to lefthook pre-commit ([cca0f03](https://github.com/osovv/vv-opencode/commit/cca0f03))
+
 ## <small>0.35.15 (2026-06-14)</small>
 
 ### Summary

package/README.md

@@ -68,6 +68,8 @@ vv-implementer → vv-spec-reviewer → vv-code-reviewer
 Done
 ```
 
+Specs and plans use a top-level lifecycle status: `draft` while being written, `approved` after explicit user approval, and `applied` after successful execution. `vv-execute` archives applied artifacts by moving specs to `.vvoc/specs/archive/` and plans to `.vvoc/plans/archive/`.
+
 ### XML grep
 
 Plans and specs are XML documents, making every element grep-able:
@@ -89,7 +91,7 @@ grep '/\*\*' .vvoc/plans/*.xml
 grep '<component>' .vvoc/plans/*.xml
 ```
 
-All four skills are auto-triggered by `vv-controller` via its built-in `<skill_trigger_rule>` — no slash commands needed. The controller checks whether `vv-spec`, `vv-plan`, `vv-review`, or `vv-reflect` applies before routing any request.
+Managed skills are installed by `vvoc`. `vv-controller` explicitly routes `vv-spec`, `vv-plan`, and `vv-review`; `vv-execute` and `vv-reflect` are available as managed skills for plan execution and durable session memory.
 
 ---
 
@@ -100,7 +102,7 @@ Setting up OpenCode for serious daily work means juggling config files, agent pr
 **vv-opencode collapses that into a single `vvoc install`.** It owns the wiring so you don't have to:
 
 - **Six plugins, one entry** — all plugins are exported from a single pinned package entry
-- **Managed agent & skill system** — `vv-controller` auto-triggers `vv-spec`, `vv-plan`, `vv-review`, and `vv-reflect` skills before routing to domain-specialized subagents
+- **Managed agent & skill system** — `vv-controller` routes `vv-spec`, `vv-plan`, and `vv-review`; bundled managed skills also include `vv-execute` and `vv-reflect`
 - **Model roles & presets** — assign models to roles (`smart`, `fast`, `vision`, …) and switch provider presets with one command
 - **Security-first** — a `guardian` agent reviews permission requests, secrets are redacted from LLM-bound chat
 - **Stale-line-number defense** — hashline-backed `edit` prevents write-against-wrong-snapshot bugs
@@ -113,7 +115,7 @@ Setting up OpenCode for serious daily work means juggling config files, agent pr
 |---|---|
 | **Plugins** | 6 plugins in one pinned package entry — workflow orchestration, model roles, guardian, hashline edit, system context injection, secrets redaction |
 | **Agent System** | `vv-controller` routes work: direct for small changes, `investigator` for bugs, implementer+reviewer loop for risky work, analyst+architect for large features |
-| **Skills** | `vv-spec` interviews you and writes an XML spec; `vv-plan` maps the spec to interface contracts and acceptance criteria; `vv-review` runs a review-only workflow; `vv-reflect` preserves reusable session findings as repository memory — all auto-triggered |
+| **Skills** | `vv-spec` interviews you and writes an XML spec; `vv-plan` maps the spec to interface contracts and acceptance criteria; `vv-execute` runs approved plans; `vv-review` runs a review-only workflow; `vv-reflect` preserves reusable session findings as repository memory |
 | **Spec-to-Code Pipeline** | `vv-spec` → spec review → `vv-plan` → plan review → `vv-implementer` → code review. Three independent review gates cover requirements, contracts, and implementation |
 | **One-Click Setup** | `vvoc install` or `vvoc sync` bootstraps everything — config, agents, skills, prompts, presets |
 | **CLI Tooling** | 15+ commands: install, sync, status, doctor, role management, presets, guardian config, shell completion, upgrade |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.35.15",
+  "version": "0.35.17",
   "description": "Portable OpenCode workflow toolkit — 6 plugins, managed agents & skills, a spec-to-code pipeline, security, and the vvoc CLI.",
   "type": "module",
   "main": "./dist/index.js",

package/schemas/vvoc/v3.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.35.15/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.35.17/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/templates/skills/vv-execute/SKILL.md

@@ -24,6 +24,18 @@ Do not mutate files until the execution mode is explicit. In classic mode, deleg
   <command>sed -n '/&lt;meta&gt;/,/&lt;\/meta&gt;/p' PLAN_PATH</command>
   <purpose>Extract plan metadata: summary, waves, complexity</purpose>
 </helper>
+<helper name="plan-document-status">
+  <command>sed -n '1,20p' PLAN_PATH | grep '&lt;status&gt;'</command>
+  <purpose>Extract the top-level plan lifecycle status. Valid document statuses are draft, approved, applied.</purpose>
+</helper>
+<helper name="linked-spec">
+  <command>sed -n '1,20p' PLAN_PATH | grep '&lt;spec&gt;'</command>
+  <purpose>Extract the spec path linked from the plan.</purpose>
+</helper>
+<helper name="spec-document-status">
+  <command>sed -n '1,20p' SPEC_PATH | grep '&lt;status&gt;'</command>
+  <purpose>Extract the top-level linked spec lifecycle status. Valid document statuses are draft, approved, applied.</purpose>
+</helper>
 <helper name="architecture">
   <command>sed -n '/&lt;architecture&gt;/,/&lt;\/architecture&gt;/p' PLAN_PATH</command>
   <purpose>Extract full architecture section with modules, files, contracts</purpose>
@@ -82,7 +94,15 @@ Do not mutate files until the execution mode is explicit. In classic mode, deleg
 <step name="load-plan">Read plan.xml from .vvoc/plans/. Use list-tasks and count-tasks to understand scope. Use dependency-graph to determine execution order.</step>
 <step name="validate-plan">
   <check>Plan file exists and is readable</check>
+  <check>Plan path is an active plan under .vvoc/plans/ and not already under .vvoc/plans/archive/</check>
   <check>Plan contains &lt;plan&gt; root tag</check>
+  <check>Plan contains a non-empty top-level &lt;status&gt; whose value is approved</check>
+  <check>If the top-level plan status is draft, stop and ask the user to approve the plan first. Do not execute draft plans.</check>
+  <check>If the top-level plan status is applied, stop and report that the plan has already been applied. Do not re-execute applied plans.</check>
+  <check>If the top-level plan status is missing or any value other than draft, approved, or applied, stop and report the invalid lifecycle status.</check>
+  <check>Plan contains a non-empty &lt;spec&gt; path pointing to a readable active spec under .vvoc/specs/ and not under .vvoc/specs/archive/</check>
+  <check>The linked spec's top-level &lt;status&gt; is approved</check>
+  <check>If the linked spec status is draft, applied, missing, or invalid, stop and report that vv-execute requires an approved active spec.</check>
   <check>Plan contains &lt;tasks&gt; section with at least one &lt;task&gt;</check>
   <check>Each task has non-empty &lt;id&gt;, &lt;title&gt;, and &lt;file&gt;</check>
   <check>Each task has &lt;snippet&gt; (may be empty but must exist)</check>
@@ -283,11 +303,16 @@ Inline mode is allowed only while the work remains clear, bounded, and low-risk.
 </model-selection>
 
 <completion>
+<step name="prepare-archive">After all tasks are complete, all required verification has passed, and all required task/wave commits are complete, prepare archival before reporting completion. Create .vvoc/specs/archive/ and .vvoc/plans/archive/ if needed. Resolve destination paths from the basenames of the active spec and plan. Never clobber existing archive files; if a destination already exists, append a timestamp suffix before the .xml extension.</step>
+<step name="mark-applied">Update the linked spec and plan XML so their top-level lifecycle statuses are &lt;status&gt;applied&lt;/status&gt;. Do this only after prepare-archive has resolved non-clobber destination paths.</step>
+<step name="archive-artifacts">Move the applied spec from .vvoc/specs/ to .vvoc/specs/archive/ and the applied plan from .vvoc/plans/ to .vvoc/plans/archive/. If either move fails, stop and report the exact source and destination paths; do not claim execution is complete.</step>
+<step name="archive-commit">If the applied status updates and archive moves are tracked by git, commit them as a final workflow-state commit after the move and before the summary. Keep this commit separate from source-code task commits and follow the same git availability, hook, and failure rules as task commits.</step>
 <step name="summary">Report to the user: selected execution mode, which tasks were completed, how many files were created/modified, and whether all acceptance criteria passed.</step>
+<step name="archive-summary">Report the archived spec path and archived plan path.</step>
 <step name="next">Ask the user: would you like a review? (vv-review can check the implementation against the spec).</step>
 </completion>
 
 <task>
-Your current task is the ongoing user request. Read the plan.xml from the path the user provided, validate its structure, assess execution complexity, and ensure the user explicitly chooses classic or inline mode unless they already specified one. Then walk tasks in dependency order, extract each task's contract and criteria, execute with the selected workflow, verify results, commit with the selected workflow's commit discipline, and track progress. Use the grep helpers to navigate the plan.
+Your current task is the ongoing user request. Read the plan.xml from the path the user provided, validate its structure and lifecycle status, verify the plan is approved, verify the linked active spec exists and is approved, assess execution complexity, and ensure the user explicitly chooses classic or inline mode unless they already specified one. Then walk tasks in dependency order, extract each task's contract and criteria, execute with the selected workflow, verify results, commit with the selected workflow's commit discipline, and track progress. After all tasks and required commits are complete, mark the linked spec and plan as applied, move them to .vvoc/specs/archive/ and .vvoc/plans/archive/ without clobbering existing files, and report the archive paths. Use the grep helpers to navigate the plan.
 </task>
 </skill>

package/templates/skills/vv-plan/SKILL.md

@@ -15,6 +15,7 @@ You are the vv-plan skill. Your job is to take an approved spec and write an imp
 
 <prerequisites>
 <rule>An approved spec MUST exist at .vvoc/specs/ before planning begins. Read the spec file in full.</rule>
+<rule>The spec's top-level &lt;status&gt; MUST be approved. If the status is draft, missing, applied, or any other value, stop and tell the user the spec must be explicitly approved before planning.</rule>
 <rule>If no spec exists, stop and tell the user to invoke vv-spec first.</rule>
 <rule>Do not reinterpret or expand the spec. The plan implements ONLY what the spec describes.</rule>
 </prerequisites>
@@ -28,9 +29,11 @@ You are the vv-plan skill. Your job is to take an approved spec and write an imp
 
 <plan_document_format>
 <rule>Load the plan template from references/plan-template.xml. Fill every element.</rule>
+<rule>The top-level &lt;status&gt; element is the plan lifecycle status and MUST be one of: draft, approved, applied.</rule>
+<rule>When first saving the plan, set the top-level status to &lt;status&gt;draft&lt;/status&gt;. Only change it to approved after the user explicitly reads/reviews and approves the final plan. Never set the top-level status to applied yourself; applied is reserved for vv-execute after successful execution.</rule>
 <rule>The plan contains two major sections: architecture (modules, contracts, dependencies) and tasks (implementation steps with code snippets).</rule>
 <rule>Architecture section uses child tags: module, name, purpose, file (path, role), contract, depends_on (module).</rule>
-<rule>Tasks use child tags: id (T-NNN pattern), title, file, status, description, depends_on (task_id), snippet (CDATA), acceptance (criterion), verification (command).</rule>
+<rule>Tasks use child tags: id (T-NNN pattern), title, file, status, description, depends_on (task_id), snippet (CDATA), acceptance (criterion), verification (command). Task-level &lt;status&gt; values are separate from the top-level plan lifecycle status and may remain pending until execution updates them.</rule>
 <rule>Every XML element is named for grep extraction. Use: `grep '<id>T-' plan.xml` to list tasks, `grep '<criterion>' plan.xml` for all criteria, `grep '<task_id>' plan.xml` for dependency graph.</rule>
 <location>Save to .vvoc/plans/YYYY-MM-DD-&lt;feature-name&gt;-plan.xml</location>
 </plan_document_format>
@@ -147,14 +150,17 @@ export type CacheStoreOptions = {
 </self_review>
 
 <execution_handoff>
-<rule>Save the plan to .vvoc/plans/YYYY-MM-DD-&lt;feature-name&gt;-plan.xml</rule>
-<rule>After saving, present the user with two execution options:</rule>
+<rule>Save the plan to .vvoc/plans/YYYY-MM-DD-&lt;feature-name&gt;-plan.xml with top-level status draft.</rule>
+<rule>After saving, present the plan file path and ask the user to read/review the plan and explicitly approve it. Do NOT offer execution options until the user approves the plan.</rule>
+<rule>If the user requests changes, keep the plan status as draft, make the changes, re-run self-review, save the updated plan, and ask for approval again.</rule>
+<rule>After explicit user approval, update the saved plan file so the top-level status is &lt;status&gt;approved&lt;/status&gt;.</rule>
+<rule>After the saved plan status is approved, present the user with two execution options:</rule>
 <option name="workflow">Workflow tracked loop (recommended) — vv-implementer executes tasks, followed by vv-spec-reviewer and vv-code-reviewer. Uses work_item_open/close for each implementation wave.</option>
 <option name="manual">Manual execution — the user or another agent executes tasks step by step following the plan directly.</option>
 <rule>Wait for the user's choice. Do NOT start implementation.</rule>
 </execution_handoff>
 
 <task>
-Your current task is the ongoing user request. Read the approved spec at .vvoc/specs/, load the plan template from references/plan-template.xml, map the architecture (modules, contracts, dependencies), write detailed tasks with code snippets in CDATA, apply self-review, save the plan as XML, and offer execution options.
+Your current task is the ongoing user request. Read the approved spec at .vvoc/specs/ and verify its top-level status is approved. Load the plan template from references/plan-template.xml, map the architecture (modules, contracts, dependencies), write detailed tasks with code snippets in CDATA, apply self-review, save the plan as XML with top-level status draft, ask the user to read/review and explicitly approve the plan, update the saved plan status to approved after approval, and only then offer execution options.
 </task>
 </skill>

package/templates/skills/vv-plan/references/plan-template.xml

@@ -1,7 +1,7 @@
 <plan>
   <spec></spec>
   <created></created>
-  <status>pending</status>
+  <status>draft</status>
 
   <meta>
     <summary></summary>

package/templates/skills/vv-spec/SKILL.md

@@ -46,6 +46,8 @@ UX cues (roadmap, progress markers, depth estimates, checkpoints) are TRANSPAREN
 <spec_document_format>
 <rule>Load the spec template from references/spec-template.xml. Fill every element with the decisions confirmed during the interview.</rule>
 <rule>Do not invent new elements beyond what the template defines. The template IS the contract.</rule>
+<rule>The top-level &lt;status&gt; element is the document lifecycle status and MUST be one of: draft, approved, applied.</rule>
+<rule>When first saving the spec, set &lt;status&gt;draft&lt;/status&gt;. Only change it to approved after the user explicitly approves the final spec. Never set applied yourself; applied is reserved for vv-execute after the approved plan has been fully executed.</rule>
 <location>Save to .vvoc/specs/YYYY-MM-DD-&lt;name&gt;.xml</location>
 </spec_document_format>
 
@@ -60,15 +62,16 @@ UX cues (roadmap, progress markers, depth estimates, checkpoints) are TRANSPAREN
 <user_approval_gate>
 <rule>Present the spec document to the user.</rule>
 <rule>Wait for the user to review it. Do NOT proceed to planning until the user explicitly approves.</rule>
-<rule>If the user requests changes, make them and re-present the spec. Re-run self-review after changes.</rule>
+<rule>If the user requests changes, keep the document status as draft, make the changes, and re-present the spec. Re-run self-review after changes.</rule>
+<rule>After explicit user approval, update the saved spec file so the top-level status is &lt;status&gt;approved&lt;/status&gt;, then present the approved document state.</rule>
 </user_approval_gate>
 
 <handoff>
-<rule>After approval, tell the user the spec is ready and that the next step is to invoke the vv-plan skill to create the implementation plan.</rule>
+<rule>After approval and after the saved file status is approved, tell the user the spec is ready and that the next step is to invoke the vv-plan skill to create the implementation plan.</rule>
 <rule>Do NOT invoke vv-plan yourself. Wait for the user.</rule>
 </handoff>
 
 <task>
-Your current task is the ongoing user request. Walk the decision tree relentlessly — one branch at a time. Propose approaches, present a design section by section, get approval at each stage. Load the spec template from references/spec-template.xml and fill every element with confirmed decisions. Save to .vvoc/specs/ as XML. Stop before any implementation or planning.
+Your current task is the ongoing user request. Walk the decision tree relentlessly — one branch at a time. Propose approaches, present a design section by section, get approval at each stage. Load the spec template from references/spec-template.xml and fill every element with confirmed decisions. Save to .vvoc/specs/ as XML with document status draft. After explicit user approval, update the saved spec status to approved. Stop before any implementation or planning.
 </task>
 </skill>

package/templates/skills/vv-spec/references/spec-template.xml

@@ -1,4 +1,5 @@
 <spec>
+  <status>draft</status>
   <goal></goal>
   <architecture></architecture>
   <tech-stack></tech-stack>