Skip to content

docs: correct the claim that nothing reports an unarchived OpenSpec change - #398

Merged
thecodedrift merged 2 commits into
mainfrom
docs/claude-md-openspec-label
Sep 23, 2026
Merged

docs: correct the claim that nothing reports an unarchived OpenSpec change#398
thecodedrift merged 2 commits into
mainfrom
docs/claude-md-openspec-label

Conversation

@thecodedrift

@thecodedrift thecodedrift commented Sep 23, 2026

Copy link
Copy Markdown
Member

CLAUDE.md told agents, under Stacked PRs → Other gotchas:

No OpenSpec archive check at all. An unarchived change directory is expected on a pull request AND on main while a forward-merging stack drains. Neither is a failure, and nothing reports it.

The first half is right and the last four words are not. .github/workflows/openspec-label.yml reports it. It runs on every pull request with no branches: filter, reads the head tree, and asks one content-only question — does any directory other than archive/ exist under openspec/changes/? If one does the pull request gets the Open OpenSpec label. The predicate asks nothing about stack position, so every PR in a stack gets the same answer and the label clears when a branch archives the change. On the tip, where gh pr list --base <head branch> returns zero open PRs, it adds a ::warning:: annotation and a job summary naming the pnpm openspec archive line to run. On main, openspec-tracking.yml opens a tracking issue for an unarchived change no open PR is working on, and openspec-sweep.yml escalates it after seven days of no activity on the directory.

Measured on #394 (feat/onboarding-tool-detection):

Nothing blocks, and the edit is careful not to imply otherwise. The workflow's own header is emphatic about it: three earlier check-status versions were deleted in 8d1f3a1 because a signal expected to be red is not a signal. It is also deliberately not a step in Validate, since release-cli-nightly.yml triggers on workflow_run matched to that workflow's name:, so an unarchived change must not be able to gate a nightly publish. The operative advice is unchanged: an unarchived change directory is normal on a mid-stack PR; archive on the tip.

Changes

Three passages in CLAUDE.md, all in the Stacked PRs section:

  • the Other gotchas bullet, rewritten to say what reports and that none of it fails
  • "No check asks about that anywhere any more" under Every OpenSpec proposal declares its delivery shape, which also claimed the abandoned-work case is unmeasured — openspec-sweep.yml measures exactly that
  • one sentence under branches: filters do not tell you where a workflow runs, which described the deleted archive check with no mention of what replaced it

Docs only. No file under packages/cli/src/** changed. The iterate-pr skill (.agents/skills/iterate-pr/SKILL.md) already describes the label, the tip warning, and the tracking issue accurately and needed no edit; openspec/specs/infrastructure/spec.md says "no check status reports it", which is still true as written.

No changeset, so the Changeset warning on this PR is expected: documentation with no released surface.

@thecodedrift
docs: correct the claim that nothing reports an unarchived OpenSpec c…
d2fe5ec 
…hange

openspec-label.yml applies the Open OpenSpec label and warns on the tip, and openspec-tracking.yml/openspec-sweep.yml report on main. None of them fail or block.
@thecodedrift

thecodedrift commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

@claude /review

@claude

claude Bot commented Sep 23, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Review complete

  • Read .prior-review.json (no prior threads/reviews found — this is the first review of this PR)
  • Fetch PR diff via gh pr diff
  • Verify factual claims in the doc edit against the actual workflow files (openspec-label.yml, openspec-tracking.yml, openspec-sweep.yml)
  • Post inline findings
  • Post final summary

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contained no reviewThreads, reviews, or prior review comments (only the @claude /review trigger comment), so there is nothing to classify as previously addressed/still-open — this is a first-pass review of the whole diff.

Findings

This is a docs-only 3-hunk edit to CLAUDE.md. I read .github/workflows/openspec-label.yml, openspec-tracking.yml, and openspec-sweep.yml directly (the diff's central claim is about what these workflows do, so it's checkable against source rather than taken on faith) and cross-checked each new sentence against them.

Two of the three hunks (the "Note how this interacts with archiving" paragraph, and the "Other gotchas" bullet) hold up well against the workflow source — the description of openspec-label.yml's predicate, the tip warning, openspec-tracking.yml's tracking issue, and openspec-sweep.yml's 7-day escalation (STALE_DAYS: "7") all match.

[New] One issue, posted inline on CLAUDE.md line 151 (the branches: filters bullet):

Its replacement, openspec-label.yml, takes the first route properly: it reads the head tree and never asks where the pull request lands.

This sentence looks like a factual misattribution, verifiable two ways:

  1. The check that "moved off pull requests onto main" and misreported an in-flight stack as a fault was replaced by openspec-tracking.yml (its header describes "the claim test" specifically built to keep a draining stack quiet), not by openspec-label.yml, which is pull_request-triggered and has no such logic.
  2. openspec-label.yml's own header says the opposite of what's claimed here ("THE LABEL PREDICATE ASKS NOTHING ABOUT STACK POSITION... This is the shape changeset.yml uses") — i.e. it takes the second route the bullet describes, not "the first route." This new sentence is also inconsistent with this same PR's "Other gotchas" bullet, which correctly says the predicate "asks nothing about stack position."

Full detail and a suggested fix are in the inline comment.

claude[bot]
claude Bot reviewed Sep 23, 2026
View reviewed changes
Comment thread CLAUDE.md Outdated
@thecodedrift
docs: name openspec-tracking.yml as the main-side replacement
d01a352 
The deleted validate.yml step was replaced by openspec-tracking.yml and its claim test, not by openspec-label.yml, which takes the changeset.yml route and asks nothing about stack position.
@thecodedrift

thecodedrift commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

Re: @claude[bot] — "Claude finished @thecodedrift's task in 3m 22s …"
#398 (comment)

The line 151 finding was right on both counts and is fixed in d01a352: the main-side replacement is openspec-tracking.yml (its header names the deleted validate.yml step as predecessor and describes the claim test that keeps a draining stack quiet), and openspec-label.yml takes the changeset.yml route, asking nothing about stack position. Inline thread replied to and resolved.

— AI Coding Agent

@thecodedrift
thecodedrift merged commit a10c955 into main Sep 23, 2026
5 checks passed
@thecodedrift
thecodedrift deleted the docs/claude-md-openspec-label branch September 23, 2026 20:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@claude claude[bot] claude[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@thecodedrift