Skip to content

first-officer: add Step 5 output-validation gate to Completion and Gates#144

Open
iamcxa wants to merge 1 commit intoclkao:mainfrom
iamcxa:feat/fo-output-validation-gate
Open

first-officer: add Step 5 output-validation gate to Completion and Gates#144
iamcxa wants to merge 1 commit intoclkao:mainfrom
iamcxa:feat/fo-output-validation-gate

Conversation

@iamcxa
Copy link
Copy Markdown
Contributor

@iamcxa iamcxa commented Apr 20, 2026

Problem

The FO advances entities through the pipeline based on ## Stage Report existence alone, without validating that the completed stage produced its expected ## {Stage_Name} Output section. When a worker hits its checklist but fails to write the Output section (context pressure, early-exit paths, circuit breakers), the entity silently advances to the next stage with no usable output. Downstream stages then discover the missing input and return BLOCKED — but the entity status has already moved forward, leaving it stranded mid-pipeline.

Fix

Add Step 5 to the Completion and Gates flow in first-officer-shared-core.md:

  • For every non-initial, non-terminal stage with a skill: property, grep the entity file for ## {Stage_Name} Output before advancing
  • Missing/empty Output → re-dispatch the same worker once with a pointed instruction to write the missing sections
  • Second failure → escalate to captain with a visible diagnostic, halt advancement
  • Skip the check for stages without skill: (draft, done)

Evidence

The bug was observed on a ship-flow workflow (spacedock-ui project) where three entities advanced past their stages without corresponding Output sections:

  • Entity 035 war-room-scroll-fix — status: plan, no ## Plan Output
  • Entity 038 design-system-v2 — status: execute, no ## Plan Output
  • Entity 029 upstream-contributions-scan — status: verify, no ## Plan Output

Paired fix on the skill side (each stage skill mandates writing Output before early-exit) lives in the downstream workflow repo (spacedock-ui). This FO change is the generic backstop that applies to every spacedock-commissioned workflow.

Convention

Follows the entity-body-schema convention: "Each stage writes up to 3 standard blocks: Output, Report, UAT with headers ## {Stage} {Block}."

Testing

  • make test-static passes: 454 passed, 22 deselected, 10 subtests passed in 24.56s
  • Touches only skills/first-officer/references/first-officer-shared-core.md (+8 lines)
  • No runtime adapter changes needed — both claude-first-officer-runtime.md and codex-first-officer-runtime.md describe HOW to detect worker completion (Agent(), wait_agent) but don't duplicate the Step 1-4 checklist prose, so Step 5 addition to the shared core is sufficient.

Stats

  • 1 commit
  • 1 file changed
  • 8 insertions, 0 deletions

Pipeline integrity fix. The FO was advancing entities through the
pipeline based on Stage Report existence alone, without validating
that the completed stage actually produced its expected Output
section in the entity file. When a worker completed (hit its
checklist) but failed to write ## {Stage_Name} Output due to
context pressure, early-exit paths, or circuit breakers, the entity
would silently advance to the next stage with no usable output.
Downstream stages like execute or verify would then discover the
missing input and return BLOCKED, but the entity status had already
moved forward, leaving it stranded.

Step 5 closes the gap by greping the entity file for
## {Stage_Name} Output before advancing any stage that has a skill
property. Missing or empty Output section triggers one re-dispatch
of the same worker with a pointed instruction to write the missing
sections; a second failure escalates to the captain with a visible
diagnostic and halts advancement.

Evidence for the bug came from a ship-flow workflow (spacedock-ui)
where entities 035, 038, 029 advanced past plan or execute without
Plan Output or Execute Output sections. Paired fix on the skill
side (write output before early-exit) lives in the downstream
workflow repo; this FO change is the generic backstop that applies
to every spacedock-commissioned workflow.

Convention referenced: entity-body-schema "Each stage writes up to
3 standard blocks: Output, Report, UAT with headers ## {Stage}
{Block}". draft and done stages (no skill property) are skipped.
@clkao
Copy link
Copy Markdown
Owner

clkao commented Apr 20, 2026

I am curious why limit the stage output verification only when skill is defined?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants