docs(iterate-pr): describe the OpenSpec label and tip warning

[thecodedrift]

.agents/skills/iterate-pr/SKILL.md said "there is no gate for it, in either direction" and "nothing will fail either way". That was written before openspec-label.yml, openspec-tracking.yml and openspec-sweep.yml existed, and an agent on the tip of a stack read it as permission to defer archiving to "on landing". main only takes PRs, so a change that lands unarchived needs another PR to correct it: on taskless/marketing, #50 and #51 landed unarchived and #52 was the correction.

The section is rewritten from the workflows themselves:

• the label predicate (openspec-label.yml reads the head tree for any directory under openspec/changes/ other than archive/, asks nothing about stack position, applies Open OpenSpec);
• the tip test (gh pr list --state open --base <this branch> returning zero) and what it emits, a ::warning:: annotation plus a job-summary block of pnpm openspec archive <change> lines, not a PR comment;
• the fork case, where neither the label nor the tip warning is evaluated;
• act on the warning before merge on a tip PR, leave the change directory alone on a non-tip PR;
• nothing fails CI, and the channel after landing is openspec-tracking.yml's OpenSpec: <change> is unarchived on main issue with openspec-sweep.yml escalating on it after seven days without git activity.

One correction to the issue's summary: the tip signal is a workflow annotation and step summary, not a comment posted on the PR. The rewritten section says so, since waiting for a comment that never arrives is the same trap in a new place.

No changeset: the skill ships through dotagents from this repo, not in the @taskless/cli package, so it carries no CLI release note.

pnpm lint (including pnpm cli check) and pnpm typecheck pass. The skill's bundled scripts/*.cjs and their tests mention neither OpenSpec nor archiving, so nothing there needed changing.

Fixes #375

@claude /review

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 2m 14s —— View job

---

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

.prior-review.json held no reviewThreads, no reviews, and only the triggering @claude /review comment — so this is the first review of this PR, and everything below is a full assessment of the diff.

Scope

This is a docs-only change: .agents/skills/iterate-pr/SKILL.md rewrites the "no gate for OpenSpec archiving" section (#### No PR check asks whether the OpenSpec change is archived) into #### The OpenSpec archive signal is a label and a warning, not a check, describing the now-existing openspec-label.yml, openspec-tracking.yml, and openspec-sweep.yml workflows.

What I checked

I read the new prose against the actual workflow YAML (.github/workflows/openspec-label.yml, openspec-tracking.yml, openspec-sweep.yml) and the planner script (.github/scripts/openspec-tracking.cjs), since the whole point of this rewrite is to describe those mechanisms accurately. Verified and matching:

• The label predicate reads the head tree with no stack-position logic, and the label clears when a branch in the stack archives the change.
• The tip test (gh pr list --state open --base <branch> == 0) and that it emits a ::warning:: annotation plus a job-summary block of pnpm openspec archive <change> lines — correctly called out as a workflow annotation/summary, not a PR comment.
• The fork case: no label (fork token is read-only) and no tip warning (a fork's head branch can't be a base in this repo, which would falsely report every fork PR as the tip).
• Nothing here fails CI, by design — matches the header comments in all three workflows about a red-that-means-"in progress" being a non-signal.
• openspec-tracking.yml's push-mode issue title/behavior (OpenSpec: <change> is unarchived on main, Open OpenSpec label, closes on archive) matches issueTitle()/planActions() in openspec-tracking.cjs.
• No stale cross-references to the old heading text elsewhere in the repo.

Finding

One inline comment posted:

• [New] .agents/skills/iterate-pr/SKILL.md:320 — "openspec-sweep.yml escalates on that issue daily once the directory has gone seven days without git activity" misstates the cadence. The sweep cron runs daily, but openspec-tracking.cjs throttles escalation to at most once per staleDays (7-day) window via the idleDays < staleDays guard, with an explicit comment in that file warning against exactly this daily-nag behavior. As written, the sentence tells a reader to expect a comment every day once a change goes stale, which is the opposite of what the code does.

No other correctness issues found; the rest of the rewritten section checks out against the workflows it describes.

[thecodedrift]

Re: @claude[bot] — "Claude finished @thecodedrift's task in 2m 14s — Review mode: incremental…"
#383 (comment)

The one finding was real: the sweep cron is daily but openspec-tracking.cjs throttles on idleDays < staleDays, so escalation is at most once per seven-day window. Corrected in 923c84a; the branch was also rebased onto current main.

— AI Coding Agent