docs(specs): align four requirements with current behavior by openspec-cloud[bot] · Pull Request #1707 · Fission-AI/OpenSpec

openspec-cloud · 2026-08-20T22:18:21Z

Status

LGTM for final human review. Manually audited against current source and tests; not merged.

Commit 55604d78a: Linux, macOS, and Windows CI pass, along with the required "All checks passed" gate, security checks, and docs preview. CI run.

What was wrong

Four requirements described outdated tool paths, apply guidance, setup output, or list-command behavior. The automated proposal also included unsupported corrections: the archive CLI's output string was attributed to the sync skill, and init cancellation was described as consistently exiting with 130.

How it was fixed

Document devin as the tool ID and windsurf as a compatibility alias, with skills written under .devin/skills when skill delivery is enabled.
Match the no-apply-block fallback instruction and account for skipped artifacts.
Describe the actual openspec init summary and missing-adapter message instead of the retired setup output.
Identify openspec change list as deprecated, preserve JSON on stdout and warnings on stderr, and document rejection of unsupported --all.

Removed the unsupported init and sync-skill corrections. Merged current main so the review diff contains only three spec files and one CLI test file.

Replication / proof

Added four CLI regression cases for legacy text/long/JSON output, exact warning placement, and unsupported --all rejection. The existing preferred-list test verifies warning-free JSON output.
Full suite: 4,233 tests across 145 files pass with Node 20.19.0, pnpm 9.15.9, a temporary home/config, and inherited Oh My Zsh paths removed.
Build, TypeScript checking, ESLint, and git diff --check pass.
Strict validation passes for ai-tool-paths, cli-artifact-workflow, and cli-change.
Independent source review found no remaining blockers in the changed claims.

Notes / nits

No production code, dependency, or release changes. This is not a claim that every repository spec is current. Unchanged init cancellation behavior and unrelated spec drift remain outside this PR.

Initial local runs exposed host-environment contamination: real MiniMax skills were discovered during update tests, and inherited ZSH made completion-tip tests see installed completions. Re-running with isolated environment settings resolved those failures without changing the test harness.

- ai-tool-paths/path-configuration-for-supported-tools#2: Changed the windsurf scenario's required skillsDir from `.windsurf` to `.devin`. - cli-update/slash-command-updates#6: Require $ARGUMENTS to be placed in the file body (not frontmatter) for OpenCode archive commands. - rules-injection/validate-artifact-ids-during-instruction-loading#6: Updated the expected warning text to use double quotes and to state it matches no artifact in any available schema, listing known artifact IDs. - specs-sync-skill/skill-output#3: Changed the expected no-changes message to 'Specs already in sync; no files changed.' to match the code. None of these reduce what a requirement demands. Scanned at 1ebddd1 by openai/gpt-5-mini.

openspec-cloud · 2026-08-20T22:22:18Z

✅ Specs and code agree — nothing to do.

AI-generated · A citation proves the line exists, not that it makes the case — verify before acting.
Checked the 4 requirements selected for this PR at e501b74 (252 total).
View results · Click Refresh, then Scan again in the check. Or comment /openspec-cloud.

openspec-cloud · 2026-08-20T23:57:28Z

▶ View full results and scan again

🔎 43 requirements drifted — 33 pointing at code, 10 needing a decision.

AI-generated · A citation proves the line exists, not that it makes the case — verify before acting.

On 1ebddd1; 1 requirement could not be judged — not a clean result.

🔴 CI Job Integration — code is wrong · high

Expected — openspec/specs/ci-nix-validation/spec.md:45

The Nix validation jobs SHALL be integrated into the existing GitHub Actions workflow and required for merge.

Observed — .github/workflows/ci.yml:171

if: needs.changes.outputs.nix == 'true'

Next → fix the code at .github/workflows/ci.yml:171 so it satisfies the requirement.
Protect the fix: add a regression check and link it from this requirement.

🔴 Nix Flake Build Validation — code is wrong · high

Expected — openspec/specs/ci-nix-validation/spec.md:7

The CI system SHALL validate that the Nix flake builds successfully on every pull request and push to main.

Observed — .github/workflows/ci.yml:170

needs: changes

Next → fix the code at .github/workflows/ci.yml:170 so it satisfies the requirement.
Protect the fix: add a regression check and link it from this requirement.

🔴 Nix Installation in CI — code is wrong · high

Expected — openspec/specs/ci-nix-validation/spec.md:76

The CI environment SHALL have Nix properly installed and configured before running validation.

Observed — .github/workflows/ci.yml:282

needs: [test_matrix, lint, nix-flake-validate]

Next → fix the code at .github/workflows/ci.yml:282 so it satisfies the requirement.
Protect the fix: add a regression check and link it from this requirement.

40 more findings are in the full check.

View results · Click Refresh, then Scan again in the check. Or comment /openspec-cloud.

- ai-tool-paths/path-configuration-for-supported-tools#2: Updated the Windsurf scenario to expect skillsDir '.devin' instead of '.windsurf'. - cli-artifact-workflow/experimental-isolation#8: Updated the file-path in the Single file implementation scenario from src/commands/artifact-workflow.ts to src/commands/workflow to match current code organization. - command-generation/toolcommandadapter-interface#2: Updated the Windsurf adapter file path pattern to use '.devin/workflows/opsx-<id>.md' to match the implemented adapter. None of these reduce what a requirement demands. Scanned at 1ebddd1 by openai/gpt-5-mini.

- ai-tool-paths/path-configuration-for-supported-tools#2: Updated the windsurf scenario to require skillsDir `.devin` instead of `.windsurf` to match current mapping. - cli-artifact-workflow/experimental-isolation#8: Updated the path in the 'Single file implementation' scenario from src/commands/artifact-workflow.ts to src/commands/workflow/*. - context-injection/format-context-with-xml-style-tags#2: Updated tag name from <context> to <project_context> in the requirement and scenarios to match implementation. - specs-sync-skill/skill-output#3: Updated the No changes needed scenario message to match the actual output: changed text to 'Specs already in sync; no files changed.' None of these reduce what a requirement demands. Scanned at 1ebddd1 by openai/gpt-5-mini.

- cli-artifact-workflow/experimental-isolation#8: Updated the single-file path from src/commands/artifact-workflow.ts to src/cli/index.ts to match code. - ai-tool-paths/path-configuration-for-supported-tools#2: Updated the Windsurf scenario to require skillsDir `.devin` instead of `.windsurf` to match the alias to Devin. - command-generation/toolcommandadapter-interface#2: Updated the Windsurf adapter file path requirement to use the .devin/workflows/opsx-<id>.md path. - cli-artifact-workflow/schema-apply-block#9: Updated the default instruction text to include the word "required", matching the implemented string. - opsx-onboard-skill/graceful-exit-handling#8: Updated the continuation command from `/opsx:continue <name>` to `/openspec-continue-change <name>` to match the implemented command. None of these reduce what a requirement demands. Scanned at f1b521d by openai/gpt-5-mini.

cloudflare-workers-and-pages · 2026-08-21T23:28:01Z

Deploying openspec-docs with Cloudflare Pages

Latest commit:	`55604d7`
Status:	✅ Deploy successful!
Preview URL:	https://6bfa53c0.openspec-docs.pages.dev
Branch Preview URL:	https://openspec-drift-corrections-c.openspec-docs.pages.dev

View logs

- ai-tool-paths/path-configuration-for-supported-tools#2: Updated the 'windsurf' scenario to require skillsDir '.devin' to match the current mapping of 'windsurf' to 'devin'. - cli-init/exit-codes#7: Updated the exit code for user-cancelled operations from 3 to 130. - context-injection/format-context-with-xml-style-tags#2: Replaced <context> tag name with <project_context> in requirement text and both scenarios to match the implemented tag. - specs-sync-skill/skill-output#3: Replaced the no-changes message text to match the actual logged message ('Specs already in sync; no files changed.'). - telemetry/first-run-telemetry-notice#5: Updated the quoted one-line notice text to include the additional opt-out instruction 'or openspec config set telemetry.enabled false' to match the implemented message. None of these reduce what a requirement demands. Scanned at f1b521d by openai/gpt-5-mini.

…c65034f27eba887

- ai-tool-paths/path-configuration-for-supported-tools#2: Updated the Windsurf scenario to require skillsDir '.devin' instead of '.windsurf'. - cli-init/progress-indicators#1: Replaced the grouped spinner text '⠋ Configuring AI tools...' with the per-tool spinner text 'Setting up <tool.name>...'. - specs-sync-skill/skill-output#3: Replaced the no-changes message to match the code: "Specs already in sync; no files changed." - telemetry/first-run-telemetry-notice#5: Updated the quoted first-run notice text to include the alternative opt-out command 'or openspec config set telemetry.enabled false'. None of these reduce what a requirement demands. Scanned at f1b521d by openai/gpt-5-mini.

- ai-tool-paths/path-configuration-for-supported-tools#2: Updated the Windsurf scenario to require skillsDir '.devin' to match the code mapping. - cli-change/legacy-compatibility#2: Changed the deprecated command in both scenarios from 'openspec list' to 'openspec change list' and updated the deprecation notice to point users to 'openspec list'. - cli-init/exit-codes#7: Updated the exit code for user-cancelled operations from 3 to 130 to match implemented behavior. - cli-artifact-workflow/schema-apply-block#9: Updated default instruction text to match code: changed "All artifacts complete. Proceed with implementation." to "All required artifacts complete. Proceed with implementation." - cli-artifact-workflow/output-messaging#12: Updated the expected skipped-commands message to match the actual output format: "Commands skipped for: <tools> (no adapter)". - specs-sync-skill/skill-output#3: Updated the exact no-changes message to match the code's wording. None of these reduce what a requirement demands. Scanned at a0ddb60 by openai/gpt-5-mini-2025-08-07.

…283e

alfred-openspec

Reviewed at 55604d7. The four spec corrections match current tool paths, apply behavior, init output, and legacy list behavior. Build and all 31 CLI e2e tests pass.

openspec-cloud Bot requested a review from a team as a code owner August 20, 2026 22:18

openspec-cloud Bot requested review from clay-good and removed request for a team August 20, 2026 22:18

openspec-cloud Bot changed the title ~~docs(openspec): resolve 4 OpenSpec Cloud findings~~ docs(openspec): update 3 requirements to match the code Aug 21, 2026

openspec-cloud Bot changed the title ~~docs(openspec): update 3 requirements to match the code~~ docs(openspec): update 4 requirements to match the code Aug 21, 2026

openspec-cloud Bot changed the title ~~docs(openspec): update 4 requirements to match the code~~ docs(openspec): update 5 requirements to match the code Aug 21, 2026

openspec-cloud Bot and others added 3 commits August 22, 2026 23:42

Merge branch 'main' into openspec/drift/corrections-c50ac33b3351fb774…

6de3441

…c65034f27eba887

openspec-cloud Bot changed the title ~~docs(openspec): update 5 requirements to match the code~~ docs(openspec): update 4 requirements to match the code Aug 23, 2026

openspec-cloud Bot changed the title ~~docs(openspec): update 4 requirements to match the code~~ docs(openspec): update 6 requirements to match the code Aug 26, 2026

clay-good added 2 commits August 27, 2026 14:09

Merge remote-tracking branch 'origin/main' into codex/harden-pr-1707-…

91c800d

…283e

docs(specs): verify drift corrections against current behavior

55604d7

clay-good changed the title ~~docs(openspec): update 6 requirements to match the code~~ docs(specs): align four requirements with current behavior Aug 27, 2026

alfred-openspec approved these changes Aug 28, 2026

View reviewed changes

Navigation Menu

Uh oh!

docs(specs): align four requirements with current behavior - #1707

docs(specs): align four requirements with current behavior#1707
openspec-cloud[bot] wants to merge 10 commits into
mainfrom
openspec/drift/corrections-c50ac33b3351fb774c65034f27eba887

openspec-cloud Bot commented Aug 20, 2026 •

edited by clay-good

Loading

Uh oh!

openspec-cloud Bot commented Aug 20, 2026

Uh oh!

openspec-cloud Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

alfred-openspec left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

openspec-cloud Bot commented Aug 20, 2026 • edited by clay-good Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Status

What was wrong

How it was fixed

Replication / proof

Notes / nits

Uh oh!

openspec-cloud Bot commented Aug 20, 2026

✅ Specs and code agree — nothing to do.

Uh oh!

openspec-cloud Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 43 requirements drifted — 33 pointing at code, 10 needing a decision.

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying openspec-docs with Cloudflare Pages

Uh oh!

alfred-openspec left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

openspec-cloud Bot commented Aug 20, 2026 •

edited by clay-good

Loading

openspec-cloud Bot commented Aug 20, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Aug 21, 2026 •

edited

Loading