Protocol method bodies in engine/ have no lint-clean form: STUB-001 vs ruff PIE790 vs code-quality

[cryptoxdog]

Not from the audit — surfaced while remediating #262. Filed because no code change can resolve it: the repository's own tooling contradicts itself, so it needs a configuration decision.

The conflict

GraphWriter.execute_write in engine/sync/idea_portfolio.py is a typing.Protocol method. Every possible body breaks one of three surfaces, measured on that branch:

Body	Scan for Contract Violations	Lint + Type Check	github-code-quality
raise NotImplementedError	❌ [STUB-001] CRITICAL, merge-blocking	✅	✅
pass	✅	❌ ruff PIE790 "Remove unnecessary pass"	✅
...	✅	✅	❌ "Statement has no effect"

• STUB-001 is r"raise\s+NotImplementedError" scoped to engine/ (tools/contract_scanner.py), so it catches the first form and not the second.
• ruff PIE790 catches the second.
• github-code-quality flags the third, and has proposed both of the other two in turn.

This has already cost a cycle

Taking the bot's first suggestion at face value turned four checks red on #262 — Scan for Contract Violations, compliance, Pre-commit Hooks and CI Gate. Reverting to ... made all four green again. A future contributor or agent reading that same bot comment will repeat this.

Why ... is the right body on the merits

GraphWriter is structural: it is never instantiated and its body never executes. IdeaPortfolioHydrator calls execute_write on the concrete object it is handed. There is no runtime path where the statement could have an effect to lack, and the repository already uses ... for every protocol method in engine/hoprag/indexer.py::GraphStore.

Suggested resolution (pick one)

1. Exempt typing.Protocol bodies in the github-code-quality configuration. Least disruptive; the other two surfaces already agree.
2. Narrow STUB-001 so raise NotImplementedError is permitted inside a Protocol class body, and standardise on it.
3. Document ... as the mandated protocol body in docs/contracts/BANNED_PATTERNS.md and accept the recurring bot comment as known-noise.

An entry in .claude/rules/learnings.md would also stop agents rediscovering this; that file invites exactly this kind of note, but adding it to #262 is not appropriate while that PR is over the reviewable-size limit.

Related: #262, and the two review threads on engine/sync/idea_portfolio.py there.

---

Generated by Claude Code