refactor(prompts): deduplicate vv-controller template sections against universal injection

src/lib/managed-agents.test.ts

@@ -2,7 +2,7 @@
 // VERSION: 0.8.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Verify vvoc-managed agent prompt template loading, scoped runtime lookup, and correctness-obligation instruction contracts.
-//   SCOPE: Bundled template reads, profile-neutral controller invariants, controller correctness leadership with settled-conclusion reopen triggers, false-premise handling, and stop/recovery distinction with reserved handoffs, bounded implementer impact investigation with worker-stop semantics, settled evidence, false-premise escalation, and reviewer-finding conflict routing, evidence-based reviewer verdicts with initial-versus-scoped-re-review guidance, investigator property reporting, primary/subagent metadata checks, semantic agreement of the shipped tracked-result protocol examples with the runtime parser, scoped prompt resolution, and missing prompt failures.
+//   SCOPE: Bundled template reads, profile-neutral controller invariants, the controller template dedup contract that leaves working_state, assumption_discipline, editing_workflow, and reroute_on_evidence to the plugin's universal injection, controller correctness leadership, stop/recovery distinction with reserved handoffs, bounded implementer impact investigation with worker-stop semantics, settled evidence, false-premise escalation, and reviewer-finding conflict routing, evidence-based reviewer verdicts with initial-versus-scoped-re-review guidance, investigator property reporting, primary/subagent metadata checks, semantic agreement of the shipped tracked-result protocol examples with the runtime parser, scoped prompt resolution, and missing prompt failures.
 //   DEPENDS: [bun:test, node:fs/promises, node:os, node:path, src/lib/managed-agents.ts, src/lib/vvoc-paths.ts, src/plugins/workflow/protocol.ts]
 //   LINKS: [M-CLI-MANAGED-AGENTS, M-WORKFLOW-PROTOCOL, V-M-CLI-MANAGED-AGENTS]
 //   ROLE: TEST
@@ -16,7 +16,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-WORKFLOW-PROMPT-SYNC-DOCTOR-ARCHIVE T-001 - Worker templates now copy the assignment header and state that the controller owns work-item lifecycle; the shipped protocol examples remain parser-validated.]
+//   LAST_CHANGE: [Instruction deduplication - The vv-controller template contract now asserts the dedup contract (no working_state, assumption_discipline, editing_workflow, or reroute_on_evidence copies; the plugin's universal sections are the single source) and drops assertions on the removed template wordings.]
 // END_CHANGE_SUMMARY
 
 import { describe, expect, test } from "bun:test";
@@ -114,10 +114,6 @@ describe("managed agent prompts", () => {
     expect(template).toContain("You are the vv-controller primary agent.");
     expect(MANAGED_PRIMARY_AGENT_NAMES.filter((name) => name === "vv-controller")).toHaveLength(1);
     expect(template).toContain("<core_principles>");
-    expect(template).toContain("<working_state>");
-    expect(template).toContain("<assumption_discipline>");
-    expect(template).toContain("<editing_workflow>");
-    expect(template).toContain("<reroute_on_evidence>");
     expect(template).toContain("<skill_trigger_rule>");
     expect(template).toContain("<source_and_authority>");
     expect(template).toContain("<stop_and_recovery>");
@@ -129,6 +125,17 @@ describe("managed agent prompts", () => {
     expect(template).toContain("`vv-execute` validates an approved plan");
     expect(template).toContain("follows the mode selected by the user");
 
+    // The four formerly duplicated sections are owned by the plugin's universal
+    // injection; the bundled template must not carry competing copies.
+    for (const deduplicatedSection of [
+      "<working_state>",
+      "<assumption_discipline>",
+      "<editing_workflow>",
+      "<reroute_on_evidence>",
+    ]) {
+      expect(template).not.toContain(deduplicatedSection);
+    }
+
     for (const inactivePolicyTerm of [
       "direct_change",
       "change_with_review",
@@ -190,7 +197,9 @@ describe("managed agent prompts", () => {
     const template = await loadManagedAgentPromptTemplate("vv-controller");
     const normalized = template.replace(/\s+/g, " ");
 
-    expect(normalized).toContain("Surface a false premise instead of silently satisfying it");
+    // working_state, assumption_discipline, and reroute_on_evidence wording now
+    // lives only in the plugin's universal injection; the assertions below cover
+    // the sections this template still carries.
     expect(normalized).toContain(
       "Distinguish unsupported disagreement or authority pressure from concrete new evidence",
     );
@@ -200,12 +209,6 @@ describe("managed agent prompts", () => {
     expect(normalized).toContain(
       "route an explicit user change in requirements through the existing scope and approval process rather than a factual debate",
     );
-    expect(normalized).toContain(
-      "Reopen a settled conclusion or reroute on concrete triggers only",
-    );
-    expect(normalized).toContain(
-      "Vague doubt or unsupported pressure is not itself a trigger, but required checks still run — an unchecked claim is not settled",
-    );
     expect(normalized).toContain(
       "Move forward once the required checks substantiate the material claims for the current files and inputs",
     );

src/lib/managed-agents.ts

@@ -2,7 +2,7 @@
 // VERSION: 0.4.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Describe vvoc-managed OpenCode agent prompts and load them from bundled templates or scoped vvoc config roots.
-//   SCOPE: Built-in primary/subagent metadata, managed prompt names, prompt file path resolution, bundled template loading, and project/global prompt lookup.
+//   SCOPE: Built-in primary/subagent metadata, managed prompt names, prompt file path resolution, bundled template loading (the vv-controller template delegates its working_state, assumption_discipline, editing_workflow, and reroute_on_evidence sections to the system-context-injection plugin's universal sections as their single source), and project/global prompt lookup.
 //   DEPENDS: [node:fs/promises, node:path, src/lib/vvoc-paths.ts]
 //   LINKS: M-CLI-MANAGED-AGENTS, M-CLI-CONFIG, M-PLUGIN-GUARDIAN
 //   ROLE: RUNTIME
@@ -37,7 +37,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v0.5.0 - Removed two creative-role managed subagents. Only executor subagents remain.]
+//   LAST_CHANGE: [Instruction deduplication - The bundled vv-controller template no longer carries working_state, assumption_discipline, editing_workflow, or reroute_on_evidence; the system-context-injection plugin's universal sections are their single source.]
 // END_CHANGE_SUMMARY
 
 import { readFile } from "node:fs/promises";

src/plugins/system-context-injection.integration.test.ts

@@ -2,8 +2,8 @@
 // VERSION: 2.0.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Verify native universal primary guidance injection, including correctness obligations and evidence discipline, and bound-family concrete vv-controller orchestration policy injection into native system parts.
-//   SCOPE: Correctness-obligations delivery, settled-conclusion reopen triggers, false-premise handling, pressure-versus-evidence distinction, per-profile controller context, primary isolation, explore guidance, built-in/managed/configured subagent exclusion, duplicate prevention, native-registry mode exclusion, and unknown/disabled no-op.
-//   DEPENDS: [bun:test, src/lib/orchestration.ts, src/lib/vvoc-config.ts, src/plugins/system-context-injection/index.ts]
+//   SCOPE: Correctness-obligations delivery, settled-conclusion reopen triggers, false-premise handling, pressure-versus-evidence distinction, per-profile controller context, primary isolation, explore guidance, built-in/managed/configured subagent exclusion, duplicate prevention, assembled vv-controller template plus injection dedup with each universal section exactly once and the merged template-only editing_workflow lines, native-registry mode exclusion, and unknown/disabled no-op.
+//   DEPENDS: [bun:test, src/lib/managed-agents.ts, src/lib/orchestration.ts, src/lib/vvoc-config.ts, src/plugins/system-context-injection/index.ts]
 //   LINKS: [M-PLUGIN-SYSTEM-CONTEXT-INJECTION, M-ORCHESTRATION-PROFILES, V-M-PLUGIN-SYSTEM-CONTEXT-INJECTION]
 //   ROLE: TEST
 //   MAP_MODE: LOCALS
@@ -19,11 +19,12 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-SNAPSHOT-ANCHORING-REDESIGN T-007 - Static guidance is asserted in the system prefix while the variable orchestration policy is asserted at the request tail.]
+//   LAST_CHANGE: [Instruction deduplication - The injected editing_workflow section absorbed the template-only contract-reading and speculative-reroute lines, and an assembled vv-controller template plus injection test pins each formerly duplicated universal section to exactly one occurrence.]
 // END_CHANGE_SUMMARY
 
 import { describe, expect, test } from "bun:test";
 import type { OrchestrationProfile } from "../lib/orchestration.js";
+import { loadManagedAgentPromptTemplate } from "../lib/managed-agents.js";
 import { createDefaultVvocConfig, type VvocConfig } from "../lib/vvoc-config.js";
 import { createSystemContextInjectionPlugin } from "./system-context-injection/index.js";
 
@@ -375,6 +376,36 @@ describe("SystemContextInjectionPlugin", () => {
     expect(tail.match(/Keep architecture, critical code reading/g)).toHaveLength(1);
   });
 
+  test("assembled vv-controller template plus injection keeps each universal section once", async () => {
+    const harness = await makeHarness({ profile: "balanced" });
+    const handler = harness.hooks.get("context");
+    if (handler === undefined) throw new Error("no context hook registered");
+    const template = await loadManagedAgentPromptTemplate("vv-controller");
+    const event: NativeContextEvent = {
+      sessionID: "session-vv-controller-assembled",
+      agent: "vv-controller",
+      system: [{ type: "text", text: template }],
+      messages: [{ role: "user", content: [] }],
+    };
+    await handler(event);
+
+    const system = systemText(event);
+    // The bundled vv-controller template carries no copies of the four formerly
+    // duplicated sections; the universal injection is their single source, so
+    // the assembled system contains each tag exactly once.
+    for (const tag of [
+      "<working_state>",
+      "<assumption_discipline>",
+      "<editing_workflow>",
+      "<reroute_on_evidence>",
+    ]) {
+      expect(system.split(tag).length - 1).toBe(1);
+    }
+    expect(system).toContain(
+      "Reserve `bash` for tests, builds, git, and other non-file-edit commands.",
+    );
+  });
+
   test("skips plugin-managed and managed subagents", async () => {
     const harness = await makeHarness();
     for (const agent of ["guardian", "vv-implementer"]) {
@@ -468,6 +499,12 @@ describe("SystemContextInjectionPlugin", () => {
     expect(text).toContain(
       "Reserve `bash` for tests, builds, git, and other non-file-edit commands.",
     );
+    expect(text).toContain(
+      "Before editing, understand the relevant local contract, nearby tests, and surrounding code.",
+    );
+    expect(text).toContain(
+      "If direct editing reveals unclear behavior or unexpectedly broad scope, stop and reroute instead of continuing speculatively.",
+    );
     expect(text).toContain(
       "inspect relevant index entries before debugging, fixing, changing behavior, operating on, architecting, or investigating repository-specific issues.",
     );

src/plugins/system-context-injection/index.ts

@@ -2,7 +2,7 @@
 // VERSION: 2.1.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Inject universal primary guidance, including correctness obligations and evidence discipline for behavior changes, and one bound-family-resolved concrete orchestration policy into vv-controller without polluting subagent prompts, through the native session context hook.
-//   SCOPE: Universal instructions with correctness obligations, material-assumption discipline, settled-conclusion reopen triggers, false-premise handling, and pressure-versus-evidence distinction; vv-controller policy selection from the immutable captured family config; the explore-subagent guidance exception even though native registry mode is subagent; built-in, managed and native-registry subagent exclusion for every other agent; internal title/summary/compaction exclusion; per-request agent-mode reads that never poison on transient failure; idempotent injection into native system parts; lifecycle cleanup. Skill-path registration is NOT delivered here: the old runtime config.skills.paths registration has no native plugin config-transform surface, and the native document `skills: string[]` install/sync writes are owned by T007.
+//   SCOPE: Universal instructions with correctness obligations, material-assumption discipline, settled-conclusion reopen triggers, false-premise handling, and pressure-versus-evidence distinction, which are the single source for the vv-controller bundled template's working_state, assumption_discipline, editing_workflow, and reroute_on_evidence sections (the bundled template no longer carries them); vv-controller policy selection from the immutable captured family config; the explore-subagent guidance exception even though native registry mode is subagent; built-in, managed and native-registry subagent exclusion for every other agent; internal title/summary/compaction exclusion; per-request agent-mode reads that never poison on transient failure; idempotent injection into native system parts; lifecycle cleanup. Skill-path registration is NOT delivered here: the old runtime config.skills.paths registration has no native plugin config-transform surface, and the native document `skills: string[]` install/sync writes are owned by T007.
 //   DEPENDS: [@opencode/plugin, src/lib/managed-agents.ts, src/lib/orchestration.ts, src/runtime/context.ts, src/runtime/types.ts]
 //   LINKS: [M-PLUGIN-SYSTEM-CONTEXT-INJECTION, M-ORCHESTRATION-PROFILES, M-CLI-MANAGED-AGENTS, M-NATIVE-RUNTIME, V-M-PLUGIN-SYSTEM-CONTEXT-INJECTION]
 //   ROLE: RUNTIME
@@ -17,7 +17,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-SNAPSHOT-ANCHORING-REDESIGN T-007 - Static primary guidance stays in the system prefix while the variable orchestration policy is injected at the tail of the last user message only, so a profile change does not invalidate the cached prefix and tool/assistant messages keep their provider payload shape.]
+//   LAST_CHANGE: [Instruction deduplication - The universal working_state, assumption_discipline, editing_workflow, and reroute_on_evidence sections are now the single source for vv-controller: the bundled template no longer carries them, and the editing_workflow section absorbed the template-only contract-reading and speculative-reroute lines.]
 // END_CHANGE_SUMMARY
 
 import { SystemPart } from "@opencode/ai";
@@ -91,9 +91,11 @@ const UNIVERSAL_PRIMARY_SYSTEM_CONTEXTS = [
   ].join("\n"),
   [
     "<editing_workflow>",
+    "Before editing, understand the relevant local contract, nearby tests, and surrounding code.",
     "When editing files, prefer the `edit` tool over shell-based rewrites when it is available.",
     "Read the file first, then use exact `line#hash#anchor` refs from the latest `read` output when present.",
     "Reserve `bash` for tests, builds, git, and other non-file-edit commands.",
+    "If direct editing reveals unclear behavior or unexpectedly broad scope, stop and reroute instead of continuing speculatively.",
     "</editing_workflow>",
   ].join("\n"),
   [

templates/agents/vv-controller.md

@@ -25,21 +25,6 @@ report the outcome.
   to alternative orchestration rules.
 </core_principles>
 
-<working_state>
-For non-trivial work, stabilize a compact working state before acting: goal, current approach,
-constraints, relevant non-goals, assumptions, verification target, current unknown, and reroute-if
-trigger. Keep it current and surface it when blocked, rerouting, or handing off.
-</working_state>
-
-<assumption_discipline>
-- Do not make silent material assumptions.
-- If an assumption is required, state it and explain its behavioral effect.
-- If fresh evidence makes a material assumption false, stop and reroute.
-- Surface a false premise instead of silently satisfying it: when the request assumes a library, file, or
-  behavior that does not exist, investigate the actual mechanism, and continue only if the original goal
-  stays unambiguous and within the approved scope.
-</assumption_discipline>
-
 <evidence_and_scope>
 - Gather enough repository evidence before acting on unfamiliar code.
 - Prefer existing project patterns, libraries, contracts, and established structure over novel
@@ -76,25 +61,6 @@ trigger. Keep it current and surface it when blocked, rerouting, or handing off.
   review, and explicit acceptance intact.
 </correctness_leadership>
 
-<editing_workflow>
-- Before editing, understand the relevant local contract, nearby tests, and surrounding code.
-- When editing files, prefer the dedicated edit tool over shell-based rewrites when available.
-- Read a file before editing it and use current context-anchored references when the tool requires
-  them.
-- Reserve shell commands for tests, builds, version control, and other non-file-edit operations.
-- If direct editing reveals unclear behavior or unexpectedly broad scope, stop and reroute instead
-  of continuing speculatively.
-</editing_workflow>
-
-<reroute_on_evidence>
-When new evidence invalidates the current approach, state the trigger, the next safe approach, and
-why continuing the previous one is unsafe. Reroute when root cause or expected behavior remains
-unclear, scope crosses an unexpected boundary, or requirement ambiguity blocks safe progress.
-Reopen a settled conclusion or reroute on concrete triggers only: contradictory evidence, a specific
-error or counterexample, changed requirements, or changed relevant inputs. Vague doubt or unsupported
-pressure is not itself a trigger, but required checks still run — an unchecked claim is not settled.
-</reroute_on_evidence>
-
 <skill_trigger_rule>
 - `vv-spec` interviews the user, proposes a design, and creates an approved specification.
 - `vv-plan` creates an implementation plan from an approved specification and does not implement.