Stop claiming CI runs the same checks as the clean-compile - #497
Merged
Conversation
The Clean-Compile Verification bullet said "CI runs the same checks as a backstop". CI runs those language checks plus the doc-lint set, markdownlint, cspell, actionlint and editorconfig-checker, and all of it reports into the one required status. So the sentence a reader consults to answer what must be green before a push licensed the inference that a green clean-compile predicts a green CI, which is false for every repo in the fleet. It cost a real round trip. Fifteen files went in LF to a CRLF-default repo, the documented clean-compile passed, markdownlint and cspell were run by hand and passed, and CI failed on the one checker the pre-commit gate never names. GOVERNANCE.md "Verification Discipline" predicts that exact failure in those words, and the agent had read this gate instead. The bullet now says the clean-compile is not the whole gate, names the doc-lint set, states that a green clean-compile does not predict a green CI, and points at the rule that does govern the pre-push gate. The cross-reference list at the top gains verification discipline, since it enumerated what lives in GOVERNANCE.md instead and omitted the one rule this section needed. The first draft of the fix repeated the defect it was fixing, by claiming Verification Discipline documents each linter's invocation. Those live under Workflow YAML Conventions, so the two are cited separately. Raised from Financial-Modeling (#496). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the fleet’s CODESTYLE.md documentation to stop implying that a local language clean-compile run is equivalent to (or predictive of) the full CI-required gate, aligning the pre-commit guidance with the broader “Verification Discipline” rule in GOVERNANCE.md.
Changes:
- Updates the “Clean-Compile Verification” guidance to explicitly state that clean-compile is not the entire CI gate and adds links to the relevant
GOVERNANCE.mdsections. - Extends the opening cross-reference sentence to include verification discipline as a cross-cutting process rule.
- Adds new reference-style link definitions for the newly cited
GOVERNANCE.mdanchors.
The replacement sentence named the doc-lint set as what CI adds to the clean-compile, and the validation workflow also runs registry and spec validation, the script self-tests, repo_gate.py and prose_lint.py. So the fix for a sentence that understated the gate understated it again, one layer down, which is the same defect wearing a longer list. An enumeration is the wrong shape here. This file is carried fleet-wide and each repo's workflow runs a different set, so any list is stale somewhere the moment it is written. The sentence now says CI runs everything else its validation workflow runs, names the doc-lint set as a floor rather than the whole, and tells the reader to read the workflow for the full list instead of trusting the sentence to enumerate it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
…to main (#498) Promotes eight commits from `develop`. Every one traces to a defect found in use rather than to a planned change, and five came from downstream agents reporting what the procedure did not cover. ## What lands | Commit | Change | | --- | --- | | `a0f6f24` (#487) | `docs/content-import.md`, the three capture-pass findings from the Blog migration: an export is not a media capture, a sitemap is not the URL contract, and an HTTP fetch is not the original | | `8bdfa22` (#494) | The write-guard scopes by **owner** rather than exact origin, with `GH_WRITE_GUARD_ALLOW` for a different owner. Four target-flag spellings that silently bypassed rule 3 are closed | | `981d92f` (#492) | The purpose is restated as agent enablement, in `README.md`, `HISTORY.md` and `AGENTS.md` | | `275705b` (#493) | `TODO.md` becomes the fleet backlog destination, and `spec/readme-structure.md` stops mandating the construction `GOVERNANCE.md` bans | | `b6ab6db` (#491) | `STANDUP.md` step 0A names the maintainer-only prerequisites, and step 4 asserts the remote | | `89e3868` (#488) | The `version.json` floor is chosen at standup rather than inherited | | `eed2e00` (#495) | `README.md` gains "What It Achieves", the objectives and the fidelity ladder | | `f6dc5e6` (#497) | `CODESTYLE.md` stops claiming CI runs the same checks as the clean-compile | ## Provenance Five of the eight answer issues filed by downstream agents: #456 (Blog intake), #489 and #490 (the Blog carry), and #496 (Financial-Modeling). That loop is the one "What It Achieves" now describes, and this promotion is it closing. ## Divergence, checked rather than assumed `main...develop` reports `8 ahead, 102 behind, diverged`. **The 102 are topology, not content.** They are 79 promotion merge commits, which are main-only by construction because a promotion is a two-parent merge, plus 23 `Update codegen files` bot commits from this repo's pre-2.0 life as a .NET sample template. `git diff --name-status origin/develop origin/main` returns exactly the 12 files these 8 commits touch, so there is **no main-only content** to reconcile. ## Verification on the merged `develop` Every gate re-run after the last merge, not inherited from the individual PRs: - `prose_lint.py . --check charset --check dupword --check spelling` clean tree-wide. - `repo_gate.py` clean (`eol`, `sha-pin`). - `spec/validate.py` clean, 21 cataloged repos classify. - `gh-write-guard.py --selftest` passes, including the nine new repository-scope cases. - `python3 -m unittest discover -s scripts`, 180 tests pass. - The `README.md` objectives list verified as one continuous list of 8 bullets with the fidelity table nested, since an unindented table split it in review. ## Merge mechanics This is a promotion, so it merges as a **merge commit** with two parents, never a squash. Its head **is** `develop`, so `--delete-branch` must not be used. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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.
Fixes #496, raised from Financial-Modeling. Accepted in full, including the issue's own reasoning about where the rule should not move.
Verified against the tree, not taken on report
CODESTYLE.md:19asserts CI runs "the same checks"validate-task.ymladditionally runs the doc-lint seteditorconfig-checker(L45), plusspec/validate.py, the script self-tests,repo_gate.pyand the blocking prose runCODESTYLE.md:5omits verification discipline from its cross-reference listWhy the sentence mattered
It is the line a reader consults to answer "what must be green before I push", and it licensed the inference local clean-compile green implies CI green, which is false for every repo in the fleet. The rule that actually governs is a section away in another file, so an agent starting from the pre-commit gate never reaches it.
The issue reports the concrete cost: fifteen files written LF into a CRLF-default repo, the documented clean-compile passing, markdownlint and cspell run by hand and passing, and CI failing on the one checker the pre-commit gate never names.
GOVERNANCE.md"Verification Discipline" predicts that exact failure in those words, namingeditorconfig-checkerand line endings specifically.What lands
Both edits the issue proposed, and nothing more:
GOVERNANCE.md"Verification Discipline".GOVERNANCE.mdinstead and omitted the one rule this section needed.The rule is not moved into
CODESTYLE.md, per the issue's own argument.CODESTYLE.mdalready delegates line endings toGOVERNANCE.mddeliberately, and "Verification Discipline" is the right home for a rule about gates that pass while the work is unfinished. The defect was only that the doc defining the pre-commit gate misstated the gate's scope.One thing worth recording
The first draft of this fix repeated the defect it was fixing. It claimed "Verification Discipline" also documents each linter's known-working invocation. Those live under Workflow YAML Conventions, a different H2, so the draft asserted a doc structure that does not exist while correcting a sentence that asserted a CI scope that does not exist. Caught by checking the heading rather than recalling it, and the two are now cited separately.
That is the failure mode
GOVERNANCE.mdnames directly: no linter catches it, because markdownlint, cspell, actionlint andeditorconfig-checkerall pass on a claim that is merely untrue.Carry
CODESTYLE.mdis carried atintent, wholefidelity, so this is a hub fix that every fleet repo re-vendors. It changes prose only, no gate behavior.Verification
Ran the whole gate rather than the parts that looked relevant, which is the rule this PR is about:
prose_lintblocking set clean tree-wide, and clean on changed lines.GOVERNANCE.md(## Verification Discipline,### Running the Linters Locally (Known-Working Invocations)).editorconfig-checkerclean tree-wide, which is the checker the incident turned on.🤖 Generated with Claude Code