Addresses CHANGES_REQUESTED review on PR #1479:
1. Remove docs/superpowers/specs/2026-05-10-incremental-indexing-design.md
per maintainer request.
2. BLOCKER (Claude Finding 1, Bugbot Round 3): Stale cross-file edges
between unchanged files. extractChangedSubgraph excluded edges where
both endpoints were unchanged-file nodes — when a barrel/re-export
file changes, cross-file resolution may update CALLS edges between
two unchanged files that would then be silently lost.
Fix: 1-hop importer-closure expansion of the writable set in
run-analyze.ts. Before deleting/rewriting rows, query DB for
importers of every changed/deleted file and add them to the writable
set. Their nodes get deleted+rewritten too, so cross-file's refined
edges land in the DB. Re-added queryImporters to lbug-adapter.ts.
3. BLOCKER (Claude Finding 3): Parse cache key omitted parser version.
After a GitNexus upgrade, the cache silently replays pre-upgrade
ParseWorkerResults against the new schema → wrong CALLS/IMPORTS/
scope edges with no visible signal.
Fix: PARSE_CACHE_VERSION now embeds the gitnexus npm package
version (read at module load via createRequire on package.json).
Format: `${SCHEMA_BUMP}+${PKG_VERSION}` e.g. "1+1.6.4". Any release
that bumps package.json automatically invalidates the on-disk cache.
Mismatched versions fall through to an empty cache (next save
overwrites with the new version baked in).
4. BLOCKER (Claude Finding 2): No automated tests for incremental
behavior. Added 28 unit tests across 3 files:
- incremental-file-hash.test.ts (10 tests)
diffFileHashes classification, computeFileHash determinism,
computeFileHashes batch / missing-file tolerance, sorted output.
- incremental-parse-cache.test.ts (12 tests)
computeChunkHash stability and order-independence, version
prefix format, pruneCache, load/save round-trip on empty /
missing / corrupt / version-mismatched files, AND a Map/Set
round-trip test that pins the JSON replacer/reviver behaviour
(without it, ParsedFile.scopes[*].typeBindings collapses to
{} and downstream `.get()` / iteration throws).
- incremental-subgraph-extract.test.ts (6 tests)
writable-set node inclusion, Community/Process always kept,
edge inclusion when at least one endpoint is writable, MEMBER_OF
edges via graph-wide endpoints, empty subgraph case.
5. Medium (Claude Finding 6): AGENTS.md "Keeping the Index Fresh"
said "only changed files are re-parsed." Imprecise — the pipeline
parses every file every run; the cache skips tree-sitter for chunks
whose contents haven't changed. Reworded to match the design doc.
Test plan still expects:
[x] Typecheck clean
[x] All 28 new unit tests pass
[x] All previously-failing tests still pass on the rebased branch
[x] Equivalence verified locally (incremental ≡ --force, byte-identical
stats on this repo)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Rewrite docs/superpowers/specs/2026-05-10-incremental-indexing-design.md
to describe the architecture that actually shipped (parse cache +
incremental DB writeback + scope-resolution short-circuit), with the
v1 hydrate-phase post-mortem preserved as historical context.
- AGENTS.md "Keeping the Index Fresh" section: note that incremental
is the new default and --force is the explicit opt-out; mention
the parse-cache file location and that it's safe to delete.
- GUARDRAILS.md Signs: add an "Index seems corrupt or incremental is
misbehaving" entry pointing users to --force as the manual escape
hatch (the dirty flag handles automatic recovery).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures the design agreed in brainstorming on 2026-05-10:
- Transitive importer closure with public-surface-change optimization
- Git-only change detection (non-git repos: full rebuild as today)
- New default behavior; --force opts out
- New hydratePhase + loadGraphFromLbug primitive
- Iterative closure expansion with parseCache reuse
- incrementalInProgress dirty flag for crash recovery
Prior art: PR #592 (zenprocess), PR #533 (davidbeesley),
PR #1146 (azeemshaik025) — referenced and credited.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Spec covers 4 HIGH-priority issues from review: path traversal via
group name, gRPC proto regex nested braces, service boundary detector
directory exclusions, double-close of LadybugDB pools.
Plan: 6 tasks with TDD, ordered by complexity.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
