ADF PR Gate Result Contract Handover

Generated: 2026-06-09 14:48 BST

Progress Summary

Tasks Completed This Session

• Implemented canonical PrGateResult handling for ADF PR fan-out gates.
• Added fail-closed handling for missing, malformed, stale, or invalid adf:gate-result blocks.
• Added drain-log backed parsing so reconciliation can read full producer output instead of only in-memory event samples.
• Added orchestrator-owned bounded canonical failure envelopes for invalid producer output.
• Added PR gate timeout fail-closed handling with a 300 second wall-clock cap for PR gate agents.
• Pushed implementation branch task/2301-pr-gate-result-contract to Gitea.
• Created PR #2318: Fix #2301: add PrGateResult contract for PR fan-out gates.
• Deployed ADF from latest branch head ca4a6f2ad07a55441f07d5e390b9ce9f8c7beabd on bigbox.
• Created binary backups before deployment:
  • /usr/local/bin/adf.bak-20260609-1425
  • /opt/ai-dark-factory/adf.bak-20260609-1425
• Restarted adf-orchestrator.service and verified it is active using /usr/local/bin/adf orchestrator.toml.
• Ran synthetic PR webhooks for PR #2318 and verified live terminal commit statuses.
• Updated Gitea PR and issues with evidence:
  • PR #2318 comment 38973
  • Issue #2301 comments 38974 and 38978
  • Follow-up issue #2334 created for producer-agent output quality.

Current Implementation State

• Branch: task/2301-pr-gate-result-contract in isolated worktree /var/folders/rb/l4_6j2nx0lnfhysk974ldpg40000gn/T/opencode/adf-2301.
• Latest implementation commit before this handover: ca4a6f2ad fix(orchestrator): fail closed on PR gate timeouts Refs #2301.
• PR #2318 is open and points to the latest pushed branch head.
• ADF on bigbox is deployed from ca4a6f2ad and active.
• Current head ca4a6f2ad07a55441f07d5e390b9ce9f8c7beabd has terminal fail-closed gate statuses:
  • adf/validation: failure, agent exceeded 300s PR gate wall-clock limit
  • adf/verification: failure, agent exceeded 300s PR gate wall-clock limit
  • adf/pr-reviewer: failure, agent exceeded 300s PR gate wall-clock limit
• Canonical timeout failure comments were posted and parsed successfully:
  • 38970: pr-verifier, adf/verification, status=fail
  • 38971: pr-reviewer, adf/pr-reviewer, status=fail
  • 38972: pr-validator, adf/validation, status=fail

What Is Working

• Branch protection no longer remains stuck on pending when PR gate producers emit malformed output.
• Malformed or missing producer output is converted into bounded canonical failure comments.
• Valid canonical adf:gate-result blocks are parsed and used to determine terminal commit statuses.
• PR gate agents that run too long are killed and failed closed after 300 seconds.
• Status descriptions and PR comments are tied to the expected PR number, context, agent name, and head SHA.
• Local verification and pre-commit hooks passed before the latest implementation commit.

What Is Blocked Or Remaining

• Producer agents still emit excessive or malformed output and can run until the 300 second safety cap.
• Useful review/validation/verification reports are not yet produced reliably by pr-reviewer, pr-validator, or pr-verifier.
• Follow-up issue #2334 tracks producer quality: make the PR gate producers emit useful bounded reports with valid canonical adf:gate-result blocks.
• Native CI status checks unrelated to ADF gates may remain pending or blocked according to branch protection and runner state.

Technical Context

Implementation Worktree

Path: /var/folders/rb/l4_6j2nx0lnfhysk974ldpg40000gn/T/opencode/adf-2301

# Current branch
task/2301-pr-gate-result-contract

# Recent commits before this handover
ca4a6f2ad fix(orchestrator): fail closed on PR gate timeouts Refs #2301
88b008a6d fix(orchestrator): synthesise canonical failed PR gate results Refs #2301
073ede3a3 fix(orchestrator): read PR gate results from drain logs Refs #2301
0e072ee74 test(orchestrator): harden PR gate result parsing Refs #2301
b71332dde feat(orchestrator): add PrGateResult contract for PR fan-out gates Refs #2301

# Modified files before this handover
?? .docs/orchestrator-legacy-2301/patch-terraphim-toml.py

The untracked .docs/orchestrator-legacy-2301/patch-terraphim-toml.py file was pre-existing and intentionally left untouched.

Main Workspace

Path: /Users/alex/projects/terraphim/terraphim-ai

# Current branch
task/2185-runner-reliability

# Recent commits
445319bdd fix(gitea-runner): force PickTask + release skipped tasks (#2185)
10159d4e6 Merge pull request 'docs(adf): document the adf binary rebuild/redeploy procedure' (#2201) from task/2175-adf-deploy-docs into main
2d4efe8df docs(adf): document the adf binary rebuild/redeploy procedure
46b414dec Merge pull request 'test: verify verdict agents post statuses (pre-opt-in e2e)' (#2123) from test/verdict-agents-e2e into main
423257f94 test: verdict-agents e2e probe

# Modified files
?? .docs/adf/2301/
?? .docs/design-2185-native-runner-reliability.md
?? .docs/design-adf-flow-remediation.md
?? .docs/design-adf-pr-gate-result-redesign.md
?? .docs/plan-2079-runner-scaling.md
?? .docs/research-2185-native-runner-reliability.md
?? .docs/research-adf-flow-remediation.md
?? .docs/research-adf-pr-gate-result-redesign.md
?? .terraphim/flow-state/flow-adf-useful-work-proof-2bbd80a7-e1f9-42d9-ba9a-8f10667f472a.json
?? .terraphim/flow-state/flow-adf-worktree-isolation-review-41235e82-249c-44ac-88a4-0df1557a9c5f.json
?? .terraphim/flow-state/flow-test-reiteration-44b6d87d-152b-4d4b-9359-795efb518453.json
?? 2026-06-06-191636-this-session-is-being-continued-from-a-previous-c.txt
?? docs/handovers/2026-06-04-adf-gate-hardening-repolocal-agents.md
?? docs/handovers/2026-06-05-adf-repolocal-rollout-doc-churn-runner3.md
?? implementation-plan-2301.md
?? latest.txt
?? latest2.txt

These main-workspace files were not part of the PR gate implementation changes in the isolated worktree.

Verification Evidence

• cargo test -p terraphim_orchestrator --lib reconcile_impl::tests: pass.
• cargo test -p terraphim_orchestrator --lib pr_gate_result: pass.
• cargo clippy -p terraphim_orchestrator --all-targets: pass.
• cargo llvm-cov -p terraphim_orchestrator --lib --summary-only -- pr_gate_result reconcile_impl::tests: 28 focused tests passed.
• ubs --only=rust --diff .: 0 critical issues.
• Commit hook passed format, cargo check, clippy, cargo build, full Rust tests, and UBS critical gate.

Next Recommended Steps

• Review and merge PR #2318 once maintainers are satisfied with fail-closed behaviour.
• Work issue #2334 next to fix producer agents so they emit useful reports before the timeout cap.
• Keep the 300 second PR gate timeout as a safety backstop, not as the normal completion path.
• Avoid re-enabling retired ADF bash build-runner; native Gitea CI remains the build path.