fix: separate dependency waits from needs-spec in pickup

[lemarier]

Change

Idle pickup had one blocker path: comment questions, add needs-spec, and drop agent-ready. A worker waiting on another open issue took that path too, so the issue needed a human to relabel it after the blocker closed, and a dependency written only in prose let the dispatcher claim an issue it could not finish (origin89hq/firmware#6 waiting on #12).

Workers now separate the two cases. A dependency on an open issue gets a blocked-by link, an evidence comment, and agent-working removed while agent-ready stays, and the coordinator unlinks the issue from the preserved worktree, so pickup takes the issue again once the blocker closes. A missing user decision keeps the needs-spec path, and both apply when both are true. The coordinator reads issue comments before claiming and skips, and reports, issues naming an open prerequisite without a link. The precheck excludes issues with an open blocker (issue_dependencies_summary.blocked_by), so a kept agent-ready does not start an idle run every tick. The final report lists issues sent to needs-spec, linked to a blocker, or skipped, and the daily hygiene check flags prose-only dependencies.

Filing gets the same rule, so new issues do not repeat the gap: origin89-working now requires a blocked-by link when an issue cannot start until another open issue lands, and whenever a later comment reveals one. Needs-spec triage links a prose dependency and may add agent-ready to an issue whose only remaining blocker is that link, since pickup skips it until the blocker closes; previously triage withheld agent-ready, which left the same manual relabel step.

The issue's point about pickup workers having no coordinator was already addressed by #16; this change only states that the issue comment is the record that outlives the Run.

Closes #15

Validation

just check passes (32 tests). Confirmed that the REST issues list returns issue_dependencies_summary.blocked_by per issue (firmware#11 reports 1). Open Code Review excludes Markdown, so it reviewed no files; the prose was reviewed by hand. Two scenarios were added to docs/skill-validation.md; no live pickup run has exercised the new rules yet.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-27T11:02:42.073597Z	f739b75	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: QUIET

Plan: Advanced

Run ID: e3f6ebea-b94e-4a8c-bd6d-f9a723e2fca5

📥 Commits

Reviewing files that changed from the base of the PR and between 3db666d and 60300f1.

📒 Files selected for processing (2)

• docs/skill-validation.md
• skills/origin89-orca/references/unattended-run.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

The issue instructions now require a blocked-by link when work depends on another open issue. Orca worker guidance distinguishes dependency waits from missing user decisions. Triage and idle pickup guidance address linked open dependencies and prose-only prerequisites. Validation scenarios cover issue filing, worker handling, and readiness after linking a dependency.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 60300

No demonstrated issue blocks merging. The partial-work handoff has not been verified against Orca’s worktree behavior.

Architecture Summary

Architecture risk: 🔵 Low · up to 60300

The change affects 2 systems.

Changed systems: skills, docs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — skills (service) was modified; 2 changed files map to changed impact.
• observed — docs (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in skills/origin89-working/SKILL.md: The issue-creation workflow now requires linking dependent issues through GitHub’s blocked-by relationship, using the blocking issue’s numeric ID, and adding the link if a dependency is identified later. This replaces the previous step that immediately instructed users to read back the created issue.
• observed — Modified behavior in docs/skill-validation.md: Adds a working-rules scenario requiring a blocked-by link when filing an issue that cannot start until another open issue lands.
• observed — Modified behavior in docs/skill-validation.md: Adds Orca scenarios requiring no claim when a ready issue's comment names an open prerequisite without a blocked-by link; requiring a pickup worker to link a discovered open dependency, comment its evidence, remove agent-working, retain agent-ready, and avoid needs-spec when no decision is missing; and requiring needs-spec while removing both readiness and working labels when a decision remains unresolved.
• observed — Modified behavior in docs/skill-validation.md: Changes the spec-answer scenario: remove needs-spec only when all questions are resolved; with an open dependency remaining, link it as blocked-by and add agent-ready. The previous expectation said not to add agent-ready.

🚥 Pre-merge checks | ✅ 4 | ❓ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	The reviewed skill guidance implements the main #15 requirements: it separates open-issue waits from missing decisions, applies both paths, checks issue_dependencies_summary.blocked_by, skips prose-…	Provide reviewable evidence that the pickup automation prompt is updated with the #15 rules or that it points to unattended-run.md as its source.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: separating open dependency waits from the needs-spec path during pickup.
Description check	✅ Passed	The description follows the required Change and Validation sections. It explains the behavior changes, affected workflows, test results, manual review, and the unperformed live pickup validation.
Out of Scope Changes check	✅ Passed	The changed paths are connected to #15. unattended-run.md contains the pickup behavior, origin89-working/SKILL.md contains the blocked-by filing rule, and docs/skill-validation.md contains valid…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

Full details: Linked Issues check

Explanation

The reviewed skill guidance implements the main #15 requirements: it separates open-issue waits from missing decisions, applies both paths, checks issue_dependencies_summary.blocked_by, skips prose-only prerequisites, records worker evidence in comments, unlinks preserved worktrees, reports outcomes, and adds issue-filing dependency rules. docs/skill-validation.md adds scenarios for these paths. The unresolved point is the pickup automation prompt. The repository has no tracked automation configuration, and the prompt in ~/.origin89/automations/ is not reviewable here. The available evidence does not establish that this prompt uses the updated guidance.

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f739b75890

ℹ️ 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".

[coderabbitai]

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

🟡 Other comments (1)

skills/origin89-orca/references/unattended-run.md-240-241 (1)

240-241: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Preserve partial work during dependency waits.

The dependency-wait path records the partial-work branch, then unlinks the preserved worktree. The next pickup uses new-top-level, but its spec does not include that branch. A later worker can therefore start without the partial changes.

Record the branch in the pickup handoff and require the next worker to reuse the preserved worktree or use that branch before unlinking it.

Suggested fix

-   authority in the spec. A parent with independent sub-issues coordinates them
+   authority in the spec. If the issue records a branch holding partial work,
+   include that branch in the pickup handoff and reuse it or the preserved
+   worktree. A parent with independent sub-issues coordinates them

🧹 Nitpick comments (1)

docs/skill-validation.md (1)

74-74: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add a combined blocker scenario.

unattended-run.md requires both blocker paths when an open dependency and an unresolved decision occur together. The current scenarios cover these paths separately, so a worker can handle only one blocker without the validation scenarios detecting it.

Suggested scenario

+| Orca | A pickup worker finds an open dependency and an unresolved decision | Link the blocker, comment the evidence, ask the decision questions, remove agent-working and agent-ready, and add needs-spec |

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: QUIET

Plan: Advanced

Run ID: 9e737b0a-25e9-4bfa-b701-48f15dd49116

📥 Commits

Reviewing files that changed from the base of the PR and between 99052e8 and 3db666d.

📒 Files selected for processing (3)

• docs/skill-validation.md
• skills/origin89-orca/references/unattended-run.md
• skills/origin89-working/SKILL.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

[lemarier]

Both CodeRabbit comments on 3db666d are addressed in 60300f1: the pickup spec now names a recorded partial-work branch and the worker builds on it, and skill-validation has a scenario for an open dependency together with an unresolved decision.

[lemarier]

Decision (lemarier, Roger Ask 01M3HFJXV41R8NEV6KR989M68X): "Keep new behavior". Needs-spec triage adds agent-ready when the only remaining blocker is an open issue recorded as a blocked-by link; the PR stays as written.