@osovv/vv-opencode 1.3.6-rc.6 → 1.3.6-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "1.3.6-rc.6",
+  "version": "1.3.6-rc.7",
   "description": "An opinionated agentic development layer for OpenCode — spec-first when it matters, review-driven execution, portable model roles, safer tools, and long-run safety.",
   "type": "module",
   "main": "./dist/index.js",
@@ -85,6 +85,10 @@
     "./plugins/peak-hours": {
       "types": "./dist/plugins/peak-hours/index.d.ts",
       "import": "./dist/plugins/peak-hours/index.js"
+    },
+    "./plugins/spec-guard": {
+      "types": "./dist/plugins/spec-guard/index.d.ts",
+      "import": "./dist/plugins/spec-guard/index.js"
     }
   },
   "scripts": {
@@ -97,7 +101,7 @@
     "grace:check": "bun scripts/check-grace-markup.ts",
     "test": "bun test",
     "check": "bun run typecheck && bun run lint && bun run fmt:check && bun run grace:check && bun test",
-    "pack:check": "bun run build && bun -e \"const root = await import('./dist/index.js'); if (!('GuardianPlugin' in root)) throw new Error('dist root export missing GuardianPlugin'); if (!('HashlineEditPlugin' in root)) throw new Error('dist root export missing HashlineEditPlugin'); if (!('ModelRolesPlugin' in root)) throw new Error('dist root export missing ModelRolesPlugin'); if (!('SystemContextInjectionPlugin' in root)) throw new Error('dist root export missing SystemContextInjectionPlugin'); if (!('WorkflowPlugin' in root)) throw new Error('dist root export missing WorkflowPlugin'); if (!('SecretsRedactionPlugin' in root)) throw new Error('dist root export missing SecretsRedactionPlugin'); if (!('WebToolsPlugin' in root)) throw new Error('dist root export missing WebToolsPlugin'); if (!('AnalyticsPlugin' in root)) throw new Error('dist root export missing AnalyticsPlugin'); if (!('PeakHoursPlugin' in root)) throw new Error('dist root export missing PeakHoursPlugin'); const tui = await import('./dist/tui.js'); if (!tui.default || typeof tui.default.tui !== 'function') throw new Error('dist TUI export missing default tui module'); await import('./dist/plugins/guardian/index.js'); await import('./dist/plugins/hashline-edit/index.js'); await import('./dist/plugins/model-roles/index.js'); await import('./dist/plugins/system-context-injection/index.js'); await import('./dist/plugins/workflow/index.js'); await import('./dist/plugins/secrets-redaction/index.js'); await import('./dist/plugins/web-tools/index.js'); await import('./dist/plugins/analytics/index.js'); await import('./dist/plugins/peak-hours/index.js')\" && npm pack --dry-run",
+    "pack:check": "bun run build && bun -e \"const root = await import('./dist/index.js'); if (!('GuardianPlugin' in root)) throw new Error('dist root export missing GuardianPlugin'); if (!('HashlineEditPlugin' in root)) throw new Error('dist root export missing HashlineEditPlugin'); if (!('ModelRolesPlugin' in root)) throw new Error('dist root export missing ModelRolesPlugin'); if (!('SystemContextInjectionPlugin' in root)) throw new Error('dist root export missing SystemContextInjectionPlugin'); if (!('WorkflowPlugin' in root)) throw new Error('dist root export missing WorkflowPlugin'); if (!('SecretsRedactionPlugin' in root)) throw new Error('dist root export missing SecretsRedactionPlugin'); if (!('WebToolsPlugin' in root)) throw new Error('dist root export missing WebToolsPlugin'); if (!('AnalyticsPlugin' in root)) throw new Error('dist root export missing AnalyticsPlugin'); if (!('PeakHoursPlugin' in root)) throw new Error('dist root export missing PeakHoursPlugin'); if (!('SpecGuardPlugin' in root)) throw new Error('dist root export missing SpecGuardPlugin'); const tui = await import('./dist/tui.js'); if (!tui.default || typeof tui.default.tui !== 'function') throw new Error('dist TUI export missing default tui module'); await import('./dist/plugins/guardian/index.js'); await import('./dist/plugins/hashline-edit/index.js'); await import('./dist/plugins/model-roles/index.js'); await import('./dist/plugins/system-context-injection/index.js'); await import('./dist/plugins/workflow/index.js'); await import('./dist/plugins/secrets-redaction/index.js'); await import('./dist/plugins/web-tools/index.js'); await import('./dist/plugins/analytics/index.js'); await import('./dist/plugins/peak-hours/index.js'); await import('./dist/plugins/spec-guard/index.js')\" && npm pack --dry-run",
     "tui:local": "bun scripts/tui-local.ts",
     "release:check": "bun scripts/release-check.ts",
     "release:bump": "bun scripts/release-bump.ts",

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@1.3.6-rc.6/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@1.3.6-rc.7/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",
@@ -393,11 +393,28 @@
                       }
                     }
                   },
-                  "required": [
-                    "windows"
-                  ],
-                  "additionalProperties": false
-                }
+                   "required": [
+                     "windows"
+                   ],
+                   "additionalProperties": false
+                 }
+               }
+             },
+             "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "description": "spec-guard plugin entry: enabled plus lint enforcement mode warn or enforce.",
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "mode": {
+                "type": "string",
+                "enum": [
+                  "warn",
+                  "enforce"
+                ]
               }
             },
             "additionalProperties": false

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

@@ -38,11 +38,15 @@ Do not mutate files until the execution mode is explicit. In classic mode, deleg
 </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>
+  <purpose>Extract full architecture section with components, files, contracts</purpose>
 </helper>
 <helper name="module-list">
-  <command>sed -n '/&lt;architecture&gt;/,/&lt;\/architecture&gt;/p' PLAN_PATH | grep '&lt;name&gt;'</command>
-  <purpose>List all module names</purpose>
+  <command>grep '&lt;COMPONENT-' PLAN_PATH</command>
+  <purpose>List all architecture component identities (COMPONENT-UPPER-SLUG element names, mirrored from spec.xml)</purpose>
+</helper>
+<helper name="extract-component">
+  <command>sed -n '/&lt;COMPONENT-UPPER-SLUG&gt;/,/&lt;\/COMPONENT-UPPER-SLUG&gt;/p' PLAN_PATH</command>
+  <purpose>Extract one full architecture component by slug (replace COMPONENT-UPPER-SLUG with the actual element name, e.g. COMPONENT-CACHE-STORE)</purpose>
 </helper>
 <helper name="list-tasks">
   <command>grep '&lt;TASK-T-' PLAN_PATH</command>
@@ -107,6 +111,7 @@ Do not mutate files until the execution mode is explicit. In classic mode, deleg
   <check>Each task element name matches the TASK-T-NNN pattern and the task has non-empty &lt;title&gt; and &lt;file&gt;. There is no child id element — identity lives in the element name.</check>
   <check>Each task has &lt;snippet&gt; (may be empty but must exist)</check>
   <check>Each task has &lt;acceptance&gt; with at least one &lt;criterion&gt;</check>
+  <check>Plan architecture components use COMPONENT-UPPER-SLUG element names and every component exists in the linked spec's components section — plan components are a subset of spec components</check>
   <action>If any check fails, stop and report the issue with line numbers. Do not proceed with broken plan.</action>
 </step>
 <step name="assess-complexity">

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

@@ -34,13 +34,13 @@ You are the vv-plan skill. Your job is to take an approved spec and write an imp
 <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>The plan contains two major sections: architecture (components, contracts, dependencies) and tasks (implementation steps with code snippets).</rule>
+<rule>Architecture maps the spec's components. Each architecture element reuses the exact COMPONENT-UPPER-SLUG identity declared in spec.xml: &lt;COMPONENT-CACHE-STORE&gt;…&lt;/COMPONENT-CACHE-STORE&gt;. Plan components are always a subset of spec components — a plan module without a spec component does not exist. Architecture child tags: name (display name from the spec), purpose, file (path, role), contract, depends_on (bare component slug). Do NOT add a child id element.</rule>
 <rule>Tasks are grouped into wave elements whose identity is the element name: &lt;WAVE-1&gt;, &lt;WAVE-2&gt;, … Each wave contains a &lt;goal&gt; and its tasks.</rule>
 <rule>A task's identity is its element name in the TASK-T-NNN pattern: &lt;TASK-T-001&gt;…&lt;/TASK-T-001&gt;. The identity repeats on both boundaries so long blocks stay addressable. Tasks use child tags: title, file, status, description, depends_on (task_id), snippet (CDATA), acceptance (criterion), verification (command). Do NOT add a child id element — the element name is the single authoritative identity. 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 '&lt;TASK-T-' plan.xml` to list tasks, `grep '&lt;criterion&gt;' plan.xml` for all criteria, `grep '&lt;task_id&gt;' plan.xml` for dependency graph.</rule>
+<rule>Every XML element is named for grep extraction. Use: `grep '&lt;TASK-T-' plan.xml` to list tasks, `grep '&lt;criterion&gt;' plan.xml` for all criteria, `grep '&lt;task_id&gt;' plan.xml` for dependency graph, `grep '&lt;COMPONENT-' plan.xml` for the component map.</rule>
 <rule>Populate the &lt;spec&gt; element with the path to the spec.xml this plan implements.</rule>
-<rule>If a design-context.xml was found and read as explanatory context, populate the &lt;design-context&gt; element with the path to design-context.xml so execution tools and reviewers can locate it.</rule>
+<rule>If a design-context.xml was found and read as explanatory context, populate the &lt;design_context&gt; element with the path to design-context.xml so execution tools and reviewers can locate it.</rule>
 <location>Save plan.xml as a sibling of spec.xml in the same spec package directory: .vvoc/specs/&lt;id&gt;/plan.xml</location>
 </plan_document_format>
 
@@ -142,7 +142,7 @@ export type CacheStoreOptions = {
 <forbidden>XML attributes in any tag — use child elements only</forbidden>
 <forbidden>Code outside CDATA — all snippets must be wrapped in CDATA sections</forbidden>
 <forbidden>Numbered criterion tags — use plain &lt;criterion&gt;, not numbered variants</forbidden>
-<forbidden>Generic &lt;task&gt; or &lt;wave&gt; elements with child id/num elements — identity belongs in the element name: &lt;TASK-T-NNN&gt;, &lt;WAVE-N&gt;</forbidden>
+<forbidden>Generic &lt;task&gt;, &lt;wave&gt;, or &lt;module&gt; elements with child id/num elements — identity belongs in the element name: &lt;TASK-T-NNN&gt;, &lt;WAVE-N&gt;, &lt;COMPONENT-UPPER-SLUG&gt;</forbidden>
 </no_placeholders>
 
 <self_review>
@@ -152,7 +152,7 @@ export type CacheStoreOptions = {
 <check>Type consistency: Do types, signatures, and property names match across tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.</check>
 <rule>Fix issues inline as you find them. No second review pass needed — just fix and continue.</rule>
 <check>Format compliance: Are there zero XML attributes? Is every snippet in CDATA? Is every task a &lt;TASK-T-NNN&gt; element with identity in the element name and no child id element?</check>
-<check>Architecture presence: Does the plan have an architecture section with modules, contracts, and dependency graph?</check>
+<check>Architecture presence: Does the plan have an architecture section with components, contracts, and dependency graph? Does every &lt;COMPONENT-UPPER-SLUG&gt; element exist in the spec's components section — plan components are a subset of spec components?</check>
 </self_review>
 
 <execution_handoff>
@@ -167,6 +167,6 @@ export type CacheStoreOptions = {
 </execution_handoff>
 
 <task>
-Your current task is the ongoing user request. Read the approved spec at .vvoc/specs/&lt;id&gt;/spec.xml and verify its top-level status is approved. Check whether a sibling design-context.xml exists; if so, read it as explanatory context only (it does NOT override spec.xml). Load the plan template from references/plan-template.xml, populate &lt;spec&gt; and optionally &lt;design-context&gt; paths, map the architecture (modules, contracts, dependencies), write detailed tasks with code snippets in CDATA, apply self-review, save the plan as .vvoc/specs/&lt;id&gt;/plan.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.
+Your current task is the ongoing user request. Read the approved spec at .vvoc/specs/&lt;id&gt;/spec.xml and verify its top-level status is approved. Check whether a sibling design-context.xml exists; if so, read it as explanatory context only (it does NOT override spec.xml). Load the plan template from references/plan-template.xml, populate &lt;spec&gt; and optionally &lt;design_context&gt; paths, map the architecture (spec components as COMPONENT-UPPER-SLUG elements, contracts, dependencies), write detailed tasks with code snippets in CDATA, apply self-review, save the plan as .vvoc/specs/&lt;id&gt;/plan.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,6 +1,6 @@
 <plan>
   <spec></spec>
-  <design-context></design-context>  <!-- optional, populated when sibling file exists -->
+  <design_context></design_context>  <!-- optional, populated when sibling file exists -->
   <created></created>
   <status>draft</status>
 
@@ -12,7 +12,14 @@
   </meta>
 
   <architecture>
-    <module>
+    <!--
+      Architecture maps the spec's components. Each element reuses the
+      exact COMPONENT-UPPER-SLUG identity declared in spec.xml — plan
+      components are always a subset of spec components. The child
+      <name> element repeats the spec's display name. depends_on holds
+      bare component slugs declared in this plan or the spec.
+    -->
+    <COMPONENT-EXAMPLE>
       <name></name>
       <purpose></purpose>
       <file>
@@ -21,10 +28,8 @@
       </file>
       <contract>
       </contract>
-      <depends_on>
-        <module></module>
-      </depends_on>
-    </module>
+      <depends_on></depends_on>
+    </COMPONENT-EXAMPLE>
   </architecture>
 
   <tasks>

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

@@ -25,11 +25,11 @@ UX cues (roadmap, progress markers, depth estimates, checkpoints) are TRANSPAREN
 <principle>Understand the full landscape: purpose, constraints, success criteria, non-goals, edge cases, existing code patterns.</principle>
 <principle>When the decision tree reaches a fork (2-3 viable approaches), present all options with trade-offs. Lead with your recommendation and explain why. The user picks one — that closes the fork and the tree continues from that branch.</principle>
 <principle>When presenting design sections, do it one section at a time. After each section: "Does this look right?" If yes, move to the next. If no, resolve concerns before continuing.</principle>
-<principle>Cover every section of the spec template: goal, architecture, tech-stack, components, data-flow, error-handling, testing, non-goals. The roadmap shown at the start IS the coverage checklist. A section is "closed" only when its template element is fully decidable.</principle>
+<principle>Cover every section of the spec template: goal, architecture, tech_stack, components, data_flow, error_handling, testing, non_goals. The roadmap shown at the start IS the coverage checklist. A section is "closed" only when its template element is fully decidable.</principle>
 <principle>YAGNI ruthlessly: prune dead branches — remove unnecessary features from every approach.</principle>
 <principle>After design is confirmed, synthesize the spec yourself. You are the expensive model — deep analysis and architectural design are your responsibility, not a subagent's.</principle>
 <principle>Maintain a structured internal decision/rationale ledger during the interview. For each decision point, track: the decision, options considered, chosen option, rationale, rejected alternatives (with reasons), and any assumptions, deferred decisions, or revisit triggers. This ledger is the raw material for design-context.xml — it is synthesized from curated decisions, not reconstructed from conversation memory.</principle>
-<principle>Open the interview with a DECISION-TREE ROADMAP: show the spec template sections (goal, architecture, tech-stack, components, data-flow, error-handling, testing, non-goals) AND the major forks that may arise within each. State traversal order (highest-impact first). The purpose is predictability of the full landscape, not brevity — the user is working, so a large honest surface is welcome. Note the tree is dynamic: the branch actually taken depends on answers, but every reachable fork is shown up front.</principle>
+<principle>Open the interview with a DECISION-TREE ROADMAP: show the spec template sections (goal, architecture, tech_stack, components, data_flow, error_handling, testing, non_goals) AND the major forks that may arise within each. State traversal order (highest-impact first). The purpose is predictability of the full landscape, not brevity — the user is working, so a large honest surface is welcome. Note the tree is dynamic: the branch actually taken depends on answers, but every reachable fork is shown up front.</principle>
 <principle>Mark the CURRENT SECTION on every question message (a short header). The user must always know their location in the tree. This reduces disorientation in long interviews; it does not skip content.</principle>
 <principle>After the first substantive exchange, give an HONEST DEPTH ESTIMATE (approximate decision points remaining). If the estimate is high (roughly 12–15+), do NOT shorten the interview. Surface it as a signal that the prompt/context needs upgrading: offer the user ways to provide richer context up front (existing PRD, requirements doc, reference project, voice description), or propose decomposition into sub-projects. A large estimate means MORE context, not fewer questions.</principle>
 <principle>After closing each section, post a ONE-LINE RECAP of the decisions made in it, then show what sections remain. This is a coherence checkpoint — every branch inside the section was already walked to its leaf, so the recap confirms fixation rather than skipping deliberation. It lets the user catch a misunderstanding immediately instead of discovering it in the final spec.</principle>
@@ -46,7 +46,9 @@ 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>Do not invent new elements beyond what the template defines. The template IS the contract. Field names use snake_case only.</rule>
+<rule>A component's identity is its element name in the COMPONENT-UPPER-SLUG pattern: &lt;COMPONENT-CACHE-STORE&gt;…&lt;/COMPONENT-CACHE-STORE&gt;. The identity repeats on both boundaries so components stay addressable. Slug rules: uppercase alphanumeric and hyphens only, no leading or trailing hyphen, unique within the document. Derive the slug from the component's display name. The child &lt;name&gt; element holds the human-readable display name. Do NOT add a child id element — the element name is the single authoritative identity.</rule>
+<rule>Component references use bare slugs: each &lt;depends_on&gt; element contains exactly one component slug declared elsewhere in the same components section. Never reference a component by prose name.</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>Canonical layout — all artifacts for one feature live in a single spec package directory:</location>

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

@@ -40,11 +40,11 @@
     </assumption>
   </assumptions>
   <deferred>
-    <item>
+    <deferred_decision>
       <decision></decision>
       <why_deferred></why_deferred>
       <revisit_trigger></revisit_trigger>
-    </item>
+    </deferred_decision>
   </deferred>
   <scenarios>
     <scenario>

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

@@ -2,21 +2,29 @@
   <status>draft</status>
   <goal></goal>
   <architecture></architecture>
-  <tech-stack></tech-stack>
+  <tech_stack></tech_stack>
   <components>
-    <component>
+    <!--
+      Each component's identity is its element name: COMPONENT-UPPER-SLUG.
+      Slug rules: uppercase alphanumeric and hyphens only, must not start
+      or end with a hyphen, unique within this document. Derive the slug
+      from the component's display name (for example "Cache Store" ->
+      COMPONENT-CACHE-STORE). References (depends_on) use the bare slug.
+      Keep the child <name> element as the human-readable display name.
+    -->
+    <COMPONENT-EXAMPLE>
       <name></name>
       <responsibility></responsibility>
-      <depends-on></depends-on>
-    </component>
+      <depends_on></depends_on>
+    </COMPONENT-EXAMPLE>
   </components>
-  <data-flow></data-flow>
-  <error-handling></error-handling>
+  <data_flow></data_flow>
+  <error_handling></error_handling>
   <testing>
     <strategy></strategy>
     <coverage></coverage>
   </testing>
-  <non-goals>
-    <non-goal></non-goal>
-  </non-goals>
+  <non_goals>
+    <non_goal></non_goal>
+  </non_goals>
 </spec>