bug(purpose): mutations can approve stale source-derived work

[styler-ai]

Why

Purpose queue work is bound to an indexed source generation, but CLI and MCP mutation paths can open the purpose writer without first reconciling current saved source. If a file changes after queue issuance, the database can still match the old token and accept an outdated agent-approved purpose. A later scan correctly preserves that authored value, leaving stale intent and a misleadingly clean queue.

The existing generation token and SQLite conditional transaction are sound after current source has been published. The missing boundary is one source-freshness admission immediately before the purpose writer opens.

The separately reported persistent queue to no-op watch to queue refresh loop was not reproducible under the same root/database binding on RC1 or current source, with or without telemetry. RC2 protects that exact convergence path with a persistent-MCP regression but makes no speculative observer or routing change.

What Changes

• Reuse the existing saved-source freshness boundary once per purpose mutation batch.
• Publish safe current source repair before conditional work is evaluated so old tokens return typed stale state without purpose writes or authored-revision change.
• Apply the same admission to explicit purpose set and review for unavailable or unrefreshed paths.
• Preserve approved authored purposes across unchanged scans and retain the existing schema, token, atomic batch, replay, and concurrent-winner behavior.
• Add real CLI and persistent MCP edit-between-queue-and-apply regressions plus a same-binding queue/watch no-op convergence regression to mandatory platform and release CI.

Capabilities

• fresh-purpose-mutation-admission: every purpose write consults current saved-source authority before the existing SQLite transaction.
• durable-purpose-convergence: stale queue work is rejected and can be requeued for current source, while unchanged approved purposes survive scan and watch refresh.

Architecture Diagrams

• Purpose mutation freshness admission

Release Scope

ProjectAtlas v0.4.5-rc2 correctness fix in the existing CLI/MCP freshness orchestration and purpose mutation adapters. No purpose schema, token, watcher, routing, table, index, crate, or dependency is added.

Non-Goals

• Claim or patch an observer event/continuity defect without a quiescent same-binding reproduction.
• Add source hashes to purpose tokens or SQLite.
• Demote every approved purpose after a source edit.
• Introduce a background reconciler, mutation framework, actor, channel, or new crate.
• Weaken project identity, generation, atomic batch, replay, or authored-revision checks.

Pre-Mortem

Likely failure modes:

1. Freshness runs once per row and makes large batches unnecessarily expensive.
2. CLI is fixed while persistent MCP still accepts stale work, or vice versa.
3. Repair advances the generation but stale work still changes a purpose or authored revision.
4. Unchanged scans demote or discard current approved purposes.
5. A no-op watch regression is mistaken for proof of an unobserved production defect.
6. Tests replay SQLite tokens without editing real saved source.

Mitigations:

• Admit saved source once per complete batch and retain the no-change fast path. (OpenSpec tasks: 2.1, 2.2, 3.1)
• Exercise both CLI and persistent MCP mutation adapters against the same stale-source scenario. (OpenSpec tasks: 2.1, 2.2, 3.3)
• Preserve the generation-bound atomic transaction and assert no row or authored-revision change on stale work. (OpenSpec tasks: 2.3, 3.1, 3.2, 3.3)
• Prove current approved purposes survive unchanged scans and final queue convergence. (OpenSpec tasks: 2.3, 3.1, 3.3)
• Protect the quiescent same-binding path without changing observer or routing behavior absent a reproduction. (OpenSpec tasks: 2.4, 3.3, 3.6)
• Edit real saved source in mandatory runtime, CLI, MCP, platform, and packaged tests. (OpenSpec tasks: 3.1, 3.3, 3.4)

OpenSpec Tasks

1. Contract And Architecture

• 1.1 Map issue bug(purpose): mutations can approve stale source-derived work #463 to this change, synchronize its objective checklist, and keep RC2 scope limited to existing source admission before purpose mutation plus convergence proof.
• 1.2 Update the authored-mutation, freshness, watcher, and failure diagrams only where mutation admission changes the durable flow; render every changed Mermaid block and inspect it visually and semantically.

2. Fresh Mutation Admission

• 2.1 Route CLI purpose set and applied review through one current saved-source admission before opening the existing writer; retain preview, explicit, conditional, replay, and output compatibility.
• 2.2 Route MCP purpose set and applied review through the existing source-observation verified path once per batch with worktree/root identity, policy witness, cancellation, and no-change fast-path behavior.
• 2.3 Preserve the existing SQLite purpose schema, generation-bound token, atomic conditional batch, authored revision, approved-purpose durability, and concurrent-curator winner while stale source work changes no row.
• 2.4 Prove the existing same-binding persistent-MCP queue, zero-candidate watch, and queue sequence converges; retain typed recovery and make no observer or routing change without a quiescent same-binding reproduction.

3. Mandatory Regression And Release Proof

• 3.1 Add focused integration coverage for edit-between-queue-and-apply stale rejection, no-write/no-revision failure, unchanged apply/replay, requeue success, scan retention, folder/file identity, and final queue/watch convergence.
• 3.2 Retain and exercise the existing negative, failure, and concurrency contracts for unavailable targets, wrong root, policy/observation failure, cancellation, concurrent publication, and concurrent curators without duplicating storage logic or claiming new observer behavior.
• 3.3 Add real CLI and persistent MCP E2E that edit saved source between queue and apply, reject old work, apply current work, read exact current source/purpose, rescan, lint, and prove a final watcher no-op and empty current queue.
• 3.4 Wire the named E2E into required Linux, Windows, and macOS CI and the packaged holistic RC agent workflow without creating a second workflow.
• 3.5 Run focused tests, cargo fmt --check, cargo check --workspace --all-targets --all-features, warnings-denied workspace Clippy, full workspace/all-feature and doc tests, warnings-denied docs, strict OpenSpec, IssueOps checklist parity, ProjectAtlas lint, and representative unchanged/changed batch timing with explicit timeouts.
• 3.6 Update durable purpose, watcher, recovery, release, and agent-integration guidance; resolve or disposition every live review and automated finding and verify the exact packaged RC2 behavior without displacing v0.4.4 Latest.
• 3.7 Review the final implementation against the architecture diagrams, update the diagrams or implementation until they agree, or reconfirm the reasoned N/A.