claude-code-generator 0.5.4__tar.gz → 0.5.6__tar.gz

{claude_code_generator-0.5.4/src/claude_code_generator.egg-info → claude_code_generator-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-generator
-Version: 0.5.4
+Version: 0.5.6
 Summary: Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file.
 Author: Silvio Baratto
 License: MIT

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-code-generator"
-version = "0.5.4"
+version = "0.5.6"
 description = "Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file."
 readme = "README.md"
 license = { text = "MIT" }

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6/src/claude_code_generator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-generator
-Version: 0.5.4
+Version: 0.5.6
 Summary: Orchestrator CLI that drives Claude Code end-to-end to generate whole projects from a requirements.md file.
 Author: Silvio Baratto
 License: MIT

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/src/claude_code_generator.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/claude_code_generator.egg-info/requires.txt
 src/claude_code_generator.egg-info/top_level.txt
 src/code_generator/__init__.py
 src/code_generator/agents.py
+src/code_generator/checklist.py
 src/code_generator/cli.py
 src/code_generator/effort.py
 src/code_generator/env.py
@@ -41,6 +42,7 @@ src/code_generator/gh/issues.py
 src/code_generator/gh/labels.py
 src/code_generator/gh/milestones.py
 src/code_generator/orchestrator/__init__.py
+src/code_generator/orchestrator/_cache_warmup.py
 src/code_generator/orchestrator/_client_lifecycle.py
 src/code_generator/orchestrator/_comments.py
 src/code_generator/orchestrator/_memory_writers.py
@@ -70,10 +72,14 @@ src/code_generator/prompts/prompt-review.md
 src/code_generator/runner/__init__.py
 src/code_generator/runner/_telemetry.py
 src/code_generator/runner/batch.py
+src/code_generator/runner/cache_breakpoints.py
+src/code_generator/runner/compaction_pause.py
 src/code_generator/runner/fake_runner.py
 src/code_generator/runner/mcp.py
+src/code_generator/runner/memory_tool.py
 src/code_generator/runner/message_parsing.py
 src/code_generator/runner/options.py
+src/code_generator/runner/phase_telemetry.py
 src/code_generator/runner/protocol.py
 src/code_generator/runner/rate_limit.py
 src/code_generator/runner/retry.py
@@ -97,12 +103,17 @@ tests/test_bench_compare.py
 tests/test_bench_export.py
 tests/test_bench_fixture.py
 tests/test_bench_regression.py
+tests/test_cache_breakpoints.py
+tests/test_cache_ttl_ordering.py
+tests/test_cache_warmup.py
 tests/test_changelog.py
+tests/test_checklist.py
 tests/test_claude_md.py
 tests/test_cli_io_logging.py
 tests/test_client_lifecycle.py
 tests/test_comments.py
 tests/test_commit_message.py
+tests/test_compaction_pause_handler.py
 tests/test_crash_recovery.py
 tests/test_cycle_loop.py
 tests/test_cycle_loop_multicycle.py
@@ -117,6 +128,7 @@ tests/test_docs_ollama_model_guide.py
 tests/test_docs_ollama_pro.py
 tests/test_effective_model_routing.py
 tests/test_effort.py
+tests/test_effort_routing_consistency.py
 tests/test_env.py
 tests/test_generate.py
 tests/test_generate_ollama.py
@@ -132,6 +144,7 @@ tests/test_logging_setup.py
 tests/test_max_turns_cli_flag.py
 tests/test_mcp.py
 tests/test_memory.py
+tests/test_memory_tool.py
 tests/test_memory_writers.py
 tests/test_message_parsing.py
 tests/test_no_max_turns_in_call_sites.py
@@ -144,12 +157,16 @@ tests/test_options.py
 tests/test_phase0.py
 tests/test_phase1.py
 tests/test_phase2.py
+tests/test_phase2_cache_regression.py
+tests/test_phase2_multicycle_token_reduction.py
+tests/test_phase2_token_reduction.py
 tests/test_phase3_4.py
 tests/test_phase5.py
 tests/test_phase5_precommit.py
 tests/test_phase6.py
 tests/test_phase7.py
 tests/test_phase_mcp_regression.py
+tests/test_phase_telemetry.py
 tests/test_phase_token_logging.py
 tests/test_preflight.py
 tests/test_preflight_ollama.py

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/src/code_generator/__init__.py

@@ -1,3 +1,3 @@
 """code-generator: orchestrator CLI for end-to-end project generation."""
 
-__version__ = "0.5.4"
+__version__ = "0.5.6"

claude_code_generator-0.5.6/src/code_generator/checklist.py

@@ -0,0 +1,121 @@
+"""Feature completion checklist (issue #249).
+
+Persists a JSON array of per-issue completion entries at
+``.code-generator/checklists/<requirements_hash>.json``. Phase 1 seeds the
+file; Phase 6 ticks ``tests_passed``; Phase 7 ticks ``committed``;
+``feature_done`` is derived (``tests_passed AND committed``) so the model
+cannot self-report completion.
+
+All writes follow the ``tmp → os.replace(tmp, path)`` pattern so a crash
+mid-write cannot corrupt the file. The module is orchestrator-only state —
+the SDK runner has no Write access to ``.code-generator/checklists/``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import asdict, dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from pathlib import Path
+
+    from code_generator.state import IssueState
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ChecklistEntry:
+    """One row in the per-feature completion checklist."""
+
+    issue_number: int
+    title: str
+    tests_passed: bool = False
+    committed: bool = False
+    feature_done: bool = False
+
+    def recompute_feature_done(self) -> None:
+        """Set ``feature_done`` from the two underlying flags."""
+        self.feature_done = self.tests_passed and self.committed
+
+
+def seed(path: Path, issues: Iterable[IssueState]) -> None:
+    """Atomically write the checklist for *issues* to *path* (idempotent).
+
+    Re-seeding with the same data is a no-op (file content stays byte-identical).
+    Re-seeding with new entries appends them while preserving any existing
+    ticks on the entries already in the file.
+    """
+    new_entries = [_entry_from_issue(issue) for issue in issues]
+    existing = {e.issue_number: e for e in load(path)}
+    merged: list[ChecklistEntry] = []
+    for fresh in new_entries:
+        prior = existing.get(fresh.issue_number)
+        merged.append(prior if prior is not None else fresh)
+    _atomic_write_json(path, [asdict(e) for e in merged])
+
+
+def load(path: Path) -> list[ChecklistEntry]:
+    """Return the checklist entries; ``[]`` when the file is absent."""
+    if not path.exists():
+        return []
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    return [_entry_from_dict(item) for item in raw]
+
+
+def tick_tests_passed(path: Path, issue_number: int) -> None:
+    """Set ``tests_passed=True`` on *issue_number*; recompute ``feature_done``."""
+    _tick(path, issue_number, "tests_passed")
+
+
+def tick_committed(path: Path, issue_number: int) -> None:
+    """Set ``committed=True`` on *issue_number*; recompute ``feature_done``."""
+    _tick(path, issue_number, "committed")
+
+
+def done_total(path: Path) -> tuple[int, int]:
+    """Return ``(feature_done_count, total_entries)`` — used by ``status``."""
+    entries = load(path)
+    return sum(1 for e in entries if e.feature_done), len(entries)
+
+
+def _tick(path: Path, issue_number: int, field: str) -> None:
+    """Mutate *field* to True for *issue_number*; warn + no-op when missing."""
+    entries = load(path)
+    target = next((e for e in entries if e.issue_number == issue_number), None)
+    if target is None:
+        _logger.warning(
+            "checklist tick: issue_number=%s not found in %s — no-op.",
+            issue_number,
+            path,
+        )
+        return
+    setattr(target, field, True)
+    target.recompute_feature_done()
+    _atomic_write_json(path, [asdict(e) for e in entries])
+
+
+def _entry_from_issue(issue: IssueState) -> ChecklistEntry:
+    return ChecklistEntry(issue_number=issue.number, title=issue.title)
+
+
+def _entry_from_dict(item: dict) -> ChecklistEntry:
+    return ChecklistEntry(
+        issue_number=int(item["issue_number"]),
+        title=str(item.get("title", "")),
+        tests_passed=bool(item.get("tests_passed", False)),
+        committed=bool(item.get("committed", False)),
+        feature_done=bool(item.get("feature_done", False)),
+    )
+
+
+def _atomic_write_json(path: Path, payload: list[dict]) -> None:
+    """``tmp.write_text(...) → os.replace(tmp, path)`` atomic write."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    os.replace(tmp_path, path)

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/src/code_generator/commands/_bench_io.py

@@ -17,7 +17,12 @@ if TYPE_CHECKING:
 
 # Bump this + add a migration note for any breaking schema change.
 # v2 (issue #212): per-phase dicts + totals now include ``num_turns``.
-SCHEMA_VERSION: int = 2
+# v3 (issue #248): per-phase dicts + totals add ``cache_write_5m``,
+#   ``cache_write_1h``, ``compaction_events``, ``clear_events``, and
+#   ``cache_hit_ratio`` (0.0-1.0 float). v2 readers still parse the original
+#   keys; v3 readers should fall back to ``.get(metric)`` so cross-version
+#   comparisons surface ``None`` rather than ``KeyError``.
+SCHEMA_VERSION: int = 3
 
 
 def write_output(path: Path | None, payload: dict[str, Any]) -> None:

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/src/code_generator/commands/_dispatch.py

@@ -19,6 +19,7 @@ import typer
 from code_generator import memory as _memory
 from code_generator.commands._crash_recovery import check_and_log_crash_recovery
 from code_generator.commands._resume import next_start_phase, resolve_continue_multi_cycle
+from code_generator.state import CycleState
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -110,6 +111,9 @@ def _compute_and_persist_graph_report(project_dir: Path, log: logging.Logger) ->
         return
 
     cmd = ["graphify", "update", "."]
+    # GRAPHIFY_NO_TIPS=1 suppresses the tip-printer that has a NameError in
+    # graphify v0.5.5 (_os not in scope outside the install block).
+    os.environ.setdefault("GRAPHIFY_NO_TIPS", "1")
     try:
         log.info("graph-report: refreshing (cmd=%s)", " ".join(cmd))
         subprocess.run(  # noqa: S603
@@ -121,13 +125,21 @@ def _compute_and_persist_graph_report(project_dir: Path, log: logging.Logger) ->
         )
     except subprocess.CalledProcessError as exc:
         stderr = _decode_stderr(exc.stderr)
-        log.warning(
-            "graph-report: graphify exited %d; using fallback. stderr: %s",
-            exc.returncode,
-            stderr or "<empty>",
-        )
-        _memory.write_memory_file(memories_dir, "cycle-repo-map.md", _memory.REPOMAP_FALLBACK)
-        return
+        # graphify v0.5.5 has a NameError in its tip-printer (_os not in scope)
+        # that fires after a successful update — treat it as success so the
+        # real GRAPH_REPORT.md is used instead of the fallback sentinel.
+        if "NameError: name '_os' is not defined" in (stderr or ""):
+            log.info(
+                "graph-report: graphify tip-printer bug (v0.5.5) — graph updated; ignoring exit 1"
+            )
+        else:
+            log.warning(
+                "graph-report: graphify exited %d; using fallback. stderr: %s",
+                exc.returncode,
+                stderr or "<empty>",
+            )
+            _memory.write_memory_file(memories_dir, "cycle-repo-map.md", _memory.REPOMAP_FALLBACK)
+            return
     except subprocess.TimeoutExpired as exc:
         log.warning(
             "graph-report: graphify timed out after %ss; using fallback",
@@ -207,6 +219,8 @@ def _reset_failed_cycles_for_continue(
 
     reset_ids: list[int] = []
     for c in st.cycles:
+        if not isinstance(c, CycleState):
+            continue
         if c.status != "failed":
             continue
         if target_cycle is not None and c.id != target_cycle:
@@ -343,7 +357,7 @@ async def dispatch_async(
     # Delta planning: multi-cycle with completed cycles needs a merge, not a
     # fresh Phase 0 run.  Single-mode delta is handled upstream (mode reset to
     # "unknown" forces Phase 0 to re-run via needs_phase0=True).
-    completed = [c for c in st.cycles if c.status == "completed"]
+    completed = [c for c in st.cycles if isinstance(c, CycleState) and c.status == "completed"]
     if delta_hash is not None and st.mode == "multi-cycle" and completed and state_path is not None:
         first_new_id = await _apply_delta_plan(
             st,
@@ -504,7 +518,9 @@ def dispatch_orchestrator(
             state_module.save_state(state_path, st)
 
         elif run_mode == "delta":
-            completed = [c for c in st.cycles if c.status == "completed"]
+            completed = [
+                c for c in st.cycles if isinstance(c, CycleState) and c.status == "completed"
+            ]
             if st.mode == "multi-cycle" and completed:
                 # Defer hash update to async path — atomicity requires Phase 0
                 # to succeed before we store the new hash.

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/src/code_generator/commands/bench.py

@@ -4,10 +4,19 @@ Signature:
     code-generator bench [--fake|--real] [--session-mode fresh|shared]
                          [--cycles N] [--fixture PATH] [--output FILE]
 
-Output schema (schema_version=1):
+Output schema (schema_version=3, see _bench_io.SCHEMA_VERSION):
     {schema_version, timestamp_utc, session_mode, fixture,
-     cycles: [{cycle_name, phases: {"0"…"7": {input, output,
-     cache_read, cache_write, cache_hit_pct, wall_seconds}}, totals}]}
+     cycles: [{cycle_name,
+               phases: {"0"…"7": {input, output, cache_read, cache_write,
+                                  cache_hit_pct, wall_seconds, num_turns,
+                                  cache_write_5m, cache_write_1h,
+                                  compaction_events, clear_events,
+                                  cache_hit_ratio}},
+               totals}]}
+
+v3 (issue #248): added the TTL split (cache_write_5m / cache_write_1h), the
+SDK lifecycle counters (compaction_events / clear_events), and the 0.0-1.0
+``cache_hit_ratio`` float used by ``bench compare`` for regression flagging.
 
 Bump schema_version + add a migration note for any breaking change.
 """
@@ -49,11 +58,20 @@ _LOGGER = logging.getLogger(__name__)
 # ---------------------------------------------------------------------------
 
 
+def _cache_hit_ratio(cache_read: int, cache_write: int, input_tokens: int) -> float:
+    """Return the 0–1 cache hit ratio (issue #248). Zero denominator → 0.0."""
+    denominator = cache_read + cache_write + input_tokens
+    if denominator <= 0:
+        return 0.0
+    return cache_read / denominator
+
+
 def _phase_metrics(result: RunResult) -> dict[str, int | float]:
-    """Convert a RunResult into the seven-key phase-metrics dict (schema v2).
+    """Convert a RunResult into the v3 phase-metrics dict (issue #248).
 
-    Includes ``num_turns`` as of issue #212 so operators can see per-phase
-    agent-loop turn counts alongside the four token counters.
+    v3 adds the TTL split (``cache_write_5m`` / ``cache_write_1h``), the SDK
+    lifecycle counters (``compaction_events`` / ``clear_events``), and the
+    0.0-1.0 ``cache_hit_ratio`` float alongside the existing v2 keys.
     """
     u = result.usage
     denominator = u.cache_read + u.cache_write + u.input
@@ -66,14 +84,20 @@ def _phase_metrics(result: RunResult) -> dict[str, int | float]:
         "cache_hit_pct": hit_pct,
         "wall_seconds": result.wall_seconds,
         "num_turns": u.num_turns,
+        "cache_write_5m": u.cache_write_5m,
+        "cache_write_1h": u.cache_write_1h,
+        "compaction_events": u.compaction_events,
+        "clear_events": u.clear_events,
+        "cache_hit_ratio": _cache_hit_ratio(u.cache_read, u.cache_write, u.input),
     }
 
 
 def _aggregate_totals(phases: dict[str, dict[str, int | float]]) -> dict[str, int | float]:
-    """Sum per-phase metrics into cycle-level totals with recomputed cache_hit_pct."""
+    """Sum per-phase metrics into cycle-level totals with recomputed ratios."""
     total_input = total_output = total_read = total_write = 0
     total_turns = 0
     total_wall = 0.0
+    total_5m = total_1h = total_compaction = total_clear = 0
     for m in phases.values():
         total_input += int(m["input"])
         total_output += int(m["output"])
@@ -81,6 +105,10 @@ def _aggregate_totals(phases: dict[str, dict[str, int | float]]) -> dict[str, in
         total_write += int(m["cache_write"])
         total_turns += int(m.get("num_turns", 0))
         total_wall += float(m["wall_seconds"])
+        total_5m += int(m.get("cache_write_5m", 0))
+        total_1h += int(m.get("cache_write_1h", 0))
+        total_compaction += int(m.get("compaction_events", 0))
+        total_clear += int(m.get("clear_events", 0))
 
     denominator = total_read + total_write + total_input
     hit_pct = round(total_read / denominator * 100, 1) if denominator else 0.0
@@ -92,6 +120,11 @@ def _aggregate_totals(phases: dict[str, dict[str, int | float]]) -> dict[str, in
         "cache_hit_pct": hit_pct,
         "wall_seconds": total_wall,
         "num_turns": total_turns,
+        "cache_write_5m": total_5m,
+        "cache_write_1h": total_1h,
+        "compaction_events": total_compaction,
+        "clear_events": total_clear,
+        "cache_hit_ratio": _cache_hit_ratio(total_read, total_write, total_input),
     }
 
 

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/src/code_generator/commands/bench_compare.py

@@ -28,6 +28,12 @@ METRIC_DIRECTION: dict[str, Literal["lower-better", "higher-better"]] = {
     "wall_seconds": "lower-better",
     "num_turns": "lower-better",
     "cache_hit_pct": "higher-better",
+    # v3 metrics (issue #248). New entries appended so v2 ordering is preserved.
+    "cache_write_5m": "lower-better",
+    "cache_write_1h": "lower-better",
+    "compaction_events": "lower-better",
+    "clear_events": "lower-better",
+    "cache_hit_ratio": "higher-better",
 }
 
 _METRICS_ORDER: list[str] = [
@@ -38,9 +44,19 @@ _METRICS_ORDER: list[str] = [
     "cache_hit_pct",
     "wall_seconds",
     "num_turns",
+    # v3 metrics — appended so legacy snapshots keep matching the v2 prefix.
+    "cache_write_5m",
+    "cache_write_1h",
+    "compaction_events",
+    "clear_events",
+    "cache_hit_ratio",
 ]
 _NUM_PHASES: int = 8
 
+# Threshold for the cache-hit-ratio regression warning (issue #248).
+# A ratio drop ≤ -0.05 (5 percentage points) triggers a WARNING line.
+_CACHE_HIT_RATIO_REGRESSION_THRESHOLD: float = -0.05
+
 
 # ---------------------------------------------------------------------------
 # Data model
@@ -116,8 +132,12 @@ def _build_row(
     a_phase: dict | None,
     b_phase: dict | None,
 ) -> DeltaRow:
-    a_val = float(a_phase[metric]) if a_phase is not None else None
-    b_val = float(b_phase[metric]) if b_phase is not None else None
+    # ``.get`` (not bracket access) so a v2 report compared against a v3
+    # report surfaces ``None`` for the new metrics rather than ``KeyError``.
+    a_raw = a_phase.get(metric) if a_phase is not None else None
+    b_raw = b_phase.get(metric) if b_phase is not None else None
+    a_val = float(a_raw) if a_raw is not None else None
+    b_val = float(b_raw) if b_raw is not None else None
     delta, delta_pct = _delta_values(a_val, b_val)
     return DeltaRow(
         phase=phase,
@@ -196,6 +216,35 @@ def render_delta_table(rows: list[DeltaRow], console: Console | None = None) ->
     _console.print(_build_table(rows))
 
 
+def _is_cache_hit_ratio_regression(row: DeltaRow) -> bool:
+    """True when *row* is a cache_hit_ratio regression ≤ -0.05 (issue #248)."""
+    if row.metric != "cache_hit_ratio" or row.delta is None:
+        return False
+    return row.delta <= _CACHE_HIT_RATIO_REGRESSION_THRESHOLD
+
+
+def _format_regression_warning(row: DeltaRow) -> str:
+    """Format the WARNING line for a single cache_hit_ratio regression row."""
+    a_pct = (row.a or 0.0) * 100
+    b_pct = (row.b or 0.0) * 100
+    delta_pp = abs((row.delta or 0.0) * 100)
+    return (
+        f"WARNING: cache_hit_ratio regressed {delta_pp:.1f}pp on phase {row.phase} "
+        f"(A={a_pct:.1f}%, B={b_pct:.1f}%)"
+    )
+
+
+def render_cache_hit_ratio_warnings(rows: list[DeltaRow], console: Console | None = None) -> None:
+    """Print one WARNING per cache_hit_ratio regression ≥5pp (issue #248).
+
+    Measurement-only — exit code stays 0 on regression.
+    """
+    _console = console or Console()
+    for row in rows:
+        if _is_cache_hit_ratio_regression(row):
+            _console.print(_format_regression_warning(row))
+
+
 def _build_table(rows: list[DeltaRow]) -> Table:
     table = Table(title="bench compare", show_header=True, header_style="bold")
     table.add_column("phase", style="dim")
@@ -247,3 +296,4 @@ def compare_command(
 
     rows = compute_deltas(a_report, b_report)
     render_delta_table(rows)
+    render_cache_hit_ratio_warnings(rows)

{claude_code_generator-0.5.4 → claude_code_generator-0.5.6}/src/code_generator/commands/status.py

@@ -9,6 +9,7 @@ import typer
 from rich.console import Console
 from rich.table import Table
 
+from code_generator import checklist as _checklist
 from code_generator import state as state_module
 from code_generator.runner.types import TokenUsage
 from code_generator.state_retention import CycleTelemetrySummary
@@ -40,9 +41,20 @@ def status_command() -> None:
         console.print(f"[bold red]⚠ Last error: {st.last_error}[/bold red]\n")
 
     _render_summary_table(console, st)
+    _render_checklist_summary(console, st, project_dir)
 
     if st.mode == "multi-cycle" and st.cycles:
         _render_cycles_table(console, st)
+        for cycle in st.cycles:
+            if isinstance(cycle, CycleTelemetrySummary):
+                continue
+            if not cycle.token_usage:
+                continue
+            console.print(f"\n[bold]{cycle.name}[/bold]")
+            _render_phase_telemetry_lines(console, cycle.token_usage)
+    elif st.token_usage:
+        console.print()
+        _render_phase_telemetry_lines(console, st.token_usage)
 
 
 def _pause_remaining(state: state_module.State) -> str:
@@ -145,6 +157,101 @@ def _format_pct_5h(token_usage: dict[str, TokenUsage]) -> str:
     return f"{pct:.1f}%"
 
 
+# Canonical phase order + display labels for the per-phase telemetry block (#247).
+_PHASE_LABELS: tuple[tuple[str, str], ...] = (
+    ("phase0", "0"),
+    ("phase1", "1"),
+    ("phase2", "2"),
+    ("phase3_4", "3/4"),
+    ("phase5", "5"),
+    ("phase6", "6"),
+    ("phase7", "7"),
+)
+
+
+def _humanize(n: int) -> str:
+    """Render *n* as a compact token count (``"12k"`` for ``12_345``).
+
+    Values below 1000 render verbatim. Values ≥ 1000 are divided by 1000 and
+    rounded with banker's rounding, matching the briefing's worked examples
+    (12_499 → ``"12k"``, 12_500 → ``"12k"``).
+    """
+    if n < 1000:
+        return str(n)
+    return f"{round(n / 1000)}k"
+
+
+def _phase_cache_hit_pct(usage: TokenUsage) -> int:
+    """Per-phase cache hit percent, rounded to the nearest integer.
+
+    Returns ``0`` when the denominator is zero so callers never need to guard
+    against ``ZeroDivisionError``.
+    """
+    denominator = usage.cache_read + usage.cache_write + usage.input
+    if denominator <= 0:
+        return 0
+    return round(usage.cache_read / denominator * 100)
+
+
+def _phase_has_activity(usage: TokenUsage) -> bool:
+    """Return True when *usage* records any non-zero counter worth printing."""
+    return bool(
+        usage.input
+        or usage.output
+        or usage.cache_read
+        or usage.cache_write
+        or usage.cache_write_5m
+        or usage.cache_write_1h
+    )
+
+
+def _render_checklist_summary(
+    console: Console, state: state_module.State, project_dir: Path
+) -> None:
+    """Print ``features: <done>/<total>`` from the §13 checklist (issue #251).
+
+    Prints the dim placeholder ``features: -`` when ``state.requirements_hash``
+    is unset or the checklist file does not yet exist. The status command must
+    never crash because the checklist is missing — it is purely informational.
+    """
+    if state.requirements_hash is None:
+        console.print("[dim]features: -[/dim]")
+        return
+    checklist_path = (
+        project_dir / ".code-generator" / "checklists" / f"{state.requirements_hash}.json"
+    )
+    if not checklist_path.exists():
+        console.print("[dim]features: -[/dim]")
+        return
+    done, total = _checklist.done_total(checklist_path)
+    console.print(f"features: {done}/{total}")
+
+
+def _render_phase_telemetry_lines(console: Console, token_usage: dict[str, TokenUsage]) -> None:
+    """Print one line per non-empty phase in canonical order (#247).
+
+    Format::
+
+        phase <label>: in=<X>k cache_read=<X>k(<P>%)
+            cache_write_5m=<X>k cache_write_1h=<X>k out=<X>k
+
+    Phases with all-zero counters are suppressed. Non-canonical keys are
+    silently skipped.
+    """
+    for key, label in _PHASE_LABELS:
+        usage = token_usage.get(key)
+        if usage is None or not _phase_has_activity(usage):
+            continue
+        console.print(
+            f"phase {label}: "
+            f"in={_humanize(usage.input)} "
+            f"cache_read={_humanize(usage.cache_read)}({_phase_cache_hit_pct(usage)}%) "
+            f"cache_write_5m={_humanize(usage.cache_write_5m)} "
+            f"cache_write_1h={_humanize(usage.cache_write_1h)} "
+            f"out={_humanize(usage.output)}"
+        )
+
+
 def _format_cache_hit_pct(cache_telemetry: dict[str, int | float]) -> str:
     """Format cache_hit_pct as XX.X% or '-' when telemetry is absent or all-zero.