feat(engine): state-mutation surface — phase lifecycle, finding resolve, drift hint (0.3.0)

[collincusce]

Fixes the state-mutation surface — the cluster a second dogfooding session root-caused (P0–P4). Diagnosis, verified in code: the read/knowledge surface is strong, but structured state drifted wherever the blessed write was missing (phases) or destructive (init/profile.lock). The headline symptom: cz_status reporting "Phase 0, nothing started" on a finished audit, because nothing could advance a phase.

P0 — Phase lifecycle (the silent-misdirect fix)

• cz_transition_phase(phase_n, to_status) — not_started/ready/in_progress/complete/blocked/failed (+ aliases start/done/block…), auto-stamps Started/Completed, updates both trackers. Phases had cz_add_phase but no way to advance them → cz_status froze. This is the write that keeps it honest.
• Dogfood proof: used the new tool to mark Clauderizer's own stuck "Phase 0 Bootstrap" complete — the digest flipped from Phase 0 READY to no in-progress/ready phase (i.e. stopped lying on a shipped tool).

P1 — Make drift visible (light, conservative)

• cz_status / SessionStart digest now emit ⚠ Drift: N entities still 'planned' while M phase(s) complete — cz_transition_status to reconcile. Fires only when there's completed work and untouched entities, so it informs without crying wolf.

P2 — Workflow-aware, non-crying-wolf preflight

• init --workflow {code,docs,audit} + a preflight_advisory config list: failing advisory checks become warn, not fail. Docs/audit make clean_tree advisory (a dirty tree is normal when accumulating deliverables); audit also makes tests advisory.

P3 — init that doesn't fight its user

• Resolves the engine command from the running interpreter's bin dir (sys.executable) before PATH/uvx — reliable for venv/WSL even off PATH.
• Stops clobbering profile.lock.toml on re-run (was overwriting the per-project overrides my own load_for_repo reads back — the fix was half a feature). Preserved now; delete to re-derive.

P4 — Finding lifecycle

• cz_resolve_finding(id, status, note) — update a finding's status + dated resolution note in HARDENING.md, honoring its "mark resolved, never delete" policy through a blessed path instead of a forbidden hand-edit. Append-only preserved.

Deferred (consciously)

• Full staleness detection beyond the conservative phase/entity hint, and separate tooling- vs target-finding streams (backlog docs: quickstart for an existing project #7) — both want a careful design pass; a rushed heuristic would re-create the crying-wolf problem.

18 MCP tools now; +12 tests (84 total); uv build + twine check clean. Ships as 0.3.0 — cut a v0.3.0 Release to publish.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HiQppNdrQhiZ5vwMEdSCzT

---

Generated by Claude Code