Resume, trace, archive, and release handoff

This workflow continues from Evidence review and reconciliation after a task, milestone, or larger planning run pauses or reaches a reviewed handoff. It shows operators, implementing agents, reviewers, and release owners how to recover from repository evidence instead of private memory, and how to preserve provenance when links or artifacts change.

Resume from durable evidence

Start by re-resolving the effective workspace and selected artifact. Inspect git status, the task definition, paired implementation summary, milestone reconciliation, and the last completed lifecycle gate. Then rerun the matching read-only readiness, review, or validation command. Do not infer completion from chat history, a stale terminal, or a status field whose body evidence is incomplete.

resume inspect and resume revalidate read a named local resume capsule and compare it with current repository evidence. They do not select work, repair artifacts, or advance status. resume save creates or replaces a capsule; resume clear removes one; and resume cleanup clears stale or expired capsule state. A capsule is a convenience pointer, not the source of truth. On conflict, trust the current repository artifacts and stop before writing.

An implementing agent resumes at the last proven gate: rerun readiness before untouched implementation, rerun declared validation after partial edits, rebuild and review a changed implementation summary, or reopen reconciliation after a build. Preserve declared task order and report an ambiguous or missing handoff as blocked.

Resume from retained transaction evidence

Lifecycle continuation and operational transaction recovery are different lanes. A resume capsule can point to a task or run gate, but it cannot prove that an interrupted multi-path write is safe to retry. When a mutation reports incomplete, a retained transaction path, cleanup errors, or a recovery fingerprint, stop lifecycle writes and inspect that exact transaction first.

Preserve .day-shift/state/write.lock, .day-shift/state/transactions/<transaction-id>/, staged bytes, the durable migration or promotion record, and any .day-shift/state/recovery-records/ receipt. A live lock means wait. Expiry alone does not authorize deletion or takeover. A diverged target, stale fingerprint, missing manifest, or missing staged evidence means recovery must stop without guessing.

Continue only through the owning command’s exact-fingerprint roll-forward or restore lane. Structural migration recovery is documented in Migrate an existing workspace; shared lock, staging, receipt, and cleanup behavior is documented in Transaction and operational recovery. After recovery reports verified terminal evidence, rerun the lifecycle’s read-only status or review gate before continuing.

Derive continuation without hidden writes

Use resume inspect to compare a capsule with the selected artifact, workflow explain to recover the workflow and prompt handoff, and planning next-action to derive the likely next planning or review boundary. All three are read-only guidance. They do not select work, authorize implementation, repair metadata, create attempts, accept reconciliation, or close a task.

Continue from the last durable record whose revision and receipt are still current. A stale readiness review routes back to readiness; a changed Runtime target routes back to validation; a changed summary routes back to summary review; and a changed reconciliation routes back to reconciliation review. Apply deterministic administrative status only through a separately previewed metadata sync-status-from-review transaction.

Keep trace links explainable

Trace links connect specifications, slice, phase, milestone, task, implementation summary, reconciliation, and downstream evidence. validation links-check, planning validation, link disposition list, link disposition show, and link disposition preview are read-only. Their findings can identify a missing, stale, retired, deleted, migrated, or malformed relationship, but cannot rewrite a reference or choose its replacement.

Use link materialize --dry-run after a planning scaffold or overview-body change. Run link materialize --write only when the preview names changes inside the selected artifact and the current workflow authorizes that body-link write. Materialization makes an already valid relationship clickable; it does not change lineage or lifecycle disposition.

When an artifact is intentionally retired, deleted, or migrated, record that decision separately with link disposition add or link disposition update. link disposition delete removes a disposition record and therefore requires the same explicit ownership. link disposition apply is limited to migrated dispositions with a known replacement; it must not apply retired or deleted dispositions, infer a target, or become a fallback for malformed storage. Preview affected links first and preserve the decision rationale and replacement provenance.

Archive without erasing history

Archival retains evidence that no longer participates in active selection. A spec archive operation updates the registry through its supported write surface; it is not equivalent to deleting the source or silently breaking downstream references. Before archival, confirm completed implementation and reconciliation evidence, inspect inbound trace links, record the archive reason and successor when one exists, and preview any migrated disposition.

Deletion is a different decision. It needs an explicit disposition, affected-path accounting, and a recovery plan. Never recommend deleting or manually rearranging .day-shift/ to recover a stale or partially migrated workspace. Use read-only diagnosis and migration preview first, then a separately authorized apply path.

Recover safely from disagreement

If a capsule, metadata field, body link, generated archive, and repository tree disagree, stop normal writes. Re-open the selected artifacts, run scoped validation, and classify the conflict. Fresh evidence may justify a narrow supported update; stale or partially upgraded workspace evidence routes through doctor and migration preview. Wrong-family, ambiguous, inconsistent, under-specified, and lossy updates remain blocking no-write failures.

Recovery should be reversible and selected-artifact scoped. Record the failed command, expected evidence, substitute inspection, residual risk, and next validation. A review or validation recommendation remains guidance until an operator selects the matching update, materialize, disposition, migration, archive, or release write.

Prepare the release handoff

The reviewer confirms that summaries and reconciliation are completed, non-placeholder, validation-backed, and explicit about accepted residuals. The implementing agent supplies changed paths, executable evidence, deviations, rollback notes, and unresolved ownership. The operator confirms repository and workspace health. Only then does the release owner select the release workflow.

release check checks local release inputs and staged output without publishing a release. release build generates local staging, archives, checksums, manifest, notes, and installer assets; run release check after a successful build. Release retention and cleanup mutate generated output according to their explicit boundaries. These writes do not publish, approve, sign, or announce a release by implication.

For local engineering output from an uncommitted worktree, release build --dirty --version <version> writes to dirty-release/<version>/ by default. It is deliberately separate from release/<version>/, does not qualify an immutable candidate, and must not be copied into website downloads or represented as a public version. A public handoff requires a clean, independently qualified candidate and separately authorized publication.

A complete handoff names the reviewed reconciliation, source revision, release version or candidate identity, generated manifest and checksums, validation results, accepted residuals, rollback path, and owner of the next action. The release owner revalidates that evidence before any external mutation.

Role-based scenarios

Operator returns after an interrupted session

Resolve the workspace, inspect the capsule and repository tree, reopen the selected task and summary, and rerun the current gate. If the capsule conflicts with the tree, treat it as stale and clear or replace it only through the explicit resume command after repository evidence selects the correct handoff.

Agent finds a moved planning artifact

Run links-check and disposition preview. If the move has a known replacement, record or update a migrated disposition, preview affected links, and apply only that migrated record through the explicit write. If the artifact was retired or deleted, preserve that disposition as history and do not invent a replacement.

Reviewer archives completed planning evidence

Confirm reconciliation and parent review evidence, inspect inbound relationships, and preserve the archive rationale. Archive through the owning registry or release surface. Keep retained evidence readable and route stale links through explicit dispositions rather than filesystem deletion.

Release owner receives a candidate

Read the reconciliation and handoff manifest, run release validation, verify checksums and residual-risk ownership, and generate or inspect local output. External publication remains a separate authorized step; a successful validation or archive build is not release approval.

The lifecycle is complete when another qualified owner can reconstruct what was selected, what changed, which evidence was accepted, how links evolved, what was archived, and which explicit action comes next. Troubleshooting begins in Guides; command syntax stays in Reference.

Recover a stale Structured specification revision

A Structured overview is bound to the canonical specification path and the exact reviewed revision recorded when the overview was created. work review --overview <path> compares that binding with the current specification. A mismatch is reported as stale-revision evidence through a read-only result: review exits without rewriting the overview, copying new requirements into planning, moving the specification, or accepting the changed source.

Recover by recertifying the changed canonical specification and creating fresh revision-bound Structured work. The existing overview remains evidence for its recorded revision; do not hand-edit it to point at new bytes.

CLI=day-shift
SPEC=.day-shift/specs/31-structured-evaluation-source/structured-evaluation-source.md
OVERVIEW=.day-shift/planning/structured/31-structured-evaluation/overview.md

$CLI work review \
  --overview "$OVERVIEW" \
  --format json

$CLI spec review \
  --spec "$SPEC" \
  --reviewed-by feature-owner \
  --reviewed-at 2026-08-01T18:00:00Z \
  --format json \
  > .day-shift/runs/run-structured-recovery/spec-review.json

$CLI spec disposition \
  --spec "$SPEC" \
  --planning-readiness ready \
  --review-result .day-shift/runs/run-structured-recovery/spec-review.json \
  --recorded-by feature-owner \
  --recorded-at 2026-08-01T18:01:00Z \
  --dry-run

$CLI spec disposition \
  --spec "$SPEC" \
  --planning-readiness ready \
  --review-result .day-shift/runs/run-structured-recovery/spec-review.json \
  --recorded-by feature-owner \
  --recorded-at 2026-08-01T18:01:00Z

$CLI work create \
  --spec "$SPEC" \
  --work-id structured-evaluation-recertified \
  --implementation-order next \
  --dry-run

$CLI work create \
  --spec "$SPEC" \
  --work-id structured-evaluation-recertified \
  --implementation-order next

Save the complete spec review in the run evidence directory before disposition. Inspect the disposition and work-create previews before applying them. If recertification is blocked, keep both the changed specification and the prior overview intact, record the blocker, and stop; no recovery command may guess a revision, reuse stale review evidence, or manufacture planning readiness.