v0.4.0 — Safe Re-Init & the Version-Upgrade Path: No-Clobber Init, `prospec upgrade` & Consent-Gated Migration

Prospec v0.4.0

v0.3.x kept hardening the spec flywheel — but two setup-layer gaps could quietly cost you
work. prospec init's idempotency gate only checked .prospec.yaml, then unconditionally
overwrote 7+ files including the curated trust zone (CONSTITUTION.md / _conventions.md /
_index.md). The common move of deleting .prospec.yaml to re-localize triggers therefore
wiped curated content. And once prospec shipped a new version, there was no upgrade
path — nothing to bring an existing project up to date. v0.4.0 closes the data-loss hole
and adds a real, two-stage upgrade path (deterministic CLI + consent-gated Skill), then
dogfoods it on this very repo.

44 files changed · +1,488 / −270 · 1 merged PR (#42)

---

✨ Headline features

No-clobber init — re-running init never overwrites curated files (P0, BL-044)

prospec init now uses a per-file skip-if-exists guard (matching knowledge-init.service):
it rebuilds only the files that are actually missing and leaves everything you've authored
untouched. The .prospec.yaml-last completion marker is preserved, so re-running init to
recover a missing file is now safe — deleting .prospec.yaml to re-localize triggers can no
longer take the trust zone with it. (PR #42)

prospec upgrade — a deterministic, zero-LLM version-bump command (P1, BL-044)

A new prospec upgrade CLI command records the prospec version in .prospec.yaml
(canonical re-serialize), re-runs agent sync, and prints a migration report. It writes no
docs and is deliberately not in INIT_COMMANDS, so an uninitialized project gets a clean
ConfigNotFound instead of a half-built tree. .prospec.yaml version now means the prospec
version the project uses (a legacy "1.0" is treated as stale and bumped on first upgrade) —
there is no separate prospec_version field. (PR #42)

/prospec-upgrade — the consent-gated migration finisher (P1, BL-044)

The judgment work the CLI can't do safely now lives in a new /prospec-upgrade Skill: it scans
the files prospec init created, compares them to the latest templates, and offers to migrate
any whose format has drifted — asking per file, format-only, never touching your authored
content. It then localizes triggers for any newly-added skills (fill-missing only) and re-runs
agent sync. Like /prospec-quickstart, it's deployed on disk but kept out of the entry
config, so it adds no recurring token cost. (PR #42)

Trigger re-localization without nuking config (P2, BL-044)

agent sync now names the skills missing a skill_triggers entry (partial localization),
and /prospec-quickstart fills only the missing triggers — so you never need to delete
.prospec.yaml to re-localize. /prospec-knowledge-update also gained a Phase 2.5 step that
asks for consent before migrating drifted AI-knowledge format. (PR #42)

---

🔁 Dogfood: the upgrade path upgraded this repo

After merge, this repo ran the new flow end-to-end: prospec upgrade + /prospec-upgrade
bumped .prospec.yaml version 1.0 → 0.3.2, localized the new /prospec-upgrade
skill's triggers, and left every init-created doc untouched — exactly the no-clobber
guarantee the P0 fix promises.

🧪 Quality & tests

• The suite grew 1,726 → 1,760 tests — new coverage for init recovery, the upgrade
  orchestrator, missing-trigger detection, version semantics, and the entry-exclusion
  contract ({quickstart, upgrade}); new contract assertions are mutation-verified.
• prospec check drift engine is 8/8 PASS (0 warn), verify:skills 28/28, coverage 96%.
• The change ran dogfood-style through prospec's own SDD workflow
  (story → plan → tasks → implement → review → verify → archive), reaching 0-critical
  adversarial review and verify grade A.

---

📊 Compared to v0.3.2

	v0.3.2	v0.4.0
Tests	1,726	1,760
Re-running init	overwrites 7+ files incl. trust zone	per-file skip-if-exists (no clobber)
Version-upgrade path	—	prospec upgrade (CLI) + /prospec-upgrade (Skill)
.prospec.yaml version	bootstrap marker ("1.0")	the prospec version the project uses
Re-localizing triggers	delete .prospec.yaml (risked clobber)	agent sync names gaps · fill-missing only
Skills	16	17 (+ /prospec-upgrade)

---

⬆️ Upgrade notes

On a version bump, run prospec upgrade then /prospec-upgrade in your AI agent: the
CLI records the new version + re-syncs agents (writing no docs), and the Skill handles
init-doc format migration + new-skill trigger localization with per-file confirmation.
If you only want the new skill wired up, prospec agent sync is enough to pick up
/prospec-upgrade. The init fix is automatic — re-running init is now safe by construction.

---

Merged PRs

• #42 fix init clobber + add prospec upgrade path (BL-044)