@osovv/vv-opencode 0.1.0 → 0.2.1

package/docs/development-plan.xml

@@ -1,14 +1,15 @@
-<DevelopmentPlan VERSION="0.2.0">
+<DevelopmentPlan VERSION="0.3.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>
+    <objective>Package portable OpenCode workflow plugins while keeping vvoc-owned config and memory data isolated from native OpenCode config.</objective>
+    <non-goal>Do not expand into a large monorepo or broad profile manager before plugin packaging, explicit memory, and vvoc config boundaries are stable.</non-goal>
     <risk-1>Config file mutation must stay conservative because users may already have hand-maintained JSONC with comments.</risk-1>
+    <risk-2>The file-based memory store does full scans and should stay explicit, simple, and easy to reason about until scale requires indexing.</risk-2>
   </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>
+        <purpose>Resolve OpenCode and vvoc 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" />
@@ -23,13 +24,13 @@
         </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-resolvePaths PURPOSE="Resolve OpenCode config paths and vvoc-managed config paths for the selected scope." />
+        <export-ensurePackageInstalled PURPOSE="Ensure the npm package 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>
+        <source>src/lib/opencode.ts + src/lib/vvoc-paths.ts</source>
         <tests>src/lib/opencode.test.ts</tests>
       </target>
       <observability>
@@ -57,7 +58,7 @@
       </contract>
       <interface>
         <export-install PURPOSE="Bootstrap plugin registration and optional Guardian config." />
-        <export-sync PURPOSE="Refresh managed config files." />
+        <export-sync PURPOSE="Refresh managed vvoc config files." />
         <export-doctor PURPOSE="Diagnose installation drift or invalid config." />
       </interface>
       <depends>M-CLI-CONFIG</depends>
@@ -71,7 +72,7 @@
       </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>
+        <note-1>Commands should stay thin and delegate file logic to helper utilities.</note-1>
       </notes>
     </M-CLI-COMMANDS>
 
@@ -92,7 +93,7 @@
       <interface>
         <export-GuardianPlugin PURPOSE="Register Guardian hooks, config agent, and permission review flow." />
       </interface>
-      <depends>none</depends>
+      <depends>M-CLI-CONFIG</depends>
       <target>
         <source>src/plugins/guardian.ts</source>
         <tests>typecheck-only in v1</tests>
@@ -103,16 +104,83 @@
       </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>
+        <note-1>Guardian now reads vvoc-managed config from `.vvoc/` or `$XDG_CONFIG_HOME/vvoc/` only.</note-1>
       </notes>
     </M-PLUGIN-GUARDIAN>
+
+    <M-PLUGIN-MEMORY-STORE NAME="MemoryStore" TYPE="UTILITY" LAYER="0" ORDER="3" STATUS="implemented">
+      <contract>
+        <purpose>Persist explicit memory entries in `.vvoc/memory`, support scope-aware CRUD, and rank lexical search results.</purpose>
+        <inputs>
+          <param name="MemoryRuntimeConfig" type="object" />
+          <param name="MemoryEntry or query/filter inputs" type="object" />
+        </inputs>
+        <outputs>
+          <param name="MemoryEntry | MemoryEntry[] | MemoryRuntimeConfig" type="object" />
+        </outputs>
+        <errors>
+          <error code="INVALID_MEMORY_CONFIG" />
+          <error code="INVALID_MEMORY_TEXT" />
+        </errors>
+      </contract>
+      <interface>
+        <export-loadMemoryRuntimeConfig PURPOSE="Load vvoc memory settings from global and project config files." />
+        <export-putMemory PURPOSE="Create a scoped memory entry in `.vvoc/memory`." />
+        <export-searchMemories PURPOSE="Return ranked lexical matches across relevant memory scopes." />
+      </interface>
+      <depends>none</depends>
+      <target>
+        <source>src/plugins/memory-store.ts</source>
+        <tests>src/plugins/memory.test.ts</tests>
+      </target>
+      <observability>
+        <log-prefix>[memory-store]</log-prefix>
+        <critical-block>BLOCK_MEMORY_SEARCH</critical-block>
+      </observability>
+      <verification-ref>V-M-PLUGIN-MEMORY-STORE</verification-ref>
+      <notes>
+        <note-1>Memory remains explicit-only. The store must not inject entries into prompts or system context.</note-1>
+      </notes>
+    </M-PLUGIN-MEMORY-STORE>
+
+    <M-PLUGIN-MEMORY NAME="MemoryPlugin" TYPE="INTEGRATION" LAYER="0" ORDER="4" STATUS="implemented">
+      <contract>
+        <purpose>Add explicit memory tools to OpenCode, register a report-only `memory-reviewer` subagent, and inject a short system reminder that encourages proactive memory tool usage without loading stored entries.</purpose>
+        <inputs>
+          <param name="PluginInput" type="@opencode-ai/plugin input" />
+        </inputs>
+        <outputs>
+          <param name="Hooks" type="OpenCode plugin hooks with custom tools and config mutation" />
+        </outputs>
+        <errors>
+          <error code="MEMORY_DISABLED" />
+          <error code="MEMORY_NOT_FOUND" />
+        </errors>
+      </contract>
+      <interface>
+        <export-MemoryPlugin PURPOSE="Register explicit memory tools and the `memory-reviewer` subagent." />
+      </interface>
+      <depends>M-PLUGIN-MEMORY-STORE</depends>
+      <target>
+        <source>src/plugins/memory.ts</source>
+        <tests>src/plugins/memory.test.ts</tests>
+      </target>
+      <observability>
+        <log-prefix>[memory]</log-prefix>
+        <critical-block>BLOCK_REGISTER_MEMORY_TOOLS</critical-block>
+      </observability>
+      <verification-ref>V-M-PLUGIN-MEMORY</verification-ref>
+      <notes>
+        <note-1>The reviewer is implemented as a bundled subagent, and the main chat path receives only a short memory policy reminder instead of prompt-injected memory entries.</note-1>
+      </notes>
+    </M-PLUGIN-MEMORY>
   </Modules>
 
   <DataFlow>
     <DF-PLUGIN-INSTALL NAME="PluginInstall" TRIGGER="vvoc install">
-      <step-1>Resolve scope-specific OpenCode and Guardian config paths.</step-1>
+      <step-1>Resolve scope-specific OpenCode config paths and vvoc 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>
+      <step-3>Create `guardian.jsonc` under the vvoc config root 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">
@@ -121,18 +189,25 @@
       <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>
+    <DF-MEMORY-ACCESS NAME="MemoryAccess" TRIGGER="memory_* tool call">
+      <step-0>Before model turns, the plugin appends a short system reminder that explicit memory tools exist, without injecting stored memory entries.</step-0>
+      <step-1>Load vvoc memory settings from `$XDG_CONFIG_HOME/vvoc/memory.jsonc` and project `.vvoc/memory.jsonc`.</step-1>
+      <step-2>Resolve relevant scopes from session id, git branch, project, or shared key.</step-2>
+      <step-3>Read or mutate entries under `.vvoc/memory/` using file-per-entry JSON records.</step-3>
+      <evidence>Correct file layout, deterministic CRUD/search behavior, and no automatic prompt injection.</evidence>
+    </DF-MEMORY-ACCESS>
+    <DF-MEMORY-REVIEW NAME="MemoryReview" TRIGGER="@memory-reviewer invocation">
+      <step-1>Register the reviewer subagent through plugin config mutation.</step-1>
+      <step-2>The reviewer inspects memory with `memory_list`, `memory_get`, and `memory_search` only.</step-2>
+      <step-3>The reviewer returns a keep/update/merge/delete report without modifying entries.</step-3>
+      <evidence>Bundled `memory-reviewer` agent with read-only memory tooling.</evidence>
+    </DF-MEMORY-REVIEW>
   </DataFlow>
 
   <ImplementationOrder>
@@ -143,8 +218,13 @@
     </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>
+      <step-1 module="M-PLUGIN-GUARDIAN" status="done" verification="V-M-PLUGIN-GUARDIAN">Port Guardian and move runtime config to vvoc-owned paths.</step-1>
     </Phase-2>
+    <Phase-3 name="Explicit Memory" status="done">
+      <goal>Add explicit persistent memory, store it in `.vvoc/memory`, and expose a report-only reviewer subagent.</goal>
+      <step-1 module="M-PLUGIN-MEMORY-STORE" status="done" verification="V-M-PLUGIN-MEMORY-STORE">Implement file-based scoped memory storage and lexical search.</step-1>
+      <step-2 module="M-PLUGIN-MEMORY" status="done" verification="V-M-PLUGIN-MEMORY">Register memory tools and the `memory-reviewer` subagent via OpenCode plugin hooks.</step-2>
+    </Phase-3>
   </ImplementationOrder>
 
   <ExecutionPolicy>

package/docs/knowledge-graph.xml

@@ -1,15 +1,15 @@
 <KnowledgeGraph>
-  <Project NAME="@osovv/vv-opencode" VERSION="0.2.0">
+  <Project NAME="@osovv/vv-opencode" VERSION="0.3.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>
+      <purpose>Path resolution, JSONC-aware config mutation, managed Guardian config rendering, and installation inspection with separated vvoc roots.</purpose>
+      <path>src/lib/opencode.ts + src/lib/vvoc-paths.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-resolvePaths PURPOSE="Resolve OpenCode config paths and vvoc-managed config paths for the selected scope." />
         <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>
@@ -22,7 +22,7 @@
       <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-sync PURPOSE="Refresh managed vvoc config files." />
         <export-guardian PURPOSE="Expose Guardian-specific helper commands." />
       </annotations>
     </M-CLI-COMMANDS>
@@ -30,13 +30,37 @@
     <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>
+      <depends>M-CLI-CONFIG</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>
 
+    <M-PLUGIN-MEMORY-STORE NAME="MemoryStore" TYPE="UTILITY" STATUS="implemented">
+      <purpose>Store explicit memory under `.vvoc/memory`, resolve scopes, and provide lexical ranking for search.</purpose>
+      <path>src/plugins/memory-store.ts</path>
+      <depends>none</depends>
+      <verification-ref>V-M-PLUGIN-MEMORY-STORE</verification-ref>
+      <annotations>
+        <fn-loadMemoryRuntimeConfig PURPOSE="Load global and project vvoc memory settings." />
+        <fn-putMemory PURPOSE="Create a scoped memory entry in `.vvoc/memory`." />
+        <fn-searchMemories PURPOSE="Return ranked lexical matches across scoped entries." />
+      </annotations>
+    </M-PLUGIN-MEMORY-STORE>
+
+    <M-PLUGIN-MEMORY NAME="MemoryPlugin" TYPE="INTEGRATION" STATUS="implemented">
+      <purpose>Add explicit memory tools to OpenCode and register the `memory-reviewer` subagent.</purpose>
+      <path>src/plugins/memory.ts</path>
+      <depends>M-PLUGIN-MEMORY-STORE</depends>
+      <verification-ref>V-M-PLUGIN-MEMORY</verification-ref>
+      <annotations>
+        <export-MemoryPlugin PURPOSE="Register memory tools and the report-only reviewer subagent." />
+      </annotations>
+    </M-PLUGIN-MEMORY>
+
     <CrossLink from="M-CLI-COMMANDS" to="M-CLI-CONFIG" relation="uses" />
+    <CrossLink from="M-PLUGIN-GUARDIAN" to="M-CLI-CONFIG" relation="uses" />
+    <CrossLink from="M-PLUGIN-MEMORY" to="M-PLUGIN-MEMORY-STORE" relation="uses" />
   </Project>
 </KnowledgeGraph>

package/docs/requirements.xml

@@ -1,4 +1,4 @@
-<RequirementsAnalysis VERSION="0.2.0">
+<RequirementsAnalysis VERSION="0.3.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>
@@ -14,53 +14,64 @@
     <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>
+      <Goal>To register `@osovv/vv-opencode` in OpenCode config while keeping vvoc-managed config in `XDG_CONFIG_HOME/vvoc` or project-local `.vvoc/`.</Goal>
+      <Preconditions>Bun and OpenCode are available, and the target config locations are writable.</Preconditions>
+      <AcceptanceCriteria>The package name appears in the resolved OpenCode config and `guardian.jsonc` is created under the vvoc config root.</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>
+      <Goal>To refresh managed vvoc-owned config 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>
+      <AcceptanceCriteria>Managed files are rewritten canonically 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>
+      <Action>Uses `memory_put`, `memory_search`, `memory_get`, `memory_update`, `memory_delete`, or `memory_list` inside OpenCode.</Action>
+      <Goal>To persist explicit durable context in `.vvoc/memory/` without automatic prompt injection.</Goal>
+      <Preconditions>The package is enabled in OpenCode and memory is not disabled in `memory.jsonc`.</Preconditions>
+      <AcceptanceCriteria>Memory entries are stored in the correct scope, searchable later, and never silently injected into prompts.</AcceptanceCriteria>
       <Priority>high</Priority>
-      <RelatedFlows>DF-GUARDIAN-SETTINGS</RelatedFlows>
+      <RelatedFlows>DF-MEMORY-ACCESS</RelatedFlows>
     </UC-003>
+    <UC-004>
+      <Actor>User</Actor>
+      <Action>Invokes the bundled `memory-reviewer` subagent.</Action>
+      <Goal>To audit stored memory and get keep/update/merge/delete suggestions without modifying entries.</Goal>
+      <Preconditions>The package is enabled in OpenCode and explicit memory exists in scope.</Preconditions>
+      <AcceptanceCriteria>The reviewer can only read memory tools and returns a report-only audit.</AcceptanceCriteria>
+      <Priority>medium</Priority>
+      <RelatedFlows>DF-MEMORY-REVIEW</RelatedFlows>
+    </UC-004>
   </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>
+    <item-1>No automatic memory injection into prompts.</item-1>
+    <item-2>No vector store, embeddings, or indexed retrieval in v1 memory.</item-2>
+    <item-3>No fallback compatibility with old `.opencode/guardian.jsonc` or `~/.config/opencode/guardian.jsonc` paths after the vvoc path migration.</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-2>vvoc-managed config must live under `$XDG_CONFIG_HOME/vvoc/` or project-local `.vvoc/`.</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>
+    <constraint-4>Memory must stay explicit-only. Stored entries must not be injected into prompts automatically.</constraint-4>
+    <constraint-5>Generated Guardian config should be clearly marked as CLI-managed so sync can distinguish owned and non-owned files.</constraint-5>
   </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>
+    <risk-3>The file-based memory store performs full scans and may degrade as the number of entries grows.</risk-3>
+    <risk-4>Guardian and Memory depend on OpenCode plugin and SDK surface area that may evolve over time.</risk-4>
   </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>
+    <question-1>Should future versions also manage OpenCode skills and agents as installable assets in addition to plugin config and vvoc-owned files?</question-1>
+    <question-2>Should memory eventually grow an index or vector-backed search layer once `.vvoc/memory` becomes large?</question-2>
   </OpenQuestions>
 </RequirementsAnalysis>

package/docs/technology.xml

@@ -1,39 +1,48 @@
-<TechnologyStack VERSION="0.2.0">
+<TechnologyStack VERSION="0.3.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" />
+    <dep name="@opencode-ai/plugin" version="1.3.17" purpose="Type-safe OpenCode plugin API, hooks, and custom tool helper." />
+    <dep name="@opencode-ai/sdk" version="1.3.17" purpose="OpenCode client types and runtime interactions used by Guardian and plugin logging." />
+    <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 for vvoc-managed config files and OpenCode config 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." />
+    <constraint lib="@opencode-ai/plugin" min="1.3.17" max="1.3.x" reason="Guardian and Memory depend on the current plugin hook and custom tool API shape." />
+    <constraint lib="@opencode-ai/sdk" min="1.3.17" max="1.3.x" reason="Guardian uses current SDK message, part, and client log types." />
   </VersionConstraints>
 
   <Tooling>
     <tool name="package-manager" value="bun" version="1.3.8" />
     <tool name="compiler" value="typescript" version="5.8.2" />
+    <tool name="linter" value="oxlint" version="1.58.0" />
+    <tool name="formatter" value="oxfmt" version="0.43.0" />
+    <tool name="git-hooks" value="lefthook" version="2.1.5" />
     <tool name="test-runner" value="bun test" version="1.3.8" />
   </Tooling>
 
+  <ConfigLayout>
+    <openCode>OpenCode config remains in `opencode.json(c)` or `$XDG_CONFIG_HOME/opencode/`.</openCode>
+    <vvoc>vvoc-managed config lives in `.vvoc/` or `$XDG_CONFIG_HOME/vvoc/`.</vvoc>
+    <memory>Persistent explicit memory is stored in project-local `.vvoc/memory/`.</memory>
+  </ConfigLayout>
+
   <Testing>
     <module-level>
-      <command>bun test src/lib/opencode.test.ts</command>
-      <focus>Fast deterministic checks for config merge and Guardian config rendering.</focus>
+      <command>bun test src/lib/opencode.test.ts src/plugins/memory.test.ts</command>
+      <focus>Fast deterministic checks for config layout, Guardian config rendering, memory CRUD, and reviewer agent registration.</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>
+      <command>bun run check</command>
+      <focus>Checks merged CLI and plugin behavior with lint and format verification included.</focus>
     </wave-level>
     <phase-level>
-      <command>bun run build &amp;&amp; bun test</command>
-      <focus>Validates package output and regression-safe baseline behavior.</focus>
+      <command>bun run check &amp;&amp; bun run build</command>
+      <focus>Validates package output and regression-safe baseline behavior after quality gates pass.</focus>
     </phase-level>
     <mocking-policy>Prefer direct pure-function verification and fixture text over broad mocks.</mocking-policy>
   </Testing>
@@ -46,6 +55,6 @@
   </Observability>
 
   <DeliveryShape>
-    <shape>One public npm package that exports OpenCode plugins and ships a Bun CLI binary named `vvoc`.</shape>
+    <shape>One public npm package that exports `GuardianPlugin` and `MemoryPlugin`, plus a Bun CLI binary named `vvoc`.</shape>
   </DeliveryShape>
 </TechnologyStack>