Review Gate (Parallel roles → Lead note → Worker fix loop)
This gate is designed for pi-async-subagents:
- •role reviewers run in parallel (chain parallel step)
- •lead reviewer aggregates and writes the authoritative
tk add-note - •the caller drives the fix loop by delegating fixes to
os-tk-worker
Inputs
- •ticket-id or alias
Resolve skill dir (for scripts)
bash
SKILL_DIR=".pi/skills/os-tk-review-gate" if [[ ! -d "$SKILL_DIR" ]]; then SKILL_DIR="pi/skills/os-tk-review-gate"; fi
Load config
- •
eval "$(bash "$SKILL_DIR/scripts/load-config.sh")"→CONFIG,MAX_ITERS,MAIN_BRANCH
Resolve ticket id
- •
TICKET_ID="$(bash "$SKILL_DIR/scripts/resolve-ticket-id.sh" "$1")"
Round loop
For round N=1..$MAX_ITERS:
1) Canonical diff_hash
- •
eval "$(bash "$SKILL_DIR/scripts/canonical-diff-hash.sh")"→DIFF_HASH,BASE_REF,MERGE_BASE_SHA,HEAD_SHA
Diffstat for reviewer context:
- •
DIFFSTAT="$(git diff --no-color --no-ext-diff --no-renames --stat "$MERGE_BASE_SHA...HEAD")"
2) Run role reviewers + lead aggregation (subagent chain)
Use the subagent tool with a parallel-in-chain fan-out/fan-in.
js
subagent({
"agentScope": "both",
"async": false,
"chain": [
{
"parallel": [
{
"agent": "os-tk-reviewer-role-bug-footgun",
"task": "Review ticket ${TICKET_ID} for bugs/footguns. Use fresh eyes.\n\nContext:\n- diff_hash: ${DIFF_HASH}\n- base_ref: ${BASE_REF}\n- merge_base_sha: ${MERGE_BASE_SHA}\n- head_sha: ${HEAD_SHA}\n\nDiffstat:\n${DIFFSTAT}\n\nIf needed, inspect the actual diff via: git diff ${MERGE_BASE_SHA}...HEAD"
},
{
"agent": "os-tk-reviewer-role-spec-audit",
"task": "Spec-audit ticket ${TICKET_ID}. Verify implementation matches OpenSpec proposal/tasks + acceptance criteria.\n\nContext:\n- diff_hash: ${DIFF_HASH}\n- merge_base_sha: ${MERGE_BASE_SHA}\n- head_sha: ${HEAD_SHA}\n\nDiffstat:\n${DIFFSTAT}\n\nIf needed: determine change-id via `tk show ${TICKET_ID}` (external_ref openspec:<change-id>) and read openspec/changes/<change-id>/*. Then inspect diff via: git diff ${MERGE_BASE_SHA}...HEAD"
},
{
"agent": "os-tk-reviewer-role-generalist",
"task": "General quality review for ticket ${TICKET_ID}. Focus on readability, consistency, tests, minimal diff.\n\nContext:\n- diff_hash: ${DIFF_HASH}\n- merge_base_sha: ${MERGE_BASE_SHA}\n- head_sha: ${HEAD_SHA}\n\nDiffstat:\n${DIFFSTAT}\n\nInspect diff if needed via: git diff ${MERGE_BASE_SHA}...HEAD"
},
{
"agent": "os-tk-reviewer-role-second-opinion",
"task": "Second-opinion review for ticket ${TICKET_ID}. Look for hidden regressions, perf, assumptions.\n\nContext:\n- diff_hash: ${DIFF_HASH}\n- merge_base_sha: ${MERGE_BASE_SHA}\n- head_sha: ${HEAD_SHA}\n\nDiffstat:\n${DIFFSTAT}\n\nInspect diff if needed via: git diff ${MERGE_BASE_SHA}...HEAD"
}
],
"concurrency": 4,
"failFast": false
},
{
"agent": "os-tk-reviewer-lead",
"task": "Aggregate the role reviewer outputs below, decide verdict, and write the authoritative tk note.\n\nTicket: ${TICKET_ID}\nRound: ${N}/${MAX_ITERS}\n\nMetadata (MUST include in note):\n- diff_hash: ${DIFF_HASH}\n- base_ref: ${BASE_REF}\n- merge_base_sha: ${MERGE_BASE_SHA}\n- head_sha: ${HEAD_SHA}\n\nRole outputs:\n{previous}\n\nNow: (1) dedupe issues, (2) choose verdict, (3) produce ordered fix list, (4) run `tk add-note ${TICKET_ID} \"...\"` with a single authoritative note that includes the <verdict> tag and the metadata lines above."
}
]
})
3) Decide next action (based on tk note)
After the chain completes, check whether we have SHIP for the current diff_hash.
Minimal check (same semantics as /os-tk-done gate):
- •
NOTE="$(tk show "$TICKET_ID" | awk 'BEGIN{p=0} /^notes:/{p=1} p{print}')" - •SHIP if NOTE contains both:
- •
<verdict>SHIP</verdict> - •
diff_hash: $DIFF_HASH
- •
Always print a short summary for the user (from the most recent note), then:
- •If SHIP: STOP (gate passed).
Suggested summary extraction:
- •
echo "Review gate note (tail):" - •
echo "$NOTE" | tail -80 | grep -E "<verdict>|diff_hash:|base_ref:|merge_base_sha:|head_sha:" || true
4) If not SHIP: delegate fixes to worker
Spawn the worker model (same ticket branch/worktree):
js
subagent({
"agent":"os-tk-worker",
"task":"Fix the issues from the latest /os-tk-review note on ticket ${TICKET_ID}.\n\nInstructions:\n- Run `tk show ${TICKET_ID}` and find the most recent note with <verdict>NEEDS_WORK</verdict> or <verdict>MAJOR_RETHINK</verdict>.\n- Implement the consolidated fix list.\n- Run tests/verification.\n- Commit fixes (one logical change per commit).\n- Report evidence (commands run).",
"agentScope":"both",
"async": false
})
Then continue to next round.
Failure
If max iterations reached without SHIP:
- •STOP and report failure.
- •Do NOT close the ticket.