Consume the fleet prose rules from the hub

[ptr727]

First fleet adoption of the hub's prose gate, and the live test of its ref design. Pairs with ptr727/ProjectTemplate#520.

What this repository gains

The prose rules that govern it live in the hub, and nothing here ran them, so a comment or a sentence breaking a documented rule reached main with every linter green. markdownlint, cspell, actionlint and editorconfig-checker all pass on prose that breaks a GOVERNANCE.md rule, which is exactly why the gate exists.

Why an action instead of a vendored script

The checker is a 934-line Python file with a 1,349-line test beside it. Copying it into every repository would make each rule change a fleet-wide sweep and would put twenty drifting copies where one canonical belongs. Consuming it as a composite action is possible because the hub is public: a public repository's actions are consumable by any repository, with no organization account required.

The ref design under test

• The uses: pin is one literal, identical on main and develop. uses: accepts no expressions, so a per-branch ref would be a permanent one-line divergence that every develop -> main promotion has to carry.
• Branch-dependent behavior lives inside the action. A develop-targeted run reads the rules from hub develop, so an unpromoted rule change is exercised here before it is promoted. Every other run uses the copy bundled at the pinned commit, so a released build's gate is reproducible and a hub commit cannot retroactively fail a re-run.
• Diff-scoped, so only lines a change touches are reported. The repository's existing backlog blocks nothing and is corrected as each file is next edited.

Checkout gains fetch-depth: 0 in the lint job, since diffing against the base needs that branch present.

Pre-flight

The action's logic was simulated end to end against this branch before pushing: the raw fetch of hub develop returns 200, the fetched checker accepts --diff, and the gate exits 0 on the lines this change touches. Run against this repository's current develop and against #35's head, it also reports zero, so adopting it blocks neither.

The pin

Pinned to cbd5eb3c9e079b640d5461400d89b390de2f0780, the squash commit of ptr727/ProjectTemplate#520 on hub develop, so the action this consumes is on a permanent ref rather than on a feature branch that would go unreachable when deleted.

That commit carries no release tag, so Dependabot has nothing to compare it against and will not bump it. It gets repointed by hand at the next hub release, after which Dependabot tracks it like any other action pin. The workflow says so inline, rather than relying on this description staying current.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 44.96%. Comparing base (1ab0f11) to head (eedfdd2).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@ Coverage Diff @@## develop #36 +/- ##
========================================
Coverage 44.96% 44.96% ========================================
Files 25 25 Lines 3398 3398 Branches 259 259 ========================================
Hits 1528 1528 Misses 1824 1824 Partials 46 46 

☔ 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.

[Copilot]

Pull request overview

This PR updates the reusable validation workflow to consume the fleet “prose gate” as a composite action from the hub repo, so prose-rule violations are enforced in CI (diff-scoped) without vendoring the checker into this repository.

Changes:

• Fetch full git history in the lint job checkout to support diffing against a base.
• Add a new “Check prose” step that runs ptr727/ProjectTemplate/.github/actions/prose-gate and passes a base ref.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.github/workflows/validate-task.yml:105

• PR description says the prose-gate pin currently targets 4ad0156, but this workflow uses 4e21a27fff0e59bdb44a3bab94b077391c4c8ddd. Please confirm which SHA should be pinned and update either the workflow or the PR description so they match (important for reproducibility/auditability).

 - name: Check prose step
if: ${{ github.ref_name != 'main' }}
uses: ptr727/ProjectTemplate/.github/actions/prose-gate@4e21a27fff0e59bdb44a3bab94b077391c4c8ddd # conformance/prose-gate-carry
with:
base: origin/${{ github.ref_name == 'develop' && 'main' || 'develop' }}

.github/workflows/validate-task.yml:100

• These comments imply this workflow itself runs on push, but validate-task.yml is a reusable workflow_call. It’s invoked by a push-triggered workflow in this repo, so the intent is correct, but the wording is slightly misleading; tightening it avoids confusion for future callers that may invoke it via other events (e.g., workflow_dispatch).

 # The base is the branch this one merges into.
# The gate runs on push, so there is no pull_request event to read a base from.
# Runs on main are skipped, since it only receives promotion merges already gated on develop.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.github/workflows/validate-task.yml:108

• The PR description says the action pin targets 4ad0156, but the workflow currently pins 4e21a27…. If 4e21a27… is the intended pin, consider updating the inline comment to include the short SHA (and ensure the PR description is updated) to avoid confusion about which hub commit is being exercised.

 if: ${{ github.event_name == 'push' && github.ref_name != 'main' }}
uses: ptr727/ProjectTemplate/.github/actions/prose-gate@4e21a27fff0e59bdb44a3bab94b077391c4c8ddd # conformance/prose-gate-carry
with:

.github/workflows/validate-task.yml:96

• The comment block says a main run uses the bundled copy at the pin, but this step is explicitly skipped on main by the if: condition below. This is internally inconsistent and can mislead future edits/debugging of the workflow behavior.

This issue also appears on line 106 of the same file.

 # The fleet prose rules live in the hub, so this repo consumes them rather than vendoring them.
# Every branch but main reads hub develop, so a rule change is exercised before promotion.
# A main run uses the copy bundled at the pin, so a released build stays reproducible.
# Only lines a change touches are reported, so the existing backlog blocks nothing.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

.github/workflows/validate-task.yml:108

• The PR description says the action pin “currently targets 4ad0156”, but this workflow pins ptr727/ProjectTemplate/.github/actions/prose-gate to 4e21a27fff0e59bdb44a3bab94b077391c4c8ddd. This mismatch makes it unclear which hub commit/ref is intended for the live test and what needs to be repointed before merge.

 if: ${{ github.event_name == 'push' && github.ref_name != 'main' }}
uses: ptr727/ProjectTemplate/.github/actions/prose-gate@4e21a27fff0e59bdb44a3bab94b077391c4c8ddd # conformance/prose-gate-carry
with:

.github/workflows/validate-task.yml:104

• This comment block says “A main run uses the copy bundled at the pin”, but the step is explicitly skipped on main below. Consider updating the comments so they describe the actual behavior consistently (non-main only, main skipped).

 # Every branch but main reads hub develop, so a rule change is exercised before promotion.
# A main run uses the copy bundled at the pin, so a released build stays reproducible.
# Only lines a change touches are reported, so the existing backlog blocks nothing.
#
# The base is the branch this one merges into.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.github/workflows/validate-task.yml:96

• The inline comment says “A main run uses the copy bundled at the pin”, but this workflow explicitly skips main (if: ... && github.ref_name != 'main'). That makes the comment misleading for this repo; consider phrasing it as “the action’s design” (or dropping the main-run note) so future maintainers don’t assume validate-task enforces a prose gate on main.

 # The fleet prose rules live in the hub, so this repo consumes them rather than vendoring them.
# Every branch but main reads hub develop, so a rule change is exercised before promotion.
# A main run uses the copy bundled at the pin, so a released build stays reproducible.
# Only lines a change touches are reported, so the existing backlog blocks nothing.

.github/workflows/validate-task.yml:107

• PR description mentions the pin currently targeting a different hub commit; to avoid confusion during the planned repoint, consider making the intent explicit inline (temporary pin + follow-up repoint) rather than relying on the PR description staying in sync.

 uses: ptr727/ProjectTemplate/.github/actions/prose-gate@4e21a27fff0e59bdb44a3bab94b077391c4c8ddd # conformance/prose-gate-carry

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.github/workflows/validate-task.yml:63

• actions/checkout is now always doing a full clone (fetch-depth: 0) for the entire lint job, even on publish (workflow_dispatch/schedule) runs where the prose gate is intentionally skipped. That adds unnecessary network/time overhead to releases and other non-push runs.

Consider making fetch-depth conditional so only branch pushes that actually run the prose gate fetch full history; keep other runs shallow.

 - name: Checkout code step
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
with:
# The prose gate diffs against the base branch, so it needs that branch's history.
fetch-depth: 0

.github/workflows/validate-task.yml:111

• The PR description says the temporary pin targets 4ad0156, but the workflow currently pins the prose-gate action to 4e21a27…. This mismatch makes it harder to verify the intended hub commit/branch for the live test and for the later repointing step.

Please update the PR description (or the pin) so they refer to the same commit.

 # TEMPORARY PIN: this SHA is the head of the hub's conformance/prose-gate-carry branch and
# is not on hub main, so it carries no released version.
# Repoint it to a released hub commit once ptr727/ProjectTemplate#520 merges.
# Dependabot cannot bump a pin that resolves to no tag, so nothing will do this for us.
uses: ptr727/ProjectTemplate/.github/actions/prose-gate@4e21a27fff0e59bdb44a3bab94b077391c4c8ddd # conformance/prose-gate-carry
with:

[ptr727]

Suppressed findings answered

Ten collapsed findings across six rounds, most of them the same three points restated as the branch moved. Answering all of them, grouped by point rather than by round, with the rounds named so each can be traced back.

A. The pin contradicts the PR description - Fixed, description corrected

Raised five times: rounds on bd32f96, 55f86c2 twice, 55f86c2 again, and 00d63aa.

PR description says the prose-gate pin currently targets 4ad0156, but this workflow uses 4e21a27fff0e59bdb44a3bab94b077391c4c8ddd. Please confirm which SHA should be pinned and update either the workflow or the PR description so they match (important for reproducibility/auditability).

Correct, and correctly persistent: I repointed the pin twice without updating the description, so the mismatch survived four more rounds of it being raised. The description now names the current pin, 90d81f71d07c11ab24264e3cdff3e51e5cfafeb9, and the temporary-pin requirement is stated inline in the workflow as well, so the two cannot drift again once the PR body is out of view.

B. The comment described main-run behavior the workflow never reaches - Fixed in 00d63aa

Raised three times, most precisely on 55f86c2:

The inline comment says "A main run uses the copy bundled at the pin", but this workflow explicitly skips main (if: ... && github.ref_name != 'main'). That makes the comment misleading for this repo; consider phrasing it as "the action's design" (or dropping the main-run note) so future maintainers don't assume validate-task enforces a prose gate on main.

Correct and internally inconsistent as described. The main-run sentence is dropped, and the comment now describes only what this workflow does.

C. Make the temporary-pin intent explicit inline - Fixed in 00d63aa

From the same round:

PR description mentions the pin currently targeting a different hub commit; to avoid confusion during the planned repoint, consider making the intent explicit inline (temporary pin + follow-up repoint) rather than relying on the PR description staying in sync.

Taken as written, and the reasoning is exactly why point A kept recurring. The workflow now carries a TEMPORARY PIN note naming the branch, the repoint condition, and the fact that Dependabot cannot bump a pin resolving to no tag, so nothing automated will do it.

D. Full clone on runs that skip the gate - Fixed in cecd86c

New on 00d63aa:

actions/checkout is now always doing a full clone (fetch-depth: 0) for the entire lint job, even on publish (workflow_dispatch/schedule) runs where the prose gate is intentionally skipped. That adds unnecessary network/time overhead to releases and other non-push runs.

Correct, and a consequence of my own skip condition that I did not follow through. The fetch depth is now tied to the same expression the gate uses, so only runs that reach the gate pay for the history, and the two conditions cannot drift apart.

E. The comments imply this workflow itself triggers on push - Disproven in substance, wording tightened

From bd32f96:

These comments imply this workflow itself runs on push, but validate-task.yml is a reusable workflow_call. It's invoked by a push-triggered workflow in this repo, so the intent is correct, but the wording is slightly misleading.

The finding concedes the intent is correct, and the behavior it worries about is the one that matters: in a reusable workflow the github context is the caller's, so github.event_name is the caller's trigger rather than workflow_call. Proven on this PR's own run, where the step reports conclusion: success and prints Rules source: hub develop on the commit that introduced the event_name == 'push' condition. Had it evaluated to workflow_call the step would have been skipped. The comment block now says explicitly that a publish run reaches this workflow through build-release-task and is skipped, which is the caller-awareness the finding asked for.

---

10 of 10 suppressed findings across all six rounds are now answered.

Four of these rounds went unanswered until the maintainer pointed them out, because the digest that surfaces suppressed findings was scoped to the current head and dropped them whenever I pushed. That is fixed upstream in ptr727/ProjectTemplate#520, along with a rule requiring an answer to quote the finding and carry a verdict, so the count can be checked without opening each review.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.github/workflows/validate-task.yml:66

• The fetch-depth expression will never evaluate to 0 here. In GitHub Actions expressions, 0 is falsy, so (cond) && 0 || 1 becomes 0 || 1 when cond is true, yielding 1. That means the base branch history likely won’t be available when the prose gate runs.

 fetch-depth: ${{ (github.event_name == 'push' && github.ref_name != 'main') && 0 || 1 }}

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.github/workflows/validate-task.yml:66

• The && 0 || 1 pattern doesn’t work here because 0 is falsy in GitHub Actions expressions. When the condition is true, it evaluates to 0 || 1, which becomes 1, so the workflow will still do a shallow clone and the prose gate won’t have the base branch history it needs.

 fetch-depth: ${{ (github.event_name == 'push' && github.ref_name != 'main') && 0 || 1 }}

[ptr727]

Suppressed findings answered (round 7)

Two from the round on cecd86c, Suppressed comments (2), both making the same point. Correct, and a real bug I introduced in that very commit. Fixed in a43e135.

.github/workflows/validate-task.yml:66 - Fixed in a43e135

The fetch-depth expression will never evaluate to 0 here. In GitHub Actions expressions, 0 is falsy, so (cond) && 0 || 1 becomes 0 || 1 when cond is true, yielding 1. That means the base branch history likely won't be available when the prose gate runs.

Exactly right, and it inverted the fix it was part of. cecd86c made the fetch depth conditional to stop publish runs paying for a full clone, and wrote the ternary with a bare 0. Since 0 is falsy, the true branch collapses:

cond true -> (true && 0) || 1 -> 0 || 1 -> 1 # shallow, always
cond false -> (false && 0) || 1 -> false || 1 -> 1 # shallow, correctly

So every run shallow-cloned and the gate would have had no base branch to diff against. The depths are now quoted, '0' and '1', since a non-empty string is truthy, and the comment says they must stay quoted so nobody simplifies them back.

Worth noting what this would have looked like without the earlier fix on the hub side. Until ptr727/ProjectTemplate#520, an unresolvable base made the gate widen to a whole-tree scan, so this bug would have surfaced as several hundred findings against a two-line change. With that fixed it now fails naming the missing base instead, which is the difference between a confusing wall and a legible error.

---

12 of 12 suppressed findings across all seven rounds on this PR are now answered.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[ptr727]

Comment sentences spanning lines - found, and why the gate missed them

The maintainer spotted three comment sentences wrapped across lines in this PR's diff, on a branch I had reported as gate-clean. The gate was right and my verification was wrong. Fixed in 790c91c.

I ran the gate from the hub's directory with an absolute path to this checkout:

$ cd /home/pieter/ProjectTemplate
$ python3 scripts/prose_lint.py /path/to/PhotoCleaner/. --diff origin/develop
0 violation(s) across 0 file(s)
$ cd /path/to/PhotoCleaner
$ python3 /home/pieter/ProjectTemplate/scripts/prose_lint.py . --diff origin/develop
3 violation(s) across 1 file(s)
comment-wrap 3

--diff runs git diff in the current directory, so it resolved against the hub's changes while scanning this repository's files. The two sets never intersect, every finding is scoped away, and the run reports a clean pass. Same gate, same commit, same file: zero from one directory and three from the other.

The three were real, all in comments I wrote:

• validate-task.yml:63 "Only the runs that reach the gate pay for it, since a publish run skips the gate and / a full clone there is time and network a release does not need."
• validate-task.yml:68 "An unquoted 0 is falsy, so cond && 0 || 1 collapses to 1 whenever cond is true and / every run would shallow-clone..."
• validate-task.yml:113 "TEMPORARY PIN: this SHA is the head of the hub's conformance/prose-gate-carry branch and / is not on hub main..."

Each is now one sentence per line.

The misuse that produced the false clean is fixed upstream in 6819955: the gate compares the repository --diff resolves against with the one each path argument belongs to, and refuses the run when they differ rather than scoping every finding away. A case covers it.

That is the third false-clean class found on this PR, after the unresolvable diff base widening to a whole-tree scan and a multi-line paths input scanning only its first entry. All three shared a shape worth naming: the gate reported success while checking less than it appeared to.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.github/workflows/validate-task.yml:117

• The workflow comment claims this pin is "the hub's develop" and ties it to ProjectTemplate#520, but the PR description references a different SHA/branch state. To avoid stale or contradictory metadata, consider rewording the comment to describe this as a SHA pin (and whether it contains #520) without asserting it is exactly develop.

 # This SHA is the hub's develop, where ptr727/ProjectTemplate#520 landed.
# It carries no release tag yet, so Dependabot cannot compare it and will not bump it.
# Repoint it by hand at the next hub release.
# Dependabot tracks it like any other action pin from then on.
uses: ptr727/ProjectTemplate/.github/actions/prose-gate@cbd5eb3c9e079b640d5461400d89b390de2f0780 # hub develop

[ptr727]

Suppressed findings answered (round 12)

One from the round on e39f8a0, Suppressed comments (1). Correct on both halves, fixed in eedfdd2 and in this PR's description.

.github/workflows/validate-task.yml:117 - Fixed in eedfdd2

The workflow comment claims this pin is "the hub's develop" and ties it to ProjectTemplate#520, but the PR description references a different SHA/branch state. To avoid stale or contradictory metadata, consider rewording the comment to describe this as a SHA pin (and whether it contains #520) without asserting it is exactly develop.

Both halves correct, and they are different problems.

The contradiction was real and is the third time on these pull requests that a stale description outlived the change it described. I repointed the pin from the unmerged branch head to the merged commit and updated the inline comment, and left the description naming the old SHA. It now names cbd5eb3c9e079b640d5461400d89b390de2f0780 and explains the release-tag caveat, and the same information is inline in the workflow so the description is no longer the only place carrying it.

The wording point is the more durable half. "This SHA is the hub's develop" is a claim with a shelf life: it was true when pinned and stops being true at the hub's next merge, so a reader six commits later is told something false by a comment that never changed. A pin is a SHA, and what is worth recording is what it contains. The comment now says it is a SHA pin carrying the prose gate from #520, that it was hub develop when pinned, and that it says nothing about where develop is now.

---

13 of 13 suppressed findings across all twelve rounds on this PR are now answered.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.