docs(01): capture phase 1 context
User locked four implementation decisions: - AI asset pipeline: minimum-viable schema + sidecar provenance + CI gate; vendor/model deferred to Phase 5; 10–20 hand-curated AI generations as Phase 1 north-stars - Save v1: minimal payload (Phase 2 fields only); synthetic v0→v1 migration proves the chain works; first real migration ships in Phase 4 - Doctrine docs: anti-FOMO consolidation + Season 7 principle-level rest-state contract; both in .planning/; no CI/lint enforcement - Phase 1 scaffold caps at the 5 success criteria — BigQty, Zustand store, and tick scheduler defer to Phase 2 Pushback recorded: user prefers minimum-viable infrastructure for support systems; no ceremonial workflows.
This commit is contained in:
@@ -0,0 +1,115 @@
|
||||
# Phase 1: Foundations & Doctrine - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-05-08
|
||||
**Phase:** 1-foundations-and-doctrine
|
||||
**Areas discussed:** AI asset pipeline depth, Save schema v1 scope, Doctrine docs concreteness, Project scaffold layout
|
||||
|
||||
---
|
||||
|
||||
## AI Asset Pipeline Depth
|
||||
|
||||
### Sub-question A: north-star reference set state at end of Phase 1
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Hand-painted by a real artist | Commission a watercolor artist (or paint them yourself) to produce 10–20 hand-painted reference images now. AI pipeline (vendor TBD in Phase 5) later trains/conditions against them. Highest fidelity, real budget commitment. | |
|
||||
| Hand-curated AI generations | Generate dozens of candidates in a chosen tool, hand-pick 10–20 that nail the watercolor target, commit them with full provenance. | ✓ |
|
||||
| Placeholder refs + sealed slot | Phase 1 ships schema + gate + a marked 'north-star slot' with placeholders; real north-stars commissioned in early Phase 5. | |
|
||||
| Public-domain watercolor refs | Curate 10–20 from public-domain or Creative Commons watercolor art. Zero budget; provenance is licensing, not generation. | |
|
||||
|
||||
**User's choice:** Hand-curated AI generations.
|
||||
|
||||
### Sub-question B: which generation tool for the Phase 1 north-stars
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Local Stable Diffusion + watercolor LoRA | Local SD via ComfyUI/Automatic1111 with a watercolor-specialized LoRA. Full provenance natively (model checksum, exact sampler, seed, full params). | |
|
||||
| Scenario (game-art-focused) | Purpose-built generative platform with custom-trained generators. Subscription-based ($29–$199/mo). Designed for reproducibility, style consistency. | |
|
||||
| Midjourney with licensed plan | Best-in-class watercolor output, lowest skill floor. Provenance is messier (no checkpoint hash exposed). | |
|
||||
| Defer tool choice, lock the discipline | Phase 1 commits to schema + gate; the model_id/checkpoint_hash fields are filled honestly per generation. Tool consolidation in Phase 5. | ✓ |
|
||||
|
||||
**User's choice:** Defer tool choice, lock the discipline.
|
||||
|
||||
### Sub-question C: how the curation gate refuses unreviewed assets
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Sidecar JSON + CI validator | Each asset requires a sibling `name.provenance.json` carrying all 6 provenance fields plus reviewed:true and reviewedBy. CI walks the tree, fails build on any missing/invalid sidecar. | (locked at minimum-viable level after pushback) |
|
||||
| Curated-pending two-stage | Generated assets land in `/assets-pending/`; curator script promotes to `/assets/` while writing a CURATION-LOG.md entry. | |
|
||||
| Manifest-as-source-of-truth | Single `/assets/manifest.json` lists every shipped asset with full provenance + reviewer. | |
|
||||
| Pre-commit hook + manifest | Combines manifest with a Git pre-commit hook that refuses to add files under `/assets/` without manifest entries. | |
|
||||
|
||||
**User's choice:** *(rejected the framing)* "We are vastly overcomplicating this. When I said I wanted AI generated assets I figured that would be just something Claude could spit out. It isn't overly important and I don't really care all this much."
|
||||
|
||||
**Notes:** Locked the *minimum viable* shape from option 1 (sidecar + CI validator) without the `reviewed` ceremony — just the 6 provenance fields + a sample refused asset proving the gate works. No curator workflow, no two-stage, no pre-commit hook, no CURATION-LOG.md. Saved a feedback memory ("avoid overengineering foundations") to recalibrate the rest of the discussion.
|
||||
|
||||
---
|
||||
|
||||
## Save Schema v1 Scope
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Minimal: just what Phase 2 needs | v1 carries only Season 1 fields. Real v1→v2 migration in Phase 4. Honest minimum, exercises the migration framework on real player data. | ✓ |
|
||||
| Structural: full 7-Season shape with empty defaults | v1 already has slots for Roothold, currentSeason, storyFlags, knownFragments, all defaulting to zero/null. Less migration churn, but designing for code that doesn't exist yet. | |
|
||||
| Hybrid: Phase 2 fields + a `_extensions` bucket | Typed `_extensions: Record<string, unknown>` for forward writes. Pragmatic but invites schema drift. | |
|
||||
|
||||
**User's choice:** Minimal: just what Phase 2 needs.
|
||||
|
||||
**Notes:** Round-trip migration test in Phase 1 will use a synthetic v0 → v1 demo migration to prove the chain works end-to-end. First real migration ships in Phase 4.
|
||||
|
||||
---
|
||||
|
||||
## Doctrine Docs Concreteness
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Principle-level: the rest-state contract | Doc answers what 'rest state' means, what the finite Roothold ceiling is tied to, what tonal register the coda lives in. No final scene text. | ✓ |
|
||||
| Treatment-level: with the binary-choice scene | Principle-level + actual final scene treatment: binary-choice prompt text, both ending paragraphs, Lura's final line, credits/coda screen. Eliminates 7 phases of drift risk at the cost of authoring the climax in Phase 1. | |
|
||||
| Principle + 'do not violate' list | Principle-level plus an explicit list of patterns Phase 2–7 must NOT introduce. Cheaper than full treatment but still gives later phases a hard wall. | |
|
||||
|
||||
**User's choice:** Principle-level: the rest-state contract.
|
||||
|
||||
**Notes:** Anti-FOMO doctrine was not put to choice — it's a consolidation of constraints already scattered across PROJECT.md / REQUIREMENTS.md / CLAUDE.md / SUMMARY.md banner concerns; Claude can write that without further input. Both doctrine docs land in `.planning/`. No CI/lint enforcement — doctrine is referenced at design reviews, not enforced by code.
|
||||
|
||||
---
|
||||
|
||||
## Project Scaffold Layout
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| BigQty wrapper around break_eternity.js | Build the typed wrapper in Phase 1 so Phase 2 starts using it immediately. | |
|
||||
| Empty Zustand store skeleton | A `src/store/` with the bridge pattern stubbed (selectors, no state). | |
|
||||
| Tick scheduler / monotonic clock | The pure simulation tick loop with monotonic-only time injection. Phase 2's CORE-11 anchors on this. | |
|
||||
| None — stop at success criteria | Phase 1 ships exactly what the 5 success criteria demand and nothing more. Phase 2 builds BigQty, the store, the tick loop as its first tasks. | ✓ |
|
||||
|
||||
**User's choice:** None — stop at success criteria.
|
||||
|
||||
**Notes:** Cleanest scope — Phase 1 stays honest as "land retrofit-hostile decisions only." Phase 2 owns BigQty, Zustand store contents, tick scheduler. The boundary directories (`src/sim/`, `src/render/`, `src/ui/`) still need to exist in Phase 1 so the ESLint boundary rule has clean targets to enforce.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- ESLint boundary plugin choice (`eslint-plugin-boundaries` vs `eslint-plugin-import`'s `no-restricted-paths`).
|
||||
- Save checksum algorithm (CRC32, simple hash, SHA-1) — any deterministic, fast hash.
|
||||
- Migration registry shape (chain of named functions, registry object).
|
||||
- `idb` wrapper API surface inside `src/save/`.
|
||||
- Vitest + Playwright config.
|
||||
- Where Zod content schemas live and how the build step is invoked (Vite plugin vs separate npm script).
|
||||
- Specific images / prompts / seeds for the 10–20 north-star generations (user accepts/rejects).
|
||||
|
||||
---
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- AI vendor lock-in / model pinning → early Phase 5.
|
||||
- `BigQty` wrapper around break_eternity.js → Phase 2 first task.
|
||||
- Empty Zustand store skeleton → Phase 2.
|
||||
- Tick scheduler / monotonic clock → Phase 2 (CORE-11).
|
||||
- Season 7 treatment-level details (binary-choice scene text, Lura's final line, coda screen) → Phase 7.
|
||||
- Anti-FOMO lint rule on UX strings → explicitly rejected.
|
||||
- Curator workflow / two-stage asset promotion / pre-commit hook on assets → explicitly rejected.
|
||||
- Visual regression testing across asset library → PIPE-04, Phase 8.
|
||||
Reference in New Issue
Block a user