fix: Phase 1 bug fixes -- manifest, search index, issue #15

[costiash]

Summary

• Fix paths_manifest.json never being committed by CI/CD - The update-docs workflow regenerated the manifest every 3 hours but only staged docs/, so the root-level manifest was permanently stale
• Auto-generate .search_index.json in CI/CD pipeline - Content search only worked if someone manually ran build_search_index.py; now it rebuilds alongside every doc fetch
• Fix issue Content search fails when helper script is called with absolute path #15: content search fails from different working directories - load_search_index() used a bare relative path Path("docs/.search_index.json") that broke when called from outside the repo root; now resolves via __file__
• Remove all hardcoded doc counts - Replaced static references like "573 paths" and "571 files" with dynamic lookups or generic language, since the actual count drifts between environments

Test plan

• All 300 tests pass (295 baseline + 5 new)
• Helper script works (--version, --status, --help)
• CI/CD workflow includes paths_manifest.json in staging
• CI/CD workflow runs build_search_index.py
• No hardcoded "573" or "571" counts in helper script
• load_search_index() uses __file__-relative path resolution

Generated with Claude Code

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
scripts/lookup
search.py					137
Project Total

This report was generated by python-coverage-comment-action

[claude]

PR Review: Phase 1 Bug Fixes

[claude]

PR Review: Phase 1 Bug Fixes (continued)

Bugs and Correctness

python vs python3 in CI/CD workflow (potential breakage): The new Build search index step uses bare 'python' rather than 'python3'. GitHub Actions ubuntu-latest runners do not have a bare python binary - only python3. The rest of the workflow uses python3 consistently. This could silently fail or invoke Python 2.

wrapped in unit test is fragile: The new test accesses load_search_index.wrapped, which only exists when the function is decorated with a functools.wraps-aware decorator. If the decorator is ever removed, the test raises AttributeError rather than a clean failure. Consider using inspect.getsource(load_search_index) directly instead.

Code Quality

Missing set -e in build step: Without set -e, a failing Python script does not fail the workflow step. Add 'set -e' at the top of the run block so Python exceptions propagate as workflow failures and prevent committing a missing or empty index.

Verbose CI output: build_search_index.py prints a confirmation line for every file indexed (~570+ lines per run, every 3 hours). Consider suppressing per-file output in CI or adding a quiet flag.

Repeated subprocess calls for path count: enhanced_search(), update_all_docs(), and show_version() each spawn a separate Python subprocess to read the same value from paths_manifest.json. Minor overhead but worth caching.

Integration Tests

Pattern-matching tests are brittle: The tests check that strings like 'paths_manifest.json' and 'build_search_index.py' appear anywhere in the workflow YAML, including comments. They do not verify the manifest is staged in the correct git add command or runs in the right job.

What Is Done Well

• Manifest staging fix: adding paths_manifest.json to git add -A is exactly the right fix.
• file-relative path resolution in load_search_index() is the canonical approach. The three-level parent chain is correct for scripts/lookup/search.py -> repo root, and works in the installed location too.
• Dual fix for Issue Content search fails when helper script is called with absolute path #15 (Python file fix plus shell cd wrapping) provides defense in depth.
• Removing hardcoded counts prevents documentation drift between releases.
• The safeguard gate on the search index step correctly skips indexing when safeguards abort the sync.

Summary

Issue	Severity
python vs python3 in workflow	Should fix before merge
Missing set -e in build step	Worth fixing
wrapped in unit test	Fragile, easy to fix
Verbose CI output	Nice to have
Repeated subprocess calls	Minor

The manifest staging fix and the file-relative path fix are both correct and address real bugs. The main item to fix before merge is the python vs python3 issue, which could cause silent failures on ubuntu-latest runners.

[costiash]

Closing to address review feedback and clean up commit messages. Will reopen as new PR.