propose: describe structural hints tiers 1-2

[HumanBean17]

Summary

• Adds propose/DESCRIBE-HINTS-STRUCTURAL-PROPOSE.md — amendment to the describe hints catalog (tiers 1–2).
• Tier 1: type wiring (IMPLEMENTS.in/out, INJECTS.in/out) when integration rollups do not fire.
• Tier 2: mid fanout CALLS, impl-side OVERRIDES, unresolved call sites, client/producer HTTP/async second hops.
• Tier 3 (callers, members, EXTENDS) deferred to #191.

No code changes in this PR — design/spec only. Implementation PR to follow the propose.

Test plan

• N/A (markdown propose only)

Made with Cursor

[HumanBean17]

Critical review (propose-only PR)

Overall this is a solid, implementable amendment: problem cases match the bank fixture, triggers stay query-time-only (no re-index), suppression vs rollups is clear, and tier 3 is cleanly deferred to #191. CI is green. I’d land this propose after a few doc/test-plan fixes below.

Verified against fixture

Built tests/bank-chat-system (pass 6) and checked describe edge_summary for the cited nodes — the problem table is accurate:

• ChatAssignmentPort: IMPLEMENTS.in=1, INJECTS.in=2, no rollups → today hints=[]; A + D would both fire (2 leaf hints, within cap).
• EventProcessor: IMPLEMENTS.in=11 → A only.
• DistributionService (SERVICE): INJECTS.out=1 (also INJECTS.in=1) → C and possibly D on the same node.
• RegexComplianceScanner#scan: OVERRIDES.out=1, no OVERRIDDEN_BY*, CALLS.out=4, unresolved_call_sites_total=3 → E, G, H all plausible together (watch cap 5).

Must-fix before implementation PR

1. ## After landing lifecycle (repo convention)
   Per agent-workflow.mdc, proposes move to propose/completed/ when the whole effort lands, not when this markdown-only PR merges. This PR only adds the spec; the implementation PR is still outstanding. Suggest:

   • Keep file in propose/ after this merge.
   • Move to completed/ only when mcp_hints.py + tests land.
   • Optionally add a line in Migration clarifying two PRs: (1) this propose, (2) implementation.

2. Negative test test_hints_describe_controller_skips_implementors_when_rollups is mis-scoped
   Row A triggers only on decl_kind == "interface". A CONTROLLER class with DECLARES.EXPOSES rollup will never emit A regardless of suppression. The suppression test should assert B and/or D absent on _controller_class_id_with_exposes (helper already exists in tests/test_mcp_hints.py), or rename/repurpose the test.

3. Existing tests will break on I/J — not listed
   test_hints_describe_client_always_declaring_method and test_hints_describe_producer_always_declaring_method assert out.hints == [want] (exactly one hint). I/J are additive; bank fixture already has clients with HTTP_CALLS.out and producers with ASYNC_CALLS.out. Implementation PR must relax these to assert want in out.hints (and add the new assertions), or the test plan should call that out explicitly.

4. generate_hints("describe") control flow
   Current code early-returns after rollups for types (line ~719) and after declaring hint for client/producer kinds. Implementation is not “append rows at the bottom” — it requires restructuring those branches so tier-1/type and I/J run before finalize_hint_list without skipping suppressed cases incorrectly. Worth one explicit bullet under Proposed solution so the impl PR doesn’t miss it.

5. Row G gate — specify the predicate
   “no OVERRIDDEN_BY* key with out > 0” should name the implementation rule (e.g. any edge_summary key with prefix OVERRIDDEN_BY. or key OVERRIDDEN_BY where out > 0), matching how rollups are keyed today (OVERRIDDEN_BY, OVERRIDDEN_BY.DECLARES_CLIENT, …).

Nits (non-blocking)

• TL;DR “10 new templates” — ambiguous: 10 hint rows (A–J minus F) vs 7 new TPL_DESCRIBE_* constants (+ reuse find v4 for I/J). Consider “10 hint rows (7 new templates)”.
• Row E test gap — trigger allows CALLS.out 1–2 when role != "OTHER"; named test only covers 3 <= CALLS.out <= 9. Optional small test or narrow the table.
• Row E on RegexComplianceScanner#scan — CALLS.out=4 and method role likely non-OTHER; good canonical example for E + G + H together; consider citing it in the test plan instead of only the type-level scanner class for B.

What looks good

• No ontology/re-index claim is consistent with edge_summary + record.data inputs.
• Suppression via _type_rollup_would_emit mirrors existing _out_count rollup keys.
• Priority band (2) fits §7.12 below rollups/override axis.
• Reuse of TPL_FIND_SUCCESS_HTTP_TARGETS / TPL_FIND_SUCCESS_ASYNC_TARGETS is consistent with v4 parity goal.
• Tier 3 deferral and #191 linkage are coherent.

Recommendation: Approve this propose PR after tweaking After landing, the controller negative test row, and the test-plan callout for client/producer == tests + describe control-flow note. Implementation can follow as a single code PR per Migration.

[HumanBean17]

Re-review — LGTM (approve from your side)

All items from the first review are addressed in 6ff8f2e:

Prior feedback	Status
After landing / two-PR lifecycle	Fixed — propose stays in propose/ after #192; completed/ only on impl PR
Controller negative test mis-scoped to A	Fixed — test_hints_describe_type_skips_tier1_when_rollups checks tier-1 substrings on rollup type
Client/producer hints == [want] regression	Fixed — explicit Regression note + relax to want in out.hints
Describe control-flow early returns	Fixed — bullet 5 + append-before-finalize_hint_list
Row G predicate	Fixed — _override_axis_would_emit / OVERRIDDEN_BY* prefix rule
TL;DR “10 templates” ambiguity	Fixed — 10 rows / 7 new constants
E test / canonical method	Fixed — RegexComplianceScanner#scan + optional low-fanout test

Fixture-backed problem table still holds; scope remains query-time-only (no re-index). CI green.

Optional impl nit (not blocking this propose): bullet 5 cites early-return at ~689–719 for client / producer / type; the method branch also returns immediately after the override/leaf block (~721–744). Same append-before-finalize pattern applies for E/G/H — obvious from tier 2, but worth a one-line comment in the impl PR if you touch that block.

Ready to merge — proceed with the implementation PR per Migration.