ECC/workflows/README.md

ECC native workflows (pilot)

Scripts in this directory are Claude Code Workflow tool scripts — deterministic, multi-agent orchestration that runs in the background and fans out to subagents.

This is a pilot: ECC's orchestration (orch-*, multi-*, GAN/Santa loops) is currently hand-rolled on top of the Task/Agent tool. These scripts port the autonomous, fan-out-heavy segments to the native engine, which gives us barrier-free pipelining, automatic concurrency capping, structured-output validation, and resumability for free.

orch-review.workflow.js

A native port of orch-pipeline Phase 5 (Review).

The gated outer loop (Gate 1 after Plan, Gate 2 before Commit) stays in the main conversation — native workflows run autonomously in the background and cannot pause for interactive approval. This script owns only the segment between the gates:

1. Review — one reviewer agent per dimension, in parallel:
   • ecc:code-reviewer (correctness & quality) — always
   • the matching ecc:<language>-reviewer — when args.language maps to one
   • ecc:security-reviewer — only when the orch-pipeline security trigger matches the diff/paths
2. Dedup — independent reviewers routinely flag the same line, so findings are merged across dimensions keyed on the normalized evidence snippet (titles and line numbers drift per reviewer; the offending code does not). Each surviving finding records which dimensions reported it and keeps the strictest severity.
3. Verify — every unique CRITICAL/HIGH finding is handed to an independent adversarial verifier that defaults to refuted on uncertainty. MEDIUM/LOW pass through as advisory.

The Review→Verify barrier is deliberate: deduping before verification is exactly the case the Workflow guidance calls a justified barrier — it stops the verifier running N times on the same bug (in local testing, 11 raw findings collapsed to 4 unique, roughly halving verifier cost).

Invocation

The main loop computes the diff, then calls the Workflow tool:

Workflow({
  scriptPath: "workflows/orch-review.workflow.js",
  args: {
    diff: "<unified git diff text>",   // required
    language: "typescript",            // optional — selects a language reviewer
    changedFiles: ["src/auth.ts"]      // optional — feeds the security trigger
  }
})

Invalid input throws (the gate fails closed): a missing/empty diff, malformed JSON, or a non-array changedFiles is rejected with a clear error rather than silently approving an unreviewed payload.

Returns

{
  "verdict": "APPROVE" | "CHANGES_REQUESTED", // CHANGES_REQUESTED if any blocker OR a dimension failed
  "incomplete": false,            // true when one or more review dimensions failed to run
  "failedDimensions": [ /* { dimension, error } — error is a bounded label, never raw subagent text:
                           "agent returned null (terminal failure or skip)" | "review agent failed" */ ],
  "blocking": [ /* confirmed CRITICAL/HIGH + unverifiable ones — must clear before Gate 2 */ ],
  "advisory": [ /* MEDIUM/LOW + adversarially-refuted findings */ ],
  "stats": { "dimensions": 3, "failed": 0, "raw": 11, "unique": 4, "confirmed": 4, "unverified": 0, "refuted": 0 }
}

The main loop presents blocking at Gate 2; the human still approves the commit. The gate fails closed at every stage: if a reviewer dies the dimension is recorded in failedDimensions (verdict never a clean APPROVE), and if a verifier dies or returns null the blocker is kept in blocking (tagged "could not be verified") rather than demoted to advisory — an unreviewed security dimension or an unverifiable CRITICAL must not pass as approved.

Invoking it

/orch-review (commands/orch-review.md) is the command surface: it gathers the diff (local uncommitted changes or a GitHub PR), calls this workflow, and reports the blocking/advisory split at Gate 2.

Not in this PR (follow-ups)

• i18n mirrors (docs/<locale>/commands/orch-review.md) for the /orch-review command (not CI-enforced; only a subset of commands are translated today).
• Wiring /orch-review into the orch-pipeline Review phase as the native option.
• Installer / manifest wiring so the script ships to ~/.claude/ on install.
• Porting the Research sweep and Plan judge-panel segments next.