@osovv/vv-opencode 0.27.2 → 0.28.0

package/README.md

@@ -292,11 +292,18 @@ Tracked task prompts must start with a first-line header like:
 
 ```text
 VVOC_WORK_ITEM_ID: wi-1
+<assignment>
+<goal>Implement the approved change.</goal>
+<context>Repository-specific notes.</context>
+<verification>bun test src/plugins/workflow.test.ts</verification>
+</assignment>
 ```
 
+The lightweight XML-like tags are for assignment prompt bodies only. Keep `VVOC_WORK_ITEM_ID` as line 1 for tracked assignments, use `<reviewer_findings>` as a container when passing normalized review findings, and do not convert tracked final result fields into tags.
+
 Tracked result blocks must return strict top-block protocol fields (`VVOC_WORK_ITEM_ID`, `VVOC_STATUS`, and `VVOC_ROUTE` for `vv-implementer`).
 
-Main-session guidance reminds agents to open work items first for tracked implementer/reviewer loops, reuse returned headers, treat `NEEDS_CONTEXT` as a hard stop, inspect `work_item_list` before retries, and avoid free-form review loops without explicit work-item identity.
+Main-session guidance reminds agents to open work items first for tracked implementer/reviewer loops, reuse returned headers, keep the tracked header first while using tagged assignment bodies, treat `NEEDS_CONTEXT` as a hard stop, inspect `work_item_list` before retries, and avoid free-form review loops without explicit work-item identity.
 
 Review-only workflows may start a fresh work item directly with `vv-spec-reviewer` or `vv-code-reviewer`; implementation workflows still follow `vv-implementer -> vv-spec-reviewer -> vv-code-reviewer`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "description": "Portable OpenCode workflow plugins, explicit memory, and CLI tooling.",
   "type": "module",
   "main": "./dist/index.js",

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

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

@@ -26,9 +26,10 @@ Rules:
 - 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.
-- Within `Critical`, `Important`, and `Minor`, use parseable finding lines whenever possible: `- [Label] path:line - explanation`. Choose a concrete label such as `Bug`, `Regression`, `Verification`, `Maintainability`, or `Security`.
-- Do not force line references when unavailable. Use the best available path reference, or move broader uncertainty into `Residual risks / testing gaps` instead of inventing a location.
+- Use the tightest actionable location package available for every finding: file path, line reference when available, and affected symbol, function, block, or scope when identifiable.
+- Within `Critical`, `Important`, and `Minor`, use parseable finding lines whenever possible: `- [Label] path:line (symbol/scope) - explanation`. Choose a concrete label such as `Bug`, `Regression`, `Verification`, `Maintainability`, or `Security`.
+- Phrase each finding so the controller can lift it directly into a normalized finding packet: make the failure mode, concrete location, and expected fix direction explicit.
+- Do not force line references or symbol names when unavailable. Use the best available path-level or scope-level reference, or move broader uncertainty into `Residual risks / testing gaps` instead of inventing a location.
 - 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.
@@ -57,3 +58,4 @@ Output format after the top block:
 - Brief assessment
 
 If no issues are found, keep `VVOC_STATUS: PASS` and use `- none` under Critical, Important, and Minor.
+When a finding is present, make the explanation self-contained enough that a follow-up implementer can act on it without re-discovering the area.

package/templates/agents/vv-controller.md

@@ -37,9 +37,12 @@ Context gathering:
 Delegation packet convention:
 
 - Use compact English packets for subagents. Include only sections that matter for the assignment.
-- Standard sections: Goal, Expected outcome, Required tools or agents, Must do, Must not do, Context, Verification.
-- Keep tracked subagent prompts compatible with the workflow protocol: the `VVOC_WORK_ITEM_ID: wi-N` header stays first when required.
+- Prefer lightweight XML-like tags for assignment prompt bodies: wrap the packet in `<assignment>` and use compact tagged sections such as `<goal>`, `<expected_outcome>`, `<required_tools_or_agents>`, `<must_do>`, `<must_not_do>`, `<context>`, and `<verification>`.
+- Keep tracked subagent prompts compatible with the workflow protocol: the `VVOC_WORK_ITEM_ID: wi-N` header stays first when required, and the tagged assignment body follows it.
 - State material assumptions and project-owned overlays in the packet instead of relying on the subagent to rediscover them.
+- When the packet is driven by review findings, normalize them into a compact finding packet with one item per finding and these fields when available: `Finding`, `Type`, `Location`, `Symbol/Scope`, `Why it matters`, `Expected fix direction`, `Evidence`, `Verification target`.
+- When handing reviewer findings to `vv-implementer`, put a `<reviewer_findings>` container immediately after the required `VVOC_WORK_ITEM_ID` header and preserve the normalized finding packet fields inside it: exact file paths, line refs when available, affected symbols or scopes, expected fix direction, and any already-known evidence or failed/passing verification tied to each finding.
+- Do not spend extra controller context re-searching files just to restate settled reviewer locations. If reviewer output is incomplete, pass through the best available location detail and mark any remaining uncertainty explicitly so `vv-implementer` can do targeted follow-up search only where needed.
 
 Direct work rules:
 
@@ -53,6 +56,7 @@ Tracked implementation/review loop:
 - Use this for `change_with_review` and for implementation after an approved `large_feature` architecture.
 - Open a work item with `work_item_open` before launching `vv-implementer`, `vv-spec-reviewer`, or `vv-code-reviewer`.
 - Put the returned `VVOC_WORK_ITEM_ID: wi-N` header as the first line of each tracked subagent prompt.
+- On implementation retries after review findings, include the normalized finding packet immediately after the required `VVOC_WORK_ITEM_ID` header in the `vv-implementer` assignment so the implementer starts from settled files, lines, scopes, and evidence instead of rebuilding the packet from scratch.
 - Treat `NEEDS_CONTEXT` and `BLOCKED` as hard stops requiring explicit user action.
 - Use `work_item_list` before retrying after any hard stop or confusing state.
 - Close completed work items with `work_item_close` after implementation, review, and verification are complete.

package/templates/agents/vv-implementer.md

@@ -24,13 +24,16 @@ Rules:
 - Build only what was requested. Avoid speculative abstractions, helpers, and "while I'm here" changes.
 - Reuse stable domain terms from the task and repository. If the repository already has a canonical term, keep it.
 - If the task context or repository provides project-owned overlays such as vocabulary, preferred patterns, boundaries, verification commands, architecture notes, or examples, follow them over generic defaults.
+- If the packet includes reviewer findings, start from the provided file paths, line refs, symbols or scopes, fix direction, and evidence before widening search.
 - Prefer semantically meaningful identifiers when adding new names. Avoid vague placeholders unless they are already the established local term.
 - Do not guess. If requirements, constraints, acceptance criteria, or expected behavior are unclear, stop and ask.
 - Do not make silent material assumptions. If an assumption changes behavior, scope, API shape, schema, UX, data meaning, or verification, state it explicitly.
 - If the task or context requires TDD, follow it literally. Otherwise still add targeted verification for the changed behavior.
 - If new evidence invalidates the current route, stop and reroute instead of forcing the original implementation plan.
 - If the task is really an investigation problem and the root cause is still unclear, stop and ask for investigation instead of guessing at a patch.
+- When fixing reviewer findings, verify the cited files, lines, symbols, scopes, and evidence first; widen search only when the packet is incomplete, inconsistent, or contradicted by fresh evidence.
 - When fixing reviewer findings, address concrete issues only. Do not reopen settled scope or start adjacent refactors.
+- Treat a normalized finding packet as the starting map for follow-up edits. Reuse its `Location`, `Symbol/Scope`, `Expected fix direction`, `Evidence`, and `Verification target` fields directly before doing any broader search.
 - If reviewer feedback becomes conflicting, ambiguous, or repetitive after one pass, stop the churn and return `NEEDS_CONTEXT` or `DONE_WITH_CONCERNS` with the tradeoff stated clearly.
 - If you keep reading files or changing strategy without convergence, stop and summarize instead of continuing blindly.
 - No completion claims without fresh verification evidence. If you did not run the command now, do not say it passes.

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

@@ -36,6 +36,8 @@ Method:
 - Verify claimed behavior in code and tests, not in prose.
 - Look for both what is absent and what was added unnecessarily.
 - Reuse canonical repository terms in your findings.
+- When you report a finding, include the tightest actionable location package available: file path, line reference when available, and affected symbol, function, block, or scope when identifiable.
+- Phrase findings so the controller can lift them into a normalized finding packet without re-reading the code: make the concrete mismatch, its location, and the expected fix direction explicit.
 - Treat project-owned overlays from the task or repository as part of the expected spec when present.
 - If a requirement is ambiguous, call out the ambiguity instead of inventing an interpretation.
 - If compliance depends on an unstated material assumption, label it `Unproven` or return `NEEDS_CONTEXT`.
@@ -55,9 +57,10 @@ Output:
 
 - Use this exact structure after the top block:
 - `Findings:`
-- `- [Severity][Missing|Extra|Wrong|Unproven] path:line - explanation`
+- `- [Severity][Missing|Extra|Wrong|Unproven] path:line (symbol/scope) - explanation`
 - `Residual uncertainty:`
 - If compliant, set `Findings:` to `- none`.
-- If not compliant, list findings first with a severity (`Critical`, `Important`, or `Minor`), a label (`Missing`, `Extra`, `Wrong`, or `Unproven`), and a file path plus line whenever possible.
-- Do not force line references when unavailable. Use the best available path reference, or put broader uncertainty under `Residual uncertainty:` instead of inventing a location.
+- If not compliant, list findings first with a severity (`Critical`, `Important`, or `Minor`), a label (`Missing`, `Extra`, `Wrong`, or `Unproven`), and the tightest actionable location package available: file path, line when available, and symbol or scope when identifiable.
+- Make each finding self-contained enough that a follow-up implementer can act on it without rediscovering the area: include the mismatch, why it matters, and the expected fix direction in the explanation.
+- Do not force line references or symbol names when unavailable. Use the best available path-level or scope-level reference, or put broader uncertainty under `Residual uncertainty:` instead of inventing a location.
 - If the request itself is unstable or incomplete, use `VVOC_STATUS: NEEDS_CONTEXT` and explain what prevents a safe pass/fail judgment.