docs(claude-lanes): narrow the queue/cancel-in-progress claim to its true form

[kyle-sexton]

Summary

components/claude-lanes/claude-review.yml justified its job-level queue block
with a key-level claim:

queue: cannot share a concurrency block with cancel-in-progress

GitHub's prohibition is value-level, not key-level. Verbatim, from the
reusable that renders into both #concurrency and #jobsjob_idconcurrency:

The combination of queue: max and cancel-in-progress: true is not allowed
and will result in a workflow validation error.

Same file, restated in the example prose:

Note that queue: max cannot be combined with cancel-in-progress: true,
because the two options describe conflicting behaviors for handling
in-progress runs.

• Source pinned at the commit read: github/docs@336b7f5
data/reusables/actions/actions-group-concurrency.md
  (lines 20 and 126).
• Rendered page carrying the same sentence, confirmed by fetch:
  https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#concurrency

queue: max + cancel-in-progress: false is legal and runs — the key-level
wording forbids a shape GitHub permits.

The correction narrows the claim to the documented pair and adds the second,
independent reason the two blocks stay separate: this group is job-scoped and
repo-wide, not per-PR. Without that clause a reader who sets
cancel-in-progress: false could conclude the blocks may now be merged, which
would silently collapse the per-PR supersede group into the repo-wide queue.

The authoritative URL is cited inline, in the tracked bytes (565559a,
added after review). Because this component is materialized verbatim
downstream, a citation living only in a commit message never reaches the
maintainers who read the claim — a correct-but-uncited assertion would repeat
this PR's own failure mode at lower severity. The link sits at the sentence that
defers to it per conventions/engineering/documentation-and-citations.md, and
it is a living URL rather than a pinned snapshot because the same convention
prefers fetching at read time over storing a snapshot with no recheck trigger.
The job-level anchor (#jobsjob_idconcurrency) is cited rather than the
workflow-level one because the comment annotates a jobs.<id>.concurrency
block; both anchors were confirmed live to exist on the rendered page and to
carry the rule sentence.

Why this races the open sync PRs

This component is sync-managed: its bytes are copied verbatim into every
consumer's .github/workflows/claude-review.yml. The wording has not landed
anywhere yet, and four open sync PRs are carrying it right now.

Regenerated from commands, not recalled:

$ grep -n '^targets:' distribution/sync-manifest.yml
216:targets:
$ awk 'NR>=216' distribution/sync-manifest.yml | grep -c '^      - claude-review-caller$'
5

Managed targets: claude-code-plugins, dotfiles, github-iac, medley,
provisioning.

Each consumer's live default-branch file was fetched and counted — the file was
read, not grepped on a ref for text expected to be there:

Repo	queue: max on default branch	old wording on default branch	open sync PR head carries old wording
claude-code-plugins	0	0	no open sync PR
dotfiles	0	0	#361 (df035f9) — yes
github-iac	0	0	#244 (0b8124d) — yes
medley	0	0	#1676 (d107862) — yes
provisioning	0	0	#231 (7b9d016) — yes

Landing this before those PRs merge means the correct text reaches every
consumer on first contact. Landing it after means a false statement propagates
fleet-wide and needs a second sync to retract.

Hold on the four sync PRs until this merges. The rollout-window gate is
intact — grep -c '^ automerge: false$' distribution/sync-manifest.yml
returns 8 against 8 total targets — and each of the four PRs was queried
live (gh pr view --json autoMergeRequest): none is armed. So nothing
merges them without a human, and a human merging any of them before #294 lands
is the only thing that defeats this PR.

Merging #294 does not require closing them. Verified in the engine at the
SHA this repository pins (ci-workflows@ac223bb,
.github/workflows/standards-sync.yml:454-461): it uses
peter-evans/create-pull-request against a fixed branch: chore/standards-sync,
which is the head branch on all four PRs — so a subsequent real run refreshes
each existing PR in place rather than opening a new one, which is also why the
engine guards auto-merge arming on pull-request-operation == 'created'.
sync.yml runs on push: branches: [main], so merging this PR is itself the
refresh trigger.

Sibling component: checked, no change

components/claude-lanes/claude-security-review.yml was read in full, not
assumed to match. It makes no key-level claim. Its one queue-adjacent
statement — "a full queue CANCELS new arrivals" — is accurate:

max: Up to 100 jobs or workflow runs can be pending in the concurrency
group. When the queue is full, any additional jobs or workflow runs are
canceled.

A repo-wide grep confirms the defect had exactly one site:

$ grep -rn 'share a concurrency block\|cannot share' . | grep -v '^\./\.git/'
./components/claude-lanes/claude-review.yml:87: ...

This repository's own .github/workflows/claude-review.yml sets no caller-level
concurrency and no queue:, so it never carried the claim.

Deliberate non-change

Independent verification surfaced a separate omission, not a falsehood: the
comment does not mention that queue: max caps at 100 pending and cancels
arrivals beyond that. Left out on purpose — this PR narrows a false claim and
should stay a one-hunk diff while it races the sync PRs.

The overflow-wedge argument that makes the cap load-bearing in the security
lane does not transfer here, and that was checked rather than assumed: every
ruleset on all five managed targets was enumerated and its
required_status_checks contexts read, and no target requires any
claude-named context today.

$ # per target: enumerate rulesets, union their required contexts, count claude ones
claude-code-plugins: total_required=4 claude_required=0
dotfiles:            total_required=3 claude_required=0
github-iac:          total_required=3 claude_required=0
medley:              total_required=3 claude_required=0
provisioning:        total_required=3 claude_required=0

So overflow cancellation on this lane cannot void a required check — the same
premise that already makes this lane's deliberate cancel-in-progress: true
safe. If a consumer later promotes the code-review context to required, the
cap becomes load-bearing and the comment should gain it. Worth a follow-up on
its own merits, not a blocker for this one.

Test plan

• components/claude-lanes/claude-lanes.test.sh, counted from the run rather
  than eyeballed, and reproduced by two independent runs:

  $ bash components/claude-lanes/claude-lanes.test.sh > run.txt 2>&1; echo "exit=$?"
  exit=0
  $ grep -cE '^PASS' run.txt; grep -cE '^FAIL' run.txt
  30
  0

  That includes [29] a synced lane caller fails actionlint without the suppression and [30] control run reports the suppressed message. Note for
  anyone re-running: the harness materializes from the git index, so the
  change must be staged or every target reports source worktree bytes differ from the indexed object and the suite fails for that reason alone.

• Comment-only change: no YAML key, value, group expression, or pin is touched.
  Confirmed by git diff --stat origin/main...HEAD — 6 insertions, 3 deletions,
  every line inside a # comment block.

• Independent verification by a fresh-context agent with the rationale withheld
  (given the final file text and asked whether every claim is true, and whether
  the constraint is stated at the correct level of generality). Verdict on the
  corrected wording: ACCURATE — "The comment restates the constraint at
  precisely the docs' generality — the docs name the literal queue: max +
  cancel-in-progress: true pair and nothing wider. Neither broader nor
  narrower. I would not reword this clause." It also independently confirmed
  queue: is valid at job level, via
  data/reusables/actions/jobs/section-using-concurrency-jobs.md including the
  same reusable.

• Repository CI on this PR: every check in the pass bucket, zero non-pass,
  verified by gh pr checks 294 --json name,bucket on each pushed head
  (a2a8228 and 565559a). That includes the Claude review lane
  (review / review) — run once per head, never re-run to chase green.

Related

• feat(distribution): add sync-managed claude review-lane caller components #286 — the PR that introduced these caller components and the wording
  corrected here.
• Open sync PRs carrying the pre-correction text: melodic-software/dotfiles#361,
  melodic-software/provisioning#231, melodic-software/github-iac#244,
  melodic-software/medley#1676.
• Two sibling sites for the same claim live in ci-workflows and are tracked
  there (ci-workflows#296 for the workflow; ci-workflows#302, merged, for
  PLAN.md). Deliberately untouched by this PR.

No linked issue.

[claude]

Claude finished @kyle-sexton's task in 1m 16s —— View job

---

Review: docs(claude-lanes): narrow the queue/cancel-in-progress claim to its true form

• Gather context and understand the request
• Read REVIEW.md for review criteria
• Read the changed file and PR diff
• Verify factual accuracy of the corrected claims
• Post review findings

---

Verdict: LGTM — no issues found.

What the diff does

The comment at claude-review.yml lines 86–91 previously said:

queue: cannot share a concurrency block with cancel-in-progress

That is a key-level prohibition — any queue: key with any cancel-in-progress: key is claimed invalid. The corrected text reads:

queue: max cannot be combined with cancel-in-progress: true, the value that block sets — and because this group is job-scoped and repo-wide, not per-PR.

This is value-level, matching the GitHub docs citation in the PR body verbatim.

Claim verification

1. The documented GitHub constraint is queue: max + cancel-in-progress: true specifically. The correction restates it at exactly that level of generality — neither broader nor narrower. The form queue: max + cancel-in-progress: false is legal, which the old wording incorrectly prohibited.

2. "the value that block sets" — the workflow-level concurrency block (line 50) does set cancel-in-progress: true. The back-reference is accurate.

3. "this group is job-scoped and repo-wide, not per-PR" — the job-level group expression is claude-review-${{ github.repository }} (line 93); the workflow-level group expression uses github.event.pull_request.number (line 49). The scope difference is real and independently sufficient to justify separate blocks.

4. "and because" — the two reasons are listed with and because, signaling they are both independently true and independently motivating. That is logically correct: even if GitHub permitted queue: max alongside cancel-in-progress: true, the scope difference would still require separate blocks.

REVIEW.md criteria

This is a comment-only change (+5/-3, no YAML key, value, or group expression touched). The two always-check criteria in REVIEW.md (audit-log on high-risk security actions; atomicity spanning related writes) have no surface here. No correctness, design, or convention findings.

Minor observation (non-blocking)

The PR body notes a deliberate non-change: the queue: max 100-job cap and its cancellation behavior are not documented in this comment. That omission is correctly scoped out — the overflow-wedge argument that makes it load-bearing in the security lane does not transfer here, and widening the diff while it races the sync PRs would be counterproductive. Nothing to act on.

---

The correction is precise, the reasoning is sound, and the test plan confirms 30/30 passing. Ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a2a8228e0d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 32s —— View job

---

Claude finished reviewing the updated PR ——

---

Review: follow-up commit 565559a — cite the queue rule inline

• Read REVIEW.md for review criteria
• Read the changed file and review the latest commit
• Verify the added citation travels correctly with the bytes
• Post review findings

---

Verdict: LGTM — no issues found.

What the follow-up commit does

565559a responds to the Codex finding that the queue: max / cancel-in-progress: true compatibility claim was asserted without a primary-source link in the tracked bytes. The fix inserts the GitHub docs URL as an inline parenthetical at claude-review.yml line 89:

    # `cancel-in-progress: true`, the value that block sets
    # (https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idconcurrency)
    # — and because this group is job-scoped and repo-wide, not per-PR.

Claim and citation verification

1. Anchor choice — #jobsjob_idconcurrency is the job-level concurrency section, which is the right anchor: the comment annotates a jobs.<id>.concurrency block (line 93), not the workflow-level block. The commit message notes both anchors (#concurrency and #jobsjob_idconcurrency) were independently confirmed to resolve and carry the rule sentence.

2. Placement — conventions/engineering/documentation-and-citations.md requires: "Place an upstream link at the sentence that actually defers to it." The URL is parenthetical immediately after "the value that block sets" — the exact clause that defers to the GitHub constraint. Placement is compliant.

3. Travels with the bytes — because this component is materialized verbatim into consumer workflows, a citation that lived only in the commit message would be invisible to downstream maintainers. The inline placement ensures the source is readable wherever the file lands.

4. Prose integrity — the sentence still reads naturally with the parenthetical and the em-dash continuation: "…the value that block sets (URL) — and because this group is job-scoped and repo-wide…"

REVIEW.md always-check criteria

• Audit-log: no high-risk security action — comment-only change, not applicable.
• Atomicity: single hunk, no multi-location write — not applicable.

No findings.