orchestr8 2.5.0 → 2.6.1

package/.blueprint/features/feature_pipeline-insights/story-bottleneck-analysis.md

@@ -0,0 +1,75 @@
+# Story — Bottleneck Analysis
+
+## User story
+
+As a developer, I want to identify which pipeline stage consistently takes the longest so that I can focus optimization efforts where they will have the greatest impact.
+
+---
+
+## Context / scope
+
+- User has executed multiple pipeline runs via `/implement-feature`
+- History data exists in `.claude/pipeline-history.json`
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` or `orchestr8 insights --bottlenecks`
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Bottleneck Detection):
+- Bottleneck threshold: >35% of total pipeline time
+- Recommendation threshold: >40% of total pipeline time
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display bottleneck stage**
+- Given the history file contains at least 3 successful pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes a "Bottlenecks" section identifying the stage with the highest average duration.
+
+**AC-2 — Show percentage of total time**
+- Given a bottleneck stage is identified,
+- When the analysis completes,
+- Then the output displays the stage name, average duration in milliseconds, and percentage of total pipeline time.
+
+**AC-3 — Bottleneck threshold reporting**
+- Given a stage accounts for more than 35% of total pipeline time,
+- When the analysis completes,
+- Then that stage is flagged as a bottleneck in the output.
+
+**AC-4 — Generate recommendation for severe bottleneck**
+- Given a stage accounts for more than 40% of total pipeline time,
+- When the analysis completes,
+- Then the output includes the recommendation: "Consider simplifying {stage} requirements or splitting features".
+
+**AC-5 — Filter to bottlenecks only**
+- Given the user runs `orchestr8 insights --bottlenecks`,
+- When the analysis completes,
+- Then only the bottleneck analysis section is displayed (other analysis types are omitted).
+
+**AC-6 — Insufficient data handling**
+- Given the history file contains fewer than 3 runs,
+- When the user runs `orchestr8 insights`,
+- Then the output displays: "Insufficient data for insights. Complete at least 3 pipeline runs."
+
+**AC-7 — Missing history file handling**
+- Given no history file exists at `.claude/pipeline-history.json`,
+- When the user runs `orchestr8 insights`,
+- Then the output displays: "No history found. Run some pipelines first."
+
+---
+
+## Out of scope
+
+- Modifying the history file or pipeline configuration
+- Customizing the 35%/40% threshold values
+- Providing automated remediation
+- Stage-specific threshold configuration
+- Analysis of partial/in-progress runs
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-failure-patterns.md

@@ -0,0 +1,75 @@
+# Story — Failure Pattern Analysis
+
+## User story
+
+As a developer, I want to analyze which pipeline stages fail most frequently so that I can identify systemic issues and improve pipeline reliability.
+
+---
+
+## Context / scope
+
+- User has executed multiple pipeline runs, some of which have failed
+- History data includes entries with `status: "failed"` and associated stage information
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` or `orchestr8 insights --failures`
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Failure Pattern Analysis):
+- Failure rate threshold: >15% is reported as concerning
+- Recommendation threshold: >20% triggers specific recommendation
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display failure rates per stage**
+- Given the history file contains at least 3 pipeline runs with at least one failure,
+- When the user runs `orchestr8 insights`,
+- Then the output includes a "Failure Patterns" section showing failure rate for each stage that has experienced failures.
+
+**AC-2 — Identify most common failure stage**
+- Given failures exist in the history,
+- When the analysis completes,
+- Then the output identifies the stage with the highest failure count as the "most common failure stage".
+
+**AC-3 — Flag concerning failure rates**
+- Given a stage has a failure rate greater than 15%,
+- When the analysis completes,
+- Then that stage is flagged as having a concerning failure rate.
+
+**AC-4 — Generate recommendation for high failure rate**
+- Given a stage has a failure rate greater than 20%,
+- When the analysis completes,
+- Then the output includes the recommendation: "Review {stage} agent configuration or specification clarity".
+
+**AC-5 — Identify features with repeated failures**
+- Given the same feature slug has failed multiple times,
+- When the analysis completes,
+- Then those features are listed as correlation hints (e.g., "Feature 'complex-auth' has failed 3 times").
+
+**AC-6 — Filter to failures only**
+- Given the user runs `orchestr8 insights --failures`,
+- When the analysis completes,
+- Then only the failure pattern analysis section is displayed (other analysis types are omitted).
+
+**AC-7 — No failures recorded**
+- Given all pipeline runs in history have status "completed" (no failures),
+- When the user runs `orchestr8 insights`,
+- Then the failure analysis section displays: "No failures recorded" and is omitted from recommendations.
+
+---
+
+## Out of scope
+
+- Automatic correlation with feature complexity metrics
+- Root cause analysis beyond stage identification
+- Failure notification or alerting
+- Retry or remediation automation
+- Classification of failure types (timeout vs error vs abort)
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-json-output.md

@@ -0,0 +1,75 @@
+# Story — JSON Output
+
+## User story
+
+As a developer, I want to export pipeline insights as structured JSON so that I can integrate the analysis with other tools or process the data programmatically.
+
+---
+
+## Context / scope
+
+- User wants machine-readable output instead of human-readable text
+- JSON output contains all the same analysis data as text output
+- Enables integration with CI/CD pipelines, dashboards, or custom tooling
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights --json`
+
+Per FEATURE_SPEC.md:Section 4 (Key alternatives or branches):
+- `--json` flag produces structured JSON instead of formatted text
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Output JSON when flag provided**
+- Given the history file contains valid pipeline data,
+- When the user runs `orchestr8 insights --json`,
+- Then the output is valid JSON (parseable by `JSON.parse()`).
+
+**AC-2 — Include bottleneck data in JSON**
+- Given bottleneck analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `bottlenecks` object with: `stage`, `averageDurationMs`, `percentageOfTotal`, `isBottleneck`, `recommendation` (if applicable).
+
+**AC-3 — Include failure data in JSON**
+- Given failure analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `failures` object with: `failuresByStage` (array), `mostCommonFailureStage`, `featuresWithRepeatedFailures` (array), `recommendation` (if applicable).
+
+**AC-4 — Include anomaly data in JSON**
+- Given anomaly detection completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes an `anomalies` object with: `detected` (array of anomalous runs), `recommendation` (if applicable).
+
+**AC-5 — Include trend data in JSON**
+- Given trend analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `trends` object with: `successRate` (trend + percentage), `duration` (trend + percentage), `recommendation` (if applicable).
+
+**AC-6 — Combine JSON with filter flags**
+- Given the user runs `orchestr8 insights --json --bottlenecks`,
+- When the analysis completes,
+- Then the JSON output includes only the `bottlenecks` section (other analysis types are omitted).
+
+**AC-7 — Handle insufficient data in JSON**
+- Given there is insufficient data for analysis,
+- When `--json` flag is provided,
+- Then the JSON output includes an `error` field with the appropriate message (e.g., `{"error": "Insufficient data for insights. Complete at least 3 pipeline runs."}`).
+
+---
+
+## Out of scope
+
+- Exporting JSON to a file (output to stdout only)
+- JSON schema validation or versioning
+- Compressed or minified JSON output options
+- Integration with specific external platforms
+- Historical JSON output comparison
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-trend-analysis.md

@@ -0,0 +1,78 @@
+# Story — Trend Analysis
+
+## User story
+
+As a developer, I want to track whether pipeline performance is improving or degrading over time so that I can understand the impact of changes and maintain development efficiency.
+
+---
+
+## Context / scope
+
+- User has accumulated sufficient history to compare earlier vs later runs
+- Analysis compares first half vs second half of history data
+- Requires minimum 6 runs to compute meaningful trends
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` (trends section included by default)
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Trend Analysis):
+- Improving: >10% better in second half
+- Degrading: >10% worse in second half
+- Stable: within 10% variance
+- Minimum data: 6 runs required
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display success rate trend**
+- Given the history file contains at least 6 pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes a "Trends" section showing success rate trend as "improving", "stable", or "degrading".
+
+**AC-2 — Display duration trend**
+- Given the history file contains at least 6 pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes average duration trend as "improving" (faster), "stable", or "degrading" (slower).
+
+**AC-3 — Calculate trend by comparing halves**
+- Given the history contains N runs (where N >= 6),
+- When trend analysis is performed,
+- Then the first N/2 runs are compared against the last N/2 runs to determine trend direction.
+
+**AC-4 — Apply threshold for trend classification**
+- Given the percentage change between halves is calculated,
+- When classifying the trend,
+- Then >10% improvement shows "improving", >10% degradation shows "degrading", and within 10% shows "stable".
+
+**AC-5 — Generate recommendation for degrading trend**
+- Given either success rate or duration trend is "degrading",
+- When the analysis completes,
+- Then the output includes the recommendation: "Review recent changes to agent specifications or system spec".
+
+**AC-6 — Insufficient data for trends**
+- Given the history file contains fewer than 6 runs,
+- When trend analysis is attempted,
+- Then it is skipped with explanation: "Insufficient data for trend analysis. Need at least 6 runs."
+
+**AC-7 — Show percentage change**
+- Given trend analysis completes successfully,
+- When the output is displayed,
+- Then the percentage change for both success rate and duration is shown alongside the trend indicator.
+
+---
+
+## Out of scope
+
+- Sliding window trend analysis (uses fixed first-half/second-half)
+- Time-based trend analysis (e.g., last 30 days)
+- Per-stage trend analysis
+- Trend visualization or charting
+- Predictive modelling of future performance
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_validate-command/FEATURE_SPEC.md

@@ -0,0 +1,209 @@
+# Feature Specification — Validate Command
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+The `orchestr8 validate` command provides pre-flight checks to ensure the environment is correctly configured before running the `/implement-feature` pipeline. This addresses a common failure mode where users invoke the pipeline without required artifacts in place, leading to mid-pipeline failures that are harder to diagnose and recover from.
+
+**Problem being addressed:**
+- Pipeline failures mid-execution due to missing system spec, agent files, or skills
+- Poor developer experience when prerequisites are unclear
+- No visibility into "readiness" state before committing to a full pipeline run
+
+**User need:**
+- Developers need confidence that their project is correctly set up before invoking the pipeline
+- Teams need actionable guidance when setup is incomplete
+
+**How this supports the system purpose:**
+- Aligns with the system's goal of reducing ambiguity and drift by enforcing explicit prerequisites
+- Supports the "System spec gate" rule defined in the system specification (Section 7)
+- Reduces failed pipeline runs by catching issues early
+
+---
+
+## 2. Scope
+
+### In Scope
+- New CLI command `orchestr8 validate` accessible via `bin/cli.js`
+- Check: System spec exists at `.blueprint/system_specification/SYSTEM_SPEC.md`
+- Check: Required directories exist (`.blueprint/`, `.business_context/`, `.claude/commands/`)
+- Check: Agent spec files exist in `.blueprint/agents/` (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md)
+- Check: Business context directory has at least one file (not empty)
+- Check: Skills installed (`.claude/commands/implement-feature.md` exists)
+- Check: Node.js version meets requirements (>=18)
+- Success output: Print success message with checkmarks for each passed check
+- Failure output: Print what is missing with actionable fix suggestions for each failed check
+- Exit code: 0 on all checks pass, non-zero on any failure
+
+### Out of Scope
+- Validation of file contents (e.g., SYSTEM_SPEC.md is well-formed)
+- Validation of business context quality or completeness
+- Automatic remediation (the command reports issues, not fixes them)
+- Network checks (e.g., can reach skills.sh)
+- Validation of queue state or in-progress features
+
+---
+
+## 3. Actors Involved
+
+### Human User (Developer)
+- **Can do:** Invoke `orchestr8 validate` to check project readiness
+- **Can do:** Review validation output to understand what is missing
+- **Cannot do:** Auto-fix issues via this command (must run `init` or manually create files)
+
+---
+
+## 4. Behaviour Overview
+
+**Happy-path behaviour:**
+1. User runs `orchestr8 validate` in a project directory
+2. Command performs all checks in sequence
+3. Each check prints a status line (checkmark for pass, X for fail)
+4. If all checks pass, prints overall success message and exits with code 0
+
+**Failure behaviour:**
+1. User runs `orchestr8 validate` in an incomplete project
+2. Command performs all checks in sequence
+3. Failed checks print X with a description of what is missing
+4. After all checks, failed items include actionable fix suggestions (e.g., "Run `orchestr8 init` to create .blueprint directory")
+5. Command exits with non-zero exit code
+
+**User-visible outcomes:**
+- Clear, scannable output showing pass/fail status for each prerequisite
+- Actionable guidance for resolving failures
+- Machine-parseable exit code for scripting/CI integration
+
+---
+
+## 5. State & Lifecycle Interactions
+
+This feature is **state-inspecting only**. It does not create, transition, or modify any system state.
+
+- **States inspected:** File system state (existence of files/directories), Node.js runtime version
+- **States entered:** None
+- **States exited:** None
+- **States modified:** None
+
+The command is idempotent and safe to run repeatedly without side effects.
+
+---
+
+## 6. Rules & Decision Logic
+
+### R1: Directory Existence Check
+- **Description:** Verify required directories exist
+- **Inputs:** Directory paths (`.blueprint/`, `.business_context/`, `.claude/commands/`)
+- **Outputs:** Pass/fail for each directory
+- **Deterministic:** Yes
+
+### R2: System Spec Existence Check
+- **Description:** Verify SYSTEM_SPEC.md exists at expected path
+- **Inputs:** Path `.blueprint/system_specification/SYSTEM_SPEC.md`
+- **Outputs:** Pass/fail
+- **Deterministic:** Yes
+
+### R3: Agent Specs Existence Check
+- **Description:** Verify all four agent specification files exist
+- **Inputs:** Paths in `.blueprint/agents/` (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md)
+- **Outputs:** Pass/fail, listing any missing files
+- **Deterministic:** Yes
+
+### R4: Business Context Non-Empty Check
+- **Description:** Verify `.business_context/` contains at least one file
+- **Inputs:** Directory listing of `.business_context/`
+- **Outputs:** Pass/fail
+- **Deterministic:** Yes
+
+### R5: Skills Installed Check
+- **Description:** Verify implement-feature skill is installed
+- **Inputs:** Path `.claude/commands/implement-feature.md`
+- **Outputs:** Pass/fail
+- **Deterministic:** Yes
+
+### R6: Node.js Version Check
+- **Description:** Verify Node.js version is 18 or higher
+- **Inputs:** `process.version`
+- **Outputs:** Pass/fail with current version
+- **Deterministic:** Yes
+
+### R7: Exit Code Logic
+- **Description:** Return exit code based on overall result
+- **Inputs:** All check results
+- **Outputs:** Exit code 0 if all pass, exit code 1 if any fail
+- **Deterministic:** Yes
+
+---
+
+## 7. Dependencies
+
+### System Components
+- `fs` module for file system checks
+- `process.version` for Node.js version check
+- CLI routing in `bin/cli.js`
+
+### Technical Dependencies
+- Node.js >= 18 (the check itself should work on lower versions to report the failure)
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance
+- All checks are local file system operations; should complete in < 100ms
+
+### Error Tolerance
+- Command should not throw exceptions; all checks should be wrapped to handle missing paths gracefully
+
+### User Experience
+- Output should be colorized if terminal supports it (green checkmarks, red X marks)
+- Output should be readable in non-color terminals (using ASCII fallback)
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+- The four agent spec files have fixed names matching current convention
+- `.business_context/` having any file (including README.md) counts as non-empty
+- The Node.js version check should report failure but not crash on old versions
+
+### Open Questions
+- Should there be a `--json` flag for machine-readable output?
+- Should there be a `--fix` flag that runs `init` if missing? (Deferred - out of scope)
+
+---
+
+## 10. Impact on System Specification
+
+This feature **reinforces** existing system assumptions:
+- Validates the prerequisites implied by "System spec gate" rule in Section 7
+- Aligns with system boundary definition (CLI tooling in scope)
+- Consistent with existing command patterns (`init`, `update`, `queue`)
+
+No contradictions or tensions with the current system specification.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+1. **Core validation flow** - User runs validate and sees results
+2. **Success path** - All checks pass, user sees green checkmarks
+3. **Failure path with guidance** - Checks fail, user sees actionable fixes
+4. **Node.js version edge case** - Running on unsupported Node version
+
+### Expected Story Boundaries
+- Each check type could be a separate acceptance criterion within a single story
+- Success/failure output formatting is a story concern
+- Exit codes are a story concern (affects CI integration)
+
+### Areas Needing Careful Story Framing
+- The distinction between "check failed" and "command error" (the command itself should not fail/throw, even if checks fail)
+- How to phrase fix suggestions to be helpful without being prescriptive
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-02-24 | Initial feature specification | New feature request for pre-flight validation | Alex |

package/.blueprint/features/feature_validate-command/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,59 @@
+# Implementation Plan — Validate Command
+
+## Summary
+
+Implement a new `orchestr8 validate` CLI command that performs pre-flight checks for directory existence, file presence, and Node.js version. The command outputs pass/fail status for each check with colorized indicators, provides actionable fix suggestions for failures, and returns appropriate exit codes (0 for success, 1 for failure).
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/validate.js` | Create | Core validation logic with `validate()`, `formatOutput()`, and `checkNodeVersion()` exports |
+| `src/index.js` | Modify | Export validate module for library consumers |
+| `bin/cli.js` | Modify | Add `validate` command routing |
+
+---
+
+## Implementation Steps
+
+1. **Create `src/validate.js` with check functions**
+   - Implement `checkDirectories()` for `.blueprint/`, `.business_context/`, `.claude/commands/`
+   - Implement `checkSystemSpec()` for `.blueprint/system_specification/SYSTEM_SPEC.md`
+   - Implement `checkAgentSpecs()` for the four agent files in `.blueprint/agents/`
+   - Implement `checkBusinessContext()` to verify directory is non-empty
+   - Implement `checkSkillsInstalled()` for `.claude/commands/implement-feature.md`
+   - Implement `checkNodeVersion()` exported separately for tests, parsing `process.version`
+
+2. **Implement main `validate()` function**
+   - Run all checks sequentially, collecting results in an array
+   - Each check returns `{ name, passed, message, fix?, detectedVersion? }`
+   - Compute `success` (all passed) and `exitCode` (0 or 1)
+   - Return `{ success, exitCode, checks }`
+
+3. **Implement `formatOutput()` function**
+   - Accept result object and color flag (detect via `process.stdout.isTTY`)
+   - Use `✓`/`✗` for color terminals, `[PASS]`/`[FAIL]` for ASCII fallback
+   - Apply green/red ANSI codes when color is enabled
+   - Include fix suggestions after failed checks
+   - Print overall success/failure summary at end
+
+4. **Add CLI routing in `bin/cli.js`**
+   - Import `validate` and `formatOutput` from `src/validate.js`
+   - Add `validate` command that runs validation, prints output, and calls `process.exit(result.exitCode)`
+
+5. **Export from `src/index.js`**
+   - Add `validate` to module exports for programmatic usage
+
+6. **Run tests and iterate**
+   - Execute `node --test test/feature_validate-command.test.js`
+   - Fix any failing assertions
+
+---
+
+## Risks/Questions
+
+- **Color detection**: Tests mock TTY state; implementation should use `process.stdout.isTTY` or accept a parameter for testability
+- **Agent file names**: Tests expect exact names (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md) - verify these match production
+- **Node version parsing**: Use `parseInt(process.version.slice(1).split('.')[0], 10)` to extract major version safely

package/.blueprint/features/feature_validate-command/story-failure-output.md

@@ -0,0 +1,61 @@
+# Story — Validation Failure Output
+
+## User story
+As a developer, I want to see what is missing and how to fix it when validation checks fail so that I can resolve issues and get my project ready for the pipeline.
+
+---
+
+## Context / scope
+- Developer using orchestr8 CLI
+- Project is missing one or more required artifacts
+- This story covers failure output and actionable guidance
+
+See feature spec: `.blueprint/features/feature_validate-command/FEATURE_SPEC.md`
+
+---
+
+## Acceptance criteria
+
+**AC-1 — X mark displayed for failed checks**
+- Given one or more required files/directories are missing,
+- When I run `orchestr8 validate`,
+- Then each failed check displays an X indicator.
+
+**AC-2 — Colorized failure output when supported**
+- Given my terminal supports color output,
+- When I run `orchestr8 validate` and checks fail,
+- Then X marks are displayed in red.
+
+**AC-3 — Description of what is missing**
+- Given a check fails,
+- When the status line is printed,
+- Then it includes a description of what is missing (e.g., "Missing: .blueprint/system_specification/SYSTEM_SPEC.md").
+
+**AC-4 — Actionable fix suggestions**
+- Given one or more checks fail,
+- When all checks have completed,
+- Then actionable fix suggestions are displayed:
+  - Missing `.blueprint/` directory: "Run `orchestr8 init` to initialize project"
+  - Missing agent specs: "Run `orchestr8 init` to create agent specification files"
+  - Missing skills: "Run `orchestr8 init` to install required skills"
+  - Empty business context: "Add at least one file to `.business_context/` directory"
+  - Node.js version: "Upgrade Node.js to version 18 or higher"
+
+**AC-5 — Exit code non-zero on failure**
+- Given one or more validation checks fail,
+- When the command completes,
+- Then the process exits with a non-zero exit code (1)
+- And this exit code can be used in scripts/CI pipelines to detect failures.
+
+**AC-6 — All checks still run on failure**
+- Given the first check fails,
+- When I run `orchestr8 validate`,
+- Then all remaining checks are still executed
+- And a complete picture of missing items is shown.
+
+---
+
+## Out of scope
+- `--fix` flag to automatically remediate issues
+- Prioritization of which issues to fix first
+- JSON output format (deferred)

package/.blueprint/features/feature_validate-command/story-node-version-check.md

@@ -0,0 +1,52 @@
+# Story — Node.js Version Check
+
+## User story
+As a developer, I want the validation to check my Node.js version so that I am warned before attempting to run the pipeline on an unsupported runtime.
+
+---
+
+## Context / scope
+- Developer using orchestr8 CLI
+- Node.js version may or may not meet minimum requirement (>=18)
+- This check should work even on older Node.js versions to report the issue
+
+See feature spec: `.blueprint/features/feature_validate-command/FEATURE_SPEC.md`
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Version check passes on Node 18+**
+- Given I am running Node.js version 18 or higher,
+- When I run `orchestr8 validate`,
+- Then the Node.js version check displays a pass indicator.
+
+**AC-2 — Version check fails on Node < 18**
+- Given I am running Node.js version lower than 18,
+- When I run `orchestr8 validate`,
+- Then the Node.js version check displays a fail indicator
+- And the current version is shown in the output.
+
+**AC-3 — Command does not crash on old Node**
+- Given I am running an older Node.js version,
+- When I run `orchestr8 validate`,
+- Then the command executes and reports the version failure
+- And the command does not throw a runtime exception.
+
+**AC-4 — Clear upgrade guidance**
+- Given the Node.js version check fails,
+- When fix suggestions are displayed,
+- Then guidance includes "Upgrade Node.js to version 18 or higher"
+- And the current detected version is shown.
+
+**AC-5 — Version detected from runtime**
+- Given I run `orchestr8 validate`,
+- When the Node.js version check executes,
+- Then the version is detected from `process.version` (not from package.json or external sources).
+
+---
+
+## Out of scope
+- Checking for specific minor/patch versions
+- Checking for Node.js feature availability beyond version number
+- nvm or version manager integration