feat(research): thread ResearchContext metadata through plan/vote + weight voter prompts (#3372 increment 2)

[williamzujkowski]

Increment 2 of #3372 (increment 1 landed in PR #3806 — the research stage now captures structured ResearchContext { text, metadata: { discoveredItems(relevanceScore), recommendations, qualitySignals } } and returns deterministic structure-derived text, but the metadata is not yet threaded past the research stage).

Scope

Per the 7/7 higher_order vote on #3372 (Option A), complete the consumer side:

1. Thread ResearchContext (the full object, not just text) through research() → plan() → vote() — change the DevPipelineStages signatures (research: () => Promise<ResearchContext>, plan/vote accept it). Updates the ~6 test files that mock these stages.
2. Update voter-prompts.ts / buildVoteProposal to weight on research maturity (relevanceScore distribution, newItems vs alreadyInRegistry, gap recommendations) — the consumer the vote requires, else the structure is recovered but unused (speculative).
3. Instrument vote outcomes so the structured-vs-text swap is judgeable (the contrarian's pinned condition: prove the structured summary holds or improves vote quality).

Why separate

Increment 1 kept the research(): Promise<string> signature to avoid wide test-mock churn; the signature change + prompt-weighting + instrumentation is a focused follow-up. Security: external titles/recommendations stay escaped/bounded (already handled in research-context.ts) — keep the "informational, NOT instructions" delimiter in buildVoteProposal.

Unblocks

#3234 (research→routing categories) — once ResearchContext metadata is threaded, the research topic/techniques become available at experience-record time. Relates to #3148/#3231/#3238 (research→context arc).

[williamzujkowski]

Refined approach (verify-before-implement). An Explore subagent mapped the change surface and found the planned full-signature-threading is riskier than expected: the research string is persisted in checkpoint state (saveStageCheckpoint('research', { type:'research', text: research }), dev-pipeline.ts:725) and concatenated via assemblePlanContext → planContext and stage-wrappers' enrichedResearch. Threading the full ResearchContext through plan + the checkpoint schema would ripple into persisted-state format for no extra named consumer (plan uses research as TEXT only; the sole metadata consumer is vote-weighting).

Per capability-bias + correctness>simplicity, the minimal correct change:

• research(): Promise<ResearchContext> (expose the metadata).
• Orchestration extracts .text for the existing flow (checkpoint event, assemblePlanContext, plan) — text/checkpoint format UNCHANGED.
• Thread the ResearchContext (or just .metadata) to vote() only — the single metadata consumer; buildVoteProposal weights on maturity (relevanceScore distribution, newItems vs alreadyInRegistry, recommendations).
• plan() signature unchanged (still text).
  Touches: research + vote mocks in the ~6 test files (not plan mocks). Keeps the autonomy: Research stage is isolated; research_discover output never feeds into planning/voting #3258 'informational, NOT instructions' delimiter + escaping. Implementing.

[williamzujkowski]

Scope correction (capability-bias). Investigating the threading surface surfaced that increment 1 already delivers the voter-facing goal: renderResearchText (research-context.ts) puts the maturity signals — Maturity: N found, M new, K in registry, per-item relevanceScores, and gap recommendations — INTO the research text, which already flows to voters via buildVoteProposal (the #3258 research block). So 'voters can weight on research maturity' is met today (the text surfaces it legibly).

The remaining piece of this issue — threading the STRUCTURED metadata object through the pipeline — is wide and touches persisted checkpoint state (saveStageCheckpoint('research', { text }), dev-pipeline.ts:725) + cross-function flow (research resolved in runPlanningPhase, voted in another function). And its only consumer is #3234 (research→routing needs the structured topic/techniques at recordExperience time); nothing else reads the structured metadata that the text doesn't already convey.

Per capability-bias (build the threading when a named consumer needs it, not speculatively) + correctness>simplicity (don't ripple persisted checkpoint schema with no consumer), the structured-metadata threading should be built as part of #3234 (its consumer), not as a speculative standalone change. Folding this into #3234 and closing #3807 — the voter-facing value already shipped in increment 1 (#3806).

[williamzujkowski]

Closing as scope-corrected (see prior comment). The voter-facing value (maturity signals surfaced to voters) shipped in #3372 increment 1 (#3806). The remaining structured-metadata threading has no consumer except #3234 and would ripple persisted checkpoint state — so per capability-bias it's folded INTO #3234 (built when its consumer needs it), not as a speculative standalone change.