factory: reviewer verdict — structured output + review against the issue, not just the diff

[ALLiDoizCode]

Gives the factory reviewer a verdict channel and the missing Spec axis — port of toon-protocol/toon-meta#299 to Forge.

What changes

• Structured verdict, enforced. Every reviewer run must end with <review>{"verdict":"clean"|"blocking","blockingFindings":[{file,line,summary,why}]}</review>. The schema is declared as sandcastle.Output.object({ tag: "review", schema }); extraction/validation is performed by the new .sandcastle/review-verdict.ts because — verified against the @ai-hero/sandcastle@0.12.0 dist — the engine's structured-output surface exists only on top-level run(), and the sandbox.run() the runners use silently ignores an output option. Extraction mirrors the engine's semantics exactly (last tag wins, fence-aware unwrap, JSON parse, zod schema validation).
• Malformed verdicts fail the run. One retry via SandboxRunResult.resume() (the engine's own structured-output retry mechanism, exactly one iteration, with engine-style error feedback); if the verdict is still malformed the runner throws and the Actions job goes red — a missing verdict is never mistaken for a clean one.
• Spec axis. The implement runner forwards ISSUE_NUMBER/ISSUE_TITLE via promptArgs; the standalone agent:review stage-0 runner resolves the issue from the PR body's Closes #n (no reference → Standards-only review). review-prompt.md instructs the reviewer to gh issue view the target FIRST and review the diff against its acceptance criteria; Forge's repo-specific review steps and gate commands are preserved, as is the context-budget section.
• Blocking side effects. Findings are posted as a PR review (event COMMENT) and needs:human is applied — pure REST via gh api (porcelain gh pr edit is broken in repos with a classic Project attached). In auto-merge mode a blocking verdict refuses to merge and falls back to PR mode.
• Standalone runner unbroken. Adopts connector#634's proven first-live-run fix: agent-review.yml now checks out main (git refuses one branch in two worktrees), and the runner materialises the PR head as a local branch (git fetch origin +head:head) so the engine's worktree add -b … HEAD fallback cannot silently review an empty diff.
• main.ts passes ISSUE_NUMBER/ISSUE_TITLE to its reviewer so the shared prompt resolves; the reserved autonomous loop does not consume the verdict yet (auto-merge wiring is toon-meta#270 work).

Forge-specific adaptations

Forge's live agent:review workflow runs forge review (forge-cli → forge-core), not the stage-0 .sandcastle/agent-review-pr.ts runner, so two extra changes keep that path working with the new prompt and checkout:

• packages/forge-core/src/sandcastle-runners.ts — runReview now passes ISSUE_NUMBER/ISSUE_TITLE (an unresolved {{…}} placeholder fails the run), recovering the issue id from the deterministic sandcastle/issue-<id> branch convention (the same id the factory PR body's Closes #n names); a branch outside the convention gets a Standards-only review.
• packages/forge-cli/src/review.ts — materialises the PR head as a local branch before prepareForReview (injectable seam, unit-tested), matching the workflow's new ref: main checkout.
• Deviation, stated openly: the forge-core review path does not yet consume the <review> verdict (extraction/enforcement lives in .sandcastle/review-verdict.ts, which a built package cannot import). The prompt contract and the Spec axis are live on that path; porting enforcement into forge-core (and into templates/sandcastle/ for newly-stamped factories) is follow-up toon-meta#270/#275 work.

zod was added as a root devDependency (^3.25.0, v3 — z.ZodIssueCode.custom kept): .sandcastle/main.ts already imported it but nothing declared it.

Verification

• Extraction smoke-tested in-repo (valid clean/blocking, fenced JSON, last-tag-wins, missing tag, invalid JSON, bad enum, blocking-without-findings, clean-with-findings, null line) — all 10 pass; temp script deleted before commit.
• Both stage-0 runners import-smoke-tested to their env guards (SANDCASTLE_PR_NUMBER / SANDCASTLE_ISSUE_NUMBER), nothing else.
• Full gate green locally in CI order: pnpm lint, pnpm typecheck, pnpm test (19 files, 172 tests incl. the two new seam tests), pnpm build, pnpm format:check.
• Workflow YAML parse-checked (actionlint unavailable locally); the workflow edit is header comments + the ref: main pin, with the #278 redact/upload forensics steps byte-identical.

Part of toon-protocol/toon-meta#270
Part of toon-protocol/toon-meta#275

🤖 Generated with Claude Code