Merge branch '025-universal-skill-progress'

Universal progress/result for all SKILL-wrapped commands.
ProgressManager shared service, 36 new tests, 1315 total passing.

Author: angelovstanton

CLAUDE.md

@@ -199,6 +199,7 @@ spectra config list-automation-dirs                 # List dirs with existence s
 - **Tests:** xUnit with structured results (never throw on validation errors)
 
 ## Recent Changes
+- 025-universal-skill-progress: ✅ COMPLETE - Universal progress/result for all SKILL-wrapped commands. New shared `ProgressManager` service (`src/Spectra.CLI/Progress/ProgressManager.cs`) extracts duplicated progress/result file logic from GenerateHandler and DocsIndexHandler. New `ProgressPhases` static class defines phase sequences for 6 command types. All 9 SKILL-wrapped commands now write `.spectra-result.json` on completion. 6 long-running commands (generate, update, docs-index, coverage, extract-criteria, dashboard) write `.spectra-progress.html` with auto-refreshing phase stepper. `ProgressPageWriter` extended with phase configs for update (classifying/updating/verifying), coverage (scanning-tests/analyzing-docs/analyzing-criteria/analyzing-automation), extract-criteria (scanning-docs/extracting/building-index), and dashboard (collecting-data/generating-html). Dynamic title support in progress page header ("SPECTRA — Coverage Analysis", etc.). Summary card renderers for coverage percentages, update counts, criteria counts, dashboard stats. Renamed `AnalyzeCoverageResult.Requirements` → `AcceptanceCriteria` (JSON: `acceptanceCriteria`). New `UpdateResult` model with classification counts. Updated all SKILL files (coverage, criteria, dashboard, validate) with universal 5-step progress flow. Updated generation agent prompt with progress/result instructions for all commands. 36 new tests (19 ProgressManager unit tests, 9 ProgressPageWriter phase/title tests, 5 SKILL flag verification tests, 3 terminology audit tests). 1315 total tests passing.
 - 024-docs-skill-coverage-fix: ✅ COMPLETE - Docs index SKILL integration, progress page, coverage fix & terminology rename. Added `.spectra-result.json` and `.spectra-progress.html` to `DocsIndexHandler` (same pattern as generate). New `--skip-criteria` flag skips auto-triggered acceptance criteria extraction. `--no-interaction` passthrough to criteria extraction (runs with defaults). Extended `DocsIndexResult` with new fields (skipped, new, total, criteria). Extended `ProgressPageWriter` for docs-index phases (scanning, indexing, extracting-criteria). New `spectra-docs` SKILL (9th bundled SKILL) with structured tool-call-sequence. Completed "requirements" → "acceptance criteria" rename in all remaining user-facing strings. `CriteriaIndexReader` auto-renames legacy `_requirements.yaml` to `.bak`. Dashboard coverage null-crash fix with zero-state defaults. Updated generation agent prompt for docs index progress-aware flow. Version 1.30.0. 1279 total tests passing.
 - 023-criteria-extraction-overhaul: ✅ COMPLETE - Acceptance criteria import & extraction overhaul. Renamed "requirements" to "acceptance criteria" across codebase (CLI, dashboard, reports, SKILLs, agents). Replaced single-prompt AI extraction (truncation-prone) with per-document iterative extraction producing individual `.criteria.yaml` files and `_criteria_index.yaml` master index. SHA-256 incremental extraction skips unchanged docs. Import from YAML/CSV/JSON with auto-column-detection for Jira/ADO exports, AI splitting of compound criteria, RFC 2119 normalization. `--merge` (default) and `--replace` modes. `--list-criteria` with `--source-type`, `--component`, `--priority` filters. Generation auto-loads related criteria as prompt context, produces `criteria` field in test frontmatter. Update flow detects criteria changes (OUTDATED/ORPHANED classification). Dashboard shows per-source-type coverage breakdown. New `spectra-criteria` SKILL (8th). `--extract-requirements` kept as hidden alias. New models: `AcceptanceCriterion`, `CriteriaIndex`, `CriteriaSource`, `AcceptanceCriteriaCoverage`. New services: `CriteriaExtractor`, `CriteriaIndexReader/Writer`, `CriteriaFileReader/Writer`, `CsvCriteriaImporter`, `JsonCriteriaImporter`, `CriteriaMerger`. Live progress HTML page (`.spectra-progress.html`) with auto-refresh for generation status. SKILL/agent names standardized to lowercase-hyphenated format. `browser/openBrowserPage` added to all tool lists. BehaviorAnalyzer retry on failure. MCP `finalize_execution_run` returns instruction to open HTML report. `--no-interaction` on all SKILL CLI commands. `--focus` flag for filtered generation. 38+ new tests, 1280+ total passing.
 - 023-copilot-chat-integration: ✅ COMPLETE - Full VS Code Copilot Chat integration for test generation and all CLI features. Added `--suite` option (flag alternative to positional arg) for LLM-friendly syntax. Added `--analyze-only` flag for two-step analyze→approve→generate flow. Automatic batch generation for large counts (batches of 30, writes per batch, index updates per batch). Live progress via `.spectra-result.json` with status lifecycle: analyzing→analyzed→generating→completed/failed. BehaviorAnalyzer timeout increased 30s→2min with proper error handling (was silently failing). 7 bundled SKILLs (generate, coverage, dashboard, validate, list, init-profile, help) with explicit tool-call-sequence format. Both agents (Generation, Execution) handle all SPECTRA commands with help reference. Progress messages from AI tool calls (scanning docs, reading docs, allocating IDs, verifying tests). Per-test verification progress. Critic verification per batch. Smart fallback count accounting for existing tests. Result file with `FileStream.Flush(true)` for Windows NTFS reliability. 1241 total passing.

specs/025-universal-skill-progress/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Universal Progress/Result for SKILL-Wrapped Commands
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-04-08
+**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
+
+- All items pass. The spec is derived from a detailed technical design document but has been written at the "what/why" level without leaking implementation specifics.
+- The user's original feature description included extensive technical details (C# code, file paths, JSON schemas) which informed the spec's accuracy but were abstracted into business-level requirements.
+- Assumptions section documents key design decisions (no concurrent run support, fast vs. long-running command distinction, auto-trigger default for criteria extraction).

specs/025-universal-skill-progress/contracts/progress-html-contract.md

@@ -0,0 +1,39 @@
+# Contract: .spectra-progress.html
+
+**Version**: 1.0  
+**Consumer**: VS Code Live Preview panel (opened by SKILL via `show preview`)
+
+## Behavior Contract
+
+1. **Created** when a long-running command starts (before first phase)
+2. **Updated** at each phase transition and sub-step within phases
+3. **Auto-refreshes** every 2 seconds via `<meta http-equiv="refresh" content="2">`
+4. **Auto-refresh removed** when command reaches terminal state (completed/failed)
+5. **Self-contained** — no external CSS, JS, or fetch calls; all data embedded inline
+6. **File links** use `vscode://file/` URI scheme for one-click navigation
+
+## Visual Elements
+
+| Element | Always Present | Description |
+|---------|---------------|-------------|
+| Title | Yes | "SPECTRA — {Command Name}" in header |
+| Phase stepper | Yes | Horizontal steps showing progress through phases |
+| Status badge | Yes | Current phase name with spinner (or checkmark/X) |
+| Summary cards | When data available | Key metrics in card grid (e.g., "Documents: 15", "Criteria: 45") |
+| Error card | On failure only | Red card with error message |
+| File links | On completion | Links to generated artifacts |
+
+## Commands That Write Progress HTML
+
+| Command | Title | Phases |
+|---------|-------|--------|
+| generate | Test Generation | Analyzing → Analyzed → Generating → Completed |
+| update | Test Update | Classifying → Updating → Verifying → Completed |
+| docs-index | Documentation Index | Scanning → Indexing → Extracting Criteria → Completed |
+| coverage | Coverage Analysis | Scanning Tests → Analyzing Docs → Analyzing Criteria → Analyzing Automation → Completed |
+| extract-criteria | Criteria Extraction | Scanning Docs → Extracting → Building Index → Completed |
+| dashboard | Dashboard Generation | Collecting Data → Generating HTML → Completed |
+
+## Commands That Do NOT Write Progress HTML
+
+validate, list, show, init, import-criteria, list-criteria — these complete too quickly to benefit from a progress page.

specs/025-universal-skill-progress/contracts/result-json-schema.md

@@ -0,0 +1,107 @@
+# Contract: .spectra-result.json Schema
+
+**Version**: 1.0  
+**Consumer**: VS Code Copilot Chat SKILLs (via `readFile .spectra-result.json`)
+
+## Base Schema (all commands)
+
+```json
+{
+  "command": "string",
+  "status": "string",
+  "timestamp": "string (ISO 8601 UTC)",
+  "message": "string | null"
+}
+```
+
+## Per-Command Extensions
+
+### generate
+```json
+{
+  "command": "generate",
+  "status": "analyzing | analyzed | generating | completed | failed",
+  "suite": "string",
+  "analysis": { "total_behaviors": 0, "already_covered": 0, "recommended": 0 },
+  "generation": { "tests_requested": 0, "tests_generated": 0, "tests_written": 0 }
+}
+```
+
+### update
+```json
+{
+  "command": "update",
+  "status": "classifying | updating | verifying | completed | failed",
+  "suite": "string",
+  "testsUpdated": 0,
+  "testsRemoved": 0,
+  "testsUnchanged": 0,
+  "classification": { "upToDate": 0, "outdated": 0, "orphaned": 0, "redundant": 0 }
+}
+```
+
+### docs-index
+```json
+{
+  "command": "docs-index",
+  "status": "scanning | indexing | extracting-criteria | completed | failed",
+  "documentsIndexed": 0,
+  "documentsSkipped": 0,
+  "documentsTotal": 0,
+  "criteriaExtracted": 0
+}
+```
+
+### analyze-coverage
+```json
+{
+  "command": "analyze-coverage",
+  "status": "scanning-tests | analyzing-docs | analyzing-criteria | analyzing-automation | completed | failed",
+  "documentationCoverage": { "percentage": 0, "covered": 0, "total": 0 },
+  "acceptanceCriteriaCoverage": { "percentage": 0, "covered": 0, "total": 0 },
+  "automationCoverage": { "percentage": 0, "covered": 0, "total": 0 }
+}
+```
+
+### extract-criteria
+```json
+{
+  "command": "extract-criteria",
+  "status": "scanning-docs | extracting | building-index | completed | failed",
+  "documentsProcessed": 0,
+  "documentsSkipped": 0,
+  "criteriaExtracted": 0,
+  "criteriaNew": 0,
+  "criteriaUpdated": 0
+}
+```
+
+### dashboard
+```json
+{
+  "command": "dashboard",
+  "status": "collecting-data | generating-html | completed | failed",
+  "outputPath": "string",
+  "suitesIncluded": 0,
+  "testsIncluded": 0
+}
+```
+
+### validate
+```json
+{
+  "command": "validate",
+  "status": "completed | failed",
+  "totalFiles": 0,
+  "valid": 0,
+  "errors": []
+}
+```
+
+## Guarantees
+
+1. File is written atomically (flush to disk) — never partially written
+2. File is deleted at command start — stale data never persists
+3. File exists after command completion (success or failure)
+4. `status` field always present — SKILL can poll for "completed" or "failed"
+5. On failure: `"success": false` and `"error": "message"` fields present

specs/025-universal-skill-progress/data-model.md

@@ -0,0 +1,96 @@
+# Data Model: Universal Progress/Result
+
+**Date**: 2026-04-08  
+**Branch**: `025-universal-skill-progress`
+
+## New Entities
+
+### ProgressManager
+
+Shared service encapsulating progress/result file lifecycle.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| Command | string | Command identifier (e.g., "generate", "docs-index", "coverage") |
+| Phases | string[] | Ordered phase names for the phase stepper |
+| Title | string | Display title for progress page header |
+| ResultPath | string | Path to `.spectra-result.json` (workspace root) |
+| ProgressPath | string | Path to `.spectra-progress.html` (workspace root) |
+
+**Lifecycle**: Reset → Start → Update(n) → Complete | Fail
+
+**Methods**:
+- `Reset()` — Delete stale files
+- `StartAsync(title)` — Create initial progress HTML
+- `UpdateAsync(phase, message, summaryData?)` — Update both files
+- `CompleteAsync(result)` — Write final result, remove auto-refresh
+- `FailAsync(error, partialResult?)` — Write error state
+
+### ProgressPhases (static)
+
+Phase sequences per command type.
+
+| Command | Phases |
+|---------|--------|
+| Generate | Analyzing → Analyzed → Generating → Completed |
+| Update | Classifying → Updating → Verifying → Completed |
+| DocsIndex | Scanning → Indexing → Extracting Criteria → Completed |
+| Coverage | Scanning Tests → Analyzing Docs → Analyzing Criteria → Analyzing Automation → Completed |
+| ExtractCriteria | Scanning Docs → Extracting → Building Index → Completed |
+| Dashboard | Collecting Data → Generating HTML → Completed |
+
+## Modified Entities
+
+### AnalyzeCoverageResult (rename field)
+
+| Field | Old Name | New Name | Type |
+|-------|----------|----------|------|
+| Acceptance criteria section | `Requirements` | `AcceptanceCriteria` | CoverageSection |
+
+JSON output changes: `"requirements": {...}` → `"acceptanceCriteria": {...}`
+
+## File Artifacts
+
+### .spectra-result.json
+
+Written by all SKILL-wrapped commands. Schema varies by command but always includes base fields:
+
+```json
+{
+  "command": "string",
+  "status": "string (analyzing|generating|completed|failed|...)",
+  "timestamp": "ISO 8601 UTC",
+  "message": "string (optional)"
+}
+```
+
+### .spectra-progress.html
+
+Written by long-running commands only. Self-contained HTML with:
+- Auto-refresh meta tag (2s interval, removed on completion/failure)
+- Phase stepper showing progress through command phases
+- Summary cards with command-specific data
+- Status badge with current operation message
+- Error card (on failure)
+- VS Code file links for generated artifacts
+
+## State Transitions
+
+```
+[Reset] → files deleted
+   ↓
+[Start] → progress HTML created (phase 1 active, auto-refresh ON)
+   ↓
+[Update]* → progress HTML updated (phase N active), result JSON updated
+   ↓
+[Complete] → final result JSON, auto-refresh OFF, last phase marked done
+   OR
+[Fail] → error result JSON, auto-refresh OFF, current phase marked failed
+```
+
+## Relationships
+
+- `ProgressManager` → uses `ProgressPageWriter` (existing static class)
+- `ProgressManager` → uses `JsonResultWriter` serialization options
+- Each command handler → owns one `ProgressManager` instance
+- `ProgressPageWriter` → reads `ProgressPhases` to render correct stepper