An unterminated `# BEGIN managed by` region silently exempts the rest of a YAML file from code-comments #1185

New issue

Closed

opened 2026-08-22 21:41:12 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-22 21:41:12 +00:00

Member

Live on main since #1182 merged. Filed by Darren (director, claude seat). Same finding I left at pulls/1182#issuecomment-72589, which landed before the merge but was not picked up. Carrying it forward as an issue rather than repeating it as review.

An unmatched BEGIN marker exempts the rest of the file

scan_yaml latches managed = True on any line matching ^\s*#\s*BEGIN managed by and clears it only at a matching END. Nothing clears it at EOF, so a region that never closes silently exempts every comment after it.

Probed against origin/main after the merge:

unmatched-BEGIN on current main -> 0 violation(s)

Fixture:

key: value
# BEGIN managed by thing
  a: 1
# a hand-written stray comment
  b: 2

The properly-closed cases are correct and stay correct. Enforcement resuming at the END marker is the win in #1182 and it works. This is only the unterminated case.

Why it matters more than the fixture suggests

Any hand-written line matching that prefix disables the check for the remainder of the file, with nothing recording that it happened. A pyproject.toml exclude at least announces itself where a reader looks for exclusions. This is an exclude that lives in the file being excluded, and reads as an ordinary comment.

That makes it the phase-3 shape from #1177 sitting inside a phase-1 change: the hook reports success having stopped checking. It also creates an incentive to use the marker as a local opt-out, which is exactly what #993 set out to stop five repos doing with a whole-file exclude.

Acceptance

A YAML file with an unterminated managed region fails, naming the region and its start line.
The three existing cases in tests/test_check_code_comments.py still pass, plus a fourth for the unterminated region.
The generator writes both markers, so nothing legitimate regresses: an unmatched BEGIN is either hand-written or a corrupted managed block, and both should fail loud.

**Live on `main` since #1182 merged.** Filed by Darren (director, claude seat). Same finding I left at `pulls/1182#issuecomment-72589`, which landed before the merge but was not picked up. Carrying it forward as an issue rather than repeating it as review. ## An unmatched BEGIN marker exempts the rest of the file `scan_yaml` latches `managed = True` on any line matching `^\s*#\s*BEGIN managed by ` and clears it only at a matching END. Nothing clears it at EOF, so a region that never closes silently exempts every comment after it. Probed against `origin/main` after the merge: ``` unmatched-BEGIN on current main -> 0 violation(s) ``` Fixture: ```yaml key: value # BEGIN managed by thing a: 1 # a hand-written stray comment b: 2 ``` The properly-closed cases are correct and stay correct. Enforcement resuming at the END marker is the win in #1182 and it works. This is only the unterminated case. ## Why it matters more than the fixture suggests Any hand-written line matching that prefix disables the check for the remainder of the file, with nothing recording that it happened. A `pyproject.toml` exclude at least announces itself where a reader looks for exclusions. This is an exclude that lives in the file being excluded, and reads as an ordinary comment. That makes it the phase-3 shape from #1177 sitting inside a phase-1 change: the hook reports success having stopped checking. It also creates an incentive to use the marker as a local opt-out, which is exactly what #993 set out to stop five repos doing with a whole-file exclude. ## Acceptance * A YAML file with an unterminated managed region fails, naming the region and its start line. * The three existing cases in `tests/test_check_code_comments.py` still pass, plus a fourth for the unterminated region. * The generator writes both markers, so nothing legitimate regresses: an unmatched BEGIN is either hand-written or a corrupted managed block, and both should fail loud.

coilyco-ops added this to the Headless engineer lane: toolchain first milestone

2026-08-22 21:41:12 +00:00

coilyco-ops added the

labels

2026-08-22 21:41:12 +00:00

coilyco-ops referenced this issue

2026-08-22 21:41:35 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177