> **⚠️ DEPRECATED (2026-04-30 monorepo migration) — HISTORICAL/AUDIT REFERENCE ONLY.** > This manual describes the dual-repo bidirectional-sync mechanism that ran while the > substrate lived in BOTH waggle-os (`packages/core/src/{mind,harvest}/`) and an external > `marolinik/hive-mind`. After the migration the substrate lives ONLY at > **`packages/hive-mind-core/src/{mind,harvest}/`**, and the OSS mirror is **generated** via > `git subtree split` — see [`packages/hive-mind-core/CONTRIBUTING.md`](../packages/hive-mind-core/CONTRIBUTING.md) > and [`scripts/oss-subtree-split.sh`](../scripts/oss-subtree-split.sh). The > `mind-parity-check.yml` / `sync-mind.yml` workflows referenced below are **inert deprecation > anchors** (their `packages/core/src/...` trigger paths no longer exist, so they never fire). > Everything below is retained for historical context — do NOT treat it as the active process. > See CLAUDE.md §7.5 for the current mechanism. --- # Memory Substrate Sync — `waggle-os` ↔ `hive-mind` This document is the operating manual for the two GitHub Actions workflows that keep `packages/core/src/mind/` and `packages/core/src/harvest/` in sync with the OSS release artifact at [`marolinik/hive-mind`](https://github.com/marolinik/hive-mind). > **Audience:** anyone modifying files under `packages/core/src/mind/` or > `packages/core/src/harvest/`. If you only touch `packages/agent/`, > `packages/server/`, `apps/web/`, etc., none of this applies — those > paths are explicitly Waggle-only per > [`hive-mind/EXTRACTION.md`](https://github.com/marolinik/hive-mind/blob/master/EXTRACTION.md). --- ## TL;DR | What you did | What happens | |--------------|--------------| | Modify `packages/core/src/mind/foo.ts` and open a PR | `mind-parity-check` runs hive-mind's tests against your change. Failure blocks merge unless allowlisted. | | Merge the PR to `main` | `sync-mind-to-hive-mind` opens a PR on `marolinik/hive-mind` with the filtered diff. Manual review there before merge. | | Want to skip a parity test that's intentionally divergent | Add the basename to `.parity-allowlist` with a comment explaining why. | | Modify `packages/core/src/mind/vault.ts` (NOT-extracted) | Sync workflow filters this out automatically — nothing leaks to hive-mind. | --- ## Why this exists Both repos carry their own copy of `packages/core/src/mind/` and `packages/core/src/harvest/`. The audit at `PM-Waggle-OS/decisions/2026-04-26-memory-sync-audit.md` documented the status quo before this workflow shipped: - No automated sync existed; bug fixes flowed in both directions ad-hoc. - Two production bug fixes that landed in hive-mind never made it back to waggle-os until the manual Step 1 backport (commits `89c1004` + `fed4a20`). - The OSS release artifact and the production substrate had silently drifted in 2/19 mind/ files. The two workflows below close that gap. Their goal is **detection + human-reviewed propagation**, never automatic merge. --- ## Workflow 1 — `mind-parity-check.yml` **File:** `.github/workflows/mind-parity-check.yml` **Trigger:** PR or push to `main` that touches `packages/core/src/mind/`, `packages/core/src/harvest/`, or `packages/core/tests/mind/`. **Outcome:** test-pass = ✅ block-clear; test-fail = ❌ merge blocked. ### What it does, step by step 1. Checks out **both** repos — waggle-os in `./waggle-os/`, hive-mind master in `./hive-mind/`. 2. Runs the **waggle-os baseline** mind/ test suite. This is the committed Step 2 ports plus all pre-existing waggle-os mind/ tests. If this fails, the PR is rejected on a regular regression — same as any other failing test. 3. **Injects** the latest hive-mind tests into the waggle-os checkout under `-hive-mind.test.ts` filenames, with import paths adapted via `sed` from `./*.js` to `../../src/mind/*.js`. Three rules govern what gets injected: - **`.parity-allowlist`**: filenames listed here are skipped entirely. - **Already-committed `-hive-mind` file**: kept as-is. The committed version (typically a Step 2 port with bespoke header comments documenting provenance and adaptation rationale) is what the parity check exercises — overwriting it with the latest hive-mind verbatim content would silently drop those headers and any waggle-os-side adaptations. - **No collision**: copy hive-mind file as `-hive-mind.test.ts` into `tests/mind/`, sed the imports. 4. Runs the **combined suite** (waggle-os baseline + injected hive-mind tests). If hive-mind has added new test cases since the last Step 2 port, they'll surface here. Failure here means waggle-os has accidentally diverged from hive-mind's surface contract. 5. Emits an **informational diff** of shared substrate file sizes — not a gate, just visibility. ### When it fails | Failure mode | What it means | What to do | |--------------|---------------|------------| | Baseline waggle-os mind/ tests fail | Regular regression | Fix your change | | `-hive-mind.test.ts` (suffixed) fails | hive-mind tests a behavior waggle-os doesn't honor any more | Decide: (a) accept and fix waggle-os to match hive-mind, OR (b) document intentional divergence and add to `.parity-allowlist` | | Test fails because of import-path adaptation drift | hive-mind reorganized imports | Update the `sed` rules in `mind-parity-check.yml` | | `db-hive-mind.test.ts` fails (always — see allowlist) | The proprietary-tables-must-be-absent assertion mismatches Waggle's schema | This is in `.parity-allowlist` already; if you removed it, restore it | ### `.parity-allowlist` policy The file at the repo root lists test basenames whose verbatim hive-mind copy is intentionally skipped during the parity check. ``` # Comment describing why this entry exists file-name.test.ts ``` **Adding an entry** requires a comment line directly above with the divergence rationale and at least one cross-reference (EXTRACTION.md section, PM-Waggle-OS memo, or related PR). **Removing an entry** is allowed only when the divergence is resolved — either hive-mind upstream changed or waggle-os adopted the upstream behavior. Re-running parity check should pass without the entry first. The current single entry is `db-hive-mind.test.ts` because hive-mind's `db.test.ts` asserts proprietary tables (ai_interactions, execution_traces, evolution_runs, improvement_signals, install_audit) MUST BE ABSENT — its OSS-scrub guarantee. Waggle-os carries those tables legitimately. The waggle-os adaptation lives in committed `db.test.ts` (no suffix) which splits the original assertion into "OSS shared must exist" (verbatim from hive-mind) + "Waggle-specific must exist" (inverted). See `PM-Waggle-OS/decisions/2026-04-26-memory-sync-step2-test-port-results.md`. --- ## Workflow 2 — `sync-mind.yml` **File:** `.github/workflows/sync-mind.yml` **Trigger:** push to `main` that touches `packages/core/src/mind/` or `packages/core/src/harvest/`. **Outcome:** opens a PR on `marolinik/hive-mind` with the filtered diff. **Never auto-merges.** The PR sits for manual review on the hive-mind side. ### Direction note (binding) This workflow implements ONLY the **waggle-os → hive-mind** direction. The empirically primary direction (**hive-mind → waggle-os**) requires a workflow living **inside the hive-mind repo**, which is out of scope for the waggle-os Step 3 PR. It will be added via a sibling PR to hive-mind once Step 3 here is ratified by PM. The current Memory Sync Repair audit shows hive-mind is the more active substrate repo (ahead in 2/5 audit dimensions, +14 organic test files), so the hive-mind-side workflow carries the heavier production burden. ### Filter list — NOT-extracted paths The workflow excludes these paths from the patch — leaking them into hive-mind would put Waggle-specific code into the Apache-2.0 release artifact: ``` packages/core/src/mind/vault.ts packages/core/src/mind/evolution-runs.ts packages/core/src/mind/execution-traces.ts packages/core/src/mind/improvement-signals.ts packages/core/src/compliance/** ``` This list mirrors the "NOT Extracted" section of [`hive-mind/EXTRACTION.md`](https://github.com/marolinik/hive-mind/blob/master/EXTRACTION.md). **If you add a new NOT-extracted file, update the workflow's `excluded_paths` array AND EXTRACTION.md in the same PR** — otherwise the file will leak on the next mind/ push. ### Setup — `HIVE_MIND_SYNC_TOKEN` This workflow needs a fine-grained PAT scoped to `marolinik/hive-mind` with `pull_request: write` + `contents: write` permissions. Marko configures it via: ```bash gh secret set HIVE_MIND_SYNC_TOKEN --repo marolinik/waggle-os gh variable set MIND_SYNC_ENABLED --body 'true' --repo marolinik/waggle-os ``` The `MIND_SYNC_ENABLED` repository variable is the kill switch — set it to `false` to disable the workflow entirely without removing the secret. The workflow's `if:` condition checks this before running. If `HIVE_MIND_SYNC_TOKEN` is unset, the workflow fails fast with a clear error rather than silently skipping. ### When the patch doesn't apply `git apply --3way` falls back to a 3-way merge when the index mismatch is small. If even that fails, the workflow exits with an error pointing to the source SHA. Manual reconciliation: 1. Check out hive-mind master locally. 2. `git apply` the patch from the workflow run's `sync-patch-` artifact. 3. Resolve conflicts; commit on a branch named `auto-sync/waggle-os-`. 4. Open the PR by hand following the same body template. This is rare in practice because hive-mind's mind/ files are mostly verbatim extractions of waggle-os's — any genuine conflict means hive-mind has its own change at the same lines, which is exactly the case the human review is supposed to catch. --- ## Bidirectional bug fix protocol When you find a bug whose fix should go into BOTH repos: 1. Fix it in waggle-os first (production-impacted). 2. Merge to waggle-os main → `sync-mind.yml` auto-opens a hive-mind PR. 3. Review and merge the hive-mind PR. 4. Confirm the next `mind-parity-check` on waggle-os main is green — that closes the loop. When the bug originates in hive-mind (e.g. an upstream contributor reports it): 1. Wait for the hive-mind PR (or open it yourself). 2. After it merges, the eventual hive-mind→waggle-os auto-PR (when that workflow ships) will pick it up. 3. Until then, manual cherry-pick to waggle-os, identical to Step 1 of the original sync repair (see Step 1 results memo at `PM-Waggle-OS/decisions/2026-04-26-memory-sync-step1-results.md` for the canonical pattern: commit message references hive-mind SHA verbatim). --- ## Cross-references - Audit + 3-step plan: `PM-Waggle-OS/decisions/2026-04-26-memory-sync-audit.md` - Step 1 results (forward-port + bidirectional audit): `PM-Waggle-OS/decisions/2026-04-26-memory-sync-step1-results.md` - Step 2 results (test port): `PM-Waggle-OS/decisions/2026-04-26-memory-sync-step2-test-port-results.md` - Step 3 results (this workflow): `PM-Waggle-OS/decisions/2026-04-26-memory-sync-step3-cicd-results.md` - EXTRACTION.md: `D:\Projects\hive-mind\EXTRACTION.md` (or [GitHub link](https://github.com/marolinik/hive-mind/blob/master/EXTRACTION.md))