moving

2026-09-02 10:10:29 +02:00
commit 0c3e2ead3b
3841 changed files with 970576 additions and 0 deletions
--- a/.github/sync.md
+++ b/.github/sync.md
@@ -0,0 +1,242 @@
+> **⚠️ 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 `<basename>-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 `<basename>-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 |
+| `<x>-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-<sha>` artifact.
+3. Resolve conflicts; commit on a branch named
+   `auto-sync/waggle-os-<short-sha>`.
+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))