fission-ai__openspec/openspec/changes/archive/2025-08-19-bulk-validation-interactive-selection/tasks.md

Implementation Tasks

1. Change Command: Interactive Validation Selection

• 1.1 Add --no-interactive flag to change validate in src/cli/index.ts
• 1.2 Implement interactivity gate respecting TTY and OPEN_SPEC_INTERACTIVE=0 in src/commands/change.ts
• 1.3 When no [change-name] is provided and interactivity is allowed, prompt with a list of active changes (exclude archive/) and validate the selected one
• 1.4 Preserve current non-interactive fallback: print available change IDs and hint, set process.exitCode = 1
• 1.5 Tests: add coverage for interactive and non-interactive flows
  • Added test/commands/change.interactive-validate.test.ts

2. Spec Command: Interactive Validation Selection

• 2.1 Make spec validate accept optional [spec-id] in src/commands/spec.ts registration
• 2.2 Add --no-interactive flag to spec validate
• 2.3 Implement interactivity gate respecting TTY and OPEN_SPEC_INTERACTIVE=0
• 2.4 When no [spec-id] provided and interactivity allowed, prompt to select from openspec/specs/*/spec.md and validate the selected spec
• 2.5 Preserve current non-interactive fallback when no spec-id and no interactivity: print existing error and exit code non-zero
• 2.6 Tests: add coverage for interactive and non-interactive flows
  • Added test/commands/spec.interactive-validate.test.ts

3. New Top-level validate Command

• 3.1 Add validate command in src/cli/index.ts
  • Options: --all, --changes, --specs, --type <change|spec>, --strict, --json, --no-interactive
  • Usage: openspec validate [item-name]
• 3.2 Create src/commands/validate.ts implementing:
  • 3.2.1 Interactive selector when no args (choices: All, Changes, Specs, Specific item)
  • 3.2.2 Non-interactive fallback with helpful hint and exit code 1
  • 3.2.3 Direct item validation with automatic type detection
  • 3.2.4 Ambiguity error when name exists as both change and spec; suggest --type or subcommands
  • 3.2.5 Unknown item handling with nearest-match suggestions
  • 3.2.6 Bulk validation for --all, --changes, --specs (exclude openspec/changes/archive/)
  • 3.2.7 Respect --strict and --json options; JSON shape per spec
  • 3.2.8 Exit with code 1 if any validation fails
  • 3.2.9 Bounded concurrency (default 4–8) for bulk validation
  • 3.2.10 Progress indication during bulk runs (current item, running counts)

4. Utilities and Shared Helpers

• 4.1 Add src/utils/interactive.ts with isInteractive(stdin: NodeJS.ReadStream, noInteractiveFlag?: boolean): boolean
  • Considers: process.stdin.isTTY, --no-interactive, OPEN_SPEC_INTERACTIVE=0
• 4.2 Add src/utils/item-discovery.ts with:
  • getActiveChangeIds(root = process.cwd()): Promise<string[]> (exclude archive/)
  • getSpecIds(root = process.cwd()): Promise<string[]> (folders with spec.md)
• 4.3 Optional: src/utils/concurrency.ts helper for bounded parallelism
• 4.4 Reuse src/core/validation/validator.ts for item validation

5. JSON Output (Bulk Validation)

• 5.1 Implement JSON schema:
  • items: Array<{ id: string, type: "change"|"spec", valid: boolean, issues: Issue[], durationMs: number }>
  • summary: { totals: { items: number, passed: number, failed: number }, byType: { change?: { items: number, passed: number, failed: number }, spec?: { items: number, passed: number, failed: number } } }
  • version: "1.0"
• 5.2 Ensure process exit code is 1 if any items[].valid === false
• 5.3 Tests for JSON shape (keys, types, counts) and exit code behavior
  • Added test/commands/validate.test.ts

6. Progress and UX

• 6.1 Use ora or minimal console progress to show current item and running counts
• 6.2 Keep output stable in --json mode (no extra logs to stdout; use stderr for progress if needed)
• 6.3 Ensure responsiveness with concurrency limits

7. Tests

• 7.1 Add top-level validate tests: test/commands/validate.test.ts
  • Includes non-interactive hint, --all JSON, --specs with concurrency, ambiguity error
• 7.2 Add unit tests for isInteractive and item discovery helpers
• 7.3 Extend existing change/spec command tests to cover interactive validate
  • Added test/commands/change.interactive-validate.test.ts, test/commands/spec.interactive-validate.test.ts

8. CLI Help and Docs

• 8.1 Update command descriptions/options in src/cli/index.ts
• 8.2 Verify help output includes validate command and flags
• 8.3 Ensure existing specs under openspec/changes/bulk-validation-interactive-selection/specs/* remain satisfied

9. Non-functional

• 9.1 Code style and types: explicit types for exported APIs; avoid any
• 9.2 No linter errors; stable formatting; avoid unrelated refactors
• 9.3 Maintain existing behavior for unaffected commands

10. Acceptance Criteria Mapping

• AC-1: openspec change validate interactive selection when no arg (TTY only; respects --no-interactive/env) — matches cli-change spec
• AC-2: openspec spec validate interactive selection when no arg (TTY only; respects --no-interactive/env) — matches cli-spec spec
• AC-3: New openspec validate supports interactive selection, bulk/filtered validation, JSON schema, progress, concurrency, exit codes — matches cli-validate spec