# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: minor -->

## What Changed

Implemented Phase 2 of the approved Approval-as-Data design: the **approval ledger**.
Every operator approval is now recorded as durable, signed data — classified as
approved-as-is, approved-with-change (with the reason for each change), or rejected — and
the system computes a per-class agreement ratio and streak from those records. The ledger
tracks approvals wherever they occur: an official spec sign-off, a decision approved in
chat, or any other surface. New endpoints record a decision, list the records, and return
the agreement summary with a breakdown by surface. The ledger is signed, append-only, and
read-only with respect to all other behavior — it never gates, blocks, or changes anything.
The authoritative source of whether an approval was as-is or changed is always the
operator; the agent never self-classifies intent, and any record is operator-correctable.

Implemented the Coordination Mandate enforcement engine (the design the operator
signed off as A/A/B): a deny-by-default authority gate for autonomous agent-to-agent
actions. The operator writes one bounded, expiring, revocable "permission slip"
delegating specific authorities to a specific pair of agents; the slip — not the agent
— is what authorizes each action, preserving the rule that the one asking is never the
one authorizing. Issuance and revocation require the operator's dashboard PIN, so an
agent's API access alone is structurally unable to create or widen a mandate. A signed
store verifies authorship on every check (a forged or edited mandate fails), risky
authorities can be tied to objective real-state conditions the agent cannot fake, and
every decision — allowed and denied alike — lands in a tamper-evident, hash-chained
audit log. With no mandate issued, the gate denies everything, so this ships inert and
changes no behavior until the operator issues the first mandate.

Added the Phase-3 invariant-parity monitor for the feedback-factory migration: a
windowing layer over parity results that computes the objective
parity-zero-divergence condition (a sustained run of clean passes over a minimum
real-traffic window) which the future cutover step reads as its go signal. Includes
a durable, restart-surviving variant (append-only pass journal, torn-line tolerant).
Internal migration tooling — not yet wired to any live behavior.

Added the Phase-4 data-migration integrity tooling for the feedback-factory
migration: import-as-is preservation of every curated field, per-row checksums
(in vs out), fingerprint-uniqueness scanning, auto-increment sequence reset,
schema-equivalence assertion, and the structural never-re-derive guard (the
processor refuses to mutate any cluster created before the cutover timestamp or
carrying governance notes). Internal migration tooling — not yet wired to any
live behavior.

SessionManager now samples the live tmux pane cwd for enabled development-agent sessions and stores it in a crash-safe sidecar. Resume spawns prepend a restore note only for fresh, existing `.worktrees` paths; home-only sessions remain a no-op.

## What to Tell Your User

Your agent now remembers your approvals instead of forgetting them the moment they happen.
Each time you approve something — a full spec, or just a choice you make in chat — it can
record whether you took its recommendation as-is or changed it, and why. Over time this
builds a simple picture of where the agent already proposes what you would have picked, and
where it still needs to close the gap. You stay the source of truth: the agent only records
what you explicitly say, and you can correct any entry. This is an internal, read-only
record — it never changes what the agent does, it just helps it learn your preferences.

You can now hand your agent a bounded permission slip instead of approving every step
of a multi-agent project. You write the slip once from your dashboard with your PIN:
exactly which actions are allowed, within which limits, for which two agents, until
when. Your agent can act inside those lines without pinging you, and nothing outside
them — and you can tear the slip up at any moment. Everything done under a slip is
written to a tamper-evident log you can review. Until you issue a slip, nothing changes
at all: the system refuses every delegated action by default.

Nothing changes for you. This is internal plumbing for the feedback-system handover:
a safety meter that has to read "clean for a sustained window" before the one-way
switch can ever be considered. It ships dormant.

Nothing changes for you. This is internal plumbing for the feedback-system
handover: the checks that guarantee curated history is copied perfectly and can
never be silently rewritten afterward. It ships dormant.

Developer-agent respawns can now re-surface the worktree checkout they were building in before the restart. Normal home-only conversations are unchanged.

## Summary of New Capabilities

- Record an approval decision through the new approvals endpoint, tagged as approved-as-is,
  approved-with-change, or rejected, with the reason for any change.
- Read a per-class agreement summary (total, approved-as-is count, ratio, streak, and a
  breakdown by where the approval happened) plus a list of recorded decisions.
- Maturity: stable for the recording and summary surface; the later auto-approval pilot
  remains a separate, operator-gated phase that is not part of this change.

- Issue or revoke a coordination mandate from the dashboard surface with your PIN —
  agent credentials alone cannot do either.
- Agents check intended agent-to-agent actions against the mandate and get an
  allow-or-deny answer with the reason; denials are the default with no mandate.
- Review every mandate decision in a chained, tamper-evident audit trail, including
  whether each entry's chain verifies.
- Maturity: stable for the gate, store, and audit; conditioned authorities (objective
  real-state gates for riskier actions) ship deny-safe and unused by the first mandate.

- Internal: order-independent parity windowing (per-report fingerprint,
  terminal-status, recurrence/cycling counts) with a conservative
  cleared-or-blocked gate verdict; survives restarts.
- Maturity: internal migration tooling, dormant until the dual-forward phase.

- Internal: integrity-safe import core + a guarded store wrapper that makes
  pre-cutover and governance-noted clusters structurally immutable.
- Maturity: internal migration tooling, dormant until the import phase.

- SessionManager can record the live pane working directory for running sessions when the development-agent-gated feature is enabled.
- A resumed respawn receives a `[BUILD-CONTEXT RESTORE]` continuation note only when the prior cwd was a fresh, existing agent worktree.
- The sidecar state write is crash-safe through the state layer's temp-file plus rename path.
