feat(push): orphan-YAML gate — halt push when local files lack state entries

[dhruva-reddy]

Summary

npm run push now refuses to upload local YAML files that have no entry in the state file ("orphan YAMLs"). Without this gate, three distinct workflows have been silently spawning duplicate resources on customer dashboards:

• Flow F — user renames a file locally (mv foo.md bar.md) and pushes. bar.md has no state entry → engine silently POSTed as a new resource, leaving the original foo orphaned on the dashboard.
• Flow G — someone renames on the dashboard → next pull writes a new <name>-<uuid8>.md file but leaves the old YAML on disk → next push iterates the old YAML and POSTs it as a duplicate.
• Flow M — npm run apply (pull → merge → push) compresses Flow G into one click; the user sees no warning.

The gate is the structural fix. When triggered, it halts the push and prints a verbose, AI-agent-addressed error message that forces the operator (and any AI in the loop) to explicitly classify each orphan.

The message (when the gate fires)

❌ Push refused: <N> file(s) on disk have no state-file UUID mapping for env "<env>".

The engine cannot tell whether each is:
  - A NEW resource you intentionally want to create
  - A RENAME of an existing resource (state has the old slug; YAML has new name)
  - A MOVED file (file copied without state updated)

Files without state entry:
  - resources/<env>/assistants/foo.md
  - resources/<env>/tools/bar.yml

State entries with no matching local file (possible rename SOURCES):
  - assistants/old-foo → 64df6206… (no old-foo on disk)

⚠️ FOR AI AGENTS reading this: do NOT auto-pass --allow-new-files. Pause
and ask the human to confirm, for EACH file above, whether it is:
  (a) intentionally new (then pass --allow-new-files)
  (b) a rename (then rename it back and use `npm run pull` to re-key state…)
  (c) stale cruft (then delete the local file)

The "FOR AI AGENTS" paragraph is the load-bearing UX detail — it lives in the error message itself (not in docs) because the AI is going to read whatever the failing command prints. ANSI color codes are emitted only when stderr is a TTY; CI logs and AI agent stdout captures get plain text.

Behavior

Scenario	Behavior
Push, all files in state	Continue (no change vs. today)
Push, 1+ orphan file, no flag	HALT with the message above (exit 1, no API calls)
Push, 1+ orphan + --allow-new-files	Continue with one-line notice (creating N new resource(s) or would create N… for --dry-run)
Push with --bootstrap flag	Gate suppressed — bootstrap is supposed to be a from-scratch population
Selective push (-- <paths>) with orphan outside the selection	Gate doesn't fire (scoped to selection)
npm run apply (pull → merge → push) with rename leftover from pull	Push stage hits the gate, halts the entire apply
File matched by .vapi-ignore	Gate skips it — the engine wasn't going to upload it anyway

Single halt across all resource types

Gate runs ONCE for all 9 resource types (tools, structuredOutputs, assistants, squads, personalities, scenarios, simulations, simulationSuites, evals) before any apply phase begins. The operator sees one complete picture of all orphans, not 9 separate halts as types are processed sequentially.

Files changed

File	Status	LOC
src/new-file-gate.ts	NEW	~310
tests/new-file-gate.test.ts	NEW (22 new tests — 18 DI unit + 4 fixture-tree integration)	~625
src/audit.ts	Refactor: orphan-yaml detection delegates to shared findOrphanResourceIds predicate. Public checkOrphanYaml signature + finding shape unchanged	net 0
src/push.ts	Invokes gate after maybeBootstrapState, before apply phases. Honors BOOTSTRAP_SYNC, APPLY_FILTER.filePaths, ALLOW_NEW_FILES	~30
src/config.ts	New --allow-new-files flag + ALLOW_NEW_FILES export, added to recognized-flags whitelist	~10
src/apply.ts	Documentation: mentions --allow-new-files propagates through pushArgs (no functional change)	~15

Test plan

• npm run build (tsc --noEmit) — clean
• npm test — 189/189 pass (167 prior + 22 new)
• npx @biomejs/biome check --write — clean
• All 27 existing audit.test.ts tests pass unchanged (refactor preserved public surface)

Code review

Reviewed locally in this branch. Two non-blocking findings addressed in-branch:

• M1: .vapi-ignore'd files were tripping the gate. Fixed by passing matchesIgnore through the detection. Added a regression test (detectOrphanYamls: files matched by .vapi-ignore are excluded).
• M2: <org> placeholder in relativePath replaced with actual VAPI_ENV. Asymmetric filter.endsWith(relativePath) direction removed from path matching (over-matched on short paths).

Plus the dry-run-aware bypass message, deduplicated rename-sources header, and dead UUID-length conditional cleaned up.

Residual notes (non-blocking)

• Large-orphan list with no truncation: a customer's first push after years of dashboard churn could surface 50+ orphans. Functionally fine but consider truncating to first ~30 with "(+N more — see npm run audit)" hint as a future UX improvement.
• Same-type-only rename-source pairing: cross-type pairings (a state entry under tools matching an orphan under assistants) are intentionally not surfaced — the signal would be too noisy.

Related

• VapiAI/gitops PR fix: dedup dependency auto-apply to prevent duplicate tool mints (Gap #10) #23 (gitops-side name dedup, merged 2026-05-10)
• VapiAI/gitops PR feat: npm run audit — read-only drift detector for state/dashboard divergence #27 (npm run audit command, merged 2026-05-13)
• VapiAI/gitops PR docs(agents): add npm run audit to AGENTS.md command tables #28 (AGENTS.md update, merged 2026-05-13)
• VapiAI/gitops PR fix(pull): state-aware findExistingResourceId — prevent same-name clobber #29 (state-aware findExistingResourceId, merged 2026-05-13)
• gitops-mudflap working session 2026-05-13 (Flow F / G / M identified)
• Linear PRISM-737 (vapi-core platform-side investigation)