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.

[clay-good]

Closing as already fixed on main — thank you for this; both halves of the fix shipped, and your framing that "validate was the odd one out" was the correct read.

#1182 (openspec validate cannot resolve changes in a workspace planning home) is closed as completed. Both parts of this PR are on main:

1. validate resolves through the planning home instead of process.cwd()/openspec/changes — #1280 (a325305, fix(resolution): converge validate, view, and archive onto canonical resolution (#1182, #1202, #1156), merged 2026-07-03).

src/commands/validate.ts on main now imports:

import { resolveRootForCommand, toRootOutput, withStoreFlag, ... } from '../core/root-selection.js';
import { getAvailableChanges } from './workflow/shared.js';

The hardcoded path.join(process.cwd(), 'openspec', 'changes', id) this PR removed is gone, and change discovery is directory-based via the shared helper rather than proposal.md-gated — the second behavior this PR asked for.

2. Nested delta specs (specs/<area>/<capability>/spec.md) — #1355 (3fdd2f2, fix(specs): discover nested spec paths recursively across parse, apply, and archive, merged 2026-07-17), then hardened by #1392 (a13abea). validateChangeDeltaSpecs on main:

// Discover delta specs through the same helper the change parser, show,
// apply, and archive use, so validate never accepts a layout the merge
// path silently skips (#1385). It finds spec.md at any depth, covering
// both specs/<capability>/spec.md and the nested multi-area
// specs/<area>/<capability>/spec.md layout (#1182b).
const specFiles = (await discoverSpecFiles(specsDir)).map(spec => spec.specFile);

Note the #1182b citation in that comment — it is tracking precisely the nested-layout half of your issue.

On the approval: this PR carries an alfred-openspec approval from 2026-06-10, i.e. the automation reviewer, not a human sign-off. I'm noting that so the close doesn't read as overriding a maintainer decision.

Terminology note: the workspace planning-home vocabulary was retired in favor of stores (see openspec store / openspec workset in src/cli/index.ts, and test/vocabulary-sweep.test.ts, which now fails CI on reintroduced workspace_/initiative_ tokens). A rebase of this branch would hit that sweep. That's context, not the reason for closing — the reason is that the behavior shipped.

Reopen if validate still misresolves in any planning-home layout on current main.