# SOP — WaterStorage / Watershed Cross-Platform Build

**Version:** 0.1  
**Date:** 2026-07-17  
**Canonical project:** `WaterStorage`  
**Public package:** `waterstorage-cross-platform`

## 1. Purpose

Build CookieBlob and Game Crafter versions of WaterStorage at the same time while preserving one rules engine: the watershed phase loop, shared state, action meanings, overflow behavior, collapse condition, and successful return.

The browser version is the persistent room. The physical version is the playable tabletop object. Neither is a disposable mockup of the other.

## 2. Source-of-truth order

When documents disagree, use this order:

1. the current user instruction;
2. `WaterStorage/framework.md`;
3. this SOP;
4. `parity-matrix.md`;
5. target-specific README and implementation notes;
6. experiments and playtest notes.

A target-specific improvement may change presentation, wording, or ergonomics. It may not change shared semantics without a version bump.

## 3. Directory contract

- `WaterStorage/` remains the canonical working project;
- `WaterStorage/watershed-cross-platform-public/` is the clean publish directory;
- `cookieblob/` contains browser-room files and WordPress embedding notes;
- `game-crafter/` contains physical component files and playtest notes;
- `parity-matrix.md` defines the shared state machine;
- `CHANGELOG.md` records public-package changes.

Do not place scratch files, generated archives, credentials, or unrelated project material in the public directory.

## 4. Build loop

### Step 1 — Select one shared slice

Work on one watershed phase, action, or transition at a time. State the intended state change before implementing either interface.

### Step 2 — Update parity first

Add or revise the rule in `parity-matrix.md`. Include preconditions, state deltas, display wording, and failure behavior.

### Step 3 — Implement CookieBlob

Use the CookieBlob techniques already established in `tenchimedia-cookieblob`:

- namespaced localStorage;
- load → render → act → save → render;
- revisiting improves or preserves state rather than silently resetting it;
- explicit reset / new cycle control;
- self-contained HTML, CSS, and JavaScript suitable for WordPress passthrough;
- no dependency on script-tag JSON that WordPress may strip;
- readable state and trace output for debugging.

### Step 4 — Implement Game Crafter

Translate the same slice into physical components:

- card text and iconography;
- token movement;
- board-zone destination;
- player-facing success / failure cue;
- setup and reset instructions.

A physical component must have a browser equivalent in the parity matrix.

### Step 5 — Run paired tests

For each test sequence:

1. record the starting state;
2. perform the same semantic actions in CookieBlob and Game Crafter;
3. record the ending state;
4. compare every shared field;
5. record presentation differences separately from rule differences.

Minimum first test: one complete W01–W10 cycle, including one stored unit, one infiltration action, one filter action, one pressure increase, one pressure reduction, and a successful return.

### Step 6 — Package

Update the changelog, confirm the public directory contains only intended files, and sync the directory to zo.pub.

## 5. CookieBlob acceptance tests

- A fresh visitor sees the initial Watershed state.
- Reloading the room preserves the saved state.
- An action changes exactly the fields defined by the parity matrix.
- Invalid phase actions are unavailable or rejected without mutation.
- Reset requires an explicit user action.
- Overflow and collapse are visible and reproducible.
- A completed trace can be inspected or copied.
- Two browser tabs do not silently destroy a saved run; last-write behavior must be documented if simultaneous editing cannot be prevented.
- The room works when embedded through the WordPress-safe passthrough pattern.

## 6. Game Crafter acceptance tests

- A new player can set up the game from the included instructions.
- All shared state fields have physical representations or are clearly tracked on the mat.
- Card effects match `parity-matrix.md`.
- The first complete cycle can be played without hidden bookkeeping.
- Overflow, collapse, and successful return have unambiguous physical procedures.
- Resetting the game does not require destroying the trace card.
- Components are labeled for prototype printing and revision.

## 7. Versioning

Use `v0.x` while the state machine is under playtest. Increment the patch number for wording, layout, or component changes that preserve semantics. Increment the minor version when adding a phase, state field, action, or transition. Record the reason in `CHANGELOG.md` and update both targets together.

## 8. Review questions

At every paired review, ask:

1. What does the water do next?
2. What does the player do next?
3. What persists after leaving and returning?
4. What is the smallest useful trace of this cycle?
5. Can the physical and browser versions explain the same result in different but compatible languages?

## 9. Initial status

The shared package is scaffolded. The next implementation slice is **W01 Ocean → W02 Evaporation**, followed by the first paired test and a minimal CookieBlob room shell plus ten Game Crafter phase cards.