Skip to content

v2.5.27 β€” decision markers enforced at write time

Choose a tag to compare

@farhank15 farhank15 released this 08 Aug 06:29
· 10 commits to main since this release

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:adr while 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.