[SaulMoro]

Closes #1078. Independent of #1126 (run records): whichever merges second adapts run records to graph runs (step lookup by path, a skipped count, end). If #1126 lands first without that, I follow up with the adaptation. One commit per slice; the plan is in #1078 (comment).

Summary

Workflow steps form a graph: needs, if, named ends, inputs, and sub-workflows (from a file or inline).

 leaseNext
-  first pending step; any earlier non-succeeded step fails the run
+  settleRun: skip steps whose needs stopped (unless their `if` reads them) or were all skipped,
+            or whose `if` is false; end the run at a reached `end` or when nothing is left
+  lease the first ready step in declaration order (child steps by path: check.classify)
 reportAttempt
-  a failed report fails the run on the spot
+  record the outcome; the next `next` keeps settling the graph

inputs:
  title: string
ends:
  shipped: succeeded
steps:
  - id: check
    workflow: check                 # file sub-workflow, snapshotted at start
    with:
      title: "{{ inputs.title }}"
  - id: fix
    needs: [check]
    if: steps.check.outputs.verdict == 'fix'
    command: node fix.js
    env:
      TITLE: "{{ inputs.title }}"   # inputs reach commands only through env
  - id: drop
    needs: [check]
    if: steps.check.outputs.verdict == 'drop'
    command: node drop.js
  - id: verify
    needs: [fix]
    workflow:                       # inline sub-workflow
      ends:
        green: succeeded
      steps:
        - id: test
          command: npm test
          end: green
  - id: shipped
    needs: [verify]
    if: steps.verify.end == 'green'
    end: shipped

Pull checks each file, then checks a step that runs another workflow against that workflow's runnable version: missing child, recursion, with keys against the child's inputs, and reads of outputs or ends the child (file or inline) does not declare. Pull and the engine take the templated fields (with, prompt, env) and the step actions from one list, so they cannot disagree on what is a template. docs/dev/workflow-engine.md lists the engine rules that span more than one file, for the next change to src/workflow/.

Pull settles every file's version before any check reads it, so no file is checked against a version that ends up rejected:

start: each file at its revision if it passed its own checks, else at its kept copy (last valid version) unless a code dropped it
repeat until no version fails, checking each against the versions the others are at now (child exists, with/inputs, outputs, ends, cycle):
  a failing version falls back (revision -> kept copy -> nothing) once nothing it runs, directly or not, still fails
  if every failing version waits on another, they run in a cycle: the new revisions on it fall back first
cache = exactly the settled versions: an unreadable file keeps its copy; a missing or symlinked file has none

Decisions worth a look:

• needs is required after the first step; needs: [] declares another root. Order alone never implies a dependency.
• skipped is a step status, not a report outcome: drivers still report only success | failed | released.
• Templates never expand inside command; ${{ … }} stays literal elsewhere (GitHub Actions text), but is flagged inside command.
• A read of an output or end the child does not declare drops the parent's cached copy even when the parent file is unchanged, so a renamed child output cannot leave a parent that always skips.
• A kept copy is kept only if it fits what the workflows it runs settle to; the cache stores the source for that check. New revisions that run each other in a cycle are all rejected, since picking one of them by file name would be arbitrary.
• A run stored by a version without needs makes next return run_unreadable instead of running later steps as roots.

Evidence

• Before (main): needs, if, end, inputs, env, with and workflow are not step keys (STEP_KEYS = id, command, prompt, prompt_file, agent, output), so the file below fails pull and a failed step fails the whole run.
  After, real CLI on 62d004f (npm run build, sandboxed HOME, teamai init --self, the two files above with check.yaml classifying the title):

  $ teamai pull
  ✔ [workspace] Synced 2 workflows
  $ teamai workflow start ship --driver local --inputs '{"title":"crash on save; rm -rf /"}'
  {"data":{"done":{"run":"r611f1d1e","outcome":"succeeded","end":"shipped"}}}
  $ steps in the run file
  check            succeeded  success
  check.classify   succeeded  success
  fix              succeeded  success
  drop             skipped
  verify           succeeded  success green
  verify.test      succeeded  success
  shipped          succeeded
  

  And a typo in an inline workflow read is caught at pull:

  $ teamai pull
  ⚠ [workflows] workflows/inline-typo.yaml:19: field "steps[1].if": step "use" if reads steps.grp.outputs.verdcit, which is not an output the inline workflow of step "grp" declares
  ⚠ [workflows] workflows/inline-typo.yaml has no runnable version
  

• Kept copies, real CLI on cc799fb (same setup). A parent whose new revision is invalid no longer keeps a copy that reads an output its child renamed:

  $ teamai pull
  ⚠ [workflows] workflows/ship.yaml:3: field "description": description must be a non-empty string
  ⚠ [workflows] Dropped the last valid version of ship: step "fix" if reads steps.check.outputs.verdict, which is not an output workflow "check" declares
  ⚠ [workflows] workflows/ship.yaml has no runnable version
  $ teamai workflow start ship --driver local
  {"error":{"code":"workflow_not_found","message":"Workflow \"ship\" has no runnable version. Check workflows/ship.yaml and pull again."}}
  

• Kept copies and cycles, real CLI on f251447 (same setup). Cache ship -> check with a command-only check, then make ship.yaml invalid and check.yaml run ship.
  Before (cc799fb): the cycle check followed check's rejected revision and dropped ship:

  $ teamai pull
  ⚠ [workflows] Dropped the last valid version of ship: step "check" runs workflow "check" in a cycle: ship -> check -> ship
  $ teamai workflow start ship --driver local
  {"error":{"code":"workflow_not_found","message":"Workflow \"ship\" has no runnable version. Check workflows/ship.yaml and pull again."}}
  

  After (f251447): check's new revision is rejected for the cycle, and both keep their last valid version:

  $ teamai pull
  ⚠ [workflows] workflows/check.yaml:9: field "steps[1].workflow": step "again" runs workflow "ship" in a cycle: check -> ship -> check
  ⚠ [workflows] Kept the last valid version of check; this revision was not cached
  ⚠ [workflows] workflows/ship.yaml:3: field "description": description must be a non-empty string
  ⚠ [workflows] Kept the last valid version of ship; this revision was not cached
  $ teamai workflow start ship --driver local
  {"data":{"done":{"run":"r806c5436","outcome":"succeeded"}}}
  

• Tests on f251447, on main 3865561: npx tsc --noEmit, npm run lint, npx vitest run (9968 passed; gitlab-clone-realspawn times out here, and also on main), full npm run test:e2e (1246 passed; the 6 workflow files pass; dashboard-unified times out here and on main, submodule-checkout-1041 passes when run alone, source-freshness-recall is the macOS /private/var path also failing on main). A table test runs a parent and its child through accept, keep, delete, unreadable and symlink revisions, a renamed output and a cycle, in both name orders. It starts every workflow each sync caches or keeps and checks the cache holds nothing else. The conformance suite gains scenarios for skipped steps, rendered env, sub-workflow paths and recovery after a failure.

• Not checked locally: providers other than git and agents other than Claude; left to CI.

Merge Danger

Door: two-way

Workflows are new in the 0.28 beta; no stable release carries them. An older teamai reading a cache written by this version runs the graph as a linear list (it fails open), so a downgrade during the beta should be followed by teamai pull.

Blast Radius: workflows

A step after the first now needs needs, so existing beta workflow files without it fail pull until updated. A workflow file that is a symlink, or a symlinked workflows/ directory, now loses its cached version at the next pull, like a deleted file. Nothing outside src/workflow/, workflow start --inputs, and the workflow guide changes.

Follow-ups noted on the issues they affect: lazy child creation and inline readiness need revisiting for parallel leases (#1079); env keys may shadow declared secrets (#1082).

[jeff-r2026]

@SaulMoro Thanks for all your recent contributions to TeamAI. We really appreciate the consistent, thoughtful work you've been doing. I've upgraded your repository access to write—well deserved!

[SaulMoro]

@jeff-r2026 Thank you, I appreciate the trust. I use TeamAI both with my team and on my own, and it's very useful in both cases. In my personal projects, it gives me a single source of truth for skills, rules and hooks, and every AI tool I use pulls from it, so I dogfood it a lot. The new workflows are very powerful. I've enjoyed contributing, and I have more ideas to improve it, so I'll keep sending them as issues and PRs.

[github-actions]

• [P1 blocking] Revalidate retained parents against updated child contracts — src/workflow/cache.ts:190. Cache a parent whose branch reads steps.check.outputs.verdict, then invalidate its description while renaming the child’s export to decision. The parent bypasses reference checking and retains its cached definition. Its condition now reads null, silently skips the branch, and can report success. Check retained definitions against the final child versions before keeping them.

• [P2 non-blocking] Check cycles against effective fallback definitions — src/workflow/cache.ts:247. Start with cached a → b and command-only b; change a → missing and b → a. Cycle detection follows the invalid new a, but pull subsequently retains old a → b and caches b → a. Both starts then fail with workflow_recursion despite b being reported synced. Include fallback definitions in cycle validation.

Testing: The description provides sufficient build and representative real-CLI evidence. Deferred provider/agent coverage is acceptable. No PR code was run, built, or installed.

[github-actions]

• [P1 blocking] Check cycles against settled child versions — src/workflow/cache.ts:264. Cache ship → check with command-only check, then invalidate ship’s description and change check → ship. Pull rejects the new check and retains its command-only copy, but asked() still follows the rejected candidate when checking retained ship. It falsely reports a cycle and deletes ship, so workflow start ship returns workflow_not_found despite a valid, acyclic fallback pair. Cycle checks must account for the versions actually retained.

Earlier findings: Both previously reported failure scenarios are resolved in this diff.

Testing: The description supplies sufficient build and representative real-CLI evidence. Deferred provider/agent coverage is acceptable. No PR code was run, built, or installed.

[github-actions]

No new findings in the specified diff.

Earlier findings: All three previously reported failure scenarios are resolved. Retained parents are revalidated against settled child contracts, and cycle checks use the effective versions, rejecting cyclic revisions before removing valid fallback copies.

Testing: The PR description supplies sufficient build and representative real-CLI evidence, including verification on f251447c. Deferred provider/agent coverage is acceptable.

No PR code was run, built, or installed.