@osovv/vv-opencode 0.1.0 → 0.2.1

package/docs/verification-plan.xml

@@ -1,19 +1,19 @@
-<VerificationPlan VERSION="0.2.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 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>
+    <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 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>
+      <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; status reports configured</trace-sequence>
+        <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">
@@ -23,7 +23,7 @@
         <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">
+    <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>
@@ -31,20 +31,20 @@
         <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>
+    <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>detect unmanaged file -&gt; skip write</trace-sequence>
+        <trace-sequence>system reminder appended -&gt; loadMemoryRuntimeConfig -&gt; putMemory/listMemories/searchMemories -&gt; correct file layout</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>
+    </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>install -&gt; status -&gt; doctor</trace-sequence>
+        <trace-sequence>plugin config registers memory-reviewer -&gt; reviewer uses memory_list/get/search only</trace-sequence>
       </required-signals>
-    </VF-CROSS-DEVICE-SETUP>
+    </VF-MEMORY-REVIEW>
   </CriticalFlows>
 
   <ModuleVerification>
@@ -55,12 +55,14 @@
       <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="failure">Invalid plugin array or invalid Guardian config shape fails loudly.</scenario-4>
+        <scenario-4 kind="success">Global path resolution separates `opencode/` and `vvoc/` roots.</scenario-4>
       </scenarios>
       <required-log-markers />
       <required-trace-assertions>
@@ -75,8 +77,10 @@
         <file>src/lib/opencode.test.ts</file>
       </test-files>
       <module-checks>
-        <check-1>bun run build</check-1>
-        <check-2>bun test</check-2>
+        <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>
@@ -86,7 +90,7 @@
       <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>
+      <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>
 
@@ -112,6 +116,52 @@
       <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>
@@ -119,7 +169,9 @@
       <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>
+        <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>
@@ -128,13 +180,28 @@
     <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>
+        <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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Portable OpenCode workflow plugins and CLI tooling.",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,7 @@
     "plugins",
     "workflow",
     "guardian",
+    "memory",
     "bun",
     "citty"
   ],
@@ -32,13 +33,21 @@
     "./plugins/guardian": {
       "types": "./dist/plugins/guardian.d.ts",
       "import": "./dist/plugins/guardian.js"
+    },
+    "./plugins/memory": {
+      "types": "./dist/plugins/memory.d.ts",
+      "import": "./dist/plugins/memory.js"
     }
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "oxlint --deny warnings src",
+    "fmt": "oxfmt --write src",
+    "fmt:check": "oxfmt --check src",
     "test": "bun test",
-    "check": "bun run typecheck && bun test"
+    "check": "bun run typecheck && bun run lint && bun run fmt:check && bun test",
+    "prepare": "lefthook install --force"
   },
   "dependencies": {
     "@opencode-ai/plugin": "1.3.17",
@@ -49,6 +58,9 @@
   "devDependencies": {
     "@types/node": "22.13.9",
     "bun-types": "1.3.11",
+    "lefthook": "2.1.5",
+    "oxfmt": "0.43.0",
+    "oxlint": "1.58.0",
     "typescript": "5.8.2"
   },
   "engines": {