feat(cli): PR-3 pass starts, heartbeats, pipeline header/footer, docs

[HumanBean17]

Scope

Implements plans/PLAN-CLI-PROGRESS-OUTPUT.md PR-3: pass-start lines and 5s heartbeats in build_ast_graph.py (verbose only), pipeline header/footer in java_codebase_rag/cli.py for lifecycle commands, erase --quiet, README + CLI + agent guide + top-level --help, and tests (test_cli_quiet_parity.py, test_cli_progress_stdout_invariant.py).

Behaviour

• Graph builder: Appendix B start lines; [passN] running … <int>s elapsed / [write] running … every 5s under --verbose; module lock for atomic stderr lines; JAVA_CODEBASE_RAG_TEST_GRAPH_SLOW_SEC test hook in pass1 (documented in tests/README.md).
• CLI: java-codebase-rag <cmd> · source=… · index=… header and matching footer (monotonic clock, two decimal seconds). Suppressed when --quiet. Increment staleness warning still prints before banner.
• Docs: One sentence on stderr streaming and --quiet in README, docs/JAVA-CODEBASE-RAG-CLI.md, docs/AGENT-GUIDE.md.

Tests

• tests/test_cli_quiet_parity.py: heartbeat ordering, pass1 start before summary, pipeline header/footer regex, quiet forbidden markers (+ increment warning).
• tests/test_cli_progress_stdout_invariant.py: erase/init stdout strings; increment/reprocess via JSON where needed.

Manual evidence

.venv/bin/ruff check build_ast_graph.py java_codebase_rag/cli.py tests/test_cli_quiet_parity.py tests/test_cli_progress_stdout_invariant.py
.venv/bin/python -m pytest tests/test_cli_quiet_parity.py tests/test_cli_progress_stdout_invariant.py -v

Notes

• Builds on PR-2 (feat/cli-progress-output-pr-2) for streaming + [lance] lines; quiet tests still assert those markers never appear under --quiet.
• No ontology bump; no re-index requirement for this PR alone.

Made with Cursor