Skip to content

Finish the verb rename in code identifiers (pass1/pass2/explore/build → tag/summarize/scan/index) #42

@fmasi

Description

@fmasi

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

  1. 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.
  2. Update imports, log strings, docstrings, test filenames.
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    code-healthTidiness / refactoring findings from codebase-health reviews

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions