add HINTS-STRUCTURED proposal

[HumanBean17]

What

Added propose/HINTS-STRUCTURED-PROPOSE.md — design proposal for machine-parseable hints_structured field on MCP outputs.

Why now

Issue #195 item 7: agents copy Python-style hints strings literally into MCP calls ("['id']"), which fails because single-quoted arrays are invalid JSON. A structured field lets agents use hints directly without reverse-engineering freeform text.

Highlights

• Adds hints_structured: list[StructuredHint] alongside existing hints: list[str] on all five outputs
• Each StructuredHint is {tool, args, actionable} — a direct MCP tool call representation
• Reuses same trigger logic as string hints; unified generate_hints returns both forms
• actionable flag distinguishes direct-call hints from advisory/prose-only hints
• No ontology bump, no re-index — pure MCP response-shape change
• String hints field unchanged and backward compatible

Tests

Docs-only; baseline unchanged.

Out of scope

• Removing hints: list[str]
• neighbors_v2 argument coercion or _coerce_ids()
• Per-row structured hints
• FastMCP upstream changes

[HumanBean17]

Reviewed the proposal — well-structured and solves a real problem. A few things worth tightening before implementation:

1. args should constrain to JSON-serializable types
StructuredHint.args: dict[str, Any] is fine for v1, but worth noting that values must be JSON-serializable (strings, ints, lists of strings). If a structured hint ever contains a Python set or tuple, MCP serialization breaks silently. A brief note under "Shape" would help implementers avoid this.

2. Parity invariant may be too strict
test_structured_hints_parity_with_string_hints asserts len(hints_structured) == len(hints) for every output. This couples the two lists forever. If a future string hint has no meaningful structured equivalent (purely informational prose with no tool reference), the implementer must invent a StructuredHint with actionable=False and near-empty args. Consider softening to len(hints_structured) <= len(hints) — v1 can aim for parity but the invariant should allow omission.

3. actionable conflates two different things

• Direct-call hints with complete args → actionable=True
• Advisory hints with partial args → actionable=False
• Batch-placeholder hints (v4 N2–N7) → also actionable=False, but they have a concrete tool and mostly-complete args (just missing ids)

This conflates "incomplete args" with "advisory recommendation." At minimum, document the distinction more explicitly in the shape section so implementers don't have to infer which actionable=False flavor they're handling.

4. Dependency paths are inconsistent
Line 8 references HINTS-V4-SUCCESS-PATH-PROPOSE.md without the completed/ prefix, while the line starts with propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md. Same for HINTS-V2, HINTS-V3. Minor but inconsistent with how the completed/ directory is organized.