feat: add --short flag to spec validate for condensed output

[mickume]

Summary

Add a --short flag to the spec validate command that produces a condensed version of the validation output.

Short output

When --short is passed, the output should keep the same overall structure as normal output but only show:

• valid: true / false
• Number of errors
• Number of warnings

No details on individual errors or warnings.

Normal output update

For consistency, also add the number of errors and number of warnings summary to the normal (non-short) validation output. The normal output continues to include full error/warning details as before.

[mickume]

Make sure to update the CLI documentation.

[mickume]

Starting fix session on branch fix/1-feat-add-short-flag-to-spec-validate-for-condensed-output... (run: 20260811_065307_4007e9)

[mickume]

Triage Report

Summary: The spec validate command has no --short flag and its JSON output omits error/warning counts. The feature requires: (1) a new --short Click option on validate_cmd in packages/spec/spec/cli.py that emits only valid, error_count, and warning_count by constructing a condensed dict from the _validate_single_spec result instead of passing it through unchanged; (2) the normal (non-short) output must also be enriched with error_count and warning_count derived from the errors and warnings lists; and (3) docs/cli.md must document the new flag.

Affected files:

• packages/spec/spec/cli.py
• docs/cli.md

Acceptance Criteria

AC-1: spec validate --short SPEC emits a JSON object containing only the keys valid, error_count, and warning_count — no errors array, no warnings array.

• Preconditions: A valid spec directory exists on disk with all four artifacts present.
• Expected: Output is a JSON object with exactly valid (bool), error_count (int), and warning_count (int); no errors or warnings keys are present.
• Assertion: Invoke validate_cmd via Click's CliRunner with ['--short', 'SPEC']; parse stdout JSON; assert set(output.keys()) == {'valid', 'error_count', 'warning_count'} and that 'errors' and 'warnings' are absent.

AC-2: Normal spec validate SPEC output (without --short) includes error_count and warning_count in addition to the full errors and warnings arrays.

• Preconditions: A spec directory exists that produces at least one error and at least one warning.
• Expected: error_count equals len(errors), warning_count equals len(warnings), and the full errors and warnings arrays are also present in the output.
• Assertion: Invoke validate_cmd without --short; parse stdout JSON; assert output['error_count'] == len(output['errors']) and output['warning_count'] == len(output.get('warnings', [])).

AC-3: spec validate --short (multi-spec mode, no SPEC argument) emits a condensed result where each entry in specs contains only valid, error_count, and warning_count.

• Preconditions: A spec directory containing at least two spec subdirectories exists.
• Expected: Top-level output has valid (bool) and specs (dict); each per-spec value has exactly valid, error_count, warning_count and no errors/warnings arrays.
• Assertion: Invoke validate_cmd with ['--short'] and no SPEC arg; parse stdout JSON; for each value in output['specs'].values() assert set(v.keys()) == {'valid', 'error_count', 'warning_count'}.

AC-4: --short preserves the exit code contract: exit 0 when all specs valid, exit 1 when any spec invalid.

• Preconditions: One spec directory with errors (invalid) and one clean spec directory.
• Expected: Exit code is 1 when --short is used and any spec has errors; exit code is 0 when all specs pass.
• Assertion: Run validate_cmd with --short against an invalid spec; assert result.exit_code == 1. Run against a clean spec; assert result.exit_code == 0.

AC-5: docs/cli.md documents the --short flag in the validate command section, including its effect on output shape.

• Preconditions: The docs/cli.md file exists and documents spec validate.
• Expected: The validate command table in docs/cli.md contains a row for --short describing condensed output.
• Assertion: Grep docs/cli.md for --short; assert at least one match exists within the validate section.

(run: 20260811_065307_4007e9)

[mickume]

Fix Review Report

Overall verdict: PASS

Summary: All 5 acceptance criteria pass. The implementation adds _shorten_result and _add_counts helper functions, a --short Click option on validate_cmd, and correctly branches in both single-spec and multi-spec code paths. All 26 validate CLI tests pass (including 9 new tests covering --short single-spec, normal counts, --short multi-spec, and exit codes). Linting and formatting pass on all changed files. The make check failure is pre-existing (6 unrelated files with formatting issues not touched by this branch). The full test suite (908 tests) passes with no regressions. Documentation in docs/cli.md is updated with a table row and usage examples.

Per-criterion verdicts

• ✅ NS-REQ-1.1: PASS
  • Evidence: The _shorten_result function (cli.py:690-696) returns a dict with exactly valid, error_count, and warning_count — no errors or warnings keys. Tests TestShortSingleSpec::test_short_keys_valid_spec and TestShortSingleSpec::test_short_no_errors_array verify this for both valid and invalid specs (with key-set assertions and explicit absence checks). All 3 tests in TestShortSingleSpec pass.
• ✅ NS-REQ-2.1: PASS
  • Evidence: The _add_counts function (cli.py:683-687) adds error_count = len(errors) and warning_count = len(warnings) to the existing result dict, preserving the original errors and warnings arrays. Tests TestNormalOutputCounts::test_normal_has_counts_valid, test_normal_has_counts_with_errors, and test_normal_still_has_errors_array all pass, asserting error_count == len(errors) and warning_count == len(warnings) and that the errors array is present.
• ✅ NS-REQ-3.1: PASS
  • Evidence: In multi-spec mode (cli.py:755-756), when short_output is true, each per-spec entry is produced via _shorten_result, yielding only valid, error_count, warning_count. The top-level output has valid and specs keys. Test TestShortMultiSpec::test_short_multi_spec_structure creates two spec directories, invokes validate --short without a SPEC arg, and asserts each per-spec value has exactly {valid, error_count, warning_count} with no errors/warnings arrays. Test passes.
• ✅ NS-REQ-4.1: PASS
  • Evidence: Tests TestShortExitCode::test_exit_code_zero_valid (valid spec → exit 0) and TestShortExitCode::test_exit_code_one_invalid (invalid spec → exit 1) both pass. The implementation preserves the existing exit-code logic: emit_ok (exit 0) for valid, emit + ctx.exit(1) for invalid, applied after the short/normal transformation.
• ✅ NS-REQ-5.1: PASS
  • Evidence: docs/cli.md line 136 contains | \--short` | Condensed output: emit only `valid`, `error_count`, and `warning_count` — no `errors` or `warnings` arrays. In multi-spec mode each per-spec entry is similarly condensed. |` in the validate command options table. Lines 151 and 154 show usage examples for single-spec and all-specs modes.

(run: 20260811_065307_4007e9)

[mickume]

Fix complete on branch fix/1-feat-add-short-flag-to-spec-validate-for-condensed-output. Changes have been merged into main. (run: 20260811_065307_4007e9)