diff --git a/plans/PLAN-CLI-PROGRESS-OUTPUT.md b/plans/completed/PLAN-CLI-PROGRESS-OUTPUT.md similarity index 95% rename from plans/PLAN-CLI-PROGRESS-OUTPUT.md rename to plans/completed/PLAN-CLI-PROGRESS-OUTPUT.md index bf7e364..41cc737 100644 --- a/plans/PLAN-CLI-PROGRESS-OUTPUT.md +++ b/plans/completed/PLAN-CLI-PROGRESS-OUTPUT.md @@ -1,7 +1,7 @@ # Plan: CLI progress output (Phase 1 — stream + heartbeats) -Status: **active**. This plan implements -[`propose/CLI-PROGRESS-OUTPUT-PROPOSE.md`](../propose/CLI-PROGRESS-OUTPUT-PROPOSE.md). +Status: **completed**. This plan implements +[`propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md`](../../propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md). Depends on: **none** (orthogonal to graph schema / ontology). No `ontology_version` bump and no re-index requirement. @@ -25,7 +25,7 @@ Depends on: **none** (orthogonal to graph schema / ontology). No `ontology_versi | PR | Scope | Ontology bump | Files touched (approx) | Test buckets | Independent of | | --- | --- | --- | --- | --- | --- | -| PR-1 | Propose merge / scope lock (if not already on main) | no | `propose/CLI-PROGRESS-OUTPUT-PROPOSE.md` | none | none | +| PR-1 | Propose merge / scope lock (if not already on main) | no | `propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md` | none | none | | PR-2 | Live stream stdout+stderr; cocoindex `[lance]` wrap; full buffers for tails; quiet parity | no | `server.py`, `java_codebase_rag/pipeline.py`, `java_codebase_rag/cli.py`, new test module | unit + integration (stdout invariant, quiet) | PR-1 if propose already merged | | PR-3 | Pass-start lines, 5 s heartbeats (`build_ast_graph.py` + `write`), pipeline header/footer, README + `docs/JAVA-CODEBASE-RAG-CLI.md` + `docs/AGENT-GUIDE.md` + `--help` one-liner | no | `build_ast_graph.py`, `java_codebase_rag/cli.py`, `README.md`, CLI docs, agent guide, tests | heartbeat ordering, header/footer, quiet extension, stdout invariant regression | PR-2 | @@ -46,7 +46,7 @@ Landing order: **PR-1 (optional) → PR-2 → PR-3**. ## File-by-file changes -### 1. `propose/CLI-PROGRESS-OUTPUT-PROPOSE.md` +### 1. `propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md` - Land or refresh status so the propose is the reviewed anchor for Phase 1 scope and Phase 2 deferrals. @@ -62,7 +62,7 @@ Landing order: **PR-1 (optional) → PR-2 → PR-3**. | # | Step | File(s) | Done when | | --- | --- | --- | --- | -| 1 | Confirm propose merged | `propose/CLI-PROGRESS-OUTPUT-PROPOSE.md` | PR-2 branch can rebase on it | +| 1 | Confirm propose merged | `propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md` | PR-2 branch can rebase on it | --- @@ -201,12 +201,12 @@ Use `tests/test_cli_quiet_parity.py` for quiet regression (propose §8 / §6). 1. Long `init` / `reprocess` runs emit visible stderr at most ~5 s apart during graph passes (verbose) and stream cocoindex + builder child output live when not `--quiet`. 2. `--quiet` lifecycle runs: stdout payloads match checked baselines; **stderr matches per-subcommand baselines from today** (no new markers from this work; `increment --quiet` baseline includes the existing staleness warning). 3. Documentation and `--help` describe stderr streaming and `--quiet` suppression. -4. `propose/CLI-PROGRESS-OUTPUT-PROPOSE.md` status updated to **completed** when the feature set is merged; this plan moved to `plans/completed/` after the final PR lands. +4. `propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md` status updated to **completed** when the feature set is merged; this plan moved to `plans/completed/` after the final PR lands. # Tracking - `PR-1` (propose): _done_ -- `PR-2` (stream + wrap): _pending_ -- `PR-3` (heartbeats + docs): _pending_ +- `PR-2` (stream + wrap): _done_ +- `PR-3` (heartbeats + docs): _done_ Optional follow-up: add `plans/CURSOR-PROMPTS-CLI-PROGRESS-OUTPUT.md` using `plans/completed/CURSOR-PROMPTS-TIER1B.md` as the structural template for per-PR Cursor handoffs. diff --git a/propose/CLI-PROGRESS-OUTPUT-PROPOSE.md b/propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md similarity index 98% rename from propose/CLI-PROGRESS-OUTPUT-PROPOSE.md rename to propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md index c7dacdb..ac1f982 100644 --- a/propose/CLI-PROGRESS-OUTPUT-PROPOSE.md +++ b/propose/completed/CLI-PROGRESS-OUTPUT-PROPOSE.md @@ -1,9 +1,9 @@ # CLI-PROGRESS-OUTPUT — make `java-codebase-rag` lifecycle commands tell the user what they're doing -**Status**: approved — locked for Phase 1 implementation per `plans/PLAN-CLI-PROGRESS-OUTPUT.md`; §7 authoritative. +**Status**: completed — Phase 1 implementation landed; archived with `plans/completed/PLAN-CLI-PROGRESS-OUTPUT.md`; §7 remains authoritative history. **Author**: Dmitriy Teriaev + Perplexity Computer **Date**: 2026-05-11 -**Last amended**: 2026-05-13 (pass5/pass6 + cocoindex stdout tee + risk wording + quiet stderr baseline parity §3.3; PR-1: status locked for implementation) +**Last amended**: 2026-05-14 (phase complete; moved to `propose/completed/`) ## TL;DR @@ -20,7 +20,7 @@ ## §1 — Frame: what is this propose, really? -The `java-codebase-rag` CLI is the operator's lifecycle interface to the index ([`CLI-SCENARIOS-PROPOSE.md`](completed/CLI-SCENARIOS-PROPOSE.md) §1). Its current output behaviour breaks two implicit promises of any lifecycle CLI: +The `java-codebase-rag` CLI is the operator's lifecycle interface to the index ([`CLI-SCENARIOS-PROPOSE.md`](CLI-SCENARIOS-PROPOSE.md) §1). Its current output behaviour breaks two implicit promises of any lifecycle CLI: 1. **"I'm alive."** A long-running command must keep emitting *something* often enough that the user does not start guessing. 2. **"I tell the truth about what's happening."** When the work involves multiple phases, the user should be able to tell which phase is running right now, not only which phase finished N minutes ago. @@ -45,7 +45,7 @@ This frame rules out: 3. **No new runtime dependencies.** No `rich`, no `tqdm`, no `click`. Pure stdlib `time` / `sys` / `threading`. 4. **Honest about partial knowledge.** When a pass cannot announce a percentage (e.g. cocoindex internals are opaque to us), we say "running…" with elapsed time, not a fake bar. Mirrors the "partial fidelity is loud" principle from CLI-SCENARIOS §2. 5. **`--quiet` is sacred.** The `--quiet` flag (which sets `quiet=True` and drops `--verbose` from the graph builder) must continue to suppress *every* new line **this propose adds**, including the pipeline header / footer and heartbeats. **Overall** `--quiet` stderr behaviour follows §3.3: **baseline equality** with today per subcommand, not “stderr is always empty” (`increment --quiet` already prints the staleness warning). CI consumers depend on no *additional* noise from this work. -6. **Cardinal-number discipline.** This propose locks **5 user-visible improvements** (stream, cocoindex wrap, heartbeats, pass-start lines, pipeline header/footer) across **3 PRs**. Adding a 6th improvement in this round requires a propose amendment, not a drive-by. Mirrors [`propose/completed/CLI-SCENARIOS-PROPOSE.md`](completed/CLI-SCENARIOS-PROPOSE.md) §6. +6. **Cardinal-number discipline.** This propose locks **5 user-visible improvements** (stream, cocoindex wrap, heartbeats, pass-start lines, pipeline header/footer) across **3 PRs**. Adding a 6th improvement in this round requires a propose amendment, not a drive-by. Mirrors [`propose/completed/CLI-SCENARIOS-PROPOSE.md`](CLI-SCENARIOS-PROPOSE.md) §6. 7. **Heartbeat cadence is fixed at ~5 s.** Not adjustable in this round (one knob, one default; matches CLI-SCENARIOS "one source of truth per config knob" principle). A future propose may make it configurable if a real consumer needs it. 8. **No structural change to the pipeline.** We surface existing phases; we do not split, merge, reorder, or rename passes in `build_ast_graph.py`.