From the 2026-06-10 codebase-health review. Priority: HIGH — top recommendation.
The user-facing verbs were renamed (tag / summarize / scan / index) and personas, CLI commands and docs use the new names — but the code identifiers still use the old ones, so the persona runner is a permanent translation layer and grep navigation is broken (searching "scan" finds explore.py, etc.).
Extent of the drift
- Filenames:
src/pipeline/pass1.py, pass2.py, explore.py, build.py; src/llm/pass2.py
- Class:
Pass1Stats (src/pipeline/pass1.py)
src/cli.py: ~110 old-name references (imports + hidden aliases)
src/persona/runner.py: imports old module names, exposes new verbs
- Log strings:
src/pipeline/build.py:21-22 ("pass1 (zero-loss)", "pass2 apply")
- Docstrings:
src/ingest/qdrant_vectors.py:6 ("explore verb"), src/ingest/profile.py:6, src/ingest/embed_text.py
- Persisted names: SQLite table
pass2 (src/llm/cache.py), CorpusProfile.pass2_cache (src/profile.py:19)
- Test filenames:
tests/test_pipeline_pass1.py, test_pipeline_pass2.py, …
Plan
- Rename modules:
pass1.py→tag.py, pass2.py→summarize.py, explore.py→scan.py, build.py→index_stage.py (avoid shadowing the builtin), src/llm/pass2.py→src/llm/summarize.py; Pass1Stats→TagStats.
- Update imports, log strings, docstrings, test filenames.
- Backward compat for persisted artifacts: keep/alias
CorpusProfile.pass2_cache so existing profiles load; either keep the SQLite table name as an internal detail or add a one-line ALTER TABLE pass2 RENAME TO summarize migration in the cache constructor.
Note: README intentionally keeps "Pass-1/Pass-2" as conceptual stage labels — that stays. This issue is about code identifiers only.
From the 2026-06-10 codebase-health review. Priority: HIGH — top recommendation.
The user-facing verbs were renamed (tag / summarize / scan / index) and personas, CLI commands and docs use the new names — but the code identifiers still use the old ones, so the persona runner is a permanent translation layer and grep navigation is broken (searching "scan" finds
explore.py, etc.).Extent of the drift
src/pipeline/pass1.py,pass2.py,explore.py,build.py;src/llm/pass2.pyPass1Stats(src/pipeline/pass1.py)src/cli.py: ~110 old-name references (imports + hidden aliases)src/persona/runner.py: imports old module names, exposes new verbssrc/pipeline/build.py:21-22("pass1 (zero-loss)", "pass2 apply")src/ingest/qdrant_vectors.py:6("explore verb"),src/ingest/profile.py:6,src/ingest/embed_text.pypass2(src/llm/cache.py),CorpusProfile.pass2_cache(src/profile.py:19)tests/test_pipeline_pass1.py,test_pipeline_pass2.py, …Plan
pass1.py→tag.py,pass2.py→summarize.py,explore.py→scan.py,build.py→index_stage.py(avoid shadowing the builtin),src/llm/pass2.py→src/llm/summarize.py;Pass1Stats→TagStats.CorpusProfile.pass2_cacheso existing profiles load; either keep the SQLite table name as an internal detail or add a one-lineALTER TABLE pass2 RENAME TO summarizemigration in the cache constructor.Note: README intentionally keeps "Pass-1/Pass-2" as conceptual stage labels — that stays. This issue is about code identifiers only.