docs(schema): the legacy workflow schema is a fork, not a stale file

[kjgbot]

The finding

ops/RUNTIME-STATUS.md records that the local SDK "refuses its old swarm/workflows schema before execution." That reads like a migration chore. It is not — two runtimes consume these files and they speak different schema versions.

The local SDK refuses 1.0 outright (rc=2):

spec: unknown key "swarm"   (expected version|name|description|cli|agents|triggers|steps|budget)
spec: unknown key "workflows"
spec.version: unsupported version "1.0" (expected "0.1.0")
spec.agents: expected a map of named { cli, model } declarations
spec.steps: expected a non-empty array

Cloud accepts it. On 2026-09-07 the review gate ran agent-relay cloud run workflows/review-swarm.yaml --sync-code --json against the unmodified 1.0 file; it returned run 04da7e48-87ec-4c7a-a1ee-22fd482e1cd1 and was given sandbox b5f3b344-64cc-434d-97f8-f5da71ba4517. It failed later on Daytona CPU quota — not on schema.

Why this PR migrates nothing

Three of the seven legacy files are consumed by cloud right now:

File	Consumer
workflows/review-swarm.yaml	.github/workflows/review-swarm.yml:145, every PR
workflows/watchdog.yaml	live cloud schedule flows-watchdog, cron 0 8 * * *, active
workflows/drive.yaml	registered via agent-relay cloud schedule (ops/AUTONOMY.md)

Migrating those makes them parse locally and may make them unrunnable in cloud — which would take out the review gate and the watchdog together. I converted all seven and confirmed they compile, then reverted every one. The diff touches no file under workflows/.

The question that has to be answered before anyone migrates: does cloud accept 0.1.0? I could not answer it from this machine without spending a cloud run, and the Relayfile database is at its 10 GiB cap.

What is here

ops/schema-migration/migrate-legacy-workflow.py — converts one file and refuses rather than guesses. A migration that silently drops a field is worse than one that fails: the flow runs, looks fine, and means something else.

Verified against the real SDK, all seven convert and compile (9, 7, 7, 6, 1, 2, 1 steps). Losses are written into each output as comments:

• swarm: {pattern, channel, timeoutMs} — no run-level slot in 0.1.0
• agent preset — persona surface, RFC-0001 decision 9
• agent-step timeoutMs — 0.1.0 bounds deterministic steps only
• a named agent reference becomes the step's cli — 0.1.0 requires model in a named declaration and the legacy schema never carried one. Verified both ways: an agent step with cli and no agents map compiles; an agents map with cli and no model is refused. Inventing a model is exactly the guess this refuses to make.

Lossless: version 1.0 → 0.1.0, step name → id, agent task → instruction, workflows[0].steps lifted to top level. Every legacy file declares exactly one workflow, so that is a lift and not a split — and the script refuses a multi-workflow file rather than guessing how to divide it.

Not merging this myself

No independent signoff is available — the review swarm is one of the things blocked.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FtQSAcGDta5VH9xiZFT4sR

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 9121769e-6da8-4180-a575-49fa5757a0da

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[github-actions]

Review swarm: maintainability

No fresh transcript was produced for run a7b56289-5b2c-41e1-8875-f7267ba8e28e (MISSING).

[github-actions]

Review swarm: history

No fresh transcript was produced for run a7b56289-5b2c-41e1-8875-f7267ba8e28e (MISSING).

[github-actions]

Review swarm: structure

No fresh transcript was produced for run a7b56289-5b2c-41e1-8875-f7267ba8e28e (MISSING).

[github-actions]

Review swarm: FAILED

• maintainability: MISSING
• history: MISSING
• structure: MISSING

Cloud run: a7b56289-5b2c-41e1-8875-f7267ba8e28e

[kjgbot]

Answered: cloud requires the 1.0 schema. The two are mutually exclusive.

The PR left one open question — does cloud accept 0.1.0? — and said it needed a cloud run. That was wrong; it needed three reads.

Cloud's HTTP route validates nothing. body.workflow is checked only as a non-empty string (packages/web/app/api/v1/workflows/run/route.ts:745), and YAML is merely parsed to JSON so bootstrap can JSON.parse it. So the fact that a 1.0 file was admitted proves nothing about schema. The sandbox then executes a compiled orchestrator-lib pinned at relay-orchestrator-sdk-11.10.3 — a different product from @relayflows/sdk.

The answer is client-side in the CLI, before anything is submitted. From the installed @agent-relay/cloud/dist/workflows.js:

function validateYamlWorkflow(content) {
  if (!hasField('version'))   throw new Error('missing required field "version"');
  if (!hasField('swarm'))     throw new Error('missing required field "swarm"');
  if (!hasField('agents'))    throw new Error('missing required field "agents"');
  if (!hasField('workflows')) throw new Error('missing required field "workflows"');
}

swarm and workflows are required by cloud. They are the exact two keys the 0.1.0 SDK rejects as unknown. No file can satisfy both validators, and agent-relay cloud run refuses a 0.1.0 file before it reaches the network.

What follows

Reverting the seven files was necessary, not cautious. Migrating review-swarm.yaml, watchdog.yaml and drive.yaml would have broken every cloud invocation of them — the review gate on every PR and the flows-watchdog schedule — in exchange for a local parse nobody was blocked on.

It also means this is not a migration problem at all. The convergence work is cloud#3270, "execute v2 runtime in Cloud sandbox", which teaches cloud to run relayflows specs directly. That is the bridge between the two runtimes, and it is admission-disabled on every stage.

The tool and analysis here stand on their own — the migrator is what you would want the day a converged runtime exists, and it refuses rather than guesses until then. But nobody should migrate a cloud-consumed file on the strength of it.

[kjgbot]

maintainability lens — FAIL

Maintainability review — PR #238 (ops/schema-migration/)

Blocker — silent in-place overwrite contradicts the safety story.
migrate-legacy-workflow.py:126 defaults dest to src when sys.argv[2] is missing. So python migrate-legacy-workflow.py workflows/review-swarm.yaml rewrites the live file that README.md:24-31 explicitly warns must not be migrated ("Migrating those to 0.1.0 makes them parse locally and may make them unrunnable in cloud, which would take out the review gate and the watchdog together"). A stranger reading the README will absorb the safety posture; the CLI's default betrays it. Either require an explicit dest, refuse to write when src == dest, or refuse to write over any path enumerated in the README's live-file table. As written the guardrail lives only in prose.

Blocker — the "verified against the real SDK" claim has no test that would fail if it stopped being true.
README line 41 says all seven files convert and compile. Nothing in the diff pins that: no fixture, no golden output, no CI invocation. The next reader who edits STEP_BY_TYPE or DROPPED_AGENT gets no signal. The whole script hinges on schema tables that will drift; a single check-in fixture ("run against testdata/legacy/*.yaml, diff against testdata/migrated/*.yaml") would make the drop-list meaningful.

Concern — boundary handling is missing at the CLI surface. sys.argv[1] throws IndexError with no usage message; yaml.safe_load may return None or a list, and set(raw) at line 36 then crashes with a bare TypeError. Same for workflows[0].get(...) at line 68 if the entry is not a dict. This is a user-facing tool, so boundary validation is appropriate.

Concern — implicit coupling between DROPPED_TOP and the inline if 'swarm' in raw. Line 27 declares a set intended to encode dropped top-level keys, but only swarm gets a note (lines 45-48). Adding another key to DROPPED_TOP silently drops it with no reader-visible note — the exact failure mode the module docstring says the script exists to prevent.

Concern — out['id'] may be None yet is used in subsequent error text. Line 70 sets id from s.get('name'); if missing, later problems (lines 91, 100, 103) render as step None: ..., degrading the "refuse rather than guess" experience.

Notes. open(path) on lines 33 and 127 leaks a handle and picks up the platform default encoding; use with open(..., encoding='utf-8'). type is in STEP_COMMON, so out[k] = v at line 98 harmlessly re-assigns it — noise, not bug. The README's RFC-0001 "decision 9" reference (line 51) has no anchor into docs/RFC-0001-everything-is-a-relayflow.md; a section link would help future readers.

REVIEW_FAILED

[kjgbot]

history lens — FAIL

Blocker — unrecorded losses contradict the commit’s stated scope (criterion 3). In 0510fae, the commit promises that the migrator “refuses rather than guesses” and that losses are recorded in output comments. However, ops/schema-migration/migrate-legacy-workflow.py:18–38 accepts top-level cli, budget, and triggers, while lines 106–110 omit them without refusal or loss notes. The same guarantee appears in ops/schema-migration/README.md:44–50.

This also echoes the conversion mistake recorded in ops/DRIVE-LOG.md:1293–1302: silently replacing authored semantics, previously repaired by refusing unrepresentable values.

Literal reproduction against the PR’s committed script:

python3 - <<'PY'
import subprocess, tempfile, yaml
ns = {'__name__': 'review'}
exec(subprocess.check_output(['git', 'show', '0510fae:ops/schema-migration/migrate-legacy-workflow.py'], text=True), ns)
raw = {'version': '1.0', 'name': 'probe', 'description': 'probe', 'cli': 'codex', 'budget': {'maxTokens': 1}, 'workflows': [{'name': 'probe', 'steps': [{'name': 'one', 'type': 'deterministic', 'command': 'true'}]}]}
with tempfile.NamedTemporaryFile(mode='w+', suffix='.yaml') as f:
    yaml.safe_dump(raw, f); f.flush()
    spec, problems, notes = ns['migrate'](f.name)
print('problems:', problems)
print('notes:', notes)
print('output keys:', sorted(spec))
print('cli preserved:', 'cli' in spec)
print('budget preserved:', 'budget' in spec)
PY

Captured output:

problems: []
notes: []
output keys: ['description', 'name', 'steps', 'version']
cli preserved: False
budget preserved: False

Preserve these fields or explicitly refuse them. The commit and README should describe the resulting supported scope accurately.

Concern: README.md:47 claims all seven files convert and compile without providing the compilation command and captured output. I did not independently rerun that compilation; missing evidence alone does not establish that the claim is false.

Notes: The cloud compatibility deferral in README.md:36–40 is appropriate. The supplied diff changes no live workflow or review gate, and I found no new contradiction with a settled RFC decision. Scaffolding and the older gate referenced by ops/NEXT.md are not rejection grounds.

REVIEW_FAILED

[kjgbot]

structure lens — MISSING

[kjgbot]

🎯 review-swarm: FAILED (M:fail H:fail S:missing)

Lens transcripts posted as sibling comments above.

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[kjgbot]

Both blockers were found against an earlier commit and no longer reproduce at the current head (bcafd421). Checked each rather than assuming either way.

History blocker — top-level cli/budget/triggers silently dropped. The lens ran its reproduction against 0510fae, where that was true. I ran the same reproduction against the head:

problems: []
notes: []
output keys: ['budget', 'cli', 'description', 'name', 'steps', 'triggers', 'version']
  cli:      preserved=True   recorded_as_loss=False
  budget:   preserved=True   recorded_as_loss=False
  triggers: preserved=True   recorded_as_loss=False

They are preserved, not omitted. The blocker's premise — "lines 106-110 omit them without refusal or loss notes" — does not hold at this head.

Maintainability blocker — dest defaults to src, enabling in-place overwrite. The lens cites migrate-legacy-workflow.py:126. At the head that logic is at lines 210-220 and does the opposite:

if len(sys.argv) > 2:
    dest = sys.argv[2]
else:
    ... f"refusing to migrate {src} in place: pass an explicit destination, "
    sys.exit(2)

An implicit in-place rewrite is refused with exit 2.

---

A note on why this was not obvious, since it bit me twice today. I tried to judge verdict freshness by comparing the head's commit timestamp to the verdict timestamp. That is unsound: commit date is not push date, so a verdict can postdate a commit and still have reviewed an earlier revision. Here the arithmetic said "fresh" while the lens was demonstrably reading 0510fae — it named the commit, which is what actually settled it.

The reliable signal is the one this lens supplied: name the reviewed SHA and show literal output. Both lenses that gave me usable verdicts today did that.

Not claiming #238 is now correct — only that these two blockers no longer reproduce. Worth a re-review at bcafd421. One thing a fresh pass should look at that neither blocker covers: those three keys are now passed through into the 0.1.0 output, and whether the SDK schema accepts top-level cli/budget/triggers is a separate question from whether they are silently lost.

[kjgbot]

Closing: the actual defect this PR touched (migrate-legacy-workflow.py raising AttributeError on scalar steps instead of REFUSED) is now tracked as its own issue at #270, with the exact repro captured. The PR's doc change alone did not fix the bug. Reopen or open a fresh PR against #270 with the guard on s.get('type'); that's the real close.