Make the prose gate reach comments, and carry it to the fleet

[ptr727]

Comment shape is the most frequently regressed rule in agent-authored work, and this repo's answer to it was a rule with nothing running it. Two independent causes, both fixed here, plus the governance and host-setup items that came out of the same session.

Closes part of #519.

The gate did not check comments

comment-wrap and comment-case sat outside DEFAULT_RULES, so prose_lint.py . never checked them. That is why #519's whole-tree figure splits cleanly into dash and semicolon with no comment findings, and why the rule read as enforced while nothing ran it. Enabling them exposes 424 findings the tree already carried, worst in spec/audit.py (103) and host-setup/agent-safety/gh-write-guard.py (56).

A test now asserts a bare run catches a wrapped comment, so the rule cannot go quiet again.

The gate did not reach downstream repos

It is hub-only by design, so no fleet repo runs it. .github/actions/prose-gate lets a repo consume the rules from here instead of vendoring a 934-line script into twenty copies, which is possible only because this repo is now public: a public repository's composite actions are consumable by any repository, with no organization account required.

The ref design, which is the part worth reviewing:

• The uses: pin is one literal, identical on both branches. uses: accepts no expressions, so a per-branch ref would be a permanent divergence that every develop -> main promotion has to preserve, fighting the branching model.
• Branch-dependent behavior lives inside the action, where expressions are legal. A develop-targeted run reads the rules from hub develop, so an unpromoted rule change is exercised fleet-wide before it reaches main. Every other run uses the copy bundled at the pinned SHA, so a released repo's gate is reproducible and a hub commit cannot retroactively fail a re-run.
• This satisfies GOVERNANCE.md "Action pinning" as written, since the downstream uses: is SHA-pinned. Dependabot bumps it like any other action pin, because the hub publishes real releases (latest 2.0.200) and the github-actions ecosystem resolves any GitHub-hosted action by owner/repo rather than through the marketplace.

Accepted trade: a hub develop commit can redden downstream develop CI fleet-wide. That is what the staging tier is for, and diff-scoping means only lines a change touches can fail.

Two exemptions, both because a finding named no possible edit

• Generated trees are skipped when a wide scan expands into them, currently reports/. spec/audit.py writes it, so a finding there is the engine's phrasing rather than an author's. This answers prose_lint: the hub's own docs, spec, and catalog do not pass the gate it ships #519's first question, and it is why the hub's own number was 549 generated to 119 authored. Naming the path directly still reads it, so nothing becomes uncheckable.
• An unpunctuated markdown HTML comment is a structural marker, not commentary. The reference-link group headers, the ToC-omit directive, and the agent-safety install markers are each matched verbatim by a tool, so capitalizing one or splitting an adjacent pair breaks what reads it. A markdown comment that does punctuate a sentence stays judged as prose, and the existing test asserting that still passes. This follows the precedent the URI exemption already set.

Governance and host-setup

• "Commit" means commit and push. Nothing reviews a local commit: the Copilot loop, the required checks, and the maintainer all read the remote, so stopping at git commit reads as progress while no gate has run.
• A Copilot decline carries proof, not a rationale. The command and its output, the code path that makes the concern impossible, or the rule that governs it. Disagreeing without evidence is not addressing a finding, so a thread is not resolved on one.
• A low-confidence finding is not a low-value one. Copilot collapses the findings it is least sure of into the review body, where they reach no thread, and they are right the large majority of the time.
• The authorization-scope backstop moved into the committed canonical. It was hand-written into one host's CLAUDE.md, which is the exact defect it describes: a rule that exists only where the history happens to be. install.py now syncs it, so it reaches a new machine. Three pre-existing spaced hyphens in that file are fixed in passing, matching the phrasing GOVERNANCE.md already uses.

Still outstanding on this branch

The catalog/snippets/** cleanup (#519's second question) is not in this commit. It is 184 findings across 17 files and lands as follow-up commits here rather than a separate PR. It is the highest-priority content fix, because a downstream repo copying build-release-task.yml inherits its 37 comment violations and is then flagged for lines it did not write.

Verification

test_prose_lint.py 148 tests, test_repo_gate.py 23, test_pr_review.py 27, spec/audit.py --selftest, scripts/repo_gate.py, spec/validate.py, and markdownlint all pass. prose_lint.py . --diff origin/develop reports zero on every line this change touches.

[Copilot]

Pull request overview

This PR tightens the fleet prose gate by ensuring comment-shape rules are enforced by default, adds targeted carve-outs for generated output and structural markdown markers, and introduces a reusable composite action so downstream repos can consume the gate logic from this hub repo.

Changes:

• Include comment-wrap and comment-case in DEFAULT_RULES, with tests preventing regressions.
• Skip generated reports/ content during wide scans (while still allowing direct scans of that tree), and treat unpunctuated markdown HTML comments as structural markers.
• Add a composite action (.github/actions/prose-gate) to run the diff-scoped gate using either bundled rules (pinned) or hub develop rules for develop-targeted runs.

Reviewed changes

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

Show a summary per file

File	Description
TODO.md	Adds a backlog item about cross-repo workflow reuse and link refs needed by that addition.
scripts/test_prose_lint.py	Adds regression tests for default comment-shape coverage, generated-tree skipping behavior, and markdown-marker handling.
scripts/README.md	Documents the updated default rules, generated-tree behavior, and markdown marker carve-out.
scripts/prose_lint.py	Enables comment-shape rules by default; implements generated-tree skipping and markdown-marker carve-out logic.
host-setup/agent-safety/claude-md-safety.md	Moves the authorization-scope backstop into the committed host-safety doc and fixes formatting.
GOVERNANCE.md	Clarifies “commit” includes pushing, and strengthens the evidence requirement when declining review findings.
.github/actions/prose-gate/action.yml	New composite action to run the prose gate downstream with pinned or develop-sourced rules.

[Copilot]

Pull request overview

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

Suppressed comments (2)

.github/actions/prose-gate/action.yml:72

• read -ra scan <<<"$PATHS" only reads up to the first newline, so a downstream workflow that provides paths as a multi-line YAML string (common for readability) will silently ignore everything after the first line. Since the intent is to split on whitespace, normalize newlines before read so all paths are honored.

        set -Eeuo pipefail
        # Split on whitespace into an array, so several paths stay several arguments.
        # Passing the array quoted keeps each element literal.
        # An unquoted expansion would instead glob, and a path holding `*` would scan the match.
        read -ra scan <<<"$PATHS"
        python3 "$SCRIPT" "${scan[@]}" --diff "$BASE"

.github/actions/prose-gate/action.yml:55

• The curl fetch of prose_lint.py has no retry/backoff, so transient network failures can fail the gate even when the ref/script is correct. Adding a small retry policy makes CI more reliable without changing the trust model (a non-200 still fails due to -f).

          dst="$RUNNER_TEMP/prose_lint.py"
          url="https://raw.githubusercontent.com/ptr727/ProjectTemplate/$ref/scripts/prose_lint.py"
          # Fail loudly rather than skipping the gate, since a silent skip reports a clean pass.
          curl -fsSL "$url" -o "$dst"
          echo "script=$dst" >>"$GITHUB_OUTPUT"

[Copilot]

Pull request overview

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

Suppressed comments (1)

scripts/prose_lint.py:146

• discover() is intended to be scoped by the user-provided paths, but the git-backed branch currently calls tracked_paths(root) without applying any pathspec/prefix filtering. Since tracked_paths() runs git ls-files with no pathspec, passing a directory like docs/ will still include the entire repo (and depending on tracked_paths() path joining semantics, may also produce incorrect paths when root != '.'). Consider always listing from the repo root and then filtering by the requested root prefix so paths reliably scopes the scan.

        root = p if p.is_dir() else Path('.')
        tracked = tracked_paths(root)
        if tracked is None:
            print(f'warning: git cannot describe {root}, falling back to a filesystem walk',
                  file=sys.stderr)

[ptr727]

Answering the suppressed finding from the review on 4e21a27, since a suppressed comment reaches no thread and the merge gate counts it as outstanding either way.

scripts/prose_lint.py:146 - discover() does not scope by paths. Disproven. The premise is that tracked_paths() runs git ls-files with no pathspec, and it does not: it runs git -C <root> ls-files -z, and -C is the scoping mechanism, changing the command's working directory so git ls-files lists only that subtree.

$ git -C docs ls-files | wc -l
6
$ git ls-files | wc -l
113

Scoping through the full discover() path, including the nested case:

$ python3 scripts/prose_lint.py docs --list-files | wc -l
6
$ python3 scripts/prose_lint.py docs --list-files | grep -vc '^docs/'
0
$ python3 scripts/prose_lint.py catalog/snippets/workflows --list-files | wc -l
13
$ python3 scripts/prose_lint.py catalog/snippets/workflows --list-files | grep -vc '^catalog/snippets/workflows/'
0

The second half of the concern, that paths may be reconstructed incorrectly when root != '.', is disproven by the same output. return [root / name ...] rejoins each name to the root, so the emitted paths are docs/content-import.md rather than a bare content-import.md, which is also what makes the --diff path match them against git diff output. An absolute root works too, emitting absolute paths.

Worth noting the alternative it proposes, listing from the repo root and filtering by prefix, would be a behavior change rather than a fix: git -C resolves the root through git's own discovery, so it works from a subdirectory of the repo and against a path outside the current one, where a root-relative prefix filter would not.

No code change. The scoping the finding asks for is what the code already does.

[ptr727]

Suppressed findings answered

Answering the collapsed findings from review 4839451158 on 4ad0156, Suppressed comments (2). Both correct, both fixed in 90d81f7. A suppressed finding has no thread, so each is quoted here to pair the answer to it.

1. .github/actions/prose-gate/action.yml:72 - Fixed in 90d81f7

read -ra scan <<<"$PATHS" only reads up to the first newline, so a downstream workflow that provides paths as a multi-line YAML string (common for readability) will silently ignore everything after the first line.

Correct, and worse than it reads: a silent under-scan is the one failure a gate must never have, because it reports the unscanned paths as clean. Reproduced:

$ PATHS=$'.\ndocs\nscripts'
$ read -ra scan <<<"$PATHS"; echo "${scan[*]} (${#scan[@]})"
. (1)

Newlines are now folded before splitting, and the step prints what it scanned so an under-scan is visible in the log rather than silent:

$ read -ra scan <<<"$(printf '%s' "$PATHS" | tr '\n' ' ')"; echo "${scan[*]} (${#scan[@]})"
. docs scripts (3)

An empty result after parsing now fails the step rather than scanning nothing.

2. .github/actions/prose-gate/action.yml:55 - Fixed in 90d81f7

The curl fetch of prose_lint.py has no retry/backoff, so transient network failures can fail the gate even when the ref/script is correct. Adding a small retry policy makes CI more reliable without changing the trust model (a non-200 still fails due to -f).

Agreed, including the reasoning about the trust model. Now curl -fsSL --retry 3 --retry-delay 2 --retry-all-errors, so -f still fails the step on a non-200 and only the transient case is retried.

---

Previously answered from review 4839478321 on 4e21a27, Suppressed comments (1): the discover() scoping claim, Disproven, with evidence in this comment. That reply predates this convention and paraphrases the finding rather than quoting it, which is the gap this convention closes.

3 of 3 suppressed findings on this PR are now answered.

[Copilot]

Pull request overview

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

Suppressed comments (2)

scripts/prose_lint.py:929

• main() now returns exit code 2 when --diff cannot be resolved, but the module header still states “Exit 1 if any violation is found”, and callers may be relying on the documented 0/1 contract. Please update the top-level documentation (and any call-site docs) to mention the new non-findings error exit code.

    scope = changed_lines(a.diff) if a.diff else None
    if a.diff and scope is None:
        # Widening to the whole tree answers a different question, and answers it silently.
        # A caller scoping to a change gets the backlog reported as though the change made it.
        # A CI adoption hits this first, where an unresolvable base walls off the first run.

scripts/pr_review.py:126

• digest() now counts suppressed findings across all Copilot review rounds, not just the current head. scripts/README.md still says the digest “covers the reviews on the current head only”, which is now incorrect and may mislead users interpreting suppressed= / earlier= output.

    # Every round, not just the head, because a suppressed finding has no resolved state to read.
    # Head-scoping treated "superseded by a push" as "answered", and the two are not the same.
    # A finding nobody replied to left the digest the moment the branch moved, reporting zero.
    # That is how four rounds went unanswered across three pull requests in one day.
    # The head is still marked per block, since a finding on an older round may be moot.

[Copilot]

Pull request overview

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

Suppressed comments (1)

.github/actions/prose-gate/action.yml:21

• rules-ref input description doesn’t match the implemented selection logic. The step selects develop for any run where TARGET != "main" (including feature branches and push runs), not only “a develop-targeted run”. This can mislead downstream consumers about when the floating develop ref is used.

  rules-ref:
    description: >-
      Hub ref supplying the rules.
      Empty selects develop for a develop-targeted run and the pinned action version otherwise.
    required: false

[Copilot]

Pull request overview

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

Suppressed comments (3)

scripts/prose_lint.py:177

• explicit.add(q) is a leftover after the generated-tree filtering change, but explicit is never read. Dropping this write avoids implying there’s special handling for “explicit” discovered files.

                found.append(q)
            elif not GENERATED_TREES.isdisjoint(Path(prefix).parts):
                # The root named is itself inside a generated tree, so it was asked for.
                found.append(q)
                explicit.add(q)

.github/actions/prose-gate/action.yml:94

• The paths input is parsed into an argv array, but it’s still passed before --diff with no -- sentinel. If a workflow accidentally includes a token that starts with - (e.g. --list-files), argparse will treat it as an option and the scan can be unintentionally altered or short-circuited. Pass options first and include -- so every token is treated as a literal path.

        echo "Scanning ${#scan[@]} path(s): ${scan[*]}"
        python3 "$SCRIPT" "${scan[@]}" --diff "$BASE"

scripts/prose_lint.py:156

• explicit is created and populated but never read. This adds dead state to the discovery logic and makes it harder to tell what inputs are actually treated as “explicit”. Remove the unused set and its first write (the direct-file case) to keep discover() minimal.

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

    found: list[Path] = []
    explicit: set[Path] = set()
    for raw in paths:
        p = Path(raw)
        if p.is_file():

[Copilot]

Pull request overview

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

Suppressed comments (2)

scripts/prose_lint.py:36

• DEFAULT_RULES now includes comment-wrap/comment-case, but OPERATIONS.md still states that a bare python3 scripts/prose_lint.py … run omits those checks (OPERATIONS.md:9). That runbook will mislead readers about what a default run covers and when comment-shape findings should appear.

DEFAULT_RULES = frozenset({'charset', 'charset-unknown', 'semicolon', 'dash', 'dupword',
                           'spelling', 'comment-wrap', 'comment-case'})

scripts/pr_review.py:160

• If a review node has a null/empty commit.oid (which the code already handles elsewhere), the digest currently prints raised on , earlier round, which is hard to interpret. Use an explicit placeholder like unknown so the SUPPRESSED marker stays readable when the SHA is missing.

        sha = ((n.get('commit') or {}).get('oid') or '')[:8]
        where = 'on head' if sha == head[:8] else f'raised on {sha}, earlier round'
        lines.append(f'  SUPPRESSED ({where}): no thread to resolve, '
                     'answer it in the PR conversation quoting the finding')

[ptr727]

Suppressed findings answered

One from review 4839761898 on 87052e8, Suppressed comments (1). Correct, fixed in 27cb352.

scripts/pr_review.py:160 - Fixed in 27cb352

When a suppressed-finding block comes from a review node that lacks a commit OID (e.g., a pending/partial review), sha becomes empty and the output renders as SUPPRESSED (raised on , earlier round), which is confusing and makes it harder to trace what round raised the finding. Consider emitting an explicit "unknown commit" marker when the commit OID is missing.

Correct, and reproduced against a payload with 'commit': None:

SUPPRESSED (raised on , earlier round): no thread to resolve, ...

The finding is sharper than a formatting nit. The sha is the only thing tracing a suppressed finding back to the round that raised it, since there is no thread to open, so an empty one reads as a rendering glitch rather than as something still needing an answer. That is the same shape as the defect this whole change set exists to fix, a finding present but not legibly present.

It also has precedent in the file: live_state already guards a null commit, with a case named test_a_null_author_or_commit_does_not_raise explaining that GraphQL returns null for a deleted account and that a crash there stalls the wait. I added a second reader of the same field without carrying that guard across.

Now commit unknown, treat as outstanding, and the block still counts toward suppressed=N, since an unknown round is not a reason to drop a finding. A case covers both the marker and the count.

---

9 of 9 suppressed findings on this PR are now answered.

[Copilot]

Pull request overview

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

Suppressed comments (1)

scripts/prose_lint.py:970

• In --diff mode, the repository-mismatch guard runs after discover() has already enumerated files. On large trees this makes an invocation that will immediately error still pay the full discovery cost even though the result is discarded. Consider running the repo_root mismatch check before discover() (optionally keeping the current --list-files bypass) so the failure is fast and side-effect free.

    rules = set(a.checks or DEFAULT_RULES)
    files = discover(a.paths or ['.'], tuple(a.exclude))

    if a.list_files:
        for f in files:
            print(rel(f))
        return 0

    if a.diff:
        # `git diff` runs in the current directory while the paths may name another checkout.
        # Scanning one repository and diffing another intersects to nothing.
        # The run then reports clean, which is the false clean this gate exists to prevent.
        # It cost a real verification once, where a branch read zero from the wrong directory.
        here = repo_root(Path('.'))
        for raw in (a.paths or ['.']):
            there = repo_root(Path(raw))
            if here and there and here != there:
                print(f'error: --diff resolves against {here}, but {raw} is in {there}. '
                      'Run the gate from the repository being scanned, since a diff taken '
                      'elsewhere scopes every finding away and reports a false clean.',
                      file=sys.stderr)
                return 2

[ptr727]

Suppressed findings answered

One from review 4839783461 on 27cb352, Suppressed comments (1). Correct, fixed in 36e140c.

scripts/prose_lint.py:970 - Fixed in 36e140c

In --diff mode, the repository-mismatch guard runs after discover() has already enumerated files. On large trees this makes an invocation that will immediately error still pay the full discovery cost even though the result is discarded. Consider running the repo_root mismatch check before discover() (optionally keeping the current --list-files bypass) so the failure is fast and side-effect free.

Correct. The guard consumes nothing from discover(), so its position was accidental rather than chosen, and discovery is not cheap: it runs git ls-files and then reads the first block of every tracked file to classify it as text. A rejected run paid all of that and discarded it.

The parenthetical is the part worth crediting. --list-files should keep the bypass, and for a reason rather than for compatibility: it reports the scan scope and never reaches changed_lines, so a diff taken elsewhere cannot mislead it. Listing files across repositories is a legitimate thing to ask for, and the guard exists to stop a false clean, which listing cannot produce. The check is now if a.diff and not a.list_files.

Verified the reorder changed only the cost and not the behavior: the real misuse still errors with the same message, an ordinary run still reports normally, and a new case asserts discover is never called on the rejected path (disc.assert_not_called()) with a second case covering the --list-files bypass across repositories.

---

10 of 10 suppressed findings on this PR are now answered.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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