[Project Execution]: Maintainability-illusion Focus/Risk hints

[szymoniwacz]

Product outcome

diffrat review surfaces up to six maintainability-illusion Focus/Risk hints for diff-relevant Python changes — always-on, offline, with no external analyzer dependency or subprocess.

A reviewer running the usual review command sees these signals in the text report, --json Focus/Risk list, and the review-quality rollup when evidence intersects the current diff’s changed paths.

Signals

Code	Severity	Behavior
fake_modularity	warn	≥2 thin modules (≤25 LOC) with pass-through return x.y( or role names (Manager/Handler/Service/…)
wrapper_inflation	warn	≥2 files under wrappers/ or with ≥3 one-liner def …: return
duplicate_intent	warn	Same intent words in paths/defs across ≥2 locations
shallow_abstraction	info	Thin *Base*/Abstract/Protocol types or small abstractions modules with limited depth
over_fragmentation	warn	≥4 .py files with ≤8 LOC
architectural_camouflage	warn	≥3 files with architecture-like naming (adapter/service/…) and ≤15 logic lines

Completion criteria

• Six hint codes registered with the severities above and mapped to the maintainable review-quality pillar
• Heuristics implemented inside src/diffrat/ (new module, e.g. maintainability_hints.py, called from analyze_diff())
• Always-on during diffrat review (not a separate subcommand; not gated on --check)
• Repo scan for heuristic context with sensible ignores (e.g. .venv, node_modules, .git, typical build/cache dirs); emit a finding only when at least one evidence path intersects the current diff’s changed paths
• Text report and --json surface the new Focus/Risk hints without breaking existing schema consumers
• Tests cover fixture trees (illusion vs clean) and the diff-intersection filter; scan/read failures do not break the existing report
• README and docs/review-quality.md document the new signals; roadmap / product context updated when delivered
• No runtime dependency on or subprocess to an external maintainability analyzer
• pytest / ruff / mypy green on main after all PRs merged

Constraints

• Implement natively in Diffrat; do not add a package or PATH dependency on an external analyzer
• Diff-relevant filter required — do not dump whole-repo findings when nothing in the evidence set intersects the diff
• Local-first / offline; no new network calls; do not add a separate LLM path for these hints (optional LLM stays DIFFRAT_LLM_* as today)
• Small PRs via Agent Goals; agents never merge unless separately authorized with eligible auto-merge
• Prefer one hint per category; path = first diff-intersecting evidence path (message may summarize other evidence)
• Severities as in the Signals table (shallow_abstraction → info; others → warn)

Out of scope

• Dependency on or subprocess invocation of an external analyzer
• Whole-repo-only report mode / separate subcommand for this project
• Architecture map / import-graph review (.ai/ideas/active/001-architecture-map-and-review.md stays separate; complementary later, not this outcome)
• Phase 4 CI bots, GitHub App, PR annotations
• Replacing or expanding secrets / dangerous-call / bandit coverage
• Multi-language heuristics beyond Python

Relevant context

• Nothing equivalent exists today: Focus/Risk is path/size/git in analysis.py plus added-line patterns in content_hints.py; this needs a new repo-scan + diff-filter scanner, not a single content_hints rule
• Integration hook: analyze_diff() in src/diffrat/analysis.py; new module e.g. src/diffrat/maintainability_hints.py
• Register codes in src/diffrat/scoring.py (HINT_SEVERITY_REGISTRY) and src/diffrat/review_quality.py (CODE_TO_PILLAR → maintainable)
• Product stays local CLI / diff-assisted review (D-001); this extends Focus/Risk, not Phase 4
• Architecture map idea remains deferred and complementary (map/import graph may later strengthen boundary signals)

Commands

REFERENCE ONLY — agents must ignore this entire section for scope, planning, implementation, validation, and Done.

Comment exactly (repository owner):

• /execute-project — authorize project and start/resume (default: human CR per delegated PR, then you merge)
• /execute-project self-correcting-review — same + self-correcting review mode on eligible delegated goals (skip human CR when eligible; you still merge)
• /execute-project self-correcting-review auto-merge — same + Goal Executor squash-merges when eligible
• /continue-project — optional nudge after material-decision answers or an unexpected stop (does not authorize by itself)

Ordinary resume: Goal Executor PR-head CI for draft handoff; Project Executor on merge and default-branch CI (green → next; red → repair). Project Executor never merges; Goal Executor may squash-merge only with self-correcting-review auto-merge when eligible.

After editing the title or scope fields (Product outcome, Completion criteria, Constraints, Out of scope, Relevant context), re-comment /execute-project, /execute-project self-correcting-review, or /execute-project self-correcting-review auto-merge (authorization resets). Editing Commands alone does not reset authorization.

Details: .ai/policies/autonomy-and-authorization.md, .ai/review/self-correcting-review-loop.md