Upgrade prompt and template customizations

An executable upgrade does not merge repository customization. Day Shift keeps package-owned defaults, the latest fallback, user prompts, workspace templates, generated context or materialized output, and authored planning artifacts in separate ownership lanes. Upgrade those lanes deliberately; never bulk-copy one over another.

Start with a clean or saved repository diff and the exact installed release version. Use Prompts and templates for shipped identities and versions, Customize prompts and templates for selected writes, and Workspace initialization for repeat-init behavior.

Establish the three merge inputs

A body merge needs three recoverable inputs:

1. Base: the prior packaged default that the customization began from, or a version-control revision that records that baseline.
2. Ours: the current workspace-owned file in .day-shift/prompts/user/ or .day-shift/templates/.
3. Theirs: the selected release’s packaged default, identified by its manifest entry and version evidence.

Save all three outside generated output directories before editing. If the base is unknown, do not guess a three-way merge. Preserve ours, inspect the new default as comparison evidence, and make a reviewed targeted edit or keep the customization unchanged.

prompt diff, prompt list/show, templates list, workflow explain, doctor, review, validation, and every dry run are read-only evidence. They can identify sources, versions, routing, compatibility, and proposed changes; they do not merge bodies, repair manifests, refresh outputs, or authorize a write.

Classify drift before choosing a write

Drift lane	Evidence to compare	Safe interpretation
Prompt source	Resolved user/latest/packaged layer, prompt identity, prompt_version, manifest version, and body diff	A user copy winning precedence is customization, not automatically stale. Version or body differences require review against the saved base.
Template source	Manifest path, class, template_version, entry version, placeholders, destination, and workspace file	Missing files, missing versions, or source differences are inventory findings. They do not prove that a generated destination should be overwritten.
Manifest identity or routing	Entry identity, family/entry versions, artifact type, destination, and usage	Ambiguous, malformed, or contradictory identity is a blocking no-write condition. Repair the selected manifest/source deliberately before materializing.
Generated output	Source identity and version used, rendered inputs, destination diff, and authored changes	Staleness is an output concern. Regenerate only from the selected source and explicit inputs; never promote output back into a source template.
Workspace schema	day-shift agent, scoped doctor, and migration preview evidence	Incompatible, malformed, or partially upgraded workspace state blocks normal authoring writes and routes to supported migration.

Choose the narrowest safe procedure

Procedure	Prerequisites and evidence	Mutation and expected output	Failure and recovery
Compatible repeat init	Healthy workspace, saved diff, and init --dry-run plan	Ordinary init fills missing managed assets and preserves divergent files.	Unexpected overwrite plans are a stop condition. Do not add --force until every replacement is intentional.
Targeted body merge	Known base, ours, theirs, stable identity, and reviewed diff	Edit only the workspace-owned prompt or template; retain intentional local changes and adopt selected upstream changes.	Conflicts, missing base, or unclear identity remain no-write review work. Restore ours from version control if an edit goes wrong.
Metadata update	One existing user prompt or workspace template and supported --field values	prompt update or template update changes supported front matter atomically. It does not merge bodies.	Wrong-family, malformed, unknown, ambiguous, or conflicting input fails without a partial write. Correct the explicit request and retry.
Intentional default reset	Saved customization and reviewed init --dry-run --force overwrite list	Force replaces eligible divergent managed defaults with packaged content. It is a reset, not a merge.	Restore ours from the saved diff and reapply reviewed customization after an interrupted or mistaken reset. Protected spec registration remains user-owned.
Manifest repair	Exact shipped/workspace identity and validation evidence	Make a reviewed targeted manifest or source correction, then rerun templates list.	Do not infer a replacement path or destination from a warning. Ambiguity remains blocking until an operator selects the identity.
Output refresh	Valid source template, explicit destination, complete placeholders, and template materialize --dry-run	Non-dry-run materialization writes only the selected generated destination; --force is required for an intentional replacement.	Missing placeholders, invalid routing, or an existing destination fails without writing. Preserve authored output or reconcile its diff before force.
Workspace migration	doctor or agent orientation reports incompatible or partially upgraded state; complete migration preview is reviewable	workspace migrate applies only the supported, explicitly confirmed metadata transition.	A failed or incomplete preview blocks apply. Never manually move or delete .day-shift/ to simulate completion.

After every write, rerun the matching evidence command and inspect the repository diff. A clean validation result describes the selected state; it does not prove that discarded customization was acceptable.

Failure and recovery matrix

Failure evidence	Recovery route
Prior base cannot be recovered	Keep the workspace copy, compare it with the new default, and perform a conservative reviewed edit. Record that a true three-way merge was unavailable.
Prompt or template identity is ambiguous	Stop. Resolve the manifest path and selected source layer before any edit, update, force, or materialization.
Front matter or manifest is malformed	Preserve the file, use parser/validation findings to make one targeted correction, and rerun read-only inventory. Do not fall back to a guessed partial update.
Body merge conflicts	Keep base, ours, and theirs available; resolve each conflict in the workspace source, then validate identity, variables, and lifecycle wording.
Force was interrupted or wrong	Stop subsequent writes, inspect version control and the dry-run plan, restore user-owned files, then repeat comparison before retrying.
Materialized output is stale	Reconstruct its source identity and inputs, preview the explicit destination, and regenerate only after authored destination changes are preserved or reconciled.
Workspace is incompatible, malformed, or partially upgraded	Stop normal planning and customization writes. Run scoped diagnosis, preview the complete supported migration, and apply only with its explicit confirmation contract.

Use disposable temporary repositories for rehearsals. Initialize a fresh target, repeat init after adding a distinctive customization marker, introduce controlled stale version evidence, and simulate malformed or partial workspace metadata. Assert that evidence commands remain no-write and that ordinary init preserves the marker. Never test upgrade recovery against the operator’s real .day-shift/ tree.

Completion check

An upgrade is complete only when selected workspace sources retain intended customization, their identities and versions are reviewable, generated outputs are either intentionally refreshed or explicitly retained, scoped health checks no longer report compatibility blockers, and the final repository diff contains no unexplained replacement. Keep the saved baseline until that review is complete.