From 2858240bd0f127b022ceca8a46d404ab8df60354 Mon Sep 17 00:00:00 2001 From: Kent Date: Sun, 19 Apr 2026 23:20:10 +0800 Subject: [PATCH] first-officer: add Step 5 output-validation gate to Completion and Gates 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. --- .../first-officer/references/first-officer-shared-core.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/skills/first-officer/references/first-officer-shared-core.md b/skills/first-officer/references/first-officer-shared-core.md index a4f668b12..bf6194dfa 100644 --- a/skills/first-officer/references/first-officer-shared-core.md +++ b/skills/first-officer/references/first-officer-shared-core.md @@ -91,6 +91,14 @@ When a worker completes: 2. Review it against the checklist. Every dispatched item must be represented as DONE, SKIPPED, or FAILED. 3. If items are missing, send the worker back once to repair the report. 4. Check whether the completed stage is gated. +5. **Validate stage output exists (pre-transition gate).** For every non-initial, non-terminal stage that has a `skill:` property in the README stage definition, grep the entity file for `## {Stage_Name} Output` (where `Stage_Name` is the stage name with first letter capitalized — e.g., `## Sharp Output`, `## Plan Output`, `## Execute Output`). This follows the entity-body-schema convention: each stage writes up to 3 blocks (`Output`, `Report`, `UAT`) with headers `## {Stage} {Block}`. + + - **If the output section is missing or empty** (header absent, or header present but no content before the next `##`): + - Do NOT advance the entity. Keep status at the completed stage. + - Emit captain-visible diagnostic: `"⚠️ {slug}: {stage} worker completed but ## {Stage_Name} Output is missing from entity file. Stage Report exists but output was not written. Blocking advancement — re-dispatch or escalate."` + - Re-dispatch the worker once (same stage, same entity) with instruction: `"Your ## {Stage_Name} Output section is missing from the entity file. Re-read your skill and write the required output sections before sending completion."` If the re-dispatch also fails to produce the output section → escalate to captain and halt. + - **If the output section exists and has content** → proceed normally. + - **Skip this check** for stages without `skill:` (e.g., `draft`, `done`) — these have no agent-produced output. The checklist review produces an explicit count summary: - `{N} done, {N} skipped, {N} failed`