Promote planning work

Promotion changes planning organization when the current level no longer fits. It does not change the specification owner, invent new implementation scope, or treat a review as write authorization. The shipped paths are Basic to Structured, Basic to Governed, and Structured to Governed. Demotion is not shipped.

Choose the shipped path

Source	Destination	Status	Command
Basic	Structured	Shipped	task promote
Basic	Governed	Shipped	task promote
Structured	Governed	Shipped	work promote
Structured or Governed	Lower level	Unsupported	No callable demotion command

Use Basic to Structured when one independent pair has grown into coordinated direct tasks. Use Basic to Governed when the destination hierarchy is already known and reconciliation is required. Use Structured to Governed when direct-task coordination needs phases, milestones, and milestone reconciliation.

Preview before apply

Planning mode is read-only by default; --dry-run makes that posture explicit. The preview reports a plan id, exact source content revisions, destination-presence conditions, metadata changes, task mappings, collisions, ambiguities, and affected paths.

$CLI task promote --task-definition .day-shift/planning/basic/tasks/01-example/task-definition.md --to structured --work-id coordinated-example --implementation-order next --spec .day-shift/specs/example/example.md --dry-run --format json

For a Basic to Governed destination, also provide the numbered slice order, slice slug, ordered phase, and ordered milestone. For Structured to Governed, provide one --task-mapping <task-id=milestone-slug> for every direct task. Missing, duplicate, contradictory, or colliding mappings fail without writes.

Apply the exact plan

Apply requires the unchanged planning inputs plus the exact returned plan id, actor, and reason. The command stages a transaction, creates the planned parents and destination pairs, records the promotion, then retires the source pair or complete Structured work only after replacement succeeds.

$CLI task promote <unchanged-preview-inputs> --apply --plan-id <preview-plan-id> --actor <identity> --reason <reason> --format json

A stale source revision, raced destination, wrong plan id, or contradictory preview/apply flags fails closed. Refresh the preview from current repository state; never edit expected revisions or reconstruct destination files by hand.

Preserve identity and evidence

Promotion preserves each semantic task id, task body, paired implementation-summary body, dependencies, specification links, agent mode, evidence profile, attempt records, runtime-attribution baselines, validation results, deviations, waivers, blockers, and review evidence. It rewrites only level-specific organization fields and parent links needed by the destination.

Readiness evidence is rebound only when its exact source revision can be translated to the rewritten destination bytes. Stale or invalid readiness receipts are rejected. Promotion does not open an attempt, run validation, accept a review, close a task, or reconcile a milestone automatically.

Recover an incomplete transaction

If apply reports incomplete, partial, cleanup errors, or retained operational state, stop. Use the reported transaction id and current inspection fingerprint with the callable roll-forward or restore recovery action. A stale fingerprint is rejected without writes.

$CLI task promote --recover roll-forward --transaction-id <transaction-id> --evidence-fingerprint <inspection-fingerprint> --actor <identity> --reason <reason> --format json

Recovery is mutually exclusive with planning inputs. Follow the exact action reported by current inspection and retain the promotion and recovery records as evidence. See Promotion and evidence preservation for the frozen examples and failure checklist.

A stale inspection fingerprint returns PROMOTION_RECOVERY_EVIDENCE_MISMATCH without writes; obtain a fresh inspection instead of retrying stale recovery authorization.

Unsupported boundaries

There is no shipped Structured-to-Basic, Governed-to-Structured, or Governed-to-Basic command. Review surfaces remain read-only and never promote, demote, remap, or otherwise mutate lifecycle state automatically. If the desired direction is not in the shipped matrix, preserve current artifacts and plan explicit follow-up work instead of presenting an unshipped migration as available.