feat(ci): announce a published nightly on the Version Packages PR

[thecodedrift]

When a nightly publishes, the open changesets "Version Packages" pull request (head changeset-release/main, currently #74) gains a build-info region at the end of its body:

<!-- nightly -->
### Build Info
`npx @taskless/cli-nightly@0.11.0-20260818123456x05b3c88`

**Built from:** 05b3c88
**Built at:** 2026-08-18 12:34:56
<!-- /nightly -->

Those reviewers are exactly the audience for a build of the work the pending changesets describe.

⚠️ One deviation from the issue text — please overrule me if you disagree

The issue writes the install line as npx @taskless/cli@<version>. Nightlies publish under @taskless/cli-nightly (.github/scripts/nightly-pack.cjs, design D2 — the pack rewrites name before packing), and @taskless/cli@0.11.0-20260818123456x05b3c88 does not exist on npm. That line would 404, or at best send a reviewer to the last release.

So the region names @taskless/cli-nightly — the package that will actually install. Everything else matches the issue's format byte for byte. If you want the literal text instead, it is one constant in nightly-breadcrumb.cjs.

How it is built

A third job, breadcrumb, holding pull-requests: write and no credential. The publish job holds an OIDC identity authorized to publish under the @taskless scope; adding pull-requests: write to it would widen what a compromised step there can reach from "publish a package" to "publish a package and rewrite pull request text" — including the text of the PR that gates the next release. Same boundary the file already draws between gate and publish, drawn once more. No id-token, no environment, no contents write beyond checkout-read.

needs: publish is what "block on a successful publish" means mechanically — a job whose dependency was skipped does not run, so a suppressed nightly (either gate false) never reaches it.

The version arrives as a job output, and every fact is parsed back out of it. The stamp is <n.m.k>-<yyyymmddhhmmss>x<sha>, so it already carries the build time and the commit. A fresh Date.now() would print a time that disagrees with the version on the line above it, and a fresh git rev-parse would print a sha the published tarball does not carry. The "stamped exactly once" rule is already load-bearing here (--print-version); this is its third consumer and it obeys it.

No open Version Packages PR exits 0. changeset-release/main exists only while changesets are pending, and a nightly can publish in the seconds before changesets opens it — a cosmetic breadcrumb must never fail a run that already published to npm. That is deliberately not the same branch as a failed API call: gh api is allowed to exit non-zero and fail the step, with no || echo '[]' fallback collapsing the two (the same fail-open closed in gate 2 by task 4.13).

gh api -X PATCH repos/{owner}/{repo}/pulls/<n>, never gh pr edit — its GraphQL path is broken by the Projects (classic) deprecation (CLAUDE.md).

Upsert semantics, and what the tests cover

The region is removed and re-appended at the end rather than replaced in place, so it converges from any starting state. .github/scripts/nightly-breadcrumb.test.cjs (16 tests) covers:

• repeated publishes replace, never accumulate (one region after N publishes)
• appends at the end when absent; idempotent for one version
• a manually deleted region is re-attached
• a region a human moved mid-body is moved back to the end, not duplicated
• coexistence with <!-- stack --> — that region is left byte-for-byte alone across two publishes, and a stack region containing the word "nightly" is not mistaken for one
• a non-array pulls response throws (empty vs. malformed are different answers)

Not reusing stack-breadcrumb.cjs

Its REGION_PATTERN hardcodes the name stack and upsertCarriedRegion is keyed to PR numbers. Neither generalizes to a singleton region under another name, and widening them would make a working, well-tested file serve two callers with different invariants. Fresh zero-dependency helpers in the same style, with a .test.cjs sibling picked up by validate.yml's node --test .github/scripts/*.test.cjs.

Spec

openspec/changes/nightly-cli-builds is still open, so this adds D11 to design.md, task 4.14, and a requirement (A published nightly is announced on the pending release pull request) to the cli-nightly-builds delta.

Verification (all run locally in the worktree)

Command	Result
pnpm lint	pass (eslint, exit 0)
pnpm typecheck	pass (1/1 task; cache hit — no TS changed)
pnpm test	pass — 51 files, 630 tests
node --test .github/scripts/*.test.cjs	pass — 161 tests, 0 fail (16 new)
pnpm openspec validate --all --strict	24 passed, 0 failed
node .github/scripts/openspec-visibility.cjs	every requirement in 23 specs visible

Also smoke-tested the script end to end against fixture pulls.json payloads: an existing region is replaced, an empty list exits 0 with changed=false, and an error object exits 1.

Conflict heads-up

The PR for #127 is being written in parallel and also touches .github/workflows/release-cli-nightly.yml (it changes how the workflow triggers). Edits here are localized — an outputs: block on publish and one appended job — but whichever merges second will need a rebase.

CI-only, no user-facing release note → skip-changeset. Per .github/workflows/changeset.yml the check is advisory now; the label suppresses the warning rather than unblocking a merge.

Fixes #128

[Copilot]

Pull request overview

Adds a post-publish nightly build breadcrumb to the pending Version Packages PR.

Changes:

• Adds a least-privileged breadcrumb workflow job.
• Implements breadcrumb parsing, rendering, upsert logic, and tests.
• Updates OpenSpec design, requirements, and tasks.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Summary	Review comments
openspec/changes/nightly-cli-builds/tasks.md	Adds task 4.14.	No final comments.
openspec/changes/nightly-cli-builds/specs/cli-nightly-builds/spec.md	Adds announcement requirements and scenarios.	No final comments.
openspec/changes/nightly-cli-builds/design.md	Documents design D11.	No final comments.
.github/workflows/release-cli-nightly.yml	Adds the post-publish PR annotation job.	Critical: Full-body updates can lose concurrent changes; use re-fetch-and-merge or coordinate writers.
.github/scripts/nightly-breadcrumb.test.cjs	Tests parsing, rendering, replacement, and edge cases.	No final comments.
.github/scripts/nightly-breadcrumb.cjs	Implements version parsing and breadcrumb upsertion.	Moderate: Global newline normalization can alter unrelated user-authored content; limit it to removed-region boundaries and add a regression test.

Suppressed comments (3)

.github/scripts/nightly-breadcrumb.cjs:183

• This helper places the nightly region at the end only for the body it currently receives. If the Version Packages PR also has carried <!-- PR:N --> regions, the existing stack canonicalizer treats <!-- nightly --> as description and appends carried regions after it, so the next stack reconcile/carry moves nightly away from the required final position. Preserve this marker in the shared canonical layout and cover the carried-region case.

function upsertRegion(body, version) {
  const region = renderRegion(version);
  const description = stripRegion(body);
  return description.length === 0 ? region : `${description}\n\n${region}`;

.github/workflows/release-cli-nightly.yml:386

• The head filter does not constrain the base branch. GitHub permits multiple open PRs from the same head branch to different bases, so a PR from changeset-release/main targeting another branch could be returned and selected for this PATCH instead of the Version Packages PR. Add base=main to the query (or validate pull.base.ref in the selector) before writing.

          gh api "repos/${REPO}/pulls?state=open&head=${OWNER}:changeset-release/main" > nightly-pulls.json

.github/workflows/release-cli-nightly.yml:357

• This workflow deliberately has no cross-run concurrency, but this job writes the single shared “latest nightly” region. Two pushes can publish concurrently; if the older run reaches this job after the newer run, its PATCH will leave the Version Packages PR pointing at the stale build. needs: publish only orders jobs within one run, so serialize or cancel stale breadcrumb jobs (or reject an older stamped version before writing).

  breadcrumb:
    name: Link the nightly on the Version Packages PR
    needs: publish

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[thecodedrift]

Rebased onto main at 423363a (the archived-change main) — no merge commit, history stays linear. Force-pushed with a lease; the single commit is GPG-signed (G).

The nightly-cli-builds change was archived while this was in flight, so the three files I had edited under openspec/changes/nightly-cli-builds/ no longer exist. Git followed the rename and put my edits inside openspec/changes/archive/2026-08-21-nightly-cli-builds/; those are dropped — an archived change is closed and does not get reopened.

The spec content is re-homed accordingly:

• The requirement (A published nightly is announced on the pending release pull request, five scenarios) now lives directly in openspec/specs/cli-nightly-builds/spec.md, appended after A nightly publish carries the same attestation as a release.
• Design decision D11 has nowhere to live, so its reasoning is folded into the header comment of .github/workflows/release-cli-nightly.yml, under ANNOUNCING THE NIGHTLY ON THE VERSION PACKAGES PR — why a third job rather than a step in publish, why the version is parsed rather than re-measured, why not stack-breadcrumb.cjs, and why the region names @taskless/cli-nightly and not the issue's literal @taskless/cli. That file is where someone editing this behavior will actually be looking.
• openspec/specs/vale-binary-packages/spec.md is untouched — the Vale-environment requirement stays withheld pending Finish nightly-cli-builds: move Vale to npm-autopublish and verify the acceptance criteria #131.

The diff against main is now four files: the two new .github/scripts/nightly-breadcrumb*.cjs, the workflow, and the spec. Nothing under openspec/changes/.

Re-verified after the rebase: pnpm lint exit 0 · pnpm typecheck 1/1 · pnpm test 51 files / 630 tests · node --test .github/scripts/*.test.cjs 161 pass, 0 fail · pnpm openspec validate --all --strict 24 passed, 0 failed · openspec-visibility.cjs all requirements in 24 specs visible.

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 5m 43s —— View job

---

Review mode: incremental — read 2 prior review thread(s) before reviewing.

Both prior threads (from copilot-pull-request-reviewer) are still isResolved: false with no addressed-marker reply, so I re-raised both as [Unchanged since last review]:

• .github/scripts/nightly-breadcrumb.cjs:162 — global newline collapse in stripRegion can alter unrelated user-authored content.
• .github/workflows/release-cli-nightly.yml:446 — full-body PATCH is a GET-then-write with no re-fetch/merge, vulnerable to lost updates from concurrent writers of the same PR body (changesets bot, stack-breadcrumb.yml).

The prior review also had 3 suppressed (collapsed, non-thread) Copilot comments — lower confidence, never posted as inline threads, so they don't carry isResolved state. I re-examined each against the current code rather than skip them:

• Missing base check in selectVersionPullRequest — held up, re-raised as [New].
• No concurrency/staleness protection on the breadcrumb job across separate workflow runs — held up, re-raised as [New].
• Possible interaction with stack-breadcrumb.cjs's canonical body layout moving the region away from the end — I traced this through `stack-breadcrumb.cjs` (`ownDescription` / `canonicalizeBody`) and confirmed the mechanism concretely: it survives when carried regions are also present. Re-raised as [New] with the trace.

Findings (5 inline comments posted)

1. [Unchanged] nightly-breadcrumb.cjs:162 — unconditional \n{3,} → \n\n collapse whenever any region is/was present, not scoped to the removal seam.
2. [Unchanged] release-cli-nightly.yml:446 — full-body PATCH from an earlier snapshot; lost-update window against other writers of the same PR body.
3. [New] nightly-breadcrumb.cjs:205 — selectVersionPullRequest matches only on head.ref, never base.ref; a second open PR from changeset-release/main to a non-main base could be mis-selected.
4. [New] release-cli-nightly.yml:399 — needs: publish only orders jobs within one run; no concurrency group means an older run's breadcrumb job can finish after a newer run's and write stale build info.
5. [New] nightly-breadcrumb.cjs:183 — if the Version Packages PR carries stack-breadcrumb.cjs `` regions, its next reconcile treats the nightly region as ordinary description and can re-lay it before those carried blocks, breaking the "always at the end" requirement. Not exercised by either test suite.

Everything else — version parsing/rendering, the upsert idempotency, the gh api -X PATCH (not gh pr edit) choice, job permission scoping, the gate/publish/breadcrumb split, and the spec scenarios — reads correctly and matches what the extensive header comments describe. Test coverage for the parts that are tested (16 new tests) is solid.

I did not run lint/typecheck/tests myself — CI (Validate, Changeset) already reports those as green on this PR.
· Branch

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 3m 17s —— View job

---

Review mode: incremental — read 7 prior review thread(s) before reviewing.

Treated as ADDRESSED (not repeated), both closed by commit 8c74d51:

• .github/scripts/nightly-breadcrumb.cjs — the global \n{3,} → \n\n whitespace collapse in stripRegion (2 threads: the original Copilot thread and my earlier [Unchanged] re-raise). Verified in the current code: REGION_SEAM_PATTERN now captures only the newlines immediately adjacent to a region and the replacer decides "" vs "\n\n" based on whether the match sat at the start/end of the body. Two new regression tests (blank lines elsewhere in the description survive a republish, the seam left by a mid-body region becomes exactly one blank line) exercise exactly the case that broke before. This holds up — no bug left here.
• .github/workflows/release-cli-nightly.yml:468 — the full-body PATCH lost-update window (2 threads, same pattern). Not engineered around (correctly — PR bodies have no compare-and-swap), but now explicitly documented as an accepted risk with real reasoning (all three writers on this PR body are additive/self-healing, so a lost write costs one cycle, not data) in a comment added directly above the step. Marked resolved by the author with the AI-Coding-Agent marker; I agree the tradeoff is reasonable and don't have a stronger alternative to propose.

Still open — re-raised as [Unchanged since last review] (3 inline comments posted), none touched by 8c74d51 (that commit only changed the whitespace-seam logic and added the two documentation comments above):

1. .github/scripts/nightly-breadcrumb.cjs:214 — selectVersionPullRequest still matches only pull.head.ref, never pull.base.ref; the workflow's gh api query has no base= filter either. A second open PR from changeset-release/main to a non-main base could still be mis-selected.
2. .github/workflows/release-cli-nightly.yml:399 — still no concurrency group or cross-run ordering on the breadcrumb job; an older run's job finishing after a newer run's can still leave the PR pointing at a stale build.
3. .github/scripts/nightly-breadcrumb.cjs:192 — the stack-breadcrumb.cjs interaction is still real and now more concrete: I re-read stack-breadcrumb.cjs's ownDescription (lines 214-221) and canonicalizeBody (lines 339-362) directly — ownDescription strips only the and markers, so a stack reconcile on a stacked Version Packages PR still rebuilds the body as breadcrumb → description(nightly region embedded) → carried regions, moving the nightly region ahead of the carried blocks. This is now a direct conflict with the requirement text added in this PR itself (openspec/specs/cli-nightly-builds/spec.md:166: "SHALL be placed at the end… SHALL NOT modify any other managed region"), and neither test suite exercises this direction.

Newly reviewed this pass: the delta since the last review is just commit 8c74d51 (REGION_SEAM_PATTERN, stripRegion, two new tests, and two documentation comments in the workflow). I traced the new seam-matching logic (offset/atStart/atEnd against the un-mutated original string, consistent with how String.replaceAll computes match offsets) against several edge cases — region with single vs. double newlines on either side, region as the entire body, region flanked by other regions — and didn't find a new bug; the two added regression tests cover the case that mattered. I found nothing else new since the last review.

Nothing else in the diff (version parsing/rendering, upsert idempotency, the gh api -X PATCH choice, job permission scoping, the spec scenarios) changed since the last pass, and it still reads correctly.

I did not run lint/typecheck/tests myself — CI (Validate, Changeset) reports those on this PR.
· Branch