session: pass preflight gate results to coder prompt to skip redundant Quick Triage

[mickume]

Problem

The coder archetype's "Quick Triage" section (in coder.md) mandates that the agent inspect tasks.json checkbox states and run make test at session start to determine if work is needed. However, the orchestrator's preflight check (run_preflight() in preflight.py) already performs these exact same checks — it reads checkbox states from the DB/file, checks for active findings, and runs make test — before deciding whether to launch the coder session at all. When the orchestrator decides to LAUNCH, none of its findings are passed forward to the coder, which then redundantly re-performs the same checks, wasting 2-5 tool calls and 30-90 seconds of wall-clock time per session.

Root Cause Analysis

Confidence: Confirmed

The orchestrator's preflight check runs in DispatchManager._run_preflight() (packages/agentfox/agentfox/engine/dispatch.py, lines 626-674). It calls run_preflight() (packages/agentfox/agentfox/engine/preflight.py, lines 147-184), which evaluates three gates in order:

1. is_task_group_done() (line 160) — checks whether all subtask checkboxes are marked complete (DB-first with file fallback)
2. has_active_critical_findings() (line 163) — queries DuckDB for unresolved critical/major review findings
3. do_tests_pass() (line 171) — runs make test with a 300-second timeout

When preflight returns PreflightVerdict.LAUNCH, the dispatcher proceeds to launch the coder session (dispatch.py, line 584-586). However, the preflight results — specifically which gate triggered the LAUNCH — are not communicated to the coder. The prepare_launch() return tuple (line 480) contains (verdict, attempt, previous_error, archetype, instances, mode) but no preflight state.

The coder then enters "Quick Triage" (coder.md, lines 18-43):

1. Lines 22-25: "Inspect checkbox states in tasks.json for your assigned task group only" — duplicates is_task_group_done() from preflight
2. Lines 27-28: "If all subtasks are [x], run make test" — duplicates do_tests_pass() from preflight

The build_task_prompt() function (session/prompt.py, lines 97-151) constructs a simple text prompt ("Implement task group N from specification X") without including any preflight state. There is no mechanism to pass the orchestrator's knowledge forward.

Related Instances

The verifier archetype also runs test suites as part of its verification, but this is not redundant because the verifier runs after the coder has made changes, verifying the post-implementation state — a fundamentally different check.

Affected Files

• packages/agentfox/agentfox/engine/dispatch.py — _run_preflight() and prepare_launch() do not surface preflight gate results
• packages/agentfox/agentfox/session/prompt.py — build_task_prompt() does not accept or include preflight state
• packages/agentfox/agentfox/_templates/profiles/coder.md — "Quick Triage" section mandates redundant checks

Suggested Fix

Approach:

Extend the task prompt to include a brief preflight summary so the coder can skip to implementation.

1. Capture preflight gate results. When run_preflight() returns LAUNCH, record which gate triggered it and relevant state:

   • checkbox_state: "N/M subtasks complete" or "all complete"
   • findings_state: "N active critical/major findings" or "none"
   • tests_state: "pass" / "fail" / "not run" (tests are only run when checkboxes are all done)

2. Thread preflight state through dispatch. Add the preflight summary to prepare_launch()'s return tuple or to the SessionRecord so the session lifecycle can access it.

3. Include in task prompt. Extend build_task_prompt() to accept an optional preflight_summary string and append it:

   ## Preflight State (from orchestrator)
   - Subtask checkboxes: 2/6 complete
   - Active findings: none
   - Test baseline: not run (incomplete group)
   
   Skip Quick Triage — proceed directly to implementation.
   

4. Simplify Quick Triage. Update coder.md to make the Quick Triage section conditional: "If a ## Preflight State section is present in your context, skip Quick Triage entirely and proceed to Task Group Routing."

Files to modify:

• packages/agentfox/agentfox/engine/preflight.py — return structured result from run_preflight() instead of bare enum
• packages/agentfox/agentfox/engine/dispatch.py — thread preflight result to session lifecycle
• packages/agentfox/agentfox/session/prompt.py — accept and render preflight state in build_task_prompt()
• packages/agentfox/agentfox/_templates/profiles/coder.md — make Quick Triage conditional on preflight presence

Risks:

• If the preflight state is stale by the time the coder starts (e.g., another process modified the worktree), the coder might skip a needed check. Mitigate by always running tests before committing (already required by the coder profile's "Verify" section).
• The coder_fix.md (nightshift fix mode) does not use the orchestrator's preflight path — this change only affects the af code pipeline. No impact on nightshift.

Acceptance Criteria

• AC-1: Given a coder session launched after preflight, when build_task_prompt() is called, then the prompt includes a ## Preflight State section with checkbox completion count, findings count, and test baseline status.
• AC-2: Given a coder session with a ## Preflight State section showing incomplete subtasks and no findings, when the coder reads the prompt, then it skips the Quick Triage inspection of tasks.json and make test and proceeds directly to Task Group Routing.
• AC-3: Given a coder session without a ## Preflight State section (e.g., retry attempt or non-orchestrated run), the Quick Triage section remains active as a fallback.
• AC-4: run_preflight() returns a structured result object (not just a bare enum) containing the gate states, without changing the existing SKIP/LAUNCH semantics.

Severity

Low — This is a performance optimization that saves 2-5 tool calls and 30-90 seconds per coder session. No correctness impact — the coder still reaches the right outcome, just more slowly.

---

Analysis by af-issue.

[mickume]

Analysis

Auto-generated by af-fix. Reviewing issue context and codebase.

Diagnosis

Classification: Feature (optimization)

Problem:
run_preflight() in preflight.py evaluates three gates (checkbox state, active findings, test baseline) before deciding whether to launch a coder session. When it returns LAUNCH, the gate results are discarded — only the bare PreflightVerdict enum is returned. The coder then redundantly re-performs these same checks via the "Quick Triage" section in coder.md, wasting 2-5 tool calls per session.

The threading path is: run_preflight() → _run_preflight() (dispatch.py) → prepare_launch() → dispatch → SerialRunner.execute() → invoke_runner() → NodeSessionRunner.execute() → _build_prompts() → build_task_prompt().

Planned Fix

Approach:

1. Add a PreflightResult dataclass to preflight.py containing verdict, checkboxes_done, has_findings, and tests_passed (nullable for "not run"). Update run_preflight() to return it. Preserve backward compatibility by keeping the .verdict attribute comparable to PreflightVerdict.

2. In _run_preflight() (dispatch.py), capture the result, format a human-readable summary string, and store it in a new self._preflight_summaries: dict[str, str] on the DispatchManager. In prepare_launch(), include the summary as a 7th element in the return tuple.

3. Thread the summary through the dispatch → runner → session lifecycle chain. build_task_prompt() accepts an optional preflight_summary parameter and appends a ## Preflight State section when present.

4. Update coder.md Quick Triage to skip when preflight state is present.

Files to modify:

• packages/agentfox/agentfox/engine/preflight.py — add PreflightResult, update run_preflight()
• packages/agentfox/agentfox/engine/dispatch.py — store/thread preflight summaries
• packages/agentfox/agentfox/engine/state.py — thread preflight_summary through invoke_runner()
• packages/agentfox/agentfox/engine/session_lifecycle.py — accept and pass preflight summary
• packages/agentfox/agentfox/session/prompt.py — render preflight section in build_task_prompt()
• packages/agentfox/agentfox/_templates/profiles/coder.md — conditional Quick Triage
• Test files for all changed modules

---

Analysis by af-fix. Implementation follows.

[mickume]

Fix Implemented

Auto-generated by af-fix.

Summary

Added structured PreflightResult to capture gate states from preflight checks, threaded the formatted summary through the dispatch chain to the coder's task prompt, and made Quick Triage in coder.md conditional on the presence of a ## Preflight State section. Coders now skip redundant checkbox inspection and make test when the orchestrator has already verified these gates.

Changes

File	Change
packages/agentfox/agentfox/engine/preflight.py	Added PreflightResult dataclass with format_summary(); run_preflight() returns structured result
packages/agentfox/agentfox/engine/dispatch.py	Store preflight summaries in _preflight_summaries dict; include in prepare_launch() 7-tuple; set on runner instance
packages/agentfox/agentfox/engine/parallel.py	Thread preflight_summary through execute_one() and _execute_session()
packages/agentfox/agentfox/engine/session_lifecycle.py	Read _preflight_summary attribute in _build_prompts()
packages/agentfox/agentfox/session/prompt.py	build_task_prompt() accepts and appends preflight_summary
packages/agentfox/agentfox/_templates/profiles/coder.md	Quick Triage skipped when ## Preflight State section present
packages/agentfox/tests/unit/engine/test_preflight.py	Updated for PreflightResult, added format_summary test
packages/agentfox/tests/unit/session/test_prompt.py	3 tests for preflight summary in task prompt
packages/agentfox/tests/unit/engine/test_parallel_drain.py	Updated mock tuples to 7-element format

Tests

• test_preflight.py: All existing tests updated to use result.verdict; new test for format_summary()
• test_prompt.py: 3 new tests verifying preflight summary inclusion, omission, and non-coder behavior

Verification

• All existing tests pass: ✅ (7074 → 7078)
• New tests pass: ✅ (4 new)
• Linter / formatter: ✅ (all changed files clean; 2 pre-existing warnings in untouched code)
• No regressions: ✅

Branch

feature/issue-718-preflight-to-prompt — ready to merge into main.

---

Fix by af-fix. Ready for review.