mastermind-codegraph-research

Codegraph research — discover structure with mmcg

The shared structural discovery layer for Mastermind. Claims about symbol existence, indexed callers, imports, and bounded blast radius come from a fresh mmcg result rather than memory. Exact source contracts and runtime behavior come from source reads and tests.

The graph is syntactic evidence with name-based target candidates, without compiler/type resolution. Dynamic dispatch, reflection, generated code, re-exports, and cross-language edges can reduce precision.

Never name a symbol, file, caller, or blast radius from memory. "I think X exists" is not evidence; mmcg_search X returning a hit is. A spec, audit, or critique built on a guessed symbol fails at the first step that touches real code.

Effort selection at handoff

Before starting a research agent, use [[mastermind-agent-handoff]] to select and apply effort to the ordinary spawn. Preserve the source/map bindings and carry facts and gaps when the duty changes. Source and citation checks below still apply.

Structural vs literal

• Bounded orientation (relevant changes, symbols, callers, tests, and history for a role) → one mmcg_brief before broad discovery. Use its aggregate disciplines to route needed evidence: inspect frontend interaction states, QA coverage, or migration data and rollback boundaries when those disciplines are detected. The classifier is path-based and is not proof of behavior; a scope-incomplete signal means it classified only returned changed files.
• Concept discovery (the intent is known but the exact symbol is not) → Before retrieval, freeze a query-only request_contract: the requested operation and exact quoted constraints with unique id, original-query text and kind (input, state, scope, result). Pass it to mmcg_concept_prepare, inspect the bound source, then mmcg_concept_finish. The original query stays authoritative if that ledger is incomplete or mistaken. Omitting it supplies the whole query as the operation with an empty parsed ledger; it does not remove any original constraint. Supply alternative implementation vocabulary in optional hints when the request uses different words; preserve the original query as the criterion. Assess the requested action, object and constraints for every candidate. Topic mentions, unrelated dispatch and neighboring operations are insufficient. Follow operation-roles-v3: relevant entries declare implementation, entrypoint, contract, essential_helper or supporting_context. First identify the candidate's own observable behavior, then its relationship to the operation. A concrete branch inside a broad handler or file module may own or expose the operation through a mandatory inspected path; delegation alone does not reduce it to context. A helper need not implement the whole workflow, but being mandatory or running earlier is insufficient: its own behavior must perform a defining domain step or enforce a requested constraint. Useful generic readiness, configuration or lifecycle prerequisites remain context. Bind non-implementation roles to inspected caller/consumer/implementation source ranges through supporting_evidence; entrypoints/contracts/helpers require evidence outside their own declaration. Generic call-graph membership is insufficient. Admit context only for specific inspected navigation to an existing requested operation satisfying every explicit constraint. Opposite or missing behavior, a narrower scope, or a place to add the feature is irrelevant. An uninspected constraint stays unknown. Prefer semantic roles for necessary steps and specific result entrypoints, including cached-result paths. Relevant entries require a typed witness with own behavior, relation and constraint_checks. Cover every declared constraint exactly once by constraint_id, status=matched and inspected source-bound evidence. Contradicted checks require irrelevant; uninspected checks require unknown, including for context. Preserve input options separately from runtime state and result conditions: an omitted selector does not establish absent binding, and rendering instructions does not execute the requested action. Record unresolved intent in query_ambiguities; useful results for an ambiguous query may only be supporting context under a plausible original interpretation that retains every explicit constraint. The full candidates page preserves navigation. Use its semantic_candidates partition for operation claims and retain supporting_context separately. Read beyond incomplete excerpts when needed; otherwise keep the candidate unknown. The calling agent supplies judgments; the server checks source bindings, completeness and declared consistency, not semantic truth. Reprepare after a role-contract change. Retrieval limits and unknowns prevent an absence claim. Use mmcg_concept for a fast lexical shortlist, then read source; its score does not establish operation relevance. Query only returned symbol names.
• Structural discovery (symbols, indexed callers/callees, imports, bounded blast radius) → mmcg first. It understands syntax better than literal text search, but remains name-based and bounded.
• Literal (string contents, log messages, comments, config values) → Grep / Read. The persistent symbol index omits strings; operation review may read bounded source bodies.
• Runtime contract (dynamic dispatch, reflection, generated code, re-exports, cross-language edges, exact branch behavior) → read source and run focused tests.