plan: HINTS-STRUCTURED — machine-parseable next-action objects

[HumanBean17]

Summary

• Adds the implementation plan for HINTS-STRUCTURED (issue hints: Python-style neighbors(['id'],…) copies fail; JSON stringified ids work #195 item 7): a StructuredHint model and hints_structured: list[StructuredHint] field on all five MCP output models.
• Companion agent-execution prompt for single-PR rollout.
• Plan-only PR (no code changes).

Scope

Deliverable	File
Plan	plans/PLAN-HINTS-STRUCTURED.md
Agent prompts	plans/AGENT-PROMPTS-HINTS-STRUCTURED.md

Key decisions

• Single generate_hints returning (list[str], list[StructuredHint]) — unified trigger logic, no parallel generators.
• Lightweight internal hint type in mcp_hints.py (avoids circular import with mcp_v2.py).
• actionable: bool flag distinguishes direct tool calls (True) from advisory/partial hints (False).
• Backward compatible: hints: list[str] unchanged; hints_structured is additive.
• No ontology bump, no re-index.

Links

• Proposal: propose/HINTS-STRUCTURED-PROPOSE.md
• Issue: #195 (item 7)

🤖 Generated with Claude Code

[HumanBean17]

Plan Review

Overall this is a well-structured plan. One correctness issue and a few suggestions:

Correctness: frozenset(args.items()) will break on nested dicts

The plan specifies dedup key as (tool, frozenset(args.items())). This fails when args contains nested dicts — and the plan already includes such cases (e.g. args={"filter": {"path_prefix": seed}} from resolve → find route, args={"filter": {"role": "SERVICE"}} from search weak-score). frozenset on a dict value raises TypeError.

Suggest using json.dumps(args, sort_keys=True) as the dedup key instead, or flattening args before hashing.

Suggestions

1. Neighbors empty structural hints — the mapping is flagged as medium-severity in the risk table but doesn't include a concrete args shape. Adding 1-2 examples would remove ambiguity during implementation.

2. resolve_v2 model_copy pattern — this call site is called out as special (uses model_copy(update=...) instead of direct construction) but the plan doesn't show the before/after. A one-liner (model_copy(update={"hints": str_hints, "hints_structured": struct_hints})) in the plan would prevent confusion.

3. Proposal lifecycle — the plan status says "active (planning)" while the agent prompt's definition of done says "Proposal — locked." Clarify whether locking happens when the plan merges or when implementation starts.

Otherwise looks good — backward compatibility, circular import prevention, parity invariant, and test coverage are all solid.