fix(propose): wait for explicit implementation request

[clay-good]

Status

LGTM.

What was wrong

The generated propose workflow could finish the planning artifacts and continue directly into implementation. Its handoff suggested apply but did not explicitly require the workflow to stop, it did not clearly limit the triggering request to planning, and it could resolve material ambiguity without asking the user. This is the behavior reported across Factory, Cursor, Kilo, Pi, and Codex.

How it was fixed

• Put a planning-only boundary before the workflow steps and repeat the explicit stop at the final handoff.
• Clarify that any request selecting or triggering propose authorizes planning only, even when it asks to build or fix something.
• Ask the user before creating the change when ambiguity would materially change scope, externally observable behavior, compatibility, or acceptance criteria. Minor details still use recorded assumptions.
• Make implementation and apply instructions in the triggering request expire with the propose workflow. Applying requires a new user request after the artifacts are presented.
• Hand command-only tools exclusively to their generated apply command. Skill surfaces may also accept an explicit request to apply the change.
• Verify the boundary and apply handoff survive every registered command adapter and the affected tools' real initialization paths.

This is prompt hardening only. It does not add an approval state, change the artifact workflow, or alter any CLI/API behavior.

Replication / proof

• Regression tests cover the skill and command templates, boundary placement, material clarification, and the final stop.
• Adapter tests verify both boundaries and the correctly transformed apply invocation in every registered command format.
• End-to-end initialization generated and verified propose instructions for Factory, Cursor, Kilo, Pi, and Codex.
• npm test -- --run: 119 files, 3,480 tests passed.
• npm run lint: passed.
• npm run build: passed.

Closes #232.
Closes #258.
Closes #262.

Notes / nits

OpenSpec controls the generated command and skill instructions, not the host model's compliance. This PR fully addresses the repository-controlled prompt surfaces without claiming a formal enforcement gate.

The propose workflow remains one-step for clear requests. Users who want open-ended discovery can still use /opsx:explore; propose asks only about ambiguity that could materially change the result.

#1500 touches the same checked-in skill and parity hashes for unrelated guidance. Whichever PR lands second may need a mechanical rebase and hash refresh.

Summary by CodeRabbit

• New Features

  • Proposal workflows now stop after creating planning artifacts.
  • Prevented proposal workflows from implementing changes or editing project code before a separate implementation request.
  • Added clarification prompts when ambiguity may affect scope or behavior.
  • Prompted users to review planning artifacts before implementation.

• Tests

  • Added coverage for these safeguards across supported tool integrations.
  • Updated template consistency checks.

• Documentation

  • Documented the planning-only proposal behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The propose workflow now stops after creating planning artifacts. It prohibits implementation and project-code edits until a separate implementation request. Tests, initialization coverage, parity hashes, and a patch Changeset cover the updated instructions.

Changes

Propose planning boundary

Layer / File(s)	Summary
Enforce planning-only behavior skills/openspec-propose/SKILL.md, src/core/templates/workflows/propose.ts	The propose skill and command templates prohibit implementation and project-code edits. They require clarification for material ambiguity and artifact review before implementation.
Validate and publish the guardrail test/core/templates/propose.test.ts, test/core/init.test.ts, test/core/templates/skill-templates-parity.test.ts, .changeset/quiet-proposals-stop.md	Tests verify the guardrail across command adapters and tool targets. Parity hashes track generated content. A patch Changeset records the release.

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

Possibly related PRs

• Fission-AI/OpenSpec#306: Updates proposal workflow templates with planning-only boundaries.
• Fission-AI/OpenSpec#1089: Updates the same propose workflow templates and generated skill behavior.
• Fission-AI/OpenSpec#1464: Updates propose workflow guidance around user clarification.

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 0.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 changes address issues #232, #258, and #262 by enforcing planning-only behavior, ambiguity clarification, and deferred implementation.
Out of Scope Changes check	✅ Passed	The changes remain within scope by updating propose guidance, templates, generated artifacts, and related regression tests.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: the propose workflow now waits for an explicit implementation request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/stop-propose-before-implementation

---

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 at exact head f36897a. Focused template, parity, and initialization coverage passes; the generated guidance now preserves selected stores, validates syncs before success, and keeps propose planning-only until a separate apply request.