Vibe Tycoon, and everything behind it.

Estimation

Estimated S, landed S — accurate

Handoff

P0 Critical, AD-6 (store logistics drive the schedule, never displaced by build work), AD-7 (Samsung is committed deadline insurance). It is an XS administrative task with zero reason to sit Deferred five weeks from the submission deadline.

Effort estimate: XS

Scope

• Register a Samsung Galaxy Store seller account at seller.samsungapps.com under the same identity/business details already used for the Google Play account. Capture the account confirmation status (pending/verified) and any ID-verification requirement Samsung imposes, and record it in `docs/research/store-compliance.md` (or wherever the Play equivalent from task-1 was recorded — check that file first) so both stores' logistics live in one place. Do not create a store listing yet — this task is account registration only.

Out of scope

• Do not build or upload a Galaxy Store listing, app bundle, or screenshots — that is separate, later work once the app is closer to release-ready. Do not touch Play Console. Do not commit any account credentials, API keys, or personal ID-verification documents to the repository.

Acceptance criteria

• Samsung Galaxy Store seller account exists and its verification status (pending or verified) is recorded outside the repo (password manager / notes), with only the non-sensitive status line committed to `docs/research/store-compliance.md`
• No credentials, tokens, or ID documents committed to git
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during registration (e.g. Samsung requiring something Play didn't)

Files likely touched

• docs/research/store-compliance.md (status line only — no code files, no `src/**` changes) (edit)

Security considerations

Account credentials and any ID-verification documents must never enter the repository, even in a private branch. Store them in the owner's password manager only.

Handoff

Catvertising judges on performance data, not ad volume. `src/monetization/adRevenue.ts` and `adRevenueConfig.ts` already ship a typed, credential-free ad-revenue boundary (task-31) — this task closes the loop by sending that data to RevenueCat via Impression-Level Revenue Data so it blends with IAP in one reportable dashboard.

Effort estimate: M

Scope

• Wire the existing `src/monetization/adRevenue.ts` impression-revenue boundary to RevenueCat's ILRD ingestion path (`Purchases.setAttributes` / the RevenueCat ILRD API — confirm current SDK method name against RevenueCat's docs, it is beta and may have moved). Reuse the existing typed, integer-micro revenue events already produced by `adRevenue.ts` — do not build a second revenue-normalization path. This is additive wiring on top of shipped code, not new economy logic.

Out of scope

• Do not modify `adRevenue.ts`'s existing revenue-normalization logic or its tests — this task consumes that boundary, it does not change it. Do not build new mediation provider integrations (AdMob is already selected, task-31). Do not log raw ad creative content, advertising identifiers, or receipts — `adReport.ts`'s existing pattern of never logging that data is the bar to match.

Acceptance criteria

• Ad revenue events from `src/monetization/adRevenue.ts` reach RevenueCat's ILRD path without modifying the existing revenue-normalization boundary or its tests
• No PII, advertising identifiers, or raw ad-creative content is logged or sent beyond what ILRD requires
• A failure in ILRD delivery does not affect gameplay or ad display — isolated the same way `adRevenue.ts` already isolates SDK failures
• Scope matches handoff — no unrelated code changed

Files likely touched

• src/monetization/adRevenue.ts (read-only reference, do not modify per scope boundary) (edit)
• src/monetization/adRevenueConfig.ts (edit)
• src/monetization/purchases.ts (from task-91, if ILRD needs the shared Purchases SDK handle) (edit)

Security considerations

No PII or advertising identifiers in ILRD payloads or logs — matches the existing `adReport.ts` boundary's rule. REFERENCE DOCS docs/research/ad-mediation-integration.md docs/design/ad-free-path.md

Estimation

Estimated S, landed S — accurate

Handoff

A disabled action currently looks unaffordable even when the real blocker is a studio-cap or progression requirement, making the local decision loop misleading.

Effort estimate: XS

Scope

• REPRODUCE: Create or use a local save with 164 cash, a 69-cash hire action, and the studio cap already reached. Confirm that the disabled hire control shows only the price or an otherwise misleading affordability state.
• ROOT CAUSE: The disabled-action label resolves the cash affordability message before checking capability or progression blockers.
• MINIMAL FIX: Change the existing blocker-resolution path so non-cash blockers take precedence and render a concise player-facing reason such as “Studio cap — reach 20 rep for Tiny Studio.” Apply the same established rule to the directly adjacent disabled CTA path only. Change only what is necessary; do not refactor unrelated UI.
• REGRESSION TEST: Extend the existing local playtest or test surface to cover a cap-blocked action with sufficient cash, an insufficient-cash action with no other blocker, and a successful enabled action.

Out of scope

• Do not redesign all disabled controls, alter economy values, add new blocker types, or change progression requirements.

Acceptance criteria

• The reproduced cap-blocked hire shows the actual blocking reason instead of only the price.
• Insufficient-cash actions still show the affordability state.
• Regression coverage distinguishes capability blockers from cash blockers.
• Fix is targeted — no unrelated code changed.
• Regression test confirms the bug no longer reproduces.

Files likely touched

• `src/ui/GameScreen.tsx` (edit)
• `scripts/playtest.cjs` (edit)

Security considerations

None — no security-relevant changes

Estimation

Estimated XS, landed XS — accurate

Estimation

Estimated S, landed S — accurate

Handoff

Explicit owner request ("Cathal wants the game to read funnier overall"), pure copy work on existing typed catalogs, and it rides the same Core branch as the automation pair at near-zero coordination cost. Serves Best Game: tone is a judged surface and the satire layer (fictional services, vibe-coding humor) is the game's voice.

Effort estimate: S

Scope

• Deliverable: a coherent comedy pass over the player-facing copy catalogs — job titles/descriptions, incident and recovery copy, agent flavor/personality text, and milestone names — so the game reads funnier while staying legible. Done looks like: a player reading the job board, an incident card, and the milestone browser encounters consistent, genuinely funny vibe-coding-industry satire rather than neutral placeholder prose.
• Work only inside the existing copy sources: the job catalog literals, the incidentCopy helper, the personality/prompting catalogs, the milestone registry names, and the typed explanation catalog where its copy is flavor rather than instruction. Copy lives where it already lives — no new copy framework, no i18n layer.
• Keep the tone inside the established satire canon: read docs/design/fictional-services.md first and stay consistent with its naming universe; keep it grounded-cheerful per AD-17 (not cyberpunk, not mean-spirited, not dystopian).
• Constraints that bind: critical action copy and mechanic explanations must remain unambiguous (the tooltip/explanation catalog's instructional entries keep their meaning — funny is allowed, unclear is not); milestone IDs and any persisted identifiers must NOT change, only display names; store-facing metadata stays 4+ appropriate per AD-10/task-34's constraint.
• Run the stop-slop/humanizer pass on the resulting copy per the task notes so it does not read as AI-tell text.
• Tests: existing snapshot/source tests that assert copy will need updating in the same commit; add or update a test asserting milestone display names stay unique and IDs unchanged.

Out of scope

• No mechanical changes: no economy values, probabilities, durations, or state shapes.
• No renaming of persisted IDs, analytics event names, or schema fields.
• No new tone for purchase/monetization disclosure copy — truthful-disclosure surfaces (AD-21/AD-23) keep their plain language.
• Not a rewrite of the player manual or design docs (touch docs only if a copy source is documented verbatim and would drift).

Acceptance criteria

• Job, incident, agent-flavor, and milestone display copy revised for comedy, consistent with docs/design/fictional-services.md and AD-17's tone
• All persisted IDs, analytics enums, and schema fields byte-identical; only display strings changed
• Instructional/critical-action copy remains unambiguous (human judgement — reviewer reads each changed instructional string)
• Copy passed through the stop-slop/humanizer check per task notes
• npm test and npx tsc --noEmit pass with test expectations updated in the same commit
• Fix is targeted — no unrelated code changed

Files likely touched

• src/game/prompting.ts, the incident-copy, personality, milestone, and job catalog modules located in pre-build verification (src/game/ and src/economy/config.ts literals), src/ui/GameScreen.tsx (only if copy is inlined there), corresponding tests under tests/, docs/player-manual.md (only if it quotes changed strings) (edit)

Pre-build verification

• Read docs/design/fictional-services.md (canonical naming source) before writing any copy.
• Read the incidentCopy helper (src/game/ — from task-98), the personality catalog (src/game/ — from task-122), the prompting approaches (src/game/prompting.ts), the milestone registry (from task-81), and the job catalog literals (from task-68) to inventory the actual copy surfaces.
• Read the typed explanation catalog (from task-163) to separate instructional entries (meaning-preserving edits only) from flavor entries.
• Docs sweep: doc_search "tone" / "satire" / "fictional services" to confirm no prior tone-pass task already covers part of this; check docs/player-manual.md for copy it quotes.

Security considerations

None — no security-relevant changes; display copy only.

Estimation

Estimated S, landed S — accurate

Handoff

AD-22 explicitly carved out this exact feature as a prestige-tier convenience layer, resolving the AD-15 conflict that parked it. It is the highest-impact unblocked Core work: it completes the manual → delegation → orchestration → automation arc that AD-13 promises, and it must land before task-209 because it takes the next save schemaVersion and establishes the late-game automation-unlock gating pattern task-209 reuses.

Effort estimate: M

Scope

• Deliverable: a late-game automation upgrade that, once unlocked and enabled, automatically accepts suitable job offers from the board and assigns them to ready agents, as a convenience layer on top of the proven manual loop. Done looks like: a player past the unlock gate can toggle "Auto-Ops" on, watch offers get collected and assigned without taps, and toggle it off to return to full manual control; a player before the gate never sees the toggle as available.
• Define the unlock gate as a pure predicate in the economy/rules layer (e.g. `automationUnlocked(state)`), derived from existing progression state that proves manual mastery — use existing signals only (company stage, unlocked milestones, or exit history; the task notes require "after the player has demonstrated understanding of manual job-review/assignment"). Pick the concrete gate from the progression ladder's late stages and document the choice in the code comment with a pointer to AD-22.
• Add persisted state: an automation-enabled boolean (and unlock provenance if needed) in SaveState, with the next schemaVersion bump (currently 18 → 19) and a forward-only migration defaulting to off, in the same commit (project convention).
• Implement the automation step inside the existing store tick path: when enabled and the gate passes, auto-accept an available offer and auto-assign it to a ready agent using the existing pure selection/assignment functions — do not duplicate assignment logic in the UI or invent a second scheduler. Respect all existing gates (capacity, tokens, blocked/busy agents, pending completion decisions); automation must never do anything a manual player could not do at that moment.
• Auto-assignment must NOT bypass the completion-decision flow (vibe check ship/review) — it automates collection and assignment only, per the task title. Completion decisions remain manual.
• UI: a clearly-labeled toggle on the existing surface where late-game controls live, visible-but-locked with truthful copy before the gate (reuse the established "planned/locked" truthful-label pattern from task-171), with an accessible label per the UI affordance guide.
• Tests: store-level tests proving (a) automation does nothing before the gate, (b) enabled automation accepts+assigns only when a manual action would be legal, (c) the toggle state persists through save/load with the schema 19 migration, (d) disabling stops automation next tick.

Out of scope

• No day-1 or mid-game availability — the gate is late-game, per AD-22.
• No auto-resolution of completion decisions, incidents, or prestige (task-209 owns prestige automation).
• No new currency, no Cash/token price on the toggle unless an existing config surface makes it trivial — the unlock is progression-gated, not a monetization surface in this task.
• No spawn-rate tuning: task-170's spawn-rate concern was fixed separately; automation is not the fix for pacing.
• Do not touch the Design-module icon work (task-179).

Acceptance criteria

• Pure unlock predicate exists in the economy/rules layer, derived only from existing progression state, with an AD-22 reference comment
• SaveState carries the automation field at schemaVersion 19 with a forward-only migration defaulting to off; migration ships in the same commit
• With automation enabled past the gate, offers are auto-accepted and auto-assigned through the existing pure functions; every existing legality gate is respected
• Completion decisions (ship/review) remain manual with automation on
• Toggle is visible-but-locked with truthful copy before the gate, and accessible
• npm test and npx tsc --noEmit pass
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation

Files likely touched

• src/persistence/save.ts, src/game/store.ts (or the store module found in pre-build verification), src/economy/rules.ts, src/economy/config.ts, src/ui/GameScreen.tsx, tests under tests/ mirroring the existing store/persistence test layout (e.g. tests/store/, tests/economy/) (edit)

Pre-build verification

• Read src/persistence/save.ts to confirm the current schemaVersion (reports say 18 after task-188) and the migration pattern.
• Read the store module (src/game/store.ts or wherever the Zustand store lives — locate the tick/assign/grantOffer path) to find the existing pure assignment/acceptance functions and the ready-agent definition from task-193.
• Read src/economy/rules.ts and src/economy/config.ts for the progression/stage predicates (currentStage, jobSlotsFor) the gate will derive from.
• Read src/ui/GameScreen.tsx for where late-game controls render and the truthful locked-label pattern from task-171.
• Docs sweep: doc_search for the progression ladder and core-loop docs (docs/design/progression-ladder.md, docs/design/core-loop.md) and confirm via doc_search "automation" that no prior task already shipped any auto-assign state; task-174 was cancelled and rescoped into this task, so verify no partial branch exists (git branch -a | grep -i auto).

Security considerations

None — no security-relevant changes; local deterministic game state only.

Estimation

Estimated M, landed M — accurate

Estimation

Estimated M, landed M — accurate

Estimation

Estimated S, landed S — accurate

Handoff

lands with the first rewarded placement (task-88) so the closed-testing build never shows ads to paying players — a HAMM/Catvertising truthfulness signal, not a follow-up nicety.

Effort estimate: S

Scope

• Deliverable: players holding the relevant entitlement (VIP/PAPI ownership from the shipped monetization state, task-186/task-16 surfaces) never see the rewarded rescue offer built by task-88; where a rewarded offer would have appeared, show a brief truthful reason (e.g. "You own PAPI — rescues are included") instead of hiding the affordance silently. Implement as a pure eligibility rule over existing persisted entitlement state, consumed by the task-88 placement render path. Done looks like: an entitled test state suppresses the offer and shows the reason; a non-entitled state behaves exactly as task-88 built it.

Out of scope

• No changes to the entitlement ladder or purchase flow (task-186 shipped it); no new entitlement tier; no suppression of IAP surfaces — this task is about rewarded offers only.

Acceptance criteria

• Entitled players never see the rewarded offer; the honest reason renders in its place
• Non-entitled behaviour is unchanged from task-88
• The eligibility rule is pure and covered by focused tests
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation

Files likely touched

• src/monetization/ (small eligibility rule module or an addition to the placement module) (edit)
• src/ui/GameScreen.tsx (offer render condition + reason copy) (edit)
• tests/ (entitlement-suppression coverage) (edit)

Pre-build verification

• src/monetization/vip.ts — the shipped cumulative-spend/entitlement ladder (task-186) the rule reads.
• The task-88 placement render path (built this cycle) — where suppression plugs in.
• src/persistence/save.ts — confirm how entitlement state is persisted and migrated.

Security considerations

None — no security-relevant changes (entitlement state is already verified purchase state; no new data exposure).

Handoff

Owner-flagged after stalling multiple cycles; both former blockers are gone (incident system shipped; AdMob mediation selected and the provider-neutral revenue boundary shipped by task-31), and AD-4 sequences rewarded video at/around launch — scheduling now puts it in the ~6 Sep closed-testing build with Catvertising evidence attached.

Effort estimate: M

Scope

• Deliverable: when an incident appears, a non-entitled player is offered a themed "roll back the deploy" rescue: watch a rewarded video and the incident is rolled back (the incident's failed-job/reputation consequence is cancelled or materially reduced) instead of paying the in-game recovery cost. Rewards and caps stay inside CONFIG.boosts.rewarded, which already encodes the 30-40%-of-IAP derivation and is asserted by tests/economy/guardrails.test.ts — do not move economy numbers. Integrate the Expo-compatible rewarded-ads binding (verify the current recommended AdMob adapter for this Expo SDK version before installing; the module history shows dependency additions here need isolated verification), normalise the earned reward through the existing provider-neutral boundary used by src/monetization/adRevenue.ts, route the placement through the task-35 compliance surface (content-rating filter + report-an-ad payload), and keep the entitlement check point clean so task-95 can build suppression on it. A player who skips or fails to complete the video keeps the normal incident route (manual recovery, refactor-as-opportunity-cost) — the non-paid route is never worse than before this task. Done looks like: an incident in the playtest/debug harness shows the rescue offer; completing a test ad (or a stubbed provider in tests) applies the rollback exactly once per incident; guardrail tests stay green.

Out of scope

• No additional placements (task-8 covers future ones); no ILRD/dashboard blending (deferred task-96); no changes to incident probability or severity math; no paid shortcuts beyond this single rewarded rescue (AD-35: no timer is eligible for finish_job_now); do not ship the Data Safety form update in this task (filed separately as new-1).

Acceptance criteria

• Incident rescue offer appears only for non-entitled players with an active incident
• Completing the rewarded video applies the rollback exactly once per incident; skipping leaves the normal route intact
• Reward amounts and caps come from CONFIG.boosts.rewarded and tests/economy/guardrails.test.ts passes unchanged
• The placement routes through the existing content-rating filter and report-an-ad payload
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation

Files likely touched

• src/monetization/adRevenue.ts (reward normalisation) (edit)
• src/monetization/ (new rewarded-placement module alongside adRevenue/adReport) (edit)
• economy config holding CONFIG.boosts.rewarded (read-only — no value changes) (edit)
• incident module (rollback application point) (edit)
• tests/economy/guardrails.test.ts plus new placement tests (edit)
• app config for the ads config-plugin (app.json / Expo config) if the chosen binding requires one (edit)

Pre-build verification

• src/monetization/adRevenue.ts — the existing provider-neutral revenue normalisation (task-31) the reward path must reuse.
• src/monetization/adReport.ts and the content-rating filter (task-35) — the compliance surface to route the placement through.
• The economy config holding CONFIG.boosts.rewarded (locate it via tests/economy/guardrails.test.ts imports) — confirm the reward shape already encoded.
• The incident module (incidentChance/incidentSeverity and the task-78 resolution flow) — where the rollback hooks into incident state.
• docs/design/depth-audit.md §6.3, §10 — the placement's design rationale.

Security considerations

New third-party SDK (ads): review the permissions and data collection it adds, keep provider identifiers out of logs and analytics payloads, and note the Play Data Safety declaration must be updated before the closed-testing build ships publicly (tracked as a separate task, not inline).

Handoff

broadens the shipped IAP ladder with a low-anchor SKU ahead of closed testing; the RevenueCat purchase path already shipped (v0.44.0), so this is catalog + surface work on an existing seam.

Effort estimate: S

Scope

• Deliverable: a $1.99 tooling bundle product purchasable through the single RevenueCat wrapper (project convention — never bypass it): explicit deterministic contents per the economy canon anchor (state exactly which tooling/upgrade value it grants), wired into the existing shop surface with truthful pricing copy, restorable via the existing restore path, idempotent like the existing purchases. Owner prerequisite, not a code blocker: the SKU must be created in RevenueCat + Play Console — implement behind the existing product-id config so the code can ship enabled-when-configured; if the SKU ID is not yet fixed, use the canon naming and list the exact IDs to configure in the build report. Done looks like: the shop shows the bundle with contents and price; a sandbox purchase (or stubbed provider in tests) grants the contents exactly once; restore re-grants without duplication.

Out of scope

• No new price points beyond the canon anchor; no randomized bundle contents (AD-23 guardrail); no changes to the VIP ladder or PAPI entitlement; no price-localisation work (task-94 stays separate).

Acceptance criteria

• Bundle renders in the shop with explicit contents and the $1.99 price
• Sandbox/stub purchase grants the contents exactly once; restore is idempotent
• Product IDs are config-driven and the exact SKU configuration steps are listed in the build report
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation

Files likely touched

• src/monetization/ (bundle product definition behind the existing wrapper) (edit)
• shop surface component(s) (tooling shop render path) (edit)
• economy config (bundle contents, read per canon) (edit)
• tests/ (purchase/restore idempotency coverage) (edit)

Pre-build verification

• The single RevenueCat purchase wrapper module (locate via the shipped v0.44.0 purchase placement) — extend it, never bypass.
• src/monetization/vip.ts — the cumulative-spend ladder the bundle must not double-count against.
• The shop surface (tooling ladder shop, task-97) — where the bundle renders.
• The economy config — the $1.99 canon anchor and what the bundle grants.

Security considerations

Purchases route through the single RevenueCat wrapper only — no receipt handling outside it, no secrets in code; keep any keys in env/config per the existing convention.

Estimation

Estimated S, landed S — accurate

Handoff

A deterministic simulator is valuable for shared reproduction, but local route implementation and public activation must remain separate.

Effort estimate: M

Scope

• Verify and reuse the existing simulator source and deterministic scenario inputs before adding anything.
• Add a clearly labeled debug route isolated from the player route and player save state.
• Show version and scenario parameters; validate deterministic URL presets, including malformed and oversized input.
• Add route, isolation, and deployment checks proving the player route is unchanged.
• Document the exact public path and activation procedure without activating public visibility.

Out of scope

• Do not deploy, publish, or change access controls.
• Do not read or mutate player saves, add a backend, expose secrets, or collect identifiers.
• Do not replace the player route or create a second server.

Acceptance criteria

• The route renders locally with a clear DEBUG BUILD label and current version.
• Valid presets reproduce the same result; malformed or oversized presets fail safely.
• The route cannot access or mutate player save storage.
• The normal player route and existing route checks remain unchanged.
• Public activation is documented as a separate exact-destination approval gate and is not performed here.

Files likely touched

• App.tsx (edit)
• src/debug/DebugSimulatorScreen.tsx (edit)
• src/debug/simulator.ts (edit)
• tests/debug/simulator.test.ts (edit)
• docs/SERVER_DEPLOYMENT.md (edit)

Pre-build verification

• App.tsx
• tests/economy/profiles.test.ts
• scripts/deploy-web.sh
• docs/SERVER_DEPLOYMENT.md
• Docs sweep: check docs/INDEX.md and doc_search for task-160, task-162, and debug-route material.

Security considerations

Treat presets as untrusted input. Keep the surface local-state-only and exclude secrets, saves, identifiers, and admin controls. Public activation remains separately authorized.

Estimation

Estimated S, landed S — accurate

Estimation

Estimated S, landed S — accurate

Handoff

This is the Shipaton entry gate (SHIPATON.md: "Ads alone do not satisfy the entry gate. A live IAP is mandatory") and the HAMM category's entire subject matter, and it does not exist in code yet anywhere in this project's history. Every prior "RevenueCat" task shipped a design doc, not a wrapper. Closed testing must start 6 Sep — there is no more slack to leave this unbuilt.

Effort estimate: L

Scope

• Build the single RevenueCat wrapper the CLAUDE.md convention names but that does not yet exist: `src/monetization/purchases.ts`.
• 1. Add the `react-native-purchases` (RevenueCat) SDK as a dependency and configure the Expo config plugin per RevenueCat's Expo setup docs.
• 2. Initialize `Purchases.configure({ apiKey })` once at app boot (in `App.tsx` or an early init path), reading the public API key from an env var / EAS secret — never hardcoded.
• 3. In `src/monetization/purchases.ts`, expose a small typed surface: fetch the current Offering (`Purchases.getOfferings()`), a `purchasePackage` wrapper, and an entitlement-check function that reads `CustomerInfo.entitlements.active` — this is the "entitlements as truth" convention, not local/save state.
• 4. Consume `docs/design/iap-offerings.md` and `docs/design/first-purchase-funnel.md` as the product/offering spec — they already define the intended product ladder (papi_ops, quiet_office per task-18/task-41's design work); do not re-derive product structure from scratch.
• 5. Wire the wrapper's entitlement state into whatever currently gates PAPI/Quiet-Office-adjacent behaviour in `src/game/store.ts`, if such a gate exists yet (check first — it may not).
• **First acceptance criterion below is a hard stop, not a formality**: if no RevenueCat dashboard project / API key is available, do not fabricate or mock entitlement data as if it were real — stop and surface that back to the user as a genuine external blocker (RevenueCat account + dashboard product/offering configuration is outside this repo).

Out of scope

• Do not build the trial ladder, win-back offers, or Experiment (task-92, task-93 — separate tasks, task-92 is this cycle and depends on this one). Do not build a paywall UI screen — this task is the data/entitlement plumbing, not the purchase surface a player sees. Do not hardcode product or entitlement identifiers as string literals scattered through the codebase — they belong in `CONFIG` or the wrapper module only.

Acceptance criteria

• RevenueCat dashboard project and API key confirmed to exist before writing entitlement logic against them — if missing, task stops here and is reported back, not mocked (see SCOPE)
• `src/monetization/purchases.ts` exists as the single wrapper; nothing else in the codebase calls the RevenueCat SDK directly
• Current Offering is fetched at runtime — no product/offering ID is a string literal outside this wrapper and `CONFIG`
• Entitlement checks read from `CustomerInfo`, never from local save state, per AD-3/the entitlements-as-truth convention
• API key is read from an env var / EAS secret, not committed to source
• Scope matches handoff — no unrelated code changed

Files likely touched

• src/monetization/purchases.ts (new)
• package.json (edit)
• app.json / app.config (Expo config plugin registration) (edit)
• App.tsx (SDK init) (edit)
• src/game/store.ts (only if wiring an existing entitlement gate — verify first) (edit)

Security considerations

This is new attack surface, not existing code being touched. The RevenueCat public API key must be an env var / EAS secret, never a string literal. Entitlement state must always be re-derived from `CustomerInfo` — never trust a locally-cached "is entitled" flag as authoritative, since that is exactly the kind of client-side state a save-file edit could forge. No purchase receipts, customer IDs, or raw SDK errors get logged (mirrors the existing pattern in `src/monetization/adReport.ts`, which already avoids logging raw SDK/PII data). REFERENCE DOCS docs/design/iap-offerings.md docs/design/first-purchase-funnel.md docs/design/ad-free-path.md (existing entitlement-shaped design for `quiet_office`, useful pattern reference even though it isn't built either)

Estimation

Estimated L, landed M — accurate

Estimation

Estimated M, landed M — accurate

Estimation

Estimated M, landed M — accurate

Handoff

Effort estimate: XS

Scope

• Re-export assets/vibe-tycoon-logo-v2.png with a REAL alpha channel: remove the baked-in background so the logo composites cleanly over any surface. Current file is 8-bit RGB, 1774x887, no alpha (verified via file(1)).
• Keep the SAME filename and path so no code changes — src/ui/GameScreen.tsx:43 requires it by path. If the source art demands a new export, name it -v3 and update the single require plus the style reference only.
• Verify by rendering: web export or dev server, confirm the header logo shows no solid box against both the header surface color and the pixel-art background. Capture a screenshot for owner approval — art quality is an owner judgment.
• Check assets/README.md provenance notes and update the entry for the logo if it documents the asset.

Out of scope

• No redesign of the logo art itself — background removal only, pixels of the mark stay as authored.
• No changes to the platform app icon, favicon, or splash assets (task-204 owns those and they are Done).
• No GameScreen layout or style changes beyond, at most, the single require path if a -v3 filename is unavoidable.

Acceptance criteria

• The logo PNG carries a real alpha channel — host runs `file assets/vibe-tycoon-logo-v2.png | grep -q RGBA && echo PASS`
• Rendered header shows the logo compositing over the background with no solid box, verified by screenshot provided to the owner
• No code changes outside at most one require path and the asset provenance note
• npm test and npx tsc --noEmit pass

Estimation

Estimated XS, landed XS — accurate

Handoff

The gate is 28 Aug 2026 and today is 21 Aug — seven days. Google's identity verification runs on its own 2-5 business day clock, and nothing downstream can begin until it clears: no Play Console, no internal testing track, no IAP product configuration, and no start to the 14 continuous days of closed testing that must be running by 6 Sep. This task was scheduled in Cycle 2, did not land, and is sitting in Deferred with a hard external clock — the highest-risk item on the board by a wide margin. AD-6 makes store logistics undisplaceable. Category served: entry eligibility itself. HAMM, Catvertising, Best Game and #BuildInPublic all score zero if the app is not publicly live on a store.

Effort estimate: XS

Scope

• Create or confirm the Google Play Console developer account under the publishing identity that will own vibe-tycoon.
• Pay the one-time $25 USD registration fee.
• Submit developer identity verification (legal name, address, government ID upload, plus D-U-N-S if registering as an organisation).
• Create docs/store/play-account.md recording: account type chosen (personal or organisation), the developer name that will appear on the public listing, the package name reserved, the date verification was submitted, and the expected clearance date. Register it in docs/INDEX.md.
• Reserve the app entry in Play Console (app name, default language, "game", "free") so the package name is claimed. If the console blocks app creation until verification clears, write that in the doc and stop there rather than working around it.

Out of scope

• Do not fill the Data safety form, the IARC questionnaire or store listing metadata. task-34 owns those.
• Do not upload a build or configure a testing track. task-9 owns that.
• Do not create IAP products or configure RevenueCat. task-6 owns that.
• Do not commit any government ID, home address, payment detail or account email to the repository.
• Do not register an Apple developer account. AD-2 keeps this Android-first and the $99 is out of budget.

Acceptance criteria

• $25 registration fee paid and the Play Console shows the developer account as created.
• Identity verification submitted, with the submission date recorded.
• docs/store/play-account.md exists and names the account type, the public developer display name, the reserved package name, the verification submission date and the expected clearance date.
• No personal identifiers — ID document, home address, account email, payment details — appear anywhere in the diff.
• If app creation was blocked pending verification, the doc says so explicitly rather than leaving it implied.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• docs/store/play-account.md (new)
• docs/INDEX.md (edit)

Pre-build verification

• Glob docs/store/ — if play-account.md or an equivalent already exists, the account may already have been created in Cycle 2; read it before paying anything a second time.
• Run doc_search for "play account", "developer account" and "identity verification" — a Cycle 2 partial record may be registered but unfiled.
• Read CLAUDE.md's deadline gate table to confirm the 28 Aug / 6 Sep / 20 Sep chain has not moved.
• Check the Cycle 2 build reports for task-1 and task-2 — task-2 (Samsung seller account) has left the board, which may mean store work partially landed and was never reported.

Security considerations

This task handles the owner's real identity documents and a payment method. None of it belongs in git. The doc records dates, account type and the public developer name only. Treat the Play Console credentials as secrets — they are not stored in the repo, in .env, or in EAS secrets as part of this task. REFERENCE DOCS docs/research/store-compliance.md SHIPATON.md CLAUDE.md — "The Deadline Is The Product Constraint" gate table

Handoff

The only unblocked Design-module task, directly serving Best Game and the Design surface: the game's systems (milestones, tooling, incidents, stages) currently read as text lists, and a consistent icon grammar is the highest-leverage legibility win available without any external gate. Build it AFTER the Core branch merges — task-208 changes display strings on the same surfaces.

Effort estimate: M

Scope

• Deliverable: a cohesive, data-driven icon and visual grammar for the highest-frequency surfaces first — milestone browser and unlock toast, upgrade/tooling shop, resource strip, job cards, agent rows, incident/recovery cards, and stage/exit surfaces. Done looks like: each of those surfaces renders a consistent, legible visual mark per concept from one canonical catalog, with locked/unlocked/affordable/active/disabled states, accessible text labels everywhere, and no reliance on color alone.
• Read PRODUCT.md for product purpose, users and design principles, and DESIGN.md for the visual tokens (palette, typography, elevation, components) — every visual decision must align with them. Run design-critique before building, per AD-17's binding process rule.
• Define canonical asset/icon IDs in ONE shared typed catalog (extend src/ui/tokens.ts or add a sibling module under src/ui/) so the same icon and meaning are reused across mobile, web, and tooltips — no scattered emoji, no ad-hoc symbols, no duplicated asset copies in components. Follow the established single-atlas pattern (task-111: one canonical atlas, crop at render time) if raster art is added; prefer text-first/vector-in-code marks in the existing pastel pixel direction (the task-188 company-icon catalog is the precedent) to keep asset scope bounded.
• Include the deliverables the task notes require: an asset audit of what exists, a missing-art list for anything deferred, contrast checks against DESIGN.md baselines, small-screen legibility, restrained state animation reusing src/ui/motion.ts budgets, and a rendering fallback when an asset is unavailable.
• Every visual carries an accessible text label; states never communicated by color alone.
• Tests: source-contract tests that the catalog is complete for every surfaced concept (each milestone/tooling/resource/incident/stage ID resolves to a catalog entry or the explicit fallback) and that labels are present.

Out of scope

• The full list in the task notes (owned products, prestige tree, debug simulator, documentation icons) is the epic, not this cycle: this task covers the named highest-frequency surfaces; put the remainder on the missing-art list for a follow-up.
• No changes to game logic, economy values, or persisted state — presentation only.
• No new binary asset sprawl: one atlas/catalog, no per-concept PNG files.
• Do not restyle copy — task-208 owns the words; consume its merged strings.
• Do not import another project's brand canon (AD-17).

Acceptance criteria

• One typed canonical icon/visual catalog exists and every listed high-frequency surface renders from it
• Locked/unlocked/affordable/active/disabled states are visually distinct, not color-only, and every mark has an accessible label
• Asset audit + missing-art list recorded (assets/README.md or a docs/design/ note) for deferred surfaces
• Contrast passes DESIGN.md baselines on the pastel palette (check per AD-17's known contrast risk)
• Visually verify rendered output in browser — provide localhost URL or screenshot to user for review
• No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips
• npm test and npx tsc --noEmit pass

Files likely touched

• src/ui/tokens.ts, a new sibling catalog module under src/ui/, src/ui/GameScreen.tsx, src/ui/job-card.ts, src/ui/milestones.ts, assets/README.md, tests under tests/ mirroring the existing UI source-contract test layout (edit)

Pre-build verification

• Read DESIGN.md and src/ui/tokens.ts (task-109's shared token module) to confirm the token roles and whether an icon catalog already partially exists.
• Read the company-icon catalog from task-188 and the AgentAvatar/atlas path from task-111 — these are the established catalog and atlas patterns to extend, not duplicate.
• Read src/ui/GameScreen.tsx, src/ui/job-card.ts, and src/ui/milestones.ts to inventory which surfaces already carry any visual marks.
• Read src/ui/motion.ts for the animation budgets that state transitions must reuse.
• Docs sweep: doc_search the UI affordance guide (task-200), docs/design/game-feel.md, docs/design/fictional-services.md, assets/characters/README.md and assets/offices/README.md (the task's own references) — confirm no prior icon-grammar doc exists before defining one.

Security considerations

None — no security-relevant changes; presentation only.

Estimation

Estimated S, landed S — accurate

Estimation

Estimated S, landed S — accurate

Handoff

The app already has an in-house React Native/Web design system and several UI surfaces. A compatibility report can reduce future migration risk without changing runtime behavior or making a human-dependent visual choice.

Effort estimate: M

Scope

• Inspect the current Expo, React Native, React Native Web, TypeScript, typography, accessibility, and UI-test setup. Compare at least three realistic React Native/Web-compatible options against the current in-house approach using primary documentation and package metadata. Cover buttons, cards, dialogs/overlays, transient messages, forms, theming, responsive behavior, icons, accessibility, touch, and keyboard interaction. Produce docs/research/ui-component-library-evaluation.md with an iOS/Android/desktop-web compatibility matrix, risks, recommendation, fallback, and staged adoption sequence. Keep the recommendation advisory and register the document with PAPI.

Out of scope

• Do not install a library or alter package.json, lockfiles, native projects, or runtime UI. Do not make a subjective visual redesign decision. Do not perform store, device, public deployment, account, payment, analytics, or provider work.

Acceptance criteria

• Report compares at least three viable options plus the current in-house approach, with primary documentation and package metadata links.
• Compatibility matrix covers iOS, Android, and desktop web and calls out DOM/native-module risks.
• Recommendation, fallback, and staged adoption plan are explicit; dependency adoption remains human-reviewed.
• No dependency manifests or runtime source files change; diff is limited to the report and required registry metadata.
• Report matches the repository's current Expo/RN/RNW/TypeScript versions and existing UI/accessibility tests.
• Document is registered in PAPI and discoverable by doc search.

Files likely touched

• docs/research/ui-component-library-evaluation.md; PAPI document registry metadata only (edit)

Estimation

Estimated M, landed M — accurate

Handoff

The current mainline still exposes one assignable offer at a time, so the player cannot compare contracts. The prerequisite slot-capacity and refill work is recorded Done; this slice adds the smallest deterministic choice surface on top of it.

Effort estimate: L

Scope

• Replace the singular player-facing offer presentation with a two-offer shortlist when the runtime has at least two eligible offers.
• Add a pure job-board helper that creates a deterministic, non-duplicated shortlist from the existing job definitions and current reputation, preserving the opening/FTUE offer contract.
• Add explicit selection state and a single selected-offer assignment path in the Zustand store; selecting one offer must leave the other available until assignment or replacement.
• Keep the shortlist bounded to two cards and preserve the current no-offer, no-free-agent, assignment feedback, and offer-refill behavior.
• Add focused store/economy/UI regression tests for deterministic choices, selection, assignment, and FTUE compatibility.

Out of scope

• Do not add new monetization, ad, RevenueCat, account, device, store, provider, network, or public-access behavior.
• Do not redesign job economics, progression stages, assignment costs, incident rules, or the FTUE sequence.
• Do not implement more than two simultaneous offers, expiry mechanics, drag/drop, sorting controls, or a new job-generation system.

Acceptance criteria

• The player-facing job board renders two distinct eligible offers whenever two offers are available, and never renders duplicate offer IDs.
• Offer generation is deterministic for a supplied reputation/seed or equivalent state and remains compatible with the existing opening sequence.
• Selecting an offer and assigning it starts the selected job only; the unselected offer remains available until the board replacement contract handles it.
• Existing no-offer, no-free-agent, blocked-action, refill, and FTUE tests continue to pass.
• Focused tests, full Jest, TypeScript, web export, deterministic headless Playwright, and git diff checks pass.

Files likely touched

• src/game/store.ts (edit)
• src/economy/config.ts (edit)
• src/ui/GameScreen.tsx (edit)
• src/game/job-board.ts (edit)
• tests/game/job-board.test.ts (edit)
• tests/game/ftue.test.ts (edit)
• tests/game/opening-journey.test.ts (edit)
• tests/ui/game-screen-accessibility.test.ts (edit)

Pre-build verification

• Read src/game/store.ts and src/economy/config.ts to verify the current offer state and job definitions before changing them.
• Read src/ui/GameScreen.tsx and tests/game/ftue.test.ts to preserve the opening contract.
• Read tests/game/job-review.test.ts, tests/game/opening-journey.test.ts, and tests/ui/game-screen-accessibility.test.ts for existing board and accessibility expectations.
• Search the registered docs for the job-board reconciliation and Cycle 49 playtest follow-up before implementing.

Security considerations

None — local game state and deterministic UI/store behavior only.

Estimation

Estimated L, landed L — accurate

Handoff

The Cycle 49 Playwright playtest found that the Upgrades surface exposes eleven rows marked “Coming later” while only Linter is live. This is a concrete, locally reproducible completeness defect: the player-facing list promises content the runtime cannot deliver.

Effort estimate: M

Scope

• 1. Audit every entry in the tooling/upgrade catalog against its real store action, progression effect, persistence path, and rendered UI path.
• 2. Write a concise, repository-local audit at docs/audits/game-systems-completeness-c51.md with one wire-up-or-cut verdict per entry and evidence paths.
• 3. Keep only entries whose action is runtime-wired and testable in the player-facing Upgrades surface. Remove or hide dead “Coming later” rows; do not delete reusable internal definitions unless the audit proves they are obsolete.
• 4. Preserve the current Linter purchase flow and its economy/save behavior.
• 5. Add focused regression tests proving every rendered upgrade has a reachable action and that the player-facing surface contains no unimplemented placeholder rows.
• 6. Register the audit document in PAPI's document registry when the report is final.

Out of scope

• Do not invent new upgrade mechanics, decide a future product roadmap, integrate RevenueCat/ads/OneSignal/Stripe/Layers, change public access, redesign typography or visuals, or implement any upgrade whose runtime contract is not already present. A planned upgrade may remain as internal configuration, but it must not appear as a player-facing actionable row.

Acceptance criteria

• Every upgrade entry is classified as wired or cut/hidden in docs/audits/game-systems-completeness-c51.md with source and test evidence.
• No player-facing Upgrades row is marked “Coming later” or otherwise claims an unavailable action.
• The currently wired Linter upgrade remains visible, purchasable, persisted, and covered by existing economy/save tests.
• Focused tests cover the catalog-to-rendered-action contract and pass.
• npm run typecheck, the applicable Jest tests, npm test, npm run export:web, and git diff --check pass.
• The final diff contains no provider, account, device, store, production, public-exposure, or human-approval dependency.

Files likely touched

• src/economy/config.ts (edit)
• src/game/store.ts (edit)
• src/ui/GameScreen.tsx (edit)
• src/ui/tooling-shop.ts (edit)
• tests/economy/curve.test.ts (edit)
• tests/economy/guardrails.test.ts (edit)
• tests/persistence/save.test.ts (edit)
• tests/ui/tooling-shop.test.ts (edit)
• tests/ui/game-screen-accessibility.test.ts (edit)
• docs/audits/game-systems-completeness-c51.md (edit)

Security considerations

None — no external service, credential, account, or data-access change.

Estimation

Estimated M, landed M — accurate

Handoff

The playtest could inspect navigation tabs but could not discover the Hire agent action as a semantic control, which blocks reliable keyboard use and objective browser QA.

Effort estimate: S

Scope

• Add explicit accessible roles, names, and disabled state to the primary game action Pressables in src/ui/GameScreen.tsx: Hire agent, Assign this collaborator, Review work, Ship now, and Buy Linter.
• Preserve existing game rules, labels, layout, and enabled/disabled behavior.
• Add a focused UI/source contract test in tests/ui/game-screen-accessibility.test.ts (or the nearest existing UI test file) that verifies each primary action has the expected accessibility contract.
• Add or update a deterministic browser-checkable test path if the repository already has one; do not add a new test framework or external service.

Out of scope

• Do not redesign the game UI or change copy.
• Do not change native-only behavior, game economics, or action availability.
• Do not claim human visual acceptance; the acceptance is semantic and keyboard/objective.

Acceptance criteria

• The web-rendered Hire agent, Assign this collaborator, Review work, Ship now, and Buy Linter controls expose role=button and a stable accessible name.
• Disabled actions expose disabled state and remain non-activatable; enabled actions retain their current behavior.
• A focused automated test proves the accessibility contract and passes with the repository test command.
• TypeScript and the relevant UI test suite pass.

Files likely touched

• src/ui/GameScreen.tsx (edit)
• tests/ui/game-screen-accessibility.test.ts (edit)

Pre-build verification

• src/ui/GameScreen.tsx
• tests/ui/layout.test.ts
• package.json
• docs/GAME_BRIEF.md and docs/PAPI_TEAM_PROTOCOL.md via doc_search or the docs index

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

At the 430x932 playtest viewport, milestone feedback rendered over the upper status chrome. This is an objective layout collision that can be removed without changing milestone logic.

Effort estimate: S

Scope

• Move the milestone toast into normal layout flow below the status chrome, or introduce an explicit reserved offset derived from the chrome layout; use the simplest responsive solution that prevents overlap at the canonical 430x932 viewport.
• Keep the toast non-blocking, readable, and announced through the existing accessibilityLiveRegion.
• Add a deterministic layout/source contract test proving the toast is anchored below the chrome and cannot cover status cards or primary controls.

Out of scope

• Do not change milestone unlock conditions, duration, copy, animation, or game progression.
• Do not redesign the full status/header layout.
• Do not rely on a human screenshot review as the only proof.

Acceptance criteria

• The milestone toast is rendered below the status chrome in the fixed 430x932 web layout and does not overlap Cash, AI tokens, Reputation, or primary controls.
• The toast remains pointer-events non-blocking and keeps its polite live-region announcement.
• A deterministic UI/layout test proves the non-overlap contract; the existing milestone tests remain green.
• TypeScript and the relevant UI test suite pass.

Files likely touched

• src/ui/GameScreen.tsx (edit)
• src/ui/layout.ts (edit)
• tests/ui/layout.test.ts (edit)

Pre-build verification

• src/ui/GameScreen.tsx
• src/ui/layout.ts
• tests/ui/layout.test.ts
• tests/ui/milestones.test.ts
• docs/GAME_BRIEF.md and docs/PAPI_TEAM_PROTOCOL.md via doc_search or the docs index

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

At maximum tech debt the current path overstates failure risk by 16x.

Effort estimate: S

Scope

• Trace src/game/store.ts and src/game/incidents.ts; replace the max-debt flat 50% path with the existing risk-scaled incident probability; keep displayed and applied probability derived from the same source; add boundary tests.

Out of scope

• No incident redesign, monetization, analytics, new incident types, or provider integrations.

Acceptance criteria

• Maximum tech debt uses configured risk-scaled probability.
• Displayed and applied probabilities agree.
• Focused and full tests pass.

Files likely touched

• src/game/store.ts; src/game/incidents.ts; tests/game/incidents.test.ts; tests/game/techDebt.test.ts (edit)

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

The retained-process resume path can award unbounded elapsed-time earnings instead of using the configured offline contract and cap.

Effort estimate: M

Scope

• Trace App.tsx, src/ui/GameScreen.tsx, and src/game/store.ts; route retained-process resume through the existing persisted-timestamp offline contract; preserve foreground ticking; add long- and short-interval regression coverage.

Out of scope

• No cap changes, subscription changes, payout changes, save-schema changes, backend, analytics, or device workaround.

Acceptance criteria

• Long resume cannot exceed configured offline maximum.
• Short valid resume still settles bounded earnings.
• Existing foreground and persistence tests remain green.

Files likely touched

• App.tsx; src/ui/GameScreen.tsx; src/game/store.ts; existing offline/time/persistence test location (edit)

Security considerations

None — no security-relevant changes.

Estimation

Estimated M, landed M — accurate

Handoff

Players currently lack deterministic guidance when an upgrade, hire, milestone, or idle-agent action is available. Small state-derived badges improve the next-action loop without adding external dependencies.

Effort estimate: M

Scope

• Derive badge visibility from existing local game state and render the existing roadsign indicators for the Upgrades, team, and milestone surfaces. Show the Upgrades badge when an upgrade is affordable; show team or hire guidance when a hire is affordable or an agent is idle while jobs are open; show milestone guidance when a milestone has unlocked and its reward is claimable. Clear each badge immediately after the corresponding action is completed. Add deterministic state tests or extend `scripts/playtest.cjs` to cover each positive condition and its cleared state. Done means a fresh local save exposes no false badges, each eligible condition produces the correct badge, and taking the action removes it.

Out of scope

• Do not redesign the roadsign artwork, add animations, change navigation structure, introduce notifications, or modify economy thresholds.

Acceptance criteria

• Badge predicates use existing local state and do not introduce duplicated economy rules.
• Affordable upgrades, eligible hires, claimable milestones, and idle agents with open jobs produce the intended badges.
• Badges are absent when no action is available and clear after the action is taken.
• Deterministic tests cover both visible and cleared states.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• `src/ui/GameScreen.tsx` (edit)
• `scripts/playtest.cjs` (edit)

Security considerations

None — no security-relevant changes

Estimation

Estimated M, landed M — accurate

Handoff

The current milestone reward is an invisible percentage multiplier. A deterministic cash payout makes progression immediately legible and directly improves the local economy loop.

Effort estimate: M

Scope

• Add an immediate cash payout to each milestone unlock using a simple linear formula based on milestone index and the existing milestone reward configuration. Preserve the current percentage multiplier alongside the new payout unless the existing implementation proves it is already replaced. Show the payout amount on the milestone row before unlock, and ensure the payout is granted exactly once when the milestone crosses its unlock threshold. Add focused deterministic tests for payout scaling, preview values, and duplicate-unlock protection. Done means a local save can unlock a milestone, receive the expected cash, and retain the existing multiplier behavior after reload.

Out of scope

• Do not redesign the milestone system, rebalance unrelated rewards, add a new currency, change save architecture, or touch RevenueCat, ads, analytics, or store integration.

Acceptance criteria

• Milestone payout follows a documented linear formula based on milestone index.
• The milestone UI previews the payout before unlock and shows the unlocked reward clearly.
• Each milestone awards cash once, including after reload or repeated evaluation.
• Existing milestone multiplier behavior remains covered by tests.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• `src/ui/GameScreen.tsx` (edit)
• `tests/economy/guardrails.test.ts` (edit)

Security considerations

None — no security-relevant changes

Estimation

Estimated S, landed S — accurate

Handoff

Recent player feedback identifies visual incohesion, and the existing token module has palette coverage but no typography contract. This is the substrate needed for either the current AD-17 direction or a future display-face decision.

Effort estimate: M

Scope

• Define and implement a compact typography system.
• Read PRODUCT.md for product purpose, users, and design principles, and DESIGN.md for visual tokens. Run impeccable init if either file is absent, then use the frontend-design skill.
• Add 4–6 named typography roles to src/ui/tokens.ts, covering display, heading, body, label, and mono/data use.
• Choose intentional family and weight pairs while keeping the display family replaceable; do not decide the AD-17 pixel-face conflict inside this task.
• Migrate all ad-hoc fontSize, fontWeight, and fontFamily literals in src/ui/ to the token roles.
• Add a source-contract test preventing new raw typography literals outside the token module.
• Validate small-screen legibility in the local web export.
• Done means the UI has one discoverable typography contract and no remaining ad-hoc typography literals in src/ui/.

Out of scope

• Do not resolve the pixel-versus-modern typography decision, redesign icons, or perform unrelated surface/card redesign.

Acceptance criteria

• Named typography roles and scale are defined in src/ui/tokens.ts.
• All src/ui/ typography literals are migrated to the token roles.
• Source-contract test detects raw typography literals outside the token module.
• Result remains legible at small mobile sizes.
• Visually verify rendered output in the browser and provide the localhost URL or screenshot for review.
• No raw IDs, abbreviations, or jargon are visible without human-readable labels or tooltips.
• Findings doc is drafted and saved to docs/research/ before submitting follow-up ideas.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.
• RESEARCH OUTPUT
• Deliverable: docs/research/typography-system-findings.md (draft path)
• Review status: pending owner approval
• Follow-up tasks: DO NOT submit to backlog until owner confirms findings are actionable

Files likely touched

• src/ui/tokens.ts (edit)
• src/ui/GameScreen.tsx (edit)
• tests/ui/typography.test.ts (edit)
• PRODUCT.md (edit)
• DESIGN.md (edit)
• docs/research/typography-system-findings.md (edit)

Security considerations

None — no security-relevant changes.

Estimation

Estimated M, landed M — accurate

Handoff

Player feedback identifies excessive nested cards. This task is now an evidence-first, locally verifiable Playwright investigation so the containment rules are derived from the real rendered web surface rather than taste or memory.

Effort estimate: M

Scope

• Use Playwright against the canonical local Expo web origin at http://127.0.0.1:8081 with a fixed 390x844 viewport and a fresh save.
• Exercise the opening Play surface plus the reachable Upgrades, More, and information-surface states. Inventory visible semantic groups and their nested decorative surfaces (background fills, borders, radii, shadows, and overlays).
• Record the evidence in docs/research/surface-hierarchy-findings.md: tested route/state, screenshot path, parent/child surface relationship, whether the chrome earns its containment, and the smallest rule that would remove unnecessary nesting.
• Define a small, testable containment contract: when a surface may introduce its own chrome, when content should inherit its parent surface, and how overlays/popovers must escape later sibling content.
• Use Playwright hit-testing and bounding-box assertions for objective checks; capture screenshots for every investigated state under the existing ignored artifact area. Reuse the task-217 Playwright setup when available; do not add runtime dependencies.
• Run the applicable local gates and report the exact evidence in the build report.

Out of scope

• Do not refactor GameScreen.tsx, migrate tokens, redesign icons, or change runtime UI behavior in this task.
• Do not create implementation follow-up tasks before the findings are complete.
• Do not use human visual taste as the only acceptance criterion; every finding must cite a rendered state and a measurable relationship.
• Do not deploy or widen public access.

Acceptance criteria

• A Playwright run against the canonical 390x844 web surface covers the opening Play state and the reachable Upgrades, More, and information-surface states, with deterministic fresh-save setup.
• The run captures an ignored screenshot for each investigated state and records the artifact paths in docs/research/surface-hierarchy-findings.md.
• The findings document contains a complete inventory table of investigated nested surfaces, including parent/child bounds, chrome signals, and an evidence-backed keep/remove/inherit recommendation.
• The document defines and applies explicit containment rules, including a rule for popovers/overlays to remain above later sibling content.
• The Playwright checks use bounding-box or hit-testing assertions for the objective relationships and fail on missing states, viewport loss, or unexpected occlusion.
• npm test, npx tsc --noEmit, npm run export:web, the Playwright investigation, and git diff --check pass; no runtime source behavior is changed.
• The final build report distinguishes objective local evidence from any owner decision still needed before implementation.

Files likely touched

• docs/research/surface-hierarchy-findings.md (edit)
• scripts/surface-hierarchy-audit.cjs (edit)
• package.json (only if an existing opt-in script must be exposed; do not add a second Playwright dependency) (edit)
• .gitignore (only if the existing ignored artifact rule does not cover the audit output) (edit)

Pre-build verification

• src/ui/GameScreen.tsx
• src/ui/tokens.ts
• src/ui/explanations.ts
• docs/testing/playtest.md
• docs/INDEX.md and the docs registry for prior surface/stacking findings

Security considerations

None — no security-relevant changes.

Estimation

Estimated M, landed M — accurate

Handoff

AD-27 prioritizes launch-visible player sharing, but the safest immediately deliverable path is the task’s explicitly permitted textual company summary fallback while public infrastructure remains unapproved.

Effort estimate: M

Scope

• Implement the smallest safe share surface: an allowlisted company-summary model plus copy/native-share text output from the existing game UI.
• Read the referenced persistence, analytics, deployment, and build-in-public documents before implementation.
• Derive the summary only from approved save fields: username, company name/icon, stage, safe headline stats, team size, upgrades, prestige history, unlocked milestones, game version, and generated-at timestamp.
• Exclude raw save serialization, credentials, analytics identifiers, internal timers, debug fields, and mutation-capable data.
• Format a concise editable message suitable for native sharing and social posts without claiming that a public URL exists.
• Add focused tests for field allowlisting, deterministic formatting, and read-only behavior.
• Done means a player can copy/share a truthful company summary without exposing private save data.

Out of scope

• Do not create, deploy, or expose a public backend, public endpoint, link shortener, account system, retention policy, or public destination. Do not add a link that cannot be verified as safe and immutable.

Acceptance criteria

• Player can copy/share an allowlisted company summary from the existing game surface.
• Summary includes the approved identity, progression, safe stats, version, and timestamp fields.
• Tests prove private/debug fields and raw save data are excluded.
• Sharing cannot mutate or write back to local game state.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/persistence/save.ts (edit)
• src/ui/GameScreen.tsx (edit)
• src/analytics/events.ts (edit)
• tests/sharing/company-summary.test.ts (edit)

Security considerations

Treat the summary as a privacy boundary. Use an explicit allowlist, never include secrets or identifiers, and ensure the share path is read-only.

Estimation

Estimated M, landed M — accurate

Handoff

Effort estimate: M

Scope

• RESEARCH FIRST: choose the UI driver for the Expo web export — evaluate Playwright (headless, screenshot, CI-friendly, natural fit for the existing web-export gate) against Maestro (native, real-device value later). Record the decision and rationale in the build report.
• Build 2-3 scripted journeys against the web export or dev server on a FRESH save: (a) FTUE walk — accept first offer, first assignment, first hire, asserting the ~35s first-meaningful-decision window from docs/design/ftue.md and that every advertised control responds; (b) info-surface sweep — open each 'i' explanation and assert the popover's bounding box is not occluded by later content (regression net for task-215); (c) visual smoke — screenshot each journey beat; assert the header logo region composites over the background rather than rendering a solid box (regression net for task-214).
• Deterministic where possible: seed state via the existing save fixtures / economy simulator checkpoints (src/economy/simulator.ts, task-160/165).
• Wire as an opt-in npm script (npm run playtest) with screenshots written to a gitignored artifacts dir. Do NOT add it to the default jest gate — separate runner so the fast test loop (task-128) stays fast.
• Document the smoke flow in the repo (README section or docs/) so any contributor can run it before a closed-testing build.

Out of scope

• Dev-dependency only — nothing ships in the app bundle; no new runtime dependencies (project small-dependency convention).
• No fixing of bugs the bot finds (task-214/215 own today's known ones) — the bot reports, humans and their tickets fix.
• No native-device automation in this task — web export only; note Maestro/device as follow-up if the research recommends it.
• No CI/release-gate integration yet — opt-in script first, promotion to the gate is a follow-up once stable.

Acceptance criteria

• Driver decision recorded with rationale (Playwright vs Maestro) in the build report
• npm run playtest exists and runs the journeys headlessly against the web export — host runs `npm run | grep -q playtest && echo PASS`
• FTUE journey asserts the first meaningful decision is reachable and all advertised first-session controls respond
• Info-surface sweep asserts explanation popovers are not occluded (fails today if task-215 is unfixed — mark as expected-fail or run after 215 merges, and say which in the report)
• Screenshots captured per beat to a gitignored artifacts directory
• npm test and npx tsc --noEmit still pass; the playtest runner is NOT part of the default jest gate

Estimation

Estimated M, landed M — accurate

Handoff

Pairs with task-178 as the second half of this cycle's late-game automation theme — the same AD-22 manual-to-automation payoff applied to AD-14's repeatable prestige. It builds after task-178 because it takes the following schemaVersion (20) and reuses the late-game gating pattern task-178 establishes on the same Core branch.

Effort estimate: S

Scope

• Deliverable: an unlockable Auto-Prestige toggle that automatically re-triggers the repeatable project-sale exit once the player has proven they understand the manual reset trade-off. Done looks like: a player who has completed at least one manual project-sale exit can enable Auto-Prestige, the sale re-triggers automatically when eligibility is met, and the summary/feedback surface still communicates each sale; the toggle is off by default and invisible-or-locked before the gate.
• Gate: unlocked only after the player has performed the manual project-sale exit at least once (derive from existing exit/prestige history state — the reference mechanic in the task notes unlocks automation "once a player proves they understand the manual reset trade-off"). This is the repeatable mid-game project sale of AD-14, NOT the company-level Acquisition/IPO exit — the endgame reset stays strictly manual.
• Persisted state: auto-prestige enabled boolean in SaveState at schemaVersion 20 with a forward-only migration defaulting to off, same commit. Stacks on task-178's schema 19 on the shared Core branch.
• Trigger logic: in the tick path, when enabled, gated, and the existing sale-eligibility predicate passes, invoke the existing pure sale/exit function — never a duplicated implementation. If the reference mechanic's configurable delay is cheap to add, expose a small fixed set of delay options from config; if it adds complexity, ship on/off only and note the delay ladder as a possible follow-up in the build report.
• The existing exit/sale feedback (summary, payout, achievement feel per task-99's exit-sequence work) must still fire on automated sales — automation must not make sales silently invisible.
• Tests: (a) toggle unavailable before first manual sale, (b) enabled auto-prestige triggers exactly when manual eligibility holds and never otherwise, (c) persistence through save/load with the schema 20 migration, (d) company-level exit is never auto-triggered.

Out of scope

• Never auto-trigger the company-level Acquisition/IPO prestige — manual only, without exception.
• No monetization of the toggle in this task (a future task may fold it into the tooling/PAPI ladder).
• No changes to sale eligibility rules, Equity math, or Founder Tree — consume them as-is.
• No UI redesign of the exit sequence.

Acceptance criteria

• Gate derives from existing exit/prestige history; toggle locked until one manual project-sale exit has occurred
• SaveState field at schemaVersion 20, forward-only migration defaulting to off, same commit, stacked on task-178's 19
• Automated sale invokes the existing pure sale function and existing feedback surfaces still fire
• Company-level exit is provably never automated (test)
• npm test and npx tsc --noEmit pass
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation

Files likely touched

• src/persistence/save.ts, src/game/store.ts (or the store module), src/economy/rules.ts, src/economy/config.ts, src/ui/GameScreen.tsx, tests under tests/ mirroring the existing store/persistence layout (edit)

Pre-build verification

• Read src/persistence/save.ts after task-178's commit to confirm schema 19 is in place and copy its migration pattern for 20.
• Read the exit/prestige code paths (store exitCompany, exitEligibility, buildExitSave — from task-71/task-99's contracts) and locate the separate repeatable project-sale function to confirm which pure function this toggle invokes.
• Read src/economy/rules.ts for the sale-eligibility predicate.
• Docs sweep: doc_search the prestige/exit design docs (docs/design/ — exit/prestige contract from task-71, project lifecycle from task-154) and confirm no auto-prestige capability already exists (grep -ri "auto.?prestige" src/).

Security considerations

None — no security-relevant changes; local deterministic game state only.

Handoff

This P1 legibility bug affects every explanation surface and remains after task-205’s shared layer contract. Fixing it locally protects the first-session experience without requiring providers, devices, accounts, deployment, or public access.

Effort estimate: S

Scope

• Deliver a minimal GameScreen stacking fix so an opened explanation popover renders above later sibling sections in the web export and remains readable.
• REPRODUCE:
• 1. Launch the local web export on the canonical development origin.
• 2. Open any “i” explanation card above another content section.
• 3. Observe that later sibling content paints over the explanation card.
• ROOT CAUSE:
• The explanation card’s zIndex is scoped inside its parent row, so later sibling sections can paint above the entire row despite the card’s higher child zIndex.
• MINIMAL FIX:
• Use the existing `layered()` / `GAME_LAYERS` contract to raise the hosting row or equivalent containing surface while an explanation is open. Change only the stacking behavior required for this defect; do not refactor unrelated GameScreen layout.
• REGRESSION TEST:
• Add a deterministic source-wiring or style-contract test proving the open explanation state applies the elevated row/container layer, and manually verify the rendered web export with an explanation opened above later content.
• Read `PRODUCT.md` for product purpose, users, and design principles, and `DESIGN.md` for visual tokens before changing the UI. Use the `frontend-design` skill for implementation.

Out of scope

• Do not redesign the explanation-card visuals or copy, replace the entire overlay architecture with a portal, modify the header logo asset owned by task-214, or perform a broad z-index refactor.

Acceptance criteria

• An opened explanation popover remains visibly above later sibling sections in the local web export.
• The fix uses the existing named layering contract where practical and does not introduce unrelated raw z-index values.
• A deterministic regression test proves the open explanation state applies the required container/row stacking behavior.
• Visually verify the rendered output in the browser and provide the localhost URL or a screenshot for review.
• No raw IDs, abbreviations, or jargon are exposed to players without human-readable labels or tooltips.
• Fix is targeted — no unrelated code changed.
• Regression test confirms the bug no longer reproduces.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• `src/ui/GameScreen.tsx` (edit)
• `src/ui/layout.ts` (edit)
• `tests/ui/layout.test.ts` (edit)

Pre-build verification

• Read `src/ui/GameScreen.tsx` and confirm the current explanation wrapper/card hierarchy and task-205’s latest wiring.
• Read `src/ui/layout.ts` and confirm the existing `layered()` helper and `GAME_LAYERS` contract.
• Read `tests/ui/layout.test.ts` to reuse the existing layering-test pattern before adding coverage.
• Check `docs/INDEX.md` and use `doc_search` for any status:final or prior task documentation covering explanation popovers, stacking, or task-205. If more than 80% of the fix already exists, report “already built” instead of reimplementing.

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

The current icon surfaces are an inspectable local asset/configuration gap. Fixing them improves recognition across the web export and app packaging without requiring provider, device, account, or store access.

Effort estimate: S

Scope

• Use the existing Vibe Tycoon logo assets as the source of truth. Audit and update `assets/icon.png`, `assets/favicon.png`, `assets/android-icon-foreground.png`, `assets/android-icon-background.png`, `assets/android-icon-monochrome.png`, and `assets/splash-icon.png` only where needed. Ensure `app.json` references the intended canonical outputs, preserve adaptive-icon alpha and safe margins, and remove superseded files only after confirming there are no remaining references. Done means the exported web bundle and Expo configuration resolve the intended assets without broken references.

Out of scope

• Do not redesign the logo, create a new brand direction, optimize unrelated runtime artwork, change splash behavior beyond the requested asset references, or perform store/device submission validation.

Acceptance criteria

• `app.json` points to the intended favicon, primary icon, and Android adaptive-icon assets.
• The primary icon and foreground layer preserve real transparency without an unintended white halo.
• Background and monochrome layers remain intentional and valid for Expo adaptive icons.
• Dimensions, alpha behavior, and small-size readability are checked on light and dark inspection surfaces.
• Only one canonical source asset and the required platform derivatives remain referenced.
• `npm run typecheck` passes.
• `npm test` passes.
• `npm run export:web` passes with no broken asset references.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• `app.json` (edit)
• `assets/icon.png` (edit)
• `assets/favicon.png` (edit)
• `assets/android-icon-foreground.png` (edit)
• `assets/android-icon-background.png` (edit)
• `assets/android-icon-monochrome.png` (edit)
• `assets/splash-icon.png` (edit)

Security considerations

None — no security-relevant changes

Estimation

Estimated S, landed S — accurate

Handoff

Recent work fixed return-overlay containment inside the playable shell, but the remaining info surfaces still use scattered layer values. A small shared layering contract can make toast, payout, overlay, content, navigation, and modal ordering deterministic.

Effort estimate: S

Scope

• Read `PRODUCT.md` for product purpose, users, and design principles, and `DESIGN.md` for visual tokens and accessibility baselines. Use the `frontend-design` skill for implementation. Audit `src/ui/GameScreen.tsx` and the native modal boundary in `src/ui/exit-sequence.tsx`. Add the smallest shared layer constants in `src/ui/layout.ts`, apply them to the existing GameScreen surfaces, and keep the native `Modal` as the highest-priority exit surface. Done means milestone feedback remains above gameplay content, payout feedback remains above its agent row, the offline return overlay blocks gameplay without covering the native exit modal, and navigation remains usable when no modal is active.

Out of scope

• Do not redesign the visual system, rewrite modal content, introduce a new overlay framework, change gameplay behavior, or alter the return-overlay placement already delivered by task-201.

Acceptance criteria

• A named shared layer contract defines the intended ordering for gameplay content, payout feedback, return overlay, and milestone toast.
• Existing surfaces use the shared contract rather than unexplained scattered z-order values.
• Milestone toasts render above gameplay content.
• Payout feedback renders above the relevant agent row without covering unrelated controls.
• The offline return overlay blocks underlying gameplay interaction and remains below the native exit modal.
• No relevant info box is clipped, hidden behind a ScrollView/card, or incorrectly covers navigation.
• `tests/ui/layout.test.ts` covers the layer ordering contract.
• `npm run typecheck` passes.
• `npm test` passes.
• `npm run export:web` passes.
• Visually verify the rendered local web export at the canonical local URL or provide a screenshot.
• No raw IDs, abbreviations, or jargon are introduced as visible labels or tooltips.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• `src/ui/layout.ts` (edit)
• `src/ui/GameScreen.tsx` (edit)
• `tests/ui/layout.test.ts` (edit)

Security considerations

None — no security-relevant changes

Estimation

Estimated S, landed S — accurate

Handoff

This is a small, deterministic UI defect that can be corrected and regression-tested without changing the game loop.

Effort estimate: S

Scope

• Inspect the existing offline return overlay and playable shell layout.
• Constrain the return message panel to the playable game area with readable width, margins, and safe-area behavior.
• Preserve modal input blocking, return-summary content, close/continue accessibility, and existing animation behavior.
• Add a focused layout/source contract test if the current test seam cannot render the full layout.

Out of scope

• No gameplay, save-shape, navigation, provider, device, account, or public-link changes.
• Do not claim visual acceptance beyond local structural/browser evidence.

Acceptance criteria

• The offline return panel is centered within the playable shell rather than the full viewport.
• The panel keeps readable max width, margins, and safe-area behavior on phone and web layouts.
• Modal input blocking and accessible dismissal/continuation remain intact.
• Focused tests, full tests, typecheck, and diff checks pass.

Files likely touched

• src/ui/GameScreen.tsx (edit)
• src/ui/layout.ts (edit)
• tests/ui/offline-overlay.test.tsx (edit)

Pre-build verification

• Read src/ui/GameScreen.tsx around the offline summary/overlay component.
• Read src/ui/layout.ts and tests/ui/layout.test.ts.
• Sweep the player manual and prior offline-summary tasks for the shipped contract.

Security considerations

None — layout-only change.

Estimation

Estimated S, landed S — accurate

Handoff

Every release must prove both metadata synchronization and website delivery; a small deterministic smoke check makes that release contract repeatable.

Effort estimate: S

Scope

• Add a local verification script/test that accepts an expected vX.Y.Z release and checks the live private website HTML plus its referenced web bundle for the expected version string.
• Keep the check read-only: it must not deploy, mutate remote state, or expose source.
• Document the release gate order: metadata check, tag-triggered deployment, HTTP 2xx, and bundle-version verification.
• Reuse the existing deployment URL/base path and release metadata tooling.

Out of scope

• No new hosting, credentials, SSH behavior, public route, source publication, or deployment replacement.
• Do not make live verification a prerequisite for ordinary unit tests.

Acceptance criteria

• The smoke check rejects a missing/mismatched version and passes for a matching deployed bundle.
• The check follows HTML script references and verifies the expected version without requiring source access.
• Documentation names the exact release gate order and failure interpretation.
• Existing tests, typecheck, and diff checks pass.

Files likely touched

• scripts/verify-live-release.mjs (edit)
• tests/release/verify-live-release.test.mjs (edit)
• docs/SERVER_DEPLOYMENT.md (edit)
• package.json (edit)

Pre-build verification

• Read scripts/release-version.mjs and scripts/deploy-web.sh.
• Read .github/workflows/deploy-web.yml and tests/release/release-version.test.mjs.
• Sweep docs/SERVER_DEPLOYMENT.md and existing deployment tests before adding a new check.

Security considerations

The check is read-only and uses no credentials; it must not log secrets or publish responses.

Estimation

Estimated S, landed S — accurate

Handoff

The app now ships several large local art assets; a bounded inventory and reversible optimization pass can reduce download/storage cost without changing gameplay.

Effort estimate: M

Scope

• Inventory only runtime-referenced raster assets, recording dimensions, format, alpha needs, and byte size before changes.
• Optimize only assets where the chosen native tool preserves transparency, crisp edges, and the existing visual identity.
• Keep one canonical asset per immutable identity, update every import/reference, and record recovered bytes and any format decisions in the owning asset README.
• Run web export and inspect representative asset outputs for broken references or obvious scaling/alpha regressions.

Out of scope

• No new art direction, generated asset family, gameplay, provider, device, public, account, or monetization work.
• Do not delete an asset unless all references are updated and the replacement is verified.
• Do not claim broad device acceptance without a bounded local/browser check.

Acceptance criteria

• The before/after inventory identifies changed assets, dimensions/formats, and recovered bytes.
• Runtime references resolve without duplicate canonical assets.
• Web export succeeds and representative local asset output remains readable with correct alpha/scaling.
• Typecheck, relevant tests, and diff checks pass.

Files likely touched

• assets/characters/README.md (edit)
• assets/offices/README.md (edit)
• assets/<only verified runtime assets> (edit)
• tests/deployment/deploy-web.test.ts (edit)

Pre-build verification

• Read assets/characters/README.md and assets/offices/README.md.
• Read src/ui/GameScreen.tsx and app.json for runtime asset references.
• Sweep the asset/design docs and prior asset commits before changing files.

Security considerations

None — local static assets only.

Estimation

Estimated M, landed M — accurate

Handoff

The shipped UI has grown through several local feature additions; a bounded interaction audit can identify the smallest polish changes before more surface area is added.

Effort estimate: S

Scope

• Audit the current GameScreen interaction surfaces and classify them as primary action, secondary action, tab, selectable choice, informational panel, or decorative content.
• Produce a focused design note with the highest-value interaction corrections, including web text-selection behavior and preserved selection for intentionally copyable content.
• Implement only the smallest clearly mechanical affordance correction discovered by the audit; leave ambiguous visual redesign as follow-up work.
• Add or update a contract test for any mechanical correction.

Out of scope

• No new gameplay, navigation model, public sharing, account, provider, or monetization surface.
• Do not redesign the whole visual system or make subjective human-play claims.

Acceptance criteria

• The audit names the current interaction classes and the prioritized corrections.
• Ordinary informational/decorative UI is not exposed as an accidental action or copy surface where the platform supports a deterministic correction.
• Intentionally selectable controls and copyable content remain usable.
• Focused tests, typecheck, and diff checks pass.

Files likely touched

• src/ui/GameScreen.tsx (edit)
• src/ui/tokens.ts (edit)
• tests/ui/button-affordances.test.tsx (edit)
• docs/design/ui-affordances.md (edit)

Pre-build verification

• Read src/ui/GameScreen.tsx and tests/ui/company-profile.test.ts.
• Read src/ui/tokens.ts and docs/player-manual.md.
• Sweep the registered UI/design docs and prior interaction tasks before adding a new rule.

Security considerations

None — no access, network, or persisted-data changes.

Estimation

Estimated S, landed S — accurate

Handoff

The small-team fantasy needs a bounded design contract before any runtime skill system is attempted; documenting the choices locally is safe and independently reviewable.

Effort estimate: M

Scope

• Define a compact, player-readable mastery model for repeated work, coaching, specialization, cross-training, diminishing returns, and substitution when an agent is unavailable.
• Reuse existing Cash, AI Tokens, Reputation, job domains, agent roster, and progression-stage vocabulary.
• Specify the smallest set of deterministic state transitions, player decisions, and future implementation seams.
• Reconcile the design with the existing progression, token, and job-review documents and register/update the owning design document.

Out of scope

• No runtime skill counters, economy rebalance, provider integration, account/device work, monetization, or human-play acceptance.
• Do not add a fourth resource or a spreadsheet-heavy roster.

Acceptance criteria

• The design defines mastery, specialization, cross-training, diminishing returns, and substitution in plain player-facing language.
• The design reuses the existing three-resource and one-progression-ladder contracts.
• The document names future implementation boundaries and at least one reversal/tuning signal.
• The document is registered, internally consistent, and passes the repository’s documentation checks.

Files likely touched

• docs/design/ai-skills-system.md (edit)
• docs/design/progression-ladder.md (edit)
• tests/game/personalities.test.ts (edit)
• tests/economy/report-shape.test.ts (edit)

Pre-build verification

• Read docs/design/ai-skills-system.md.
• Read docs/design/progression-ladder.md, docs/design/token-economy.md, and docs/design/core-loop.md.
• Sweep the registered design docs and related agent-capability tasks before authoring.

Security considerations

None — design-only local documentation.

Estimation

Estimated M, landed M — accurate

Handoff

This is a deterministic local identity feature that can share the existing profile picker contract while remaining independent of public sharing and monetization.

Effort estimate: M

Scope

• Reuse the profile identity picker’s established selection, fallback, accessibility, and save conventions.
• Define exactly 20 canonical company-icon IDs with repository-owned assets or newly authored local artwork and recorded provenance.
• Persist only the canonical company-icon ID through the existing forward-only save migration path.
• Render the selected icon on existing company/stage surfaces and add tests for cardinality, selection, save/reload, unknown IDs, fallback, and responsive/accessibility behavior.

Out of scope

• No uploads, public link, account, network storage, new backend, provider integration, or monetization.
• Do not replace the approved logo or duplicate immutable assets.

Acceptance criteria

• Exactly 20 canonical company-icon IDs exist and have accessible labels.
• Selection persists by ID and unknown values fall back safely.
• Existing company/stage surfaces render the chosen icon without gameplay changes.
• Tests, typecheck, and diff checks pass.

Files likely touched

• src/persistence/save.ts (edit)
• App.tsx (edit)
• src/ui/GameScreen.tsx (edit)
• assets/offices/README.md (edit)
• tests/persistence/save.test.ts (edit)
• tests/ui/company-icon-picker.test.tsx (edit)

Security considerations

No network or account surface; only allowlisted local IDs are persisted.

Estimation

Estimated M, landed M — accurate

Handoff

The explanation layer improves comprehension using existing local game rules and directly supports the current player-facing manual without external services.

Effort estimate: M

Scope

• Audit the visible surfaces in App.tsx, src/ui/GameScreen.tsx, src/ui/job-card.ts, src/ui/tooling-shop.ts, src/ui/milestones.ts, and src/ui/action-feedback.ts.
• Create one shared, data-driven explanation catalog for concepts that already exist in code, starting with resources, jobs, upgrades, incidents, milestones, and blocked actions.
• Add a consistent tap/click info affordance with keyboard focus and screen-reader labeling; keep critical information visible outside the tooltip.
• Keep copy in the shared catalog and update docs/player-manual.md only where the implemented vocabulary is now authoritative.
• Add focused tests for catalog coverage, locked/blocked explanations, keyboard access, and no-op behavior when no explanation exists.

Out of scope

• Do not invent new economy rules, add new resources, change monetization copy, or implement provider/account/device features.
• Do not rewrite the entire UI or hide required information behind hover-only behavior.

Acceptance criteria

• Every implemented surface in scope has either an explanation or an explicit documented no-op.
• Explanations state what the concept is, how it changes, why it matters, and the next action using current behavior only.
• The affordance works with touch, keyboard, and assistive labels.
• Manual and shared catalog remain aligned.
• Focused tests, full local tests, typecheck, and diff checks pass.

Files likely touched

• App.tsx (edit)
• src/ui/GameScreen.tsx (edit)
• src/ui/action-feedback.ts (edit)
• src/ui/job-card.ts (edit)
• src/ui/tooling-shop.ts (edit)
• src/ui/milestones.ts (edit)
• docs/player-manual.md (edit)
• tests/ui/explanations.test.tsx (edit)

Security considerations

None — local copy and presentation behavior; no data or access changes.

Estimation

Estimated M, landed M — accurate

Handoff

This is an XS UI correctness fix that prevents decorative art from intercepting player input without changing game behavior.

Effort estimate: XS

Scope

• Inspect App.tsx and the rendered UI for the decorative background image.
• Remove link behavior, click handlers, pointer cursor styling, and pointer-event interception from that decorative layer only.
• Preserve its visual placement and stacking.
• Add a focused regression test covering pointer/click behavior and a touch-equivalent interaction path where the test harness supports it.

Out of scope

• Do not redesign the screen, change gameplay controls, or disable interaction on any real control.
• Do not change monetization, analytics, navigation, or deployment configuration.

Acceptance criteria

• The decorative image cannot receive or trigger interaction.
• Intended controls still receive pointer and touch input.
• Existing visual output is unchanged.
• Focused tests, typecheck, and diff checks pass.

Files likely touched

• App.tsx (edit)
• src/ui/GameScreen.tsx (edit)
• tests/ui/background-interaction.test.tsx (edit)

Security considerations

None — local presentation-only change.

Estimation

Estimated XS, landed XS — accurate

Handoff

The approved local asset is already present and this is a contained presentation improvement with no external dependency.

Effort estimate: M

Scope

• Inspect App.tsx, the existing splash/header surfaces, app.json, and the approved assets/vibe-tycoon-logo-v2.png.
• Add the logo to the primary visible application branding surface(s) where the current UI needs a brand mark.
• Keep the existing pastel color system and mobile-safe sizing.
• Verify the asset is bundled through the existing platform configuration without replacing the app icon unless the code proves that is the intended surface.
• Add or update focused rendering/asset checks.

Out of scope

• Do not introduce a new logo asset, duplicate the canonical asset, replace app icons, or alter gameplay layout beyond the branding surface.
• Do not publish any source or asset publicly.

Acceptance criteria

• The approved logo renders on the intended visible surface.
• It remains legible on narrow/mobile layouts.
• No broken asset reference or packaging regression exists.
• Existing gameplay tokens and behavior remain unchanged.
• Relevant tests, typecheck, and diff checks pass.

Files likely touched

• App.tsx (edit)
• app.json (edit)
• assets/vibe-tycoon-logo-v2.png (edit)
• tests/ui/branding.test.tsx (edit)

Security considerations

None — local bundled asset and presentation-only wiring.

Estimation

Estimated M, landed M — accurate

Handoff

A local, deterministic profile identity picker is safe to implement without accounts, uploads, providers, or public sharing.

Effort estimate: M

Scope

• Inspect the current save schema, profile/header surfaces, and existing canonical assets before implementation.
• Define exactly 20 canonical profile-picture IDs using repository-owned assets or newly authored local artwork with recorded provenance; do not copy external assets.
• Add a compact picker with selected and fallback states, accessible labels, and mobile/web-safe layout.
• Persist only the canonical ID through the existing forward-only save migration path and render the selected identity wherever the current profile surface already exists.
• Add tests for selection, save/reload, unknown IDs, fallback, and catalog cardinality.

Out of scope

• No user uploads, accounts, network storage, public sharing, new backend, or provider integration.
• Do not duplicate immutable assets across directories or change unrelated save fields.

Acceptance criteria

• Exactly 20 canonical IDs are available and each has a valid local asset and accessible label.
• Selection persists by ID and round-trips through save/load.
• Unknown IDs fall back safely without data loss.
• The picker is usable on narrow screens and keyboard/touch input.
• Tests, typecheck, and diff checks pass.

Files likely touched

• src/persistence/save.ts (edit)
• App.tsx (edit)
• src/ui/GameScreen.tsx (edit)
• assets/characters/README.md (edit)
• tests/persistence/save.test.ts (edit)
• tests/ui/profile-picker.test.tsx (edit)

Security considerations

No network or account surface; verify no raw save data or upload path is introduced.

Estimation

Estimated M, landed M — accurate

Handoff

The manual and future UI need one authoritative vocabulary before a universal tooltip system is attempted.

Effort estimate: XS

Scope

• Create a concise source-of-truth explanation catalog for currently implemented Cash, AI Tokens, Reputation, agents, jobs, upgrades, incidents, Vibe, offline earnings, and other Cycle 40-visible surfaces. Each entry states what it is, how it changes, why it matters, and the next useful action.

Out of scope

• Do not implement a universal tooltip component, describe unshipped features, add accessibility infrastructure, or duplicate definitions outside the owning documentation.

Acceptance criteria

• Every catalog entry has the four required explanations.
• Copy matches current economy and lifecycle contracts.
• No entry promises unimplemented provider, device, public-sharing, or monetization behavior.
• The player manual references the catalog as its source of truth.
• The catalog is concise enough for future UI consumption.

Files likely touched

• docs/player-manual.md (edit)
• docs/design/core-loop.md (edit)
• docs/design/economy-guardrails.md (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/player-manual.md docs/design/core-loop.md docs/design/economy-guardrails.md

Estimation

Estimated XS, landed XS — accurate

Handoff

Cycle 40 established layered economy behavior; typed local telemetry makes inflation, dead resources, and hard stops observable before remote analytics.

Effort estimate: S

Scope

• Define or extend typed local events and deterministic aggregation for Cash, Tokens, Reputation, offer acceptance, contract completion, incidents, rework, upgrades, hiring, exits, offline return, product decisions, and stage transitions. Keep output suitable for local tests and debug reports.

Out of scope

• Do not add a remote analytics provider, credentials, network calls, dashboards, or production tracking policy.

Acceptance criteria

• Event names and payloads are typed and compile.
• Local aggregation covers the listed transitions.
• Tests cover a source, sink, transition, and guardrail signal.
• Malformed event data cannot silently corrupt the report.
• No provider, credential, or network dependency is introduced.

Files likely touched

• src/analytics/events.ts (edit)
• docs/design/economy-guardrails.md (edit)
• docs/design/retention-hooks.md (edit)
• tests/economy/guardrails.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS src/analytics/events.ts docs/design/economy-guardrails.md docs/design/retention-hooks.md

Estimation

Estimated S, landed S — accurate

Handoff

The game needs legible variation while keeping economy effects deterministic, bounded, and compatible with Cycle 40 contracts.

Effort estimate: S

Scope

• Define a small catalog of market events such as urgent demand, client bonuses, outages, model-price changes, and limited contract windows. Specify trigger, frequency, cooldown, response, resource effects, and recovery interaction.

Out of scope

• Do not add rewarded video, advertising, provider integrations, progress wipes, random monetization outcomes, or runtime event delivery.

Acceptance criteria

• Every event has a bounded trigger and cooldown.
• Every event names its source, sink, and player response.
• Events cannot erase progress or create an unbounded loop.
• The design preserves non-deceptive monetization.
• At least three deterministic event examples are documented.

Files likely touched

• docs/design/job-system.md (edit)
• docs/design/economy-guardrails.md (edit)
• docs/design/depth-audit.md (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/job-system.md docs/design/economy-guardrails.md docs/design/depth-audit.md

Estimation

Estimated S, landed S — accurate

Handoff

The layered economy needs a bounded relationship model before repeat work and retention behavior are implemented.

Effort estimate: S

Scope

• Define repeat clients, escalating expectations, loyalty, churn, and relationship value using Cash, Reputation, and Tokens. Include at least three deterministic examples and explain effects on future contract quality.

Out of scope

• Do not add a new currency, runtime UI, backend state, provider integration, or monetization dependency.

Acceptance criteria

• The model has explicit states and transition rules.
• Repeat work changes existing resources only.
• Loyalty, churn, and escalation are bounded.
• At least three deterministic examples are included.
• The design preserves the assignment-first loop.

Files likely touched

• docs/design/job-system.md (edit)
• docs/design/progression-ladder.md (edit)
• docs/research/design-reconciliation.md (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/job-system.md docs/design/progression-ladder.md docs/research/design-reconciliation.md

Estimation

Estimated S, landed S — accurate

Handoff

Cycle 40 added layered economy contracts; deterministic profiles are the local gate before external monetization work.

Effort estimate: M

Scope

• Run deterministic casual, average, and power profiles across first job, first upgrade, stage transitions, first exit, offline return, token recovery, and day-one/day-seven sources and sinks. Record a compact local report and assert the three-resource and integer-currency guardrails.

Out of scope

• Do not perform human playtests, device testing, provider integration, monetization validation, or subjective balance changes.

Acceptance criteria

• All three profiles complete without runtime errors.
• The report covers the required milestones and resource sources/sinks.
• Repeated runs are stable.
• Existing economy guardrails remain satisfied.
• Human-playtest gates are explicitly recorded as pending.

Files likely touched

• docs/research/idle-curve-maths.md (edit)
• docs/research/economy-and-items.md (edit)
• docs/design/depth-audit.md (edit)
• tests/economy/guardrails.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/research/idle-curve-maths.md docs/research/economy-and-items.md docs/design/depth-audit.md tests/economy/guardrails.test.ts

Estimation

Estimated M, landed S — accurate

Handoff

The broad agent-training idea needs a small pure contract before runtime progression is attempted.

Effort estimate: S

Scope

• Define finite agent mastery states, training transitions, existing-resource costs, specialization, cross-training, diminishing returns, substitution, deterministic examples, and the smallest migration-safe shape.

Out of scope

• Do not implement runtime training, add currencies, change the assignment-first verb, add providers, or replace existing save behavior.

Acceptance criteria

• The contract has a finite state shape and explicit transitions.
• Training uses existing resources only.
• Specialization and cross-training have bounded returns.
• Substitution does not automate away assignment.
• The design is compatible with forward-only save migrations.

Files likely touched

• docs/design/ai-skills-system.md (edit)
• docs/design/progression-ladder.md (edit)
• docs/design/token-economy.md (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/ai-skills-system.md docs/design/progression-ladder.md docs/design/token-economy.md

Estimation

Estimated S, landed S — accurate

Handoff

Contract selection needs a compact decision grammar that makes scope, urgency, quality, risk, token burn, and payout legible within the assignment-first loop.

Effort estimate: S

Scope

• Update `docs/design/job-system.md` with a small modifier grammar for client scope, rush, and quality. Define how each modifier changes payout, deadline, AI-token demand, incident/rework exposure, Reputation, and compatibility with existing skills and client tiers. Include a readable job-card example and guardrails preventing modifiers from creating a fourth resource or punitive pay-to-avoid-failure mechanic. Done means a future job-card implementation can render the trade-offs without inventing semantics.

Out of scope

• Do not implement job cards, client relationships, random market events, rewarded recovery, or final numeric tuning.

Acceptance criteria

• `docs/design/job-system.md` defines the modifier vocabulary and allowed combinations.
• Each modifier has observable player-facing effects and economy mappings.
• The grammar is compatible with AD-12, AD-15, and AD-21.
• At least one normal, rushed, and high-quality example is documented.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• `docs/design/job-system.md` (edit)
• `docs/research/idle-curve-maths.md` (edit)
• `docs/research/monetization-canon.md` (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS `docs/design/job-system.md` `docs/research/idle-curve-maths.md` `docs/research/monetization-canon.md`

Estimation

Estimated S, landed S — accurate

Handoff

The transition from paid client work to compounding owned products is the central mid-game arc in AD-11 and must consume one authoritative economy contract.

Effort estimate: S

Scope

• Using the completed economy contract from task-146, produce or complete `docs/design/contract-to-product-transition.md`. Define the transition gate, capacity opportunity cost, contract Cash versus product income, product maintenance/content decisions, sale timing, and how Reputation and existing resources interact. Include one concrete early-to-mid-game example showing why a player might keep taking contracts, launch a product, hold it, or sell it. Done means the transition is one connected decision path rather than two unrelated economies.

Out of scope

• Do not implement owned products, project-sale runtime, prestige code, new currencies, or final balance numbers. Do not duplicate the full owned-products design.

Acceptance criteria

• The transition gate and player-facing decision are explicit.
• Contract income, product income, capacity, Reputation, Cash, and AI tokens have defined interactions.
• Hold, maintain, sell, and return-to-contract decisions are distinguishable.
• The document references task-146’s economy contract and identifies unresolved tuning questions.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• `docs/design/contract-to-product-transition.md` (edit)
• `docs/design/economy-contract.md` (edit)
• `docs/design/owned-products.md` (edit)
• `docs/design/progression-ladder.md` (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS `docs/research/design-reconciliation.md` `docs/design/owned-products.md` `docs/design/progression-ladder.md`

Estimation

Estimated S, landed S — accurate

Handoff

The game needs one lifecycle that connects client contracts and owned products without duplicating or contradicting the operations loop from task-141.

Effort estimate: M

Scope

• Using task-141’s reconciled operations loop, produce or complete `docs/design/project-lifecycle.md`. Define brief, scope, assignment, build, review, launch, maintenance, and eventual sale or retirement, including which decisions are reversible and where Cash, AI tokens, Reputation, incidents, and product value enter the lifecycle. Explain how the lifecycle remains understandable when multiple projects exist. Done means implementation can model one shared state machine for both contract and owned-product work.

Out of scope

• Do not implement the state machine, owned-product runtime, project-sale UI, company prestige, or multi-project concurrency beyond documenting the required rules.

Acceptance criteria

• `docs/design/project-lifecycle.md` defines every lifecycle state and allowed transition.
• Contract and owned-product paths share the lifecycle where appropriate and identify their differences.
• Reversibility, failure, rework, launch, maintenance, sale, and retirement behavior are explicit.
• The document links to task-141’s core loop and does not introduce a competing primary verb.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• `docs/design/project-lifecycle.md` (edit)
• `docs/design/core-loop.md` (edit)
• `docs/design/job-system.md` (edit)
• `docs/design/owned-products.md` (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS `docs/design/core-loop.md` `docs/design/job-system.md` `docs/design/owned-products.md` `docs/research/design-reconciliation.md`

Estimation

Estimated M, landed M — accurate

Handoff

Once the assignment loop and economy vocabulary are explicit, a small strategy-focus layer can give players durable direction without exposing project-management bureaucracy.

Effort estimate: S

Scope

• Update `docs/design/progression-ladder.md` or create the smallest linked strategy-focus section. Define a compact set of company focuses such as throughput, quality, growth, and stability, with one benefit, one cost, one visible consequence, and a safe way to change direction. Map each focus to existing resources and progression stages, preserving the three-resource contract and local-first play. Done means a player can understand why a focus matters and when to change it.

Out of scope

• Do not implement strategy controls, add a fourth resource, require a live MCP connection, or design a full PAPI planning interface.

Acceptance criteria

• Each proposed focus has a distinct benefit, cost, consequence, and change rule.
• Focuses interact with existing progression and economy concepts without creating parallel progression.
• The document identifies the smallest stage at which each focus becomes available.
• The design remains understandable without PAPI terminology or external services.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• `docs/design/progression-ladder.md` (edit)
• `docs/design/depth-audit.md` (edit)
• `docs/design/papi-service.md` (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS `docs/design/progression-ladder.md` `docs/design/depth-audit.md` `docs/design/papi-service.md` `docs/research/design-reconciliation.md`

Estimation

Estimated S, landed S — accurate

Handoff

The project has multiple economy documents but no single contract that downstream implementation and validation can safely consume. This is the foundation for AD-12, AD-14, and the contract/product transition.

Effort estimate: M

Scope

• Produce or complete `docs/design/economy-contract.md` as the authoritative economy contract. Reconcile Cash, AI tokens, Reputation, state, and unlock sources and sinks across contracts, skills, tooling, incidents, rework, owned products, project sales, and company prestige. Define invariants for token throttling, offline earnings, risk costs, product income, and reset carry-over, including explicit no-progress-wipe and no-fourth-currency rules. Done means every referenced system has a named source, sink, gate, or state relationship that a later implementation task can test.

Out of scope

• Do not implement economy code, tune final numeric balance values, add telemetry, create monetization SKUs, or redesign the three-resource decision.

Acceptance criteria

• `docs/design/economy-contract.md` is authoritative and links or supersedes conflicting economy statements.
• Cash, AI tokens, and Reputation each have documented sources, sinks, gates, and non-goals.
• Offline earnings, token throttling, incidents, product income, sale, and prestige carry-over rules are explicit.
• The contract identifies unresolved numeric tuning as follow-up work rather than silently inventing values.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• `docs/design/economy-contract.md` (edit)
• `docs/design/token-economy.md` (edit)
• `docs/design/economy-guardrails.md` (edit)
• `docs/design/owned-products.md` (edit)
• `docs/design/company-prestige.md` (edit)
• `docs/research/idle-curve-maths.md` (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS `docs/research/idle-curve-maths.md` `docs/design/token-economy.md` `docs/design/economy-guardrails.md` `docs/design/owned-products.md` `docs/design/company-prestige.md`

Estimation

Estimated M, landed M — accurate

Handoff

Establish the smallest coherent playable translation of the PAPI-inspired loop before deeper economy and lifecycle rules are implemented. This directly supports AD-11, AD-12, AD-13, and AD-15.

Effort estimate: S

Scope

• Read the referenced design material and reconcile it into the smallest local-first playable loop: choose work, assign people/agents, run work, review the result, ship, and improve. Map each step to existing game resources, state, progression, and owned-product concepts without adding a fourth resource or requiring a live PAPI connection. Update `docs/design/core-loop.md` with the authoritative flow, state transitions, player decisions, and first-session boundary. Done means a builder can implement one deterministic vertical slice from the document without inventing missing rules.

Out of scope

• Do not implement runtime code, live-service integration, analytics, monetization offers, public sharing, or the full late-game economy. Do not expose PAPI terminology as mandatory player-facing UI.

Acceptance criteria

• `docs/design/core-loop.md` defines the complete smallest playable loop and its state transitions.
• Every step maps to Cash, AI tokens, Reputation, state, or unlocks without introducing a fourth resource.
• The first-session slice and explicit out-of-scope systems are named.
• Existing design conflicts are resolved or clearly flagged for later decision work.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• `docs/design/core-loop.md` (edit)
• `docs/design/papi-service.md` (edit)
• `docs/research/design-reconciliation.md` (edit)
• `docs/INDEX.md` (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS `docs/design/papi-service.md` `docs/GAME_DESIGN_BRAINSTORM.md` `docs/research/design-reconciliation.md`

Estimation

Estimated S, landed S — accurate

Handoff

The repository and live release are tagged v0.39.0, but package.json, package-lock.json, app.json, and the deployed bundle still report 0.17.0. This makes each release difficult to identify and allows version drift to ship unnoticed.

Effort estimate: S

Scope

• Implement one deterministic release-version source of truth, using the vX.Y.Z release input or an equivalent repository-owned release value. Propagate it to package metadata, package-lock metadata when required, Expo app configuration, and every existing in-app version display/report surface. Add a local/CI check that fails when the release version and app metadata disagree. Update the release/deployment documentation with the exact invocation and verification rule. Preserve the existing tagged deployment flow.

Out of scope

• Do not implement store uploads, RevenueCat, analytics, account identity, public sharing, device validation, or a new deployment service. Do not rewrite historical tags or retroactively change old deployed releases. Do not add a fourth version scheme or make a date-based version.

Acceptance criteria

• A vX.Y.Z release input resolves to the same version in package metadata, Expo configuration, and the existing app-version display/report surfaces without manual per-file edits.
• package.json and package-lock.json remain internally consistent when the release version is propagated.
• A mismatch between the release version and app metadata fails a deterministic local/CI check with an actionable error.
• Tests cover a valid version, mismatch rejection, and the current app-version display contract.
• The existing typecheck, Jest suite, duration report, export, and diff checks remain green.
• Release documentation explains the version source, check command, and tagged deployment verification.
• No provider, account, device, public, or human-acceptance claim is introduced.

Files likely touched

• package.json (edit)
• package-lock.json (edit)
• app.json (edit)
• scripts/ (edit)
• src/ (edit)
• tests/ (edit)
• docs/SERVER_DEPLOYMENT.md (edit)
• docs/release/release-process.md (edit)

Security considerations

None — local metadata and validation only; do not add credentials or network access. REFERENCE DOCS docs/SERVER_DEPLOYMENT.md docs/release/release-process.md

Estimation

Estimated S, landed S — accurate

Handoff

Cycle 38 introduced bounded refill scaling for ready agents. Its most important invariant is that incidents, review decisions, and a fully busy roster must not accelerate the refusal cadence.

Effort estimate: XS

Scope

• Add focused store-level tests for no ready agents, incident-blocked agents, and completion-decision-blocked agents.
• Assert the baseline refill delay remains CONFIG.offerRefillMs when every roster member is unavailable.
• Keep the existing helper tests and deterministic selector unchanged.

Out of scope

• No balance retuning, multi-offer queue, UI changes, or new production behavior unless a test proves the current contract is wrong.

Acceptance criteria

• All blocked-roster cases preserve the baseline refill delay.
• At least one ready agent still uses the bounded scaled delay.
• Focused tests, typecheck, and diff check pass.

Files likely touched

• tests/game/ftue.test.ts; tests/game/offer-spawn.test.ts (edit)

Security considerations

None — regression tests only.

Estimation

Estimated XS, landed XS — accurate

Handoff

The local username shipped in Cycle 38, but the studio/company identity is still missing. Add the smallest display-only local companion without opening public, account, or monetization scope.

Effort estimate: S

Scope

• Add a separate companyName field with schema-versioned forward migration and a bounded default such as “Vibe Tycoon”.
• Add a local editor in the existing More/profile surface and show the saved name in the local company header/status surfaces already present.
• Reuse the existing profile normalization/validation pattern; renames are free and never alter economy state.
• Add save/reload, migration, invalid-input, exit-preservation, and UI contract coverage.

Out of scope

• No account identity, backend, public profile/link, native sharing, duplicate checks, Cash sink, or device/provider work.
• Do not touch the existing username semantics or add a new resource.

Acceptance criteria

• Existing saves migrate to the default company name without losing progress.
• Valid names round-trip locally, remain after company exit, and invalid input is rejected without changing economy state.
• The name is visible in the existing local profile/header surface with accessible labels.
• Focused tests, typecheck, and diff check pass.

Files likely touched

• src/economy/config.ts; src/game/profile.ts; src/game/store.ts; src/persistence/save.ts; src/ui/GameScreen.tsx; tests/game/profile.test.ts; tests/persistence/save.test.ts; tests/ui/company-profile.test.ts; docs/player-manual.md (edit)

Security considerations

None — local display-only data; no account, network, or public surface. REFERENCE DOCS docs/player-manual.md; docs/design/progression-ladder.md; docs/design/economy-guardrails.md

Estimation

Estimated S, landed S — accurate

Handoff

Existing sharing ideas are public/external and remain out of scope. A pure allowlisted summary gives local UI and future copy actions a truthful seam without exposing raw saves or requiring a provider. DEPENDS ON task-185

Effort estimate: S

Scope

• Add a pure formatter for a local company summary using only display-safe fields: company name, username, stage, agent count, Equity, unlocked milestone IDs/labels, and app version.
• Add focused tests proving stable output and omission of raw timers, incidents, tokens, analytics, save internals, and credentials.
• Keep the formatter unconnected to public routes or native share APIs; the immediate consumer is a local debug/player-facing text preview only if an existing local surface can host it without new infrastructure.

Out of scope

• No public link, backend, clipboard/share SDK, account identity, analytics payload, or raw-save serialization.
• Do not claim this is a public sharing feature.

Acceptance criteria

• Formatter output is deterministic and includes only the approved allowlist.
• Tests prove sensitive/private fields are absent.
• Typecheck and diff check pass.
• No network, provider, device, or public route is introduced.

Files likely touched

• src/game/company-summary.ts; tests/game/company-summary.test.ts (edit)

Security considerations

Review the allowlist for accidental save, credential, timer, incident, or analytics leakage; no external surface is added. REFERENCE DOCS docs/player-manual.md; docs/design/build-in-public-growth.md

Estimation

Estimated S, landed S — accurate

Handoff

The manual still contains layered-economy/product language that must not become a promise before its runtime exists. A short local audit keeps documentation truthful after the identity changes.

Effort estimate: XS

Scope

• Compare docs/player-manual.md with the actual store, persistence, UI, and config behavior.
• Remove or clearly label unsupported product, public-sharing, provider, or monetization claims.
• Keep the manual short and preserve verified resource, assignment, incident, identity, and manual-exit instructions.
• Re-register the final document in PAPI.

Out of scope

• No gameplay code, balance changes, public links, provider/account/device claims, or broad documentation rewrite.

Acceptance criteria

• Every player-facing claim in the edited sections is traceable to shipped source.
• Unsupported future systems are clearly excluded or labeled as future.
• The guide remains concise and the body is re-registered.
• Diff check passes.

Files likely touched

• docs/player-manual.md (edit)

Security considerations

None — documentation-only.

Estimation

Estimated XS, landed XS — accurate

Handoff

The profile editor shipped with labels and local-only copy in Cycle 38. A small source contract prevents future UI edits from dropping the accessible name, length bound, or identity boundary.

Effort estimate: XS

Scope

• Add a focused static/UI contract test for the profile editor's accessibility labels, save action, max length, and local-only explanatory copy.
• Keep the contract narrow to the existing component and avoid introducing a UI abstraction.
• If the test reveals drift, make the smallest source correction and verify it.

Out of scope

• No visual redesign, native-device acceptance claim, account/public identity, or generalized tooltip framework.

Acceptance criteria

• The profile editor exposes an accessible company-name input and save control.
• The configured maximum length and local-only boundary remain discoverable in source.
• Focused test, typecheck, and diff check pass.

Files likely touched

• src/ui/GameScreen.tsx; tests/ui/company-profile.test.ts (edit)

Security considerations

None — local UI contract only.

Estimation

Estimated XS, landed XS — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed S — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed XS — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed S — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed S — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed XS — accurate

Handoff

Effort estimate: M

Estimation

Estimated S, landed S — accurate

Handoff

Effort estimate: M

Estimation

Estimated XS, landed XS — accurate

Handoff

Effort estimate: M

Estimation

Estimated XS, landed XS — accurate

Handoff

Effort estimate: M

Estimation

Estimated S, landed S — accurate

Handoff

Contributors need a reproducible local path to the deterministic debug report.

Effort estimate: XS

Scope

• Add a short runbook for the canonical loopback port, seed/report provenance, browser smoke checks, and cleanup.
• Link it from the debug README and docs index if standalone.

Out of scope

• No public exposure, authentication, deployment, port change, or human-play acceptance claim.

Acceptance criteria

• A contributor can open the report and run a named scenario.
• The runbook distinguishes debug smoke from product acceptance.
• No external provider or public endpoint is introduced.

Files likely touched

• economy-playground/README.md; docs/INDEX.md (edit)

Security considerations

None — low-impact local work only.

Estimation

Estimated XS, landed XS — accurate

Handoff

The Cycle 35 debug simulator needs an authoritative version label so reports cannot be mistaken for another build.

Effort estimate: S

Scope

• Trace the existing authoritative app/package version.
• Show it on the development game screen and local economy debug view without a duplicate hardcoded version.
• Add focused regression coverage and keep save schema/release tag terminology distinct.

Out of scope

• No production store metadata, release channels, public routes, deployment, or save schema changes.

Acceptance criteria

• Fresh development launch and local debug view show the authoritative version.
• Changing the authoritative version updates both surfaces.
• Typecheck and focused tests pass.

Files likely touched

• package.json; app.json; src/ui/GameScreen.tsx; economy-playground/index.html; tests/ui (edit)

Security considerations

None — low-impact local work only.

Estimation

Estimated S, landed S — accurate

Handoff

The full Jest suite is already under two minutes, but the result is not easy to compare over time.

Effort estimate: S

Scope

• Add an opt-in local command or script using the existing Jest runner that reports suite count, test count, elapsed time, and pass/fail.
• Preserve the existing worker limit and add no second runner.

Out of scope

• No hardware-specific hard threshold, hosted telemetry, CI service, or dashboard.

Acceptance criteria

• The command uses the canonical test command.
• Output includes elapsed time and pass/fail.
• No watcher or background process remains.

Files likely touched

• package.json; scripts or docs/README.md (edit)

Security considerations

None — low-impact local work only.

Estimation

Estimated S, landed S — accurate

Handoff

Checked-in seed-35 reports need a regression check against the production-backed simulator.

Effort estimate: S

Scope

• Run every checked-in scenario and compare day 1, 7, and 30 checkpoint fields against the report.
• Keep failure messages scenario/day-specific.
• Document the check without a new build system.

Out of scope

• No balance changes, randomness, browser, provider, device, or network.

Acceptance criteria

• All scenarios replay deterministically.
• A changed checkpoint fails with a useful scenario/day message.
• Focused and full tests pass.

Files likely touched

• tests/economy/simulator.test.ts; economy-playground/scenario-data.json; economy-playground/README.md (edit)

Security considerations

None — low-impact local work only.

Estimation

Estimated S, landed S — accurate

Handoff

A small consistency pass can catch stale review dates, links, or summaries before the next design batch.

Effort estimate: XS

Scope

• Compare docs/INDEX.md, review headers, and registered summaries for Cycle 35 economy documents.
• Correct only demonstrable inconsistencies and register changed bodies.

Out of scope

• No design rewrite, visibility change, duplicate document, or public publication.

Acceptance criteria

• Changed documents have current review task and index entry.
• Registry metadata and local paths agree.
• git diff --check passes.

Files likely touched

• docs/INDEX.md; Cycle 35 economy documents (edit)

Security considerations

None — low-impact local work only.

Estimation

Estimated XS, landed XS — accurate

Handoff

Existing fixed profile tests and the standalone illustrative playground need one production-backed deterministic scenario runner.

Effort estimate: XL

Scope

• Read the current profile harness, playground, docs, and game/economy modules. Build a seeded injected-time headless runner that reuses production functions, executes supported local actions, reports deterministic timelines/checkpoints and explicit unsupported actions, and backs the existing profile tests and local debug playground. Add casual, average, power, active, idle, token-starved, incident-heavy, and growth scenarios; run/reset controls; readable tables/charts; README verification steps; and regression coverage for token dead ends, offline bounds, active-vs-idle, stage pacing, and three-resource balance.

Out of scope

• No backend, network, provider, account, device, monetization, production UI, save-schema changes, public deployment, synthetic telemetry, unbounded workers, wall-clock loops, or invented unsupported game actions.

Acceptance criteria

• Same seed/scenario/time produces identical results.
• All named scenarios report checkpoints and failure reasons.
• Production functions are reused and parallel balance formulas are removed or become views of the runner.
• Regression scenarios cover token dead ends, offline cap, active-vs-idle, stage pacing, and layered guardrails.
• Debug view is local-only with run/reset and readable output.
• Typecheck, focused tests, full tests, and browser smoke pass.

Files likely touched

• src/economy/ (edit)
• src/game/ (edit)
• tests/economy/profiles.test.ts (edit)
• tests/economy/profileDefinitions.ts (edit)
• tests/economy/simulator.test.ts (edit)
• economy-playground/app.js (edit)
• economy-playground/index.html (edit)
• economy-playground/styles.css (edit)
• economy-playground/README.md (edit)

Security considerations

None — local debug-only surface; no network or secrets.

Estimation

Estimated XL, landed L — accurate

Handoff

Owned products and contracts need a small attention-allocation contract before runtime portfolio expansion.

Effort estimate: M

Scope

• Read owned-products, retention, progression, reconciliation, and index sources. Define which project receives scarce agents/team, AI Tokens, marketing/maintenance attention, or founder focus; specify pause, update, hold, sell, and abandon behavior only where current contracts support it; state visible consequence, opportunity cost, recovery path, and cadence. Update the authoritative portfolio document and register it if required.

Out of scope

• No runtime, new currency, provider, monetization, device, save, backend, or replacement of task-40 sale rules. Mark unsupported behavior future rather than inventing it.

Acceptance criteria

• Attention choices and opportunity costs are concrete and limited.
• Supported versus future actions are separated.
• Only existing resources/state are used.
• Low-micromanagement cadence and review header are explicit.
• git diff --check passes.

Files likely touched

• docs/design/owned-products.md (edit)
• docs/design/retention-hooks.md (edit)
• docs/design/progression-ladder.md (edit)
• docs/INDEX.md (edit)

Security considerations

None — documentation-only.

Estimation

Estimated M, landed S — accurate

Handoff

The existing prestige and idle-curve documents need one coherent, player-readable post-exit choice before implementation.

Effort estimate: S

Scope

• Read the existing prestige, retention, idle-curve, and reconciliation documents. Define exactly two post-exit founder focus choices—hands-on and absentee/idle—with benefits, costs, cadence, visible consequences, timing, reversibility, next-run effects, and fairness guardrails. Use only existing Cash, AI Tokens, Reputation, company/prestige state, and offline-cap concepts. Update the authoritative design document(s) with a concise decision table, examples, and a task-152 review header.

Out of scope

• No runtime code, UI, saves, migrations, analytics, monetization, providers, device integrations, new resources, or Active Decision changes. Do not duplicate an existing design.

Acceptance criteria

• Exactly two focus choices are defined with distinct active and offline trade-offs.
• Effects map only to existing resources and state.
• Timing, reversibility, next-run effect, and fairness guardrails are explicit.
• Three-resource economy and free-play viability are preserved.
• Review headers are current and git diff --check passes.

Files likely touched

• docs/design/company-prestige.md (edit)
• docs/design/retention-hooks.md (edit)
• docs/research/idle-curve-maths.md (edit)

Estimation

Estimated S, landed S — accurate

Handoff

The layered economy needs a dependency-ordered teaching contract before more runtime surfaces are built.

Effort estimate: M

Scope

• Read core-loop, idle maths, guardrails, fictional services, FTUE, player manual, index, opening tests, and hints. Define staged teaching for assignment/Cash, AI Tokens/throttle, Reputation/client tiers, incidents/rework, products, and prestige/focus. For each stage record player question, in-world explanation, visible evidence, next action, and hidden-until-earned concepts. Add explainability checks for offline caps, token pressure, incidents, products versus contracts, and free-route/monetization boundaries. Update the authoritative FTUE or manual design and register it if required.

Out of scope

• No runtime UI, translation, analytics, provider, monetization, device, save, or balance changes. Do not expose PAPI terminology or teach unsupported systems without marking them future.

Acceptance criteria

• One-concept-at-a-time dependency order is explicit.
• Every stage has a question, in-world explanation, evidence, and next action.
• Token, offline, incident, product, prestige, and monetization boundaries are understandable without a wiki.
• Three resources and free route remain intact.
• Review header and git diff --check pass.

Files likely touched

• docs/design/ftue.md (edit)
• docs/player-manual.md (edit)
• docs/design/core-loop.md (edit)
• docs/INDEX.md (edit)

Security considerations

None — documentation-only.

Estimation

Estimated M, landed S — accurate

Handoff

The existing tooling ladder needs a concise branch contract before implementation.

Effort estimate: M

Scope

• Read the progression, token-economy, guardrail, and doc-index sources. Define exactly three mutually exclusive branches—burn efficiency, delivery speed, and quality/incident prevention—with player promise, opportunity cost, resource effects, level ceiling, interactions, and switching point. Update the authoritative design document and register it if required.

Out of scope

• No runtime code, new identifiers, new resources, monetization, providers, devices, saves, or balance constants. Do not create a second progression ladder.

Acceptance criteria

• Exactly three branches have distinct benefits and opportunity costs.
• All effects use existing resources/state and preserve the three-resource rule.
• Switching, ceilings, and current-tooling interactions are explicit.
• Review header/index metadata are current and git diff --check passes.

Files likely touched

• docs/design/progression-ladder.md (edit)
• docs/design/token-economy.md (edit)
• docs/design/economy-guardrails.md (edit)
• docs/INDEX.md (edit)

Security considerations

None — documentation-only.

Estimation

Estimated M, landed S — accurate

Handoff

Cycle 30 was released and verified locally while hosted PAPI still reports that the project has no linked repository. Contributors need one durable rule explaining how to record the two evidence sources without treating a visibility warning as a code failure.

Effort estimate: XS

Scope

• Add a short section to docs/PAPI_TEAM_PROTOCOL.md under the release/review guidance that distinguishes local Git/CI evidence from hosted PAPI repository visibility; requires release reports to record the exact local commit, branch, tag, and gate results when the hosted adapter cannot inspect the checkout; states that repository linking is an account/project configuration task, not a reason to repeat a verified build or alter source; and preserves private-repository and credential boundaries.

Out of scope

• Do not link repositories, change PAPI configuration, publish source, change deployment settings, add credentials, or modify application code.

Acceptance criteria

• The protocol clearly separates local release evidence from hosted repository visibility.
• The protocol names the minimum release evidence: commit, branch, tag/version, and gate results.
• The section explicitly preserves private-source and credential boundaries.
• The change passes git diff --check and contains no unrelated edits.

Files likely touched

• docs/PAPI_TEAM_PROTOCOL.md (edit)

Security considerations

Do not document or add credentials, private URLs, tokens, or repository contents.

Estimation

Estimated XS, landed XS — accurate

Handoff

The existing deployment script can leave failed incoming archives and retains every superseded release indefinitely. This is a small, bounded maintenance repair with no product or provider dependency.

Effort estimate: S

Scope

• Update scripts/deploy-web.sh so the remote deployment removes the uploaded incoming archive on every exit after upload, including validation, extraction, and health-check failures.
• After a successful activation, retain the active release plus a small explicit number of newest prior release directories; make the retention count a documented constant in the script.
• Preserve current symlink activation, rollback behavior, path/link safety checks, and the existing success cleanup.
• Add or update local verification for shell syntax and the cleanup/retention logic using the repository’s existing test or script-verification conventions.
• Update deployment documentation only if the retention behavior or operator recovery contract changes.

Out of scope

• Do not run a deployment against the VPS.
• Do not delete any live remote artifact manually.
• Do not change hostnames, credentials, SSH policy, public routes, release packaging, Expo build behavior, or application code.
• Do not redesign the deployment pipeline or add a new dependency.

Acceptance criteria

• Failed remote deployment paths remove the matching incoming archive without masking the original failure.
• Successful activation retains the active release and only the documented newest prior releases.
• Rollback still restores the previous release and cleans the failed staged release.
• Existing archive path, symlink, and unsafe-content protections remain intact.
• Local shell/script verification passes and covers the new cleanup contract.
• No credentials or live VPS changes are introduced.

Files likely touched

• scripts/deploy-web.sh (edit)
• docs/SERVER_DEPLOYMENT.md (only if operator-facing retention behavior needs documenting) (edit)
• tests/deployment/ (only if an existing local script-verification layout exists) (edit)

Estimation

Estimated S, landed S — accurate

Handoff

task-123’s AD-21 decision gate is resolved, but its implementation remains underspecified. This investigation creates the durable product contract needed before building the collection layer.

Effort estimate: S

Scope

• Produce `docs/design/prompt-library-collection.md` describing the smallest viable prompt-library collection model.
• Define deterministic acquisition and value disclosure; paid randomized rewards, hidden odds, opaque costs, and spending-required progression are explicitly excluded.
• Map the collection model to Cash, AI tokens, and Reputation without introducing a fourth resource.
• Explain how the model remains local-first and compatible with AsyncStorage and forward-only save migrations.
• Include implementation-ready acceptance criteria and a follow-up scope for task-123.
• Register the document through the project’s documentation registry.
• Done means a builder can implement task-123 without making an unresolved monetization or economy decision.

Out of scope

• Do not implement the prompt-library collection UI, persistence changes, monetization offers, RevenueCat products, rewarded-video placements, backend services, or store configuration.

Acceptance criteria

• The design document specifies deterministic acquisition, disclosed value, and a meaningful non-paid route.
• The model uses only the existing three resources and does not add a premium or collection currency.
• The document explicitly aligns with AD-21, AD-3, AD-18, and AD-19.
• The document defines the implementation boundary and follow-up acceptance criteria for task-123.
• The document is registered and discoverable through the project documentation registry.
• Scope matches handoff — no unrelated code or monetization implementation is added.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• `docs/design/prompt-library-collection.md` (edit)
• `docs/INDEX.md` (edit)

Pre-build verification

• `docs/INDEX.md`
• `docs/research/economy-and-items.md`
• `docs/research/monetization-canon.md`
• `src/persistence/save.ts`
• `tests/economy/guardrails.test.ts`

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

The current migration sets buildInPublicPosts to zero for every schemaVersion below 4, which can erase the bounded shipment Reputation bonus from legacy saves. AD-19 requires forward-only in-place upgrades, and the existing Build-in-Public contract explicitly says legacy post counts retain that bonus.

Effort estimate: S

Scope

• Read the existing save schema history and Build-in-Public contract before changing code.
• Update migrate() so a pre-schema-4 save preserves a valid legacy buildInPublicPosts value when that field is present, while defaulting genuinely absent values to zero.
• Keep the existing CONFIG.buildInPublic.maxPosts bound and reject malformed, negative, fractional, or over-cap legacy values rather than silently inventing progress.
• Preserve all other forward-only migration behavior and the current-schema validation rules.
• Add focused regression tests using a literal legacy-shaped fixture: confirm a schema 0–3 save with a bounded legacy post count retains that count and a schema 0–3 save without the field defaults to zero; verify the loaded state still exposes the corresponding shipment Reputation bonus through the existing economy rule.
• Update docs/design/build-in-public-growth.md if its save-contract wording still claims all schema 0–3 saves lose the post count.

Out of scope

• Do not add a new save schema version, reset or rewrite existing player progress, or change the AsyncStorage backend.
• Do not change the Reputation economy, shipment formula, milestone definitions, UI, analytics, or current-version save format beyond the compatibility fix.
• Do not restore post counts from fields that are not part of the established legacy save shape, and do not broaden the allowed cap.
• Do not add a server, cloud sync, or migration framework.

Acceptance criteria

• A schema 0–3 legacy fixture carrying a valid buildInPublicPosts count migrates in place to the current schema and retains the bounded count.
• A schema 0–3 fixture with no buildInPublicPosts field migrates with buildInPublicPosts set to zero.
• Legacy counts outside the configured integer range are rejected safely, while current-version validation behavior remains unchanged.
• The preserved legacy count continues to produce the existing bounded shipment Reputation bonus after migration; no duplicate bonus is introduced.
• Focused persistence regression tests pass, and the save-contract documentation matches the implemented compatibility behavior.
• Forward-only migration behavior and all existing save tests remain green.

Files likely touched

• src/persistence/save.ts (edit)
• tests/persistence/save.test.ts (edit)
• docs/design/build-in-public-growth.md (edit)

Pre-build verification

• Read src/persistence/save.ts, especially migrate(), hasValidCoreFields(), and the buildInPublicPosts validation.
• Read tests/persistence/save.test.ts for the existing literal migration fixtures and persistence regression style.
• Read src/economy/rules.ts and src/economy/config.ts to confirm the existing bounded shipment Reputation bonus and cap.
• Check docs/design/build-in-public-growth.md and the docs index/doc registry for any newer save-compatibility decision or prior task covering legacy Build-in-Public state. If more than 80% of this scope is already implemented, report "already built" instead of re-implementing.

Security considerations

None — no security-relevant changes. REFERENCE DOCS - docs/design/build-in-public-growth.md

Estimation

Estimated S, landed S — accurate

Handoff

AD-6 makes Google Play logistics date-driven and non-displaceable; the 28 Aug fee and identity-verification deadline is imminent, while all existing implementation candidates remain provider-gated.

Effort estimate: S

Scope

• Create a concise, evidence-backed release-readiness checklist at `docs/release/google-play-readiness.md`. Verify the current Google Play registration fee, identity-verification status, closed-testing setup, tester count, test start date, and earliest eligible production-application date. Record either dated evidence for each gate or the exact owner action/blocker required. Register the document through the project’s normal docs registry.
• Done means the owner can inspect one document and immediately see which Google Play gates are complete, which are missing, and the next concrete action.

Out of scope

• Do not implement RevenueCat, OneSignal, rewarded video, analytics, authentication, store SDK code, or production deployment. Do not commit credentials, tokens, screenshots containing private account data, or copied console secrets.

Acceptance criteria

• Fee and identity-verification status are recorded with a date and evidence, or an exact blocker and owner action is recorded.
• Closed-testing status records tester count, start date, and earliest production-application date, or explicitly identifies missing inputs.
• The checklist links to the canonical store-policy and submission documents without duplicating their rules.
• No credentials, tokens, or private account data are committed.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• `docs/release/google-play-readiness.md` (edit)
• `docs/INDEX.md` (edit)

Security considerations

Do not store Play Console credentials, tokens, private account identifiers, or unredacted screenshots. Keep external account access outside the repository.

Estimation

Estimated S, landed S — accurate

Handoff

The first-order Founder Tree and milestone surfaces are now present, but a tooling purchase still needs to feel like a meaningful studio decision rather than a balance-sheet mutation. This is a small, local-first improvement that makes the next upgrade legible before provider-dependent monetization work is activated.

Effort estimate: S

Scope

• Add player-facing feedback for purchasing a named tooling upgrade using the existing game screen, economy state, and design tokens. Show the purchased tool's name, the practical effect it unlocked or improved, and the resulting resource change in the existing purchase flow. Keep the copy deterministic and derive it from the canonical tooling/economy definitions. Add focused pure/store or UI coverage for the feedback content and for the existing purchase state transition.

Out of scope

• Do not add RevenueCat, IAP, rewarded-video, analytics, notification, clipboard, or external sharing integration. Do not change prices, balance formulas, save migrations, unlock gates, or the underlying purchase effect. Do not add a second tooling registry.

Acceptance criteria

• A successful tooling purchase produces deterministic player-facing copy naming the tool and explaining its practical effect.
• The feedback is shown in the existing purchase surface and does not change purchase gating, rewards, persistence, or economy formulas.
• Focused tests cover the named feedback and preserve the existing purchase transition.
• TypeScript and the full Jest suite pass.

Files likely touched

• src/game/store.ts (edit)
• src/economy/config.ts (edit)
• src/ui/GameScreen.tsx (edit)
• tests/game/store.test.ts (edit)
• tests/ui/layout.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/research/monetization-canon.md docs/research/design-reconciliation.md docs/GAME_BRIEF.md

Estimation

Estimated S, landed S — accurate

Handoff

Task-72 established the permanent Founder Tree model, while Cycle 24 made milestones and build-in-public progress legible. The missing player-facing surface is a browsable tree that gives the company a memorable identity and makes long-term progression visible.

Effort estimate: M

Scope

• Build a compact Founder Tree screen or disclosure inside the existing game shell using the canonical Founder Tree nodes and current upgrade state. Render the four branches and their permanent nodes with clear names, costs or gate conditions, and locked/unlocked/purchased states. Reuse the existing layout and visual tokens, keep the surface usable on the current narrow web/mobile viewport, and make the screen read as a game surface rather than a raw debug list. Add focused presentation/store coverage for node-state derivation and the key visible states.

Out of scope

• Do not invent a second Founder Tree registry, add second-order prestige, reset behavior, new currencies, purchases, RevenueCat, rewarded video, analytics, or a new navigation framework. Do not change node costs, effects, persistence, or unlock rules established by task-72.

Acceptance criteria

• The existing Founder Tree nodes render grouped into their four canonical branches with names and concise conditions.
• Locked, available, and purchased states are visually distinguishable and derive from the existing store state.
• The surface works in the existing mobile-width game shell and does not regress the current scroll layout.
• Focused UI/store tests cover branch grouping and representative locked/available/purchased states.
• TypeScript and the full Jest suite pass.

Files likely touched

• src/game/store.ts (edit)
• src/ui/GameScreen.tsx (edit)
• src/ui/tokens.ts (edit)
• tests/game/store.test.ts (edit)
• tests/ui/layout.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/design-reconciliation.md docs/research/category-strategy.md docs/GAME_BRIEF.md

Estimation

Estimated M, landed M — accurate

Handoff

The Founder Tree is now defined and this task's notes explicitly call for a specification before implementation. Capturing the next reset layer now gives later cycles a coherent ceiling and prevents prematurely coding a second currency before real first-order runs provide evidence.

Effort estimate: L

Scope

• Produce a concise, registered design specification for a future Angel/Fund layer above the Founder Tree. Define the player promise, reset boundary, new-currency provenance, unlock timing, relationship to Founder Focus, anti-exploit and anti-dark-pattern constraints, and the evidence required before implementation. Include explicit non-goals: no code, no new save field, no live economy change, no UI implementation, and no monetization provider integration. Link the specification from the project docs index and register it through PAPI.

Out of scope

• Do not implement an Angel/Fund currency, reset the Founder Tree, alter economy formulas, add save migrations, add UI, or touch RevenueCat, rewarded video, analytics, or external services.

Acceptance criteria

• A registered design document defines the player promise, reset boundary, currency provenance, timing gate, Founder Focus relationship, and anti-exploit/anti-dark-pattern rules.
• The document states the evidence required before implementation and names the first-order metrics or player observations to collect.
• The document is linked from docs/INDEX.md without duplicating existing canon.
• No runtime code, save schema, economy behavior, or provider integration changes.

Files likely touched

• docs/design/angel-fund-layer.md (edit)
• docs/INDEX.md (edit)

Security considerations

None — design-only work; the spec must not contain credentials or private operational data. REFERENCE DOCS docs/research/economy-and-items.md docs/research/monetization-canon.md docs/design/core-loop.md docs/research/design-reconciliation.md docs/INDEX.md

Estimation

Estimated L, landed L — accurate

Handoff

The pastel visual direction is now represented in the current shell, but AD-17 explicitly requires a real-device contrast check before confidence can increase. This is a bounded validation task that protects the Design Award path and prevents browser-only evidence from being treated as device acceptance.

Effort estimate: XS

Scope

• Run the existing app on an available real device or faithful device build, inspect the pastel palette and primary game surfaces under normal brightness and text scaling, and compare the result with the contrast/readability conditions in AD-17. Record the observed surfaces, device/build identity, failures or passes, and the resulting confidence recommendation in the project's PAPI review/build evidence. If the check fails, create the smallest follow-up task or finding with the exact surface and repair needed.

Out of scope

• Do not redesign the palette speculatively, change AD-17 without observed evidence, add a new accessibility framework, or treat a browser screenshot as a real-device result. Do not make any public deployment or store submission.

Acceptance criteria

• A real-device or explicitly identified faithful-device validation record names the build, device/viewport, surfaces checked, and observed contrast/readability result.
• AD-17 confidence is updated only from that evidence, or remains unchanged with a precise reason if the device gate cannot be run.
• Any failure produces a bounded follow-up finding rather than an untracked visual concern.
• No source behavior changes are made unless a concrete accessibility defect is found and separately scoped.

Files likely touched

• docs/research/design-reconciliation.md (edit)
• docs/research/game-art-direction-research.md (edit)
• docs/INDEX.md (edit)
• src/ui/tokens.ts (edit)
• src/ui/GameScreen.tsx (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/research/game-art-direction-research.md docs/research/design-reconciliation.md docs/GAME_BRIEF.md

Estimation

Estimated XS, landed XS — accurate

Handoff

The exit loop and return signals now exist, so the previously premature focus choice can become a meaningful run identity. Offering a clear foreground-versus-absentee choice gives the player a reason to decide how this run should feel without adding provider dependencies.

Effort estimate: S

Scope

• Add a small, persistent Founder Focus choice after the first exit: Hands-On improves foreground assignment or active-work value, while Absentee improves offline accrual or cap behavior. Define the choice and its bounded effect using the existing economy/config and save contracts, expose the choice in the existing game shell, and show the current focus and its consequence. Add migration-safe persistence and focused tests for fresh state, selection, reload, and both effect paths.

Out of scope

• Do not add a second-order prestige currency, additional reset layers, subscription/IAP/ad integration, analytics, notifications, or a new settings/navigation system. Do not change the base economy outside the two explicit focus modifiers. Preserve forward-only save migrations and old-save defaults.

Acceptance criteria

• A player after the first exit can choose Hands-On or Absentee and can see the active choice and its effect.
• Hands-On changes only the documented foreground path; Absentee changes only the documented offline path/cap path.
• The choice survives save/reload with a forward-only migration and safe default for older saves.
• Focused tests cover fresh state, both choices, reload, and no cross-path modifier leakage.
• TypeScript and the full Jest suite pass.

Files likely touched

• src/game/store.ts (edit)
• src/persistence/save.ts (edit)
• src/economy/rules.ts (edit)
• src/economy/time.ts (edit)
• src/ui/GameScreen.tsx (edit)
• tests/game/store.test.ts (edit)
• tests/persistence/save.test.ts (edit)
• tests/economy/time.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/research/idle-curve-maths.md docs/research/economy-and-items.md docs/design/core-loop.md docs/GAME_BRIEF.md

Estimation

Estimated S, landed S — accurate

Handoff

Cycle 23 established latent defect and session-end state signals, but the incident outcome still needs player-legible language that makes recovery feel like a decision rather than an arbitrary penalty.

Effort estimate: M

Scope

• Audit the existing incident, latent-defect, and recovery copy on the actual completion and return paths.
• Replace generic failure wording with concise, in-world language that explains what went wrong and what recovery action is available.
• Make the recovery choice distinguishable from ordinary job completion without introducing a new resource.
• Preserve existing incident probabilities, rewards, caps, and save behavior.
• Add focused tests for the primary incident and recovery copy paths.

Out of scope

• Do not add rewarded video, purchases, or provider calls.
• Do not change incident probability or severity formulas in this task.
• Do not add a new failure state or rewrite the job economy.

Acceptance criteria

• An incident explains the problem in plain, game-appropriate language.
• The available recovery action and its cost are visible before the player commits.
• Ordinary success copy remains distinct from incident copy.
• Existing incident and save behavior is unchanged apart from presentation.
• Focused tests, full Jest, and TypeScript pass.

Files likely touched

• src/game/job-review.ts (edit)
• src/game/store.ts (edit)
• src/game/sessionEnd.ts (edit)
• src/ui/GameScreen.tsx (edit)
• tests/game/job-review.test.ts (edit)
• tests/game/sessionEnd.test.ts (edit)

Pre-build verification

• Read src/game/job-review.ts.
• Read src/game/store.ts.
• Read src/game/sessionEnd.ts.
• Read src/ui/GameScreen.tsx.
• Run a docs sweep through docs/INDEX.md and PAPI doc_search for incident, recovery, and monetization-canon guidance before implementing. If more than 80% of this scope already exists, report "already built" instead of re-implementing it.

Security considerations

None — no security-relevant changes.

Estimation

Estimated M, landed M — accurate

Handoff

Named milestones now persist, but players have no immediate confirmation or durable place to understand what they unlocked. This is the smallest player-facing layer that turns Cycle 23’s hidden progression into a visible reason to continue.

Effort estimate: S

Scope

• Add a compact in-game unlock toast when a new milestone is earned.
• Add a browsable milestone section using the existing game surface and existing visual tokens.
• Show unlocked and locked milestone states with readable names and concise completion conditions.
• Reuse the existing unlockedMilestones state and milestone definitions; do not create a second registry.
• Add focused UI/store coverage for toast timing, unlock display, and locked-state rendering.

Out of scope

• Do not introduce a new navigation framework or separate route.
• Do not add achievements, badges, push notifications, or social sharing.
• Do not change milestone rewards or persistence semantics.

Acceptance criteria

• A newly unlocked milestone produces one player-readable toast.
• Players can browse unlocked and locked milestones from the existing game screen.
• The screen uses the existing pastel visual system and remains readable on a phone viewport.
• Reopening the app preserves the unlocked milestone list without duplicate unlocks.
• Existing Jest and TypeScript checks pass.

Files likely touched

• src/ui/GameScreen.tsx (edit)
• src/game/store.ts (edit)
• src/game/milestones.ts (edit)
• tests/game/milestones.test.ts (edit)
• tests/ui/layout.test.ts (edit)

Pre-build verification

• Read src/game/milestones.ts.
• Read src/game/store.ts.
• Read src/ui/GameScreen.tsx.
• Read tests/ui/layout.test.ts.
• Run a docs sweep through docs/INDEX.md and PAPI doc_search for milestone and core-loop guidance before implementing. If more than 80% of this scope already exists, report "already built" instead of re-implementing it.

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

Cycle 23 added player-legible session-end state signals. This task can now rank truthful return reasons at the provider-neutral boundary without activating OneSignal or rewarding notification permission.

Effort estimate: M

Scope

• Extend the existing provider-neutral session-end signal selection to rank the new milestone, incident, and exit states.
• Preserve the two-per-absence cap and existing signal ordering for offline earnings and jobs finishing.
• Keep notification copy tied to a still-true player benefit.
• Add tests for priority ordering, cap enforcement, and the no-provider path.

Out of scope

• Do not add the OneSignal SDK, app credentials, native permission prompts, or network calls.
• Do not compensate players for enabling notifications.
• Do not change the existing offline earnings or job completion semantics.

Acceptance criteria

• New milestone, incident, and exit signals can be selected through the existing provider-neutral boundary.
• No absence produces more than two candidate signals.
• Existing offline and job-finished signal behavior remains compatible.
• Notification permission is never required for gameplay or rewards.
• Focused tests, full Jest, and TypeScript pass.

Files likely touched

• src/game/sessionEnd.ts (edit)
• src/game/store.ts (edit)
• tests/game/sessionEnd.test.ts (edit)

Pre-build verification

• Read src/game/sessionEnd.ts.
• Read src/game/store.ts.
• Read tests/game/sessionEnd.test.ts.
• Read docs/research/store-compliance.md.
• Run a docs sweep through docs/INDEX.md and PAPI doc_search for retention hooks and notification policy before implementing. If more than 80% of this scope already exists, report "already built" instead of re-implementing it.

Security considerations

No credentials or network access are introduced; notification permission remains optional.

Estimation

Estimated M, landed M — accurate

Handoff

Cycle 23 established named, persistent milestones but left the older build-in-public interaction path separate. Unifying the progression signal gives the milestone UI and post-draft work one authoritative event source and removes a dead interaction that conflicts with AD-15.

Effort estimate: XS

Scope

• Reuse the existing milestone definitions, unlock IDs, and store state.
• Make build-in-public progress contribute through the named milestone path rather than a separate three-tap mechanic.
• Remove the dead three-tap action and its reachable UI copy.
• Preserve the existing reputation and cash rules, save shape, and forward-only migration contract.
• Add focused regression coverage for milestone unlocks, build-in-public progress, and the removed interaction.

Out of scope

• Do not add a social network, external posting, analytics provider, or notification provider.
• Do not add a new currency, resource, save reset, or new milestone catalogue.
• Do not redesign the entire game shell.

Acceptance criteria

• Build-in-public progress is represented by the existing named milestone system.
• The dead three-tap mechanic and its player-facing entry point are removed.
• Existing milestone persistence and migration tests continue to pass.
• A fresh-save path can reach the unified build-in-public milestone state without external services.

Files likely touched

• src/game/milestones.ts (edit)
• src/game/store.ts (edit)
• src/ui/GameScreen.tsx (edit)
• tests/game/milestones.test.ts (edit)
• tests/game/context-rot.test.ts (edit)

Pre-build verification

• Read src/game/milestones.ts.
• Read src/game/store.ts.
• Read src/ui/GameScreen.tsx.
• Read tests/game/milestones.test.ts.
• Run a docs sweep through docs/INDEX.md and PAPI doc_search for build-in-public and milestone design before implementing. If more than 80% of this scope already exists, report "already built" instead of re-implementing it.

Security considerations

None — no security-relevant changes.

Estimation

Estimated XS, landed XS — accurate

Handoff

After the milestone event model is unified, milestone unlocks can produce a useful build-in-public draft without requiring an external account or network. This gives the player a shareable expression of progress while keeping the action truthful and optional.

Effort estimate: S

Scope

• Generate a deterministic local draft when a named milestone unlocks.
• Include the milestone name and a concise description of what changed in the company.
• Expose the draft through the existing game UI with copyable text or an equivalent local handoff.
• Ensure each unlock produces at most one draft and does not repeat after reload.
• Add pure tests for draft text and store-level tests for unlock provenance.

Out of scope

• Do not post to X, Discord, Reddit, or any other external service.
• Do not add authentication, clipboard permissions beyond the platform’s existing safe API, or analytics.
• Do not let generated copy claim revenue, players, or public traction that does not exist.

Acceptance criteria

• Each newly unlocked milestone produces one deterministic local draft.
• Drafts contain truthful milestone-specific language and no invented traction claims.
• Reloading the save does not duplicate the same draft.
• The player can view and copy the draft without connecting an external account.
• Focused tests and TypeScript pass.

Files likely touched

• src/game/milestones.ts (edit)
• src/game/store.ts (edit)
• src/ui/GameScreen.tsx (edit)
• tests/game/milestones.test.ts (edit)
• tests/game/context-rot.test.ts (edit)

Pre-build verification

• Read src/game/milestones.ts.
• Read src/game/store.ts.
• Read src/ui/GameScreen.tsx.
• Read tests/game/milestones.test.ts.
• Run a docs sweep through docs/INDEX.md and PAPI doc_search for build-in-public guidance before implementing. If more than 80% of this scope already exists, report "already built" instead of re-implementing it.

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

Incident presentation must be tuned against deterministic outcomes rather than intuition. This is a small quality task that makes the new incident language testable without introducing a staging service or external dependency.

Effort estimate: XS

Scope

• Add deterministic test fixtures or helpers for the existing incident probability and severity inputs.
• Cover representative low-risk, high-risk, and recovery-required outcomes.
• Assert that the resulting incident state remains bounded and compatible with the current economy guardrails.
• Keep the tooling local to Jest and existing configuration.

Out of scope

• Do not add a hosted staging environment, CI service, provider credential, or new dependency.
• Do not change the production probability model in this task.
• Do not add a second incident implementation.

Acceptance criteria

• Tests cover representative incident probability and severity boundaries.
• The fixtures are deterministic and do not depend on wall-clock timing or randomness.
• Existing economy guardrails continue to pass.
• The full Jest suite and TypeScript check pass.

Files likely touched

• src/economy/config.ts (edit)
• src/game/job-review.ts (edit)
• tests/economy/guardrails.test.ts (edit)
• tests/game/context-rot.test.ts (edit)

Pre-build verification

• Read src/economy/config.ts.
• Read src/game/job-review.ts.
• Read tests/economy/guardrails.test.ts.
• Read tests/game/context-rot.test.ts.
• Run a docs sweep through docs/INDEX.md and PAPI doc_search for incident and monetization guardrail guidance before implementing. If more than 80% of this scope already exists, report "already built" instead of re-implementing it.

Security considerations

None — no security-relevant changes.

Estimation

Estimated XS, landed XS — accurate

Handoff

The session-end explanation should point players toward a meaningful return reason after milestone state exists. DEPENDS ON task-81

Effort estimate: M

Scope

• Extend the pure session-end description with milestone-near, incident-pending, and exit-ready signals. Preserve the existing absence cap and stale-session semantics and keep output deterministic.

Out of scope

• Do not integrate OneSignal, credentials, push delivery, ads, or device-specific behavior.

Acceptance criteria

• Each new signal is emitted only from the corresponding bounded state.
• Existing session-end reasons and absence/stale caps remain unchanged.
• Focused tests cover the new signals and their precedence.

Files likely touched

• src/game/session-end.ts (edit)
• tests/game/session-end.test.ts (edit)

Security considerations

No external services or secrets.

Estimation

Estimated M, landed M — accurate

Handoff

Named, deterministic milestones are the lowest-risk retention signal and can feed later session messaging.

Effort estimate: M

Scope

• Add a pure milestone definition/evaluator with an initial bounded set of named achievements, persistent unlocked IDs, and small permanent global effects using the existing save migration rules.

Out of scope

• Do not build a milestone screen, push notifications, ads, IAP, or a new currency in this task.

Acceptance criteria

• Evaluating the same state twice is idempotent and returns only newly unlocked IDs.
• Definitions are named, deterministic, and bounded; unlocks persist through a forward-only save migration.
• Existing saves and economy guardrails remain compatible.

Files likely touched

• src/game/milestones.ts (edit)
• src/game/config.ts (edit)
• src/game/save.ts (edit)
• tests/game/milestones.test.ts (edit)

Security considerations

No external data or credentials; persisted IDs are local and validated.

Estimation

Estimated M, landed M — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed S — accurate

Handoff

Effort estimate: M

Estimation

Estimated S, landed S — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed M — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed M — accurate

Handoff

The current efficiency upgrade is the first half of the shop and cannot scale into a named tooling ladder without a shared, typed cost/effect contract and a safe save migration.

Effort estimate: M

Scope

• Introduce a generic upgradeCost(def, level) contract for named tooling upgrades and migrate the existing efficiency upgrade into a Linter definition. Preserve the existing efficiency behavior and caps, seed the Linter level from existing efficiency saves, and keep forward-only save migration semantics. Add focused tests for cost calculation, level caps, migration, purchase behavior, and regression of existing saves. Update the owning economy/progression documentation.

Out of scope

• Do not define all 10–12 tooling upgrades, build the shop UI, add IAP or ads, change the three-resource model, or reset existing saves. Do not add a backend or provider integration.

Acceptance criteria

• upgradeCost(def, level) is typed, deterministic, bounded, and covers the existing efficiency/Linter cost curve.
• Existing saves migrate efficiencyLevel to the Linter level without losing progress or changing unrelated state.
• Existing efficiency purchase behavior remains equivalent through the new contract.
• Focused tests cover formulas, caps, migration, purchase behavior, and malformed/legacy boundaries.
• Documentation identifies the Linter as the compatibility successor to efficiency.

Files likely touched

• src/economy/config.ts (edit)
• src/economy/rules.ts (edit)
• src/game/store.ts (edit)
• src/persistence/save.ts (edit)
• tests/economy/curve.test.ts (edit)
• tests/economy/checkpoints.test.ts (edit)
• tests/persistence/save.test.ts (edit)
• docs/design/progression-ladder.md (edit)
• docs/research/economy-and-items.md (edit)

Security considerations

None — local economy and save migration only; no credentials, network access, or user data. REFERENCE DOCS docs/design/progression-ladder.md docs/research/economy-and-items.md docs/design/economy-guardrails.md

Estimation

Estimated S, landed M — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed M — accurate

Handoff

Once task-74 defines the ladder, players need a readable place to understand and buy the next upgrade.

Effort estimate: M

Scope

• Add a focused shop surface to the existing game UI for the named tooling ladder. Show each upgrade's name, effect, level, cost, affordability state, and purchase action. Highlight the next affordable or closest affordable upgrade without hiding other choices. Reuse existing store actions, tokens, accessibility patterns, and responsive layout. Add focused UI/store coverage and run the design critique before implementation.

Out of scope

• Do not add IAP, ads, RevenueCat, new currency, new navigation architecture, or a separate shop application. Do not change the task-75/task-74 economy formula.

Acceptance criteria

• A player can identify each tool's purpose, level, cost, and purchase state.
• The next affordable or closest affordable tool is clear without hiding other choices.
• Purchase actions use the authoritative store path and update visible state.
• The surface works at handset width with accessible labels and disabled states.
• Tests cover affordable, unaffordable, maxed, and post-purchase states.

Files likely touched

• src/ui/GameScreen.tsx (edit)
• src/ui/tokens.ts (edit)
• src/game/store.ts (edit)
• tests/ui/tooling-shop.test.ts (edit)
• docs/design/progression-ladder.md (edit)
• docs/INDEX.md (edit)

Security considerations

None — local UI and existing local store actions only. REFERENCE DOCS docs/design/progression-ladder.md docs/design/game-feel.md docs/research/economy-and-items.md

Estimation

Estimated M, landed M — accurate

Handoff

The game now has a visible risk/recovery loop and a first company exit; players and future builders need one truthful reference.

Effort estimate: S

Scope

• Create a concise player manual linked from docs/INDEX.md or docs/README.md. Explain assignment, Cash/AI tokens/Reputation, agents and Vibe, review versus ship, incidents/refactoring, the first exit, carry-over, and reset. Add a small maintenance section naming authoritative sources and requiring behavior-changing tasks to update affected docs in the same change. Add review headers to documents updated by this task.

Out of scope

• Do not rewrite historical research, add store-policy promises, document unimplemented SDKs or monetization, duplicate rules, publish the manual, or change repository visibility.

Acceptance criteria

• A new player can understand how to start, the three resources, quality/recovery, and the first exit in a few minutes.
• Every player-facing claim matches shipped code and canonical docs.
• The manual is linked from the docs index and the maintenance rule names authoritative sources.
• Updated documents carry a current review header with task ID and date.
• A documentation review confirms no unsupported SDK, store, or monetization claim.

Files likely touched

• docs/player-manual.md (edit)
• docs/INDEX.md (edit)
• docs/README.md (edit)
• docs/design/core-loop.md (edit)
• docs/design/company-prestige.md (edit)
• docs/research/economy-and-items.md (edit)

Security considerations

None — repository documentation only; keep it private and exclude credentials and private infrastructure details. REFERENCE DOCS PRODUCT.md docs/GAME_BRIEF.md docs/design/core-loop.md docs/design/company-prestige.md docs/research/economy-and-items.md

Estimation

Estimated S, landed S — accurate

Handoff

The new progression and risk loop needs a typed, privacy-safe event contract. Cycle 20 provides an authoritative exit lifecycle.

Effort estimate: M

Scope

• Extend the provider-neutral analytics contract for tooling views/purchases, incident appearance/resolution, company exits, and milestone-related events only where a real milestone state exists. Wire existing runtime paths with privacy-minimal properties. Keep collection disabled and provider integration outside this task. Add event-shape and real-path coverage.

Out of scope

• Do not add Firebase, RevenueCat, OneSignal, device identifiers, remote transport, dashboards, or a milestone system. Do not emit fake milestone events; document contract-only events awaiting task-81.

Acceptance criteria

• New event names and properties are typed and provider-neutral.
• Tooling purchase, incident/recovery, and company-exit paths emit intended events once.
• Properties contain no credentials, free-form prompts, or direct identifiers.
• Tests cover shapes, duplicate suppression, and available runtime paths.
• Collection remains disabled.

Files likely touched

• src/analytics/events.ts (edit)
• src/analytics/index.ts (edit)
• src/game/incidents.ts (edit)
• src/game/prestige.ts (edit)
• src/game/store.ts (edit)
• tests/analytics/events.test.ts (edit)
• tests/game/incidents.test.ts (edit)
• tests/game/prestige.test.ts (edit)
• docs/research/analytics-tooling.md (edit)

Security considerations

Review payloads for privacy minimization; add no credentials, identifiers, prompts, or network transport. REFERENCE DOCS docs/research/analytics-tooling.md docs/design/retention-hooks.md docs/design/company-prestige.md

Estimation

Estimated M, landed M — accurate

Handoff

The current shop is too narrow to give the player a meaningful build. The generalized upgrade foundation in task-75 must land first.

Effort estimate: M

Scope

• Define 10–12 named tooling upgrades in the existing economy configuration. Give each a clear Cash cost curve, level cap, and player-visible effect across existing mechanics. Keep the Linter/efficiency migration from task-75 canonical. Add focused economy coverage for definitions, costs, caps, and effects.

Out of scope

• Do not build the shop UI, IAP products, rewarded-video placements, new agent skills, or a second economy. Do not add mechanics without a present runtime consumer.

Acceptance criteria

• Named tooling definitions are typed, deterministic, and use task-75's shared upgrade-cost contract.
• Every upgrade has a bounded cap, cost, and effect covered by focused tests.
• Existing efficiency saves and purchases remain compatible through the Linter mapping.
• Configuration and design documentation explain each upgrade's player-facing purpose.

Files likely touched

• src/economy/config.ts (edit)
• src/economy/rules.ts (edit)
• src/game/store.ts (edit)
• tests/economy/curve.test.ts (edit)
• tests/economy/guardrails.test.ts (edit)
• docs/design/progression-ladder.md (edit)
• docs/research/economy-and-items.md (edit)

Security considerations

None — local economy configuration only. REFERENCE DOCS docs/design/progression-ladder.md docs/research/economy-and-items.md docs/design/economy-guardrails.md

Estimation

Estimated M, landed M — accurate

Handoff

The first exit must arrive during the first meaningful session, and task-71 provides the authoritative lifecycle to calibrate.

Effort estimate: S

Scope

• Retune the existing first-exit timing and eligibility constants to target 25–40 minutes, update the associated deterministic tests, and revise docs/design/company-prestige.md so the old 90–180 minute target is no longer authoritative. Preserve the existing contract and progression model. The result is complete when a fresh-save simulation reaches the documented target range under the repository’s standard timing assumptions.

Out of scope

• Do not redesign prestige, add new resources, change the Founder Tree, or alter monetization.

Acceptance criteria

• The authoritative timing target is 25–40 minutes.
• Tests cover the revised timing and eligibility boundaries.
• No remaining authoritative document states the superseded 90–180 minute target.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/game/rules.ts (edit)
• src/game/prestige.ts (edit)
• docs/design/company-prestige.md (edit)
• tests/economy/prestige.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md

Estimation

Estimated S, landed S — accurate

Handoff

The tree is the first meaningful consumer of prestige progression and can now be built after the Equity boundary is defined.

Effort estimate: M

Scope

• Add a typed Founder Tree definition and pure unlock/purchase evaluator for 12–16 permanent nodes across Capital, Talent, Infrastructure, and Reputation. Enforce the documented opportunity-cost and capstone rules, persist purchased nodes through the existing save schema, and expose a stable model for the later Founder Tree screen. The result is complete when valid choices persist, invalid choices are rejected, and the evaluator is independently testable.

Out of scope

• Do not build the full Founder Tree screen, second-order Angel/Fund prestige, randomized rewards, or new resources.

Acceptance criteria

• The four branches and 12–16 named nodes are represented by typed definitions.
• Opportunity-cost and prerequisite rules are enforced.
• Purchased nodes persist through forward-only save migration.
• Invalid purchases do not mutate state.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/game/founder-tree.ts (edit)
• src/game/prestige.ts (edit)
• src/persistence/save.ts (edit)
• tests/game/founder-tree.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md

Estimation

Estimated M, landed M — accurate

Handoff

The first-exit contract is being established this cycle, so the player-facing transition should consume its result rather than present a raw reset.

Effort estimate: M

Scope

• Create a focused exit-summary presentation using the existing screen and UI patterns. Show what the player achieved, what carries forward, the Equity result, and the explicit confirmation boundary before reset; after confirmation, invoke the task-71 transition rather than duplicating reset logic. Read PRODUCT.md for product purpose, users and design principles, and DESIGN.md for visual tokens; run impeccable init if either file is missing and use the frontend-design skill for implementation. For this M-sized UI task, use the full impeccable workflow: shape → craft → live → detect. The result is complete when a player can understand the gain and consequence of exiting before confirming.

Out of scope

• Do not implement the prestige calculation, Founder Tree, new IAP, or second-order prestige. Do not duplicate reset logic inside the UI.

Acceptance criteria

• The exit summary clearly presents achievements, carry-over values, Equity, and the confirmation action.
• Confirmation calls the authoritative prestige transition from task-71.
• Cancel/back leaves the operating save unchanged.
• Visually verify rendered output in browser — provide localhost URL or screenshot to user for review.
• No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/ui/GameScreen.tsx (edit)
• src/ui/exit-sequence.ts (edit)
• src/game/prestige.ts (edit)
• tests/ui/exit-sequence.test.ts (edit)

Security considerations

None — no security-relevant changes.

Estimation

Estimated M, landed M — accurate

Handoff

Equity is the reset-boundary value required by the Founder Tree and permanent prestige multiplier, and task-71 supplies the exit result it consumes.

Effort estimate: S

Scope

• Extend the completed prestige result with deterministic Equity earned from exited-company lifetime Reputation. Persist it through the existing forward-only save migration path, but keep it outside the operating HUD and unavailable as a mid-run spendable resource. The result is complete when an exit awards the documented Equity value and repeated loading preserves it without introducing a fourth operating currency.

Out of scope

• Do not build Founder Tree nodes, a shop screen, an Equity IAP, or a second-order prestige layer.

Acceptance criteria

• Equity is calculated deterministically from exited-company lifetime Reputation.
• Equity is awarded only at the exit boundary and persists across saves.
• Equity is not shown or spent as a fourth operating resource.
• Existing saves migrate without reset or loss.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/game/prestige.ts (edit)
• src/game/store.ts (edit)
• src/persistence/save.ts (edit)
• tests/game/prestige.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md

Estimation

Estimated S, landed S — accurate

Handoff

The AD-12 dependency is resolved, and the first exit is the prerequisite for Equity, Founder Tree, first-exit timing, first-exit analytics, and the prestige presentation.

Effort estimate: M

Scope

• Implement the authoritative first-exit transition in src/game/prestige.ts, reusing the existing company-prestige rules and persistence contracts. Define eligibility, produce an atomic reset snapshot, preserve the documented carry-over values, and prevent reset during an active purchase or restore. The result is complete when a player can perform a valid exit without losing protected progress or purchased value, and invalid exits leave the save unchanged.

Out of scope

• Do not implement the Founder Tree, Equity multiplier, exit animation, analytics events, or new monetization products in this task.

Acceptance criteria

• A valid exit produces the documented reset and carry-over result.
• Invalid or ineligible exits do not mutate the save.
• Purchase and restore activity cannot be reset mid-operation.
• Save migrations remain forward-only and preserve existing player progress.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/game/prestige.ts (edit)
• src/game/store.ts (edit)
• src/persistence/save.ts (edit)
• tests/game/prestige.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/company-prestige.md docs/design/depth-audit.md

Estimation

Estimated M, landed M — accurate

Handoff

Once Equity exists at the reset boundary, a deterministic RevenueCat purchase can provide the flagship prestige monetization surface without introducing randomized or deceptive value.

Effort estimate: S

Scope

• Add one deterministic RevenueCat product for a permanent Equity multiplier using the existing monetization integration and entitlement/restore conventions. Apply the multiplier only to future eligible Equity awards, make purchase and restore idempotent, and keep the product value explicit in the shop copy. The result is complete when sandbox purchase, restore, and repeat-load paths produce the same entitlement state without requiring a backend.

Out of scope

• Do not add randomized paid items, hidden odds, subscriptions, a new backend, or other IAP products.

Acceptance criteria

• The product has deterministic, explicit value and uses the existing RevenueCat path.
• Purchase and restore are idempotent across reloads.
• The multiplier affects future Equity awards without changing Reputation or creating a fourth operating currency.
• No secret RevenueCat credential is stored in source or logs.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/monetization/revenuecat.ts (edit)
• src/monetization/catalog.ts (edit)
• src/game/prestige.ts (edit)
• tests/monetization/revenuecat.test.ts (edit)

Security considerations

Use only the public client configuration required by the existing RevenueCat SDK. Never embed private API keys, receipt secrets, or credentials; do not log purchase tokens or receipt contents. REFERENCE DOCS docs/design/depth-audit.md

Handoff

Effort estimate: M

Estimation

Estimated M, landed XS — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed M — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed S — accurate

Handoff

This is the clearest player-facing expression of vibe coding: accept speed and risk, or spend time verifying the work before shipping.

Effort estimate: M

Scope

• Add an optional completion decision in the existing job-finished flow: review the work or ship immediately.
• Make review consume agent time or capacity and reduce the chance of a later incident; shipping immediately remains viable but carries the existing tech-debt risk.
• Reuse the incident and recovery contract from task-78 so later failures can identify whether the job was reviewed.
• Keep the decision legible in one existing surface with concise copy and no new resource.
• Done means both choices are playable, observably different, and covered by deterministic tests.

Out of scope

• Do not add rewarded-ad review, prompt-library collection, new review grades, or a separate review screen.

Acceptance criteria

• Players can choose review or immediate shipment at job completion.
• The two choices produce a measurable, documented difference in risk or time.
• Later incidents retain enough provenance to show whether the job was reviewed.
• Both routes remain viable without a forced purchase or ad.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/screens/GameScreen.tsx (edit)
• src/game/job-review.ts (edit)
• src/game/incidents.ts (edit)
• src/economy/rules.ts (edit)
• tests/game/job-review.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md §6.3 docs/design/job-system.md

Estimation

Estimated M, landed M — accurate

Handoff

The roster needs an ongoing management decision beyond headcount, and context rot supplies a recognisable cause for slower, less reliable work.

Effort estimate: M

Scope

• Track bounded per-agent context rot during continuous work in the existing local game state.
• Increase rot over sustained uninterrupted work and clear or reduce it through the smallest existing reset, reassignment, or rest action.
• Feed rot into the agent’s duration or quality outcome using existing rules; do not add a new currency.
• Add tests covering accumulation, bounds, clearing, and offline/foreground consistency.
• Done means a continuously working agent measurably degrades, the player can clear the state, and the behavior survives save/load.

Out of scope

• Do not build the Vibe meter, model-personality system, new agent types, or a roster redesign.

Acceptance criteria

• Context rot is bounded, observable through agent behavior, and clearable by a player action.
• The mechanic does not create a fourth resource or break existing save migrations.
• Tests cover continuous work, reset behavior, bounds, and persistence.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/game/context-rot.ts (edit)
• src/persistence/save.ts (edit)
• src/screens/GameScreen.tsx (edit)
• tests/game/context-rot.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md

Estimation

Estimated M, landed M — accurate

Handoff

After incidents and context rot exist, a derived Vibe state can make clean runs feel good, give the game a readable mood, and connect the name to the core loop without violating AD-12.

Effort estimate: M

Scope

• Add a bounded derived Vibe state that rises after clean ships and consecutive successes and falls after incidents, rework, and context rot.
• Render the meter in the existing game surface using the established design tokens, with readable labels and no new currency wallet.
• Apply one conservative output or quality multiplier while the meter is high; keep the free route fully playable at low Vibe.
• Add deterministic tests for increase, decay, bounds, and the multiplier.
• Done means players can see Vibe change after the selected gameplay events and understand that it is a temporary state, not spendable currency.

Out of scope

• Do not add a fourth resource, monetized Vibe boosts, a new visual theme system, or a complete balance pass across every economy curve.

Acceptance criteria

• Vibe rises and decays from the specified gameplay events and remains bounded.
• The meter is visible in the existing game surface and uses named design tokens.
• Vibe affects output or quality through one documented, testable multiplier.
• Low Vibe does not block ordinary progress or create a forced purchase path.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/game/vibe.ts (edit)
• src/screens/GameScreen.tsx (edit)
• src/economy/rules.ts (edit)
• tests/game/vibe.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md DESIGN.md

Estimation

Estimated M, landed M — accurate

Handoff

Once tech debt can create risk, the game needs a legible consequence and a meaningful recovery choice rather than unexplained punishment.

Effort estimate: M

Scope

• Add the smallest incident state and resolution contract after a job failure, consuming the probability/severity functions from task-77.
• Make an incident fail or interrupt the affected job, place Reputation at risk, and expose a refactor/recovery action that costs time or capacity instead of Cash payout.
• Preserve the existing no-reset save migration contract and ensure Reputation can decrease without corrupting company-stage progression.
• Add concise player-facing copy in the existing GameScreen flow explaining what happened, which job caused it, and what recovery costs.
• Done means an incident can be traced to its originating job, resolved through the intended recovery action, and verified through tests.

Out of scope

• Do not add rewarded video, Vibe meter behavior, new incident varieties, or a complete rework of the job board.

Acceptance criteria

• Incidents are attributable to a specific job and expose a deterministic recovery path.
• Reputation loss and stage-regression behavior are intentional and visibly explained.
• Refactor/recovery has a real opportunity cost and does not silently grant normal job payout.
• Save migration and incident resolution tests pass.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/economy/rules.ts (edit)
• src/persistence/save.ts (edit)
• src/screens/GameScreen.tsx (edit)
• src/game/incidents.ts (edit)
• tests/game/incidents.test.ts (edit)

Security considerations

None — game state remains local and no credentials or external endpoints are introduced. REFERENCE DOCS docs/design/depth-audit.md §6.3

Estimation

Estimated M, landed M — accurate

Handoff

The game currently has no meaningful downside. This is the foundation for incidents, the vibe-check decision, and future rescue monetization while preserving the three-resource rule.

Effort estimate: M

Scope

• Add bounded `techDebt` to the local save state with a forward-only migration through `src/persistence/save.ts`.
• Add pure `incidentChance` and `incidentSeverity` calculations in `src/economy/rules.ts`, driven by tech debt and existing job/tooling inputs.
• Accrue debt through the existing completed-job path without creating a fourth resource or changing Cash, AI tokens, or Reputation semantics.
• Add focused economy and migration tests.
• Done means a shipped job can increase bounded tech debt, pure rules return deterministic values, and older saves load without resetting progress.

Out of scope

• Do not build the incident UI, incident resolution flow, rewarded-video rescue offer, or vibe-check interaction in this task.

Acceptance criteria

• `techDebt`, `incidentChance`, and `incidentSeverity` are implemented with bounded, deterministic behavior.
• Existing saves migrate forward without losing player progress.
• Focused tests cover accrual, bounds, deterministic calculations, and migration.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/economy/rules.ts (edit)
• src/persistence/save.ts (edit)
• src/config.ts (edit)
• tests/economy/guardrails.test.ts (edit)
• tests/persistence/save.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md §6.3

Estimation

Estimated M, landed M — accurate

Handoff

The game needs failures that emerge after apparent success, making the review decision meaningful and giving incidents a traceable cause.

Effort estimate: M

Scope

• Extend the incident flow so a job can complete and pay normally while retaining a bounded latent-defect state.
• Resolve that latent defect later through the existing incident path, with the originating job and contributing risk visible to the player.
• Keep the result deterministic under tests and avoid random punishment that cannot be explained from state.
• Done means at least one successful-looking job can later produce an attributable incident without deleting its original payout.

Out of scope

• Do not add new currencies, multiple defect classes, ad rescue, or a full simulation of software bugs.

Acceptance criteria

• A job can pay successfully while retaining a bounded latent defect.
• A later incident identifies the originating job and explains the causal risk.
• Original job payout and player progress are preserved.
• Regression tests cover both reviewed and unreviewed or equivalent risk paths.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items are documented if discovered during implementation.

Files likely touched

• src/game/incidents.ts (edit)
• src/persistence/save.ts (edit)
• src/screens/GameScreen.tsx (edit)
• tests/game/incidents.test.ts (edit)

Security considerations

None — no security-relevant changes. REFERENCE DOCS docs/design/depth-audit.md §6.3

Estimation

Estimated M, landed M — accurate

Handoff

Cycle 17 design work is planned and blocked only by its missing persisted handoff.

Effort estimate: L

Scope

• Read progression-ladder.md and trace the existing stage selector/state.
• Create visually distinct office compositions for Solo Coder, Tiny Studio, and Growing Company using a shared stage-driven renderer.
• Make room occupancy and props reflect growth without altering progression calculations; add per-stage render coverage.

Out of scope

• Do not change unlock thresholds, economy balance, or save schema unless existing stage state cannot be consumed.
• Do not create separate app shells per stage or duplicate common assets.

Acceptance criteria

• Each required company stage has an immediately distinguishable office composition.
• The visible room grows through desks, people, props, and spatial density using existing progression state.
• Switching stages remains deterministic and covered by tests/captures.
• No parallel stage-specific application path is introduced.

Files likely touched

• docs/design/progression-ladder.md (edit)
• DESIGN.md (edit)
• src/ui (edit)
• src/game (edit)
• assets (edit)
• tests (edit)

Pre-build verification

• docs/design/progression-ladder.md
• DESIGN.md
• src/ui
• src/game
• Sweep the docs index/doc_search for final design or prior-task evidence; if more than 80% already exists, report already built instead of duplicating it.

Security considerations

None — local visual state only.

Estimation

Estimated L, landed S — accurate

Handoff

Cycle 17 design work is planned and blocked only by its missing persisted handoff.

Effort estimate: S

Scope

• After the app shell, agent art, and stage offices are accepted, capture new store screenshots and demo footage from the real release candidate.
• Replace the greybox v0.11.0 marketing set and update the asset manifest with release/commit provenance.
• Run bounded structural media checks plus visual review of beginning, middle, end, and every screenshot.

Out of scope

• Do not fabricate UI or capture from mocks.
• Do not regenerate accepted source art merely to fit capture tooling.
• Do not publish or alter store listings without separate explicit authorization.

Acceptance criteria

• Store screenshots show the accepted production art at required device dimensions with no greybox surfaces.
• The demo video truthfully shows the current release candidate and passes duration/codec/opening-ending checks.
• The manifest records exact source commit, release identity, dimensions, hashes, and review status.
• Old greybox assets are retired from the production submission path without deleting required history.

Files likely touched

• assets/store/task-29-manifest.md (edit)
• assets/store (edit)
• scripts (edit)
• package.json (edit)

Pre-build verification

• assets/store/task-29-manifest.md
• assets/store
• scripts
• package.json
• Sweep the docs index/doc_search for final design or prior-task evidence; if more than 80% already exists, report already built instead of duplicating it.

Security considerations

Do not expose credentials, private dashboards, personal notifications, or unrelated device data in captures.

Estimation

Estimated S, landed S — accurate

Handoff

Cycle 17 design work is planned and blocked only by its missing persisted handoff.

Effort estimate: M

Scope

• Read DESIGN.md and the current app shell before changing code.
• Replace the GreyboxScreen presentation with the canonical visual language while preserving the existing game-state and action contracts.
• Add focused rendering/interaction coverage for the revised shell.

Out of scope

• Do not redesign game rules, economy, persistence, or monetization.
• Do not create a parallel shell or retain GreyboxScreen as an alternate production path.

Acceptance criteria

• The production entry path no longer renders GreyboxScreen.
• The app shell applies the hierarchy, spacing, colour, and character direction defined in DESIGN.md.
• Existing player actions and state transitions remain covered and pass.

Files likely touched

• DESIGN.md (edit)
• src/ui/GreyboxScreen.tsx (edit)
• src/App.tsx (edit)
• src/ui (edit)
• tests (edit)

Pre-build verification

• DESIGN.md
• src/ui/GreyboxScreen.tsx
• src/App.tsx
• src/ui
• Sweep the docs index/doc_search for final design or prior-task evidence; if more than 80% already exists, report already built instead of duplicating it.

Security considerations

None — presentation-only work; do not add network access or secrets.

Estimation

Estimated M, landed S — accurate

Handoff

Cycle 17 design work is planned and blocked only by its missing persisted handoff.

Effort estimate: S

Scope

• Read DESIGN.md and inventory existing colour and typography literals.
• Create one shared typed style/tokens module for the eight canonical palette roles and typography.
• Migrate affected UI, including ReportAdPanel, away from ad-hoc palette hex values and add contrast/token tests.

Out of scope

• Do not redesign layouts or produce character art.
• Do not add a styling framework or duplicate token modules.

Acceptance criteria

• All eight DESIGN.md palette roles are exported from one shared module.
• Production UI no longer hardcodes competing palette hex values.
• Normal text/background combinations used by the UI meet a 4.5:1 contrast baseline.
• Token and affected UI tests pass.

Files likely touched

• DESIGN.md (edit)
• src/ui/ReportAdPanel.tsx (edit)
• src/ui (edit)
• src/styles (edit)
• tests (edit)

Pre-build verification

• DESIGN.md
• src/ui/ReportAdPanel.tsx
• src/ui
• src/styles
• Sweep the docs index/doc_search for final design or prior-task evidence; if more than 80% already exists, report already built instead of duplicating it.

Security considerations

None — local presentation constants only.

Estimation

Estimated S, landed S — accurate

Handoff

Cycle 17 design work is planned and blocked only by its missing persisted handoff.

Effort estimate: L

Scope

• Audit DESIGN.md and the current asset pipeline before producing assets.
• Create the canonical agent pixel-art set with readable silhouettes, expressive faces, varied hair, and one recognition accent per agent.
• Integrate agents into the roster/workspace through one reusable asset/component path and add asset/render checks.

Out of scope

• Do not use placeholder programmer art or text rows as the final representation.
• Do not duplicate immutable assets across worktrees or introduce a second rendering application.
• Do not redesign economy or agent stats.

Acceptance criteria

• Agents are visually represented as people in the shipped UI, not only text rows.
• The set follows DESIGN.md silhouette, face, hairstyle, and accent guidance at target device scale.
• Assets have one canonical location and render without missing-file fallbacks.
• Asset and UI verification passes.

Files likely touched

• DESIGN.md (edit)
• assets (edit)
• src/ui (edit)
• src/components (edit)
• tests (edit)

Pre-build verification

• DESIGN.md
• assets
• src/ui
• src/components
• Sweep the docs index/doc_search for final design or prior-task evidence; if more than 80% already exists, report already built instead of duplicating it.

Security considerations

No secrets or external player data; retain asset provenance and licensing records.

Estimation

Estimated L, landed XS — accurate

Handoff

Cycle 17 design work is planned and blocked only by its missing persisted handoff.

Effort estimate: XS

Scope

• Inspect the roster panel and the referenced shipped screenshot.
• Change roster sizing/layout so a one-row roster does not stretch into a large empty panel.
• Add a focused layout or render regression covering sparse and populated rosters.

Out of scope

• Do not reshoot store assets in this task.
• Do not change roster data, hiring rules, or progression.

Acceptance criteria

• A one-agent roster no longer produces the documented 1700px empty region.
• The roster remains usable when populated and at the target mobile viewport.
• Focused regression coverage passes.

Files likely touched

• assets/store/screenshot-1179x2556-v0.11.0.png (edit)
• docs/design/depth-audit.md (edit)
• src/ui/GreyboxScreen.tsx (edit)
• src/ui (edit)
• tests (edit)

Pre-build verification

• assets/store/screenshot-1179x2556-v0.11.0.png
• docs/design/depth-audit.md
• src/ui/GreyboxScreen.tsx
• src/ui
• Sweep the docs index/doc_search for final design or prior-task evidence; if more than 80% already exists, report already built instead of duplicating it.

Security considerations

None — layout-only work.

Estimation

Estimated XS, landed XS — accurate

Handoff

Effort estimate: M

Estimation

Estimated M, landed M — accurate

Handoff

task-10 (OneSignal) depends on a session-end hook, while the existing store only persists last-seen time and computes offline earnings implicitly. A provider-neutral contract is the smallest unblocked step toward meaningful, non-deceptive retention.

Effort estimate: S

Scope

• Define a provider-neutral session-end return signal at the existing game-state/persistence boundary. Capture the minimum durable facts a future notification adapter needs: whether the session ended with a meaningful return opportunity, the reason/category, and the time or expiry boundary needed to avoid stale prompts. Reuse the existing offline earnings and save model where possible. Add focused unit tests for meaningful and non-meaningful exits, repeated exits, and forward-compatible persistence/migration behavior. Document the contract and its handoff to task-10.

Out of scope

• Do not install OneSignal or another push provider. Do not request notification permission, send notifications, add credentials, change monetization, add rewarded video, claim device/store delivery evidence, or redesign the idle economy or rolling offer chain.

Acceptance criteria

• A typed provider-neutral session-end return signal exists at the existing game-state/persistence boundary and records reason plus validity/expiry information.
• The signal is emitted only for a meaningful return opportunity and is deterministic across duplicate exits.
• Persistence remains forward-compatible and does not reset existing saves; migration behavior is tested.
• Focused tests cover meaningful exit, no-op exit, duplicate exit, and stale/expired signal behavior.
• task-10 can consume the contract without importing a notification SDK or credentials.
• Documentation names the contract, consumer, and remaining provider/permission work.

Files likely touched

• src/game/store.ts (edit)
• src/persistence/save.ts (edit)
• src/economy/time.ts (edit)
• tests/persistence/save.test.ts (edit)
• docs/GAME_BRIEF.md or docs/research/monetization-canon.md (edit)
• docs/INDEX.md (edit)

Security considerations

Do not persist notification tokens, device identifiers, or account data. Keep the signal local and add no credentials or network calls. REFERENCE DOCS - docs/GAME_BRIEF.md - docs/research/monetization-canon.md - docs/research/store-compliance.md - docs/PAPI_TEAM_PROTOCOL.md

Estimation

Estimated S, landed S — accurate

Handoff

The strategy review identified this as the bottleneck for rewarded placements, ad compliance, and RevenueCat's blended IAP-plus-ad reporting. External provisioning is not yet proven, but repository inspection, provider selection, configuration contracts, credential-free integration seams, and tests are executable now and will turn the remaining account work into explicit, bounded gates.

Effort estimate: M

Scope

• Inspect the current Expo 57 managed application, package dependencies, app configuration, and monetization research before choosing an integration path.
• Select and document one mediation provider using current constraints: Expo compatibility, RevenueCat Ads/ILRD support, Android effort, account requirements, beta-access requirements, and suitability for later rewarded placements. Prefer AdMob only if repository and current SDK compatibility evidence supports its lower-friction `loadAndTrack` path; record the reason if another provider is selected.
• Add the smallest credential-free application boundary needed to receive normalized impression-level revenue data and forward it to a RevenueCat ad-revenue tracker once native SDKs and credentials are available. Keep gameplay independent from provider-specific payloads.
• Add typed configuration validation for required non-secret identifiers and explicit unavailable/not-configured behavior. Do not place account IDs, API keys, tokens, or test credentials in source control.
• Add focused tests covering provider-payload normalization, forwarding behavior, malformed or incomplete events, and the unconfigured local/test path.
• Add only provider and RevenueCat dependencies that can be installed and compiled without credentials and whose Expo 57 compatibility is verified from authoritative package metadata or documentation. If a native dependency cannot be safely added yet, leave the boundary compiling with a documented adapter gate rather than inventing an SDK API.
• Record a checklist of external gates with evidence fields: mediation account creation, application registration, Android app/ad-unit identifiers, ILRD enablement, RevenueCat Ads beta enrollment, dashboard linkage, test-device registration, consent configuration, and one verified test impression.
• Done means the repository contains a documented provider decision, a compiling credential-free ILRD boundary with passing tests, and a precise external-gate checklist that distinguishes completed local work from unverified account work.

Out of scope

• Do not create external accounts, accept provider terms, enroll in a beta, enter billing details, or claim dashboard configuration without authenticated evidence.
• Do not add rewarded placement UX or reward economy behavior; that belongs to task-8.
• Do not build the content-rating filter or report-an-ad route; that belongs to task-35.
• Do not hardcode secrets, production ad-unit IDs, fabricated ILRD receipts, or simulated revenue as proof of a live integration.
• Do not add a backend, analytics platform, generalized event bus, or multi-provider abstraction beyond the single selected provider boundary.

Acceptance criteria

• A registered integration note names the selected mediation provider and compares it against the viable alternative using Expo 57, RevenueCat Ads/ILRD, effort, and account-gate evidence.
• The application has one typed, provider-bounded path for normalizing an impression revenue event and forwarding it to the RevenueCat tracking boundary.
• Missing configuration and malformed impression payloads fail safely without crashing gameplay or fabricating revenue.
• Automated tests cover normalization, forwarding, malformed input, and the unconfigured local/test path.
• `npm test -- --runInBand` passes.
• `npm run typecheck` passes.
• No credentials, secrets, production identifiers, or invented dashboard receipts are committed.
• External provisioning and live-verification gates are recorded individually with owner, required evidence, and current status.
• Scope matches handoff — no unrelated code changed.
• Out-of-scope items documented if discovered during implementation.

Files likely touched

• package.json (edit)
• package-lock.json (edit)
• app.json (edit)
• src/monetization/adRevenue.ts (edit)
• src/monetization/adRevenueConfig.ts (edit)
• tests/monetization/adRevenue.test.ts (edit)
• docs/research/ad-mediation-integration.md (edit)
• docs/INDEX.md (edit)

Pre-build verification

• Read `package.json` and `package-lock.json` to confirm the installed Expo/React Native versions and whether RevenueCat or advertising SDK work already exists.
• Read `app.json` to verify the Android package identity and existing Expo plugin configuration before adding any native integration.
• Read `src/game/store.ts` to keep advertising/revenue tracking outside the gameplay state and offline loop.
• Read `docs/research/category-strategy.md` and `docs/research/monetization-canon.md` through `doc_search`/the registered docs index, then inspect `docs/INDEX.md` for any newer design, research, prior-task, or status:final document covering mediation or RevenueCat Ads.
• If more than 80% of the provider decision, typed integration seam, tests, and external-gate record already exist, report “already built” instead of re-implementing.

Security considerations

Treat mediation and RevenueCat credentials, application identifiers, and dashboard receipts as sensitive configuration. Commit only documented environment/configuration names and safe test fixtures; redact secrets and personal/account data from logs and evidence. REFERENCE DOCS docs/research/category-strategy.md

Estimation

Estimated M, landed M — accurate

Handoff

Second half of the owner-directed reusables adoption addressing the "no design to it" feedback — the secondary surfaces where ad-hoc styling is most visible after the core loop is migrated.

Effort estimate: S

Scope

• Read PRODUCT.md and DESIGN.md first — every visual decision aligns with them; run `impeccable init` to create them if missing. Use the frontend-design skill for implementation. Run design-critique on the target surfaces before building.
• Migrate the secondary surfaces — shop/tooling cards (task-97/100/171 lineage), the More/profile editors (task-182/185/194 lineage), and the milestone toast/surfaces (task-236 lineage) — to src/ui/primitives and DESIGN.md token roles.
• Retire ad-hoc hex and raw font literals on exactly these surfaces.
• Preserve accessibility contracts already established on these surfaces (task-180 close buttons, task-194 editor labels).
• Verify headlessly at 127.0.0.1:8081 with the scoped playtest pattern; avoid the stale broad FTUE script.
• Done looks like: the named secondary surfaces render via primitives/tokens, verified in the browser and by tests.

Out of scope

• Do not touch the core gameplay surfaces (new-5's scope).
• Do not add NativeWind/Uniwind, the upstream CLI, or any dependency.
• Do not change shop economics, tooling status filtering, or editor behaviour — presentation only.

Acceptance criteria

• Shop/tooling cards, More/profile editors and milestone surfaces render via primitives and token roles
• No ad-hoc hex or raw font literals remain on the named surfaces
• Existing accessibility contracts on these surfaces still pass (close buttons, editor labels)
• Visually verify rendered output in browser — provide localhost URL or screenshot for review
• No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation
• Repository test gate passes (npm test)

Files likely touched

• src/ui/ (shop cards, profile editors, milestone surfaces) (edit)
• src/ui/primitives/ (only if a variant/size is genuinely missing) (edit)
• tests/ui/ (edit)

Pre-build verification

• src/ui/primitives/ — available variants (task-252)
• Shop/tooling card components (task-97/100/171 lineage)
• More/profile editor components (task-182/185/194 lineage) and milestone toast (task-236 lineage)
• tests/ui/reusables-primitives.test.tsx — test pattern to extend
• Docs sweep: DESIGN.md, docs/INDEX.md — confirm no prior adoption doc covers these surfaces; if >80% is already migrated, report "already built"

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

Quality-gate priority. Before a sale/gate commits, the player must see its consequences — this is the AD-23 truthful-disclosure mechanism applied to the mid-game sale moment (AD-14).

Effort estimate: S

Scope

• Read docs/design/playability-plan.md rung A3 FIRST — it is the authoritative spec; the doc wins on conflict and deltas go in the build report.
• Implement the §A3 disclosure: before a sale/gate commits, show its consequences (what is given up, what is kept, payout and any multiplier effects) using existing state only.
• Follow the established blocked-action/action-feedback pattern (task-230 precedence rule) and put copy in the existing explanation catalog (task-163 lineage) rather than a new framework.
• Keep lifecycle states consistent with docs/design/project-lifecycle.md (task-154) where the sale gate intersects them.
• Add coverage at the helper boundary and one headless flow assertion.
• Done looks like: a player facing the sale gate can read its consequences before committing, in the same disclosure idiom as every other gated action.

Out of scope

• Do not change sale math, multipliers, or any economy tunable.
• Do not add a modal/tutorial framework; reuse the existing feedback/catalog idiom.
• Do not touch monetization surfaces (owner quality gate).

Acceptance criteria

• Rung A3 implemented per docs/design/playability-plan.md §A3; any delta noted in the build report
• Sale-gate consequences are visible before commitment, derived from existing state
• Disclosure copy lives in the shared catalog/helper, not inline strings scattered in the screen
• Helper-boundary tests plus one headless flow assertion pass
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation
• Repository test gate passes (npm test)

Files likely touched

• src/ui/ (sale/disclosure presentation and the shared helper) (edit)
• src/game/ (gate predicates, if not already exposed) (edit)
• docs/player-manual.md (edit)
• tests/ (edit)

Pre-build verification

• docs/design/playability-plan.md (§A3) — the rung's exact intent; report "already built" if >80% exists
• The pure action-feedback helper from task-230 — the disclosure idiom to extend
• src/game/ sale/exit gating (task-71 exit contract lineage)
• docs/player-manual.md — where disclosure copy may need a manual entry
• Docs sweep: doc_search "sale gate" / "disclosure" before implementing

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

This task gates the ~6 Sep closed-testing start (AD-31). The 14-day clock cannot be recovered once slipped, and tester recruitment is the longest lead item — it must start before any tooling work.

Effort estimate: M

Scope

• This is a coordinated OWNER+BUILDER task per docs/store/eas-pipeline.md (the runbook, task-9) — read it fully before anything else.
• Owner-side (account credentials; the builder cannot do these):
• Decide and record which Expo account owns EAS builds BEFORE running `eas init`.
• `eas login` + `eas init` in the repository.
• On Nova's Play Console account: create the app entry, create the CLOSED testing track (never internal), configure tester list.
• Recruit 12+ opted-in testers (target 15-20 — some will not complete opt-in) from Discord and r/vibecoding; track opt-in status from day one — a tester joining on day 9 does not backdate the counter.
• Builder-side:
• Verify the repo half still matches: eas.json profiles, versionCode derivation, app.json/package.json consistency (task-9 lineage).
• Build and upload the AAB to the closed track via EAS; publish the track.
• Supply the keystore explicitly to `eas build` per the runbook — never let EAS generate one, never commit it.
• Record the exact closed-testing start date in the dated readiness record (task-137 lineage) and note any runbook deltas in docs/store/eas-pipeline.md.
• Done looks like: the closed track is live with a published AAB and 12+ opted-in testers, and the exact start date is recorded.

Out of scope

• No iOS work (AD-30 deferral past this gate).
• No web deploy lane — that is separate (npm run deploy:web) and does not gate this.
• No Layers SDK / growth-experiment work (task-220) and no monetization surfaces.
• Do not change signing-key custody under any circumstances.

Acceptance criteria

• Expo account decision recorded before eas init
• eas init done; eas.json / app.json / versionCode contract verified unchanged
• Play Console CLOSED testing track created on Nova's account (internal track NOT used)
• AAB built and uploaded; track published
• 12+ tester opt-ins recruited and tracked from Discord and r/vibecoding (target above the minimum)
• Exact closed-testing start date recorded in the readiness record
• Keystore supplied explicitly to eas build; never EAS-generated; never committed
• Repository test gate passes (npm test)

Files likely touched

• eas.json (edit)
• app.json (edit)
• package.json (edit)
• docs/store/eas-pipeline.md (edit)
• the private readiness record (path per task-137) (edit)

Pre-build verification

• docs/store/eas-pipeline.md — read fully before running anything
• eas.json — existing profiles
• app.json and package.json — versionCode derivation and eas CLI presence
• The dated readiness record from task-137 (doc_search "release gate" / "readiness") — where the start date is recorded
• Docs sweep: doc_search "closed testing" before starting

Security considerations

Signing-key custody is the hard rule: the keystore stays with Cathal, is supplied explicitly to eas build, is never EAS-generated and never committed. Account credentials stay owner-side and out of the repo. Tester emails are PII — keep them in Play Console, not in repository files.

Handoff

Quality-gate priority. The launch/payout beat must read as timed, productive waiting (AD-40's presentation contract) rather than a label that flips; A2 is the unblocked rung that makes that beat legible.

Effort estimate: S

Scope

• Read docs/design/playability-plan.md rung A2 FIRST — it is the authoritative spec; the doc wins on conflict and deltas go in the build report.
• Implement the launch-receipt clock per §A2: a bounded, continuously updating presentation of the launch beat — progress toward launch and the receipt/payout moment.
• Reuse the established owned pattern from task-266: a PURE ratio/timing helper beside its renderer (src/ui/work-progress.tsx is the seam) — split pure helper from presentation, keep GameScreen presentation-only.
• Honour reduced-motion the same way task-114 did (same event lifetime, opacity-only where applicable).
• Add tests for the pure helper and rendered assertions for the visible state.
• Done looks like: on the relevant surface, a player can see the launch beat advancing and the payout landing without tapping anything.

Out of scope

• No tap-to-speed-up, no finish-now, no skip control (AD-38/AD-35 forbid on this beat).
• No new persisted state where existing tick state suffices.
• No economy tunable moves.

Acceptance criteria

• Rung A2 implemented per docs/design/playability-plan.md §A2; any delta noted in the build report
• The launch beat shows continuous progress and a legible payout/receipt transition on its surface
• Pure helper unit-tested; rendered state asserted
• Reduced-motion behaviour honoured
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation
• Repository test gate passes (npm test)

Files likely touched

• src/ui/work-progress.tsx (or a sibling presentation module following its pattern) (edit)
• src/game/ (only if timing metadata must be exposed) (edit)
• tests/ui/ (edit)

Pre-build verification

• docs/design/playability-plan.md (§A2) — the rung's exact intent; report "already built" if >80% exists
• src/ui/work-progress.tsx — the established progress pattern to extend
• src/game/store.ts — tick/payout timing the helper reads
• src/ui/job-card.ts — typed job-card presentation the clock may sit beside
• Docs sweep: doc_search "launch receipt" / "progress" before implementing

Security considerations

None — no security-relevant changes.

Estimation

Estimated S, landed S — accurate

Handoff

The owner's 30 Aug quality gate directs the unblocked playability ladder first. A7 makes stage naming single-sourced so the visible progression milestone (AD-13) reads consistently and the AD-33 canon label is authoritative everywhere the player looks.

Effort estimate: S

Scope

• Read docs/design/playability-plan.md rung A7 FIRST — it is the authoritative spec. Build to it; if the doc details more or less than this handoff, the doc wins and you note the delta in the build report.
• Establish one authority for player-facing company-stage labels: a single exported label map/helper module (extend the existing shared stage selector from the task-112 lineage rather than adding a parallel one).
• Replace duplicated or ad-hoc stage label literals across src/ui and player-facing docs with the authority. The top stage reads "Software Business" (AD-33).
• Update docs/player-manual.md wherever it names stages so the manual stays the shipped-behavior authority (task-127/192 lineage).
• Add or extend a focused test asserting the label authority and the AD-33 top-stage label.
• Done looks like: every stage the player can see renders the canonical label from one source, verified headlessly.

Out of scope

• Do not change stage ids, thresholds, save schema, or analytics keys (AD-33 keeps those fixed).
• Do not redesign stage visuals or the office background system.
• Do not touch monetization surfaces (owner quality gate).

Acceptance criteria

• Rung A7 implemented per docs/design/playability-plan.md §A7; any delta noted in the build report
• Top player-facing stage label is "Software Business" everywhere it renders (UI and player manual)
• No duplicated stage-label literals remain in src/ui
• Stage ids, save fixtures and analytics keys unchanged
• Scope matches handoff — no unrelated code changed
• Out-of-scope items documented if discovered during implementation
• Repository test gate passes (npm test)