oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
waggle-os/docs/briefs/2026-04-26-memory-sync-repair-cc2-brief.md
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
Details
moving
2026-09-02 10:10:29 +02:00

12 KiB
Raw Permalink Blame History

Memory Sync Repair — CC-2 Paste-Ready Brief

Date: 2026-04-26 Authority: PM (Marko ratifikovao 2026-04-26 — sve 3 step-a + paralelna CC-2 sesija) Companion document: decisions/2026-04-26-memory-sync-audit.md (full audit + diagnostic context) Sequencing: Step 1 → Step 2 → Step 3 (sequential, halt-and-ping nakon svakog) Parallel constraint: Independent od CC-1 agent fix sprint Phase 1.x; no shared code paths, no merge conflict expected

§1 — Goal

Sync repair između D:\Projects\waggle-os\packages\core\src\mind\ (production substrate, used by Tauri desktop) i D:\Projects\hive-mind\packages\core\src\mind\ (Apache-2.0 release artifact, npm publishable). Trenutno divergent — bug fixes idu u oba pravca bez automated sync.

Final state target:

  1. Bug fixes back-portovani u oba pravca (no production bugs unfixed)
  2. Tests u oba repoa (production code coverage matches release artifact coverage)
  3. CI/CD sync workflow (parity check + auto-PR creation) — divergence ne raste organički

§2 — Step 1: Back-port hive-mind bug fixes u waggle-os (1-3h work)

2.1 — Cherry-pick targets (binding)

Two fixes from hive-mind:

Fix A — 9ec75e6 Stage 0 root cause:

fix(harvest-local): persist item.timestamp to memory_frames.created_at (Stage 0 root cause)

Action: git -C D:\Projects\hive-mind show 9ec75e6 to read patch. Apply equivalent change u waggle-os/packages/core/src/mind/ + harvest pipeline. NOTE: hive-mind paths su packages/core/src/mind/ ali file content nije identical sa waggle-os; cherry-pick će biti manual application of fix logic, ne raw git cherry-pick jer su file SHAs different.

Fix B — 0bbdf7a content preview cap:

fix(harvest-local): raise content preview cap 2000 → 10000 chars (Stage 0 Task 0.5)

Action: identičan pattern. Read hive-mind patch, apply equivalent change u waggle-os. Verify cap je sad 10000.

2.2 — Bidirectional audit (waggle-os → hive-mind candidates)

Three waggle-os commits koji potencijalno treba u hive-mind:

Candidate 1 — 63ef881:

fix(frames): findDuplicate must use JS trim, not SQLite trim

Action: read waggle-os patch. Compare against hive-mind packages/core/src/mind/frames.ts. If hive-mind has identical bug pattern, port fix to hive-mind. If hive-mind code is different (e.g., already uses JS trim, or refactored differently), document and skip.

Candidate 2 — 803c6f6:

fix(memory-mcp): harvest_import / ingest_source dedup detection uses frame id, not timestamp

Action: read waggle-os patch. Compare against hive-mind packages/mcp-server/src/tools/harvest.ts (or equivalent). If bug exists, port. If already fixed or N/A, document.

Candidate 3 — b8ffe8e:

fix(agent,core): Day-1-PM correctness cluster from orchestrator review

Action: this is a multi-file fix. Filter to changes touching packages/core/src/mind/ only. If any mind/ changes exist, audit each whether they apply to hive-mind. Agent-side changes (packages/agent/) are explicitly Waggle-only per EXTRACTION.md, do not port.

2.3 — Step 1 acceptance criteria

  • Both Fix A + Fix B applied to waggle-os, compile clean (tsc --noEmit)
  • Existing waggle-os tests pass (no regression)
  • Both fixes have explicit commit message referencing source hive-mind SHA: e.g., fix(harvest): port hive-mind 9ec75e6 (Stage 0 root cause: timestamp persist)
  • Three Candidates 1-3 audited; each has explicit Y/N decision in commit body or PM-Waggle-OS decisions/ memo
  • If any Candidate ports to hive-mind, separate hive-mind commit + PR opened
  • PM ratification halt before Step 2 kickoff

§3 — Step 2: Port hive-mind tests u waggle-os (4-8h work)

3.1 — Test files to port

From D:\Projects\hive-mind\packages\core\src\mind\ (15 test files):

  • awareness.test.ts
  • concept-tracker.test.ts
  • db.test.ts
  • embedding-provider.test.ts
  • entity-normalizer.test.ts
  • frames.test.ts
  • identity.test.ts
  • inprocess-embedder.test.ts
  • knowledge.test.ts
  • litellm-embedder.test.ts
  • ontology.test.ts
  • reconcile.test.ts
  • scoring.test.ts
  • search.test.ts
  • sessions.test.ts

3.2 — Test placement convention

Verify existing waggle-os test placement convention:

  • Check D:\Projects\waggle-os\packages\core\src\ for existing *.test.ts files
  • Check D:\Projects\waggle-os\tests\ or D:\Projects\waggle-os\packages\core\tests\ for separate test folder convention
  • Check vitest.config.ts and package.json test scripts u waggle-os/packages/core/ za include/exclude patterns

Port tests to convention. Default: adjacent *.test.ts files in same directory as source.

3.3 — Run + classify

cd D:\Projects\waggle-os\packages\core
npm test -- --reporter=verbose

Per failed test, classify:

  • PASS: API match, test validno za waggle-os production code
  • FAIL — bug u waggle-os: identify, fix, document. If fix exists in hive-mind, cherry-pick same way as Step 1.
  • FAIL — API mismatch: waggle-os ima Waggle-specific extension koja menja signature/behavior. Two sub-options:
    • (i) Test ne primenjuje se na waggle-os; document u test file kao .skip() sa komentarom + PM-Waggle-OS memo entry
    • (ii) Test treba prilagoditi Waggle-specific extension sa adapter wrapper; document u memo + reach out PM ako adapter scope > 30 minuta
  • FAIL — test depends on hive-mind-only utility: dependency missing u waggle-os (npm import not available). Either install dep, or skip + document.

3.4 — Step 2 acceptance criteria

  • All 15 test files ported to waggle-os (or explicitly skipped sa documented reason)
  • Per-test outcome documented u summary table (PASS / FAIL bug / FAIL extension / FAIL dependency)
  • Bug fixes from FAIL → bug applied to waggle-os
  • Summary report posted to D:\Projects\PM-Waggle-OS\decisions\2026-04-26-memory-sync-step2-test-port-results.md
  • PM ratification halt before Step 3 kickoff

§4 — Step 3: CI/CD sync workflow (3-5h work)

4.1 — Workflow A: mind-parity-check

File: D:\Projects\waggle-os\.github\workflows\ci.yml (extend existing) — add new job:

mind-parity-check:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with:
        path: waggle-os
    - uses: actions/checkout@v4
      with:
        repository: marolinik/hive-mind
        path: hive-mind
    - uses: actions/setup-node@v4
      with:
        node-version: 20
    - name: Copy hive-mind tests to waggle-os
      run: |
        cp hive-mind/packages/core/src/mind/*.test.ts waggle-os/packages/core/src/mind/ || true
    - name: Install + run tests
      run: |
        cd waggle-os
        npm install
        npm test --workspace=@waggle/core -- --testPathPattern='packages/core/src/mind'
    - name: Compare critical files (informational)
      run: |
        for f in frames.ts search.ts knowledge.ts schema.ts; do
          if ! diff -q waggle-os/packages/core/src/mind/$f hive-mind/packages/core/src/mind/$f > /dev/null 2>&1; then
            echo "DIFF: $f"
          fi
        done

Trigger: PR + push na main, paths-filter ako touch-uje packages/core/src/mind/ ili packages/core/src/harvest/.

Pass criteria: hive-mind tests pass na waggle-os codebase. Failing tests = block merge unless explicitly allowlisted (.parity-allowlist file in repo root sa documented reason per allowed test).

4.2 — Workflow B: mind-sync-pr

New file: D:\Projects\waggle-os\.github\workflows\sync-mind.yml:

name: Sync Mind to hive-mind
on:
  push:
    branches: [main]
    paths:
      - 'packages/core/src/mind/**'
      - 'packages/core/src/harvest/**'
      - '!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'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Generate diff for hive-mind
        run: |
          # extract changes from this push (excluding NOT-extracted files per EXTRACTION.md)
          # ... script to generate filtered patch
      - name: Open PR to hive-mind
        # use github API or gh CLI to open PR with filtered diff

Filter list (NOT-extracted, must be excluded from sync):

  • 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/**
  • (any other files marked "NOT extracted" in D:\Projects\hive-mind\EXTRACTION.md)

PR review: manual u hive-mind. PR title format: auto-sync from waggle-os@{sha}: {original commit subject}.

PR creation requires HIVE_MIND_SYNC_TOKEN repository secret (GitHub PAT sa repo write access to marolinik/hive-mind).

4.3 — Step 3 acceptance criteria

  • Both workflows committed u waggle-os/.github/workflows/
  • mind-parity-check test run on synthetic test branch (touch a mind/ file, verify CI runs hive-mind tests against the change)
  • mind-sync-pr test run on synthetic test branch (touch a mind/ file, push to main, verify auto-PR opens u hive-mind)
  • HIVE_MIND_SYNC_TOKEN secret configured u waggle-os repo settings (Marko handles secret creation; CC-2 cannot)
  • Documentation u waggle-os/.github/README.md ili separate sync.md: how sync works, how to add to allowlist, how to handle bidirectional bug fixes
  • D:\Projects\PM-Waggle-OS\decisions\2026-04-26-memory-sync-step3-cicd-results.md summary report
  • PM ratification + final sign-off

§5 — Halt-and-ping triggers (binding)

  1. Step 1 cherry-pick reveals fix doesn't apply cleanly (file structure changed dramatically): halt + ping PM + document specific deviation
  2. Step 2 reveals >5 tests FAIL — bug u waggle-os (bigger than back-port can handle quickly): halt + ping PM, scope decision (cherry-pick all, defer some, refactor)
  3. Step 2 reveals API mismatch on critical files (frames.ts, search.ts, knowledge.ts): halt + ping PM, decide whether Waggle-specific extension is intended or accidental drift
  4. Step 3 secret token not available: halt + ping PM, Marko provides via gh secret set or repo settings
  5. Cumulative time exceeds 16h (Step 1 + 2 + 3): halt + ping PM, scope re-evaluation

§6 — Cost ceiling

No API spend (this is local code work + GitHub API calls for PR creation only). GitHub Actions minutes (free tier sufficient for this volume).

Estimated total time: 8-15h CC-2 work + ~30 min PM review per step (3 PM halts).

§7 — What NOT to do (hard rules)

  • DO NOT apply hive-mind code wholesale to waggle-os (would lose Waggle-specific extensions). Fix-by-fix targeted patches only.
  • DO NOT apply waggle-os code wholesale to hive-mind (would leak Waggle-specific schema/compliance/tier code into Apache-2.0 release). Filter per EXTRACTION.md "NOT extracted" list always.
  • DO NOT disable existing waggle-os tests to make hive-mind tests pass. Identify root cause and fix the actual bug or document the legitimate API mismatch.
  • DO NOT skip Step 1 PM ratification halt to "save time". The 3 candidate audits (63ef881, 803c6f6, b8ffe8e) require PM judgment on whether to port to hive-mind.
  • DO NOT make this a "rewrite both repos to align" exercise. The 3-step plan is targeted: bug fixes + tests + CI sync. Don't expand scope without PM ratification.

§8 — Cross-references

  • decisions/2026-04-26-memory-sync-audit.md — full audit + diagnostic context (read first)
  • D:\Projects\hive-mind\EXTRACTION.md — file-by-file map of what's extracted vs NOT extracted
  • Pilot evidence: decisions/2026-04-26-pilot-verdict-FAIL.md
  • Agent fix sprint plan: D:\Projects\waggle-os\decisions\2026-04-26-agent-fix-sprint-plan.md (CC-1 sprint, parallel)
  • Sprint plan addendum (Phase 4 acceptance gate): commit 2ad3688 u waggle-os
  • Phase 1.1 commit: 4a557cc u waggle-os
Reference in New Issue View Git Blame Copy Permalink