Add support for XML-style <cmt>comment</cmt> <comment>comment</comment> formats in refine-plan

[Lyken17]

Summary

Extends the refine-plan command to support three comment annotation formats instead of just CMT:/ENDCMT, making plan reviews more intuitive and flexible
for different user preferences.

New Comment Formats

• Classic format (existing): CMT: comment ENDCMT
• Short tag format (new): <cmt>comment</cmt>
• Long tag format (new): <comment>comment</comment>

Key Features

• ✅ All formats support both inline and multi-line usage
• ✅ Formats can be mixed within the same file
• ✅ Proper nesting detection and error reporting
• ✅ Code block and HTML comment exclusion works for all formats
• ✅ 100% backward compatible with existing workflows

Examples

Inline annotations:

Text before CMT: classic comment ENDCMT text after.
Text before <cmt>short tag comment</cmt> text after.
Text before <comment>long tag comment</comment> text after.

Multi-line annotations:
CMT:
Multi-line classic comment
ENDCMT

<cmt>
Multi-line short tag comment
</cmt>

<comment>
Multi-line long tag comment
</comment>

Mixed formats in one file:
## Goal Description
Update the API CMT: why not use REST? ENDCMT to support GraphQL.

## Acceptance Criteria
- AC-1: <cmt>Should this be split into multiple ACs?</cmt>
- AC-2: <comment>Need to clarify the error handling requirements</comment>

Test plan

- Verify all three formats are correctly parsed by the validator
- Test inline and multi-line usage for each format
- Confirm mixed formats work in the same file
- Validate error detection for mismatched start/end markers
- Ensure code blocks and HTML comments properly exclude markers
- Run existing test suite to confirm backward compatibility

Implementation Notes

- Enhanced AWK parser with format-specific marker detection
- Added helper functions for marker length calculation and format validation
- Updated all documentation to reflect the new capabilities

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 79714b73d5

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Encode marker results without : collisions

find_comment_markers serializes matches as marker:position, but the legacy start token itself contains a colon (CMT:), so classic matches become strings like CMT::12. The later split(..., ":") parsing then yields found_marker="CMT" and an empty marker_pos, which prevents recognizing the marker and can leave pos unchanged (pos = marker_pos + 1), causing scan_cmt_blocks to spin indefinitely on files that still use CMT: blocks. This breaks backward compatibility and can hang refine-plan validation on existing annotated plans.

Useful? React with 👍 / 👎.

[Lyken17]

@codex address that feedback

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[Lyken17]

@codex address that feedback

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.