traverse-framework · enricopiovesan · Aug 24, 2026 · Aug 23, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -28,9 +28,11 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \
 | `llm-mcp-meeting-notes-workflow` | **Done** (#239) | Meeting-notes MCP tool-sequence runbook |
 | `llm-mcp-cursor-live-smoke` | **Done** (#240) | Cursor MCP Mode A stdio evidence |
 | `llm-mcp-claude-live-smoke` | **Done** (#241) | Claude Desktop/Code MCP Mode A evidence |
-| `llm-mcp-traverse-starter-catalog` | **Blocked** | Kit IDs on MCP stdio — Traverse #865 / registry #99 |
+| `llm-mcp-traverse-starter-catalog` | **Blocked** | Traverse #865 (registry #99 closed) |
 | `loop-wf1-registry-deps` | **Done** (#263) | Digest inventory in `docs/loop-registry-deps.md` |
 | `loop-wf1-multi-os` | **Done** (#265) | `apps/loop/` WF1 × 7 OS; compose via `registry_ref` |
+| `retire-registry-ref-materialize` | **In Progress** | Phase A gate/docs; full delete blocked on Traverse BundleEmbedder + Spec 107 |
+| `llm-mcp-embedded-host` | **Ready** | Mode B host on Spec 520 cache (#860 closed) |
 
 Full gap table + wave notes: [`docs/production-reference-plan.md`](docs/production-reference-plan.md).
 

diff --git a/docs/production-packaging.md b/docs/production-packaging.md
@@ -111,11 +111,12 @@ Governing Traverse / Registry specs:
 
 | Layer | Today | Next |
 |---|---|---|
-| Component manifests under `manifests/` | **All six primary components** use `registry_ref` (`^1.0.0` → live `1.0.1` when yank-aware) | Keep ranges; no local-path reintroduction |
-| Sync / packaging | [`runtime-bundle-sync.md`](runtime-bundle-sync.md) + `sync_bundle_materialize_registry_refs` for embedder trees | Embedder-native resolve (Traverse) can retire materialize |
-| Implementation ticket | `registry-ref-full-kit-cutover` | Done when smoke evidence is green |
+| Component manifests under `manifests/` | **All six primary components** (+ Loop WF1) use `registry_ref` | Keep ranges; no local-path reintroduction |
+| Sync / packaging | [`runtime-bundle-sync.md`](runtime-bundle-sync.md) + **gated** `sync_bundle_materialize_registry_refs` (default **on**) | Retire rewrite once hosts resolve `registry_ref` offline from Spec 520 cache |
+| Spec 520 (Traverse) | `#860` closed — Rust `HostRegistryCache` + web standalone prepare/resolve APIs | Web `BundleEmbedder` still requires `wasm_binary_path`; native Spec 107 adopt incomplete |
+| App-Refs ticket | `retire-registry-ref-materialize` | Phase A: gate/tests/docs; full delete blocked on Traverse BundleEmbedder + Spec 107 |
 
-**Checked-in source of truth** for every primary component is `registry_ref` only (no local `contract_path` / `wasm_*` on source manifests). Platform sync **materializes** local wasm paths into destination bundles for FetchBundleLoader hosts that still require `wasm_binary_path`.
+**Checked-in source of truth** for every primary component is `registry_ref` only (no local `contract_path` / `wasm_*` on source manifests). Platform sync **materializes** local wasm paths into destination bundles by default (`APP_REFS_MATERIALIZE_REGISTRY_REFS=1`) for FetchBundleLoader / native bridges that still require `wasm_binary_path`. Set `APP_REFS_MATERIALIZE_REGISTRY_REFS=0` to leave destination `registry_ref` intact (hosts must use Traverse prepare + verified cache — not production-ready for all App-Refs shells yet).
 
 ## Intended component shape
 
@@ -167,7 +168,7 @@ If sync has not run, registration must fail with a stable error that `traverse-c
 ## Agent / playbook rules
 
 - Do **not** reintroduce local `contract_path` / `wasm_*` on checked-in primary `manifests/` components.
-- Platform sync may materialize `registry_ref` → local wasm in **destination** bundles only.
+- Platform sync may materialize `registry_ref` → local wasm in **destination** bundles only (default on). Do not flip `APP_REFS_MATERIALIZE_REGISTRY_REFS=0` for primary shells until BundleEmbedder / native adopt paths are proven in smoke.
 - Prefer `version_range: "^1.0.0"` so yanked stub `1.0.0` is skipped and live `1.0.1` is selected when the resolver is yank-aware (registry spec 005).
 - UI remains a rendering layer — registry adoption does not move business field computation into App-References.
 

diff --git a/docs/runtime-bundle-sync.md b/docs/runtime-bundle-sync.md
@@ -28,6 +28,8 @@ Wrappers only choose destination, app id, component list, and which optional lay
 | `--traverse-assets` | `required` / `optional` / `none` | Web required; WinUI optional; Swift/Android none |
 | `--manifest-layout` | `root` / `subdir` | Android uses `subdir` (`manifests/` under bundle); others `root` |
 
+`registry_ref` destination rewrite is gated by `APP_REFS_MATERIALIZE_REGISTRY_REFS` (default `1`). See [`production-packaging.md`](production-packaging.md) and ticket `retire-registry-ref-materialize`.
+
 ## Commands
 
 ```bash

diff --git a/scripts/ci/repository_checks.sh b/scripts/ci/repository_checks.sh
@@ -149,6 +149,7 @@ check "scripts/ci/fixtures/traverse-starter-smoke-agents/process-agent.wasm" "Pi
 check "scripts/ci/fixtures/traverse-starter-smoke-agents/validate-agent.wasm" "Pinned Traverse validate agent wasm"
 check "scripts/ci/fixtures/traverse-starter-smoke-agents/summarize-agent.wasm" "Pinned Traverse summarize agent wasm"
 check "scripts/ci/sync_bundle_core.sh"         "Shared bundle sync core"
+check "scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh" "registry_ref materialize gate test"
 check "scripts/ci/sync_web_starter_bundle.sh"  "Web starter bundle sync"
 check "scripts/ci/sync_web_doc_approval_bundle.sh" "Web doc-approval bundle sync"
 check "scripts/ci/sync_web_meeting_notes_bundle.sh" "Web meeting-notes bundle sync"

diff --git a/scripts/ci/sync_bundle_core.sh b/scripts/ci/sync_bundle_core.sh
@@ -276,9 +276,23 @@ sync_bundle_destination() {
 # Canonical source under manifests/ stays registry_ref; destinations materialize.
 # Also copies the referenced example WASM + contract into dest/_traverse when missing
 # (Android/Swift sync with --traverse-assets none).
+#
+# Interim gate (ticket retire-registry-ref-materialize / Spec 520):
+#   APP_REFS_MATERIALIZE_REGISTRY_REFS=1 (default) — rewrite destination manifests
+#   APP_REFS_MATERIALIZE_REGISTRY_REFS=0 — leave registry_ref intact (hosts must
+#     resolve via Traverse HostRegistryCache / prepare+offline APIs). Full
+#     retirement waits on BundleEmbedder accepting registry_ref without wasm_*
+#     (web) and Spec 107 native adopt tickets.
 sync_bundle_materialize_registry_refs() {
   local dest="$1"
   local app_id="$2"
+  local materialize_mode="${APP_REFS_MATERIALIZE_REGISTRY_REFS:-1}"
+  case "$materialize_mode" in
+    0|false|off|no|NO|False|Off)
+      echo "OK: skipping registry_ref materialize (APP_REFS_MATERIALIZE_REGISTRY_REFS=$materialize_mode)"
+      return 0
+      ;;
+  esac
   REPO_ROOT="$REPO_ROOT" TRAVERSE_REPO="$TRAVERSE_REPO" DEST="$dest" APP_ID="$app_id" python3 - <<'PY'
 import hashlib, json, os, pathlib, shutil, sys
 

diff --git a/scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh b/scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Assert APP_REFS_MATERIALIZE_REGISTRY_REFS gate for sync_bundle_materialize_registry_refs.
+# Does not require TRAVERSE_REPO example trees when materialize is off.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+# shellcheck source=scripts/ci/sync_bundle_core.sh
+source "$ROOT/scripts/ci/sync_bundle_core.sh"
+sync_bundle_init
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+mkdir -p "$TMP/components/process"
+cat >"$TMP/components/process/component.manifest.json" <<'JSON'
+{
+  "component_id": "test.process-component",
+  "version": "1.0.0",
+  "schema_version": "1.0.0",
+  "capability_id": "meeting-notes.process",
+  "capability_version": "1.0.0",
+  "registry_ref": {
+    "namespace": "meeting-notes",
+    "id": "meeting-notes.process",
+    "version_range": "^1.0.0"
+  }
+}
+JSON
+
+# Off: destination must keep registry_ref and must not gain wasm_* fields.
+APP_REFS_MATERIALIZE_REGISTRY_REFS=0 sync_bundle_materialize_registry_refs "$TMP" "meeting-notes"
+python3 - <<PY
+import json
+from pathlib import Path
+p = Path("$TMP/components/process/component.manifest.json")
+data = json.loads(p.read_text())
+assert "registry_ref" in data, data
+assert "wasm_binary_path" not in data and "wasm_digest" not in data, data
+print("OK: materialize gate off preserves registry_ref")
+PY
+
+echo "PASS: sync_bundle_materialize_registry_refs_gate"