v2.5.27 β decision markers enforced at write time
What's new in v2.5.27
Decision markers (// matcha:) now enforced at write time, not cleanup.
Previously the marker rule lived only in Checkpoint 4 (Cleanup) β the phase agents often skip β so deliberate shortcuts sometimes shipped unmarked. Now:
- core.md Checkpoint 3 (Implementation): any comment documenting a deliberate choice (skipped validation, workaround, intentional hardcode, known debt, architecture decision) must be prefixed
// matcha:explain/// matcha:debt/// matcha:adrwhile writing. Explicit boundary: plain "what this does" comments need no marker. - AGENTS.md #8 + Implementation row, CLAUDE/GEMINI/QWEN/.windsurfrules #8, SKILL.md, and docs/index.html workflow prose all synced.
- debugger: new MARK DECISIONS boundary β logs deliberate shortcuts of minimal fixes at write time.
- reviewer: Maintainability now flags a deliberate shortcut/workaround comment in changed lines missing the marker (judge-intent qualifier β no regex, no false-positive risk).
Why: ~50% of unmarked comments were correctly plain comments; the other half was a real gap β rule placed far from the decision point with no safety net. This closes it without adding ceremony to small tasks (conditional rule) and without a brittle hook detector.
Audit clean: 14 rule/md files changed, zero .js touched, copies consistent across all providers, 594/594 tests pass.