v2.0.0 -Readiness Gate: never launch a step on unready inputs

What's new

Readiness Gate: never launch a step on unready inputs

Why

The coding step could be dispatched while its inputs — detailed-design /
uiux-design — were missing or empty. The engine only injected artifact paths
into the prompt and never checked the files, so the agent ran blind, stalled,
and burned the 2-hour hard cap. Two root causes:

• Resume hole: --from / --only silently dropped a read whose artifact
  file was missing, so the consumer launched with "(no prior input)".
• Lying success: a step could report outcome=succeeded while writing an
  empty/truncated artifact — nothing validated the file before consumers ran.

Pre-flight readiness check

Before each run-order group launches, every member's declared reads are
verified on disk: the artifact must exist and be at least
defaults.readinessMinBytes (200 bytes).

Ask, then repair — retry default 3

When an input is unready, the flow prints the list and asks at the terminal:

  Missing or incomplete input artifact(s):
    - Detailed Design (`.orca/artifacts/DETAILED_DESIGN.md`) — missing — needed by "Coding"
  Run the producing step(s) now to (re)generate missing inputs? [y/N]

• Asked even in auto-run — input safety is not agent autonomy.
  Piped/CI stdin (EOF) counts as "no".
• Decline stops the run immediately with the exact
  node .orca/flow.mjs --from <producer> "<objective>" command to resume.
• Accept re-runs ONLY the missing producers — singleton groups (parallel
  siblings are not re-run), transitively up the read chain in pipeline
  order — up to defaults.readinessRetries (3 default) attempts.
  The artifact file is ground truth; a worker's claimed outcome doesn't count.
• No blind re-dispatch: an indefinite outcome (unknown) during repair stops
  the run instead of risking a double dispatch.

Config (2 new defaults fields)

Field	Default	Meaning
readinessRetries	3	Repair attempts per missing producer before aborting
readinessMinBytes	200	Minimum artifact size to count as ready input

Stricter config validation (load time, every mode)

• Reads pointing at a later in-run step die: "reorder the pipeline".
• Reads of a step with no writes die fast (previously a raw TypeError
  crash at dispatch time).

Exemptions

• Reads of enabled: false steps (e.g. the optional grill interview) are
  optional inputs — never gated, matching the config contract.
• Dry-run and --status-preview are untouched.

Breaking / behavioral (why the major bump)

• A run now stops (with a resume hint) where it previously launched a
  consumer against missing/empty inputs.
• Previously-accepted configs with forward reads or writes-less reads are
  rejected at load.

Tests

15 new E2E scenarios (E12–E18, F10/F11) covering decline-abort, repair,
transitive chains, retry exhaustion, unknown-outcome safety, undersized
artifacts, repair hangs, and disabled-producer exemption — including E18,
the suite's first real run of the shipped default config on a fresh worktree.
Full suite: 216/216 (merged with the v1.7.0 notifications line).

Docs

• .orca/CONFIGURATION.md — new fields + "Readiness gate" subsection
• TROUBLESHOOTING.md — "Missing or incomplete input artifact(s)" entry

Install fix (re-tag, 2026-09-18)

The original v2.0.0 tag shipped a broken npx install: bin/init.mjs
created only the top-level .orca/ directory, so the newly added
.orca/workflow-template/* files failed with copy failed: ENOENT ... .orca\workflow-template\README.md on a fresh install (after a partial
copy of seven files). The tag is re-pointed to the fix (ad5845f): the
installer now creates each file's parent directory before writing.

If npx github:vankhangfet/orca-sdlc-kit failed with that error, simply
re-run the same command — it fills in whatever is missing (existing files
are kept; --force overwrites). Pinned by new E2E scenarios I1 (real
installer run into an empty project) and I2 (FILES ↔ package.json files
sync guard); suite 233/233.