plan: revise hints string removal — category-mismatch gap + string-only structured equivalents

[HumanBean17]

Summary

• Revises propose/HINTS-STRING-REMOVAL-PROPOSE.md to document the category-mismatch gap discovered during implementation: ~10% of hints are pure advisory nudges with no meaningful tool call, and some string-only hints have zero structured counterpart
• Rewrites plans/PLAN-HINTS-STRING-REMOVAL.md to resolve the gap: string-only hints (fanout count, unresolved sites, role-filter fallback, role collision, brownfield absence) gain structured equivalents with actionable=False and reason carrying the advisory text — no separate advisories field needed

Test plan

• Verify proposal gap section reads correctly and the three hint categories are accurate
• Verify plan step 3 (new structured equivalents) covers all five string-only cases
• Verify new tests (steps 9–10) are named and scoped
• ruff check . clean
• pytest tests -v passes (plan docs only, no code changes)

🤖 Generated with Claude Code

[HumanBean17]

Review: plan: revise hints string removal

Overall the three-field model (hints_structured + advisories + remove hints) is a solid design that resolves a real gap. The directory restructuring to active/ subdirectories is clean and consistent across all skill files and AGENTS.md.

One issue to fix before merge:

---

Contradiction: "High fanout (describe)" classification

The proposal lists "High fanout (describe)" in both the hints_structured table and the advisories table:

• Proposal hints_structured table: | High fanout (describe) | neighbors(ids, "out", ["CALLS"]) | "many CALLS — consider filtering" |
• Proposal advisories table: | Describe "many CALLS" — "consider filtering by target microservice" | Vague suggestion, not a concrete call |

The plan resolves this correctly (move to advisories only, step 3 classification table), but the proposal's hints_structured table still has the row. An implementer reading only the proposal would try to keep it in both places.

Fix: Remove the "High fanout (describe)" row from the proposal's hints_structured table.

---

Two suggestions (non-blocking)

1. generate_hints tuple order swap. The current code returns tuple[list[str], list[_StructuredHint]] (string first). The plan swaps to tuple[list[_StructuredHint], list[str]] (structured first). This is a good change, but consider adding a one-line note in the plan's resolved decisions table since it's easy to miss during implementation.

2. Role-filter OTHER fallback advisory text. The advisory says "try edge_filter={exclude_callee_declaring_roles: ['ENTITY','DTO']}" which contains a concrete tool call argument. If the intent is pure education, consider softening the text (e.g., "callee declaring role filter may not match OTHER targets — check target roles and adjust edge_filter"). Otherwise it reads like a tool call suggestion masquerading as an advisory.

---

Everything else looks good — classification tables, test plan (12 tests is thorough), risk register, and directory restructuring are all clean.