[ptr727]

Summary

Each of the five issues is implemented the way the maintainer answered it on 2026-11-01.

• An Anchored intentRef Is Dated by Its Whole File, So Unrelated Doc Edits Flag Line-Ending and Versioning Copies #1819, anchored intentRef dating. spec/audit.py hub_last_change now takes the anchor and dates an anchored intentRef by the section its anchor names. It narrows each revision to that region and then runs _last_effective_change, the way check_verbatim narrows a section's history. When the anchor names no heading in the current canonical, it dates the whole file. spec/fidelity_text.py gains heading_slug and extract_anchored, a slug-keyed region extract that works at any heading level (both live anchors are H3). A new test checks that every anchored intentRef in spec/files.json resolves in the hub. That way a typo cannot fall back to whole-file dating without anyone noticing.
• An intent finding verified satisfied cannot be cleared, so a correct resync can never produce a clean run #727, clearing a verified intent finding. The advisory now has its own check id, files.intent. intent_ref parses an intent unit's canonical and anchor in one place. It is a repo-scope check that runs after the file stage, with hub: false and suppression: { endsWithType: null } in spec/checks.json. Before this, the advisory sat inside files.presence. A registry driftNote naming (files.intent) acknowledges a copy with a `<path>@<sha>` code span. That clears the copy until its intent canonical changes again. The note reader, spanned_notes, is shared with the filenaming.scripts exemption, so the file-naming check now goes through it too. The check reports a stale acknowledgement, meaning one the advisory no longer raises at that sha, and it also reports a note that names no such span. AUDIT.md section 7 describes the acknowledgement, and section 8's list of suppression notes now names it.
• Decide Whether section_key Should Casefold Rather Than Lowercase #3710. section_key keeps strip().lower(). Its docstring now says lower() rather than casefold() is intended, since fleet headings are ASCII and the two agree there.
• Make validate.py's files.json Section-Name Match Agree With section_key #3706. spec/validate.py keeps the exact section-name match. A comment at the comparison says why: the declared name is the verbatim disposition label.
• Drop the Stale RegressionTests Clause From PlexCleaner's driftNote Once PlexCleaner #1064 Reaches main #3623. The stale RegressionTests clause is dropped from PlexCleaner's driftNote. PlexCleaner#1064's merge commit is on PlexCleaner main, which carries RegressionTests/tests/ and passes python-directories: RegressionTests from both validator callers.

Verification

• The owned test files pass on the head. The full tests/ suite passed on the first commit.
• spec/validate.py passes.
• The pre-commit gate passes: ruff format, ruff check, mypy, and the prose gate. The prose gate needs the comments label for two comment lines in spec/validate.py: the one Make validate.py's files.json Section-Name Match Agree With section_key #3706 asks for, and the existing comment that now names intent_ref().
• A live audit of one fleet repo on hub 23c7d784 no longer flags .editorconfig, .editorconfig-checker.json, or .gitattributes against the latest whole-file GOVERNANCE.md change. version.json is still flagged, but against the change that actually edited WORKFLOW.md "D3 - Versioning and Classification", not the whole file's latest edit.

Local findings fixed after opening

The third local pass raised three introduced findings once the first push's edit budget was spent. Commit 0ac4676 fixes all three under a fresh pass:

• tests/test_audit_helpers.py now pins that files.intent runs after files.presence, the read it depends on, since spec/validate.py's ordering guard covers only file checks. Commit 7bff4e5 widens that test to the whole class. Every repo check whose function reads run.content, run.found, run.docs, or the README through _readme must sit after the first baseline check.
• A test now pins that intent_trail passes the intentRef's anchor to hub_last_change.
• The heading_slug docstring now says _ is kept as well as -.

The fourth local pass found one more introduced gap: no test drove check_files_intent with a copy read at a declared alternative. Commit d014dcd adds that test. The fifth pass found that no test pinned files.intent's suppression role, and commit b3a8d04 adds one.

Declined local findings

• spec/audit.py hub_last_change anchored narrowing no longer catches an edit to the hub's own .gitattributes, .editorconfig, .editorconfig-checker.json or version.json unless the anchored section also moves (local pass, introduced): declined. The maintainer's 2026-11-01 answer on An Anchored intentRef Is Dated by Its Whole File, So Unrelated Doc Edits Flag Line-Ending and Versioning Copies #1819 chose option 1, dating the anchored section only. The decision record says option 2, adding the file's own hub canonical, "still takes the noisy doc date unless combined with option 1", and option 2 was not chosen. An intent finding verified satisfied cannot be cleared, so a correct resync can never produce a clean run #727's 2026-08-15 comment shows hub-only edits to those files, such as a CRLF default or a hub-tree pin, are exactly the noise a downstream copy must not be dated by. The content-identical shortcut against the hub file at path stays, and it only ever clears.

• spec/fidelity_text.py extract_anchored's extent against sections() (local pass, introduced, design): declined. sections() is the manifest's level-two unit, which ends only at the next H2, and every verbatim section and the carry depend on that extent. An anchor names a GitHub section, which ends at the next heading of its own level or above, and that is what bounds an H3 such as "Line Endings" at all. If one primitive served both, it would either move the H2 unit's extent or lose the H3 case. So the sections() docstring now claims only the level-two extent. The any-level duplicate inside scripts/build_dist.py is Share One Any-Level Heading Region Primitive Between build_dist heading_body and fidelity_text extract_anchored #3810.

• spec/audit.py spanned_notes shares only the no-span half of a code-span driftNote (local pass, introduced, consolidation): declined. The stale half matches differently at each site. A file-naming path is checked against what the check reports. An intent path@sha is checked by sha prefix against the change the advisory cites. Folding the two would mean passing the matcher in, which costs more than the few lines it saves.

• spec/validate.py Make validate.py's files.json Section-Name Match Agree With section_key #3706 comment gives the verbatim disposition label as the reason for the exact match, but the match also covers intent-fidelity and string-form sections (local pass, introduced): declined. The comment states the reason the maintainer's 2026-11-01 answer on Make validate.py's files.json Section-Name Match Agree With section_key #3706 recorded, "the files.json name is the verbatim disposition label". A section's fidelity is a one-field manifest edit, and an exact rule that holds for every declared section means flipping one to verbatim never needs a spelling fix first.

Pre-existing findings, filed

• docs/reusable-workflows.md tracker: the PlexCleaner item is a sibling of Drop the Stale RegressionTests Clause From PlexCleaner's driftNote Once PlexCleaner #1064 Reaches main #3623's stale claim (local pass, pre-existing), filed as Re-Check the PlexCleaner Item in the Reusable-Workflows Tracker Against Its main #3813.

Pre-existing findings, not filed

• registry/repos.json PlexCleaner driftNote: the clause this change keeps still says "uvx scripts profile", a term the python-codestyle build-versus-lint-only split no longer uses (local pass, pre-existing).

Dropped findings

• spec/fidelity_text.py section_span and extract_section docstrings, and scripts/build_dist.py heading_body, say "case-folded" or "folded" (local pass, pre-existing, wording on text this change did not touch).

Deferred

• RESYNC.md section 5, "What a Resync Cannot Detect", still summarizes the advisory without the anchor and acknowledgement cases. RESYNC.md is outside this change's file claim, so it is filed as Bring RESYNC.md's Intent Advisory Summary in Line With Anchored Dating and driftNote Acknowledgements #3808 (local pass, introduced, deferred).
• The three line-ending units name GOVERNANCE.md#line-endings, which is a one-paragraph pointer to the comment-and-doc-style Skill. Dated by that section alone, their advisory fires only when the pointer itself is reworded. Re-pointing them is a spec/files.json decision outside this change's claim, filed as Decide Whether the Line-Ending intentRefs Should Name the Section Holding the Policy #3812 (local pass, introduced, deferred).
• spec/fidelity_text.py extract_anchored and scripts/build_dist.py heading_body compute the same any-level region. scripts/build_dist.py is outside this change's file claim, so it is filed as Share One Any-Level Heading Region Primitive Between build_dist heading_body and fidelity_text extract_anchored #3810 (local pass, introduced, consolidation, deferred).

Closes on promotion: #1819, #727, #3710, #3706, #3623

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a repository check that flags outdated intent copies and supports acknowledgements tied to a cited change.
  • Intent checks can now focus on a named section and ignore changes limited to formatting or workflow normalization.
• Documentation
  • Clarified how to record verified intent advisories and how acknowledged copies are checked.
  • Updated the PlexCleaner advisory to reflect that Python lockfile pinning does not apply.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: ptr727/ProjectTemplate
• Branch: burndown/1819-audit-intent
• File: .coderabbit.yaml
• Commit: 7bff4e5
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: ff8573bc-ca10-492b-9e24-ba7c1c3b499e

Commits

Reviewing files that changed from the base of the PR and between 6dfcc04 and 7bff4e5.

Files selected for processing: 9

• AUDIT.md
• registry/repos.json
• spec/audit.py
• spec/checks.json
• spec/fidelity-model.md
• spec/fidelity_text.py
• spec/validate.py
• tests/test_audit_helpers.py
• tests/test_fidelity_text.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

Adds anchored intentRef dating and a repository-scoped files.intent check. The check compares intent copies with canonical changes and accepts path-and-SHA drift-note acknowledgements. Baseline reads record the path used, and drift-note span parsing is shared with file-naming exemptions.

Changes: Intent freshness audit

Layer / File(s)	Summary
Anchored canonical-date resolution spec/fidelity_text.py, spec/audit.py, spec/fidelity-model.md, spec/validate.py, tests/test_fidelity_text.py, tests/test_audit_helpers.py	Heading regions determine scoped change dates for anchored intent references. Unresolved anchors use whole-file history. Tests cover heading extraction, section dates, and reference resolution.
Intent trail detection and check wiring spec/audit.py, spec/checks.json, tests/test_audit_helpers.py	Baseline reads record the path used. The files.intent check compares intent-copy commit dates with canonical changes and validates acknowledgements. Tests cover alternatives, stale acknowledgements, and check registration.
Drift-note validation and guidance spec/audit.py, AUDIT.md, registry/repos.json	Drift-note spans are parsed for check-specific acknowledgements and file-naming exemptions. Audit guidance and the PlexCleaner registry note are updated.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• ptr727/ProjectTemplate#727: Adds per-file files.intent acknowledgements using path-and-SHA spans.
• ptr727/ProjectTemplate#1819: Dates anchored intentRef values from the named section, with whole-file fallback.
• ptr727/ProjectTemplate#3706: Documents exact heading-name matching in the validator.
• ptr727/ProjectTemplate#3710: Documents the existing strip-and-lowercase section_key behavior.
• ptr727/ProjectTemplate#3813: Updates the PlexCleaner registry drift note’s test-related claim.

Possibly related PRs

• ptr727/ProjectTemplate#3417: Introduced the audit and registry contracts that this change extends with files.intent and its acknowledgements.

Merge Risk: Minimal · up to 7bff4

No specific issue remains that calls for a change before merging; proceed with normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 41.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and specifically describes the main changes: section-based dating for anchored intentRef values and driftNote acknowledgement of verified intent advisories.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 41.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 24 functions across 5 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[ptr727]

A recorded local strict-review pass covers head 591ffffbbc20d951e860233546c448d750709350, the content this pull request carries at that commit against develop, and it recorded 6 findings.

[Copilot]

🟡 Changes recommended

Approval is blocked by an unresolved moderate issue in required file-check stage ordering, with additional documentation and regression-test gaps still active.

3 open issues

• Validate required files.intent stage ordering · New
• Correct the heading_slug underscore documentation · New
• Assert intentRef anchors reach hub_last_change · New

What changed in this PR

This pull request updates intent-fidelity auditing to date anchored references by their Markdown sections and allow verified intent advisories to be acknowledged through registry driftNote entries.

Changes:

• Adds heading slugging and anchored region extraction for section-scoped history comparisons.
• Introduces the repository-level files.intent check with SHA-based acknowledgement and stale-note handling.
• Updates validation comments, documentation, tests, and audit guidance.
• Removes PlexCleaner's obsolete RegressionTests drift-note clause.

File	Description
tests/​test_fidelity_text.py	Tests heading slugs, anchored extraction, and lowercased section keys.
tests/​test_audit_helpers.py	Tests intent advisories, acknowledgements, alternatives, and anchored history dating.
spec/​validate.py	Documents exact section-name validation and updates intent helper terminology.
spec/​fidelity-model.md	Documents anchored intent dating and acknowledgement behavior.
spec/​fidelity_text.py	Adds heading slugging and any-level anchored region extraction.
spec/​checks.json	Registers the repository-scoped files.intent check.
spec/​audit.py	Implements anchored history dating, intent trails, acknowledgements, and shared note parsing.
registry/​repos.json	Removes PlexCleaner's resolved regression-test drift-note clause.
AUDIT.md	Documents recording and reconciling verified intent advisories.

_{Review effort: Lite}

[codecov]

Codecov Report

❌ Patch coverage is 97.36842% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.90%. Comparing base (23c7d78) to head (7bff4e5).
⚠️ Report is 2 commits behind head on develop.

Files with missing lines	Patch %	Lines
spec/audit.py	96.96%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3811      +/-   ##
===========================================
+ Coverage    82.72%   82.90%   +0.17%     
===========================================
  Files           29       29              
  Lines         9629     9700      +71     
===========================================
+ Hits          7966     8042      +76     
+ Misses        1663     1658       -5     

Flag	Coverage Δ
python-3.13	82.90% <97.36%> (+0.17%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ptr727]

A recorded local strict-review pass covers head b3a8d042769fd800026a1455780a5a860c2e0c96, the content this pull request carries at that commit against develop, and it recorded 1 finding.

[ptr727]

A recorded local strict-review pass covers head 7bff4e50fbf05c9f6210d5dce84e3affd4b433ba, the content this pull request carries at that commit against develop, and it recorded 0 findings.

[ptr727]

@coderabbitai review

[coderabbitai]

Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ptr727]

CodeRabbit pre-merge warning on head 7bff4e5, "Docstring coverage is 41.67% which is insufficient. The required threshold is 80.00%": No change needed. Every helper this change adds with any logic carries a docstring: hub_last_change, intent_ref, intent_trail, intent_findings, spanned_notes, heading_slug, and extract_anchored. The one that does not is check_files_intent, a registry-dispatched check_<id> wrapper. In spec/audit.py, 28 of 38 check_ functions carry no docstring, because spec/checks.json's description field documents each check. The 80% figure is CodeRabbit's default threshold, not a rule this repository sets. Its review otherwise reported no actionable comments.