heavy-duty/ceremony

Fork 2

docs: add actions read to private caller guidance #174

Merged

codex-bot-andresmgsl merged 1 commit from build/173-private-read-scopes into main

2026-07-24 23:35:47 +00:00

codex-bot-andresmgsl commented

2026-07-24 22:57:39 +00:00

(Migrated from github.com)

Closes #173

Summary

Document the complete private-repository permission set for labels reconciliation and keep the blind-sweep warning aligned with the proven actions: read requirement.

Worklog

Pin the new three-scope warning bytes and demonstrate failure against the old implementation
Update both blind-sweep warning variants with the specified candidate tail
Add actions: read and its private-repository rationale to the consumer caller example
Update the following prose from both reads to all three reads
Add the flat, bounded changelog fragment
Run the full test suite
Run ShellCheck and actionlint
Confirm CI is green
Mark ready and request the full review bench

Acceptance criteria

Both warning lines carry the specified three-scope candidate tail without diagnosis language
test/labels-reconcile.test.sh passes with the updated expectation and fails against the old hint text
docs/CONSUMERS.md carries actions: read with the why-comment and retains the empty-state:* symptom
ShellCheck and actionlint are green locally and in CI
changelog.d/173.md exists in flat form with entries at most 300 characters

Testing

Red proof: updated expectation against the old implementation failed 149 passed / 1 failed on the exact warning bytes
Green proof: bash test/labels-reconcile.test.sh — 150 passed / 0 failed
bash test/run.sh — 18 test files passed / 0 failed
bash .github/scripts/shellcheck-all.sh — pass (39 scripts)
bash .github/scripts/actionlint-all.sh — pass (6 workflows)
GitHub Actions — all applicable checks pass

Closes #173 ## Summary Document the complete private-repository permission set for labels reconciliation and keep the blind-sweep warning aligned with the proven `actions: read` requirement. ## Worklog - [x] Pin the new three-scope warning bytes and demonstrate failure against the old implementation - [x] Update both blind-sweep warning variants with the specified candidate tail - [x] Add `actions: read` and its private-repository rationale to the consumer caller example - [x] Update the following prose from both reads to all three reads - [x] Add the flat, bounded changelog fragment - [x] Run the full test suite - [x] Run ShellCheck and actionlint - [x] Confirm CI is green - [x] Mark ready and request the full review bench ## Acceptance criteria - [x] Both warning lines carry the specified three-scope candidate tail without diagnosis language - [x] `test/labels-reconcile.test.sh` passes with the updated expectation and fails against the old hint text - [x] `docs/CONSUMERS.md` carries `actions: read` with the why-comment and retains the empty-`state:*` symptom - [x] ShellCheck and actionlint are green locally and in CI - [x] `changelog.d/173.md` exists in flat form with entries at most 300 characters ## Testing - Red proof: updated expectation against the old implementation failed 149 passed / 1 failed on the exact warning bytes - Green proof: `bash test/labels-reconcile.test.sh` — 150 passed / 0 failed - `bash test/run.sh` — 18 test files passed / 0 failed - `bash .github/scripts/shellcheck-all.sh` — pass (39 scripts) - `bash .github/scripts/actionlint-all.sh` — pass (6 workflows) - GitHub Actions — all applicable checks pass

danmt (Migrated from github.com) reviewed 2026-07-24 22:57:39 +00:00

grok-bot-andresmgsl commented

2026-07-24 23:00:50 +00:00

(Migrated from github.com)

🔎 reviewing head eae000bd62

🔎 reviewing head eae000bd624df8318a46b91a624634ba5166af84

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 23:01:51 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: approve

Head: eae000bd624df8318a46b91a624634ba5166af84
Issue: Closes #173

Acceptance criteria

Criterion	Result
Both `blind_sweep_warning` emit lines carry the three-scope candidate tail verbatim (`checks: read, statuses: read and actions: read…`), still framed as "one candidate", no diagnosis language	met — L73 and L75 match the issue's tail bytes exactly; lead still "sampled reason" / "no reason was captured"
`test/labels-reconcile.test.sh` pins the new bytes and the suite is green	met — 150/0 locally; full-line expectation covers both the new scopes and #101 D5
`docs/CONSUMERS.md` example gains `actions: read` with the incubator#60 why-comment; prose is "all three explicit reads"; empty-`state:*` symptom retained	met
shellcheck / actionlint	met — CI `self-guards` green; local shellcheck on the script is clean of new findings (only pre-existing SC1091 on the `ruling.sh` source)
`changelog.d/173.md` flat, entry ≤300 chars	met — one flat bullet, 131 characters

Verification run

Detached worktree at the head SHA.
bash test/labels-reconcile.test.sh → 150 passed, 0 failed.
bash test/run.sh → 18 test files passed, 0 failed.
Spot-checked both warning variants emit the exact three-scope tail; old two-scope tail is gone.
CI on this head: test, self-guards, action-exercise, docs-sync-exercise, labels jobs, release-exercise steps all success.

Scope / non-blocking

Tight, mechanical catch-up to the private-repo contract incubator#60/62 proved. Comment block on blind_sweep_warning still documents the #101 D5 "report, do not diagnose" posture correctly; only the candidate list grew, as the issue required. No blocking nits.

Non-blocking: the secondary grep assertions still only name checks: read and statuses: read (the full-line pin already locks actions: read). Optional follow-up if someone wants symmetry — not required by #173.

## Verdict: approve **Head:** `eae000bd624df8318a46b91a624634ba5166af84` **Issue:** Closes #173 ### Acceptance criteria | Criterion | Result | |---|---| | Both `blind_sweep_warning` emit lines carry the three-scope candidate tail verbatim (`checks: read, statuses: read and actions: read…`), still framed as "one candidate", no diagnosis language | **met** — L73 and L75 match the issue's tail bytes exactly; lead still "sampled reason" / "no reason was captured" | | `test/labels-reconcile.test.sh` pins the new bytes and the suite is green | **met** — 150/0 locally; full-line expectation covers both the new scopes and #101 D5 | | `docs/CONSUMERS.md` example gains `actions: read` with the incubator#60 why-comment; prose is "all three explicit reads"; empty-`state:*` symptom retained | **met** | | shellcheck / actionlint | **met** — CI `self-guards` green; local shellcheck on the script is clean of new findings (only pre-existing SC1091 on the `ruling.sh` source) | | `changelog.d/173.md` flat, entry ≤300 chars | **met** — one flat bullet, 131 characters | ### Verification run - Detached worktree at the head SHA. - `bash test/labels-reconcile.test.sh` → 150 passed, 0 failed. - `bash test/run.sh` → 18 test files passed, 0 failed. - Spot-checked both warning variants emit the exact three-scope tail; old two-scope tail is gone. - CI on this head: `test`, `self-guards`, `action-exercise`, `docs-sync-exercise`, labels jobs, release-exercise steps all **success**. ### Scope / non-blocking Tight, mechanical catch-up to the private-repo contract incubator#60/62 proved. Comment block on `blind_sweep_warning` still documents the #101 D5 "report, do not diagnose" posture correctly; only the candidate list grew, as the issue required. No blocking nits. Non-blocking: the secondary grep assertions still only name `checks: read` and `statuses: read` (the full-line pin already locks `actions: read`). Optional follow-up if someone wants symmetry — not required by #173.

kimi-bot-andresmgsl commented

2026-07-24 23:02:47 +00:00

(Migrated from github.com)

🔎 reviewing head eae000bd62

🔎 reviewing head eae000bd624df8318a46b91a624634ba5166af84

kimi-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 23:03:09 +00:00

kimi-bot-andresmgsl (Migrated from github.com) left a comment

Approve — head eae000b.

Reviewed the whole PR against #173's spec, which was byte-precise; the diff matches it exactly.

Verified by running, in a detached worktree at the head:

Extracted blind_sweep_warning() from the new script and ran both variants. With-reason and no-reason outputs match the spec's verbatim tail — — one candidate is missing checks: read, statuses: read and actions: read in the caller (private repos do not imply them) — byte-for-byte, and the no-reason variant keeps the candidate framing without diagnosis language (#101 D5 holds: the two grant checks: read and statuses: read must-fail guards in the test are negative assertions and still pass).
Red proof, locally: the origin/main implementation's output differs from the new pinned expectation — the updated test fails against the old hint text, as required.
Partial-blind and zero-PR cases still emit nothing.
CONSUMERS.md: actions: read line with the why-comment sits after statuses: read; prose now says "all three explicit reads"; the empty-state:*-axis symptom sentence is retained. Matches spec item 2 verbatim.
changelog.d/173.md: flat single bullet, 134 bytes, under the 300-character bound (#167).
Swept the tree for other surfaces still carrying the old two-scope hint — none outside the intended negative test guards.

Could not verify locally, and relied on CI instead: this box has no jq or shellcheck, so I could not run the full test file, test/run.sh, or the shellcheck/actionlint scripts myself. All applicable CI checks on this head are green (test, self-guards, labels / reconcile, action-exercise, docs-sync-exercise, the release-exercise jobs), which covers the suite and the lint gates the PR body claims.

Nothing blocking; the change is minimal, spec-faithful, and evidenced.

**Approve** — head `eae000b`. Reviewed the whole PR against #173's spec, which was byte-precise; the diff matches it exactly. Verified by running, in a detached worktree at the head: - Extracted `blind_sweep_warning()` from the new script and ran both variants. With-reason and no-reason outputs match the spec's verbatim tail — `— one candidate is missing checks: read, statuses: read and actions: read in the caller (private repos do not imply them)` — byte-for-byte, and the no-reason variant keeps the candidate framing without diagnosis language (#101 D5 holds: the two `grant checks: read and statuses: read` must-fail guards in the test are negative assertions and still pass). - Red proof, locally: the `origin/main` implementation's output differs from the new pinned expectation — the updated test fails against the old hint text, as required. - Partial-blind and zero-PR cases still emit nothing. - CONSUMERS.md: `actions: read` line with the why-comment sits after `statuses: read`; prose now says "all three explicit reads"; the empty-`state:*`-axis symptom sentence is retained. Matches spec item 2 verbatim. - `changelog.d/173.md`: flat single bullet, 134 bytes, under the 300-character bound (#167). - Swept the tree for other surfaces still carrying the old two-scope hint — none outside the intended negative test guards. Could not verify locally, and relied on CI instead: this box has no `jq` or `shellcheck`, so I could not run the full test file, `test/run.sh`, or the shellcheck/actionlint scripts myself. All applicable CI checks on this head are green (`test`, `self-guards`, `labels / reconcile`, `action-exercise`, `docs-sync-exercise`, the release-exercise jobs), which covers the suite and the lint gates the PR body claims. Nothing blocking; the change is minimal, spec-faithful, and evidenced.

claude-bot-andresmgsl commented

2026-07-24 23:21:04 +00:00

(Migrated from github.com)

🔎 reviewing head eae000bd62

🔎 reviewing head eae000bd624df8318a46b91a624634ba5166af84

claude-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 23:22:59 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

Approve at eae000bd624df8318a46b91a624634ba5166af84.

Reviewed against #173's spec; every criterion verified by running it, not by reading the worklog:

Warning lines (spec D1): both emit lines in blind_sweep_warning() carry the specced three-scope tail byte-for-byte — grep -cF on the verbatim tail returns exactly 2. The candidate framing ("one candidate is missing…") survives, no diagnosis language returns, and the #101 D5 incident comment block above the function is untouched.
CONSUMERS.md (spec D2): line 317 is the specced actions: read line verbatim, including the why-comment and (incubator#60) pointer, placed after statuses: read. The prose now reads "needs all three explicit reads above" and still describes the empty-state:*-axis symptom.
Test moves with the text (spec D3): ran the red proof myself — restored the merge-base labels-reconcile.sh under the PR's test and got 149 passed / 1 failed, failing on exactly the pinned warning bytes; with the PR's script, 150 passed / 0 failed. Full bash test/run.sh: 18 test files passed / 0 failed.
Changelog (spec D4, #167): changelog.d/173.md exists, flat, single entry at 133 characters (≤300).
Gates: shellcheck-all.sh and actionlint-all.sh both pass locally; all applicable CI checks are green on this head.

Docs-only change with the test pin moving in lockstep — exactly the scope the issue minted, nothing extra. Ship it.

**Approve** at `eae000bd624df8318a46b91a624634ba5166af84`. Reviewed against #173's spec; every criterion verified by running it, not by reading the worklog: - **Warning lines (spec D1):** both emit lines in `blind_sweep_warning()` carry the specced three-scope tail byte-for-byte — `grep -cF` on the verbatim tail returns exactly 2. The candidate framing ("one candidate is missing…") survives, no diagnosis language returns, and the #101 D5 incident comment block above the function is untouched. - **CONSUMERS.md (spec D2):** line 317 is the specced `actions: read` line verbatim, including the why-comment and `(incubator#60)` pointer, placed after `statuses: read`. The prose now reads "needs all three explicit reads above" and still describes the empty-`state:*`-axis symptom. - **Test moves with the text (spec D3):** ran the red proof myself — restored the merge-base `labels-reconcile.sh` under the PR's test and got **149 passed / 1 failed**, failing on exactly the pinned warning bytes; with the PR's script, **150 passed / 0 failed**. Full `bash test/run.sh`: **18 test files passed / 0 failed**. - **Changelog (spec D4, #167):** `changelog.d/173.md` exists, flat, single entry at 133 characters (≤300). - **Gates:** `shellcheck-all.sh` and `actionlint-all.sh` both pass locally; all applicable CI checks are green on this head. Docs-only change with the test pin moving in lockstep — exactly the scope the issue minted, nothing extra. Ship it.

codex-bot-andresmgsl commented

2026-07-24 23:31:23 +00:00

(Migrated from github.com)

Closing round summary

What shipped

The private-repository blind-sweep warning now names the complete candidate permission set: checks: read, statuses: read, and actions: read, while retaining candidate framing and avoiding diagnosis language.
The consumer guidance now grants actions: read, explains why private repositories require it (as proven by heavy-duty/incubator#60), and keeps the empty-state:* symptom documented.
The warning-byte regression test and flat changelog fragment moved with the behavior.

Rounds

Round 1 reviewed head eae000bd624df8318a46b91a624634ba5166af84. Grok, Kimi, and Claude all approved that head. No blocking findings were raised and no review-round code changes were required. Grok left one explicitly non-blocking residue: the secondary negative grep assertions still name only checks: read and statuses: read; the full-line assertion already pins actions: read, so this is outside #173 and does not weaken the shipped contract.

Verification

Red proof: the updated expectation against the old implementation fails exactly on the warning bytes (149 passed / 1 failed).
Green proof: bash test/labels-reconcile.test.sh — 150 passed / 0 failed.
Full suite: bash test/run.sh — 18 test files passed / 0 failed.
shellcheck-all.sh and actionlint-all.sh pass.
Reviewers independently checked both warning variants, the consumer permission example and symptom prose, the flat ≤300-character changelog entry, and the current-head diff.
All applicable GitHub Actions checks are green; the PR is mergeable with no blocker:* labels.

Post-merge residue

No required post-merge work. The optional secondary-grep symmetry note above can return through discussion/triage if desired; it is not part of #173.

## Closing round summary ### What shipped - The private-repository blind-sweep warning now names the complete candidate permission set: `checks: read`, `statuses: read`, and `actions: read`, while retaining candidate framing and avoiding diagnosis language. - The consumer guidance now grants `actions: read`, explains why private repositories require it (as proven by `heavy-duty/incubator#60`), and keeps the empty-`state:*` symptom documented. - The warning-byte regression test and flat changelog fragment moved with the behavior. ### Rounds - Round 1 reviewed head `eae000bd624df8318a46b91a624634ba5166af84`. Grok, Kimi, and Claude all approved that head. No blocking findings were raised and no review-round code changes were required. Grok left one explicitly non-blocking residue: the secondary negative grep assertions still name only `checks: read` and `statuses: read`; the full-line assertion already pins `actions: read`, so this is outside #173 and does not weaken the shipped contract. ### Verification - Red proof: the updated expectation against the old implementation fails exactly on the warning bytes (149 passed / 1 failed). - Green proof: `bash test/labels-reconcile.test.sh` — 150 passed / 0 failed. - Full suite: `bash test/run.sh` — 18 test files passed / 0 failed. - `shellcheck-all.sh` and `actionlint-all.sh` pass. - Reviewers independently checked both warning variants, the consumer permission example and symptom prose, the flat ≤300-character changelog entry, and the current-head diff. - All applicable GitHub Actions checks are green; the PR is mergeable with no `blocker:*` labels. ### Post-merge residue - No required post-merge work. The optional secondary-grep symmetry note above can return through discussion/triage if desired; it is not part of #173.