Repository navigation
Merged
Conversation
…nce Splits (#3578) ## Summary This audits the `WORKFLOW.md` sentence-length sweep (#3561, squash `d2b8babf`) split by split. Each of its 107 split or rewritten sentences was compared with the pre-sweep text. Ten had lost or changed meaning, and this repairs each one to say what the original said. Every repaired sentence stays within the 25-word cap. The `workflow-ci-contract` include regions for sections 3, 4, and 5 are regenerated from the new text with `scripts/build_dist.py`. ## Splits Repaired Each entry is the sweep's text -> the repair, then the drift class. **A pronoun or "that" losing its antecedent (6)** 1. Intro, defining principle. "A violation of a convention it states as a guarantee" -> "A violation of a convention section 4 states as a guarantee". Standing alone, "it" could read as section 2, the last singular noun before it. 2. Section 3, Release Model. "so `github.actor` gates it." -> "so `github.actor` gates that push." The pre-sweep "it" was the bot push, and the split left it pointing at "every Dependabot/codegen PR". 3. D1.6. "The second is there because a run triggered by a Dependabot pull request reads the Dependabot store." -> "The token is in the second because ...". The pre-sweep text said the token lives in the second store for this reason, and "The second is there" had no clear subject. 4. D4.7. "the branch has not moved again since it read that record." -> "since that check." This restores the pre-sweep words. The re-check compares the branch tip with the head fetched for the tree comparison, so "since it read that record" named a narrower point than the original did. 5. 5A citation rule. "It is its own name where a setting, a ruleset, or a secret name rather than a file is the evidence." -> "It is the evidence's own name where ...". With "It" now the citation, "its own name" read as the citation's name rather than the setting's. 6. Section 6, `codegen`. "It carries no per-run timestamp or GUID." -> "That workflow carries no per-run timestamp or GUID." Pre-sweep, the generation workflow carried this property, but the next sentence's "It" is the type, so both read as the type. **A reason dropped, or put on the wrong half (2)** 1. D7.3. "A composite action's inputs are strings whatever their caller passed." -> "The composite-action gate compares against a string because a composite action's inputs are strings whatever their caller passed." Pre-sweep, this clause explained the string comparison, and the split left it as a bare fact. 2. Section 6, `hugo`. "The gate admits production from the default branch only, while any ref may reach a non-production environment. That is because proving a branch before it merges is what that environment is for." -> "The gate admits production from the default branch only. Any ref may reach a non-production environment, since proving a branch before it merges is what that environment is for." The pre-sweep "since" explained only the non-production half, and "That is because" stretched it over the production rule too. **A condition no longer reaching its clause (1)** 1. Section 3, Output Seam, package-registry push. "NuGet.org answers `HTTP 401` with `does not start with <owner>/<repo>/.github/workflows/`." -> "There NuGet.org answers `HTTP 401` with ...". Pre-sweep, the 401 answered the rejected cross-repository token exchange. Standing alone, it read as unconditional. **A split that no longer parses (1)** 1. Section 3, Output Seam, file on the GitHub release. "Or, for a repo calling the hub-hosted task, the files its `build-release-asset` hook writes, which the task uploads as one such artifact." -> "For a repo calling the hub-hosted task, the path is instead the files its `build-release-asset` hook writes, which the task uploads as one such artifact." The sweep's sentence was a fragment, and the repair restores the original either/or. No sentence was stopped on. No heading, anchor, link target, table, code, inline code, quoted string, or ID changes. ## Verification - `python3 scripts/prose_lint.py --check sentence-length WORKFLOW.md`: exit 0. - `prose_lint.py` default rules on `WORKFLOW.md` and the three reference files: exit 0. - `uv run --no-project --script scripts/build_dist.py --check`: current. - The pre-commit hook (ruff, mypy, prose, EOL) passed on the commit. ## Local Review One recorded `local-strict-review` pass over the whole branch diff, at the `frontier` tier, raised no findings. That pass also re-read all 107 sweep splits independently and found none left unrepaired. It confirmed the three closest calls against the workflows they describe. Those are D4.5's "That gate is that it `needs:` the release-task call", D9.1's exception to the pin, and `upstream-wrapper`'s stated reason. ## Dropped findings - `.agents/skills/workflow-ci-contract/references/d-guarantees.md:3`, `style`: a 28-word `sentence-length` hit in the skill's own preamble, outside the include region. #3561 did not write it, and this change does not touch it. Refs #3531 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
) ## Summary Audits every sentence that #3551 (`GOVERNANCE.md`, squash `444ec63e`) and #3559 (`AGENTS.md` and `.github/copilot-instructions.md`, squash `eb35070d`) split or rewrote. Each new sentence was compared with its original. The splits listed below had lost or changed meaning, and each is repaired here. Every repaired sentence stays within the 25-word cap. The `agent-conduct` and `session-handoff` include regions are regenerated from the new `GOVERNANCE.md` text. No other skill's region changes. ## Repairs Each line reads sweep text -> repaired text. ### Reason left on only one half of a split - `GOVERNANCE.md` "Verification Discipline", canonical content: the manifest-owned tree, the byte-for-byte compare, and the drift on the next fidelity check stood as bare facts. -> "That is because the tree is manifest-owned, and the copy is compared...", then "It is also because a local edit there is drift...". - Same bullet: "It would otherwise reach a carrier..." -> "It is also because such a unit would otherwise reach a carrier...". - `GOVERNANCE.md` "Communicating with the User", blocked work: "The one line still waiting on the user is the easiest in it to skim past." -> "It is also because the one line still waiting on the user is the easiest in a summary to skim past." - Same section, parked queue: "Closing such an issue just to clear the queue discards..." -> "It is also because closing such an issue...". - `GOVERNANCE.md` "Workflow YAML Conventions", action pinning: "Dependabot still bumps SHA pins..." -> "It is also because Dependabot still bumps SHA pins...". - `GOVERNANCE.md` "Running the Linters Locally", pre-push hook: "Those describe the same content only sometimes." -> rejoined to its "That is because" sentence with ", and those describe...". - Same section, excludes: "The gate refuses one rather than reporting..." -> "Skipping them also matters because the gate refuses one...". ### A "so" consequence left on only one half - `GOVERNANCE.md` "Hub-Hosted Tooling": "A tool taking its target as an argument runs anywhere..." -> "Likewise, a tool taking its target...". - `GOVERNANCE.md` "Running the Linters Locally", pre-push hook: "The prose layer above stays the agent-agnostic one..." -> "The prose layer above therefore stays...". ### A condition no longer reaching every clause it covered - `GOVERNANCE.md` "Verification Discipline", locating checks: "Read that file whole where it exists..." -> "In that case, read that file whole...". - `GOVERNANCE.md` "Repository Details": "The fix is to sharpen the declared source..." read as the fix for any drift. -> "The fix there is to sharpen...". ### A pronoun or "that" losing its antecedent - `GOVERNANCE.md` "Verification Discipline", canonical content: "It adds a bounded slice..." -> "That work also covers a bounded slice...". - `AGENTS.md` "Session Scope": "That section states the account whole..." now followed a different sentence. -> "That `GOVERNANCE.md` section states the account whole...". ### An example list turned into a closed definition - `GOVERNANCE.md` "Character Set": "Its tiers are never legitimate, ..., and developer-typed Unicode." The skill has four tiers, and developer-typed Unicode stays regardless of tier. -> "That tier system covers what is never legitimate, ...", then "It also covers a fixed set of emoji callout markers and developer-typed Unicode." ### A restriction widened - `.github/copilot-instructions.md` "Disproved Claims": "A reason not to check is strictly worse than proving the claim a second time." generalized to any reason. -> "That outcome is strictly worse...". ## Verification - `python3 scripts/prose_lint.py --check sentence-length` on `GOVERNANCE.md`, `AGENTS.md`, and `.github/copilot-instructions.md`: exit 0 each. - `uv run --no-project --script scripts/build_dist.py --check`: current. - `python3 scripts/prose_lint.py . --diff origin/develop` and the whole-tree `--check` block from `OPERATIONS.md` "Local Verification": exit 0. - `scripts/repo_gate.py`, `spec/validate.py`, and `canonical_review.py status`: clean. - `unittest discover -s tests`: 3081 tests, OK (7 skipped). ## Local Review Two recorded `local-strict-review` passes at the `frontier` tier, each checking every hunk against its pre-sweep original. The first raised 2 `introduced` findings. The Character Set repair had an unclear "It" and a list with no noun, and the excludes repair had an "It" with no antecedent. Both are fixed in the second commit. The second pass raised none. Refs #3531 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
 |
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The identified sentence-context issues were addressed across the canonical and generated documentation, with no active blocking issues recorded.
No open issues 🎉
What changed in this PR
This pull request promotes develop to main and restores meaning lost through sentence splits across governance, workflow-contract, agent-conduct, and session-handoff documentation, along with their generated distributions.
Changes:
- Restores antecedents, reasons, conditions, and complete sentence context in
WORKFLOW.mdand workflow-contract references. - Repairs corresponding meaning in
GOVERNANCE.md,AGENTS.md, and.github/copilot-instructions.md. - Regenerates the affected skill copies and updates Claude source digests.
- One documentation nit remains in
GOVERNANCE.mdregarding the distinction between developer-typed Unicode and the four-tier system. - The named distribution check was not independently rerun because
uvwas unavailable in the container.
| File | Description |
|---|---|
WORKFLOW.md |
Restores workflow-contract sentence context, conditions, and explanations. |
GOVERNANCE.md |
Repairs governance rationale, scope, and antecedents. |
AGENTS.md |
Clarifies the governance-section reference in session handoffs. |
.github/skills/workflow-ci-contract/references/test-methodology.md |
Regenerated workflow test-methodology reference. |
.github/skills/workflow-ci-contract/references/d-guarantees.md |
Regenerated workflow guarantees reference. |
.github/skills/workflow-ci-contract/references/architecture.md |
Regenerated workflow architecture reference. |
.github/skills/session-handoff/SKILL.md |
Regenerated session-handoff guidance. |
.github/skills/agent-conduct/SKILL.md |
Regenerated agent-conduct guidance. |
.github/copilot-instructions.md |
Clarifies the disproved-claims rule scope. |
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/test-methodology.md |
Regenerated Claude workflow test-methodology reference. |
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/d-guarantees.md |
Regenerated Claude workflow guarantees reference. |
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/architecture.md |
Regenerated Claude workflow architecture reference. |
.claude-plugin/fleet-skills/skills/session-handoff/SKILL.md |
Regenerated Claude session-handoff guidance. |
.claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md |
Regenerated Claude agent-conduct guidance. |
.claude-plugin/fleet-skills/.source-digests/workflow-ci-contract |
Updated workflow-contract source digest. |
.claude-plugin/fleet-skills/.source-digests/session-handoff |
Updated session-handoff source digest. |
.claude-plugin/fleet-skills/.source-digests/agent-conduct |
Updated agent-conduct source digest. |
.agents/skills/workflow-ci-contract/references/test-methodology.md |
Updated canonical workflow test-methodology source. |
.agents/skills/workflow-ci-contract/references/d-guarantees.md |
Updated canonical workflow guarantees source. |
.agents/skills/workflow-ci-contract/references/architecture.md |
Updated canonical workflow architecture source. |
.agents/skills/session-handoff/SKILL.md |
Updated canonical session-handoff source. |
.agents/skills/agent-conduct/SKILL.md |
Updated canonical agent-conduct source. |
Review effort: Lite
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3580 +/- ##
=======================================
Coverage 81.60% 81.60%
=======================================
Files 26 26
Lines 9070 9070
=======================================
Hits 7402 7402
Misses 1668 1668
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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.
Summary
Promotes
developtomain, carrying the sentence-split audit of the carried rule text:WORKFLOW.md, the workflow-ci-contract references, and their generated copies.GOVERNANCE.md,AGENTS.md, and.github/copilot-instructions.mdsentence splits, and in the agent-conduct and session-handoff skills with their generated copies.Both pull requests continue #3531 and do not close it.
🤖 Generated with Claude Code