Skip to content

Fix: spec-queue loop reads tasks.md from the wrong branch #83

Description

@androidand
Proposal

Why

The spec-queue loop (loop-spec-queue) resolves its cursor by reading tasks.md
from the working tree (resolveQueuereadTasksfs.readFileSync). When a
loop iteration checks out a different branch (e.g. loop/change-a) and the next
iteration targets a different change (e.g. loop/change-b), the queue resolution
reads tasks.md from whichever branch is currently checked out — not the branch
that belongs to the change being worked.

Observed failure:
The loop was working change A (all tasks checked, working tree on loop/a). It
then switched to loop/b for change B. When it returned to change A, the working
tree was still on loop/b, so resolveQueue read branch B's tasks.md and reported
a stale "next unchecked task" for change A. The loop burned 6+ iterations
re-reporting the same task, and the VERIFY gate reviewer hit its step limit
trying to verify a change that was already done.

What

The queue loop SHALL ensure the working tree is on the correct branch
(loop/<change-slug>) before reading tasks.md to derive the cursor and next
unchecked task. Alternatively, the queue resolution SHALL read tasks.md from
the change's branch directly (e.g. git show loop/<slug>:openspec/changes/<slug>/tasks.md)
without requiring a checkout.

Scope

  • packages/opencode/src/loop/spec-queue/queue.tsresolveQueue / readTasks
  • packages/opencode/src/loop/spec-queue/brief.tsbuildBrief (reads tasks.md again)
  • Possibly packages/opencode/src/loop/loop.ts — branch checkout before iteration

Risks

  • git show reads are slower than direct file reads, but tasks.md is small
  • If the branch doesn't exist yet (first iteration of a new change), fall back to
    the working tree read
  • Concurrent loops on different branches in the same repo could race on checkout;
    git show avoids this entirely

Tasks

Phase 1: Reproduce and confirm

  • 1.1 Write a failing test: two changes on different branches, loop switches between them, queue reports wrong next task
    • Validation: bun test packages/opencode/test/loop/spec-queue/queue-mode.test.ts
    • Note: Test should create a temp repo with two changes on two branches, check out branch A, resolve queue (expect change A's tasks), check out branch B, resolve queue (expect change B's tasks, not A's stale state)

Phase 2: Fix

  • 2.1 Make readTasks branch-aware: read tasks.md from the change's branch via git show when the working tree is on a different branch
    • Validation: bun typecheck in packages/opencode
    • Note: git show loop/<slug>:openspec/changes/<slug>/tasks.md with fallback to direct file read when branch doesn't exist or git fails
  • 2.2 Update buildBrief to use the same branch-aware read for the tasks.md content it embeds in the prompt
    • Validation: bun test packages/opencode/test/loop/spec-queue/
  • 2.3 Add integration test: full loop iteration across two changes on different branches produces correct briefs
    • Validation: bun test packages/opencode/test/loop/spec-queue/queue-mode.test.ts

Phase 3: Verify

  • 3.1 Run full loop test suite
    • Validation: bun test packages/opencode/test/loop/
  • 3.2 Typecheck
    • Validation: bun typecheck in packages/opencode

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions