Vc Autoresearch

PVL Wiring

When vc-autoresearch is the bookkeeper for a PVL (plan-validate-fix loop):

• domain: plan, corpus: = the plan .md file
• Research step = vc-validate-agent runs V1–V3 gates; autoresearch does NOT run these itself. The validate step itself fans out in parallel via vc-validate-findings (Layer 1 dimension agents + Layer 2 feasibility agents) — that parallelism is owned by vc-validate-agent.
• Gap signal = FAIL / CONDITIONAL / CONCERN from validate-agent
• Fix step (parallel) = when the gap set spans independent plan sections, the orchestrator spawns multiple parallel plan-fix agents, one per independent gap group, partitioned so no two agents edit the same plan region. fix_agents: defaults to the count of independent gap groups (cap to the plan-domain default unless raised). Each fixer is scoped to its assigned gap IDs only. When gaps are interdependent or touch one section, fall back to a single plan-fix agent.
• Convergence = validate-agent returns PASS → SUCCESS
• Cap = 10 plan-validate-fix loops
• Per-cycle report = every PVL cycle writes its own report file {task_folder}/{plan-slug}-pvl-iteration-{NNN}_REPORT_{dd-mm-yy}.md (zero-padded {NNN}) capturing: gaps found (with severity), fixes applied vs backlogged, and the validate verdict for that cycle. Never a single rolling notes file.

Boundary:

• vc-autoresearch owns: iteration counter, plateau detection, per-cycle iteration report, regression flag, parallel-fix partitioning (which gap groups go to which fixer) — all executed by the ORCHESTRATOR at each cycle boundary; no agent runs these implicitly
• vc-validate-agent owns: V1–V7 gate sequence + its own Layer-1/Layer-2 fan-out, SUPPLEMENT REQUEST format, validate-contract write, known-gap exclusion — it emits its verdict and terminates; the orchestrator re-spawns it from V1 after each SUPPLEMENT_APPLIED

EVL Wiring

When vc-autoresearch is the bookkeeper for an EVL (execute-validate-fix loop):

• domain: tests, verify: = validate-contract gate commands (read from contract — never invented)
• Research step = a SPAWNED vc-tester agent runs the validate-contract fully-automated gate commands (vc-tester may run independent gate groups in parallel). The orchestrator NEVER runs gate commands in its own shell — a gate result not produced by a vc-tester spawn does not count as an EVL confirmation, even if green.
• Gap signal = failing gate (non-zero exit)
• Fix step (parallel) = when multiple independent gates fail across non-overlapping file groups, the orchestrator spawns multiple parallel execute-fix agents (vc-execute-agent in supplement mode), one per failing gate / file group, partitioned so no two agents edit the same file. Each fixer is scoped to exactly its failing gate — no scope expansion. When failing gates share files or a single root cause, fall back to a single execute-fix agent. The fix is ALWAYS a vc-execute-agent spawn — the orchestrator never edits source files itself, no matter how small the fix.
• Convergence = all validate-contract fully-automated gates pass → SUCCESS
• Cap = 10 execute-validate-fix loops
• Per-cycle report = every EVL cycle writes its own report file {task_folder}/{plan-slug}-evl-iteration-{NNN}_REPORT_{dd-mm-yy}.md (zero-padded {NNN}) capturing: which gates ran, which failed (with trimmed failure output), fixes applied, and the re-run result for that cycle. Never a single rolling notes file.

Boundary:

• vc-autoresearch owns: iteration counter, plateau detection, TSV log, per-cycle iteration report, HANDOFF SUMMARY trigger, parallel-fix partitioning (which failing gate goes to which fixer) — all executed by the ORCHESTRATOR at each cycle boundary; no agent runs these implicitly
• vc-tester owns: which gate commands to run, HANDOFF SUMMARY format, agent-probe re-invocation — its confirmation run is UNCONDITIONAL after every EXECUTE DONE (execute-agent's internal iterate-until-green loop never substitutes for it); it reports failing gates and terminates; the orchestrator runs the fix cycle and re-spawns it

Iteration Report Format

See process/development-protocols/vc-autoresearch-spec.md §Iteration report for full frontmatter schema and body sections.

Gap entry format:

### GAP-I{N}-{ID} — {short title}
- **SEVERITY:** FAIL | CONCERN | OBSERVATION
- **LOCATION:** {file} §{section}
- **GAP:** {what is missing or wrong}
- **RESOLUTION:** {what was changed}
- **STATUS:** APPLIED | BACKLOG

Each iteration report is written inside the active task folder as {slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md with {NNN} zero-padded to 3 digits (task-folder artefact colocation — never a sibling reports/ dir). One file per iteration; PVL/EVL cycles use the {plan-slug}-pvl-iteration-{NNN} / {plan-slug}-evl-iteration-{NNN} slug variants.

TSV Log Format

Header row:

iteration	timestamp	gaps_found	fail_count	concern_count	applied	saturation_status	loop_status	notes

• Baseline row = iteration 0, before any fixes, loop_status: baseline
• One row appended after each iteration's fix batch completes
• saturation_status: ACTIVE | PLATEAU | SATURATED
• loop_status: CONTINUE | HALTED_SUCCESS | HALTED_PLATEAU | HALTED_CAP | HALTED_REGRESSION

Run vc-autoresearch:evals {task_folder}/results.tsv to analyze trends and get a plateau/recommendation report.

Hook Notes

• iteration-context.cjs — injects last 3 TSV rows at UserPromptSubmit; must scan process/features/*/active/*/results.tsv (not project-root autoresearch/ paths)
• session-init.cjs — active plan summary at SessionStart; adapted to scan process/general-plans/active/ and process/features/*/active/
• stop-notify.cjs — terminal notification at SessionEnd; no changes needed
• Do NOT register scout-block.cjs or privacy-block.cjs from the autoresearch reference repo — vc-system settings.json has superior versions; registering them would cause conflicts