# Change Request CR-010 — Inherited Veteran Pilot and Profit-Share Pay

> **Numbering note (added when implemented):** this request arrived titled "CR-007 — Inherited Veteran Pilot and Profit-Share Pay" for "Phase 10G", applying to "CR-001 through CR-006". CR-007 to CR-009 and Phases 10G–10I already existed, so it is stored as **CR-010** and done as **Phase 10J**: every "10G.n" below means **10J.n**. Decision 0.5.12 is replaced in place; the new 0.5.51 and 0.5.52 are recorded as **0.5.69 Deduction order** and **0.5.70 Veteran pilot** (0.5.51–0.5.68 were in use). "CR-001 decision 0.5.24" (the loan) is plan §0.5.32 in this repo. "CR-001 through CR-006" means the build as it stands (CR-001 to CR-009).

**Project:** Deadhead: Space Freight Tycoon
**Applies to:** a build with Phases 1–10 and CR-001 through CR-006 complete
**Do this:** as **Phase 10G**, after Phase 10F and before Phase 11
**Related docs:** `implementation-plan.md`, `change-request-faster-start.md` (CR-001), `change-request-pilot-rest.md` (CR-004), `game-design-document.md`, `DECISIONS.md`

---

## 1. Why

Two related changes to pilots:

1. **The deal comes with a veteran pilot.** The player takes over the retiring owner's business, so his last hire comes with it. Today, when the avatar must rest, the player's only ship sits idle. With a second pilot at the Earth HQ, the player can swap crews and keep flying, which teaches the rest-and-swap system in the first session. The veteran has a skill the avatar lacks (Heavy Cargo 1), so choosing who flies is a real decision.
2. **Hired pilots earn a share of profit instead of a flat fee.** A flat per-delivery fee can eat most of a cheap Moon run, or more once fuel is counted. A share of profit (payout minus fuel) guarantees the business always keeps the larger share of a profitable job and never pays a pilot on a losing one.

## 2. How it works

### The veteran
| Rule | Detail |
|---|---|
| When | Created when the player accepts the CR-001 deal. |
| Where | At Earth, unassigned. The avatar crews the Courier as before. |
| Who | A fixed name and short bio from content (for example "Rosa Kell, Halvorsen's pilot for twelve years"). |
| Level | Level 2, with one skill point already spent on Heavy Cargo (Heavy Cargo 1) and the remaining earned points unspent. |
| Rules | Same as any hired pilot: profit-share pay, duty and rest, assign and unassign only at a bay. |

### Profit-share pay
`pilot pay = max(0, payout − fuel cost) × pilot profit share`

| Case | Pilot pay |
|---|---|
| Hired pilot, profitable contract | Profit share of (payout − fuel) |
| Hired pilot, fuel ≥ payout | 0 |
| Avatar | 0 (exempt) |
| Deadhead or tutorial run | 0 |

Example (default share 0.25): payout 400 cr, fuel 150 cr → pilot gets 62.5 cr, business keeps 187.5 cr before loan repayment.

Order of deductions on resolution: payout − pilot pay − loan repayment (CR-001 decision 0.5.24 applies to what remains after pilot pay). Fuel was already charged at dispatch.

## 3. Rules for this change

- All rules in `implementation-plan.md` §0.1 apply: steps in order, one commit per step, each step's test must pass, `packages/sim` stays pure, all numbers and names live in `packages/content`.
- Credits round the same way they already do elsewhere; use that rounding for pilot pay and say so in `DECISIONS.md`.
- Resetting the dev and test databases is fine. Schema migrations are still required if any are needed.
- Update existing tests whose expectations change. Update `architecture.md` for schema or API changes and `progress.md` after every step.
- Stop for the user's review at the end of Phase 10G.

## 4. Decisions

Record these in `DECISIONS.md` and `implementation-plan.md` §0.5.

- **0.5.12 (replaced) Pilot pay.** Hired pilots earn `max(0, payout − fuel cost) × pilot profit share` per contract delivery. The avatar is exempt. Deadheads and tutorial runs pay nothing.
- **0.5.51 Deduction order.** On resolution: pilot pay is taken from the payout first; loan repayment (0.5.24) is calculated on what remains.
- **0.5.52 Veteran pilot.** Accepting the deal also creates the veteran per §2. The veteran is a normal hired pilot in every respect except how they were acquired.
- **CR-001 goal change.** Goal 4 "Hire your first pilot" becomes "Fly a contract with [veteran's name]".
- **CR-001 timing target change.** "Hire first pilot: 30–45 minutes" becomes "Buy a second ship: 30–45 minutes".

## 5. Steps — Phase 10G

### Step 10G.1 — Content: config and veteran
- Replace the GameConfig field "pilot pay per delivery (flat fee)" with "pilot profit share" (default 0.25, must be between 0 and 1).
- Add a veteran pilot entry: name, short bio line, starting level (2), and starting skill allocation (Heavy Cargo 1).
- **Test:** Config validates; the profit share is between 0 and 1. The veteran's starting skill allocation does not exceed the skill points a level-2 pilot has. The veteran's skill references an existing skill.
- **Amended by CR-013:** The veteran's starting skill is Expensive Cargo 1 (Step 10M.1).

### Step 10G.2 — Sim: profit-share pay
- Replace the flat fee in dispatch resolution with the profit-share formula (decision 0.5.12) and apply the deduction order (decision 0.5.51).
- **Test:** A hired pilot on a 400 cr payout with 150 cr fuel earns 62.5 cr (with the project's rounding). Fuel greater than or equal to payout gives zero pilot pay. The avatar earns zero. A deadhead and a tutorial run earn zero. With a loan balance, repayment is calculated on payout minus pilot pay. Credits added + pilot pay + loan repayment = payout, for a range of inputs. Update the Step 3.17 tests that assumed a flat fee.

### Step 10G.3 — Sim: goal change
- Change goal 4 in the onboarding goals (CR-001 Step 10A.5) to "Fly a contract with the veteran": complete when any contract delivered by the veteran has resolved.
- **Test:** The goal is incomplete when only the avatar has delivered and complete after one resolved contract flown by the veteran. A deadhead by the veteran does not complete it.
- **Amended by CR-013:** Goal 4 is now "Complete a Priority contract", by any pilot (Step 10M.2).

### Step 10G.4 — Server: veteran on the deal
- Accepting the deal (CR-001 Step 10A.8) also creates the veteran per §2, in the same transaction.
- **Test:** After accepting, state has exactly two pilots at Earth: the avatar crewing the Courier, and the veteran unassigned at level 2 with Heavy Cargo 1 and the correct number of unspent skill points. The veteran is not exempt from pilot pay. A failed or repeated accept creates no veteran. When the avatar must rest at Earth, the avatar can be unassigned and the veteran assigned to the Courier and dispatched immediately.
- **Amended by CR-013:** The veteran starts crewing the deal's Clipper, not unassigned (Step 10M.3).

### Step 10G.5 — Client: deal modal and pilot card
- The deal modal (CR-001 Step 10A.13) lists the veteran by name with their bio line, for example "…and Rosa Kell, who's flown for me for twelve years."
- The veteran's card on the Pilots screen shows the bio line.
- **Test:** Component test: the modal shows the veteran's name and bio from content; the Pilots screen shows the veteran's bio, level, and Heavy Cargo 1.

### Step 10G.6 — Client: pilot share in dispatch and summaries
- The dispatch sheet shows a "Pilot share" line between fuel and net profit for hired pilots, and no line for the avatar. Net profit accounts for it.
- Delivery summaries show the pilot's share as its own line when it's above zero.
- **Test:** Component test: for a hired pilot the sheet shows the share and a net profit matching the sim; for the avatar there's no share line. A summary for a hired pilot's delivery shows the share line.

### Step 10G.7 — Plan amendments and regression
- Apply the amendments in §6 to `implementation-plan.md` and CR-001's text.
- Run the full suite.
- **Test:** CI is green. Manual check: on a fresh account, accept the deal and confirm the veteran is at Earth; fly the avatar until mandatory rest at Earth; swap in the veteran, take a Heavy contract the avatar couldn't, and confirm the summary shows the pilot share and goal 4 becomes claimable.
- **Amended by CR-013:** The rest-and-swap manual check is replaced by CR-013's: accept the deal on a fresh account, dispatch the Courier and the Clipper at the same time, and complete a Priority contract with the Clipper to unlock goal 4 (Step 10M.5).

## 6. Amendments

| Where | Change |
|---|---|
| Plan 0.5.12 | Replaced by profit-share pay (10G.2). |
| Plan 0.5 | Add 0.5.51 and 0.5.52. |
| Plan 2.1 | Config field change (10G.1). |
| Plan 3.17 | Profit-share formula and deduction order (10G.2). |
| Plan 9.5 | Pilot share line in the dispatch sheet (10G.6). |
| Plan 12.1 | Replace "first pilot hired between 30 and 45 minutes" with "second ship bought between 30 and 45 minutes". Add a check that the veteran flies at least one contract in the first session. Re-check all targets with profit-share pay; adjust content values, not thresholds. |
| CR-001 10A.5 | Goal 4 changed (10G.3). |
| CR-001 10A.8 | Deal also creates the veteran (10G.4). |
| CR-001 10A.13 | Deal modal lists the veteran (10G.5). |
| CR-001 §2 targets | "Hire first pilot" target replaced as above. |

## 7. Out of scope

Pay share that scales with pilot level, salaries, pilot morale or loyalty, pilots leaving or being poached, additional inherited assets, and anything else in `implementation-plan.md` §0.3.