fix(cleanup): clarify legacy file deletion warning

[clay-good]

Status

LGTM for the scoped warning fix. Ready for review.

What was wrong

Legacy cleanup said “No user content to preserve,” although openspec/AGENTS.md is detected by existence alone and deleted entirely.

How it was fixed

Warn about whole-file deletion and ask users to back up custom content. Add warning coverage for command files and directories, put the migration guidance in docs-lab, and include a patch changeset that reflects current cleanup behavior.

Replication / proof

All 109 cleanup tests pass. Restoring the old warning fails 3 regression tests. Build, lint, TypeScript, changeset validation, and diff checks pass.

The full local suite passed 5,935 tests, with 4 existing failures reproduced on clean main at 79b6aa9c. GitHub's Linux, macOS, and Windows test jobs all pass, along with lint, type checking, release tracking, dependency review, audit, and CodeQL.

Credit

This carries forward the fix proposed by @philo-x in #1820. Thank you for identifying the misleading cleanup text, implementing the original correction, adding regression coverage, and following up with the changeset. The implementation commit retains co-author credit.

Notes

This version adapts #1820 to current main and moves the documentation change to docs-lab. Cleanup behavior and --force semantics are unchanged.

Closes #1819.
Supersedes #1820.

[coderabbitai]

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

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

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

Review profile: CHILL

Plan: Advanced

Run ID: a98ddb1e-3043-4403-84ac-757b1b28d40d

📥 Commits

Reviewing files that changed from the base of the PR and between 79b6aa9 and d27d8a4.

📒 Files selected for processing (4)

• .changeset/legacy-cleanup-deletion-warning.md
• docs-lab/help/legacy/migration.md
• src/core/legacy-cleanup.ts
• test/core/legacy-cleanup.test.ts

 ______________________________________________
< Winning the war on bugs, one line at a time. >
 ----------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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

[openspec-cloud]

No PR-relevant drift confirmed.

AI-generated · A citation proves the line exists, not that it makes the case — verify before acting.
Checked the 8 requirements selected for this PR at d27d8a4 (255 total).
This is not a full-repository clean result; see the check for coverage and any broader findings.
View results · Click Refresh, then Scan again in the check. Or comment /openspec-cloud.

[alfred-openspec]

Reviewed the current head. The cleanup warning now accurately distinguishes files that are deleted entirely from managed command files that preserve custom content, and tests cover the user-facing wording. Hosted CI is green. Approved. Final review of the docs-lab change still belongs to @TabishB.