feat(research): add scoped user-approved opportunity and evidence research

[akoita]

Parent: #4

Outcome

Let the agents propose and perform narrowly scoped internet research when supplied opportunity or candidate sources are insufficient, while keeping every fetch visible, approved, provenance-bearing, and unable to invent candidate facts. Interpret approved resources to uncover supported achievements, explain their relevance to the target job, and propose reusable candidate knowledge even when the candidate has not identified that value themselves.

Scope

• Let the planner propose a research question, reason, source class, domains or URLs, data-transmission impact, and bounded fetch budget.
• Require an explicit user approval boundary before search or fetch.
• Keep opportunity/company research separate from candidate evidence and optional corroboration.
• Allow approved GitHub repositories, certification pages, authored articles, and similar public candidate resources to enter a selected knowledge base with provenance.
• Record query, approved scope, fetch time, source URL, extraction status, checksum, and user decision.
• Treat remote content as untrusted data and apply URL, size, timeout, redirect, content-type, and prompt-injection controls.
• Never turn company/job requirements or third-party speculation into candidate experience.
• Do not submit applications, message people, contact employers, or publish externally.

Resource interpretation

Fetching a linked page is only intake. The research workflow must analyse the approved material and produce job-relevant, source-linked descriptions for candidate review.

• Repositories: inspect relevant implementation, architecture, tests, documentation and available release evidence. Explain the problem, design choices, boundaries, testing and observed outcomes. A repository's capabilities do not by themselves establish the candidate's authorship, responsibility, production use or personal achievements; flag those attribution gaps for focused clarification.
• Certifications and education: consult authoritative issuer material for the exact credential, syllabus, assessment and level where available. Explain relevance to the job and distinguish certification, diploma, bootcamp completion and course attendance. Training demonstrates covered learning or assessed competence within its documented scope; it does not establish production experience.
• Other candidate-linked resources: interpret articles, talks, demos, project reports and portfolio material through the same provenance and attribution rules. Surface transferable accomplishments and skills the candidate may have overlooked, rather than relying only on their initial labels.
• Synthesis: connect supported evidence to job requirements, explain why a contribution matters, propose concise CV wording and reusable knowledge-base additions, and expose uncertainty or conflicting sources. Keep observed facts, candidate-confirmed contributions and interpretive relevance distinct. Candidate review controls promotion into reusable facts.
• Budgets: propose the smallest useful set of files or pages, with visible fetch/model limits and a stopping rule. Do not recursively follow every link or execute repository code as part of inspection. Reuse approved source versions where suitable; record when external material is unavailable or insufficient.

This is a planning rollup, not an admitted execution issue. Before implementation, split ordered child issues with one observable outcome, architecture boundary, focused test surface and credible one-PR exit each. Research acquisition, repository interpretation, credential interpretation, reviewed knowledge promotion and representative evaluation require separate bounded work. The current Reference model pair milestone remains the priority; this elaborates the existing planned research outcome without advancing it into the active sprint.

Acceptance criteria

• No web search or fetch occurs without visible per-research approval.
• The candidate can inspect, accept, reject, or delete fetched sources before use.
• Research failures and inaccessible sources are visible and recoverable.
• Candidate facts remain grounded in candidate-provided or explicitly accepted candidate resources.
• Opportunity context and candidate evidence have distinct source roles throughout planning and critique.
• Security tests cover SSRF, redirects, oversized content, unsupported content, prompt injection, and approval bypass.
• Fictional committed fixtures demonstrate job-relevant repository contributions, credential framing and discovery of overlooked activities, without importing real candidate data.
• Regression cases reject unsupported authorship, invented outcomes, exaggerated certification scope, course-to-production experience claims and instructions embedded in remote content.
• Every proposed CV claim and reusable knowledge addition links to the supporting source version and identifies any unresolved attribution or scope question.
• Candidate review can accept, edit or reject inferred relevance and proposed knowledge without silently replacing original facts.
• pnpm validate passes.

Dependencies

• feat(opportunity): assemble a reviewed opportunity brief from URLs and instructions #67 reviewed opportunity brief
• feat(knowledge): manage reusable candidate knowledge bases and source lifecycle #78 candidate knowledge-base lifecycle

[akoita]

Roadmap update: optional user-approved research is no longer on the v0.7 drafting critical path. It remains a planned capability after the source-grounded core workflow demonstrates parity; opportunity intake from explicitly supplied URLs and content remains in #67.