Check carried markdown section presence at DRIFT (#368, PR-2) - #370
Merged
Conversation
Turn on the section-presence check the scope mechanism (PR-1) made possible. spec/audit.py previously verified only file-path presence; sections were never read. Now, for each carried entry, union the sections scoped to the repo (required_sections filters each section by its own appliesTo), and for a markdown file that exists, confirm every required section heading is present (heading_texts, case-insensitive). A missing section is a DRIFT finding, not a LETTER - a heading rename reads as missing and equivalence is judged by hand, and DRIFT does not flip the exit code, so this is safe to run fleet-wide. Non-markdown "sections" (e.g. a tasks.json task group) are intent markers, not headings, so the heading check is gated to .md files. File-presence behavior is unchanged: the checked-path list is identical for all 21 cataloged repos, so this only adds section DRIFT findings. AUDIT.md notes the new check. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Enables section-presence auditing for carried Markdown files so the fleet audit can surface DRIFT when required headings (scoped via appliesTo) are missing from otherwise-present carried docs.
Changes:
- Add
required_sections()to compute required headings per repo scope, including per-sectionappliesTo. - Add
heading_texts()and integrate a Markdown heading-presence check into the file-presence audit loop (DRIFT-only). - Update
AUDIT.mdto document the new section-presence behavior and its DRIFT semantics.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| spec/audit.py | Implements scoped required-section computation and a Markdown heading-presence DRIFT check during file presence auditing. |
| AUDIT.md | Documents that missing required Markdown sections in carried files are reported as DRIFT (not LETTER). |
Copilot round-1 findings: - audit.py: the section-presence check silently skipped when the contents API returns no inline content (an oversized >1MB file), which is exactly the gates-fail-loud-never-narrow-quietly discipline this repo enforces. Emit a DRIFT saying the check could not run instead of passing as a false clean. - AUDIT.md: drop the clause-joining semicolon on the line edited here. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot round-2 finding: the DRIFT message and comment assumed a >1MB oversized file, but the contents API also omits inline content for a symlink or submodule. State that no inline content was returned and let triage judge the cause. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
Second of the staged PRs for #368. PR-1 gave sections a scope; this turns on the section-presence check in the audit. Previously
spec/audit.pyverified only file-path presence —sectionswere never read, so a repo carrying anAGENTS.mdmissing half its required sections passed clean.Change
required_sections(item, sel)— the sections a repo must carry from a baseline entry, filtered by each section's ownappliesTo(a bare-string section is*; an object section carries its selector).heading_texts(md)— case-insensitive heading extraction.Why DRIFT, not LETTER
A heading rename reads as "missing," and equivalence is judged by hand (AUDIT.md §7). DRIFT surfaces in every report and blocks a "clean" verdict but does not flip the exit code (only DEFECT/LETTER/ERROR do), so this is safe to turn on fleet-wide. Non-markdown "sections" (e.g. the tasks.json task group) are intent markers, not headings, so the heading check is gated to
.mdfiles.Verified
AGENTS.mdpasses clean (all 8 required sections present); a doc missing a heading is flagged; section-levelappliesTofiltering resolves correctly (ready for PR-3's scoped sections).Held on
develop— nodevelop → mainpromotion. The fleet triage (running the live audit to see which repos'AGENTS.mddrift) happens after merge.