Zaxy Merge Sprint Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Consolidate the accumulated Zaxy memory, onboarding, graph, and documentation work into a clean merge-ready release.

Architecture: Treat this as an integration sprint, not a feature sprint. First freeze the current working tree, then split commits by product capability, update the public site/docs narrative, run the release gate, and push/merge only after the repo tells one coherent story.

Tech Stack: Python 3.13, pytest, ruff, mypy, static HTML docs site, Eventloom JSONL, Neo4j, MCP.

---

Task 1: Freeze And Inventory Current Work

Files:

• Inspect: git status --short --branch
• Inspect: git diff --stat
• Inspect: git log --oneline --decorate --max-count=12

• [ ] Step 1: Confirm branch and dirty state

Run:

git status --short --branch

Expected: master is ahead of origin/master and has tracked/untracked changes.

• [ ] Step 2: Capture the changed surface area

Run:

git diff --stat
git diff --name-only

Expected: changed files are grouped across local profile/onboarding, graph provenance, memory checkout/refs/capabilities, MCP, hooks, tests, and docs.

• [ ] Step 3: Run the current verification baseline

Run:

ruff check .
mypy src/zaxy
pytest -q

Expected: ruff clean, mypy clean, full test suite passes with coverage above 90%.

Task 2: Split Work Into Coherent Commits

Files:

• Stage selectively from the current working tree.
• Do not include unrelated generated artifacts.

• [ ] Step 1: Commit local infrastructure and onboarding cleanup

Stage:

git add .env.example scripts/setup.sh src/zaxy/local_profile.py src/zaxy/onboarding.py tests/test_setup_script.py tests/test_onboarding.py docs/configuration.md docs/getting-started.md docs/packet-analyzer.md docs/hooks.md
git commit -m "feat: streamline local onboarding capture"

Expected: commit covers deterministic capture defaults, local-codex, localhost Neo4j profile, packet capture opt-in guidance, and Codex hook JSON safety.

• [ ] Step 2: Commit graph provenance and projection integrity

Stage:

git add scripts/setup_neo4j_indexes.cypher src/zaxy/graph.py src/zaxy/schema.py src/zaxy/extract.py tests/test_graph.py tests/test_extract.py tests/test_schema_migrations.py docs/eventloom.md docs/graph-schema.md
git commit -m "feat: add graph provenance integrity checks"

Expected: commit covers Eventloom hash-path projection, NEXT_EVENT/PREVIOUS_EVENT, graph status checks, and schema docs.

• [ ] Step 3: Commit model-facing memory UX

Stage:

git add src/zaxy/capabilities.py src/zaxy/refs.py src/zaxy/__init__.py src/zaxy/__main__.py src/zaxy/core.py src/zaxy/mcp_server.py src/zaxy/embedding.py tests/test_capabilities.py tests/test_refs.py tests/test_cli.py tests/test_core.py tests/test_mcp.py docs/mcp.md docs/getting-started.md AGENTS.md
git commit -m "feat: add model-facing memory checkout"

Expected: commit covers memory_capabilities, Memory Checkout, memory refs, checkout-by-ref, MCP exposure, and model-facing docs.

Task 3: Update Public Site Narrative

Files:

• Modify: site/index.html
• Modify: site/style.css only if the content needs layout support.
• Test: tests/test_docs_site.py

• [ ] Step 1: Add failing docs-site assertions

Modify tests/test_docs_site.py so the public site is required to mention:

assert "Git for LLM memory" in html
assert "Memory Checkout" in html
assert "memory_capabilities" in html
assert "deterministic capture" in html
assert "local-codex" in html
assert "NEXT_EVENT" in html

Run:

pytest tests/test_docs_site.py --no-cov -q

Expected: failure until site/index.html is updated.

• [ ] Step 2: Update the site copy

Modify site/index.html so the first screen and architecture sections explain:

Zaxy is Git for LLM memory: an Eventloom-backed, hash-linked, replayable memory substrate with graph projection, Memory Checkout, deterministic capture, and MCP-native model awareness.

Expected: the site now reflects the current product direction rather than only the earlier temporal graph fabric positioning.

• [ ] Step 3: Verify docs site

Run:

pytest tests/test_docs_site.py --no-cov -q
bash scripts/validate-docs.sh --root .

Expected: docs-site tests and link validation pass.

• [ ] Step 4: Commit public site update

Run:

git add site/index.html site/style.css tests/test_docs_site.py
git commit -m "docs: update public memory product narrative"

Expected: commit is docs/site only.

Task 4: Release Gate And Merge

Files:

• Inspect: full repo.

• [ ] Step 1: Run release gate

Run:

scripts/release-check.sh --root .

Expected: release checks pass. If the script requires services not currently running, capture the exact failing check and run the documented focused alternative only after confirming it is an environmental dependency.

• [ ] Step 2: Confirm final history

Run:

git status --short --branch
git log --oneline --decorate --max-count=12

Expected: clean working tree, local master ahead of origin/master by the new sprint commits plus the previous five local commits.

• [ ] Step 3: Push merge result

Run:

git push origin master
git status --short --branch

Expected: master is synchronized with origin/master and no uncommitted work remains.