fix(tasks): separate completion from archive readiness

[Marzx13]

Summary

openspec instructions apply currently calls a change ready to archive when every tracked checkbox is checked. Task lists can also include archive-dependent work that cannot be completed beforehand, producing warnings in stock OpenSpec and a circular dependency under stricter project policies.

This PR reports tracked completion more precisely and helps avoid generating circular task lists. Follow-up work stays visible as ordinary bullets in the existing task document.

Closes #1790

Key changes

• Replaces the archive-readiness claim with: "All tracked tasks are complete. Review or verify the change as appropriate before archiving."
• Guides the default spec-driven task authoring flow toward work completable before archive, including hosted review or verification when appropriate.
• Preserves requested archive and archive-dependent steps in an optional ## Workflow follow-up section at the end of tasks.md, with a plain-bullet example. These bullets are reference information outside tracked task progress.
• Updates the shared apply instructions and committed generated skill, with regression coverage for output, unchanged JSON state/progress, per-tool command rewriting, and generated-template parity.

Testing performed

• Build, lint, and TypeScript checks.
• Revised guidance: 201 focused CLI, task parsing, task-guidance, command-reference, and template-parity tests passed across six files.
• The follow-up example is checked with the existing task parser to confirm it adds no tracked tasks.
• Original implementation: full local suite passed (4,343 tests; 79 skipped). Under npm 12, that run used a process-local npm_config_allow_git=all for the Git-dependency installation fixture; no persistent npm configuration was changed.
• git diff --check.

Risks and follow-ups

The behavioral improvement depends on agents following the guidance; this does not enforce archive readiness or guarantee generated plans. Stock OpenSpec still permits archiving incomplete tasks after confirmation. Projects remain responsible for their archive policy and review-evidence requirements.

The all_done state, progress fields, task syntax and parsing, validation, and archive behavior remain unchanged. There are no dependency, migration, configuration-format, or schema-format changes. No changeset is included, following the normal release cadence unless a maintainer requests dedicated tracking.

AI assistance disclosure

Original research, implementation, and verification used OpenAI Codex with gpt-5.6-sol at xhigh reasoning effort. Subsequent review and revisions used OpenAI Codex with GPT-6 Astra.

Summary by CodeRabbit

• Documentation
  • Clarified that tracked tasks cover implementation and verification work completed before archiving. Archive-related steps now belong in an optional “Workflow follow-up” section.
  • Updated completion guidance to recommend reviewing or verifying a change before archiving.
• Tests
  • Added checks for task guidance, follow-up handling, and completion messaging.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (1)

test/AGENTS.md — auto-discovered

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: Fission-AI/OpenSpec/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 9e06afcf-85b2-4ee6-b0cb-0b599d3e9a98

📥 Commits

Reviewing files that changed from the base of the PR and between 3a34ea3 and c9bb3f0.

📒 Files selected for processing (8)

• docs-lab/reference/schemas/spec-driven/index.md
• schemas/spec-driven/schema.yaml
• skills/openspec-apply-change/SKILL.md
• src/commands/workflow/instructions.ts
• src/core/templates/workflows/apply-change.ts
• test/commands/artifact-workflow.test.ts
• test/core/templates/propose.test.ts
• test/core/templates/skill-templates-parity.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

Task-authoring guidance now separates tracked pre-archive work from optional archive follow-up. Apply completion messages report tracked tasks as complete and suggest review or verification before archiving.

Changes

Task Tracking and Archive Guidance

Layer / File(s)	Summary
Tracked tasks and workflow follow-up schemas/spec-driven/schema.yaml, docs-lab/reference/schemas/spec-driven/index.md, test/core/templates/propose.test.ts	Guidance places implementation and verification work that can finish before archiving in numbered tracked-task groups. Optional archive-related steps go in a plain-bullet ## Workflow follow-up section. Tests check that those bullets do not count as tracked tasks.
Apply completion guidance and validation src/core/templates/workflows/apply-change.ts, src/commands/workflow/instructions.ts, skills/openspec-apply-change/SKILL.md, test/commands/artifact-workflow.test.ts, test/core/templates/skill-templates-parity.test.ts	Apply completion guidance reports tracked tasks as complete and suggests review or verification before archiving. Tests check completion wording, progress output, and generated-template parity.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: clay-good

Merge Risk: ⚪ Minimal · up to c9bb3

This PR rewords apply-completion messages and task-authoring guidance so that finishing tracked tasks is no longer presented as readiness to archive. Task progress and archive behavior are unchanged. No merge-blocking risk is evident.

Security Architecture Review

Security architecture risk: ⚪ Minimal · up to c9bb3

The change clarifies completion guidance and keeps archive-dependent follow-up visible without counting it as unfinished implementation. The reviewed changes do not weaken completion checks, expand permissions, or introduce a new security finding.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — The concrete public-entrypoint signals identify template payload and generated-content hash expectations in tests. Their updates do not expose a production endpoint or grant additional authority.

Trust Boundaries and Controls

• observed — The task document influences reported progress and agent workflow, but the PR does not add automatic archive execution or make review guidance an authorization check. Existing blocked-state handling and the archive handoff remain in place.

Resilience and Maintainability Implications

• observed — Completion still requires configured tracking, available tracking evidence, at least one task, and zero remaining tasks. Missing artifacts, missing tracking files, and unusable task evidence retain their existing handling. The PR does not introduce a new persistent transition, retry, concurrency, or recovery mechanism.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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: separating tracked task completion from archive readiness.
Linked Issues check	✅ Passed	The PR meets the coding requirements in [#1790]. src/commands/workflow/instructions.ts reports tracked completion without declaring archive readiness. The shared apply template and `skills/openspec-…
Out of Scope Changes check	✅ Passed	The changed source files, generated guidance, reference documentation, and tests all implement or verify [#1790]. No unrelated behavior or unrelated product area is changed in the reviewed diff.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 5 files. (3 skipped: 3 …

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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

[alfred-openspec]

Reviewed the completion semantics, profile-aware archive handoff, generated-skill parity, task parsing coverage, and canonical docs update. Progress behavior remains compatible, and CI is green.