fix(promotion): commit the files of transitions that applied when a later one fails

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: project — PR 9 of 10 for inline simulation PR checks (TEST-141). This is a fix to promotion, independent of the check stack (cut from main), and the promotion gate (PR 10) depends on it.

• Problem: when a multi-transition promotion fails partway, the "Commit reconciled files and UUID state" step pushes nothing: not the UUID state, and not the files of transitions that already reached the platform.
  • Why: on failure the step stages only .vapi-state.*.json, but the failed transition's promotionPlanApply has already rewritten tracked files in its target org, so git pull --rebase refuses with "You have unstaged changes".
  • Result: git and the platform disagree, and the next promotion plans from stale files.
• Who it affects: teams using promotion.yml with two or more transitions (dev → staging → prod), and anyone who adds the promotion gate in PR 10, where a failing gate is exactly a mid-run failure.
• What changes:

  • src/promote-cmd.ts:

    • each --apply run truncates tmp/promotion-applied.txt (gitignored);
    • after each successful apply.ts, it records each path git status --porcelain -z --untracked-files=all -- resources/<target> reports (new, modified, deleted and renamed files, by current path), with its content at that moment written to git's object store (git hash-object -w; - for a deletion). These are read from git, not the plan, because apply's own pull and push can rewrite files the plan didn't name;
    • promotionCommandRun(args, deps = { childRun }) gains a test seam.

  • .github/workflows/promotion.yml: on a non-success outcome, the commit step:

    1. stages the state files plus exactly the recorded blobs (git update-index --cacheinfo; deletions with git rm --cached), and commits. Staging the recorded content, not the working tree, means a later failed transition that rewrote the same file can't replace what was applied;
    2. runs git reset --hard HEAD && git clean -fd -- resources, so the failed transition's rewrites are discarded;
    3. then rebases and pushes as before.

    On success it's unchanged: it commits all of resources.

  • improvements.md: refactor(engine): extract shared slug + folder helpers into slug-utils #35, RESOLVED.

Evidence of value

Red/green in a scratch repo.

• Setup: a bare origin plus a clone; the pipeline is a → b → c, and c starts with a tracked assistants/intake.yml.
• The run: promote --all --apply runs this branch's promote-cmd with a fake child runner. Apply into b succeeds (writing state and one extra file, as apply's pull can). Apply into c writes state, then fails.
• Then: the workflow's real commit step, extracted from each ref's promotion.yml, runs with PROMOTION_OUTCOME=failure.

	main (69c7e83)	This branch
Commit step	error: cannot pull with rebase: You have unstaged changes. exit 128	pushed, exit 0
origin/main	unchanged (only base)	chore: record promoted Vapi state [skip promotion]
.vapi-state.b.json / .c.json on origin	{} / {} (state lost)	uuid-b / uuid-c (both recorded)
resources/b/assistants/intake.yml, pulled-by-apply.yml	missing	committed
resources/c/assistants/intake.yml	old content	old content (the failed rewrite is discarded)
resources/c/assistants/pulled-by-apply.yml	—	removed by git clean

tmp/promotion-applied.txt after the run held exactly the two resources/b/... paths.

Same-org case: red before the fix, green after. Two pipelines promote into the same org in one --all run. The first applies resources/c/assistants/intake.yml with a's content, and the second rewrites that file with b's content and then fails. Before the fix, the committed file was b's (the failed rewrite); after it, the commit holds a's, the content that was actually applied.

Tests: on top of #68, npm test goes from 476 to 484 passing.

Testing plan

• tests/promote-cmd.test.ts (3 tests, a real temp git repo, injected child runner):

  • one transition applies and the next fails: only the applied transition's files are recorded, including a file apply rewrote that the plan didn't name;
  • every --apply run starts a fresh record, and a plan-only run leaves it alone;
  • deleted and renamed files are recorded by their current path.

• tests/promote-cmd.test.ts also checks that each applied file is recorded with its content at apply time (git cat-file of the recorded blob, after a later rewrite), and a deletion as -.

• New tests/promotion-workflow-commit.test.ts (4 tests) runs the workflow's real commit step, read from promotion.yml and run with bash -e, against a clone of a bare origin, after a promotion driven through promote-cmd:

  • partial failure: state and the applied transition's files are pushed, and the failed rewrite is not;
  • the same-org case above;
  • success commits every change;
  • no changes pushes nothing.

  A later edit to the YAML that brings either bug back fails here.

• The existing tests/promotion.test.ts, and test(promotion): pin the exact files promoting an assistant writes to the target #68's golden promotion test, pass unchanged.

• Not tested:

  • a real GitHub Actions promotion run (the step runs locally under bash, read from the YAML) — manual QA with two non-production orgs before merge.

Stacked on #68.

Refs TEST-141

After review

• Dhruva: if recording an applied transition's files fails, the run now stops with an error naming the org and how to reconcile it (npm run pull -- <org>), instead of warning and letting the commit step save that org's state without its files. Test: promote-cmd.test.ts breaks git after the first apply and expects the run to stop there.
• Chris (commit per transition): replied on the PR. The blob snapshot gives the same guarantee, that what's committed is what reached the platform, without the CLI making git commits mid-run.

🤖 Generated with Claude Code

[scott-lowe-vapi]

• feat: identify every gitops API request with a User-Agent #78
• feat(validate): catch broken references and show findings on the PR #77
• ci: validate every org's resources on every pull request #76
• ci: lint workflows and test the PR check's key-sharing decision #75
• test(docs): check that doc links, commands and flags exist #74
• fix(cleanup): never delete resources matched by .vapi-ignore #73
• docs(agents): one compact guide for Claude, Codex and Cursor #72
• docs: edit the guides for new readers and fix inaccuracies #71
• docs: restructure the README into a short landing page and topic guides #70
• docs: prepare for public release: scrub internal names, fix examples, add community files #69
• feat(promotion): gate promotion out of an org on a passing check #66
• fix(promotion): commit the files of transitions that applied when a later one fails #65 👈 (View in Graphite)
• test(promotion): pin the exact files promoting an assistant writes to the target #68
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[chris-garber-vapi]

I'm a little wary on this one. It seems to me like if we're making git blobs for the files that we could instead just be doing some type of commit operation, so we could have like: test -> apply -> commit or something like that, rather than having a kinda intermediate half state that we commit after the fact. I think this would make our system more like terraform (which I think we're kinda taking inspiration from).

Don't wanna block here, I'm far from an expert. I think this will likely get the job done, but I don't know if it's the best option

[dhruva-vapi]

lgtm, snapshotting the blob after each apply is a nice touch since a later failed transition into the same org can't overwrite what actually reached the platform. tests pass locally too

one non-blocking thing: if appliedPathsRecord fails it only warns, so when a later transition fails we'd commit that org's state without its files, which is the same git vs platform drift this PR is fixing. can we make that fail loudly so someone knows to reconcile that org by hand

[scott-lowe-vapi]

Thanks both.

@dhruva-vapi: done. If recording an applied transition's files fails, the run now stops with an error that names the org and how to reconcile it (npm run pull -- <org>), instead of warning and letting the commit step save that org's state without its files. promote-cmd.test.ts covers it.

@chris-garber-vapi on committing per transition: I looked at it. It would mean promote making git commits, and pushing with auth, between transitions inside the CI run, and a crash between an apply and its commit would still leave the same gap. Snapshotting exactly what each apply left, then committing those blobs in the always() step, gives the same guarantee (what's committed is what reached the platform) without the CLI touching git history mid-run. Happy to revisit if we move toward a broader plan/apply/commit model.

🤖 Generated with Claude Code

[scott-lowe-vapi]

Merge activity

• Oct 7, 5:47 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Oct 7, 5:49 PM UTC: Graphite rebased this pull request as part of a merge.
• Oct 7, 5:49 PM UTC: @scott-lowe-vapi merged this pull request with Graphite.