diff --git a/.gitignore b/.gitignore
index f64bb52..5289304 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,5 +23,6 @@ agents-workspace-cannon-repo/
 audit-findings/
 shared-baseline-audit-2026-05-10.md
 
-# parity harness cache (cloned frozen source + packed candidates)
+# stale parity cache from before it moved to ~/.cache/workspacejson/cli-parity;
+# still ignored so a leftover clone never gets committed
 .parity-cache/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5b4fc78..bdb8d82 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,12 +41,15 @@ node migration/parity-datahub-shim.mjs     # DataHub adapter parity
 
 They are self-contained. On first run the bash harnesses clone the frozen source
 at its recorded SHA, build it, build this repository, and pack both sides; the
-clone is cached under `.parity-cache/` (gitignored), so later runs take seconds.
-The Node harness reuses that same cache and tells you what to run if it is
-missing.
-
-Overridable via environment: `WORKSPACEJSON_OLD_CHECKOUT` to point at an
-existing clone, `WORKSPACEJSON_PARITY_OUT` for the working directory,
+clone is cached under `~/.cache/workspacejson/cli-parity/`, so later runs take
+seconds. The Node harness reuses that same cache and tells you what to run if it
+is missing. The cache deliberately lives outside the repository: the frozen
+source contains content the architecture guard rejects, so an in-tree cache
+would turn `pnpm check:architecture` red.
+
+Overridable via environment: `WORKSPACEJSON_PARITY_CACHE` for the cache root,
+`WORKSPACEJSON_OLD_CHECKOUT` to point at an existing clone,
+`WORKSPACEJSON_PARITY_OUT` for the working directory,
 `WORKSPACEJSON_SKIP_BUILD=1` to reuse existing builds.
 
 **Expected results today:** runtime `27/29` with two recorded intentional
diff --git a/migration/parity-datahub-shim.mjs b/migration/parity-datahub-shim.mjs
index 38f8d0c..2c72968 100644
--- a/migration/parity-datahub-shim.mjs
+++ b/migration/parity-datahub-shim.mjs
@@ -6,16 +6,20 @@
 // with different code, different dependencies and a different contract.
 
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 
 // Paths are derived, never hardcoded. The old side is a clone of the frozen
 // pre-migration source; migration/parity-lib.sh resolves, pins and builds it,
-// and caches it under .parity-cache/ so repeat runs are cheap.
+// and caches it under ~/.cache/workspacejson/cli-parity so repeat runs are
+// cheap. The cache lives OUTSIDE the repository on purpose: the frozen source
+// contains content the architecture guard exists to reject, so caching it in
+// the working tree turns scripts/check-architecture.mjs red.
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const PARITY_CACHE = process.env.WORKSPACEJSON_PARITY_CACHE ?? join(REPO_ROOT, ".parity-cache");
+const XDG_CACHE = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+const PARITY_CACHE = process.env.WORKSPACEJSON_PARITY_CACHE ?? join(XDG_CACHE, "workspacejson", "cli-parity");
 const OLD_CHECKOUT = process.env.WORKSPACEJSON_OLD_CHECKOUT ?? join(PARITY_CACHE, "source-agents-audit");
 
 const SIDES = {
diff --git a/migration/parity-lib.sh b/migration/parity-lib.sh
index 7928b98..7495203 100644
--- a/migration/parity-lib.sh
+++ b/migration/parity-lib.sh
@@ -8,10 +8,12 @@
 # hand. Every path is derived; nothing is hardcoded to a machine.
 #
 # Overridable:
+#   WORKSPACEJSON_PARITY_CACHE  cache root for the clone and packed candidates
+#                               (default: ~/.cache/workspacejson/cli-parity)
 #   WORKSPACEJSON_OLD_CHECKOUT  path to an existing clone of the frozen source
-#                               (default: cached clone under .parity-cache/)
+#                               (default: $WORKSPACEJSON_PARITY_CACHE/source-agents-audit)
 #   WORKSPACEJSON_PARITY_OUT    working directory for packed candidates
-#                               (default: .parity-cache/out)
+#                               (default: $WORKSPACEJSON_PARITY_CACHE/out)
 #   WORKSPACEJSON_SKIP_BUILD    set to 1 to reuse existing dist/ and tarballs
 
 set -uo pipefail
@@ -24,7 +26,12 @@ REPO_ROOT="$(cd "$PARITY_LIB_DIR/.." && pwd)"
 FROZEN_SOURCE_REPO="https://github.com/workspace-json/agents-audit.git"
 FROZEN_SOURCE_SHA="e47eb1b8556c4f361db9a78190a2f36b400756e8"
 
-PARITY_CACHE="${WORKSPACEJSON_PARITY_CACHE:-$REPO_ROOT/.parity-cache}"
+# The cache lives OUTSIDE the repository on purpose: the old side is a clone of
+# the frozen source, which contains the very content scripts/check-architecture.mjs
+# exists to reject (a copied schema, an ambient @workspacejson/spec declaration).
+# Caching it inside the working tree turns the architecture guard red on any
+# machine that has run a parity harness.
+PARITY_CACHE="${WORKSPACEJSON_PARITY_CACHE:-${XDG_CACHE_HOME:-$HOME/.cache}/workspacejson/cli-parity}"
 OLD_CHECKOUT="${WORKSPACEJSON_OLD_CHECKOUT:-$PARITY_CACHE/source-agents-audit}"
 OUT="${WORKSPACEJSON_PARITY_OUT:-$PARITY_CACHE/out}"