propose: hints-v3 — kind/direction-aware empty-result hints driven by EDGE_SCHEMA

[HumanBean17]

Status: draft

Adds propose/HINTS-V3-PROPOSE.md and docs/PROPOSES-ORDER.md.

What this propose does

Replaces the generic TPL_NEIGHBORS_EMPTY_KIND_CHECK in mcp_hints.py with a family of four templates driven by EDGE_SCHEMA (introduced in SCHEMA-V2):

1. TPL_NEIGHBORS_WRONG_SUBJECT_KIND — subject node kind isn't in EdgeSpec.src (or .dst for direction='in').
2. TPL_NEIGHBORS_WRONG_DIRECTION — kind matches the opposite endpoint of the requested direction.
3. TPL_NEIGHBORS_TYPE_LEVEL_REQUERY — subject is a type-kind Symbol, edge lives on methods.
4. TPL_NEIGHBORS_BROWNFIELD_RESOLVED_MAYBE_UNRESOLVED — requested edge has EdgeSpec.brownfield_resolver_sourced=True (consumes the new BROWNFIELD_RESOLVER_STRATEGY_SET from SCHEMA-V2 Decision 28).

The v2 TPL_NEIGHBORS_FUZZY_STRATEGY hint stays unchanged. Hints v3 reads BROWNFIELD_RESOLVER_STRATEGY_SET via EdgeSpec.brownfield_resolver_sourced, not by enumerating the set directly.

Why it exists as its own propose

SCHEMA-V2 Decision 30 makes PR-D (the implementation of hints v3) gated on HINTS-V3-PROPOSE.md existing as a draft PR. Shipping the v2 graph shape without v3 hints leaves the wrong-subject-kind footgun (e.g. agent holds method id, asks HTTP_CALLS outbound post-flip, gets [] with no guidance to DECLARES_CLIENT).

Implementation

1 code PR = SCHEMA-V2 PR-D. Sequencing recorded in docs/PROPOSES-ORDER.md:

• Phase 1 — propose locks: SCHEMA-V2 (locked), HINTS-V3 (this PR).
• Phase 2 — plans + cursor prompts.
• Phase 3 — code PRs A → B → C → D, sequential, no parallelization.

Use-case re-walk

20 named cases (HV1–HV20) covering structural-mismatch hits, structural-mismatch misses (HV8/HV9/HV11 — graph state, not structural), brownfield-resolver absence (HV4/HV13/HV14), and EDGE_SCHEMA coverage invariant (HV19).

What this deliberately does NOT do

Bespoke per-edge prose; multi-hop composition planning; reasoning about graph state; dot-key edge labels in recommendations (forbidden by v2 invariant); caching; localization.

Decisions taken

14 locked decisions, including:

• TPL_NEIGHBORS_EMPTY_KIND_CHECK is deleted, not extended.
• Priority PRIORITY_LEAF_FOLLOWUP=2 for all four new templates — same as the v1 template they replace.
• Canonical traversals come verbatim from EDGE_SCHEMA[e].typical_traversals.
• New EdgeSpec.member_only: bool field (hint-engine-only; preferable to land in SCHEMA-V2 PR-A).
• No back-compat alias (per locked repo rule "Breaking changes allowed; no active users.").

Files

• propose/HINTS-V3-PROPOSE.md — the propose.
• docs/PROPOSES-ORDER.md — lock + merge sequence for SCHEMA-V2 + HINTS-V3.

Marking as draft per the propose-doc-author convention; will move Status to under review after first review-round feedback.

[HumanBean17]

Review (addressed in ac65097)

Solid framing and HV table; the propose is the right companion to SCHEMA-V2. The first draft had several internal contradictions and one cross-doc gate mismatch — all fixed on this branch.

Blockers fixed

1. Merge gates vs SCHEMA-V2 Decision 30 — §6 and docs/PROPOSES-ORDER.md incorrectly required HINTS-V3 locked before PR-A. Decision 30 only requires a draft propose merged before PR-A; lock is required before PR-D. Phase 1/3 text updated accordingly.

2. Structural hint algorithm (HV5/HV6) — Checking only the requested-direction endpoint made Client + HTTP_CALLS + in hit wrong-subject instead of wrong-direction. Replaced with a fixed three-step order: alien kind (neither endpoint) → wrong direction (opposite endpoint) → type-level requery. §3.2, §3.3, Decision 3 updated.

3. TPL_NEIGHBORS_TYPE_LEVEL_REQUERY vs Principle 1 — Template hardcoded DECLARES. Now uses {canonical_traversal} from typical_traversals["type_subject"] only; §3.5 locks role-keyed map shape for PR-A.

4. member_only contradiction — §3.4 listed post-flip HTTP/ASYNC under member_only while §8 said Symbol-only edges. Unified: member_only is for type-level Symbol → method-level Symbol edges only; post-flip Client/Producer edges use row 1 (wrong subject) for method subjects.

5. PRIORITY_LEAF_FOLLOWUP claim — Shipped v1/v2 empty-neighbors hints use PRIORITY_META=1. Decision 5 and Principle 6 corrected.

6. neighbors hint payload — Added §3.6: PR-D must pass requested_direction, origin_id, and subject_record into generate_hints (not in payload today). Multi-id: hints use origins[0].

Other fixes

• Removed invalid direction='any' / HV18; replaced with Route + DECLARES (row 1).
• HV19 clarified: ∃ (edge, subject, direction) coverage per edge in CI — not “every empty query gets a hint”.
• Principle 8: brownfield empty hint is an explicit exception to structural-only framing (HV13/HV14).
• Principle 4: fuzzy vs brownfield hints are branch-exclusive on one call.
• PR-D test list now includes HV9, HV11, HV12.
• Removed duplicate Appendix A template block; review traceability in Appendix A.
• Dropped “Perplexity Computer” author credit.

Verdict

Approve as draft propose PR — satisfies SCHEMA-V2 Decision 30 (draft merged unblocks PR-A). Move Status to locked after plan review, before PR-D implementation starts.