fix(validate): support workspace planning homes and nested delta specs

[XiaojuCH]

Fixes #1182.

This PR makes top-level openspec validate work correctly for workspace-planning changes created from a workspace root.

What changed:

• make top-level validate resolve change paths through the current planning home instead of assuming repo-local openspec/changes
• add directory-based change discovery for validate flows instead of relying only on proposal.md
• make change delta-spec validation recurse through nested workspace-planning paths like specs/<area>/<capability>/spec.md
• add a workspace-planning regression test covering validate <change> and validate --changes from the workspace root

Why:

• status / instructions / new change already resolve workspace planning homes correctly
• validate was the odd one out and returned Unknown item '<change>' from the same workspace root
• workspace-planning uses nested spec paths, so top-level validate also needed recursive delta-spec discovery to actually validate those artifacts

Validation:

• node build.js
• node node_modules/vitest/vitest.mjs run test/commands/validate.test.ts
• node node_modules/vitest/vitest.mjs run test/commands/artifact-workflow.test.ts --testNamePattern "nested workspace-planning specs"

Summary by CodeRabbit

• New Features

  • Enhanced validation to recursively discover specifications in nested directories.
  • Improved support for workspace planning structures with better filesystem path resolution.

• Bug Fixes

  • Fixed change discovery to properly handle nested change structures within workspaces.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ab225c2e-2e5e-4fdd-8e1c-f4bc57bdbe0c

📥 Commits

Reviewing files that changed from the base of the PR and between 1b06fdd and 7777c99.

📒 Files selected for processing (4)

• src/commands/validate.ts
• src/core/validation/validator.ts
• src/utils/item-discovery.ts
• test/commands/validate.test.ts

---

📝 Walkthrough

Walkthrough

The validate command now resolves changes and specs via planning-home scoping, supporting both repo and workspace planning homes. Item discovery is refactored to extract planning-home–scoped helpers, and delta spec discovery becomes recursive to support nested spec structures within multi-area schemas.

Changes

Planning-home–aware validation with nested spec support

Layer / File(s)	Summary
Planning-home–scoped item discovery helpers src/utils/item-discovery.ts	New getChangeDirectoryIds enumerates change directories filtering dot-prefixed and archive entries. getActiveChangeIds is refactored to reuse this helper and filter by proposal.md readability.
Recursive delta spec discovery src/core/validation/validator.ts	New findDeltaSpecFiles recursively walks specs directory to collect all spec.md files sorted. validateChangeDeltaSpecs calls this helper and derives entryPath from relative paths normalized to POSIX form.
Planning-home resolution in validate command src/commands/validate.ts	Command imports are updated to include resolveCurrentPlanningHomeSync and getChangeDir. Interactive selection, direct validation, and bulk validation all resolve planningHome once and use planning-home–relative paths via getChangeDir() and planningHome.root instead of process.cwd().
Integration test for workspace planning-home validation test/commands/validate.test.ts	New test sets up a workspace, creates a nested change, writes a delta spec, and validates that the change is resolved and reported as valid for both single-change and bulk validation modes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Suggested reviewers

• alfred-openspec

Poem

🐰 A workspace now validates with grace,
Planning homes guide us to the right place,
Nested specs recursively explored,
Changes discovered, their paths adored,
Validation's reach extends so far,
No matter where the changes are! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: fixing validate command to support workspace planning homes and nested delta specs, matching the core functionality in the PR.
Linked Issues check	✅ Passed	Changes directly address all issue #1182 requirements: validate now resolves workspace planning homes like other commands, discovers changes directory-based, and validates nested delta specs with recursive scanning.
Out of Scope Changes check	✅ Passed	All changes are scoped to validate command and supporting utilities; no unrelated modifications found across modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[alfred-openspec]

Reviewed the diff and focused validation paths. The fix shape looks right: top-level validate now resolves through the current planning home, nested delta specs are discovered recursively, and directory-based change discovery is consistent with the workspace-planning direction.

Focused gates passed locally: pnpm install --frozen-lockfile, then pnpm exec vitest run test/commands/validate.test.ts test/core/validation.test.ts.