fix(cli): reject missing roots for list and validate

[clay-good]

Status

LGTM. Ready for human review.

What was wrong

From a directory with no OpenSpec root, openspec validate --all and openspec list --json resolved the current directory as an implicit root. They exited 0 and reported empty results, creating a silent false-pass for CI and agents.

How it was fixed

• Require an existing root for bulk validation (--all, --changes, and --specs).
• Require an existing root for list while preserving the established fallback for legacy projects with openspec/project.md.
• Keep direct validation and other intentional implicit-root workflows unchanged.
• Document the command-specific root policy.

Replication / proof

The regression tests first failed with exit code 0, then passed after the fix. Verified locally:

• pnpm build
• pnpm lint
• vitest run test/commands/store-root-selection.test.ts (40/40)
• vitest run test/commands/validate.test.ts (12/12)
• vitest run test/cli-e2e/view-store-resolution.test.ts (5/5)
• vitest run test/core/root-selection.test.ts (31/31)
• Manual human and JSON repros now exit 1 with no_openspec_root; direct validate missing still reports unknown_item.

The full GitHub regression gate passes on Linux, macOS, and Windows, along with lint/type-check, release tracking, dependency review, security audit, CodeQL, and deployment checks.

Notes / nits

• Review-requested legacy-root and path-canonicalization coverage is included.
• An open-issue audit found no additional duplicate or related open issue fixed by this PR, so only the genuine reported defect is linked.

Closes #1611

[coderabbitai]

📝 Walkthrough

Walkthrough

The change restricts implicit root resolution for bulk validation and listing without a root. Listing still uses the fallback for legacy OpenSpec projects. Tests cover human-readable errors, JSON diagnostics, empty roots, and direct validation.

Changes

Root resolution behavior

Layer / File(s)	Summary
Root resolution policy and listing integration src/core/root-selection.ts, src/cli/index.ts, docs/agent-contract.md	The resolver documents explicit root requirements. list uses an implicit root only when openspec/project.md exists.
Bulk validation behavior and regression coverage src/commands/validate.ts, test/commands/store-root-selection.test.ts	Bulk validation rejects missing roots and emits structured diagnostics in JSON mode. Tests cover missing roots, empty existing roots, legacy listing, and direct validation of unknown items.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1363: Both changes modify root-selection fallback behavior.
• Fission-AI/OpenSpec#1473: Both changes modify root selection and validation/list handling.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address issue #1611 by rejecting missing roots for bulk validation and list while preserving valid legacy and direct-validation behavior.
Out of Scope Changes check	✅ Passed	The documentation, implementation changes, and regression tests directly support the linked issue and stated pull request objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: rejecting missing roots for the list and validate commands.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-1611-root-validation

---

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.}

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	b15f1b5
Status:	✅  Deploy successful!
Preview URL:	https://883e5778.openspec-docs.pages.dev
Branch Preview URL:	https://codex-fix-1611-root-validati.openspec-docs.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

test/commands/store-root-selection.test.ts (1)

564-587: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Verify the legacy list compatibility path.

The added tests cover a missing root and a modern nearest root. They do not exercise list when the only marker is openspec/project.md. Confirm that an existing test asserts success and root.source equal to implicit for this layout. If no test covers it, add that regression.

Also applies to: 589-621

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/commands/store-root-selection.test.ts` around lines 564 - 587, Inspect
the existing store-root selection tests for the legacy list layout where only
openspec/project.md exists. Ensure a regression test runs list from that
repository, expects success, and verifies the resolved root source is implicit;
add the test if this behavior is not already covered, reusing the established
root-selection assertion helpers.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/commands/store-root-selection.test.ts`:
- Line 640: Update the assertion for json.root in the store-root selection test
to canonicalize json.root.path with the same realpath resolution used to create
appRepo before comparing paths. Preserve the expected source value of "nearest"
and keep the comparison path-safe for symlinked or resolved directories.

---

Nitpick comments:
In `@test/commands/store-root-selection.test.ts`:
- Around line 564-587: Inspect the existing store-root selection tests for the
legacy list layout where only openspec/project.md exists. Ensure a regression
test runs list from that repository, expects success, and verifies the resolved
root source is implicit; add the test if this behavior is not already covered,
reusing the established root-selection assertion helpers.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 82306e2b-2f86-4bd9-bddb-225c6844b8a1

📥 Commits

Reviewing files that changed from the base of the PR and between e50bd09 and b15f1b5.

📒 Files selected for processing (5)

• docs/agent-contract.md
• src/cli/index.ts
• src/commands/validate.ts
• src/core/root-selection.ts
• test/commands/store-root-selection.test.ts