feat(push): enhance safety and clarity in push and apply operations

This commit introduces several improvements to the push and apply processes, focusing on safety and user experience. Key changes include:

- Updated the `apply` command to incorporate a validation step before executing the pull and push operations, ensuring that schema errors are caught early.
- Enhanced logging in the `push` command to provide clearer context during scoped runs, suppressing unnecessary output while still informing users of the resources being applied.
- Introduced a `quiet` option in the resource loading logic to minimize clutter in the console output during scoped operations.

These changes aim to reduce the risk of errors during deployment and improve the overall clarity of the command outputs.

Author: vtkovapi

improvements.md

@@ -73,6 +73,10 @@ you which stack PR closes the row.**
 | 19  | No `maxTokens` floor warning for tool-using assistants   | `maxTokens: 1` bricks the assistant silently       | None       | RESOLVED 2026-04-30 (Stack D)     |
 | 20  | Prompt vocabulary leaks into TTS                         | `Reason.` becomes verbal contaminant               | None       | Partial — Stack D heuristic       |
 | 21  | `.vapi-ignore` was pull-only (push could silently delete) | `--force` push DELETEd dashboard-only opt-outs    | None       | RESOLVED 2026-05-11 (#TBD)        |
+| 22  | Dashboard rename recreated the local file (duplicate per UUID) | Duplicate files after dashboard renames       | None       | RESOLVED (see entry)              |
+| 23  | Phantom `both-diverged` (canonicalization + agree-gate)  | Untouched resources blocked on first push          | None       | RESOLVED 2026-06-03 (#TBD)        |
+| 24  | Bare `push` is too easy to use as the deploy path        | Raw push skips apply's validate+pull safety        | None       | Open — mitigated by per-resource drift gate |
+| 25  | Interactive flows lack automated coverage                | Picker/conflict-prompt regressions ship silently   | None       | Open — scheduled for the test-update iteration |
 
 ---
 
@@ -1156,6 +1160,72 @@ RESOLVED 2026-06-03 (#TBD — PR number updates when opened).
 
 ---
 
+## 24. Bare `push` is too easy to use as the deploy path
+
+**Problem.** PR #41 review (dhruva-reddy): operators shouldn't have to memorize
+"`validate` && `apply` && avoid `push`". Raw `push` skips apply's
+validate-then-pull safety yet reads like the natural deploy verb, so it keeps
+getting used as one.
+
+**Current behavior.** `npm run push -- <org>` (`src/push.ts`) runs the raw
+push directly. Apply now embeds validation (`src/apply.ts` runs
+`validate-cmd` before its pull stage) and defaults conflict handling to the
+per-resource prompt, but bare push remains a single flag-less command.
+
+**Risk.** Lower than when the review was written — push now has the
+per-resource drift gate (`src/push.ts`, `checkDriftForUpdate` +
+`promptDriftResolution`), so out-of-band dashboard edits prompt or block
+instead of being clobbered. Remaining gap: push skips schema validation and
+the pull/merge pass, so it can still 400 mid-run or PATCH from a stale local
+view (one-sided, detectable, but avoidable).
+
+**Current mitigation.** Docs hierarchy (`AGENTS.md` "Choosing a sync
+command"), the orphan-YAML gate, and the drift gate/prompt.
+
+**Possible fix.** Reviewer's suggested shape: make raw local→dashboard push
+explicit/advanced via `npm run push -- <org> --direct`; bare `push` either
+delegates to safe apply or prints guidance telling the operator to use
+`apply` unless `--direct` is intended. Backwards-incompatible for automation
+that calls bare `push` — needs a deprecation window.
+
+**Status.** Open (mitigated 2026-06-04 by the per-resource drift gate and
+apply's built-in validate).
+
+---
+
+## 25. Interactive flows lack automated coverage
+
+**Problem.** PR #41 review (dhruva-reddy): the interactive picker
+(`src/interactive.ts` — Back/Cancel/empty-selection states) and the
+local-wins-apply-stays-clean invariant have no automated tests, and these are
+exactly the paths that regress while unit tests for path parsing still pass.
+
+**Current behavior.** No tests cover: (a) the picker's step machine
+(org → scope → pick → confirm → execute, including Back/Cancel/empty), (b)
+the push conflict prompt's three choices, (c) the regression "apply the same
+resource twice → second run is clean, not `both-diverged`" (root cause fixed
+by response-hash baselines in `src/push.ts` `writeBaselineFromResponse` and
+the `classifyDrift` live-agreement invariant in `src/drift.ts`, but
+unguarded by tests).
+
+**Risk.** Silent regressions in the most operator-visible surfaces; the
+existing suite also predates the hash-store refactor and will fail until
+reconciled.
+
+**Current mitigation.** Manual run-throughs per stage (see
+`docs/superpowers/specs/2026-06-03-state-hash-store-design.md`).
+
+**Possible fix.** The planned test-update iteration for the hash-store
+refactor must include, by name: picker smoke test (Back/Cancel/empty),
+conflict-prompt choice handling (mock TTY + select), and the
+double-apply-stays-clean regression (`localHash=B, platformHash=B,
+baseline=A → clean` plus baseline refresh after push).
+
+**Status.** Open — scheduled as part of the test-update iteration that
+reconciles the suite with the slim-state/hash-store engine.
+
+---
+
 ## Out of scope (intentionally not improvements)
 
 - **State file is identity-only and not git-ignored.** It's intentionally

src/apply.ts

@@ -106,14 +106,27 @@ export async function runApply(): Promise<void> {
     "═══════════════════════════════════════════════════════════════",
   );
   console.log(`🔄 Vapi GitOps Apply - Environment: ${env}`);
-  console.log("   Pull → Merge → Push");
+  console.log("   Validate → Pull → Merge → Push");
   if (hasForce) {
     console.log("   ⚠️  Deletions enabled (--force)");
   }
   console.log(
     "═══════════════════════════════════════════════════════════════\n",
   );
 
+  // Apply is the one-shot safe deploy verb: run the local schema validators
+  // first so a shape error never burns a pull/push cycle. No network call —
+  // this is the same check as `npm run validate`, just built in. It stays
+  // available standalone for CI / pre-flight use.
+  const validateCmd = `npx tsx src/validate-cmd.ts ${env}`;
+  const validateExit = runPassthrough(validateCmd);
+  if (validateExit !== 0) {
+    console.error(
+      "\n❌ Validation failed — fix the schema errors above before applying.",
+    );
+    process.exit(1);
+  }
+
   const pullCmd = `npx tsx src/pull.ts ${env} ${pullArgs}`.trim();
   const pullExit = runPassthrough(pullCmd);
   if (pullExit !== 0) {

src/push.ts

@@ -1391,9 +1391,18 @@ async function main(): Promise<void> {
     // a `--force` push can't silently delete a dashboard resource the repo
     // has explicitly opted out of managing. Bootstrap-pull paths read their
     // own patterns directly and are unaffected by this constant.
-    console.log("\n📂 Loading resources...\n");
+    if (partial) {
+      console.log(
+        "\n📂 Loading resources (scoped run — full set loaded quietly for reference resolution; only the selection below is applied)...\n",
+      );
+    } else {
+      console.log("\n📂 Loading resources...\n");
+    }
     const ignorePatterns = FORCE_DELETE ? [] : loadIgnorePatterns();
-    const loadOpts = { ignorePatterns };
+    // In a scoped run, suppress the per-file "Loaded" chatter — printing every
+    // local resource makes the blast radius look larger than it is. The scoped
+    // selection is printed explicitly after filtering instead.
+    const loadOpts = { ignorePatterns, quiet: partial };
     const allToolsRaw = await loadResources<Record<string, unknown>>(
       "tools",
       loadOpts,
@@ -1621,6 +1630,31 @@ async function main(): Promise<void> {
       ? filterResourcesByPaths(allEvals, "evals")
       : [];
 
+    // Scoped run: print exactly what's in scope (the load above was quiet).
+    if (partial) {
+      const scoped: Array<[string, ResourceFile<Record<string, unknown>>[]]> = [
+        ["tools", tools],
+        ["structuredOutputs", structuredOutputs],
+        ["assistants", assistants],
+        ["squads", squads],
+        ["personalities", personalities],
+        ["scenarios", scenarios],
+        ["simulations", simulations],
+        ["simulationSuites", simulationSuites],
+        ["evals", evals],
+      ];
+      let any = false;
+      for (const [label, list] of scoped) {
+        for (const r of list) {
+          console.log(`  📦 In scope: ${label}/${r.resourceId}`);
+          any = true;
+        }
+      }
+      if (!any) {
+        console.log("  ⚠️  Nothing matched the requested scope.");
+      }
+    }
+
     // Auto-dependency resolution context
     const autoApplied = new Set<string>();
     const autoAppliedTools: ResourceFile<Record<string, unknown>>[] = [];

src/resources.ts

@@ -15,6 +15,11 @@ import type { ResourceFile, ResourceType, StateFile } from "./types.ts";
 // preserve the pre-change behavior.
 export interface LoadOptions {
   ignorePatterns?: string[];
+  // Suppress per-file "📦 Loaded" / "📁 No <type> directory" chatter. Used by
+  // scoped (single-file / --type) pushes: the FULL set is still loaded for
+  // reference resolution, but printing every file makes the blast radius look
+  // larger than it is — the caller prints the scoped selection instead.
+  quiet?: boolean;
 }
 
 // Map resource types to their folder paths (relative to resources/)
@@ -208,7 +213,7 @@ export async function loadResources<T>(
   const ignorePatterns = options.ignorePatterns ?? [];
 
   if (!existsSync(resourceDir)) {
-    console.log(`📁 No ${type} directory found, skipping...`);
+    if (!options.quiet) console.log(`📁 No ${type} directory found, skipping...`);
     return [];
   }
 
@@ -309,7 +314,7 @@ export async function loadResources<T>(
     }
 
     resources.push({ resourceId, filePath, data });
-    console.log(`  📦 Loaded ${resourceId}`);
+    if (!options.quiet) console.log(`  📦 Loaded ${resourceId}`);
   }
 
   return resources;