Skip to content

fix(schemas): honor canonical root selection - #1616

Open
Patodo wants to merge 3 commits into
Fission-AI:mainfrom
Patodo:fix/schemas-root-selection
Open

fix(schemas): honor canonical root selection#1616
Patodo wants to merge 3 commits into
Fission-AI:mainfrom
Patodo:fix/schemas-root-selection

Conversation

@Patodo

@Patodo Patodo commented Aug 9, 2026

Copy link
Copy Markdown

Summary

  • Resolve openspec schemas through the canonical OpenSpec root-selection precedence.
  • Add --store <id> and the standard hidden --store-path rejection path while preserving successful human output and the bare JSON array.
  • Return the shared machine-readable root-selection diagnostics on JSON failures.
  • Synchronize command completion metadata, shared/generated store-selection guidance, directly affected documentation, and the OpenSpec change artifacts.
  • Add real CLI fixtures for explicit stores, declared pointers, global defaults, nearest roots, rootless compatibility, failure behavior, and paths containing spaces.

Root cause

schemasCommand() always read schemas from process.cwd(), and the command did not expose --store. As a result, schema discovery ignored an explicitly selected registered store and could disagree with the canonical root chosen by the rest of the workflow.

Impact

Schema discovery now follows the same authoritative root as other root-scoped commands. Existing successful output shapes remain compatible; ambiguous registered-store environments fail closed with actionable diagnostics instead of silently reading the wrong directory.

Validation

  • pnpm run lint
  • pnpm run build
  • pnpm test — 3,867 tests passed
  • pnpm exec openspec validate fix-schemas-root-selection --strict
  • git diff --check
  • Independent read-only code review completed and findings addressed

Windows/pwsh path behavior, including the store path containing spaces, remains gated by the repository CI matrix.

AI disclosure

Generated and verified with Codex using gpt-5.6-sol at max reasoning effort.

Summary by CodeRabbit

  • New Features

    • openspec schemas now supports --store <id> and standard project/store root selection.
    • Store selection is propagated through related workflows and command completion.
    • JSON errors now return an empty schema list, null root, and diagnostics.
  • Bug Fixes

    • Schema discovery respects configured defaults, project pointers, and nearest roots instead of only the current directory.
  • Documentation

    • Updated CLI, workflow, store-selection, and command-contract guidance.
  • Tests

    • Added coverage for selection, precedence, failures, output formats, and compatibility.

@coderabbitai

coderabbitai Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 462288fa-1e68-49aa-a3a6-113c203f537b

📥 Commits

Reviewing files that changed from the base of the PR and between 253d5b1 and 9b93085.

📒 Files selected for processing (1)
  • test/commands/schemas.test.ts

📝 Walkthrough

Walkthrough

The schemas command now uses canonical root resolution, supports --store, rejects unsupported --store-path usage, preserves successful output shapes, and returns structured JSON diagnostics on resolution failures. Workflow guidance, tests, specifications, and documentation were updated.

Changes

Schema root selection

Layer / File(s) Summary
Schema resolution contract
openspec/changes/fix-schemas-root-selection/*
Defines root precedence, store options, diagnostics, output compatibility, and validation tasks.
Schemas command resolution
src/cli/index.ts, src/commands/workflow/schemas.ts, src/core/completions/command-registry.ts, test/commands/schemas.test.ts, test/core/completions/command-registry.test.ts
Routes schemas through resolveRootForCommand(), supports store selection, preserves successful output, and emits JSON failure payloads.
Store propagation in workflows
src/core/templates/workflows/*, skills/openspec-*/SKILL.md, test/core/templates/*
Adds schemas to store-scoped guidance and propagates explicit store IDs during schema discovery.
CLI and contract documentation
docs/agent-contract.md, docs/cli.md, docs/stores-beta/user-guide.md
Documents canonical root selection, --store, JSON output compatibility, and failure envelopes.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI as schemas CLI
  participant Resolver as resolveRootForCommand
  participant Lister as listSchemasWithInfo
  CLI->>Resolver: resolve root from store and project context
  Resolver-->>CLI: resolved root or diagnostics
  CLI->>Lister: list schemas from resolved root
  Lister-->>CLI: schema results
Loading

Possibly related PRs

Suggested reviewers: clay-good, tabishb, alfred-openspec

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 11.11% 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 clearly and concisely describes the main change: applying canonical root selection to the schemas command.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ 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

Comment @coderabbitai help to get the list of available commands.

@Patodo
Patodo marked this pull request as ready for review August 9, 2026 12:14
@Patodo
Patodo requested a review from a team as a code owner August 9, 2026 12:14
@Patodo
Patodo requested review from clay-good and removed request for a team August 9, 2026 12:14

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 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 `@skills/openspec-onboard/SKILL.md`:
- Line 14: Remove view from the shared store-scoped command list in the
generator source while retaining schemas, then regenerate the committed skill
artifacts. Apply the resulting change to skills/openspec-onboard/SKILL.md (line
14), skills/openspec-propose/SKILL.md (line 28),
skills/openspec-sync-specs/SKILL.md (line 16),
skills/openspec-update-change/SKILL.md (line 14), and
skills/openspec-verify-change/SKILL.md (line 14); all listed files require the
same generated update.

In `@src/commands/workflow/schemas.ts`:
- Around line 25-29: Update the resolveRootForCommand options in schemasCommand
to set allowImplicitRoot: true, enabling schema discovery without an OpenSpec
root while preserving strict handling of explicit store failures.

In `@test/commands/schemas.test.ts`:
- Around line 117-132: Strengthen the successful JSON assertions in the schemas
CLI test by validating the complete entry for store-only, including its
documented description, artifacts, and source fields and their expected values.
Keep the existing exit, stderr, inclusion, and exclusion assertions, and use the
parsed schema result from parseSchemas rather than only checking the name.
🪄 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: 6e375e19-a242-4f60-b1cf-8b329573ab96

📥 Commits

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

📒 Files selected for processing (29)
  • docs/agent-contract.md
  • docs/cli.md
  • docs/stores-beta/user-guide.md
  • openspec/changes/fix-schemas-root-selection/.openspec.yaml
  • openspec/changes/fix-schemas-root-selection/design.md
  • openspec/changes/fix-schemas-root-selection/proposal.md
  • openspec/changes/fix-schemas-root-selection/specs/schema-resolution/spec.md
  • openspec/changes/fix-schemas-root-selection/tasks.md
  • skills/openspec-apply-change/SKILL.md
  • skills/openspec-archive-change/SKILL.md
  • skills/openspec-bulk-archive-change/SKILL.md
  • skills/openspec-continue-change/SKILL.md
  • skills/openspec-explore/SKILL.md
  • skills/openspec-ff-change/SKILL.md
  • skills/openspec-new-change/SKILL.md
  • skills/openspec-onboard/SKILL.md
  • skills/openspec-propose/SKILL.md
  • skills/openspec-sync-specs/SKILL.md
  • skills/openspec-update-change/SKILL.md
  • skills/openspec-verify-change/SKILL.md
  • src/cli/index.ts
  • src/commands/workflow/schemas.ts
  • src/core/completions/command-registry.ts
  • src/core/templates/workflows/propose.ts
  • src/core/templates/workflows/store-selection.ts
  • test/commands/schemas.test.ts
  • test/core/completions/command-registry.test.ts
  • test/core/templates/propose.test.ts
  • test/core/templates/skill-templates-parity.test.ts

Comment thread skills/openspec-onboard/SKILL.md
Comment thread src/commands/workflow/schemas.ts
Comment thread test/commands/schemas.test.ts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant