# Cross-company Workflow Runner v0

# Cross-company workflow runner v0

Last verified: 2026-05-25

## What it is

`~/system/tools/cross-company-workflow.js` is a deterministic wrapper around Mission Control and Company Mesh.

Use it when a task needs a bounded multi-company loop such as:

- CodeCraft builds or reviews an implementation plan.
- Securion reviews security/privacy risk.
- Proveo validates acceptance or QA evidence.

It is **not** a replacement for Mission Control ownership, Mehanik/Prompt-Forge gates, or Proveo verification. It only makes the cross-company handoff repeatable and evidence-producing.

## Source files

- Runner: `~/system/tools/cross-company-workflow.js`
- Deterministic smoke workflow: `~/system/workflows/company-mesh-tool-smoke.json`
- Strong-model workflow smoke: `~/system/workflows/company-mesh-strong-review-smoke.json`
- Smoke test wrapper: `~/system/tools/tests/cross-company-workflow-smoke.sh`
- Evidence output default: `/tmp/alai/cross-company-workflows/`

## Commands

Validate a workflow:

```bash
node ~/system/tools/cross-company-workflow.js validate ~/system/workflows/company-mesh-tool-smoke.json --json
```

Run a workflow:

```bash
node ~/system/tools/cross-company-workflow.js run ~/system/workflows/company-mesh-tool-smoke.json --json
```

Inspect state:

```bash
node ~/system/tools/cross-company-workflow.js status /tmp/alai/cross-company-workflows/<state>.json --json
```

Finalize MC tasks after a PASS workflow:

```bash
node ~/system/tools/cross-company-workflow.js finalize /tmp/alai/cross-company-workflows/<state>.json \
  --bookstack https://docs.alai.no/link/184 \
  --json
```

For static plumbing-only responder runs, finalization is intentionally blocked unless explicitly marked:

```bash
node ~/system/tools/cross-company-workflow.js finalize /tmp/alai/cross-company-workflows/<state>.json \
  --bookstack https://docs.alai.no/link/184 \
  --allow-plumbing-finalize \
  --json
```

## Workflow JSON shape

Minimum example:

```json
{
  "name": "example-review-loop",
  "description": "Bounded build/security/QA review loop.",
  "priority": "M",
  "actor": "john",
  "responderMode": "gemini-review",
  "steps": [
    {
      "id": "codecraft",
      "company": "CodeCraft",
      "title": "CodeCraft review",
      "purpose": "Review implementation approach.",
      "prompt": "Review the pasted evidence. Return PASS/PARTIAL/BLOCKED first.",
      "endState": "ANSWERED"
    },
    {
      "id": "securion",
      "company": "Securion",
      "title": "Security review",
      "purpose": "Review security/privacy risks.",
      "dependsOn": ["codecraft"],
      "prompt": "Review security implications of the pasted evidence.",
      "endState": "ANSWERED"
    }
  ]
}
```

Required per step:

- `id`
- `company` or `agent`
- `purpose`
- `prompt` or `promptFile`

Optional per step:

- `dependsOn`
- `title`
- `priority`
- `endState` (`PASS`, `PARTIAL`, `BLOCKED`, `ANSWERED`, `DECLINED`)
- `responderMode` (`answer`, `blocked`, `decline`, `agent-runner`, `gemini-review`)
- `ttlSeconds`, `maxTurns`, `costCapUsd`, `timeoutSeconds`

## Safety defaults

The runner is intentionally conservative:

- Uses JSON workflows only.
- Uses `spawnSync` argv arrays, not shell interpolation.
- `promptFile` must remain under the workflow file directory.
- MC child tasks use `route=general` so pi-orchestrator does not compete with the workflow.
- Responder execution is explicit per run/step; no daemon is started.
- State records the workflow SHA-256 and refuses status/finalize if the workflow file changed.
- Finalize refuses non-PASS workflows.
- Finalize refuses static responder evidence unless `--allow-plumbing-finalize` is provided.

## Responder modes

| Mode | Meaning | Use |
|---|---|---|
| `answer` | Static deterministic response | Plumbing-only smoke tests |
| `blocked` | Static blocked response | Negative-path plumbing tests |
| `decline` | Static decline response | Policy/eligibility tests |
| `agent-runner` | Local persona via `agent-runner.js` | Cheap local advisory, subject to claim gate |
| `gemini-review` | Cloud strong-model advisory via Gemini CLI | Bounded strong review; keep prompts evidence-based and cost-limited |

## Claim-gate override

`--claim-gate-off` passes `COMPANY_MESH_CLAIM_GATE=off` to responder execution. Treat this as a break-glass/debug option only.

Use it only when all are true:

- the workflow is plumbing-only or local debugging;
- no production, deploy, legal, financial, security, or customer-facing completion claim will be made from the output;
- the final evidence explicitly says claim gate was disabled;
- MC finalization is either skipped or marked as plumbing-only.

Do **not** use `--claim-gate-off` to make blocked `agent-runner` responses look valid. If claim gate blocks a response, prefer adding concrete evidence paths/pasted evidence or returning `PARTIAL`/`BLOCKED` honestly.

## Evidence model

A run writes:

- state JSON (`0600`) containing parent task, child tasks, message ids, responses, and end states.
- markdown evidence summary next to the state JSON.
- responder evidence JSON under the chosen evidence directory.

Evidence should be treated precisely:

- Company Mesh delivery proves delivery only.
- Static `answer` proves plumbing only.
- `agent-runner`/`gemini-review` output is advisory unless it cites concrete evidence paths or pasted evidence.
- Mission Control `done` still requires normal validator/verdict gates.

## Known gotchas

- `mc.js ready` requires task status `in_progress` or `ready_for_review`, validation notes, and `--bookstack <url>`.
- Claim gate can block `agent-runner` outputs if the response makes factual completion claims without evidence paths.
- `gemini-review` uses the local `gemini` CLI and may fail if credentials/model access are unavailable.
- Public demo/product workflows must still obey product guardrails: no destructive public mutation, no fake deploy/integration claims.

## Current verified status

Completed evidence exists for the initial Company Mesh workflow runner smoke:

- `/tmp/alai/company-mesh-handoff-20260523/mc-101896-cross-company-workflow-final-pass.md`
- `/tmp/alai/company-mesh-p2p-six-artifacts-consolidated-20260525T0210Z.md`

The next maturity step is a bounded non-smoke workflow using `gemini-review` or `agent-runner` against a real evidence artifact, with cost capped and no production mutation.