iso-postflight

@agent-pattern-labs/iso-postflight

iso-postflight answers: is this dispatched agent workflow settled, and what is the next safe action?

It is a deterministic, local CLI/library for reconciling a dispatch plan with observed outcomes, artifact evidence, and post-run steps. It does not call a model, does not run an MCP server, and does not add prompt or tool-schema tokens.

Use it after iso-preflight or any other planner has emitted bounded rounds:

• detect in-flight work that should not be re-dispatched
• detect missing outcomes for already-dispatched candidates
• require output artifacts such as tracker TSVs before a round is complete
• identify failed outcomes that need replacement candidates
• decide when to dispatch the next round
• require post-steps such as merge and verify before declaring the workflow complete

Install

npm install @agent-pattern-labs/iso-postflight

CLI

iso-postflight status --config postflight.json --plan plan.json --outcomes outcomes.json
iso-postflight check --config postflight.json --plan plan.json --outcomes outcomes.json
iso-postflight explain --config postflight.json

Use --workflow <name> when a config contains multiple workflows, and --json for machine-readable output. check exits 1 unless the workflow is fully complete.

JobForge-style usage

iso-postflight status \
  --config examples/jobforge-postflight.json \
  --plan examples/jobforge-plan.json \
  --outcomes examples/jobforge-outcomes-partial.json

Example output:

iso-postflight: STATUS workflow=jobforge.apply
state: ready-for-next-round
next: dispatch-round - Dispatch round 2.
rounds: 1 complete, 1 not-started
outcomes: 2 succeeded, 0 failed, 0 skipped, 0 replacement, 0 in-flight, 0 missing, 0 blocked
round details:
  1. complete: job-1=succeeded, job-2=succeeded
  2. not-started: job-3=not-started
post:
  - merge: pending
  - verify: pending

Config shape

{
  "version": 1,
  "workflows": [
    {
      "name": "jobforge.apply",
      "successStatuses": ["APPLIED"],
      "failureStatuses": ["APPLY FAILED"],
      "skipStatuses": ["SKIP", "Discarded"],
      "inFlightStatuses": ["running", "in-flight"],
      "replacementStatuses": ["APPLY FAILED"],
      "requiredArtifacts": [
        {
          "id": "tracker-tsv",
          "label": "Tracker TSV outcome",
          "statuses": ["APPLIED", "APPLY FAILED", "SKIP", "Discarded"]
        }
      ],
      "postSteps": [
        { "id": "merge", "label": "Merge tracker TSV outcomes", "command": "npx job-forge merge" },
        { "id": "verify", "label": "Verify tracker integrity", "command": "npx job-forge verify" }
      ]
    }
  ]
}

Plan shape

The plan can be the JSON output from iso-preflight plan --json, or this minimal shape:

{
  "workflow": { "name": "jobforge.apply" },
  "rounds": [
    { "index": 1, "candidates": [{ "id": "job-1" }, { "id": "job-2" }] },
    { "index": 2, "candidates": [{ "id": "job-3" }] }
  ]
}

Candidate, round, outcome, dispatch, artifact, and step IDs must be unique and candidate observations must refer to IDs declared by the selected plan. Required artifact IDs are requirements, not an allowlist: outcomes may include additional artifact evidence. Workflow post-steps always remain required; plan post-steps can override matching presentation details or add supplemental steps, but cannot remove workflow requirements. Step observations must refer to one of those effective workflow or plan steps.

Success, failure, skip, and in-flight status categories are compared after trimming and case-folding and must not overlap. Replacement statuses may overlap failure statuses intentionally—replacement is checked first—but cannot overlap success, skip, or in-flight statuses.

Outcome shape

{
  "dispatches": [
    { "candidateId": "job-1", "source": "trace:root" }
  ],
  "outcomes": [
    {
      "candidateId": "job-1",
      "status": "APPLIED",
      "source": "batch/tracker-additions/001-acme.tsv",
      "artifacts": [
        { "id": "tracker-tsv", "status": "present", "source": "batch/tracker-additions/001-acme.tsv" }
      ]
    }
  ],
  "steps": [
    { "id": "merge", "status": "pass", "source": "npx job-forge merge" }
  ]
}

Library

import {
  formatPostflightResult,
  loadPostflightConfig,
  settlePostflight,
} from "@agent-pattern-labs/iso-postflight";

const result = settlePostflight(config, plan, outcomes);
console.log(formatPostflightResult(result));
if (!result.ok) process.exit(1);

Boundaries

iso-postflight does not dispatch agents, poll task systems, parse transcripts, or merge tracker files. Domain code should materialize observations from authoritative sources such as trace exports, TSV files, ledgers, or workflow records, then feed those observations into iso-postflight.

Related packages:

• iso-preflight checks safety before dispatch.
• iso-orchestrator owns durable execution and fan-out primitives.
• iso-ledger stores durable workflow events.
• iso-trace parses production transcripts.
• iso-guard audits policy violations after a run.
• iso-postflight reconciles observed outputs into a next-action gate.