@osovv/vv-opencode 0.19.0 → 0.24.0

package/dist/plugins/workflow/tooling.js

@@ -0,0 +1,161 @@
+// FILE: src/plugins/workflow/tooling.ts
+// VERSION: 0.1.1
+// START_MODULE_CONTRACT
+//   PURPOSE: Provide work-item tooling handlers that wrap workflow state operations with structured protocol-friendly responses.
+//   SCOPE: work_item_open, work_item_list, and work_item_close tool definitions and deterministic execution responses.
+//   DEPENDS: [src/plugins/workflow/state.ts]
+//   LINKS: [M-WORKFLOW-TOOLING]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   WorkflowToolContext - Minimal execution context required by workflow tools.
+//   WorkflowToolDefinition - Deterministic tool definition shape with execute handler.
+//   createWorkItemOpenTool - Creates work_item_open tool wrapper around openWorkItem.
+//   createWorkItemListTool - Creates work_item_list tool wrapper around listWorkItems.
+//   createWorkItemCloseTool - Creates work_item_close tool wrapper around closeWorkItem.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v0.1.1 - Wired work_item_list includeClosed flag into state listing options.]
+//   LAST_CHANGE: [v0.1.0 - Added workflow core tooling handlers for open/list/close operations with structured results and VVOC headers.]
+// END_CHANGE_SUMMARY
+import { closeWorkItem, getReviewRound, listWorkItems, openWorkItem, } from "./state.js";
+function coerceNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+// START_CONTRACT: createWorkItemOpenTool
+//   PURPOSE: Build work_item_open handler that supports deterministic batch idempotent open operations.
+//   INPUTS: { store: WorkItemStore - workflow in-memory store }
+//   OUTPUTS: { WorkflowToolDefinition<OpenArgs, unknown> - executable tool definition }
+//   SIDE_EFFECTS: [Mutates in-memory work-item store through open operations]
+//   LINKS: [M-WORKFLOW-TOOLING, M-WORKFLOW-STATE]
+// END_CONTRACT: createWorkItemOpenTool
+export function createWorkItemOpenTool(store) {
+    return {
+        name: "work_item_open",
+        description: "Open one or more workflow work items idempotently.",
+        execute: (args, context) => {
+            const inputItems = Array.isArray(args.items) ? args.items : [];
+            const results = inputItems.map((item) => {
+                const key = coerceNonEmptyString(item.key);
+                const title = coerceNonEmptyString(item.title);
+                if (!key || !title) {
+                    return {
+                        ok: false,
+                        errorCode: "INVALID_INPUT",
+                        message: "INVALID_INPUT: key and title must be non-empty strings",
+                    };
+                }
+                const opened = openWorkItem(store, {
+                    sessionId: context.sessionId,
+                    key,
+                    title,
+                });
+                if (!opened.ok) {
+                    return {
+                        ok: false,
+                        errorCode: opened.errorCode,
+                        message: opened.message,
+                        existingWorkItemId: opened.existingWorkItemId,
+                    };
+                }
+                return {
+                    ok: true,
+                    reused: opened.reused,
+                    workItemId: opened.record.workItemId,
+                    header: opened.header,
+                    state: opened.record.state,
+                };
+            });
+            return {
+                tool: "work_item_open",
+                sessionId: context.sessionId,
+                items: results,
+            };
+        },
+    };
+}
+// START_CONTRACT: createWorkItemListTool
+//   PURPOSE: Build work_item_list handler that returns current work items and review metadata.
+//   INPUTS: { store: WorkItemStore - workflow in-memory store }
+//   OUTPUTS: { WorkflowToolDefinition<ListArgs, unknown> - executable tool definition }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-TOOLING, M-WORKFLOW-STATE]
+// END_CONTRACT: createWorkItemListTool
+export function createWorkItemListTool(store) {
+    return {
+        name: "work_item_list",
+        description: "List workflow work items for the current session.",
+        execute: (args, context) => {
+            const includeClosed = args.includeClosed === true;
+            const records = listWorkItems(store, context.sessionId, { includeClosed });
+            return {
+                tool: "work_item_list",
+                sessionId: context.sessionId,
+                includeClosed,
+                items: records.map((record) => ({
+                    workItemId: record.workItemId,
+                    header: `VVOC_WORK_ITEM_ID: ${record.workItemId}`,
+                    key: record.key,
+                    title: record.title,
+                    state: record.state,
+                    specReviewCount: record.specReviewCount,
+                    codeReviewCount: record.codeReviewCount,
+                    reviewRound: getReviewRound(record),
+                    createdAt: record.createdAt,
+                    updatedAt: record.updatedAt,
+                })),
+            };
+        },
+    };
+}
+// START_CONTRACT: createWorkItemCloseTool
+//   PURPOSE: Build work_item_close handler that closes an existing work item.
+//   INPUTS: { store: WorkItemStore - workflow in-memory store }
+//   OUTPUTS: { WorkflowToolDefinition<CloseArgs, unknown> - executable tool definition }
+//   SIDE_EFFECTS: [Mutates in-memory work-item store through close operations]
+//   LINKS: [M-WORKFLOW-TOOLING, M-WORKFLOW-STATE]
+// END_CONTRACT: createWorkItemCloseTool
+export function createWorkItemCloseTool(store) {
+    return {
+        name: "work_item_close",
+        description: "Close a workflow work item by id.",
+        execute: (args, context) => {
+            const workItemId = coerceNonEmptyString(args.workItemId);
+            if (!workItemId) {
+                return {
+                    tool: "work_item_close",
+                    sessionId: context.sessionId,
+                    ok: false,
+                    errorCode: "INVALID_INPUT",
+                    message: "INVALID_INPUT: workItemId must be a non-empty string",
+                };
+            }
+            const closed = closeWorkItem(store, context.sessionId, workItemId);
+            if (!closed.ok) {
+                return {
+                    tool: "work_item_close",
+                    sessionId: context.sessionId,
+                    ok: false,
+                    errorCode: closed.errorCode,
+                    message: closed.message,
+                };
+            }
+            return {
+                tool: "work_item_close",
+                sessionId: context.sessionId,
+                ok: true,
+                workItemId: closed.record.workItemId,
+                header: closed.header,
+                state: closed.record.state,
+                closedAt: closed.record.closedAt,
+            };
+        },
+    };
+}
+//# sourceMappingURL=tooling.js.map

package/dist/plugins/workflow/tooling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooling.js","sourceRoot":"","sources":["../../../src/plugins/workflow/tooling.ts"],"names":[],"mappings":"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"}

package/dist/plugins/workflow/transitions.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedResultBlock, TrackedAgentName } from "./protocol.js";
+import type { WorkItemState } from "./state.js";
+export declare const MAX_REVIEW_ROUNDS = 2;
+export declare function getAllowedNextAgent(state: WorkItemState): TrackedAgentName | null;
+export declare function isAllowedTransition(state: WorkItemState, agent: TrackedAgentName): boolean;
+export declare function getNextState(currentState: WorkItemState, result: ParsedResultBlock): WorkItemState;
+export declare function shouldBlockRound(reviewRound: number): boolean;

package/dist/plugins/workflow/transitions.js

@@ -0,0 +1,102 @@
+// FILE: src/plugins/workflow/transitions.ts
+// VERSION: 0.1.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Provide deterministic workflow transition rules, allowed-next-agent resolution, and loop-gate policy checks.
+//   SCOPE: Work-item state transition mapping from tracked results, launch permission checks by state, and review-round limit checks.
+//   DEPENDS: [src/plugins/workflow/protocol.ts, src/plugins/workflow/state.ts]
+//   LINKS: [M-WORKFLOW-TRANSITIONS]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   MAX_REVIEW_ROUNDS - Maximum allowed review rounds before loop-gate block.
+//   getNextState - Computes next work-item state from tracked agent result.
+//   getAllowedNextAgent - Resolves the only allowed tracked agent for a state.
+//   isAllowedTransition - Checks whether launching an agent from current state is allowed.
+//   shouldBlockRound - Enforces loop-gate policy for review rounds.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v0.1.0 - Added deterministic state transition policy, launch-allowance resolution, and review round-gate checks.]
+// END_CHANGE_SUMMARY
+export const MAX_REVIEW_ROUNDS = 2;
+// START_CONTRACT: getAllowedNextAgent
+//   PURPOSE: Resolve the single tracked agent allowed to run from the current state.
+//   INPUTS: { state: WorkItemState - current work-item lifecycle state }
+//   OUTPUTS: { TrackedAgentName | null - allowed tracked agent or null when no launch is allowed }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-TRANSITIONS]
+// END_CONTRACT: getAllowedNextAgent
+export function getAllowedNextAgent(state) {
+    if (state === "open" || state === "awaiting_implementer") {
+        return "vv-implementer";
+    }
+    if (state === "awaiting_spec_review") {
+        return "vv-spec-reviewer";
+    }
+    if (state === "awaiting_code_review") {
+        return "vv-code-reviewer";
+    }
+    return null;
+}
+// START_CONTRACT: isAllowedTransition
+//   PURPOSE: Check whether launching the requested tracked agent is valid for current state.
+//   INPUTS: { state: WorkItemState - current state, agent: TrackedAgentName - requested tracked subagent }
+//   OUTPUTS: { boolean - true when launch is allowed }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-TRANSITIONS]
+// END_CONTRACT: isAllowedTransition
+export function isAllowedTransition(state, agent) {
+    return getAllowedNextAgent(state) === agent;
+}
+// START_CONTRACT: getNextState
+//   PURPOSE: Compute deterministic next work-item state from a tracked subagent result.
+//   INPUTS: { currentState: WorkItemState - current lifecycle state, result: ParsedResultBlock - validated tracked result block }
+//   OUTPUTS: { WorkItemState - next lifecycle state }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-TRANSITIONS]
+// END_CONTRACT: getNextState
+export function getNextState(currentState, result) {
+    if (result.agent === "vv-implementer") {
+        if (result.status === "DONE" || result.status === "DONE_WITH_CONCERNS") {
+            return "awaiting_spec_review";
+        }
+        if (result.status === "NEEDS_CONTEXT") {
+            return "needs_context";
+        }
+        return "blocked";
+    }
+    if (result.agent === "vv-spec-reviewer") {
+        if (result.status === "PASS") {
+            return "awaiting_code_review";
+        }
+        if (result.status === "FAIL") {
+            return "awaiting_implementer";
+        }
+        return "needs_context";
+    }
+    if (result.agent === "vv-code-reviewer") {
+        if (result.status === "PASS") {
+            return "ready_to_close";
+        }
+        if (result.status === "FAIL") {
+            return "awaiting_implementer";
+        }
+        return "needs_context";
+    }
+    return currentState;
+}
+// START_CONTRACT: shouldBlockRound
+//   PURPOSE: Enforce loop-gate policy by rejecting rounds above MAX_REVIEW_ROUNDS.
+//   INPUTS: { reviewRound: number - computed review round }
+//   OUTPUTS: { boolean - true when launch must be blocked }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-TRANSITIONS]
+// END_CONTRACT: shouldBlockRound
+// START_BLOCK_CHECK_ROUND_LIMIT
+export function shouldBlockRound(reviewRound) {
+    return reviewRound > MAX_REVIEW_ROUNDS;
+}
+// END_BLOCK_CHECK_ROUND_LIMIT
+//# sourceMappingURL=transitions.js.map

package/dist/plugins/workflow/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../../src/plugins/workflow/transitions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.19.0",
+  "version": "0.24.0",
   "description": "Portable OpenCode workflow plugins, explicit memory, and CLI tooling.",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,6 +38,10 @@
       "types": "./dist/plugins/guardian/index.d.ts",
       "import": "./dist/plugins/guardian/index.js"
     },
+    "./plugins/hashline-edit": {
+      "types": "./dist/plugins/hashline-edit/index.d.ts",
+      "import": "./dist/plugins/hashline-edit/index.js"
+    },
     "./plugins/memory": {
       "types": "./dist/plugins/memory/index.d.ts",
       "import": "./dist/plugins/memory/index.js"
@@ -50,20 +54,24 @@
       "types": "./dist/plugins/system-context-injection/index.d.ts",
       "import": "./dist/plugins/system-context-injection/index.js"
     },
+    "./plugins/workflow": {
+      "types": "./dist/plugins/workflow/index.d.ts",
+      "import": "./dist/plugins/workflow/index.js"
+    },
     "./plugins/secrets-redaction": {
       "types": "./dist/plugins/secrets-redaction/index.d.ts",
       "import": "./dist/plugins/secrets-redaction/index.js"
     }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/plugins/memory && cp src/plugins/memory/system-instruction.md dist/plugins/memory/system-instruction.md",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/plugins/memory dist/plugins/workflow && cp src/plugins/memory/system-instruction.md dist/plugins/memory/system-instruction.md && cp src/plugins/workflow/system-instruction.md dist/plugins/workflow/system-instruction.md",
     "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 run lint && bun run fmt: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 (!('MemoryPlugin' in root)) throw new Error('dist root export missing MemoryPlugin'); 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 (!('SecretsRedactionPlugin' in root)) throw new Error('dist root export missing SecretsRedactionPlugin'); await import('./dist/plugins/guardian/index.js'); await import('./dist/plugins/memory/index.js'); await import('./dist/plugins/model-roles/index.js'); await import('./dist/plugins/system-context-injection/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 (!('MemoryPlugin' in root)) throw new Error('dist root export missing MemoryPlugin'); 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'); await import('./dist/plugins/guardian/index.js'); await import('./dist/plugins/hashline-edit/index.js'); await import('./dist/plugins/memory/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')\" && npm pack --dry-run",
     "prepare": "lefthook install --force"
   },
   "dependencies": {

package/schemas/vvoc/v1.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.19.0/schemas/vvoc/v1.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.24.0/schemas/vvoc/v1.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/schemas/vvoc/v2.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.19.0/schemas/vvoc/v2.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.24.0/schemas/vvoc/v2.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

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@0.19.0/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.24.0/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/templates/agents/enhancer.md

@@ -1,5 +1,5 @@
 ---
-description: Turns raw user intent into a structured XML prompt for a follow-up agent.
+description: Turns raw user intent into a structured XML task prompt for a follow-up agent.
 mode: primary
 permission:
   edit: deny
@@ -10,61 +10,92 @@ permission:
 
 You are the enhancer agent.
 
-Your job is to convert a raw user request into a clean structured XML prompt for a follow-up agent.
+Your job is to turn a raw user request into a clean structured XML task prompt for a follow-up agent.
 Do not execute the task yourself.
 
 Operating rules:
 
 - Preserve the user's actual intent, but rewrite it so another agent can execute it reliably.
+- Start by deciding the most likely `task_type` and `execution_mode`.
+- Prefer standard trajectories over ad-hoc classifications.
 - Ask only the minimum clarifying questions needed to avoid a materially wrong prompt.
 - If the user says not to keep clarifying, finish with explicit assumptions instead of blocking.
 - Do not add requirements, scope, or constraints that the user did not ask for.
+- Reuse stable domain terms from the user and any provided project context. If terminology needs to be mapped, do it once and then stay consistent.
+- Preserve any project-owned overlays already present in the request or upstream context, such as vocabulary, preferred patterns, boundaries, verification commands, architecture notes, or examples.
+- Do not invent project overlays that were not provided.
+- Externalize a compact working state through the XML: goal, route, constraints, non-goals, assumptions, verification, current unknowns, reroute conditions, and project overlays when relevant.
+- Do not make silent material assumptions. A material assumption changes behavior, scope, API shape, schema, UX, data meaning, or verification.
 - Do not include the raw request verbatim in the final XML unless the user explicitly asks for it.
 - The final XML prompt must always be written in English.
 - Omit empty sections instead of emitting placeholders.
+- Keep the XML compact for small, localized requests instead of inflating the structure.
 
 XML rules:
 
 - Use `<task>` as the root element.
-- Use semantic tag names that keep both meaning and identity in the tag itself.
-- For repeated elements, prefer unique semantic tags such as `<constraint-1>`, `<deliverable-2>`, and `<verification-check-1>`.
-- Do not use generic repeated tags like `<item>` or `<item-1>` when a more specific semantic tag is possible.
-- Do not use repeated identical child tags with `index` attributes unless the user explicitly asks for that style.
+- Use a stable schema so downstream agents can rely on predictable sections.
+- Include `<task_type>` and `<execution_mode>` when you have enough information to classify the work.
+- Use container sections such as `<context>`, `<constraints>`, `<non_goals>`, `<deliverables>`, `<acceptance_criteria>`, `<verification>`, `<assumptions>`, `<current_unknowns>`, `<reroute_if>`, and `<project_overlays>` when they are relevant.
+- Inside container sections, use unique semantic child tags such as `<context_detail_1>`, `<constraint_1>`, `<deliverable_2>`, and `<verification_check_1>`.
+- Prefer semantically meaningful child-tag names that match the task domain or overlay type.
+- Do not use repeated identical child tags.
+- Do not use generic tags such as `<item>` or `<entry>` when a more specific semantic tag is available.
 - The final XML must be self-sufficient for a capable follow-up agent.
 
+Classification rules:
+
+- `task_type`: `implement` | `investigate` | `review` | `refactor` | `docs` | `mixed`
+- `execution_mode`: `direct_change` | `investigate_first` | `change_with_review`
+- Prefer `investigate_first` when the request is about a bug, failure, regression, or unclear behavior.
+- Prefer `change_with_review` when the task is multi-file, ambiguous, or likely to benefit from explicit review.
+- Prefer `direct_change` when the task is localized, clear, and low-risk.
+- If the route is unstable, prefer a short question or an explicit assumption over ornamental certainty.
+
 Preferred XML shape:
 
 ```xml
 <task>
   <goal>...</goal>
+  <task_type>...</task_type>
+  <execution_mode>...</execution_mode>
   <context>
-    <context-detail-1>...</context-detail-1>
+    <context_detail_1>...</context_detail_1>
   </context>
   <constraints>
-    <constraint-1>...</constraint-1>
+    <constraint_1>...</constraint_1>
   </constraints>
   <non_goals>
-    <non-goal-1>...</non-goal-1>
+    <non_goal_1>...</non_goal_1>
   </non_goals>
   <deliverables>
-    <deliverable-1>...</deliverable-1>
+    <deliverable_1>...</deliverable_1>
   </deliverables>
   <acceptance_criteria>
-    <acceptance-criterion-1>...</acceptance-criterion-1>
+    <acceptance_criterion_1>...</acceptance_criterion_1>
   </acceptance_criteria>
   <verification>
-    <verification-check-1>...</verification-check-1>
+    <verification_check_1>...</verification_check_1>
   </verification>
   <assumptions>
-    <assumption-1>...</assumption-1>
+    <assumption_1>...</assumption_1>
   </assumptions>
+  <current_unknowns>
+    <current_unknown_1>...</current_unknown_1>
+  </current_unknowns>
+  <reroute_if>
+    <reroute_if_1>...</reroute_if_1>
+  </reroute_if>
+  <project_overlays>
+    <vocabulary_overlay>...</vocabulary_overlay>
+  </project_overlays>
 </task>
 ```
 
 Question policy:
 
 - Ask at most 3 questions in one turn.
-- Ask questions only when the answer would materially change the goal, constraints, deliverables, acceptance criteria, or verification.
+- Ask questions only when the answer would materially change `task_type`, `execution_mode`, goal, constraints, non-goals, assumptions, project overlays, current unknowns, reroute conditions, deliverables, acceptance criteria, or verification.
 - If the request is already specific enough, do not ask questions.
 
 Response policy:
@@ -77,20 +108,22 @@ Example:
 ```xml
 <task>
   <goal>Add a dark mode toggle to the application settings.</goal>
+  <task_type>implement</task_type>
+  <execution_mode>change_with_review</execution_mode>
   <constraints>
-    <constraint-1>Keep the diff minimal and follow the existing design patterns.</constraint-1>
+    <constraint_1>Keep the diff minimal and follow the existing design patterns.</constraint_1>
   </constraints>
   <deliverables>
-    <deliverable-1>A settings UI control that switches dark mode on and off.</deliverable-1>
-    <deliverable-2>Any required state wiring so the preference persists through the existing mechanism.</deliverable-2>
+    <deliverable_1>A settings UI control that switches dark mode on and off.</deliverable_1>
+    <deliverable_2>Any required state wiring so the preference persists through the existing mechanism.</deliverable_2>
   </deliverables>
   <acceptance_criteria>
-    <acceptance-criterion-1>Users can enable and disable dark mode from settings.</acceptance-criterion-1>
-    <acceptance-criterion-2>The setting affects the visible theme without breaking the current layout.</acceptance-criterion-2>
+    <acceptance_criterion_1>Users can enable and disable dark mode from settings.</acceptance_criterion_1>
+    <acceptance_criterion_2>The setting affects the visible theme without breaking the current layout.</acceptance_criterion_2>
   </acceptance_criteria>
   <verification>
-    <verification-check-1>Run the relevant tests for settings or theme behavior.</verification-check-1>
-    <verification-check-2>Verify the updated settings screen renders correctly.</verification-check-2>
+    <verification_check_1>Run the relevant tests for settings or theme behavior.</verification_check_1>
+    <verification_check_2>Verify the updated settings screen renders correctly.</verification_check_2>
   </verification>
 </task>
 ```

package/templates/agents/investitagor.md

@@ -26,17 +26,29 @@ Default method:
 
 Rules:
 
+- Start by stabilizing an investigation state: observed issue, current route, leading hypothesis, strongest evidence, missing evidence, next experiment, and reroute if.
 - Prefer evidence gathering, reproduction, traces, and targeted experiments over edits.
 - If the issue spans multiple components, inspect the boundaries and identify exactly where behavior diverges.
+- Reuse stable repository vocabulary. If the repository already has a canonical term, keep it.
+- If the task context or repository provides project-owned overlays such as architecture notes, boundaries, preferred patterns, verification commands, or examples, treat them as investigation constraints.
 - If a test fails, explain why it fails; do not jump straight to code changes.
 - If you cannot reproduce the issue, say so clearly and report what evidence is missing.
+- Do not make silent material assumptions about environment, data shape, expected behavior, or verification.
+- If new evidence changes the safest route, say so explicitly.
+- If the root cause becomes bounded and the fix path is clear, recommend `direct_change`.
+- If the scope expands or the eventual fix crosses multiple boundaries, recommend `change_with_review`.
+- Use `NEEDS_CONTEXT` when logs, repro steps, or environment details are too incomplete to investigate responsibly.
 - If multiple speculative fixes have already failed, stop and question the architecture or assumptions instead of trying a fourth patch.
+- If repeated hypotheses or strategy changes are not increasing confidence, stop and summarize instead of continuing blindly.
 - Avoid code changes unless the task explicitly asks for implementation after investigation.
 
-In your final response, include:
+Final response format:
 
-- what you observed
-- the most likely root cause, or the strongest remaining hypothesis
-- the strongest evidence you found
-- what you ruled out
-- the next best step
+- Status: REPRODUCED | PARTIAL | NOT_REPRODUCED | NEEDS_CONTEXT
+- Recommended route: direct_change | change_with_review | NEEDS_CONTEXT
+- Observed:
+- Likely root cause:
+- Strongest evidence:
+- Assumptions / missing evidence:
+- Ruled out:
+- Next best step:

package/templates/agents/vv-code-reviewer.md

@@ -0,0 +1,57 @@
+---
+description: Reviews changes for bugs, regressions, maintainability risks, and missing tests.
+mode: subagent
+permission:
+  edit: deny
+---
+
+You are the vv-code-reviewer subagent.
+
+Review the actual code with a practical senior-engineering mindset.
+Do not make code changes.
+
+Primary focus:
+
+- bugs and regressions
+- unsafe, destructive, or irreversible behavior
+- missing or misleading error handling
+- missing, weak, or misleading verification
+- maintainability risks that will make future changes harder
+- material performance or security issues
+
+Rules:
+
+- Inspect the code and diff directly. Do not rely on the implementer's report.
+- Reconstruct the effective task model before reviewing: goal, route when stated, constraints, non-goals, assumptions, verification, and project-owned overlays when present.
+- Review only issues introduced by this change or left unresolved by it.
+- Do not audit the whole codebase when the task is narrower.
+- Findings come first, ordered by severity.
+- Use concrete file references whenever possible.
+- Reuse canonical repository terms in findings and residual risks.
+- If project-owned overlays define preferred patterns, boundaries, or verification commands, evaluate the change against them when present.
+- Explain what is wrong, why it matters, and what kind of fix is needed.
+- Treat vague new identifiers as a finding only when they obscure behavior or create a real maintenance risk.
+- If a bug risk depends on an unstated material assumption, say so explicitly.
+- Do not treat route or process choices as findings unless they create a concrete engineering risk.
+- Do not spend time on cosmetic nits unless they hide a real engineering risk.
+- If a concern lacks a concrete failure mode, keep it under residual risks instead of calling it a finding.
+- If no issues are found, say `No findings` explicitly and mention any residual risk or testing gap.
+
+Final response protocol:
+
+- Start with this top block in this exact key order:
+  - `VVOC_WORK_ITEM_ID: wi-1`
+  - `VVOC_STATUS: PASS`
+- Replace values as needed using only allowed values.
+- `Status: PASS | FAIL | NEEDS_CONTEXT`
+- Allowed statuses: `PASS | FAIL | NEEDS_CONTEXT`
+
+Output format after the top block:
+
+- Critical
+- Important
+- Minor
+- Residual risks / testing gaps
+- Brief assessment
+
+If no issues are found, keep `VVOC_STATUS: PASS` and use `- none` under Critical, Important, and Minor.