feat(v1.47.0): live progress bars for generate + update (spec 041)

Long generate runs (--count 40+) and update runs now show real
per-batch generation and per-test critic progress in two places:

- Terminal: Spectre.Console two-task progress bar via the new
  ProgressReporter.ProgressTwoTaskAsync wrapper. Generation handle
  advances per batch; verification handle advances per critic call
  with the latest test ID + verdict in the description. Update
  handler shows a single per-proposal bar.

- Browser progress page: a new progress section in
  .spectra-progress.html driven by an in-flight `progress` object
  inside .spectra-result.json. Verification bar is dimmed during
  the generation phase, then activated. Picked up by the existing
  1.5s auto-refresh; no new I/O during generation phase (reuses
  the existing per-batch result file flush).

Suppression rules: progress bars are suppressed under
--output-format json, --verbosity quiet, AND non-interactive stdout
(no TTY / piped). SKILL/CI invocations stay ANSI-free.

ProgressManager.Complete()/Fail() now clear the in-flight
ProgressSnapshot before the final write, so the final result file
always has runSummary instead of stale progress data.

+17 unit tests covering suppression rules, snapshot clear-on-complete,
and HTML rendering for generating/verifying/updating phases.

Out of scope: ETA, per-test progress within a batch, formal cancel.

Author: angelovstanton

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.47.0] - 2026-04-11
+
+### Added
+- **Live progress bars for `spectra ai generate` and `spectra ai update`** (spec 041). Long runs (`--count 40+`) now show real progress feedback in two places:
+  - **Terminal**: a `Generating tests` Spectre.Console progress bar advances per batch, followed by a `Verifying tests` bar that increments once per critic call (showing the most recent test ID and verdict). For `update`, an `Updating tests` bar advances per applied proposal.
+  - **Browser progress page** (`.spectra-progress.html`): a new live progress section renders the same data driven by an in-flight `progress` object inside `.spectra-result.json`, picked up on the existing 1.5s auto-refresh cycle. Verification bar is dimmed during the generation phase, then activated.
+- **`progress` field in `.spectra-result.json`** — present only while a run is in flight (snapshot of phase, target, generated, verified, current batch, total batches, last test ID, last verdict). Removed automatically by `ProgressManager.Complete()` / `Fail()` so the final result file shows `runSummary` instead. Schema documented in `specs/041-progress-bars/contracts/result-json-progress-schema.md`.
+- **`ProgressReporter.ProgressTwoTaskAsync(...)`** — new wrapper that creates two sequential Spectre tasks inside a single live region. Handles passed to the action implement a small `IProgressTaskHandle` abstraction so command handlers don't take a direct dependency on Spectre internals.
+- **`ProgressSnapshot` + `ProgressPhase` model** at `src/Spectra.CLI/Progress/ProgressSnapshot.cs`.
+- **+17 unit tests** — `ProgressBarTests`, `ProgressManagerProgressFieldTests`, `ProgressPageProgressBarTests` covering suppression rules, progress field clear-on-complete/fail, and HTML rendering for generation/verifying/updating phases.
+
+### Changed
+- **`ProgressReporter` suppression rules** — now suppresses progress bars not just under `--output-format json`, but also under `--verbosity quiet` and when stdout is non-interactive (redirected, piped, or no TTY). SKILL/CI invocations remain ANSI-free.
+- **`ProgressReporter.StatusAsync`** — short-circuits when the reporter is inside an active `ProgressTwoTaskAsync` block, so existing inline `_progress.StatusAsync(...)` spinners inside the batch loop don't conflict with the outer progress bars.
+- **`UpdateHandler.ApplyChangesAsync`** — gained an optional `onProposalApplied` callback parameter for per-proposal progress reporting. Existing call sites unaffected.
+
+### Notes
+- ETA / time-remaining display, per-test progress within a single generation batch, and formal cancel-with-cleanup on Ctrl+C are explicitly out of scope. See `specs/041-progress-bars/spec.md`.
+- `--output-format json` and `--verbosity quiet` behavior is unchanged: SKILLs and CI scripts see no progress-bar output on stdout.
+
 ## [1.46.1] - 2026-04-11
 
 ### Fixed

docs/cli-reference.md

@@ -188,6 +188,15 @@ spectra ai generate checkout --no-interaction --output-format json    # CI pipel
 
 Session state is stored in `.spectra/session.json` and expires after 1 hour.
 
+**Live progress bars** (spec 041) — at default verbosity, long runs render two
+sequential Spectre.Console progress bars in the terminal: a `Generating tests`
+bar that advances per batch, then a `Verifying tests` bar that advances per
+critic call (showing the most recent test ID and verdict). The same data is
+mirrored to `.spectra-progress.html` via an in-flight `progress` object inside
+`.spectra-result.json`. Progress bars are automatically suppressed under
+`--output-format json`, `--verbosity quiet`, or non-interactive stdout (piped
+or redirected) so SKILL/CI output remains clean.
+
 User-described tests are marked with `grounding.verdict: manual` and `source: user-described`.
 
 When a project has documentation in `docs/` and acceptance criteria in `docs/criteria/`, `--from-description` runs in **doc-aware mode**: it best-effort loads matching docs (capped at 3 docs × 8000 chars) and matching `.criteria.yaml` entries as formatting context, then populates the new test's `source_refs` (with the doc paths used) and `criteria` fields (with any IDs the AI matches to your description). The grounding verdict stays `manual` — doc context is used for terminology and navigation alignment only, never for verification. If no docs or criteria exist, the flow is identical to the no-context behavior.

specs/041-progress-bars/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Generation & Verification Progress Bars
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-04-11
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec mentions Spectre.Console and `.spectra-progress.html` / `.spectra-result.json` filenames, but these are existing project surfaces (not new technology choices) and are documented in the Assumptions section as such — so they are treated as scoped context, not implementation leakage.
+- All items pass on first iteration. Ready for `/speckit.plan`.

specs/041-progress-bars/contracts/result-json-progress-schema.md

@@ -0,0 +1,44 @@
+# Contract: `progress` field in `.spectra-result.json`
+
+**Producer**: `Spectra.CLI` `GenerateHandler`, `UpdateHandler` via `ProgressManager.Update(result)`.
+**Consumers**: `ProgressPageWriter` (writes `.spectra-progress.html`); SKILL/CI scripts that watch the result file.
+
+## Field
+
+`progress` is OPTIONAL and present only while a run is in flight. It MUST be absent from the final result file (after `Complete()` or `Fail()`).
+
+## Schema
+
+```json
+{
+  "progress": {
+    "phase":         "generating | verifying | updating",  // required
+    "testsTarget":   40,           // required, integer ≥ 0
+    "testsGenerated": 24,          // required, integer ≥ 0, ≤ testsTarget
+    "testsVerified":  0,           // required, integer ≥ 0, ≤ testsGenerated
+    "currentBatch":   3,           // required, integer ≥ 1, ≤ totalBatches
+    "totalBatches":   5,           // required, integer ≥ 1
+    "lastTestId":     "TC-124",    // optional, string or absent
+    "lastVerdict":    "grounded"   // optional; one of grounded|partial|hallucinated; absent unless phase = verifying
+  }
+}
+```
+
+## Stability Guarantees
+
+- Field names are camelCase (matches existing `JsonResultWriter` policy).
+- Consumers MUST tolerate the entire `progress` object being absent.
+- Consumers MUST tolerate `lastTestId` / `lastVerdict` being absent.
+- Adding new optional fields to `progress` in future revisions is non-breaking.
+- Removing or renaming fields is breaking and requires a spec increment.
+
+## Refresh Cadence
+
+- Generation phase: written after each batch completes (existing per-batch write site, no extra I/O).
+- Verification phase: written after each individual critic call completes (per-test write — acceptable since critic calls take 4–6s).
+- Update phase: written after each proposal application.
+- Final write (with `progress` absent): one write at end of run.
+
+## Reading Safety
+
+`ProgressPageWriter` writes `.spectra-result.json` via temp file + atomic move (existing path in `ProgressManager.FlushWriteFile`). Readers performing whole-file reads will always see a consistent snapshot — either the previous version or the new one, never a half-written file.

specs/041-progress-bars/data-model.md

@@ -0,0 +1,104 @@
+# Phase 1 Data Model: Progress Bars
+
+## ProgressSnapshot (record)
+
+Lives in `src/Spectra.CLI/Progress/ProgressSnapshot.cs` (NEW). Attached to `GenerateResult` and `UpdateResult` via an optional `Progress` field. Serialized as `progress` in `.spectra-result.json`.
+
+### Fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `Phase` | enum `ProgressPhase` | yes | `Generating` \| `Verifying` \| `Updating` |
+| `TestsTarget` | int | yes | Total tests this run intends to produce/process |
+| `TestsGenerated` | int | yes | Cumulative count after each completed batch (0 in `Updating` phase) |
+| `TestsVerified` | int | yes | Cumulative count after each completed critic call (0 outside `Verifying` phase) |
+| `CurrentBatch` | int | yes | 1-based index of the in-progress (or just-completed) unit. For `Generating`: batch index. For `Verifying`: stays at the final batch index. For `Updating`: proposal index. |
+| `TotalBatches` | int | yes | Total units. For `Generating`: `ceil(TestsTarget / GenerationBatchSize)`. For `Updating`: total proposal count. |
+| `LastTestId` | string? | no | Most recent test handled (test ID, e.g. `TC-118`) |
+| `LastVerdict` | string? | no | Critic verdict for `LastTestId`: `grounded` \| `partial` \| `hallucinated`. Null outside `Verifying`. |
+
+### Lifecycle / State Transitions
+
+```
+null
+  │
+  │ handler creates snapshot at start of generation
+  ▼
+Phase=Generating, TestsGenerated=0, TestsVerified=0, CurrentBatch=1, TotalBatches=N
+  │
+  │ after each batch completes: TestsGenerated += batch.RequestedCount, CurrentBatch++
+  ▼
+Phase=Generating, TestsGenerated=TestsTarget, CurrentBatch=N (terminal generation state)
+  │
+  │ critic phase begins (only if not --skip-critic)
+  ▼
+Phase=Verifying, TestsVerified=0
+  │
+  │ after each critic call: TestsVerified++, LastTestId, LastVerdict updated
+  ▼
+Phase=Verifying, TestsVerified=TestsTarget
+  │
+  │ ProgressManager.Complete() or .Fail()
+  ▼
+null  (cleared from final result file)
+```
+
+For `UpdateHandler`: snapshot starts as `Phase=Updating`, advances per proposal apply, cleared on completion.
+
+### Validation Rules
+
+- `TestsGenerated <= TestsTarget`
+- `TestsVerified <= TestsGenerated` (you cannot verify what wasn't generated)
+- `CurrentBatch <= TotalBatches`
+- `LastVerdict ∈ {grounded, partial, hallucinated, null}`
+- `Phase` ↔ `LastVerdict` consistency: `LastVerdict` MUST be null when `Phase != Verifying`
+
+These are invariants of the producing handler — not validated at deserialization (the consumer is the progress page, which is tolerant of missing fields).
+
+## Glossary Note
+
+**"Chunks" vs "Proposals"**: The original spec text referenced update "chunks". The actual `UpdateHandler` has no chunk concept — it does one classification batch and then a per-proposal apply loop. The Update progress bar tracks proposals; `CurrentBatch` / `TotalBatches` carry proposal counts in `Phase=Updating`. FR-005 is satisfied by per-proposal advancement.
+
+## Result File Shape (full example)
+
+In-flight (mid-generation):
+
+```json
+{
+  "status": "generating",
+  "command": "generate",
+  "suite": "checkout",
+  "progress": {
+    "phase": "generating",
+    "testsTarget": 40,
+    "testsGenerated": 24,
+    "testsVerified": 0,
+    "currentBatch": 3,
+    "totalBatches": 5,
+    "lastTestId": "TC-124",
+    "lastVerdict": null
+  }
+}
+```
+
+In-flight (mid-verification):
+
+```json
+{
+  "status": "generating",
+  "command": "generate",
+  "suite": "checkout",
+  "progress": {
+    "phase": "verifying",
+    "testsTarget": 40,
+    "testsGenerated": 40,
+    "testsVerified": 18,
+    "currentBatch": 5,
+    "totalBatches": 5,
+    "lastTestId": "TC-118",
+    "lastVerdict": "grounded"
+  }
+}
+```
+
+Final (after `Complete()`): `progress` field is omitted (`JsonIgnoreCondition.WhenWritingNull`); `runSummary` is present instead.