From 77a157bfcdbc754565163ebe740671da203ccbbf Mon Sep 17 00:00:00 2001 From: ksdisch Date: Sun, 26 Jul 2026 16:30:28 -0500 Subject: [PATCH] docs: initialize project wiki (PROJECT, HANDOFF, Sources, Decisions) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wiki initialized via the project-wiki skill (INIT mode): - PROJECT.md — purpose, scope, status, next actions, boundaries - HANDOFF.md — resume point: post-M13 state, playtest is the next move - Sources.md — authoritative-source index (README/CLAUDE/BACKLOG/audit/runbooks) - Decisions.md — audit decisions D1-D8 with approved/unresolved status - CLAUDE.md — appended the Project Wiki maintenance section Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 13 +++++++++++++ Decisions.md | 12 ++++++++++++ HANDOFF.md | 24 ++++++++++++++++++++++++ PROJECT.md | 27 +++++++++++++++++++++++++++ Sources.md | 14 ++++++++++++++ 5 files changed, 90 insertions(+) create mode 100644 Decisions.md create mode 100644 HANDOFF.md create mode 100644 PROJECT.md create mode 100644 Sources.md diff --git a/CLAUDE.md b/CLAUDE.md index 19786b9..5284b84 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -142,3 +142,16 @@ To vendor more of your global commands/skills or brainstorm new repo-specific au ## Operating Constraints @.claude/operating-constraints.md + +## Project Wiki + +This project uses the project-wiki skill. When integrating new sources, recording decisions, or pausing work: +- Update `PROJECT.md` status and next actions +- Update `HANDOFF.md` with what changed and what's next +- Add durable understanding to `Wiki/` topic pages +- Record decisions in `Decisions.md` +- Keep `Wiki/_index.md` current + +(`Wiki/`, `Decisions.md`, and `Sources.md` are created on first need — templates live in the skill.) + +Invoke the `project-wiki` skill when wiki updates are needed. diff --git a/Decisions.md b/Decisions.md new file mode 100644 index 0000000..0153f85 --- /dev/null +++ b/Decisions.md @@ -0,0 +1,12 @@ +# Decisions + +| ID | Decision | Status | Date | Source/Rationale | +|----|----------|--------|------|-----------------| +| D1 | Add a minimal CI workflow (npm ci → typecheck → typecheck:tests → vitest → build → smoke:relay) and amend session-start's no-CI rule to "don't extend beyond this" | Approved | 2026-07-11 | Audit decision #1 (F-32); landed in Phase 4, PR #30 | +| D2 | Adopt Prettier (config-only, no plugins) | Unresolved | 2026-07-09 | Audit decision #2 — pure consistency; strict tsc already covers correctness | +| D3 | Jump feel: keep hold-to-bunny-hop (`isDown`) or switch to `JustDown` | Unresolved | 2026-07-09 | Audit decision #3 (F-43) — pure game-feel call, flagged for Kyle | +| D4 | Cap `solveMs` at the puzzle's effective talent-tuned timer (vs wall-clock) when the phone backgrounds mid-puzzle | Approved | 2026-07-11 | Audit decision #4 (F-50); landed in Phase 5, PR #31, via the `PUZZLE_TIMER_SECONDS` map | +| D5 | PROJECT_GUIDE.md: banner-only interim landed (Phase 3, PR #29); full regenerate (~L effort) still undecided | Unresolved | 2026-07-11 | Audit decision #5 — BACKLOG lists the regen as an open decision | +| D6 | Docker slim approach: move `tsx` to deps (simple) vs esbuild-bundle (smallest) | Unresolved | 2026-07-09 | Audit decision #6 (F-60); only matters at deploy time — decide with Phase 6 | +| D7 | Stack locked to Phaser 3, React 19, `ws`, Vite, tsx, TypeScript — new dependencies are a real decision, not routine | Approved | pre-2026-07 | CLAUDE.md "Do / don't"; reaffirmed by the audit's "no new dependencies" stance | +| D8 | Audit Phase 6 (deploy hardening: F-34, F-37, F-38b, F-39, F-60, F-61) rides the actual public deploy rather than landing standalone | Approved | 2026-07-11 | BACKLOG deploy item note + PR #32; the phase's gate needs the deploy context anyway | diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..760f5e9 --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,24 @@ +# HANDOFF.md + +_Last updated: 2026-07-26_ + +## What was just done +- 2026-07-26: Project wiki initialized (PROJECT.md, HANDOFF.md, Sources.md, Decisions.md) via the project-wiki skill. +- 2026-07-17: Vendored global Claude Code commands/skills/hooks into the repo via `/claudify-repo` (PR #33) — CLAUDE.md gained the tooling reference section. +- 2026-07-11: M13 hardening completed — audit Phases 0–5 all landed (PRs #26–#31); the BACKLOG hardening item was marked Done with Phase 6 explicitly deferred to the deploy (PR #32). + +## Where things stand +The game is playable end-to-end (hub + three planets + four powers + talents + rhythm portrait + procedural audio/mute) and freshly hardened: the 2026-07-09 audit's Phases 0–5 closed the relay crash vectors, disconnect blindness, the invisible-particles and freeze-truncation bugs, the doc drift, the test-spine gaps (CI now runs on every PR), and the phone hygiene findings — with StrictMode on and 204 Vitest green. Nothing is in flight. The two remaining BACKLOG items are both gated on Kyle rather than code: the never-run fun-gate playtest and the account-bound public deploy (which carries audit Phase 6 with it). + +## Immediate next move +Run the fun-gate playtest (one full co-op session with the partner). It has never run in the project's life, the whole asymmetric premise lives or dies on it, and the audit's Phase 2 specifically fixed the feel bugs that made running it earlier pointless. + +## Open questions / blockers +- Audit decisions still open (see Decisions.md): Prettier adoption (D2), jump feel `isDown` vs `JustDown` (D3), PROJECT_GUIDE.md full regen vs the landed banner-only (D5), Docker slim approach (D6 — only matters at deploy). +- Playtest is human-gated (partner availability); deploy is account-gated (Fly + itch.io credentials). + +## Files touched recently +- `CLAUDE.md` — tooling reference section vendored in PR #33 (last substantive change in the repo) +- `BACKLOG.md` — hardening item moved to Done with full phase-by-phase record (PRs #31–#32) +- `src/phone/**` — audit Phase 5 hygiene (StrictMode, solvedRef guards, palette/touch-target/aria fixes, `solveMs` cap) +- `.github/workflows/` — minimal CI gate added in audit Phase 4 (decision D1) diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..bc77515 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,27 @@ +# PROJECT.md + +## Purpose +Constellation is an asymmetric cozy co-op game for two: one player platforms through tiny planet worlds on the laptop (Phaser), the other solves quick puzzles on their phone (React) to cast tactical powers that reshape the world — glued together by a small `ws` relay. + +## Scope +**In scope (current phase — post-M13 tail):** +- The two open BACKLOG items: (1) the fun-gate playtest with the real audience, (2) the credentialed public deploy (relay → Fly, clients → itch.io), with audit Phase 6 (deploy hardening) deliberately riding the deploy. + +**Out / deferred:** +- Procedural planet generation (the M10 rhythm-portrait wedge landed telemetry-first; generation waits until the portrait proves itself — see `docs/ideas/planet-that-knows-you-two.md`) +- Role specialization exploration (`docs/ideas/specialization.md`) +- New dependencies (stack is locked), relay rewrite, power-architecture rework, code-splitting, major-version upgrades (all explicitly left alone by the 2026-07-09 audit plan) + +## Current status +**Active** (nothing in flight). Playable end-to-end: galaxy hub, three planets, four powers, talent constellation, rhythm portrait, procedural audio + master mute. M11 shipped; M13 hardening (audit Phases 0–5) landed 2026-07-11; audit Phase 6 waits for the deploy. Last commit 2026-07-17 (vendored Claude Code tooling, PR #33). + +## Next actions +1. Run the fun-gate playtest (BACKLOG Open) — one full co-op session: handshake → hub → planets 1–3 with real phone casts → spend stardust → read the portrait. Phase 2 of the audit fixed the feel bugs, so this is finally worth running. Human-gated (needs the partner). +2. Credentialed deploy (BACKLOG Open) — `fly deploy` the relay, build clients with `VITE_RELAY_URL`, upload `dist/` to itch.io, doing audit Phase 6 alongside. Account-gated (needs Kyle's Fly + itch.io accounts). Walkthrough: `docs/DEPLOY.md`. + +## Boundaries +- **Stack locked:** Phaser 3, React 19, `ws`, Vite, tsx, TypeScript (strict). Adding anything else is a real decision. +- **Strict boundaries:** `src/shared/` holds only `protocol.ts` (wire types); the relay is an allowlist forwarder with zero game logic; protocol changes must land in both clients in the same commit. +- **Phone UI:** inline styles only, fixed palette, ≥44px touch targets. +- **Testing:** Vitest for pure framework-free logic only; the human playtest remains the integration gate for game feel; the `?test=1` bridge covers headless gameplay verification (`docs/AUTONOMY.md`). +- **Account/human gates:** deploy needs Kyle's Fly + itch.io accounts; the playtest needs his partner. diff --git a/Sources.md b/Sources.md new file mode 100644 index 0000000..6294aac --- /dev/null +++ b/Sources.md @@ -0,0 +1,14 @@ +# Sources + +| Source | Location | Type | Authoritative for | +|--------|----------|------|-------------------| +| README | `README.md` | overview | What ships today: powers, planets, run/deploy instructions, stack layout | +| CLAUDE.md | `CLAUDE.md` | conventions | File layout, commands, coding conventions, contracts (power/planet/protocol), gotchas, repo tooling | +| Backlog | `BACKLOG.md` | log / plan | Open work, in-flight state, and the full per-milestone Done history with verification notes | +| 2026-07-09 audit & fix plan | `docs/AUDIT-2026-07-09.md` | audit | Findings F-01…F-61, the phased fix plan, and the six numbered decisions | +| Deploy guide | `docs/DEPLOY.md` | runbook | Relay → Fly, clients → itch.io, env wiring, end-to-end checks | +| Autonomy playbook | `docs/AUTONOMY.md` | runbook | The `?test=1` headless bridge driver and verification playbook | +| Project guide | `PROJECT_GUIDE.md` | historical snapshot | Point-in-time deep dive — carries a banner; do NOT treat as current (audit F-27) | +| Idea docs | `docs/ideas/` | vision briefs | Deferred explorations: planet-that-knows-you-two, specialization | +| Milestone plans | `docs/plans/`, `docs/m5–m9-*.md`, `.claude/notes/` | plans | Per-milestone design intent (M5–M10); superseded by BACKLOG Done notes once landed | +| Orchestrator docs | `.claude/orchestrator.md`, `.claude/agents/` | workflow | Invariants, gates, and role prompts for the orchestrator-worker build workflow |