Codebase File Map 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: Add file-level codebase indexing events and graph projection.

Architecture: Create a focused zaxy.codebase collector, add a code.file.indexed extractor, expose MemoryFabric.ingest_codebase, and wire a CLI command that appends events through the existing fabric.

Tech Stack: Python 3.11, pathlib, hashlib, Typer, pytest, ruff.

---

Task 1: Codebase Collector

Files:

Create: src/zaxy/codebase.py
Create: tests/test_codebase.py

[ ] Step 1: Write failing tests

Test that collect_codebase_events() indexes supported source files with language, sha256, bytes, and lines; skips hidden/cache/dependency directories; and rejects missing roots.

[ ] Step 2: Run red test

Run: pytest --no-cov tests/test_codebase.py -q

Expected: fail because zaxy.codebase does not exist.

[ ] Step 3: Implement collector

Add supported suffixes, excluded directory names, language inference, and event payload generation.

[ ] Step 4: Run green test

Run: pytest --no-cov tests/test_codebase.py -q

Expected: pass.

Task 2: Extractor

Files:

Modify: src/zaxy/extract.py
Modify: tests/test_extract.py

[ ] Step 1: Write failing extractor test

Test code.file.indexed creates a code_file entity and indexed_code_file edge from actor to file.

[ ] Step 2: Run red test

Run: pytest --no-cov tests/test_extract.py -q

Expected: fail because no extractor is registered.

[ ] Step 3: Implement extractor

[ ] Step 4: Run green test

Run: pytest --no-cov tests/test_extract.py -q

Expected: pass.

Task 3: Fabric And CLI

Files:

Modify: src/zaxy/core.py
Modify: src/zaxy/__main__.py
Modify: tests/test_core.py
Modify: tests/test_cli.py

[ ] Step 1: Write failing tests

Test MemoryFabric.ingest_codebase() appends collected code events to the requested session. Test zaxy index-codebase PATH --session-id default reports the indexed count with MemoryFabric mocked.

[ ] Step 2: Run red tests

Run: pytest --no-cov tests/test_core.py tests/test_cli.py -q

Expected: fail because the method and command do not exist.

[ ] Step 3: Implement method and command

Add ingest_codebase() beside document/transcript ingestion and a Typer command that calls it.

[ ] Step 4: Run green tests

Run: pytest --no-cov tests/test_codebase.py tests/test_extract.py tests/test_core.py tests/test_cli.py -q

Expected: pass.

Task 4: Docs And Verification

Files:

Create: docs/codebase.md
Modify: docs/eventloom.md
Modify: docs/retrieval.md
Modify: docs/runbook.md
Modify: AGENTS.md

[ ] Step 1: Document codebase indexing

Explain file-level scope, command usage, event shape, and future symbol extraction.

[ ] Step 2: Verify

Run:

ruff check src/zaxy/codebase.py src/zaxy/extract.py src/zaxy/core.py src/zaxy/__main__.py tests/test_codebase.py tests/test_extract.py tests/test_core.py tests/test_cli.py
pytest --no-cov tests/test_codebase.py tests/test_extract.py tests/test_core.py tests/test_cli.py tests/test_docs_site.py -q
pytest --no-cov -m "not integration"

Expected: all checks pass.