diff --git a/AGENTS.md b/AGENTS.md
index cf8082c..bc4182a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,7 @@ This project manages **Vapi voice agent configurations** as code. All resources
 
 **Template-safe first run:** In a fresh clone, prefer `npm run pull -- <org> --bootstrap` to refresh `.vapi-state.<org>.json` and credential mappings without materializing the target org's resources into `resources/<org>/`. `npm run push -- <org>` will auto-run the same bootstrap sync when it detects empty or stale state for the resources being applied.
 
-**Excluding resources from sync (`.vapi-ignore`):** To prevent specific resources from being pulled at all (e.g. assistants owned by another team or legacy resources you don't want to manage), create `resources/<org>/.vapi-ignore` with gitignore-style patterns. See `resources/.vapi-ignore.example` for syntax and examples. Ignored resources are silently skipped on every pull and never tracked in state — distinct from "locally deleted" which keeps an entry in state.
+**Excluding resources from sync (`.vapi-ignore`):** To prevent specific resources from being touched in either direction (e.g. assistants owned by another team or legacy resources you don't want to manage), create `resources/<org>/.vapi-ignore` with gitignore-style patterns. See `resources/.vapi-ignore.example` for syntax and examples. The list is **bidirectional**: matched ids are skipped on pull (never written), on push and `apply` (never sent), and orphan-protected (a `--force` push will not DELETE a dashboard resource whose id matches the ignore). `--force` on push bypasses the load-filter so a deliberate override can flow through, but orphan-protect still applies. A resource that references an ignored resource (e.g. a squad pointing at `assistants/foo` while `assistants/foo` is ignored) is a validation ERROR — `--strict` push aborts before any API call.
 
 **Learnings & recipes:** Before configuring resources or debugging issues, read the relevant file in **`docs/learnings/`**. Load only what you need:
 
diff --git a/docs/learnings/simulations.md b/docs/learnings/simulations.md
index f9a37bd..2a19bf8 100644
--- a/docs/learnings/simulations.md
+++ b/docs/learnings/simulations.md
@@ -356,7 +356,7 @@ Returns the org's voice-simulation concurrency budget:
 
 **Why it matters for gitops:** in a freshly-scaffolded org (no local `simulations/personalities/` directory), the engine sees these 7 personalities as orphans on every push — "exist on the dashboard, not in local files." Without `--force` this is just log noise. With `--force`, the push halts on the FIRST delete attempt against an immortal default and exits non-zero, before reaching any legitimate orphans you actually wanted to clean.
 
-**Also note:** `.vapi-ignore` does **not** suppress these from the "pending deletions" warning. `matchesIgnore` is only called during pull operations (`src/pull.ts:695`), not during the push-time deletion-detection sweep. Adding `simulations/personalities/**` to `.vapi-ignore` quiets future pulls from materializing the defaults locally, but the push warning persists.
+**Also note:** `.vapi-ignore` is now **bidirectional** (symmetric on pull, push, and orphan-detect). Adding `simulations/personalities/**` to `.vapi-ignore` quiets future pulls from materializing the defaults locally AND orphan-protects them: ignored ids are excluded from the "pending deletions" sweep and a `🚫 personalities/<id> retained (matched .vapi-ignore — orphan-protected)` line is emitted instead. `--force` does NOT override this — the orphan-protect always wins. A resource that references an ignored resource is a hard validation error; `--strict` push aborts before any API call.
 
 **Recommendations:**
 1. **Skip `--force` against fresh orgs** that haven't had their stock fixtures touched. The pending-deletions warning is harmless without `--force`.
diff --git a/docs/learnings/yaml-conventions.md b/docs/learnings/yaml-conventions.md
index b8c58b1..2efc2d5 100644
--- a/docs/learnings/yaml-conventions.md
+++ b/docs/learnings/yaml-conventions.md
@@ -187,6 +187,14 @@ The blank line after `---` is conventional; the strict requirement is just that
 
 `.vapi-ignore` lives at `resources/<org>/.vapi-ignore` and excludes specific resources from pull and push so the dashboard stays the source of truth for them. See `AGENTS.md` (line 13) for the basic gitignore-style syntax.
 
+The list is **bidirectional**:
+
+- **Pull** skips matched ids (never writes them to disk, never tracks them in state).
+- **Push** (and `apply`) skips matched ids in the load pass — they are filtered out before drift detection, validation, or any API call.
+- **Orphan-detect** during push honors the list: a `--force` push will NOT silently DELETE a dashboard resource whose id matches the ignore, even if the state file maps it. Operators see a `🚫 <type>/<id> retained (matched .vapi-ignore — orphan-protected)` line so the retention is visible.
+- **`--force`** on push bypasses the load-filter so a deliberate override can flow through (mirrors pull's `--force`), but the orphan-protect still applies — there is no `--force` escape hatch for the delete path.
+- **References to ignored resources are a hard validation error.** A squad pointing at `assistants/foo` while `assistants/foo` is in `.vapi-ignore` produces an `❌ squads/<id> references assistants/foo, which is in .vapi-ignore` finding. `--strict` push aborts before any API call.
+
 The recovery flow when a sync surfaces "drift" you didn't expect — typically prompted by "was that not in the .vapi-ignore?":
 
 1. **Inspect first**, don't edit. Diff the file against `main` to see whether the path was already ignored:
diff --git a/improvements.md b/improvements.md
index 6ff0dfd..405492e 100644
--- a/improvements.md
+++ b/improvements.md
@@ -72,6 +72,7 @@ you which stack PR closes the row.**
 | 18  | Structured-output `name` capped at 40 chars (no warning) | Push fails partway after partial application       | None       | RESOLVED 2026-04-30 (Stack D)     |
 | 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)        |
 
 ---
 
@@ -974,6 +975,61 @@ flag that the heuristic is partial.
 
 ---
 
+## 21. `.vapi-ignore` was pull-only — push and orphan-detect ignored the list
+
+**[RESOLVED 2026-05-11] (#TBD)**
+
+**Discovered:** during the symmetric-ignore plan review — a `--force` push
+in a fresh customer org would happily DELETE a dashboard assistant that the
+repo had explicitly opted out of managing via `.vapi-ignore`, just because
+the local file was absent. Data-safety incident waiting to happen.
+
+### Problem
+
+`.vapi-ignore` (gitignore-flavored opt-out list at
+`resources/<org>/.vapi-ignore`) was honored on `pull` only. `push` and
+`apply` loaded all on-disk resources unconditionally, validated them, and
+sent them. Orphan-detect computed "in state but not in local files" without
+consulting the ignore list, so a state-mapped resource whose local file had
+been removed would be queued for DELETE under `--force` — even when its id
+was explicitly listed in `.vapi-ignore`.
+
+### Current behavior (Verified)
+
+- `src/resources.ts` `loadResources()` accepts `{ ignorePatterns }`; matched
+  ids emit `🚫 <id> (matched .vapi-ignore: <pattern>)` and are filtered out
+  before duplicate detection or parsing.
+- `src/push.ts` reads `const ignorePatterns = FORCE_DELETE ? [] : loadIgnorePatterns()`
+  and passes it into every `loadResources` call. `--force` bypasses the
+  load-filter for deliberate overrides.
+- `src/delete.ts` `findOrphanedResources()` accepts an `ignoredIds: Set<string>`;
+  matched ids are excluded from the orphan list. `deleteOrphanedResources`
+  computes the matched set per type and emits
+  `🚫 <type>/<id> retained (matched .vapi-ignore — orphan-protected)` so the
+  retention is visible. Orphan-protect ALWAYS honors the list — `--force`
+  does not bypass it.
+- `src/validate.ts` `validateNoIgnoredReferences()` walks each loaded
+  resource's referenced ids and emits an `error`-severity finding for any
+  ref pointing at an ignored id. `--strict` push aborts before any API call.
+
+### Risk
+
+Silent dashboard deletion of a resource the repo had explicitly declined to
+manage. Hardest possible class of mistake to recover from in production.
+
+### Resolution
+
+Symmetric load-filter + orphan-protect + reference validator, with `--force`
+bypassing the load-filter but never bypassing orphan-protect. Test coverage
+in `tests/vapi-ignore-push.test.ts` (T1–T5 spawn-fixture integration tests +
+in-process unit tests for each helper).
+
+### Status
+
+RESOLVED 2026-05-11 (#TBD — PR number updates when opened).
+
+---
+
 ## Out of scope (intentionally not improvements)
 
 - **State file is identity-only and not git-ignored.** It's intentionally
diff --git a/resources/.vapi-ignore.example b/resources/.vapi-ignore.example
index 0e050a9..3f63ccd 100644
--- a/resources/.vapi-ignore.example
+++ b/resources/.vapi-ignore.example
@@ -1,7 +1,20 @@
 # .vapi-ignore — explicit opt-out for resources this repo does NOT manage.
 #
-# Resources matching any pattern below are skipped during `npm run pull --
-# <org>` — never written to disk, never tracked in state. Use this for:
+# Matched resources are skipped in BOTH directions:
+#   - `npm run pull -- <org>` never writes them to disk / tracks them.
+#   - `npm run push -- <org>` (and `npm run apply`) skips them during the
+#     load pass; ids matching the ignore list are filtered out before
+#     drift detection, validation, or any API call. Orphan-detection ALSO
+#     honors the list — a `--force` push will not silently DELETE a
+#     dashboard resource just because its local file is absent and its
+#     id matches `.vapi-ignore`.
+#   - `--force` on push bypasses the load-filter (so a deliberate override
+#     can flow through) BUT the orphan-protect still applies.
+#   - A resource that references an ignored resource (e.g. a squad
+#     pointing at `assistants/foo` while `assistants/foo` is ignored) is
+#     a validation ERROR — `--strict` push aborts before any API call.
+#
+# Use this for:
 #   - Resources owned by another team or repo
 #   - Legacy/broken resources you don't want to touch
 #   - Resource types you don't care about (e.g. an entire `simulations/**`)
diff --git a/src/apply.ts b/src/apply.ts
index 83691dc..86acb0e 100644
--- a/src/apply.ts
+++ b/src/apply.ts
@@ -1,5 +1,5 @@
 import { execSync } from "child_process";
-import { join, dirname, resolve } from "path";
+import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/src/call.ts b/src/call.ts
index 3f62f93..7c230bd 100644
--- a/src/call.ts
+++ b/src/call.ts
@@ -1,9 +1,9 @@
-import { existsSync, readFileSync } from "fs";
-import { join, dirname, resolve } from "path";
-import { fileURLToPath } from "url";
 import { execSync } from "child_process";
-import * as readline from "readline";
+import { existsSync, readFileSync } from "fs";
 import { createRequire } from "module";
+import { dirname, join, resolve } from "path";
+import * as readline from "readline";
+import { fileURLToPath } from "url";
 import type { Environment, StateFile } from "./types.ts";
 
 const require = createRequire(import.meta.url);
diff --git a/src/cleanup.ts b/src/cleanup.ts
index 321c0b8..2492ca1 100644
--- a/src/cleanup.ts
+++ b/src/cleanup.ts
@@ -1,6 +1,6 @@
 import { resolve } from "path";
 import { fileURLToPath } from "url";
-import { VAPI_ENV, VAPI_BASE_URL, VAPI_TOKEN } from "./config.ts";
+import { VAPI_BASE_URL, VAPI_ENV, VAPI_TOKEN } from "./config.ts";
 import { loadState } from "./state.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/src/config.ts b/src/config.ts
index ab6eb69..fd952a9 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "fs";
-import { join, basename, dirname, resolve, relative } from "path";
+import { basename, dirname, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import type { Environment, ResourceType } from "./types.ts";
 import { VALID_RESOURCE_TYPES } from "./types.ts";
diff --git a/src/delete.ts b/src/delete.ts
index 492ef33..24497c0 100644
--- a/src/delete.ts
+++ b/src/delete.ts
@@ -1,13 +1,14 @@
-import { vapiDelete, VapiApiError } from "./api.ts";
-import { FORCE_DELETE } from "./config.ts";
+import { VapiApiError, vapiDelete } from "./api.ts";
+import { FORCE_DELETE, loadIgnorePatterns, matchesIgnore } from "./config.ts";
 import { extractReferencedIds } from "./resolver.ts";
+import { FOLDER_MAP } from "./resources.ts";
 import type {
-  ResourceFile,
-  ResourceState,
-  StateFile,
   LoadedResources,
   OrphanedResource,
+  ResourceFile,
+  ResourceState,
   ResourceType,
+  StateFile,
 } from "./types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -17,18 +18,45 @@ import type {
 export function findOrphanedResources(
   loadedResourceIds: string[],
   stateResourceIds: Record<string, ResourceState>,
+  ignoredIds?: Set<string>,
 ): OrphanedResource[] {
   const orphaned: OrphanedResource[] = [];
 
   for (const [resourceId, entry] of Object.entries(stateResourceIds)) {
-    if (!loadedResourceIds.includes(resourceId)) {
-      orphaned.push({ resourceId, uuid: entry.uuid });
-    }
+    if (loadedResourceIds.includes(resourceId)) continue;
+    // Data-safety: an id absent from local files BUT listed in .vapi-ignore
+    // is an opt-out, not an orphan. Excluding here prevents `--force` push
+    // from silently DELETE'ing dashboard resources the repo has explicitly
+    // declined to manage.
+    if (ignoredIds?.has(resourceId)) continue;
+    orphaned.push({ resourceId, uuid: entry.uuid });
   }
 
   return orphaned;
 }
 
+// Compute the set of state-tracked ids that match the current .vapi-ignore
+// for a given resource type. Used by `deleteOrphanedResources` to wire
+// orphan-protect and to emit the "retained" log lines.
+function computeIgnoredIds(
+  type: ResourceType,
+  stateSection: Record<string, ResourceState>,
+  patterns: string[],
+): { ignored: Set<string>; matched: Array<{ id: string; pattern: string }> } {
+  const ignored = new Set<string>();
+  const matched: Array<{ id: string; pattern: string }> = [];
+  if (patterns.length === 0) return { ignored, matched };
+  const folder = FOLDER_MAP[type];
+  for (const resourceId of Object.keys(stateSection)) {
+    const pattern = matchesIgnore(folder, resourceId, patterns);
+    if (pattern) {
+      ignored.add(resourceId);
+      matched.push({ id: resourceId, pattern });
+    }
+  }
+  return { ignored, matched };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Reference Checking - Find resources that reference a given resource
 // ─────────────────────────────────────────────────────────────────────────────
@@ -158,62 +186,122 @@ export async function deleteOrphanedResources(
   const shouldCheck = (type: ResourceType) =>
     !typesToDelete || typesToDelete.includes(type);
 
+  // Orphan-protect: always honor .vapi-ignore here, even under `--force`,
+  // so an opt-out can't be silently DELETEd.
+  const patterns = loadIgnorePatterns();
+  const ignoredByType: Record<
+    ResourceType,
+    { ignored: Set<string>; matched: Array<{ id: string; pattern: string }> }
+  > = {
+    tools: computeIgnoredIds("tools", state.tools, patterns),
+    structuredOutputs: computeIgnoredIds(
+      "structuredOutputs",
+      state.structuredOutputs,
+      patterns,
+    ),
+    assistants: computeIgnoredIds("assistants", state.assistants, patterns),
+    squads: computeIgnoredIds("squads", state.squads, patterns),
+    personalities: computeIgnoredIds(
+      "personalities",
+      state.personalities,
+      patterns,
+    ),
+    scenarios: computeIgnoredIds("scenarios", state.scenarios, patterns),
+    simulations: computeIgnoredIds("simulations", state.simulations, patterns),
+    simulationSuites: computeIgnoredIds(
+      "simulationSuites",
+      state.simulationSuites,
+      patterns,
+    ),
+    evals: computeIgnoredIds("evals", state.evals, patterns),
+  };
+
+  const retainedLogLines: string[] = [];
+  for (const [type, { matched }] of Object.entries(ignoredByType) as Array<
+    [ResourceType, (typeof ignoredByType)[ResourceType]]
+  >) {
+    for (const { id } of matched) {
+      // Only emit the retained line when the id WOULD have been an orphan
+      // (i.e., not present in the loaded set). A still-loaded id is not at
+      // risk of orphan deletion and logging it would be noise.
+      const loadedIds = loadedResources[type].map((r) => r.resourceId);
+      if (!loadedIds.includes(id)) {
+        retainedLogLines.push(
+          `  🚫 ${type}/${id} retained (matched .vapi-ignore — orphan-protected)`,
+        );
+      }
+    }
+  }
+
   // Find orphaned resources (only for applicable types)
   const orphanedTools = shouldCheck("tools")
     ? findOrphanedResources(
         loadedResources.tools.map((t) => t.resourceId),
         state.tools,
+        ignoredByType.tools.ignored,
       )
     : [];
   const orphanedOutputs = shouldCheck("structuredOutputs")
     ? findOrphanedResources(
         loadedResources.structuredOutputs.map((o) => o.resourceId),
         state.structuredOutputs,
+        ignoredByType.structuredOutputs.ignored,
       )
     : [];
   const orphanedAssistants = shouldCheck("assistants")
     ? findOrphanedResources(
         loadedResources.assistants.map((a) => a.resourceId),
         state.assistants,
+        ignoredByType.assistants.ignored,
       )
     : [];
   const orphanedSquads = shouldCheck("squads")
     ? findOrphanedResources(
         loadedResources.squads.map((s) => s.resourceId),
         state.squads,
+        ignoredByType.squads.ignored,
       )
     : [];
   const orphanedPersonalities = shouldCheck("personalities")
     ? findOrphanedResources(
         loadedResources.personalities.map((p) => p.resourceId),
         state.personalities,
+        ignoredByType.personalities.ignored,
       )
     : [];
   const orphanedScenarios = shouldCheck("scenarios")
     ? findOrphanedResources(
         loadedResources.scenarios.map((s) => s.resourceId),
         state.scenarios,
+        ignoredByType.scenarios.ignored,
       )
     : [];
   const orphanedSimulations = shouldCheck("simulations")
     ? findOrphanedResources(
         loadedResources.simulations.map((s) => s.resourceId),
         state.simulations,
+        ignoredByType.simulations.ignored,
       )
     : [];
   const orphanedSimulationSuites = shouldCheck("simulationSuites")
     ? findOrphanedResources(
         loadedResources.simulationSuites.map((s) => s.resourceId),
         state.simulationSuites,
+        ignoredByType.simulationSuites.ignored,
       )
     : [];
   const orphanedEvals = shouldCheck("evals")
     ? findOrphanedResources(
         loadedResources.evals.map((e) => e.resourceId),
         state.evals,
+        ignoredByType.evals.ignored,
       )
     : [];
 
+  if (retainedLogLines.length > 0) {
+    for (const line of retainedLogLines) console.log(line);
+  }
+
   // Collect all orphaned resources (in reverse dependency order for deletion)
   const allOrphaned = [
     ...orphanedEvals.map((r) => ({
diff --git a/src/drift.ts b/src/drift.ts
index df8392f..e9e7249 100644
--- a/src/drift.ts
+++ b/src/drift.ts
@@ -18,8 +18,8 @@
 // has nothing to compare against — only PATCH (update) is drift-sensitive.
 // ─────────────────────────────────────────────────────────────────────────────
 
-import { hashPayload } from "./state-serialize.ts";
 import { VAPI_BASE_URL, VAPI_TOKEN } from "./config.ts";
+import { hashPayload } from "./state-serialize.ts";
 import type { ResourceState } from "./types.ts";
 
 export interface DriftCheckResult {
diff --git a/src/index.ts b/src/index.ts
index 16e0e13..ea4c9e6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,9 +1,10 @@
 // Re-export shared modules for easy importing
 // Note: apply.ts and pull.ts are entry points with main() functions, not re-exported here
-export * from "./types.ts";
-export * from "./config.ts";
+
 export * from "./api.ts";
-export * from "./state.ts";
-export * from "./resources.ts";
-export * from "./resolver.ts";
+export * from "./config.ts";
 export * from "./delete.ts";
+export * from "./resolver.ts";
+export * from "./resources.ts";
+export * from "./state.ts";
+export * from "./types.ts";
diff --git a/src/interactive.ts b/src/interactive.ts
index 28c58cf..1ae4662 100644
--- a/src/interactive.ts
+++ b/src/interactive.ts
@@ -1,8 +1,8 @@
+import { confirm, select } from "@inquirer/prompts";
 import { execSync } from "child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "fs";
-import { join, dirname, relative, extname } from "path";
+import { dirname, extname, join, relative } from "path";
 import { fileURLToPath } from "url";
-import { select, confirm } from "@inquirer/prompts";
 import searchableCheckbox, { BACK_SENTINEL } from "./searchableCheckbox.js";
 import type { StateFile } from "./types.ts";
 
diff --git a/src/pull.ts b/src/pull.ts
index 1af43b8..ac298b9 100644
--- a/src/pull.ts
+++ b/src/pull.ts
@@ -1,23 +1,23 @@
 import { execSync } from "child_process";
 import { existsSync, readdirSync, statSync } from "fs";
 import { mkdir, writeFile } from "fs/promises";
-import { join, dirname, relative, resolve } from "path";
+import { dirname, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import { stringify } from "yaml";
 import {
-  VAPI_ENV,
-  VAPI_BASE_URL,
-  VAPI_TOKEN,
-  RESOURCES_DIR,
-  BASE_DIR,
   APPLY_FILTER,
+  BASE_DIR,
   BOOTSTRAP_SYNC,
   loadIgnorePatterns,
   matchesIgnore,
+  RESOURCES_DIR,
+  VAPI_BASE_URL,
+  VAPI_ENV,
+  VAPI_TOKEN,
 } from "./config.ts";
-import { hashPayload, loadState, saveState, upsertState } from "./state.ts";
 import { credentialReverseMap, replaceCredentialRefs } from "./credentials.ts";
-import type { ResourceState, StateFile, ResourceType } from "./types.ts";
+import { hashPayload, loadState, saveState, upsertState } from "./state.ts";
+import type { ResourceState, ResourceType, StateFile } from "./types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
diff --git a/src/push.ts b/src/push.ts
index 536fddd..450b6d5 100644
--- a/src/push.ts
+++ b/src/push.ts
@@ -1,26 +1,31 @@
 import { resolve } from "path";
 import { fileURLToPath } from "url";
-import { vapiRequest, VapiApiError, getDryRunCounts } from "./api.ts";
+import { getDryRunCounts, VapiApiError, vapiRequest } from "./api.ts";
 import {
-  VAPI_ENV,
-  VAPI_BASE_URL,
-  FORCE_DELETE,
-  DRY_RUN,
-  STRICT_VALIDATION,
-  OVERWRITE_DRIFT,
   APPLY_FILTER,
   BASE_DIR,
+  DRY_RUN,
+  FORCE_DELETE,
+  loadIgnorePatterns,
+  OVERWRITE_DRIFT,
   removeExcludedKeys,
+  STRICT_VALIDATION,
+  VAPI_BASE_URL,
+  VAPI_ENV,
 } from "./config.ts";
-import { summarizeFindings, validateResources } from "./validate.ts";
-import { checkDriftForUpdate } from "./drift.ts";
-import { writeSnapshot } from "./snapshot.ts";
-import { mergeScoped } from "./state-merge.ts";
 import {
   extractResourceName,
   findExistingResourceByName,
   type RemoteResource,
 } from "./dep-dedup.ts";
+import { checkDriftForUpdate } from "./drift.ts";
+import { writeSnapshot } from "./snapshot.ts";
+import { mergeScoped } from "./state-merge.ts";
+import {
+  summarizeFindings,
+  validateNoIgnoredReferences,
+  validateResources,
+} from "./validate.ts";
 
 // Map a resource label to its state-file key. Used for snapshotting —
 // snapshot directories are keyed by the same names the state file uses.
@@ -34,22 +39,23 @@ const RESOURCE_LABEL_TO_TYPE: Record<string, ResourceType> = {
   simulation: "simulations",
   "simulation suite": "simulationSuites",
 };
-import { hashPayload, loadState, saveState, upsertState } from "./state.ts";
-import { loadResources, loadSingleResource, FOLDER_MAP } from "./resources.ts";
+
+import { credentialForwardMap, replaceCredentialRefs } from "./credentials.ts";
+import { deleteOrphanedResources } from "./delete.ts";
 import { fetchAllResources, resourceIdMatchesName, runPull } from "./pull.ts";
 import {
-  resolveReferences,
-  resolveAssistantIds,
   extractReferencedIds,
+  resolveAssistantIds,
+  resolveReferences,
 } from "./resolver.ts";
-import { credentialForwardMap, replaceCredentialRefs } from "./credentials.ts";
-import { deleteOrphanedResources } from "./delete.ts";
+import { FOLDER_MAP, loadResources, loadSingleResource } from "./resources.ts";
+import { hashPayload, loadState, saveState, upsertState } from "./state.ts";
 import type {
+  LoadedResources,
   ResourceFile,
-  StateFile,
-  ResourceType,
   ResourceState,
-  LoadedResources,
+  ResourceType,
+  StateFile,
 } from "./types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1297,23 +1303,52 @@ async function main(): Promise<void> {
   // have been created on the remote, we still need their UUIDs recorded locally
   // — otherwise the next run creates duplicates.
   try {
-    // Load all resources (we need them for reference resolution and filtering)
+    // Load all resources (we need them for reference resolution and filtering).
+    // `.vapi-ignore` is symmetric with pull: matched ids are filtered out
+    // before validation, drift check, and apply. `--force` bypasses the
+    // load-filter (so deliberate overrides flow through); the orphan-protect
+    // pass inside `deleteOrphanedResources` ALWAYS honors the ignore list so
+    // 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");
-    const allToolsRaw = await loadResources<Record<string, unknown>>("tools");
-    const allStructuredOutputsRaw =
-      await loadResources<Record<string, unknown>>("structuredOutputs");
-    const allAssistantsRaw =
-      await loadResources<Record<string, unknown>>("assistants");
-    const allSquadsRaw = await loadResources<Record<string, unknown>>("squads");
-    const allPersonalitiesRaw =
-      await loadResources<Record<string, unknown>>("personalities");
-    const allScenariosRaw =
-      await loadResources<Record<string, unknown>>("scenarios");
-    const allSimulationsRaw =
-      await loadResources<Record<string, unknown>>("simulations");
-    const allSimulationSuitesRaw =
-      await loadResources<Record<string, unknown>>("simulationSuites");
-    const allEvalsRaw = await loadResources<Record<string, unknown>>("evals");
+    const ignorePatterns = FORCE_DELETE ? [] : loadIgnorePatterns();
+    const loadOpts = { ignorePatterns };
+    const allToolsRaw = await loadResources<Record<string, unknown>>(
+      "tools",
+      loadOpts,
+    );
+    const allStructuredOutputsRaw = await loadResources<
+      Record<string, unknown>
+    >("structuredOutputs", loadOpts);
+    const allAssistantsRaw = await loadResources<Record<string, unknown>>(
+      "assistants",
+      loadOpts,
+    );
+    const allSquadsRaw = await loadResources<Record<string, unknown>>(
+      "squads",
+      loadOpts,
+    );
+    const allPersonalitiesRaw = await loadResources<Record<string, unknown>>(
+      "personalities",
+      loadOpts,
+    );
+    const allScenariosRaw = await loadResources<Record<string, unknown>>(
+      "scenarios",
+      loadOpts,
+    );
+    const allSimulationsRaw = await loadResources<Record<string, unknown>>(
+      "simulations",
+      loadOpts,
+    );
+    const allSimulationSuitesRaw = await loadResources<Record<string, unknown>>(
+      "simulationSuites",
+      loadOpts,
+    );
+    const allEvalsRaw = await loadResources<Record<string, unknown>>(
+      "evals",
+      loadOpts,
+    );
 
     const loadedResources: LoadedResources = {
       tools: allToolsRaw,
@@ -1334,7 +1369,14 @@ async function main(): Promise<void> {
     // an otherwise-good push. With --strict, any error-severity finding aborts
     // before any API call.
     console.log("\n🔎 Running validators...");
-    const findings = validateResources(loadedResources);
+    const findings = [
+      ...validateResources(loadedResources),
+      // Cross-ignore reference check uses the user-facing ignore list (NOT
+      // the FORCE_DELETE-shadowed `ignorePatterns`) — even under `--force`,
+      // a config that references an ignored resource is a contradiction the
+      // operator should see.
+      ...validateNoIgnoredReferences(loadedResources, loadIgnorePatterns()),
+    ];
     if (findings.length > 0) {
       console.log(summarizeFindings(findings));
     } else {
diff --git a/src/resources.ts b/src/resources.ts
index 17963b8..2421a38 100644
--- a/src/resources.ts
+++ b/src/resources.ts
@@ -1,10 +1,19 @@
-import { parse as parseYaml } from "yaml";
-import { readdir, readFile, stat } from "fs/promises";
-import { join, extname, relative, resolve, dirname } from "path";
 import { existsSync } from "fs";
-import { RESOURCES_DIR, BASE_DIR } from "./config.ts";
+import { readdir, readFile, stat } from "fs/promises";
+import { dirname, extname, join, relative, resolve } from "path";
+import { parse as parseYaml } from "yaml";
+import { BASE_DIR, matchesIgnore, RESOURCES_DIR } from "./config.ts";
 import type { ResourceFile, ResourceType } from "./types.ts";
 
+// Options bag for the load functions. `ignorePatterns` is the symmetric
+// counterpart to pull's filter: when present, ids matching any pattern are
+// dropped from the returned array (with a skip-log) before any caller sees
+// them. Push wires this from `loadIgnorePatterns()`; pass `[]` (or omit) to
+// preserve the pre-change behavior.
+export interface LoadOptions {
+  ignorePatterns?: string[];
+}
+
 // Map resource types to their folder paths (relative to resources/)
 export const FOLDER_MAP: Record<ResourceType, string> = {
   tools: "tools",
@@ -108,9 +117,11 @@ async function scanDirectory(dir: string, baseDir: string): Promise<string[]> {
 
 export async function loadResources<T>(
   type: ResourceType,
+  options: LoadOptions = {},
 ): Promise<ResourceFile<T>[]> {
   const folderPath = FOLDER_MAP[type];
   const resourceDir = join(RESOURCES_DIR, folderPath);
+  const ignorePatterns = options.ignorePatterns ?? [];
 
   if (!existsSync(resourceDir)) {
     console.log(`📁 No ${type} directory found, skipping...`);
@@ -130,6 +141,17 @@ export async function loadResources<T>(
     const relativePath = relative(resourceDir, filePath);
     const resourceId = relativePath.slice(0, -ext.length);
 
+    // Symmetric ignore: drop matched ids before duplicate-detection and
+    // parsing so the rest of the pipeline never sees the file. Caller passes
+    // `[]` (or omits) to opt out — preserves the pre-change behavior.
+    if (ignorePatterns.length > 0) {
+      const matched = matchesIgnore(folderPath, resourceId, ignorePatterns);
+      if (matched) {
+        console.log(`  🚫 ${resourceId} (matched .vapi-ignore: ${matched})`);
+        continue;
+      }
+    }
+
     // Check for duplicate resourceIds (e.g., foo.yml and foo.yaml in same directory)
     if (seenIds.has(resourceId)) {
       throw new Error(
@@ -242,6 +264,7 @@ export function getResourceTypeFromPath(filePath: string): ResourceType | null {
  */
 export async function loadSingleResource(
   filePath: string,
+  options: LoadOptions = {},
 ): Promise<{ type: ResourceType; resource: ResourceFile } | null> {
   // Resolve path (could be relative to cwd or absolute)
   const absolutePath = resolve(filePath);
@@ -264,6 +287,15 @@ export async function loadSingleResource(
   const relativePath = relative(resourceDir, absolutePath);
   const resourceId = relativePath.slice(0, -ext.length);
 
+  const ignorePatterns = options.ignorePatterns ?? [];
+  if (ignorePatterns.length > 0) {
+    const matched = matchesIgnore(folderPath, resourceId, ignorePatterns);
+    if (matched) {
+      console.log(`  🚫 ${resourceId} (matched .vapi-ignore: ${matched})`);
+      return null;
+    }
+  }
+
   let data: Record<string, unknown>;
 
   if (ext === ".ts") {
diff --git a/src/searchableCheckbox.ts b/src/searchableCheckbox.ts
index daed7a8..a96ba24 100644
--- a/src/searchableCheckbox.ts
+++ b/src/searchableCheckbox.ts
@@ -1,11 +1,11 @@
 import {
   createPrompt,
-  useState,
-  useKeypress,
-  isUpKey,
   isDownKey,
-  isSpaceKey,
   isEnterKey,
+  isSpaceKey,
+  isUpKey,
+  useKeypress,
+  useState,
 } from "@inquirer/core";
 
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/src/setup.ts b/src/setup.ts
index 432c0af..1e7ae62 100644
--- a/src/setup.ts
+++ b/src/setup.ts
@@ -1,9 +1,9 @@
+import { confirm, input, password, select } from "@inquirer/prompts";
+import { execSync } from "child_process";
 import { existsSync, readdirSync } from "fs";
-import { mkdir, writeFile, rm } from "fs/promises";
-import { join, dirname } from "path";
+import { mkdir, rm, writeFile } from "fs/promises";
+import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { execSync } from "child_process";
-import { input, password, confirm, select } from "@inquirer/prompts";
 import searchableCheckbox, { BACK_SENTINEL } from "./searchableCheckbox.js";
 
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/src/sim.ts b/src/sim.ts
index fabf07e..8b29344 100644
--- a/src/sim.ts
+++ b/src/sim.ts
@@ -5,7 +5,7 @@
 // here (rather than importing from `config.ts`) for the same reason.
 
 import { existsSync, readFileSync } from "fs";
-import { join, dirname } from "path";
+import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import type { StateFile } from "./types.ts";
 
diff --git a/src/snapshot.ts b/src/snapshot.ts
index b7dcb1d..30153bf 100644
--- a/src/snapshot.ts
+++ b/src/snapshot.ts
@@ -16,7 +16,7 @@
 // ─────────────────────────────────────────────────────────────────────────────
 
 import { existsSync } from "fs";
-import { mkdir, readFile, readdir, writeFile } from "fs/promises";
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
 import { join } from "path";
 import { sortedKeysReplacer } from "./state-serialize.ts";
 
diff --git a/src/validate-cmd.ts b/src/validate-cmd.ts
index e4f9f08..f6ab527 100644
--- a/src/validate-cmd.ts
+++ b/src/validate-cmd.ts
@@ -7,10 +7,10 @@
 
 import { resolve } from "path";
 import { fileURLToPath } from "url";
-import { VAPI_ENV, VAPI_BASE_URL } from "./config.ts";
+import { VAPI_BASE_URL, VAPI_ENV } from "./config.ts";
 import { loadResources } from "./resources.ts";
-import { summarizeFindings, validateResources } from "./validate.ts";
 import type { LoadedResources } from "./types.ts";
+import { summarizeFindings, validateResources } from "./validate.ts";
 
 async function main(): Promise<void> {
   console.log(
diff --git a/src/validate.ts b/src/validate.ts
index cb57133..8e0f68e 100644
--- a/src/validate.ts
+++ b/src/validate.ts
@@ -14,6 +14,9 @@
 //   - Per-provider voice schema                → improvements #9
 // ─────────────────────────────────────────────────────────────────────────────
 
+import { matchesIgnore } from "./config.ts";
+import { extractReferencedIds } from "./resolver.ts";
+import { FOLDER_MAP } from "./resources.ts";
 import type { LoadedResources, ResourceFile, ResourceType } from "./types.ts";
 
 export type ValidationSeverity = "warn" | "error";
@@ -416,6 +419,84 @@ function checkVoiceSchemas(resources: LoadedResources): ValidationFinding[] {
   return findings;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Check 6: References to ignored resources
+//
+// A config that references a resource matched by `.vapi-ignore` is internally
+// inconsistent — at push time the reference cannot be resolved (the ignored
+// resource was filtered out before resolver ran) and the silent-drop pattern
+// in resolver.ts (`.filter(id => id !== null)`) used to mask the problem.
+// Promote it to a blocking validation finding.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const REF_TYPE_KEYS: Array<{
+  refKey: keyof ReturnType<typeof extractReferencedIds>;
+  refType: ResourceType;
+}> = [
+  { refKey: "tools", refType: "tools" },
+  { refKey: "structuredOutputs", refType: "structuredOutputs" },
+  { refKey: "assistants", refType: "assistants" },
+  { refKey: "personalities", refType: "personalities" },
+  { refKey: "scenarios", refType: "scenarios" },
+  { refKey: "simulations", refType: "simulations" },
+];
+
+const RESOURCE_TYPES_WITH_REFS: ResourceType[] = [
+  "tools",
+  "structuredOutputs",
+  "assistants",
+  "squads",
+  "personalities",
+  "scenarios",
+  "simulations",
+  "simulationSuites",
+  "evals",
+];
+
+function checkResourceRefs(
+  resource: ResourceFile,
+  type: ResourceType,
+  ignorePatterns: string[],
+): ValidationFinding[] {
+  const findings: ValidationFinding[] = [];
+  const refs = extractReferencedIds(resource.data as Record<string, unknown>);
+
+  for (const { refKey, refType } of REF_TYPE_KEYS) {
+    const folder = FOLDER_MAP[refType];
+    for (const refId of refs[refKey]) {
+      if (!refId) continue;
+      const matched = matchesIgnore(folder, refId, ignorePatterns);
+      if (!matched) continue;
+      findings.push({
+        severity: "error",
+        type,
+        resourceId: resource.resourceId,
+        rule: "reference-to-ignored",
+        message:
+          `❌ ${type}/${resource.resourceId} references ${refType}/${refId}, ` +
+          `which is in .vapi-ignore (pattern: ${matched})`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function validateNoIgnoredReferences(
+  loaded: LoadedResources,
+  ignorePatterns: string[],
+): ValidationFinding[] {
+  if (ignorePatterns.length === 0) return [];
+
+  const findings: ValidationFinding[] = [];
+  for (const type of RESOURCE_TYPES_WITH_REFS) {
+    for (const resource of loaded[type]) {
+      findings.push(...checkResourceRefs(resource, type, ignorePatterns));
+    }
+  }
+  return findings;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Public entry: run all checks
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/tests/clean-resource.test.ts b/tests/clean-resource.test.ts
index 646412c..a7225ba 100644
--- a/tests/clean-resource.test.ts
+++ b/tests/clean-resource.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 
 // Regression tests for P0-3.
 //
diff --git a/tests/cleanup-safety.test.ts b/tests/cleanup-safety.test.ts
index c488104..0575aba 100644
--- a/tests/cleanup-safety.test.ts
+++ b/tests/cleanup-safety.test.ts
@@ -1,15 +1,15 @@
-import test from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import {
+  cpSync,
   mkdtempSync,
-  writeFileSync,
   rmSync,
-  cpSync,
   symlinkSync,
+  writeFileSync,
 } from "node:fs";
-import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
 import { fileURLToPath } from "node:url";
 
 // Regression tests for P0-4.
diff --git a/tests/cli-arg-parsing.test.ts b/tests/cli-arg-parsing.test.ts
index 39ef84a..8066ddb 100644
--- a/tests/cli-arg-parsing.test.ts
+++ b/tests/cli-arg-parsing.test.ts
@@ -1,15 +1,15 @@
-import test from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import {
+  cpSync,
   mkdtempSync,
-  writeFileSync,
   rmSync,
-  cpSync,
   symlinkSync,
+  writeFileSync,
 } from "node:fs";
-import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
 import { fileURLToPath } from "node:url";
 
 // Regression tests for P0-7 (bare-id refusal half).
diff --git a/tests/credentials.test.ts b/tests/credentials.test.ts
index 59a916b..109e7d6 100644
--- a/tests/credentials.test.ts
+++ b/tests/credentials.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import { replaceCredentialRefs } from "../src/credentials.ts";
 import type { StateFile } from "../src/types.ts";
 
diff --git a/tests/dep-dedup.test.ts b/tests/dep-dedup.test.ts
index 15e8af2..40db393 100644
--- a/tests/dep-dedup.test.ts
+++ b/tests/dep-dedup.test.ts
@@ -1,10 +1,10 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import {
-  findExistingResourceByName,
-  slugify,
   extractBaseSlug,
   extractResourceName,
+  findExistingResourceByName,
+  slugify,
 } from "../src/dep-dedup.ts";
 
 // Dedup helper coverage. Verifies that bootstrap-renamed state entries and
diff --git a/tests/drift.test.ts b/tests/drift.test.ts
index 9906707..826f98c 100644
--- a/tests/drift.test.ts
+++ b/tests/drift.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import { checkPronunciationDictDrop } from "../src/state-serialize.ts";
 
 // Stack G — drift unit tests.
diff --git a/tests/path-matching.test.ts b/tests/path-matching.test.ts
index 630987f..afb82ef 100644
--- a/tests/path-matching.test.ts
+++ b/tests/path-matching.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 
 // Regression tests for P0-7.
 //
diff --git a/tests/push-dry-run.test.ts b/tests/push-dry-run.test.ts
index a4d858d..408fd0e 100644
--- a/tests/push-dry-run.test.ts
+++ b/tests/push-dry-run.test.ts
@@ -1,17 +1,17 @@
-import test from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import {
-  mkdtempSync,
-  writeFileSync,
-  rmSync,
   cpSync,
-  symlinkSync,
   existsSync,
   mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
 } from "node:fs";
-import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
 import { fileURLToPath } from "node:url";
 
 // Stack C — push --dry-run regression coverage.
diff --git a/tests/sim.test.ts b/tests/sim.test.ts
index ae6e970..7414f96 100644
--- a/tests/sim.test.ts
+++ b/tests/sim.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import { resolveSelection, resolveTarget } from "../src/sim.ts";
 import type { StateFile } from "../src/types.ts";
 
diff --git a/tests/snapshot.test.ts b/tests/snapshot.test.ts
index 8aef921..839fbd8 100644
--- a/tests/snapshot.test.ts
+++ b/tests/snapshot.test.ts
@@ -1,8 +1,8 @@
-import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
 import {
   _resetRunSnapshotDir,
   listSnapshotTimestamps,
diff --git a/tests/state-key-order.test.ts b/tests/state-key-order.test.ts
index 2009d34..3ca83ca 100644
--- a/tests/state-key-order.test.ts
+++ b/tests/state-key-order.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import { sortedKeysReplacer } from "../src/state-serialize.ts";
 
 // Stack B regression test — pin deterministic key ordering on state file
diff --git a/tests/state-merge.test.ts b/tests/state-merge.test.ts
index 7d55642..5cf2f30 100644
--- a/tests/state-merge.test.ts
+++ b/tests/state-merge.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import { mergeScoped, type TouchedSets } from "../src/state-merge.ts";
 import type { StateFile } from "../src/types.ts";
 
diff --git a/tests/state-migration.test.ts b/tests/state-migration.test.ts
index 1f985fe..f5f0ac3 100644
--- a/tests/state-migration.test.ts
+++ b/tests/state-migration.test.ts
@@ -1,5 +1,5 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import test from "node:test";
 import {
   asResourceState,
   canonicalize,
diff --git a/tests/validate.test.ts b/tests/validate.test.ts
index e19b282..0286202 100644
--- a/tests/validate.test.ts
+++ b/tests/validate.test.ts
@@ -1,6 +1,15 @@
-import test from "node:test";
 import assert from "node:assert/strict";
-import { validateResources } from "../src/validate.ts";
+import test from "node:test";
+
+// validate.ts now imports from config.ts (matchesIgnore) for the
+// reference-to-ignored validator; config.ts asserts argv[2] / VAPI_TOKEN at
+// module load. Set both before importing — same trick used in
+// tests/path-matching.test.ts and tests/vapi-ignore-push.test.ts.
+process.argv = ["node", "test", "test-fixture-org"];
+process.env.VAPI_TOKEN = process.env.VAPI_TOKEN || "test-token-not-used";
+
+const { validateResources } = await import("../src/validate.ts");
+
 import type { LoadedResources, ResourceFile } from "../src/types.ts";
 
 // Stack D — validator regression coverage. Each spec exercises one rule
diff --git a/tests/vapi-ignore-push.test.ts b/tests/vapi-ignore-push.test.ts
new file mode 100644
index 0000000..4e32b5b
--- /dev/null
+++ b/tests/vapi-ignore-push.test.ts
@@ -0,0 +1,764 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Spec for `.vapi-ignore` symmetry on push + apply.
+//
+// Today `.vapi-ignore` is pull-only. The implementer is making it symmetric
+// so push and apply also honor it. These tests pin the behavior contract
+// described in the planner output:
+//
+//   T1 — dry-run honors ignore (skip log + no PATCH/POST)
+//   T2 — --force bypasses ignore (matches pull's force flag)
+//   T3 — orphan-detect protects ignored-but-state-mapped resources
+//        (the silent-delete scenario without the fix)
+//   T4 — squad referencing an ignored assistant is a hard error
+//   T5 — explicit-file push honors ignore
+//
+// Plus in-process unit tests for the helpers the implementer will add:
+//   - loadResources back-compat when patterns are empty/omitted
+//   - findOrphanedResources excluding ignored ids
+//   - validateNoIgnoredReferences flagging cross-ignore references
+// ─────────────────────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, "..");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fixture helpers (Pattern A — spawn-fixture)
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Fixture {
+  dir: string;
+  env: string;
+  port: number;
+  worker: Worker;
+  cleanup: () => Promise<void>;
+}
+
+interface StubRoute {
+  method: string;
+  pathStartsWith: string;
+  body: unknown;
+}
+
+// Spin up a tiny HTTP stub in a Worker thread so `fetchAllResources` (called
+// from `maybeBootstrapState → getInvalidStateMappings`) can be served while
+// the main thread is blocked on `spawnSync`. An in-thread `http.createServer`
+// can't service requests during a sync spawn — the event loop is parked —
+// which is why the stub MUST run on a separate thread.
+function startStub(
+  routes: StubRoute[],
+): Promise<{ worker: Worker; port: number }> {
+  return new Promise((resolveStart, rejectStart) => {
+    const stubSource = `
+      const http = require('node:http');
+      const { parentPort, workerData } = require('node:worker_threads');
+      const routes = workerData.routes;
+      const server = http.createServer((req, res) => {
+        const url = req.url || '';
+        const method = (req.method || 'GET').toUpperCase();
+        const match = routes.find(
+          (r) => r.method === method && url.startsWith(r.pathStartsWith),
+        );
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(match ? match.body : []));
+      });
+      server.listen(0, '127.0.0.1', () => {
+        const addr = server.address();
+        const port = typeof addr === 'object' && addr ? addr.port : 0;
+        parentPort.postMessage({ type: 'listening', port });
+      });
+      parentPort.on('message', (msg) => {
+        if (msg && msg.type === 'shutdown') {
+          server.close(() => process.exit(0));
+        }
+      });
+    `;
+    const worker = new Worker(stubSource, {
+      eval: true,
+      workerData: { routes },
+    });
+    worker.once("error", rejectStart);
+    worker.on("message", (msg: { type: string; port?: number }) => {
+      if (msg.type === "listening" && typeof msg.port === "number") {
+        resolveStart({ worker, port: msg.port });
+      }
+    });
+  });
+}
+
+interface FixtureInit {
+  env?: string;
+  ignorePatterns?: string[];
+  // Map of `<folder>/<resourceId>.<ext>` → file contents (yaml/markdown).
+  resources?: Record<string, string>;
+  // Pre-populated state file content (no bootstrap path traversed if state is
+  // populated AND remote inventory matches).
+  state?: Record<string, unknown> | null;
+  // Routes the stub HTTP server should answer with non-empty bodies. Anything
+  // not listed returns `[]`.
+  stubRoutes?: StubRoute[];
+}
+
+async function setupFixture(init: FixtureInit = {}): Promise<Fixture> {
+  const env = init.env ?? "test-vapi-ignore";
+  const dir = mkdtempSync(join(tmpdir(), "vapi-ignore-test-"));
+
+  // Copy source + package.json, symlink node_modules (mirrors push-dry-run.test.ts).
+  cpSync(join(REPO_ROOT, "src"), join(dir, "src"), { recursive: true });
+  cpSync(join(REPO_ROOT, "package.json"), join(dir, "package.json"));
+  symlinkSync(
+    join(REPO_ROOT, "node_modules"),
+    join(dir, "node_modules"),
+    "dir",
+  );
+
+  // Per-env resource directory.
+  const resourceRoot = join(dir, "resources", env);
+  mkdirSync(resourceRoot, { recursive: true });
+
+  // .vapi-ignore (optional).
+  if (init.ignorePatterns && init.ignorePatterns.length > 0) {
+    writeFileSync(
+      join(resourceRoot, ".vapi-ignore"),
+      `${init.ignorePatterns.join("\n")}\n`,
+    );
+  }
+
+  // Resource files (optional). Keys look like `assistants/foo.md`.
+  for (const [relPath, contents] of Object.entries(init.resources ?? {})) {
+    const fullPath = join(resourceRoot, relPath);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, contents);
+  }
+
+  // State file (optional). When null/omitted, no state file is written —
+  // engine treats it as a fresh org.
+  if (init.state !== null && init.state !== undefined) {
+    writeFileSync(
+      join(dir, `.vapi-state.${env}.json`),
+      JSON.stringify(init.state, null, 2),
+    );
+  }
+
+  // Stub HTTP server runs in a Worker thread (see `startStub` comment).
+  const { worker, port } = await startStub(init.stubRoutes ?? []);
+
+  writeFileSync(
+    join(dir, `.env.${env}`),
+    [
+      "VAPI_TOKEN=fake-token-not-used",
+      `VAPI_BASE_URL=http://127.0.0.1:${port}`,
+      "",
+    ].join("\n"),
+  );
+
+  return {
+    dir,
+    env,
+    port,
+    worker,
+    cleanup: async () => {
+      worker.postMessage({ type: "shutdown" });
+      await new Promise<void>((res) => {
+        worker.once("exit", () => res());
+        // Safety net — if the worker doesn't exit cleanly, terminate.
+        setTimeout(() => {
+          worker
+            .terminate()
+            .then(() => res())
+            .catch(() => res());
+        }, 1000);
+      });
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+function runPush(
+  fx: Fixture,
+  extraArgs: string[],
+): { code: number | null; stdout: string; stderr: string } {
+  const result = spawnSync(
+    "node",
+    ["--import", "tsx", "src/push.ts", fx.env, "--dry-run", ...extraArgs],
+    {
+      cwd: fx.dir,
+      env: {
+        ...process.env,
+        VAPI_TOKEN: "fake-token-not-used",
+        VAPI_BASE_URL: `http://127.0.0.1:${fx.port}`,
+      },
+      encoding: "utf-8",
+      timeout: 30_000,
+    },
+  );
+  return {
+    code: result.status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+}
+
+function emptyState() {
+  return {
+    credentials: {},
+    assistants: {},
+    structuredOutputs: {},
+    tools: {},
+    squads: {},
+    personalities: {},
+    scenarios: {},
+    simulations: {},
+    simulationSuites: {},
+    evals: {},
+  };
+}
+
+const DUMMY_UUID_1 = "11111111-1111-1111-1111-111111111111";
+const DUMMY_UUID_2 = "22222222-2222-2222-2222-222222222222";
+
+const MINIMAL_ASSISTANT_MD = `---
+name: foo
+model:
+  provider: openai
+  model: gpt-4o
+voice:
+  provider: 11labs
+  voiceId: burt
+---
+
+You are foo.
+`;
+
+const MINIMAL_ASSISTANT_BAZ_MD = `---
+name: baz
+model:
+  provider: openai
+  model: gpt-4o
+voice:
+  provider: 11labs
+  voiceId: burt
+---
+
+You are baz.
+`;
+
+const SQUAD_BAR_YML = `name: bar
+members:
+  - assistantId: foo
+`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// T1 — dry-run honors .vapi-ignore (skip log + no PATCH/POST for ignored id)
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("T1: dry-run skips ignored assistants and emits the matched log line", async () => {
+  const fx = await setupFixture({
+    ignorePatterns: ["assistants/foo"],
+    resources: {
+      "assistants/foo.md": MINIMAL_ASSISTANT_MD,
+    },
+    // Pre-populated state with foo already tracked so the engine takes the
+    // PATCH path (no bootstrap pull required) and the network stub stays idle.
+    state: {
+      ...emptyState(),
+      credentials: { fake: { uuid: DUMMY_UUID_2 } },
+      assistants: { foo: { uuid: DUMMY_UUID_1 } },
+    },
+    stubRoutes: [
+      // Bootstrap precondition: list-assistants returns foo so the existing
+      // mapping passes validation and bootstrap is skipped.
+      {
+        method: "GET",
+        pathStartsWith: "/assistant",
+        body: [{ id: DUMMY_UUID_1, name: "foo" }],
+      },
+    ],
+  });
+  try {
+    const res = runPush(fx, []);
+    // Skip log must mention foo, the matched pattern, and the .vapi-ignore.
+    assert.match(
+      res.stdout,
+      /🚫.*foo.*\.vapi-ignore.*assistants\/foo/s,
+      `expected ignore-skip log; stdout=${res.stdout}\nstderr=${res.stderr}`,
+    );
+    // No PATCH/POST line should mention the ignored assistant.
+    assert.doesNotMatch(
+      res.stdout,
+      /would (PATCH|POST)[^\n]*\bfoo\b/,
+      `ignored assistant must not appear in would-PATCH/POST lines; stdout=${res.stdout}`,
+    );
+    // Engine must not have queued the API call: assistant POST/PATCH counter
+    // should be zero (no `/assistant/<uuid>` line for the ignored id).
+    assert.doesNotMatch(
+      res.stdout,
+      new RegExp(`would (PATCH|POST) /assistant/${DUMMY_UUID_1}`),
+    );
+  } finally {
+    await fx.cleanup();
+  }
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// T2 — --force bypasses .vapi-ignore (mirrors pull's force semantics at
+// pull.ts:907 — the `force` flag short-circuits the ignore check).
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("T2: --force bypasses .vapi-ignore and processes ignored resources normally", async () => {
+  const fx = await setupFixture({
+    ignorePatterns: ["assistants/foo"],
+    resources: {
+      "assistants/foo.md": MINIMAL_ASSISTANT_MD,
+    },
+    state: {
+      ...emptyState(),
+      credentials: { fake: { uuid: DUMMY_UUID_2 } },
+      assistants: { foo: { uuid: DUMMY_UUID_1 } },
+    },
+    stubRoutes: [
+      {
+        method: "GET",
+        pathStartsWith: "/assistant",
+        body: [{ id: DUMMY_UUID_1, name: "foo" }],
+      },
+    ],
+  });
+  try {
+    const res = runPush(fx, ["--force"]);
+    // Under --force the ignore is bypassed: no skip log for foo.
+    assert.doesNotMatch(
+      res.stdout,
+      /🚫[^\n]*foo[^\n]*\.vapi-ignore/,
+      `--force must bypass ignore, no skip log expected; stdout=${res.stdout}`,
+    );
+    // The assistant is now processed end-to-end: dry-run records the would-PATCH.
+    assert.match(
+      res.stdout,
+      new RegExp(`would PATCH /assistant/${DUMMY_UUID_1}`),
+      `--force must let the ignored assistant flow through; stdout=${res.stdout}\nstderr=${res.stderr}`,
+    );
+  } finally {
+    await fx.cleanup();
+  }
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// T3 — orphan-detect must protect ignored-but-state-mapped resources.
+// This is the silent-delete scenario: state file maps foo → uuid, the local
+// file has been removed, .vapi-ignore lists foo. Without the fix, push
+// --force would DELETE foo from the dashboard. With the fix, orphan-detect
+// excludes foo and emits a "retained — orphan-protected" log line.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("T3: --force does NOT delete ignored orphans (state-mapped but missing locally)", async () => {
+  const fx = await setupFixture({
+    ignorePatterns: ["assistants/foo"],
+    // No local foo.md — by today's logic, this is an orphan and --force would
+    // issue a DELETE. The fix must exclude ignored ids from orphan-detect.
+    resources: {},
+    state: {
+      ...emptyState(),
+      credentials: { fake: { uuid: DUMMY_UUID_2 } },
+      assistants: { foo: { uuid: DUMMY_UUID_1 } },
+    },
+    stubRoutes: [
+      {
+        method: "GET",
+        pathStartsWith: "/assistant",
+        body: [{ id: DUMMY_UUID_1, name: "foo" }],
+      },
+    ],
+  });
+  try {
+    const res = runPush(fx, ["--force"]);
+    // No DELETE for the ignored, orphaned-by-local-deletion resource.
+    assert.doesNotMatch(
+      res.stdout,
+      new RegExp(`would DELETE /assistant/${DUMMY_UUID_1}`),
+      `ignored orphan must NOT be queued for deletion; stdout=${res.stdout}\nstderr=${res.stderr}`,
+    );
+    // Orphan-protection log line must be present so operators see the retention.
+    assert.match(
+      res.stdout,
+      /🚫.*foo.*(retained|orphan-protected).*\.vapi-ignore/s,
+      `expected orphan-protected log line; stdout=${res.stdout}`,
+    );
+  } finally {
+    await fx.cleanup();
+  }
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// T4 — Squad referencing an ignored assistant is a HARD error (was a silent
+// drop today via resolver.ts:103-110 `.filter(id => id !== null)`).
+// The new validator must promote this to a blocking validation finding.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("T4: squad referencing an ignored assistant is a hard validation error", async () => {
+  const fx = await setupFixture({
+    ignorePatterns: ["assistants/foo"],
+    resources: {
+      "assistants/foo.md": MINIMAL_ASSISTANT_MD,
+      "squads/bar.yml": SQUAD_BAR_YML,
+    },
+    state: {
+      ...emptyState(),
+      credentials: { fake: { uuid: DUMMY_UUID_2 } },
+      assistants: { foo: { uuid: DUMMY_UUID_1 } },
+      squads: { bar: { uuid: DUMMY_UUID_2 } },
+    },
+    stubRoutes: [
+      {
+        method: "GET",
+        pathStartsWith: "/assistant",
+        body: [{ id: DUMMY_UUID_1, name: "foo" }],
+      },
+      {
+        method: "GET",
+        pathStartsWith: "/squad",
+        body: [{ id: DUMMY_UUID_2, name: "bar" }],
+      },
+    ],
+  });
+  try {
+    const res = runPush(fx, ["--strict"]);
+    // Non-zero exit on the new validator's error-severity finding.
+    assert.notEqual(
+      res.code,
+      0,
+      `expected non-zero exit code; got ${res.code}\nstdout=${res.stdout}\nstderr=${res.stderr}`,
+    );
+    // Combined output must call out the offending reference.
+    const combined = `${res.stdout}\n${res.stderr}`;
+    assert.match(
+      combined,
+      /❌[^\n]*bar[^\n]*references[^\n]*foo[^\n]*\.vapi-ignore/,
+      `expected '❌ bar references foo, which is in .vapi-ignore'; stdout=${res.stdout}\nstderr=${res.stderr}`,
+    );
+    // Engine must NOT have queued the squad write in dry-run.
+    assert.doesNotMatch(
+      res.stdout,
+      new RegExp(`would (PATCH|POST) /squad/${DUMMY_UUID_2}`),
+      `squad must not be queued when its ref is ignored; stdout=${res.stdout}`,
+    );
+  } finally {
+    await fx.cleanup();
+  }
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// T5 — Explicit-file push (APPLY_FILTER.filePaths) still honors .vapi-ignore.
+// Even when the user names baz.md directly, an ignore match wins.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("T5: explicit-file push honors .vapi-ignore (single-file mode)", async () => {
+  const fx = await setupFixture({
+    ignorePatterns: ["assistants/baz"],
+    resources: {
+      "assistants/baz.md": MINIMAL_ASSISTANT_BAZ_MD,
+    },
+    state: {
+      ...emptyState(),
+      credentials: { fake: { uuid: DUMMY_UUID_2 } },
+      assistants: { baz: { uuid: DUMMY_UUID_1 } },
+    },
+    stubRoutes: [
+      {
+        method: "GET",
+        pathStartsWith: "/assistant",
+        body: [{ id: DUMMY_UUID_1, name: "baz" }],
+      },
+    ],
+  });
+  try {
+    const res = runPush(fx, ["assistants/baz.md"]);
+    assert.match(
+      res.stdout,
+      /🚫.*baz.*\.vapi-ignore.*assistants\/baz/s,
+      `expected explicit-file skip log; stdout=${res.stdout}\nstderr=${res.stderr}`,
+    );
+    assert.doesNotMatch(
+      res.stdout,
+      new RegExp(`would (PATCH|POST) /assistant/${DUMMY_UUID_1}`),
+      `explicit-file push must still skip ignored ids; stdout=${res.stdout}`,
+    );
+  } finally {
+    await fx.cleanup();
+  }
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Unit tests (Pattern B — in-process)
+//
+// These pin the helpers the implementer is adding. config.ts calls
+// `process.exit(1)` at module load when VAPI_TOKEN / argv[2] are missing,
+// so we set both before any dynamic import (same trick as
+// `tests/path-matching.test.ts`).
+// ─────────────────────────────────────────────────────────────────────────────
+
+process.argv = ["node", "test", "test-fixture-org"];
+process.env.VAPI_TOKEN = process.env.VAPI_TOKEN || "test-token-not-used";
+
+const resources = await import("../src/resources.ts");
+const deleteModule = await import("../src/delete.ts");
+const validateModule = await import("../src/validate.ts");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// loadResources back-compat: with no patterns supplied, behaves as before.
+// With patterns, ignored files are filtered out and a "skipping" log is emitted.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("loadResources: omitted/empty ignorePatterns is a no-op (back-compat)", async () => {
+  // Build a tiny on-disk fixture matching what loadResources scans
+  // (`resources/<env>/<folder>`). Use a unique env to avoid colliding with
+  // other tests' module-level state.
+  const env = "unit-load-no-patterns";
+  const baseFixture = mkdtempSync(join(tmpdir(), "vapi-ignore-unit-"));
+  const folder = join(baseFixture, "resources", env, "assistants");
+  mkdirSync(folder, { recursive: true });
+  writeFileSync(join(folder, "alpha.md"), MINIMAL_ASSISTANT_MD);
+  writeFileSync(join(folder, "beta.md"), MINIMAL_ASSISTANT_MD);
+
+  // loadResources reads from RESOURCES_DIR which is bound to the test fixture
+  // org via process.argv at module-load time. The unit fixture needs its own
+  // working tree — easier path: just count what the helper returns when the
+  // FIXTURE matches the test-fixture-org env. The implementer will need to
+  // expose an option to override the resource root OR the test must spawn a
+  // child process. For this assertion we exercise the simpler contract: the
+  // function signature accepts `ignorePatterns` and returns the same shape
+  // (length-comparable array). The contract holds against the
+  // path-matching.test.ts pattern: dynamic-import after setting argv.
+
+  // NOTE: we can't easily redirect BASE_DIR/RESOURCES_DIR from within the same
+  // process without re-importing config.ts. The assertion below covers the
+  // shape: with no patterns, `loadResources("assistants")` returns the
+  // existing array unchanged (call twice, expect equal length).
+  rmSync(baseFixture, { recursive: true, force: true });
+
+  // Existing call signature (single arg) must still type-check and execute
+  // without throwing. We don't have an in-process fixture without colliding
+  // with config.ts's RESOURCES_DIR; treat this test as a smoke check that the
+  // import surface still exposes loadResources.
+  assert.equal(typeof resources.loadResources, "function");
+});
+
+test("loadResources: ignorePatterns parameter is supported (signature check)", () => {
+  // The implementer is adding an options bag `{ ignorePatterns }`. Until the
+  // implementation lands, this test asserts the export exists. Once it lands
+  // the implementer should expand this into a real on-disk fixture test
+  // (mirroring the integration tests above) that confirms:
+  //   1. matched files are filtered from the returned array
+  //   2. each match emits `🚫 <id> (matched .vapi-ignore: <pattern>)`
+  //   3. with `ignorePatterns: []` or undefined, the returned array is
+  //      identical to the pre-change behavior (back-compat).
+  assert.equal(typeof resources.loadResources, "function");
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// findOrphanedResources: ignored ids must be excluded from the result.
+// Pinning the contract — the implementer adds an optional `ignoredIds` arg.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("findOrphanedResources: today's signature returns orphans normally (regression baseline)", () => {
+  const loadedIds = ["alpha"];
+  const stateMap = {
+    alpha: { uuid: DUMMY_UUID_1 },
+    beta: { uuid: DUMMY_UUID_2 },
+  };
+  const orphans = deleteModule.findOrphanedResources(loadedIds, stateMap);
+  assert.deepEqual(orphans, [{ resourceId: "beta", uuid: DUMMY_UUID_2 }]);
+});
+
+test("findOrphanedResources: ignored ids are excluded from orphan list (new arg)", () => {
+  const loadedIds = ["alpha"];
+  const stateMap = {
+    alpha: { uuid: DUMMY_UUID_1 },
+    beta: { uuid: DUMMY_UUID_2 },
+  };
+  // Call with the new third arg `ignoredIds`. Until the implementation lands
+  // this will fail with "expected 2 args, got 3" or return beta-as-orphan.
+  const orphansFn = deleteModule.findOrphanedResources as unknown as (
+    loaded: string[],
+    state: Record<string, { uuid: string }>,
+    ignoredIds?: Set<string>,
+  ) => Array<{ resourceId: string; uuid: string }>;
+  const orphans = orphansFn(loadedIds, stateMap, new Set(["beta"]));
+  assert.deepEqual(
+    orphans,
+    [],
+    "beta is in state but ignored — must NOT appear as orphan",
+  );
+});
+
+test("findOrphanedResources: ignored ids do not affect non-ignored orphans", () => {
+  const loadedIds = ["alpha"];
+  const stateMap = {
+    alpha: { uuid: DUMMY_UUID_1 },
+    beta: { uuid: DUMMY_UUID_2 },
+    gamma: { uuid: "33333333-3333-3333-3333-333333333333" },
+  };
+  const orphansFn = deleteModule.findOrphanedResources as unknown as (
+    loaded: string[],
+    state: Record<string, { uuid: string }>,
+    ignoredIds?: Set<string>,
+  ) => Array<{ resourceId: string; uuid: string }>;
+  const orphans = orphansFn(loadedIds, stateMap, new Set(["beta"]));
+  assert.deepEqual(orphans, [
+    { resourceId: "gamma", uuid: "33333333-3333-3333-3333-333333333333" },
+  ]);
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// validateNoIgnoredReferences: new validator. Returns error-severity finding
+// for any squad/assistant that references an ignored assistant id.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function emptyLoaded() {
+  return {
+    tools: [],
+    structuredOutputs: [],
+    assistants: [],
+    squads: [],
+    personalities: [],
+    scenarios: [],
+    simulations: [],
+    simulationSuites: [],
+    evals: [],
+  };
+}
+
+test("validateNoIgnoredReferences: squad references ignored assistant → error finding", () => {
+  const validator = (
+    validateModule as unknown as {
+      validateNoIgnoredReferences?: (
+        loaded: ReturnType<typeof emptyLoaded>,
+        ignorePatterns: string[],
+      ) => Array<{
+        severity: "warn" | "error";
+        rule: string;
+        resourceId: string;
+        message: string;
+      }>;
+    }
+  ).validateNoIgnoredReferences;
+
+  // The implementer adds this export. Until then the test fails with
+  // `validator is not a function`, which is the desired spec-first failure.
+  assert.equal(
+    typeof validator,
+    "function",
+    "validateNoIgnoredReferences must be exported from src/validate.ts",
+  );
+
+  const loaded = emptyLoaded();
+  loaded.assistants.push({
+    resourceId: "foo",
+    filePath: "/fake/foo.md",
+    data: { name: "foo" },
+  });
+  loaded.squads.push({
+    resourceId: "bar",
+    filePath: "/fake/bar.yml",
+    data: { name: "bar", members: [{ assistantId: "foo" }] },
+  });
+
+  const findings = validator!(loaded, ["assistants/foo"]);
+  const errors = findings.filter((f) => f.severity === "error");
+  assert.ok(
+    errors.length >= 1,
+    `expected at least one error-severity finding; got ${JSON.stringify(findings)}`,
+  );
+  const flagged = errors.find(
+    (f) =>
+      f.resourceId === "bar" &&
+      /references[^\n]*foo[^\n]*\.vapi-ignore/.test(f.message),
+  );
+  assert.ok(
+    flagged,
+    `expected error to mention bar references foo & .vapi-ignore; got ${JSON.stringify(errors)}`,
+  );
+});
+
+test("validateNoIgnoredReferences: clean fixture (no refs to ignored) → no findings", () => {
+  const validator = (
+    validateModule as unknown as {
+      validateNoIgnoredReferences?: (
+        loaded: ReturnType<typeof emptyLoaded>,
+        ignorePatterns: string[],
+      ) => Array<{ severity: "warn" | "error"; rule: string }>;
+    }
+  ).validateNoIgnoredReferences;
+  if (typeof validator !== "function") {
+    // Until impl lands, surface the same spec-first failure shape.
+    assert.equal(
+      typeof validator,
+      "function",
+      "validateNoIgnoredReferences must be exported from src/validate.ts",
+    );
+    return;
+  }
+
+  const loaded = emptyLoaded();
+  loaded.assistants.push({
+    resourceId: "foo",
+    filePath: "/fake/foo.md",
+    data: { name: "foo" },
+  });
+  loaded.squads.push({
+    resourceId: "bar",
+    filePath: "/fake/bar.yml",
+    data: { name: "bar", members: [{ assistantId: "foo" }] },
+  });
+
+  // foo is NOT ignored — validator should be silent.
+  const findings = validator(loaded, ["assistants/other"]);
+  assert.equal(
+    findings.filter((f) => f.severity === "error").length,
+    0,
+    `expected no error-severity findings; got ${JSON.stringify(findings)}`,
+  );
+});
+
+test("validateNoIgnoredReferences: empty ignore list → no findings (back-compat)", () => {
+  const validator = (
+    validateModule as unknown as {
+      validateNoIgnoredReferences?: (
+        loaded: ReturnType<typeof emptyLoaded>,
+        ignorePatterns: string[],
+      ) => Array<{ severity: "warn" | "error" }>;
+    }
+  ).validateNoIgnoredReferences;
+  if (typeof validator !== "function") {
+    assert.equal(
+      typeof validator,
+      "function",
+      "validateNoIgnoredReferences must be exported from src/validate.ts",
+    );
+    return;
+  }
+  const loaded = emptyLoaded();
+  loaded.squads.push({
+    resourceId: "bar",
+    filePath: "/fake/bar.yml",
+    data: { members: [{ assistantId: "foo" }] },
+  });
+  const findings = validator(loaded, []);
+  assert.equal(findings.length, 0);
+});