[MartinP7r]

Summary

• add explicit tome paperclip-agents preview|apply workflow for resolving versioned catalog categories/use-case sets into Paperclip agent desired skills
• keep generic tome sync/copy deployment separate from Paperclip mutation; preview uses state files or read-only API, apply requires a confirmation token
• sync via Paperclip agent skill replacement and read every affected agent back, surfacing desired/runtime mismatches
• document the command and update the changelog

Verification

• cargo test -p tome paperclip_agents::tests
• cargo test -p tome cli::tests::obsolete_commands_are_rejected
• cargo clippy -p tome --all-targets -- -D warnings
• disposable preview: cargo run -p tome -- paperclip-agents preview --catalog <scratch>/catalog.toml --assignments <scratch>/assignments.toml --current-state <scratch>/state.json --constraint paperclip-agent rendered token apply-0695cf089bcb and before/after diff without mutation

Paperclip: MCO-158

[MartinP7r]

Blocking review findings

PR #618 is not ready to merge. Please correct all of the following and add regression coverage.

1. Authentication is broken — paperclip_agents.rs:333 generates Authorization: Bearer *** literally, so api_key is never sent. The real API integration must authenticate while keeping secrets out of logs/errors/config artifacts.

2. Confirmation does not prove an exact preview — paperclip_agents.rs:891 derives a deterministic, replayable truncated hash with no preview-issued state/nonce/expiry/single-use consumption. At minimum, bind confirmation to an exact immutable plan and reject replay/staleness; do not accept a token merely derivable for a plan.

3. Confirmation ignores before-state drift — the token excludes each agent’s current desired state. A concurrent assignment added after preview can be removed by apply without appearing in the confirmed preview. Bind per-agent before desired state and reject drift before mutation, or provide an equivalent safe optimistic-concurrency mechanism.

4. Incomplete state snapshots are unsafe — paperclip_agents.rs:283 treats an assigned agent absent from --current-state as empty. Require a state record for every assigned agent; fail preview rather than inventing an empty state.

5. Fleet apply/read-back is incomplete on failure — paperclip_agents.rs:588-596 returns on the first sync or read-back failure. After any mutation attempt, collect outcomes and read back every attempted/affected agent; return an explicit partial-mutation report including successes, sync failures, read-back failures, and mismatches. Apply rendering must preserve the actual before state, not a synthetic empty one.

Keep the approved boundaries: generic tome sync must never mutate Paperclip agents; previews/dry runs/state-file paths must make no real mutation or model calls; no Desktop changes. Add focused tests for authentication request construction without secret leakage, incomplete snapshot rejection, token/plan state drift, token replay/staleness, and multi-agent partial-failure read-back.

Do not mark MCO-158 done until a corrected PR has local verification, green exact-head CI, independent review, and a read-back of the Paperclip issue state.

[MartinP7r]

Final blocking review: confirmation-token atomicity

The d6ccc516 head fixes the prior authentication, snapshot, before-state binding, expiry/drift, and fleet read-back blockers. Full review suite passed (1,196 passed, 2 ignored).

One critical blocker remains:

• crates/tome/src/paperclip_agents.rs:423,445,473 uses an unlocked load-modify-save token store and a fixed .json.tmp path. Two concurrent apply processes can both read an unconsumed token, independently mark/save it consumed, then both proceed to mutate agents. Concurrent previews can also lose issued-token records or collide on the temp file.

Required correction:

1. Make issuing and consuming confirmation tokens a process-safe, atomic transaction over the shared store: exclusive lock, read/check/update/persist while held, and safe cleanup. A consume claim must be durably recorded before any external agent mutation begins.
2. Use unique temporary files and atomic replacement (with appropriate error/recovery handling), not a predictable shared *.tmp filename.
3. Add deterministic concurrent regression tests proving: (a) exactly one of two simultaneous consumes succeeds and the loser performs no mutation; (b) concurrent issue operations preserve both records; (c) failure/cleanup does not leave a token spuriously usable or corrupt the store.
4. Retain all previously accepted safeguards: authenticated-but-redacted requests, complete snapshots, plan/before-state binding with expiry/drift checks, preview/dry-run non-mutation, all-agent apply/read-back outcomes, and no Desktop changes.

Do not mark MCO-158 done until the corrected exact head passes local verification, exact-head CI, independent review, and Paperclip issue read-back.