Problem
Workflow nodes currently infer agent outcomes from ad hoc Markdown files and prose conventions. For example, implement_review expects .forge/review-plan.md and must distinguish actionable feedback from a valid no-op. Checking only file existence can fail open, while parsing exact sentinel strings or Markdown headings is brittle and overly restrictive.
AISOS-2157 exposed this when the analysis agent described the correct plan in its final response but stopped before writing the required artifact. Forge interpreted the missing plan as no actionable items and silently returned to the human-review gate.
Proposed direction
Introduce a shared, machine-readable handoff contract for agent-driven workflow nodes, while retaining Markdown artifacts for human readability. A typed artifact should express an explicit outcome such as actionable, no_action, contested, or failed, plus structured items and validation errors.
Scope
- inventory agent-produced artifacts across all workflows
- define a versioned JSON schema or typed model for handoff outcomes
- update prompts and skills to emit the structured artifact
- validate artifacts before workflow routing
- fail closed on missing, malformed, or internally inconsistent output
- retain human-readable Markdown where useful
- add contract and workflow regression tests
- document migration and backward-compatibility behavior
Acceptance criteria
- workflow routing does not depend on exact prose or Markdown headings
- missing or malformed required artifacts cannot be treated as successful no-ops
- explicit no-action outcomes are distinguishable from analysis failures
- the contract is reusable across review, planning, triage, RCA, and other agent-driven nodes
- tests cover actionable, no-action, contested, missing, malformed, and incompatible-version outcomes
Context
PR #149 explored a narrow fail-closed fix for implement_review, but was closed because robust handling requires a broader contract rather than increasingly strict Markdown parsing.
Problem
Workflow nodes currently infer agent outcomes from ad hoc Markdown files and prose conventions. For example, implement_review expects .forge/review-plan.md and must distinguish actionable feedback from a valid no-op. Checking only file existence can fail open, while parsing exact sentinel strings or Markdown headings is brittle and overly restrictive.
AISOS-2157 exposed this when the analysis agent described the correct plan in its final response but stopped before writing the required artifact. Forge interpreted the missing plan as no actionable items and silently returned to the human-review gate.
Proposed direction
Introduce a shared, machine-readable handoff contract for agent-driven workflow nodes, while retaining Markdown artifacts for human readability. A typed artifact should express an explicit outcome such as actionable, no_action, contested, or failed, plus structured items and validation errors.
Scope
Acceptance criteria
Context
PR #149 explored a narrow fail-closed fix for implement_review, but was closed because robust handling requires a broader contract rather than increasingly strict Markdown parsing.