# Downstream Upgrade Playbook

Owner: `PM` by default

Use this playbook when a downstream project wants to adopt a newer version of
the minion template without overwriting project-specific state.

For first-time setup, use `docs/downstream-onboarding-playbook.md` instead.

## Goal

Make downstream upgrades reviewable by comparing:

1. the currently approved vendored template
2. the incoming template version
3. the live downstream files

## Recommended Paths

- current approved template snapshot: `.minions-template/`
- incoming candidate snapshot during upgrade: `.minions-template.next/`

If the downstream repo does not already keep a vendored template snapshot, the
first upgrade should establish one that matches the repo's current base-template
version before attempting a larger template jump. If the repo is truly new,
run the onboarding playbook first.

Both snapshot paths should contain export-ready copies of the template, not full
Git clones.

- exclude `.git/`
- exclude files marked `do-not-export` in `docs/export-manifest.md`

## Ownership

- `PM` owns the upgrade packet, merge order, and Operator-facing decision
  summary
- `AM` reviews architecture and design changes that affect role boundaries,
  plans, or shared structure
- `SM` reviews new guardrails, security expectations, and trust-boundary changes
- `CM` applies downstream file merges that require implementation-oriented
  technical judgment
- `OM-Test` / `OM` review deployment or runtime workflow changes when relevant
- `Operator` approves the downstream adoption decision

## Upgrade Workflow

1. Confirm the downstream repo's current base-template version in
   `minion-version.md`.
2. Stage the current approved export-ready template snapshot in
   `.minions-template/` if it is not already present.
3. Import the incoming template version into `.minions-template.next/` using the
   same export-ready filtering rules.
4. Diff `.minions-template/` against `.minions-template.next/` to see what the
   template changed.
5. Use `docs/export-manifest.md` to classify each affected live file as:
   - `template-replace`
   - `manual-merge`
   - `downstream-owned`
   - `do-not-export`
6. Apply `template-replace` files first, while reviewing any intentional local
   downstream divergence before overwriting.
7. Manually merge files such as `MEMORY.md`, `INIT.md`,
   `docs/operator-onboarding-checklist.md`, and `minion-version.md`.
8. Preserve `downstream-owned` files unless the Operator explicitly directs a
   project-specific rewrite.
9. Record the upgrade packet in `minions/mail/`, mirror the same-day summary
   into `minions/chat/`, and update the downstream `CHANGELOG.md`.
10. After approval, replace `.minions-template/` with the new approved snapshot
   and remove `.minions-template.next/`.
11. Update the base-template portion of `minion-version.md` only after the live
   downstream files and vendored snapshot are aligned.

## Manual-Merge Guidance

### `MEMORY.md`

- preserve project-specific facts, constraints, environments, and operating
  history
- merge new template guardrails, role definitions, and workflow rules
- if the file is later split into template-managed and project-managed sections,
  restrict template upgrades to the template-managed sections

### `INIT.md`

- preserve the downstream project's onboarding framing and project-specific
  references
- merge new baseline workflow expectations, role sets, and handoff rules

### `docs/operator-onboarding-checklist.md`

- preserve completed downstream decisions
- merge new template checklist items so future onboarding reviews stay current

### `minion-version.md`

- preserve the downstream version suffix
- update the base-template version only after the upgrade is actually complete

## Minimum PM Upgrade Packet

- current downstream version
- target template version
- files replaced from template
- files manually merged
- files intentionally left downstream-owned
- Operator decision needed
- follow-up owners and verification steps