Skip to content

Bound Step 4 substitution-table scan by heading, not a fixed byte window - #83

Merged
dmccoystephenson merged 1 commit into
mainfrom
fix/check-docs-substitution-table-window
Jul 29, 2026
Merged

Bound Step 4 substitution-table scan by heading, not a fixed byte window#83
dmccoystephenson merged 1 commit into
mainfrom
fix/check-docs-substitution-table-window

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • check_docs.py read the Step 4 substitution table through a hardcoded table_start + 8000 byte window, which had shrunk to ~231 bytes of headroom against the current template.
  • A table row falling outside that window silently drops out of declared, so check_placeholders reports a placeholder as "missing a Step 4 substitution-table row" even when the row exists — a misleading CI failure pointing contributors at the wrong problem.
  • Bound the scan by the next ### heading instead of a byte count, so the section boundary tracks the template's actual structure as the table grows.

Research grounding

No RESEARCH.md finding applies — this is a mechanical CI-tooling correctness fix (byte-window vs. structural parsing), not a change to create-dev-loop.md's template or phase definitions.

Test plan

  • python3 scripts/check_docs.py passes cleanly on the current tree with the fix applied.
  • Regression check (per the issue's suggestion): simulated a placeholder used in the template body with its substitution-table row pushed past byte 8000 (via padding rows). Confirmed the old windowed logic drops the row from declared (false "missing" report), and the new heading-bounded logic correctly finds it.
  • No .claude/ state staged (git status --porcelain before commit showed only scripts/check_docs.py).
  • Not applicable: this PR doesn't touch create-dev-loop.md/the template surface, so the /create-dev-loop-against-a-fixture validation in CLAUDE.md's "Testing changes" section doesn't apply here.

Closes #80

check_docs.py read the table through a hardcoded 8000-byte window with
only ~230 bytes of headroom against the current template. A row falling
outside the window silently drops from `declared`, so CI reports a
placeholder as missing a row even though the row exists — the wrong
failure message pointing at the wrong problem. Scan to the next `### `
heading instead so the section boundary tracks the template's actual
structure as it grows.

Closes #80

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric:

Universal:

  • Scope: PASS — only scripts/check_docs.py is touched; the single 2-line change is exactly what's necessary to close check_docs.py reads the Step 4 substitution table through a fixed 8000-byte window with only 231 bytes of headroom #80, no unrelated churn.
  • Tests-new: N/A — no new template placeholder or Step is introduced by this PR, so there's nothing new here to exercise.
  • Tests-fix: PASS (simulated stash-and-revalidate) — the real template doesn't currently have a row past byte 8000, so a literal stash-and-rerun against the tree wouldn't surface the defect either way. Instead simulated both the old windowed logic and the new heading-bounded logic against a copy of the template with a placeholder + row pushed past offset 8000 (padding rows inserted into the Step 4 table): old logic reports the row as not declared (reproducing the false "missing" failure), new logic correctly finds it. Details in the PR test plan.
  • Sibling structure: N/A — no new section added.
  • Sibling renames: N/A — no renames in this PR.
  • Docs: PASS — no documented claim changes; this is a CI-tooling correctness fix enforcing an invariant CLAUDE.md already states correctly, not a change to what's documented.
  • Issue resolution: PASS — check_docs.py reads the Step 4 substitution table through a fixed 8000-byte window with only 231 bytes of headroom #80's named surface area (check_docs.py:63's fixed 8000-byte window) is exactly what's changed; the suggested fix (bound by next ### heading) is implemented as proposed.
  • Manual validation: PASS — python3 scripts/check_docs.py passes cleanly on the current tree with the fix applied.

Repo-specific:

  • Placeholder-consistency: N/A — this PR doesn't touch create-dev-loop.md's template or its Step 4 table.
  • Escaping: N/A — no fenced-code-block changes in the template.
  • Research-grounding: PASS — no RESEARCH.md finding applies (stated explicitly in the PR body); this is CI-tooling parsing correctness, not a change to create-dev-loop.md's template or phase definitions.

No judgment-call items to flag; all applicable items pass on direct evidence.

@dmccoystephenson
dmccoystephenson merged commit e933cdb into main Jul 29, 2026
1 check passed
@dmccoystephenson
dmccoystephenson deleted the fix/check-docs-substitution-table-window branch July 29, 2026 08:51
dmccoystephenson added a commit that referenced this pull request Aug 3, 2026
…dow (#83)

check_docs.py read the table through a hardcoded 8000-byte window with
only ~230 bytes of headroom against the current template. A row falling
outside the window silently drops from `declared`, so CI reports a
placeholder as missing a row even though the row exists — the wrong
failure message pointing at the wrong problem. Scan to the next `### `
heading instead so the section boundary tracks the template's actual
structure as it grows.

Closes #80

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

check_docs.py reads the Step 4 substitution table through a fixed 8000-byte window with only 231 bytes of headroom

1 participant