<purpose>
Conduct stack research and codebase investigation for the target phase, validating dependency versions and threat models to produce a structured `RESEARCH.md` document.
</purpose>

<required_reading>
@.opencode/references/hm-coordination-contracts.md
</required_reading>

<downstream_awareness>
Outputs generated by this workflow are consumed by:
1. **hm-plan**: Uses `RESEARCH.md` to map dependencies, import patterns, and outline specific task behaviors.
2. **hm-gate**: References tech-stack details to verify implementation compliance.
</downstream_awareness>

<scope_guardrail>
**CRITICAL: Investigation only.** The researcher must not implement code changes or modify configurations. All work must be read-only analysis of the workspace and external documentation.
</scope_guardrail>

<process>

<step name="initialize" priority="first">
Verify phase number from argument ($ARGUMENTS). Check for existing context and boundaries in `CONTEXT.md` or ROADMAP.md.
</step>

<step name="investigate_stack">
Validate the target technology stack:
- Inspect `package.json` and lockfiles to extract installed versions of required libraries.
- Run MCP tools (e.g. `context7`) to resolve library IDs and query canonical documentation.
- Flag version mismatches or outdated dependencies.
</step>

<step name="map_codebase">
Trace implementation coordinates in the active workspace:
- Locate source files, interfaces, and patterns to modify or reuse.
- Check for existing tests or mocks that can be extended.
- Record relative links of relevant files.
</step>

<step name="analyze_threats">
Identify security vectors:
- Formulate STRIDE threats specific to the component/feature domain.
- Map trust boundaries and design mitigation strategies.
</step>

<step name="resolve_questions">
Draft recommendations for any open questions, architectural alternatives, or risks.
</step>

<step name="write_research">
Generate `${phase_dir}/${padded_phase}-RESEARCH.md` using the standard `hm-research` template, substituting stack versions, codebase paths, and threat details.
</step>

<step name="git_commit">
Stage and commit the generated `RESEARCH.md` file atomically to git.
</step>

<step name="update_state">
Record research completion details in `.planning/STATE.md` and commit.
</step>

</process>

<success_criteria>
- Library versions confirmed against workspace lockfile and MCP.
- Codebase paths mapped with relative links.
- STRIDE threat model mapped.
- `RESEARCH.md` written and committed.
</success_criteria>
