Promotion and evidence preservation

Use this guide when a reviewed planning-level decision is ready to become an explicit repository change. The reproducible fixture at apps/docs/content-workflows/governed-promotion-examples.json is captured from the current repository CLI in disposable workspaces; it labels every upward path shipped, records no-write failures, and proves exact-fingerprint recovery without leaking fixture paths.

Promotion status matrix

Path	Status	Preview	Apply
Basic to Structured	Shipped	task promote, read-only by default	Exact plan id, actor, and reason
Basic to Governed	Shipped	task promote, explicit hierarchy	Exact plan id, actor, and reason
Structured to Governed	Shipped	work promote, complete task mapping	Exact plan id, actor, and reason
Any demotion	Unsupported	No callable descriptor	No apply or recovery lane

The two callable descriptors use applies-transaction mutation posture. Neither descriptor authorizes automatic promotion from review, implicit destination selection, or demotion.

Evidence to inspect in the preview

Before apply, confirm all of the following:

• Source task or overview path and every content revision match the repository you reviewed.
• The destination order, parent paths, task ids, and task-to-milestone mappings are complete and collision-free.
• changedPaths is empty and readOnly is true in planning mode.
• Destination-presence conditions cover every planned parent and task pair.
• Metadata changes are structural only: level, numbered position, and canonical parent links.
• Recovery guidance requires a refreshed preview when source or destination state changes.

Incomplete Structured mappings return PROMOTION_PLANNING_INCOMPLETE_MAPPING with no-writes. Stale apply returns PROMOTION_APPLICATION_PLAN_MISMATCH with no-writes. Treat both as evidence to correct inputs or refresh the plan, not permission to patch generated paths.

Evidence preserved across apply

Task identity is semantic, not its directory prefix. Apply preserves the task id and the authored bodies of task-definition.md and implementation-summary.md. That boundary carries dependencies, acceptance criteria, attempts, baselines, validation results, deviations, waivers, blockers, and review history into the destination pair while rebinding canonical parent paths.

Specifications remain under .day-shift/specs/; promotion references them and never moves or copies them. Basic apply retires exactly one source pair after destination commit. Structured apply retires the overview and every mapped pair only after the complete Governed destination commits.

After apply, compare the promotion record, destination paths, retired paths, created parent paths, write outcome, and transaction id with the reviewed plan. Then resume the ordinary lifecycle at the destination’s current state. Do not infer a new attempt, acceptance, closure, or reconciliation result.

Recovery checklist

An interrupted transaction may have staged files, partial replacement, committed canonical output with cleanup errors, or retained operational evidence. Use this sequence:

1. Stop ordinary planning and implementation writes.
2. Keep the reported transaction directory and promotion evidence.
3. Inspect current recovery output and select its exact roll-forward or restore action.
4. Supply the exact current evidence fingerprint, transaction id, actor, and reason.
5. Reinspect canonical source and destination postconditions after recovery.

A stale fingerprint returns PROMOTION_RECOVERY_EVIDENCE_MISMATCH with no-writes. Never guess a fingerprint, combine recovery with planning inputs, delete retained transaction state, or manually move source and destination pairs.

Boundaries that remain unsupported

Demotion is unsupported. A review does not automatically promote or alter lifecycle state. Promotion does not manufacture planning readiness, repair stale evidence, choose missing mappings, run implementation, or accept downstream reconciliation. When those decisions are needed, use their separate review and write-capable lifecycle commands after promotion completes.

For command sequencing, see Promote planning work and the core workflow command reference.