@osovv/vv-opencode 0.2.1 → 0.2.2

package/docs/verification-plan.xml

@@ -1,212 +0,0 @@
-<VerificationPlan VERSION="0.3.0">
-  <GlobalPolicy>
-    <log-format>[service][function][block] message</log-format>
-    <deterministic-first>true</deterministic-first>
-    <module-level-focus>Fast deterministic checks for vvoc config layout, Guardian config rendering, memory CRUD, and reviewer registration.</module-level-focus>
-    <wave-level-focus>Typecheck, lint, format-check, and test the merged CLI + plugin surface after each coordinated change.</wave-level-focus>
-    <phase-level-focus>Buildable package output plus stable command behavior for installation, Guardian review, and explicit memory 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 global or project config root.</scenario>
-      <expected-outcome>The package name is present in the resolved OpenCode `plugin` array and Guardian config lives under the vvoc config root.</expected-outcome>
-      <required-signals>
-        <trace-sequence>resolvePaths -&gt; ensurePackageInstalled -&gt; installGuardianConfig -&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-001" 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-MEMORY-ACCESS NAME="MemoryAccess" USE_CASES="UC-003" DATA_FLOW="DF-MEMORY-ACCESS" PRIORITY="high">
-      <scenario>User stores and retrieves explicit memory across session, branch, project, and shared scopes.</scenario>
-      <expected-outcome>Entries are written to `.vvoc/memory`, later searchable, and never injected into prompts automatically, while the agent still receives a short system reminder to use memory tools proactively.</expected-outcome>
-      <required-signals>
-        <trace-sequence>system reminder appended -&gt; loadMemoryRuntimeConfig -&gt; putMemory/listMemories/searchMemories -&gt; correct file layout</trace-sequence>
-      </required-signals>
-    </VF-MEMORY-ACCESS>
-    <VF-MEMORY-REVIEW NAME="MemoryReview" USE_CASES="UC-004" DATA_FLOW="DF-MEMORY-REVIEW" PRIORITY="medium">
-      <scenario>User invokes `@memory-reviewer` to audit existing memory.</scenario>
-      <expected-outcome>The reviewer can inspect memory with read-only tools and returns a report without changing entries.</expected-outcome>
-      <required-signals>
-        <trace-sequence>plugin config registers memory-reviewer -&gt; reviewer uses memory_list/get/search only</trace-sequence>
-      </required-signals>
-    </VF-MEMORY-REVIEW>
-  </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>
-        <check-3>bun run lint</check-3>
-        <check-4>bun run fmt:check</check-4>
-      </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="success">Global path resolution separates `opencode/` and `vvoc/` roots.</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 lint</check-1>
-        <check-2>bun run fmt:check</check-2>
-        <check-3>bun run build</check-3>
-        <check-4>bun test</check-4>
-      </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 home.</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>
-
-    <V-M-PLUGIN-MEMORY-STORE MODULE="M-PLUGIN-MEMORY-STORE" PRIORITY="high">
-      <test-files>
-        <file>src/plugins/memory.test.ts</file>
-      </test-files>
-      <module-checks>
-        <check-1>bun test src/plugins/memory.test.ts</check-1>
-        <check-2>bun x tsc --noEmit</check-2>
-      </module-checks>
-      <scenarios>
-        <scenario-1 kind="success">Scoped memory entries are stored in the expected `.vvoc/memory` layout.</scenario-1>
-        <scenario-2 kind="success">Search returns the best lexical match in the requested scope.</scenario-2>
-        <scenario-3 kind="success">Update and delete preserve store consistency and clean empty directories.</scenario-3>
-      </scenarios>
-      <required-log-markers />
-      <required-trace-assertions>
-        <assertion-1>Memory stays explicit-only and no store operation injects entries into prompts automatically.</assertion-1>
-      </required-trace-assertions>
-      <wave-follow-up>Watch performance if the number of JSON entries grows significantly.</wave-follow-up>
-      <phase-follow-up>Consider indexing only when the simple file scan becomes a measured problem.</phase-follow-up>
-    </V-M-PLUGIN-MEMORY-STORE>
-
-    <V-M-PLUGIN-MEMORY MODULE="M-PLUGIN-MEMORY" PRIORITY="high">
-      <test-files>
-        <file>src/plugins/memory.test.ts</file>
-      </test-files>
-      <module-checks>
-        <check-1>bun test src/plugins/memory.test.ts</check-1>
-        <check-2>bun x tsc --noEmit</check-2>
-      </module-checks>
-      <scenarios>
-        <scenario-1 kind="success">MemoryPlugin registers all six memory tools.</scenario-1>
-        <scenario-2 kind="success">Plugin config registers the `memory-reviewer` subagent.</scenario-2>
-        <scenario-3 kind="success">Plugin appends a short system instruction encouraging proactive memory tool usage without injecting stored entries.</scenario-3>
-        <scenario-4 kind="failure">Disabled memory config blocks tool use instead of pretending memory exists.</scenario-4>
-      </scenarios>
-      <required-log-markers>
-        <marker-1>memory plugin initialized</marker-1>
-      </required-log-markers>
-      <required-trace-assertions>
-        <assertion-1>The reviewer agent must not have write/delete memory tools enabled.</assertion-1>
-        <assertion-2>The system reminder must not include stored memory entries or imply that memory is already loaded.</assertion-2>
-      </required-trace-assertions>
-      <wave-follow-up>Consider adding a smoke test around custom tool execution in a live OpenCode session.</wave-follow-up>
-      <phase-follow-up>Add coverage for memory config warnings and disabled mode if the config surface grows.</phase-follow-up>
-    </V-M-PLUGIN-MEMORY>
-  </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 run lint</command-2>
-        <command-3>bun run fmt:check</command-3>
-        <command-4>bun test</command-4>
-      </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 x tsc --noEmit</command-1>
-        <command-2>bun run lint</command-2>
-        <command-3>bun run fmt:check</command-3>
-        <command-4>bun run build</command-4>
-      </commands>
-      <required-evidence>
-        <evidence-1>`src/plugins/guardian.ts` is present and package root exports `GuardianPlugin`.</evidence-1>
-      </required-evidence>
-    </Gate-Phase-2>
-    <Gate-Phase-3 PHASE="Phase-3">
-      <goal>Explicit memory is packaged from the repo and stored under `.vvoc/memory` with a report-only reviewer agent.</goal>
-      <commands>
-        <command-1>bun x tsc --noEmit</command-1>
-        <command-2>bun run lint</command-2>
-        <command-3>bun run fmt:check</command-3>
-        <command-4>bun test</command-4>
-        <command-5>bun run build</command-5>
-      </commands>
-      <required-evidence>
-        <evidence-1>`src/plugins/memory.ts` and `src/plugins/memory-store.ts` are present and package root exports `MemoryPlugin`.</evidence-1>
-      </required-evidence>
-    </Gate-Phase-3>
-  </PhaseGates>
-
-  <FailurePackets>
-    <packet-template>
-      <expected-fields>scenario, expected-evidence, observed-evidence, first-divergent-block, next-action</expected-fields>
-    </packet-template>
-  </FailurePackets>
-</VerificationPlan>