vinix24/vnx-orchestration/orchestrate

T0 Orchestrator — Detailed Workflow Reference

This is the extended reference for the headless T0 orchestrator. The condensed identity is in agents/orchestrator/CLAUDE.md.

1. Receipt Review Protocol

Claim Verification (minimum 3 per receipt)

For each worker receipt, spot-check at least 3 specific claims:

# 1. Claimed file was modified
git log --oneline -1 -- <file>
 
# 2. Specific fix is present
grep -r "expected_pattern" <file>
 
# 3. Old problem no longer exists
grep -r "old_pattern" src/  # Must return 0 matches

Acceptance criteria:

• Automated test pass counts are acceptable evidence
• Code change descriptions are NOT acceptable without code verification
• Vague claims ("improved performance", "fixed bug") require concrete evidence
• If ANY claim fails verification: reject receipt, do not close items

Quality Advisory Interpretation

2. Open Items Lifecycle

Inspect

python3 scripts/open_items_manager.py digest
python3 scripts/open_items_manager.py list --status open

Resolve (only with evidence)

# Verify fix exists before closing
grep -r "old_pattern" src/        # Must return 0
grep -r "new_pattern" src/        # Must return expected matches
git log --oneline -1 -- <file>    # Must show recent commit
 
# Then close
python3 scripts/open_items_manager.py close OI-XXX --reason "evidence: ..."
python3 scripts/open_items_manager.py defer OI-XXX --reason "non-blocking"
python3 scripts/open_items_manager.py wontfix OI-XXX --reason "out of scope"

Create new item

python3 scripts/open_items_manager.py add \
  --title "<short risk title>" \
  --severity warn \
  --pr-id PR-X \
  --description "<what was discovered>"

3. PR Queue Lifecycle

Read state

python3 scripts/pr_queue_manager.py status
python3 scripts/pr_queue_manager.py list

Staging-first dispatch

python3 scripts/pr_queue_manager.py staging-list
python3 scripts/pr_queue_manager.py show <dispatch-id>
python3 scripts/pr_queue_manager.py promote <dispatch-id>
python3 scripts/pr_queue_manager.py reject <dispatch-id> --reason "..."

Complete PR

python3 scripts/pr_queue_manager.py complete PR-X

Only after all blocker/warn obligations are satisfied and required gates pass.

4. Review Gate Verification

Before closing any PR with a review stack:

python3 scripts/review_gate_manager.py status --pr <number> --json

Verify ALL of these:

1. Request record exists in .vnx-data/state/review_gates/requests/
2. Result record exists in .vnx-data/state/review_gates/results/
3. contract_hash is non-empty and matches active contract
4. report_path is non-empty
5. Normalized markdown report exists under $VNX_DATA_DIR/unified_reports/
6. No unresolved blocking findings carried into PR completion
7. Gate is not stuck in queued with no completion evidence

Closure blockers:

• Request exists but execution never started
• Gate result with empty contract_hash
• Gate result with empty report_path
• Ad hoc shell output exists but no normalized report/result
• Structured JSON and normalized report content disagree (treat as evidence failure)

5. Dispatch Format

Every dispatch must include these headers:

Plus: Workflow, Context, and explicit success criteria.

Validate role names before dispatch:

python3 scripts/validate_skill.py --list

6. Headless T1 Dispatch

T1 is a headless backend-developer. Dispatch via:

python3 scripts/lib/subprocess_dispatch.py \
  --terminal-id T1 \
  --dispatch-id <id> \
  --model sonnet \
  --instruction "<task>"

T1 receipts arrive in t0_receipts.ndjson with source="subprocess".

7. Decision Output Rules

When not dispatching, provide explicit status:

• WAIT: explain exact blocker (terminal busy, queue active, dependency unmet)
• ESCALATE: explain ambiguity and propose options
• APPROVE/PROCEED: show why all criteria are met

Final rule: if evidence is weak or contradictory, do not approve by default.