From ad1b8c76d94622b3f71aae2180d45eb623c5897b Mon Sep 17 00:00:00 2001 From: fireshaper Date: Sat, 10 Oct 2026 20:28:29 -0400 Subject: [PATCH] Record CR-019: only show jobs the fleet can complete (Phase 19) Received as CR-018 for Phase 18; renumbered. Decisions 0.5.114-0.5.117. Co-Authored-By: Claude Opus 5.5 --- DECISIONS.md | 5 + .../CR-019-completable-boards.md | 115 ++++++++++++++++++ memory-bank/implementation-plan.md | 10 ++ memory-bank/progress.md | 10 ++ 4 files changed, 140 insertions(+) create mode 100644 memory-bank/change-requests/CR-019-completable-boards.md diff --git a/DECISIONS.md b/DECISIONS.md index fc94cd7..29eb2bf 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -1615,3 +1615,8 @@ Implementation decisions not spelled out in `memory-bank/implementation-plan.md` ## Step 18.5 - **The e2e flying helper refuels before every trip**, as a Manual player would. It had relied on Auto top-up, so e2e 12.6 failed on the Step 18.3 and 18.4 commits; the unit suites didn't cover it. + +## CR-019 recorded (Only Show Jobs the Fleet Can Complete) + +- **Numbering:** received as "CR-018 — Only Show Jobs the Fleet Can Complete" for "Phase 18"; stored as **CR-019**, built as **Phase 19** (its 18.n = 19.n). Its decisions CR-018.D1–D4 are **0.5.114–0.5.117**. Its references: CR-005 → CR-007 (steps 10E.n → 10G.n), CR-006 → CR-009, CR-009 → CR-012, CR-011 → CR-014, CR-014 → CR-015; CR-002, CR-004 and plan steps 3.9, 3.11, 9.4 are unchanged. +- **It replaces this repo's CR-006 board rules**, which its numbering doesn't know about: the open and preview slots of decision 0.5.52 and the weight warning of 0.5.53. diff --git a/memory-bank/change-requests/CR-019-completable-boards.md b/memory-bank/change-requests/CR-019-completable-boards.md new file mode 100644 index 0000000..d6576f3 --- /dev/null +++ b/memory-bank/change-requests/CR-019-completable-boards.md @@ -0,0 +1,115 @@ +# Change Request CR-019 — Only Show Jobs the Fleet Can Complete + +> **Numbering note (added when recorded):** this request arrived titled "CR-018 — Only Show Jobs the Fleet Can Complete" for "Phase 18". CR-018 (fuel tuning) and Phase 18 already existed, so it is stored as **CR-019** and done as **Phase 19**: every "18.n" below means **19.n**. Its references map to this repo as: "Phase 13 and CR-001 through CR-017" = Phase 13 and **CR-001 to CR-018**; "CR-002 open markets" and "CR-004" (rest) are the same numbers; "CR-005 cargo goods" = **CR-007** (its steps 10E.n are **10G.n**, so "10E.3, 10E.8" are **10G.3, 10G.8**); "CR-006 ship upgrades" = **CR-009**; "CR-009 new ships and range" = **CR-012**; "CR-011 local-first" = **CR-014**; "CR-014 fixed map and fuel tanks" = **CR-015**. Plan steps 3.9, 3.11 and 9.4 are the same numbers. Its new decisions CR-018.D1–D4 are recorded as **0.5.114 Completable boards, 0.5.115 Qualifying fleet, 0.5.116 Permanent checks only, 0.5.117 Mid-period changes**. +> +> **On recording:** this repo already has fleet-fitted boards from its own **CR-006 "Boards That Fit Your Fleet"** (decisions **0.5.52** and **0.5.53**), which the request's numbering doesn't include. In CR-006 every band keeps a configured number of open jobs (`boardOpenSlotsPerBand`) and bands no ship can carry shrink to a preview (`boardPreviewSlots`). The contract card also highlights a mass no ship there can carry (the weight warning, 0.5.53). This CR replaces all three: boards keep only completable jobs, and permanent-problem badges go. The "HQ" in §2 is a player bay at the location. + +**Project:** Deadhead: Space Freight Tycoon +**Applies to:** a build with Phase 13 and CR-001 through CR-017 complete +**Do this:** as **Phase 18** +**Related docs:** `change-request-open-markets.md` (CR-002), `change-request-cargo-goods.md` (CR-005), `change-request-ship-upgrades.md` (CR-006), `change-request-new-ships-and-range.md` (CR-009), `change-request-local-first.md` (CR-011), `change-request-fixed-map-and-fuel-tanks.md` (CR-014), `DECISIONS.md` + +This change request is written for the local-first engine (CR-011). + +--- + +## 1. Why + +Contract boards fill up with jobs nobody in the player's fleet can take: too heavy for any ship there, Priority windows no ship can make, destinations out of range, or skill tiers no pilot has. They clutter the board and crowd out real work. From now on, **a board only offers jobs at least one of the player's ship-and-pilot pairs could take.** + +## 2. Rules + +### Which ships and pilots count +For a location's board, the **qualifying fleet** is: + +- Owned ships **at** the location (idle, resting crew, or in the shop), plus owned ships **in flight to** the location that arrive before the board period ends. +- Each such ship's assigned pilot, or any unassigned pilot at that location if the player has an HQ there (so they could be assigned). +- **If no ship qualifies, use the whole fleet:** every owned ship and pilot pair, wherever they are. This keeps boards at empty locations useful for deciding where to deadhead. + +### What "can complete" means +A job is completable if at least one qualifying pair passes every permanent check: + +| Check | Uses | +|---|---| +| Cargo fits | Ship's effective capacity (CR-006) | +| Can land | Landing class | +| In range | Full-tank reach from the job's origin (CR-014); if the origin doesn't sell fuel, the fuel on board | +| Not stranded | No-strand rule (CR-009/CR-014) | +| Fast enough | Priority window, with handling time (CR-005) | +| Skilled enough | Cargo skill tier and Long Haul requirement (CR-005, plan 3.11) | + +**Temporary conditions are ignored:** pilot resting, ship in the shop, not enough fuel on board right now (it can be refueled), and not enough credits. Those still show as reasons in the dispatch sheet. + +### Generation +- When a board is generated (first view in a period, CR-002), the generator produces candidate contracts as it does now and **keeps only completable ones** until the board is full or a maximum number of attempts is reached (default 200). A board may end up smaller than the configured size if the fleet can do very little there. +- First-contact contracts follow the same rule. +- The board stores the qualifying fleet's capabilities it was generated against, so results are deterministic and reproducible. + +### When the fleet changes mid-period +- Stored boards stay as generated, but the board view **also filters at display time**: a job that's no longer completable (for example, the only capable ship left) is hidden. +- New capability (a new ship, an upgrade, a spent skill point) shows up on the next board refresh. With 10-minute periods (the rest/board tuning), that's a short wait. + +### Cards +- Card badges for permanent problems ("TOO HEAVY", "TOO SLOW", skill too low) are removed: everything shown can be done by someone. Pairs that can't take a job are still disabled with their reason in the dispatch sheet. +- If filtering leaves a board empty: "No jobs here your fleet can take right now. New contracts in mm:ss." with the existing Rest and Deadhead options when a ship is idle there (CR-004). + +### Unchanged +- The tutorial board (always fits the loaner). +- How cargo classes, goods, Priority, and shippers are chosen (CR-005); filtering naturally shifts the mix toward what the fleet can carry. + +## 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 live in `packages/content`. +- The completability check is one pure function in `packages/sim`, reused by the generator, the display filter, and the dispatch sheet, so they never disagree. +- Save migration: stored boards from before this change are discarded and regenerate on next view. +- Update existing tests whose expectations change (board contents, card badges, the CR-005 class-mix baseline test, which should run with a "full capability" fleet fixture). Update `architecture.md` and `progress.md` as you go. +- Stop for the user's review at the end of Phase 18. + +## 4. Decisions + +Record these in `DECISIONS.md` and `implementation-plan.md` §0.5, using the next free numbers (labeled CR-018.D1–D4 here; note the mapping). + +- **CR-018.D1 Completable boards.** Boards contain only jobs at least one qualifying ship-and-pilot pair can complete, per §2. +- **CR-018.D2 Qualifying fleet.** Ships at or arriving at the location, with their pilots or assignable pilots there; the whole fleet if none. +- **CR-018.D3 Permanent checks only.** Rest, shop, fuel on board, and credits don't affect completability. +- **CR-018.D4 Mid-period changes.** Display-time filtering hides jobs that stopped being completable; new capability appears at the next refresh. + +## 5. Steps — Phase 18 + +### Step 18.1 — Sim: completability check +- Add a pure function: given a contract and a list of ship-and-pilot capability snapshots (effective stats, landing class, skills, location), return whether any pair can complete it and, per pair, the first failing permanent check. +- Add a function that builds the qualifying fleet for a location per §2. +- **Test:** One test per permanent check, each with a pair that fails only that check. A job is completable if any one pair passes. Resting, in-shop, low-fuel, and no-credit states don't change the result. A location with no ships returns the whole fleet as qualifying. + +### Step 18.2 — Sim: generation keeps only completable jobs +- The board generator takes the qualifying fleet snapshot and keeps only completable candidates, up to the board size or the attempt limit. First-contact candidates are filtered the same way. +- **Test:** Over 1,000 boards with assorted fleet fixtures, no generated contract fails the completability check for its fleet. With only a level-0 avatar in a Courier at Earth, every board is full and every job is Standard, fits the Courier, and goes to the Moon. With a fleet that can do almost nothing, generation stops at the attempt limit and returns a smaller board without error. Same inputs still give identical boards. The CR-005 class-mix test passes with a full-capability fleet fixture. + +### Step 18.3 — Engine: boards, filtering, and migration +- Board generation passes the qualifying fleet snapshot and stores it with the board. Board reads filter out jobs that are no longer completable for the current qualifying fleet. +- Save migration discards stored boards from before this change. +- **Test:** Generating a board, then selling or moving away the only ship that could take a heavy job, hides that job on the next read. Buying a bigger ship mid-period doesn't add jobs until the next period. An older save migrates with no stored boards, and boards regenerate on view. + +### Step 18.4 — Client: cards and empty state +- Remove permanent-problem badges from contract cards. Keep the dispatch sheet's per-pair reasons. +- Add the empty-board message from §2. +- **Test:** Component test: no card shows TOO HEAVY, TOO SLOW, or a skill-too-low badge. An empty filtered board shows the message with the refresh countdown, plus Rest and Deadhead when a ship is idle there. + +### Step 18.5 — Plan amendments and regression +- Apply the amendments in §6. +- Run the full suite. +- **Test:** CI is green. The Phase 12 balance script still meets all timing targets, and its simulated player never sees a job it can't complete. Manual check: with only the deal's Courier and Clipper, browse the Earth board and confirm every job can be dispatched with one of them. + +## 6. Amendments + +| Where | Change | +|---|---| +| Plan 0.5 | Add CR-018.D1–D4. | +| Plan 3.9 | Board generation filters by the qualifying fleet (18.2). | +| Plan 9.4 | Cards drop permanent-problem badges; empty-board message (18.4). | +| CR-005 10E.3, 10E.8 | Class-mix test uses a full-capability fleet fixture; "TOO SLOW" card badge removed. | +| CR-002 | Stored boards also record the fleet snapshot (18.3). | + +## 7. Out of scope + +A "show all jobs" toggle, regenerating boards immediately when the fleet changes, hiding jobs based on credits or fuel on board, and anything else in `implementation-plan.md` §0.3. diff --git a/memory-bank/implementation-plan.md b/memory-bank/implementation-plan.md index 05d9e02..2bea999 100644 --- a/memory-bank/implementation-plan.md +++ b/memory-bank/implementation-plan.md @@ -169,6 +169,10 @@ These answer the pre-build review. Log each one in `DECISIONS.md` as it is imple 111. **Deal ships full** (CR-018). The deal's Courier and Clipper start with full tanks, valued at Earth's fuel price (replaces the quarter tank chosen during CR-015). 112. **Manual by default** (CR-018). New ships, from the deal or bought, default to Manual refueling (replaces 0.5.97's Auto default); Auto top-up is unchanged and still available per ship. Existing saves move every ship to Manual. 113. **Low-fuel warning** (CR-018). A ship's Fleet card warns "Low fuel" when its tank can't fly its longest reachable leg from where it is (CR-015 §4, CR-016 §3). +114. **Completable boards** (CR-019). A location board contains only jobs at least one qualifying ship-and-pilot pair can complete (CR-019 §2). Replaces 0.5.52's open and preview slots. +115. **Qualifying fleet** (CR-019). Owned ships at the location, or in flight there and arriving before the board period ends, each with its assigned pilot, or with any unassigned pilot at the location when the player has a bay there; the whole fleet when no pair qualifies. +116. **Permanent checks only** (CR-019). Completable means passing cargo fit (effective capacity), landing, range (full-tank reach, or the fuel on board where the origin sells none), the no-strand rule, the Priority window and the cargo and Long Haul skills. Rest, the shop, fuel on board and credits don't count. +117. **Mid-period changes** (CR-019). A stored board keeps the fleet snapshot it was generated with; reads hide jobs the current qualifying fleet can no longer complete; new capability shows at the next board period. Replaces 0.5.53's weight warning. ### 0.6 Translating change requests written for the server (CR-014 §7) @@ -833,6 +837,12 @@ Steps 18.1–18.5 are specified in `memory-bank/change-requests/CR-018-fuel-tuni --- +## Phase 19 — Only Show Jobs the Fleet Can Complete (CR-019) + +Steps 19.1–19.5 are specified in `memory-bank/change-requests/CR-019-completable-boards.md` §5 (written there as 18.1–18.5), with its §6 amendments. Stop for review at the end. + +--- + ## Definition of Done (Base Game) - All step tests pass in CI. diff --git a/memory-bank/progress.md b/memory-bank/progress.md index e0f4cd1..9eb6bd3 100644 --- a/memory-bank/progress.md +++ b/memory-bank/progress.md @@ -435,3 +435,13 @@ Spec: `memory-bank/change-requests/CR-018-fuel-tuning.md` (received as "CR-017 - [x] **Step 18.5 — Plan amendments and regression.** CR-018 §6 applied: plan 0.5.94, 0.5.96, 0.5.97 and Step 12.1; CR-015 §3 (refueling), its CR-014.D5, Steps 15.4 and 15.6; CR-013 Step 10M.3 (deal ships full). The e2e `flyUntil` helper now fills the tank before each trip (it had relied on Auto top-up, so e2e 12.6 failed from Step 18.3 until this fix), and `playToDeal` checks that both deal ships arrive full on Manual. Full suite: typecheck, lint, 1300 unit tests and 9 e2e tests pass. Balance (7 worlds): deal 3.7 min (under 10), first Market purchase 36.7 (30–95), discovery 36.6, loan paid off 123.9, four ships within 25%, no violations. **Phase 18 is complete; stopped for review.** Manual check for the user: on a fresh company, accept the deal, check both ships are full and on Manual (Fleet → Fuel), fly several Earth–Moon jobs, and check credits grow; a ship short of fuel for its longest leg shows Low fuel on its Fleet card. + +## Phase 19 — Only Show Jobs the Fleet Can Complete (CR-019) + +Spec: `memory-bank/change-requests/CR-019-completable-boards.md` (received as "CR-018 … Phase 18"). New decisions recorded as plan §0.5.114–0.5.117. + +- [ ] Step 19.1 — Sim: completability check +- [ ] Step 19.2 — Sim: generation keeps only completable jobs +- [ ] Step 19.3 — Engine: boards, filtering, and migration +- [ ] Step 19.4 — Client: cards and empty state +- [ ] Step 19.5 — Plan amendments and regression