Make Sandcastle a Blocker-Aware Orchestrator

[NandaScott]

Description

This replaces the sandcastle simple-loop runner with a blocker-aware issue orchestrator. A run picks up open ready-for-agent issues, works each in an isolated Docker sandbox, opens a PR, and relabels the issue to needs-review.

The initial setup (PR #175) shipped the Python-adapted simple-loop template. This builds on it: the agent now commits only, and the host pushes, opens the PR, and relabels. That split fixes the behavior I did not want from the template, where the agent closed issues before the work was reviewed.

The orchestrator reads the ## Blocked by section of each issue and only dispatches one once every blocker it names is cleared. A blocker is cleared when its issue is closed or when the target branch already carries a commit referencing it (e.g. (#170)). That commit check is what lets PRD branches work: merging a slice into a prd/<slug> branch lands the commit but does not auto-close the issue, since auto-close only fires on the default branch. Issues with a milestone target their prd/<slug> branch; everything else targets develop. This matters for the connector series (#170 to #171 to #172/#173), where a later slice must never branch off a base that lacks the earlier slice's work.

Two correctness fixes came out of the first live run. The agent's gates were missing black, which CI checks first, so #176 opened red even though the agent passed its own checks: the prompt gates now mirror CI exactly. And the host was opening a PR whenever the agent produced any commits, so I gated PR creation on the agent's completion signal (RunResult.completionSignal) so partial work leaves a branch for review instead of a red PR.

Changes:

• Replaced main.mts with a host orchestrator: list ready-for-agent, fan out one agent per issue, push, open a PR, relabel ready-for-agent to needs-review.
• Made dispatch respect each issue's ## Blocked by list, clearing a blocker on issue-closed or a (#N) commit on the target branch.
• Routed milestone issues to a prd/<slug> branch (created from develop on first use) and everything else to develop.
• Gated PR creation on the agent's completion signal, so a stalled run leaves its branch for review rather than opening a red PR.
• Rewrote the prompt as a per-issue template whose gates mirror CI: black, ruff check scrython tests, mypy, pytest.
• Added DRY_RUN=1 (print the plan, spawn nothing) and ONLY_ISSUE=N (single-issue smoke test) controls.
• Documented the runner in Contributing.md: the label flow, how a run works, setup, and the run commands.

Testing

• DRY_RUN=1 npx tsx .sandcastle/main.mts prints the correct dispatch plan and blocked list (Add paginate to Connector ABC and rewire iter_all to delegate #171 waits on Connector seam: ABC + ScryfallConnector + handler rewiring + ContextVar resolution #170; MockConnector and retire mock_urlopen across the test suite #172/CachedConnector decorator and deprecate cache= / cache_ttl= kwargs #173 wait on Connector seam: ABC + ScryfallConnector + handler rewiring + ContextVar resolution #170 and Add paginate to Connector ABC and rewire iter_all to delegate #171)
• ONLY_ISSUE=170 npx tsx .sandcastle/main.mts ran live end-to-end: created prd/scryfallconnector-refactor, the agent passed its gates and committed, the host opened Connector seam: ABC + ScryfallConnector + handler rewiring + ContextVar resolution #176 against the PRD branch and relabeled Connector seam: ABC + ScryfallConnector + handler rewiring + ContextVar resolution #170 to needs-review
• Connector seam: ABC + ScryfallConnector + handler rewiring + ContextVar resolution #176 is green on 3.10/3.11/3.12 after the black gate fix landed on its branch