@osovv/vv-opencode 0.1.0 → 0.2.2

package/docs/development-plan.xml

@@ -1,155 +0,0 @@
-<DevelopmentPlan VERSION="0.2.0">
-  <ArchitectureNotes>
-    <objective>Package the existing Guardian plugin without behavior drift, while adding a small CLI that manages portable OpenCode config safely.</objective>
-    <non-goal>Do not expand into a large monorepo or broad profile manager before the first plugin packaging path is stable.</non-goal>
-    <risk-1>Config file mutation must stay conservative because users may already have hand-maintained JSONC with comments.</risk-1>
-  </ArchitectureNotes>
-
-  <Modules>
-    <M-CLI-CONFIG NAME="OpenCodeConfigTools" TYPE="UTILITY" LAYER="0" ORDER="1" STATUS="implemented">
-      <contract>
-        <purpose>Resolve OpenCode config paths, edit JSONC safely, render managed Guardian config, and inspect installation state.</purpose>
-        <inputs>
-          <param name="scope" type="global | project" />
-          <param name="cwd" type="string" />
-          <param name="configDir" type="string | undefined" />
-        </inputs>
-        <outputs>
-          <param name="ResolvedPaths | WriteResult | InstallationInspection" type="object" />
-        </outputs>
-        <errors>
-          <error code="INVALID_JSONC" />
-          <error code="INVALID_GUARDIAN_CONFIG" />
-        </errors>
-      </contract>
-      <interface>
-        <export-resolvePaths PURPOSE="Resolve config and Guardian file paths for the selected scope." />
-        <export-ensurePackageInstalled PURPOSE="Ensure the npm plugin is registered in OpenCode config." />
-        <export-syncGuardianConfig PURPOSE="Rewrite managed Guardian config while preserving current values." />
-      </interface>
-      <depends>none</depends>
-      <target>
-        <source>src/lib/opencode.ts</source>
-        <tests>src/lib/opencode.test.ts</tests>
-      </target>
-      <observability>
-        <log-prefix>[OpenCodeConfigTools]</log-prefix>
-        <critical-block>BLOCK_SYNC_GUARDIAN_CONFIG</critical-block>
-      </observability>
-      <verification-ref>V-M-CLI-CONFIG</verification-ref>
-      <notes>
-        <note-1>Main config edits should preserve comments when only the plugin array changes.</note-1>
-      </notes>
-    </M-CLI-CONFIG>
-
-    <M-CLI-COMMANDS NAME="VVOCCommands" TYPE="ENTRY_POINT" LAYER="1" ORDER="1" STATUS="implemented">
-      <contract>
-        <purpose>Expose install, sync, status, doctor, and Guardian config subcommands through citty.</purpose>
-        <inputs>
-          <param name="argv" type="string[]" />
-        </inputs>
-        <outputs>
-          <param name="stdout/stderr" type="terminal output" />
-        </outputs>
-        <errors>
-          <error code="INVALID_ARGUMENT" />
-        </errors>
-      </contract>
-      <interface>
-        <export-install PURPOSE="Bootstrap plugin registration and optional Guardian config." />
-        <export-sync PURPOSE="Refresh managed config files." />
-        <export-doctor PURPOSE="Diagnose installation drift or invalid config." />
-      </interface>
-      <depends>M-CLI-CONFIG</depends>
-      <target>
-        <source>src/cli.ts + src/commands/*.ts</source>
-        <tests>src/lib/opencode.test.ts</tests>
-      </target>
-      <observability>
-        <log-prefix>[VVOC]</log-prefix>
-        <critical-block>BLOCK_APPLY_COMMAND</critical-block>
-      </observability>
-      <verification-ref>V-M-CLI-COMMANDS</verification-ref>
-      <notes>
-        <note-1>Commands should stay thin and delegate file logic to `M-CLI-CONFIG`.</note-1>
-      </notes>
-    </M-CLI-COMMANDS>
-
-    <M-PLUGIN-GUARDIAN NAME="GuardianPlugin" TYPE="INTEGRATION" LAYER="0" ORDER="2" STATUS="implemented">
-      <contract>
-        <purpose>Review OpenCode permission requests with a constrained Guardian agent and auto-allow only low-risk actions.</purpose>
-        <inputs>
-          <param name="PluginInput" type="@opencode-ai/plugin input" />
-        </inputs>
-        <outputs>
-          <param name="Hooks" type="OpenCode plugin hooks" />
-        </outputs>
-        <errors>
-          <error code="GUARDIAN_REVIEW_FAILED" />
-          <error code="PERMISSION_REPLY_FAILED" />
-        </errors>
-      </contract>
-      <interface>
-        <export-GuardianPlugin PURPOSE="Register Guardian hooks, config agent, and permission review flow." />
-      </interface>
-      <depends>none</depends>
-      <target>
-        <source>src/plugins/guardian.ts</source>
-        <tests>typecheck-only in v1</tests>
-      </target>
-      <observability>
-        <log-prefix>[guardian]</log-prefix>
-        <critical-block>BLOCK_REVIEW_PERMISSION</critical-block>
-      </observability>
-      <verification-ref>V-M-PLUGIN-GUARDIAN</verification-ref>
-      <notes>
-        <note-1>This module is a direct port of the existing standalone plugin and should change minimally at first.</note-1>
-      </notes>
-    </M-PLUGIN-GUARDIAN>
-  </Modules>
-
-  <DataFlow>
-    <DF-PLUGIN-INSTALL NAME="PluginInstall" TRIGGER="vvoc install">
-      <step-1>Resolve scope-specific OpenCode and Guardian config paths.</step-1>
-      <step-2>Ensure `@osovv/vv-opencode` exists in the OpenCode `plugin` array.</step-2>
-      <step-3>Create `guardian.jsonc` when it does not already exist.</step-3>
-      <evidence>`vvoc status`, parsed config content, and successful typecheck/build.</evidence>
-    </DF-PLUGIN-INSTALL>
-    <DF-CONFIG-SYNC NAME="ManagedConfigSync" TRIGGER="vvoc sync">
-      <step-1>Inspect whether Guardian config is CLI-managed.</step-1>
-      <step-2>Parse current Guardian values from JSONC.</step-2>
-      <step-3>Rewrite managed file canonically while preserving current values.</step-3>
-      <evidence>Stable rewritten `guardian.jsonc` and no overwrite of unmanaged files without force.</evidence>
-    </DF-CONFIG-SYNC>
-    <DF-GUARDIAN-SETTINGS NAME="GuardianConfigWrite" TRIGGER="vvoc guardian config">
-      <step-1>Parse CLI overrides for model, variant, timeout, and thresholds.</step-1>
-      <step-2>Render a managed Guardian config template.</step-2>
-      <step-3>Write or print the config depending on mode.</step-3>
-      <evidence>JSONC parse succeeds and plugin can load the written file later.</evidence>
-    </DF-GUARDIAN-SETTINGS>
-    <DF-GUARDIAN-REVIEW NAME="GuardianPermissionReview" TRIGGER="permission.asked event">
-      <step-1>Capture relevant tool and command intent for the session.</step-1>
-      <step-2>Build a bounded transcript and planned action prompt.</step-2>
-      <step-3>Run Guardian, interpret risk, and auto-reply only when below threshold.</step-3>
-      <evidence>Guardian logs, toasts, and permission reply behavior inside OpenCode.</evidence>
-    </DF-GUARDIAN-REVIEW>
-  </DataFlow>
-
-  <ImplementationOrder>
-    <Phase-1 name="CLI Foundation" status="done">
-      <goal>Establish safe config mutation helpers and wire them into a usable Bun CLI.</goal>
-      <step-1 module="M-CLI-CONFIG" status="done" verification="V-M-CLI-CONFIG">Implement path resolution, JSONC edits, inspection, and Guardian template helpers.</step-1>
-      <step-2 module="M-CLI-COMMANDS" status="done" verification="V-M-CLI-COMMANDS">Expose install, sync, status, doctor, and Guardian config commands.</step-2>
-    </Phase-1>
-    <Phase-2 name="Guardian Packaging" status="done">
-      <goal>Move the existing standalone Guardian plugin into the repository and export it from the package.</goal>
-      <step-1 module="M-PLUGIN-GUARDIAN" status="done" verification="V-M-PLUGIN-GUARDIAN">Port the current Guardian plugin source into `src/plugins/guardian.ts`.</step-1>
-    </Phase-2>
-  </ImplementationOrder>
-
-  <ExecutionPolicy>
-    <default-profile>balanced</default-profile>
-    <controller-owns>docs/development-plan.xml, docs/knowledge-graph.xml, docs/verification-plan.xml</controller-owns>
-    <worker-owns>Only package source files, tests, and narrowly scoped documentation updates required by the approved module changes.</worker-owns>
-  </ExecutionPolicy>
-</DevelopmentPlan>

package/docs/knowledge-graph.xml

@@ -1,42 +0,0 @@
-<KnowledgeGraph>
-  <Project NAME="@osovv/vv-opencode" VERSION="0.2.0">
-    <keywords>opencode, plugins, workflow</keywords>
-    <annotation>Portable OpenCode workflow package with plugins and a Bun CLI for install, sync, and cross-device setup.</annotation>
-
-    <M-CLI-CONFIG NAME="OpenCodeConfigTools" TYPE="UTILITY" STATUS="implemented">
-      <purpose>Path resolution, JSONC-aware config mutation, managed Guardian config rendering, and installation inspection.</purpose>
-      <path>src/lib/opencode.ts</path>
-      <depends>none</depends>
-      <verification-ref>V-M-CLI-CONFIG</verification-ref>
-      <annotations>
-        <fn-resolvePaths PURPOSE="Resolve scope-aware config file paths for OpenCode and Guardian." />
-        <fn-ensurePackageInstalled PURPOSE="Add the package name to the OpenCode plugin array if needed." />
-        <fn-syncGuardianConfig PURPOSE="Rewrite managed Guardian config while preserving current values." />
-      </annotations>
-    </M-CLI-CONFIG>
-
-    <M-CLI-COMMANDS NAME="VVOCCommands" TYPE="ENTRY_POINT" STATUS="implemented">
-      <purpose>Compose the `vvoc` CLI and expose install, sync, status, doctor, and Guardian config commands.</purpose>
-      <path>src/cli.ts + src/commands/*.ts</path>
-      <depends>M-CLI-CONFIG</depends>
-      <verification-ref>V-M-CLI-COMMANDS</verification-ref>
-      <annotations>
-        <export-install PURPOSE="Bootstrap package registration and optional Guardian config." />
-        <export-sync PURPOSE="Refresh managed config files." />
-        <export-guardian PURPOSE="Expose Guardian-specific helper commands." />
-      </annotations>
-    </M-CLI-COMMANDS>
-
-    <M-PLUGIN-GUARDIAN NAME="GuardianPlugin" TYPE="INTEGRATION" STATUS="implemented">
-      <purpose>Review OpenCode permission requests using a constrained Guardian agent and safe fallback behavior.</purpose>
-      <path>src/plugins/guardian.ts</path>
-      <depends>none</depends>
-      <verification-ref>V-M-PLUGIN-GUARDIAN</verification-ref>
-      <annotations>
-        <export-GuardianPlugin PURPOSE="Register Guardian hooks for config, events, tool intent capture, and permission review." />
-      </annotations>
-    </M-PLUGIN-GUARDIAN>
-
-    <CrossLink from="M-CLI-COMMANDS" to="M-CLI-CONFIG" relation="uses" />
-  </Project>
-</KnowledgeGraph>

package/docs/operational-packets.xml

@@ -1,106 +0,0 @@
-<OperationalPackets VERSION="0.1.0">
-  <ExecutionPacketTemplate>
-    <ExecutionPacket>
-      <module-id>M-EXAMPLE</module-id>
-      <module-name>ExampleDomain</module-name>
-      <purpose>Implement the approved module without architectural drift.</purpose>
-      <write-scope>
-        <file-1>src/example/index.ts</file-1>
-        <file-2>src/example/index.test.ts</file-2>
-      </write-scope>
-      <contract-excerpt><![CDATA[
-Planned module contract excerpt goes here.
-      ]]></contract-excerpt>
-      <graph-entry-excerpt><![CDATA[
-Knowledge graph entry excerpt goes here.
-      ]]></graph-entry-excerpt>
-      <dependency-contract-summaries>
-        <dependency-1 module="M-LOGGER">Structured logger interface with stable marker fields.</dependency-1>
-      </dependency-contract-summaries>
-      <verification-excerpt><![CDATA[
-Verification-plan excerpt goes here.
-      ]]></verification-excerpt>
-      <expected-graph-delta-fields>
-        <field-1>imports</field-1>
-        <field-2>exports</field-2>
-        <field-3>annotations</field-3>
-        <field-4>CrossLinks</field-4>
-      </expected-graph-delta-fields>
-      <expected-verification-delta-fields>
-        <field-1>test-files</field-1>
-        <field-2>module-checks</field-2>
-        <field-3>required-log-markers</field-3>
-        <field-4>follow-up-checks</field-4>
-      </expected-verification-delta-fields>
-      <notes>
-        <note-1>Workers should only read more context when the packet is insufficient.</note-1>
-      </notes>
-    </ExecutionPacket>
-  </ExecutionPacketTemplate>
-
-  <GraphDeltaTemplate>
-    <GraphDelta module="M-EXAMPLE">
-      <imports-added>
-        <import-1>M-LOGGER</import-1>
-      </imports-added>
-      <imports-removed />
-      <exports-added>
-        <export-1>runExample</export-1>
-      </exports-added>
-      <exports-removed />
-      <annotations-added>
-        <annotation-1>&lt;fn-runExample PURPOSE="Execute the example flow" /&gt;</annotation-1>
-      </annotations-added>
-      <annotations-removed />
-      <cross-links-added>
-        <CrossLink from="M-EXAMPLE" to="M-LOGGER" relation="uses" />
-      </cross-links-added>
-      <cross-links-removed />
-      <notes>
-        <note-1>Only list graph facts that really changed in the code.</note-1>
-      </notes>
-    </GraphDelta>
-  </GraphDeltaTemplate>
-
-  <VerificationDeltaTemplate>
-    <VerificationDelta module="M-EXAMPLE">
-      <test-files-added>
-        <file-1>src/example/index.test.ts</file-1>
-      </test-files-added>
-      <test-files-removed />
-      <module-checks>
-        <command-1>bun test src/example/index.test.ts</command-1>
-        <command-2>bun x tsc --noEmit</command-2>
-      </module-checks>
-      <required-log-markers>
-        <marker-1>[ExampleDomain][runExample][BLOCK_EXECUTE_FLOW]</marker-1>
-      </required-log-markers>
-      <required-trace-assertions>
-        <assertion-1>Failure path must not emit BLOCK_PERSIST_RESULT.</assertion-1>
-      </required-trace-assertions>
-      <wave-follow-up>
-        <item-1>Run merged-surface integration check for the logger adapter.</item-1>
-      </wave-follow-up>
-      <phase-follow-up>
-        <item-1>Run the broader regression suite before marking the phase done.</item-1>
-      </phase-follow-up>
-    </VerificationDelta>
-  </VerificationDeltaTemplate>
-
-  <FailurePacketTemplate>
-    <FailurePacket>
-      <scenario>Primary success path fails on valid input.</scenario>
-      <contract-ref>M-EXAMPLE / V-M-EXAMPLE / scenario-1</contract-ref>
-      <expected-evidence>
-        <marker-1>[ExampleDomain][runExample][BLOCK_VALIDATE_INPUT]</marker-1>
-        <assertion-1>Expected return value should equal "ok".</assertion-1>
-      </expected-evidence>
-      <observed-evidence>
-        <log-1>[ExampleDomain][runExample][BLOCK_VALIDATE_INPUT] emitted</log-1>
-        <trace-1>BLOCK_VALIDATE_INPUT -&gt; threw EXAMPLE_INVALID_STATE</trace-1>
-      </observed-evidence>
-      <first-divergent-block>BLOCK_VALIDATE_INPUT</first-divergent-block>
-      <suggested-next-action>Read the contract, inspect the divergent block, and apply the smallest safe fix.</suggested-next-action>
-    </FailurePacket>
-  </FailurePacketTemplate>
-</OperationalPackets>

package/docs/requirements.xml

@@ -1,66 +0,0 @@
-<RequirementsAnalysis VERSION="0.2.0">
-  <Project>
-    <name>@osovv/vv-opencode</name>
-    <annotation>Portable OpenCode workflow package with plugins and a Bun CLI for install, sync, and cross-device setup.</annotation>
-    <keywords>opencode, plugins, workflow</keywords>
-  </Project>
-
-  <Actors>
-    <actor-User>Engineer who wants a portable OpenCode workflow across devices and repositories.</actor-User>
-    <actor-System>CLI and plugin runtime that install, sync, and execute the configured workflow safely.</actor-System>
-  </Actors>
-
-  <UseCases>
-    <UC-001>
-      <Actor>User</Actor>
-      <Action>Runs `vvoc install` for global or project scope.</Action>
-      <Goal>To register `@osovv/vv-opencode` in OpenCode config and bootstrap Guardian config when needed.</Goal>
-      <Preconditions>Bun and OpenCode are available, and the target config location is writable.</Preconditions>
-      <AcceptanceCriteria>The package name appears in the resolved OpenCode config and a default Guardian config can be created idempotently.</AcceptanceCriteria>
-      <Priority>high</Priority>
-      <RelatedFlows>DF-PLUGIN-INSTALL</RelatedFlows>
-    </UC-001>
-    <UC-002>
-      <Actor>User</Actor>
-      <Action>Runs `vvoc sync` on another machine or after package updates.</Action>
-      <Goal>To refresh managed workflow files without clobbering manually-owned config.</Goal>
-      <Preconditions>The target config files already exist or can be created.</Preconditions>
-      <AcceptanceCriteria>Managed files are rewritten canonically, existing values are preserved, and unmanaged files are skipped unless force is explicit.</AcceptanceCriteria>
-      <Priority>high</Priority>
-      <RelatedFlows>DF-CONFIG-SYNC</RelatedFlows>
-    </UC-002>
-    <UC-003>
-      <Actor>User</Actor>
-      <Action>Runs `vvoc guardian config` with optional model, variant, timeout, or threshold overrides.</Action>
-      <Goal>To customize Guardian behavior without editing JSONC by hand.</Goal>
-      <Preconditions>A target OpenCode config scope has been chosen.</Preconditions>
-      <AcceptanceCriteria>The generated `guardian.jsonc` is valid, readable by the plugin, and safe to resync later.</AcceptanceCriteria>
-      <Priority>high</Priority>
-      <RelatedFlows>DF-GUARDIAN-SETTINGS</RelatedFlows>
-    </UC-003>
-  </UseCases>
-
-  <NonGoals>
-    <item-1>No public plugin marketplace, profile manager, or multi-package monorepo in v1.</item-1>
-    <item-2>No forced overwrite of unmanaged user config files without an explicit force flag.</item-2>
-    <item-3>No attempt to redesign Guardian logic before it is safely packaged and reproducible from this repository.</item-3>
-  </NonGoals>
-
-  <Constraints>
-    <constraint-1>OpenCode config integration must follow documented global and project path conventions.</constraint-1>
-    <constraint-2>Guardian must remain compatible with the current standalone plugin behavior while being moved into the repo.</constraint-2>
-    <constraint-3>Config writes must be idempotent and preserve existing JSONC comments in the main OpenCode config where practical.</constraint-3>
-    <constraint-4>Generated Guardian config should be clearly marked as CLI-managed so sync can distinguish owned and non-owned files.</constraint-4>
-  </Constraints>
-
-  <Risks>
-    <risk-1>Repositories or machines may contain multiple config files (`.json` and `.jsonc`) that can drift from each other.</risk-1>
-    <risk-2>Unsafe rewrites of user-maintained config could damage trust in the CLI.</risk-2>
-    <risk-3>Guardian depends on OpenCode plugin and SDK surface area that may evolve over time.</risk-3>
-  </Risks>
-
-  <OpenQuestions>
-    <question-1>Should future versions also manage agents, commands, skills, and themes in addition to plugins and Guardian config?</question-1>
-    <question-2>Should the package eventually export multiple plugins from the same npm entrypoint or separate them by subpath and opt-in config?</question-2>
-  </OpenQuestions>
-</RequirementsAnalysis>

package/docs/technology.xml

@@ -1,51 +0,0 @@
-<TechnologyStack VERSION="0.2.0">
-  <Runtime>Bun 1.3.8</Runtime>
-  <Language>TypeScript 5.8.2</Language>
-  <Framework>citty 0.2.2</Framework>
-
-  <Dependencies>
-    <dep name="@opencode-ai/plugin" version="1.3.17" purpose="Type-safe OpenCode plugin API and hook definitions" />
-    <dep name="@opencode-ai/sdk" version="1.3.17" purpose="OpenCode client types and runtime interactions used by Guardian" />
-    <dep name="citty" version="0.2.2" purpose="CLI command tree and argument parsing for `vvoc`" />
-    <dep name="jsonc-parser" version="3.3.1" purpose="Safe JSONC-aware config parsing and in-place edits" />
-  </Dependencies>
-
-  <VersionConstraints>
-    <constraint lib="bun" min="1.3.8" max="1.3.x" reason="The package and local verification target Bun-based runtime and test execution." />
-    <constraint lib="@opencode-ai/plugin" min="1.3.17" max="1.3.x" reason="Guardian depends on the current plugin hook and input shape." />
-    <constraint lib="@opencode-ai/sdk" min="1.3.17" max="1.3.x" reason="Guardian uses current SDK message, part, and config types." />
-  </VersionConstraints>
-
-  <Tooling>
-    <tool name="package-manager" value="bun" version="1.3.8" />
-    <tool name="compiler" value="typescript" version="5.8.2" />
-    <tool name="test-runner" value="bun test" version="1.3.8" />
-  </Tooling>
-
-  <Testing>
-    <module-level>
-      <command>bun test src/lib/opencode.test.ts</command>
-      <focus>Fast deterministic checks for config merge and Guardian config rendering.</focus>
-    </module-level>
-    <wave-level>
-      <command>bun run typecheck &amp;&amp; bun test</command>
-      <focus>Checks merged CLI and helper behavior after coordinated changes.</focus>
-    </wave-level>
-    <phase-level>
-      <command>bun run build &amp;&amp; bun test</command>
-      <focus>Validates package output and regression-safe baseline behavior.</focus>
-    </phase-level>
-    <mocking-policy>Prefer direct pure-function verification and fixture text over broad mocks.</mocking-policy>
-  </Testing>
-
-  <Observability>
-    <logger>OpenCode app log via `client.app.log()` plus Guardian best-effort debug file in `/tmp`.</logger>
-    <log-format>[service][function][block] message</log-format>
-    <required-fields>service, level, message, requestID, sessionID</required-fields>
-    <redaction>Never log secrets, credentials, or raw high-risk payloads beyond the existing Guardian truncation policy.</redaction>
-  </Observability>
-
-  <DeliveryShape>
-    <shape>One public npm package that exports OpenCode plugins and ships a Bun CLI binary named `vvoc`.</shape>
-  </DeliveryShape>
-</TechnologyStack>

package/docs/verification-plan.xml

@@ -1,145 +0,0 @@
-<VerificationPlan VERSION="0.2.0">
-  <GlobalPolicy>
-    <log-format>[service][function][block] message</log-format>
-    <deterministic-first>true</deterministic-first>
-    <module-level-focus>Fast deterministic checks for config mutation and rendering helpers.</module-level-focus>
-    <wave-level-focus>Typecheck and test the merged CLI + helper surface after each coordinated change.</wave-level-focus>
-    <phase-level-focus>Buildable package output plus stable command behavior for installation and sync workflows.</phase-level-focus>
-    <redaction>Never log secrets, credentials, raw tokens, or high-risk payloads outside the existing Guardian truncation policy.</redaction>
-  </GlobalPolicy>
-
-  <CriticalFlows>
-    <VF-PLUGIN-INSTALL NAME="PluginInstall" USE_CASES="UC-001" DATA_FLOW="DF-PLUGIN-INSTALL" PRIORITY="high">
-      <scenario>User installs the package into a fresh or existing OpenCode config.</scenario>
-      <expected-outcome>The package name is present in the resolved `plugin` array and OpenCode can later load the plugin from npm.</expected-outcome>
-      <required-signals>
-        <trace-sequence>resolvePaths -&gt; ensurePackageInstalled -&gt; status reports configured</trace-sequence>
-      </required-signals>
-    </VF-PLUGIN-INSTALL>
-    <VF-CONFIG-SYNC NAME="ManagedConfigSync" USE_CASES="UC-002" DATA_FLOW="DF-CONFIG-SYNC" PRIORITY="high">
-      <scenario>User syncs a managed Guardian config after changing package versions or moving to another device.</scenario>
-      <expected-outcome>The managed file is rewritten canonically and current values survive the rewrite.</expected-outcome>
-      <required-signals>
-        <trace-sequence>inspect managed file -&gt; parse current values -&gt; render canonical JSONC</trace-sequence>
-      </required-signals>
-    </VF-CONFIG-SYNC>
-    <VF-GUARDIAN-REVIEW NAME="GuardianReview" USE_CASES="UC-003" DATA_FLOW="DF-GUARDIAN-REVIEW" PRIORITY="high">
-      <scenario>OpenCode asks for a permission decision while Guardian is active.</scenario>
-      <expected-outcome>Low-risk actions may be auto-approved and higher-risk actions fall back to manual approval.</expected-outcome>
-      <required-signals>
-        <log-marker>guardian review started</log-marker>
-        <log-marker>guardian review completed</log-marker>
-      </required-signals>
-    </VF-GUARDIAN-REVIEW>
-    <VF-SAFE-UPDATES NAME="SafeUpdates" USE_CASES="UC-002" DATA_FLOW="DF-CONFIG-SYNC" PRIORITY="high">
-      <scenario>User already owns a manually-maintained Guardian config file.</scenario>
-      <expected-outcome>The CLI skips rewriting it unless force is explicit.</expected-outcome>
-      <required-signals>
-        <trace-sequence>detect unmanaged file -&gt; skip write</trace-sequence>
-      </required-signals>
-    </VF-SAFE-UPDATES>
-    <VF-CROSS-DEVICE-SETUP NAME="CrossDeviceSetup" USE_CASES="UC-001, UC-002" DATA_FLOW="DF-PLUGIN-INSTALL" PRIORITY="high">
-      <scenario>User repeats install or sync on another machine.</scenario>
-      <expected-outcome>The same package and config layout can be recreated with predictable CLI output.</expected-outcome>
-      <required-signals>
-        <trace-sequence>install -&gt; status -&gt; doctor</trace-sequence>
-      </required-signals>
-    </VF-CROSS-DEVICE-SETUP>
-  </CriticalFlows>
-
-  <ModuleVerification>
-    <V-M-CLI-CONFIG MODULE="M-CLI-CONFIG" PRIORITY="high">
-      <test-files>
-        <file>src/lib/opencode.test.ts</file>
-      </test-files>
-      <module-checks>
-        <check-1>bun test src/lib/opencode.test.ts</check-1>
-        <check-2>bun x tsc --noEmit</check-2>
-      </module-checks>
-      <scenarios>
-        <scenario-1 kind="success">Fresh install config renders with schema and plugin array.</scenario-1>
-        <scenario-2 kind="success">Existing JSONC comments survive plugin insertion.</scenario-2>
-        <scenario-3 kind="success">Guardian config round-trips explicit override values.</scenario-3>
-        <scenario-4 kind="failure">Invalid plugin array or invalid Guardian config shape fails loudly.</scenario-4>
-      </scenarios>
-      <required-log-markers />
-      <required-trace-assertions>
-        <assertion-1>Sync must not overwrite unmanaged Guardian config without force.</assertion-1>
-      </required-trace-assertions>
-      <wave-follow-up>Smoke command output for `status` and `doctor` after build.</wave-follow-up>
-      <phase-follow-up>Extend tests to cover more path and scope permutations.</phase-follow-up>
-    </V-M-CLI-CONFIG>
-
-    <V-M-CLI-COMMANDS MODULE="M-CLI-COMMANDS" PRIORITY="medium">
-      <test-files>
-        <file>src/lib/opencode.test.ts</file>
-      </test-files>
-      <module-checks>
-        <check-1>bun run build</check-1>
-        <check-2>bun test</check-2>
-      </module-checks>
-      <scenarios>
-        <scenario-1 kind="success">CLI compiles and registers all planned top-level subcommands.</scenario-1>
-        <scenario-2 kind="success">`guardian config --print` emits valid JSONC content.</scenario-2>
-      </scenarios>
-      <required-log-markers />
-      <required-trace-assertions>
-        <assertion-1>Command handlers should delegate file mutation to helper utilities instead of duplicating filesystem logic.</assertion-1>
-      </required-trace-assertions>
-      <wave-follow-up>Verify `vvoc install`, `vvoc sync`, and `vvoc doctor` against a temp config directory.</wave-follow-up>
-      <phase-follow-up>Add command-level smoke tests once temp-dir fixtures are introduced.</phase-follow-up>
-    </V-M-CLI-COMMANDS>
-
-    <V-M-PLUGIN-GUARDIAN MODULE="M-PLUGIN-GUARDIAN" PRIORITY="high">
-      <test-files>
-        <file>typecheck-only in v1</file>
-      </test-files>
-      <module-checks>
-        <check-1>bun x tsc --noEmit</check-1>
-      </module-checks>
-      <scenarios>
-        <scenario-1 kind="success">Guardian plugin exports compile against current OpenCode plugin and SDK types.</scenario-1>
-        <scenario-2 kind="failure">Review failures fall back to manual approval instead of silently allowing.</scenario-2>
-      </scenarios>
-      <required-log-markers>
-        <marker-1>guardian plugin initialized</marker-1>
-        <marker-2>guardian review started</marker-2>
-        <marker-3>guardian review completed</marker-3>
-      </required-log-markers>
-      <required-trace-assertions>
-        <assertion-1>Auto-allow only occurs when Guardian returns a risk score below the configured threshold.</assertion-1>
-      </required-trace-assertions>
-      <wave-follow-up>Add isolated behavioral tests around assessment parsing and decision thresholds.</wave-follow-up>
-      <phase-follow-up>Consider extracting pure Guardian parsing helpers for direct unit coverage.</phase-follow-up>
-    </V-M-PLUGIN-GUARDIAN>
-  </ModuleVerification>
-
-  <PhaseGates>
-    <Gate-Phase-1 PHASE="Phase-1">
-      <goal>CLI foundation is buildable and the helper layer has deterministic checks.</goal>
-      <commands>
-        <command-1>bun x tsc --noEmit</command-1>
-        <command-2>bun test</command-2>
-      </commands>
-      <required-evidence>
-        <evidence-1>Config merge and Guardian config rendering are covered by module-local tests.</evidence-1>
-      </required-evidence>
-    </Gate-Phase-1>
-    <Gate-Phase-2 PHASE="Phase-2">
-      <goal>Guardian is packaged from the repo and exported without behavior drift.</goal>
-      <commands>
-        <command-1>bun run build</command-1>
-        <command-2>bun x tsc --noEmit</command-2>
-      </commands>
-      <required-evidence>
-        <evidence-1>`src/plugins/guardian.ts` is present and package root exports `GuardianPlugin`.</evidence-1>
-      </required-evidence>
-    </Gate-Phase-2>
-  </PhaseGates>
-
-  <FailurePackets>
-    <packet-template>
-      <expected-fields>scenario, expected-evidence, observed-evidence, first-divergent-block, next-action</expected-fields>
-    </packet-template>
-  </FailurePackets>
-</VerificationPlan>