fix(status): clarify planning completion

[clay-good]

Status

LGTM. This remains a backward-compatible clarification of the existing status contract.

What was wrong

openspec status --json reports isComplete: true when every planning artifact exists. That name led agents to interpret the change as fully implemented even when tracked implementation work was unfinished.

The continue workflow, human status summary, and completion next step reinforced that ambiguity by saying all artifacts were complete, assuming a task file existed, or directing users to review tasks before implementation even when implementation had already started.

How it was fixed

• Add isPlanningComplete with the same value and keep isComplete unchanged as a compatibility alias.
• Update first-party continue and update workflows to prefer the explicit name, with a fallback for older CLI versions.
• Say Planning is complete! and advise archiving only after implementation and any tracked work are complete, which also supports custom schemas without a task file.
• Report All planning artifacts complete! in human output instead of the ambiguous All artifacts complete!.
• Make completed-planning nextSteps stage-neutral by directing users to openspec instructions apply ... --json to inspect implementation progress, preserving --store when supplied.
• Document that planning completion does not mean implementation task completion.

No command flags, schemas, storage, task semantics, or architecture changes.

Replication / proof

A CLI regression creates all 4 planning artifacts with 1 unchecked task. Status reports isPlanningComplete: true, while apply instructions still report state: "ready" and remaining: 1. Completed-planning status now points to apply instructions rather than assuming implementation has not begun.

A black-box regression covers skip_specs: true: status reports planning complete, the compatibility alias has the same value, the specs artifact is skipped, and no specs directory is created. A store lifecycle regression confirms the apply next step retains the selected store.

Generated-workflow coverage rejects both the old All artifacts created! message and guidance that offers archive as an alternative when only planning is complete.

Validation completed:

• build and lint pass
• strict validation of the updated live spec passes
• package dry-run passes
• 154 focused CLI, status, store lifecycle, and generated-template tests pass
• full Node 22 suite: 3,476 tests pass; 2 unrelated npm-global-path assertions fail only because the runtime is launched through npx
• 3 independent adversarial review tracks found no remaining issues after the fixes

Notes / nits

The legacy isComplete field is not removed or redefined, so existing consumers keep their current behavior.

Fixes #795

Summary by CodeRabbit

• New Features
  • Added isPlanningComplete to status --json to indicate when all planning artifacts are complete.
  • Skipped planning artifacts now count as satisfied without requiring output files.
• Bug Fixes
  • Improved workflow guidance to distinguish planning completion from implementation completion, helping prevent premature archiving.
  • isComplete remains available as a compatibility alias for older integrations.
• Documentation
  • Updated CLI, workflow, and status documentation with clearer planning-completion semantics and messaging.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The status payload now exposes isPlanningComplete for planning-artifact completion. isComplete remains a compatibility alias. Workflow templates, skills, documentation, CLI output, and tests use or describe the new field.

Changes

Planning completion status

Layer / File(s)	Summary
Status contract and completion state openspec/specs/cli-artifact-workflow/spec.md, docs/agent-contract.md, src/core/artifact-graph/instruction-loader.ts, src/commands/workflow/status.ts, src/core/change-status-policy.ts, test/core/artifact-graph/*, test/commands/artifact-workflow.test.ts, test/cli-e2e/store-lifecycle.test.ts	The status response adds isPlanningComplete. isComplete remains an equivalent alias. CLI output identifies planning completion. Tests cover incomplete planning, completed planning, skipped artifacts, and unfinished implementation tasks.
Workflow status handling src/core/templates/workflows/*.ts, skills/openspec-*-change/SKILL.md, test/core/templates/skill-templates-parity.test.ts	Continue and update workflows use isPlanningComplete and support legacy isComplete responses. Continue guidance requires implementation before archiving. Template parity hashes and generated skill content hashes are updated.
CLI status documentation docs/cli.md	The JSON status documentation defines isPlanningComplete, skipped-artifact handling, implementation-task scope, and its compatibility relationship with isComplete.

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

Possibly related PRs

• Fission-AI/OpenSpec#1089: Both PRs modify status completion fields and workflow status handling.
• Fission-AI/OpenSpec#1278: Both PRs modify the update-change workflow template.
• Fission-AI/OpenSpec#1357: Both PRs modify continue and update skills and template parity tests.

Suggested reviewers: alfred-openspec, tabishb

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.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
Linked Issues check	✅ Passed	The PR addresses [#795] by adding isPlanningComplete, retaining isComplete as an alias, and clarifying planning versus implementation completion.
Out of Scope Changes check	✅ Passed	The documentation, workflow guidance, implementation updates, and tests directly support the status-completion clarification objective.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the primary change: introducing isPlanningComplete to clarify that status completion indicates planning artifact readiness, not implementation completion.

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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@openspec/specs/cli-artifact-workflow/spec.md`:
- Around line 29-30: Update the isPlanningComplete contract in
openspec/specs/cli-artifact-workflow/spec.md lines 29-30 so all non-skipped
planning artifacts must exist, while skipped artifacts count as satisfied;
retain isComplete as the same-value compatibility alias. Apply the same
definition in docs/agent-contract.md line 58, while preserving the rule that
skipped artifacts must not be created.

🪄 Autofix (Beta)

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: 014ddf96-3081-4d8a-8597-65c06140bbc9

📥 Commits

Reviewing files that changed from the base of the PR and between 45cca5d and 1126ebf.

📒 Files selected for processing (11)

• docs/agent-contract.md
• docs/cli.md
• openspec/specs/cli-artifact-workflow/spec.md
• skills/openspec-continue-change/SKILL.md
• skills/openspec-update-change/SKILL.md
• src/core/artifact-graph/instruction-loader.ts
• src/core/templates/workflows/continue-change.ts
• src/core/templates/workflows/update-change.ts
• test/commands/artifact-workflow.test.ts
• test/core/artifact-graph/instruction-loader.test.ts
• test/core/templates/skill-templates-parity.test.ts

[alfred-openspec]

Approved at exact head fb4b708. The new field preserves the existing contract while making planning completion explicit; a fresh build, lint, strict spec validation, and 143 focused status, template, and skipped-artifact tests pass.

[alfred-openspec]

Exact head bf14eb9 is clean. Planning completion remains backward-compatible in JSON, skipped artifacts count correctly, human guidance no longer conflates planning with implementation, and store-aware apply instructions are preserved. A fresh build and 147 focused workflow, loader, store-lifecycle, and parity tests pass, with hosted CI green.

[alfred-openspec]

Re-reviewed the rebased head. Planning completion remains backward-compatible, skipped artifacts count correctly, archive guidance is implementation-aware, 153 focused workflow/loader/store/parity tests and strict spec validation pass locally, and the full hosted matrix is green.