diff --git a/.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md b/.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md new file mode 100644 index 0000000..d63d5fa --- /dev/null +++ b/.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md @@ -0,0 +1,136 @@ +# Phase 1: Reproducible Fidelity Baseline - Context + +**Gathered:** 2026-11-12 +**Status:** Ready for planning + + +## Phase Boundary + +Establish reproducible original/port comparison scenarios, original-file preservation, +a full-game coverage ledger and revision-specific native Linux/Windows baseline +receipts (EVID-01 through EVID-04). Build on existing implementation and evidence. +This phase establishes comparison infrastructure and captures; movement fixes and +broader gameplay admission retain their later phase gates. Unavailable execution +keeps affected acceptance open under the roadmap's source-backed-work exception. + + + +## Implementation Decisions + +### Baseline journeys +- **D-01:** Capture the continuous lab → VR04 → lab → outside journey and focused replays of specific moments, including dialogue return, banked jumps and landing. +- **D-02:** Natural and skipped dialogue are equally required baseline cases. +- **D-03:** Fresh entry and retained departure/return receive separate, equally required runs that preserve their respective lifetimes. +- **D-04:** Include ordinary play and deliberate edge cases: held input through dialogue/return, banked jumps, landing and idle. + +### Comparison review +- **D-05:** Open scenario results with paired original/port playback and links to corresponding images, audio and input/event traces. +- **D-06:** Keep captures unobstructed by default; annotations and image differences are optional overlays. +- **D-07:** Align key events while preserving actual recording speed and elapsed time; expose timing drift rather than concealing it through retiming. +- **D-08:** Switch between original and port audio at corresponding moments, playing one recording at a time. Clearly label any review-only volume adjustment. + +### Evidence navigation +- **D-09:** Browse the full-game ledger by gameplay capability (movement, contacts, gadgets, progression, visuals, audio), with links to scenarios, source evidence and platform receipts. Retain requirement traceability. +- **D-10:** Each capability leads with what works, where it was verified, known differences and remaining acceptance conditions. +- **D-11:** Show current applicable evidence first; retain expandable history with exact revisions and clear superseded labels. +- **D-12:** Order discrepancies by player impact: blocking or visibly disruptive failures first, then subtler differences and missing verification. Missing evidence still leaves its acceptance open regardless of display order. + +### Original and Windows access +- **D-13:** The user has a local Windows PC available to run prepared packages and return results. Availability does not itself establish successful native execution. +- **D-14:** Prepare one local test bundle per checkpoint. A launcher collects source/package/resource identities, logs and captures, with clear user steps and local transfer instructions. Packages and captures remain local. +- **D-15:** Run a separate generated copy of the original on that Windows PC through **DxWnd**. Record DxWnd version/configuration and execution/rendering limitations with each capture. Preserve wrapper provenance separately from native Windows port receipts; do not silently treat wrapper behavior as historical-platform parity. +- **D-16:** Prepare all materials before one combined hands-on session per checkpoint, covering original-reference captures and port checks and collecting results together. + +### Carried-forward constraints +- Preserve every original byte and never execute originals in place; verify against `docs/original-manifest.json`. +- Preserve the implemented TSK-backed first-story input-order correction, fresh direct-scene order and legitimate landing bank. No invented leveling reset or replacement movement tuning. +- Keep source recovery, inference, copied-original component execution, port runtime, Wine, DxWnd reference execution, cross-publish and native platform receipts explicitly distinguished. +- Current Windows and original-reference acceptance remain open until new identified receipts demonstrate the required scenarios. A prepared bundle, wrapper launch or historical result alone cannot close them. +- All builds/tests/captures/packages stay local. Push only verified source/tools/docs to the existing Gitea remote. Preserve current actor/collision admission gates and the lab/outside compatibility solver. + +### Agent discretion +No product decisions were explicitly delegated. Research/planning selects file formats, +local viewer technology, capture tooling, event markers and bundle mechanics within +the decisions above. The discussion does not require an external hosted website. + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Scope and preservation +- `.planning/PROJECT.md` — full reconstruction goal, constraints and existing foundations. +- `.planning/REQUIREMENTS.md` — EVID-01 through EVID-04 and full-game acceptance definitions. +- `.planning/ROADMAP.md` — Phase 1 boundary, access exception and later phase dependencies. +- `AGENTS.md` — current fidelity, source-control, REA and gameplay admission rules. +- `../AGENTS.md` — parent project requirements and evidence preservation. +- `../prompt.MD` — authoritative reconstruction specification; later push authorization supersedes older Git restrictions. +- `docs/original-manifest.json` — original-file identity baseline. + +### Current evidence and protected behavior +- `docs/progress.md` — implementation and revision-specific verification status. +- `docs/compatibility.md` — platform receipts and explicit verification limitations. +- `docs/tasks.md` — existing work and open gates. +- `docs/decisions.md` — durable project decisions. +- `docs/checkpoint/next-work-plan.md` — movement/recovery and route verification sequence. +- `docs/checkpoint/coverage.md` — existing coverage/admission ledger. +- `docs/checkpoint/implementation-plan.md` — reconstruction dependencies and remaining gates. +- `docs/gameplay/main-menu-player-lifetime.md` — implemented TSK-backed startup-order correction. +- `docs/gameplay/jimmy-movement-stabilization.md` — movement baseline and stabilization priority. + +### Reusable infrastructure +- `.planning/codebase/TESTING.md` — local tests, fixtures and runtime evidence boundaries. +- `.planning/codebase/CONVENTIONS.md` — bounded tooling and evidence-reporting conventions. +- `.planning/codebase/STRUCTURE.md` — source, tool and documentation integration locations. +- `docs/rea.md` — original-binary investigation workflow when needed. + +No user-supplied DxWnd configuration document was provided; capture the actual local +version/settings during preparation and execution, without inventing them. + + + +## Existing Code Insights + +### Reusable Assets +- `tools/recon/inventory.py` — hash verification using the recorded manifest. +- `tools/recon/reference_capture.py` — existing copied-original isolated Wine capture and port smoke infrastructure; useful starting evidence/tooling, not proof of Windows/DxWnd support. +- `scripts/test.sh` — consolidated local Python, managed, rendering/audio and original-hash checks. +- `scripts/test-window-transitions.sh` — existing local native window/transition verification. +- `scripts/package.sh`, `scripts/build-linux.sh`, `scripts/build-windows.sh` — existing offline package/build paths and provenance foundations. +- `src/GamePort/Application/CutsceneIdleSmoke.cs`, `src/GamePort/Application/WindowTransitionSmoke.cs` — existing native scenario fixture patterns; reuse suitable behavior instead of claiming component fixtures are gameplay. + +### Established Patterns +- Python standard-library tooling and standalone .NET 10 console regression projects. +- Saved original observations and full-state/event comparisons are distinct from integrated native captures. +- Generated resources, screenshots, traces and packages stay in ignored local output, outside originals and source commits. +- Durable reports identify exact revisions, supporting source evidence and bounded verification scope. + +### Integration Points +- `tools/recon/` for inventory/reference orchestration; `scripts/` for local launch/test/package entry points. +- `src/GamePort/Program.cs` and existing application fixtures expose bounded port capture routes; gameplay algorithms remain protected by current gates. +- Existing `docs/checkpoint/coverage.md` and root status reports provide ledger inputs; reconcile current/superseded receipts rather than assuming report order establishes current proof. +- A local comparison viewer connects scenario captures, optional overlays, timing markers, audio selection and capability-ledger links. Its implementation is a planning choice. + + + +## Specific Ideas + +The user explicitly clarified: “Local testing on my windows machine will have the +original game running via dxwnd”. Use that setup for the planned Windows original +reference sessions. Compare original and port without simultaneous mixed audio or +hidden timing correction. Prepare a complete, reviewable local checkpoint bundle +before requesting hands-on execution. + + + +## Deferred Ideas + +None — discussion stayed within phase scope. Native execution and capture are +future execution tasks, not results established by this discussion. + + +--- + +*Phase: 01-reproducible-fidelity-baseline* +*Context gathered: 2026-11-12* diff --git a/.planning/phases/01-reproducible-fidelity-baseline/01-DISCUSSION-LOG.md b/.planning/phases/01-reproducible-fidelity-baseline/01-DISCUSSION-LOG.md new file mode 100644 index 0000000..6f47662 --- /dev/null +++ b/.planning/phases/01-reproducible-fidelity-baseline/01-DISCUSSION-LOG.md @@ -0,0 +1,231 @@ +# Phase 1: Reproducible Fidelity Baseline - Discussion Log + +> **Audit trail only.** Planning, research and execution consume CONTEXT.md, not this log. + +**Date:** 2026-11-12 +**Phase:** 01-reproducible-fidelity-baseline +**Areas discussed:** Baseline journeys, Comparison review, Evidence navigation, Original and Windows access + +The user selected all four areas. Discussion used individual numbered text questions. +Each area was completed explicitly, and the user selected “Ready for context” after the final summary. + +## Baseline journeys + +### For lab → VR04 → lab → outside, how should comparison runs be organized? + +| Option | +|--------| +| Full route plus focused replays (Recommended) | +| Full route first | +| Focused replays first | + +**User’s choice / clarification:** Full route plus focused replays: capture the continuous journey, then replay specific moments such as dialogue return, banked jumps and landing. + +### How should natural and skipped dialogue appear in the baseline? + +| Option | +|--------| +| Both as equal cases (Recommended) | +| Natural dialogue first | +| Skipped dialogue first | + +**User’s choice / clarification:** Both as equal cases: run the route with dialogue completing naturally and with dialogue skipped. + +### How should fresh entry and retained return be covered? + +| Option | +|--------| +| Separate, equally required runs (Recommended) | +| Continuous journey first | +| Fresh start first | + +**User’s choice / clarification:** Separate, equally required runs: capture a clean start and a continuous departure/return journey, preserving each lifetime. + +### How should player inputs be chosen for the focused replays? + +| Option | +|--------| +| Normal play plus deliberate edge cases (Recommended) | +| Normal play first | +| Repeat your reported sequences first | + +**User’s choice / clarification:** Normal play plus deliberate edge cases: include ordinary movement alongside held input through dialogue/return, banked jumps, landing and idle. + +### More on baseline journeys, or next area? + +| Option | +|--------| +| Next area | +| More on baseline journeys | + +**User’s choice / clarification:** Next area: Comparison review. + +## Comparison review + +### What should appear first when opening scenario results? + +| Option | +|--------| +| Paired playback with marked differences (Recommended) | +| Written findings first | +| Chronological capture timeline | + +**User’s choice / clarification:** Paired playback with marked differences: original and port shown together, with links to matching images, audio and input/event traces. + +### How should differences be highlighted? + +| Option | +|--------| +| Clean playback with optional overlays (Recommended) | +| Annotations always visible | +| Clean playback with notes alongside | + +**User’s choice / clarification:** Clean playback with optional overlays: both captures remain unobstructed by default; annotations and image differences can be toggled for inspection. + +### How should original and port playback line up when timing differs? + +| Option | +|--------| +| Align key events and show timing drift (Recommended) | +| Start together and run continuously | +| Step through matching events | + +**User’s choice / clarification:** Align key events and show timing drift, preserving actual recording speed and elapsed time. + +### How should audio be reviewed? + +| Option | +|--------| +| Switch between original and port (Recommended) | +| Original then port excerpts | +| Separate audio review | + +**User’s choice / clarification:** Switch between original and port at corresponding moments, hearing one recording at a time; review-only volume adjustments must be clearly labeled. + +### More on comparison review, or next area? + +| Option | +|--------| +| Next area | +| More on comparison review | + +**User’s choice / clarification:** Next area: Evidence navigation. + +## Evidence navigation + +### What should be the main entry point into the full-game evidence ledger? + +| Option | +|--------| +| Gameplay capabilities (Recommended) | +| Playable journeys | +| Requirements | + +**User’s choice / clarification:** Gameplay capabilities: browse movement, contacts, gadgets, progression, visuals and audio; each leads to scenarios, source evidence and platform receipts. + +### What should each capability show before detailed evidence? + +| Option | +|--------| +| Current state and remaining gap (Recommended) | +| Latest comparison result | +| Evidence summary | + +**User’s choice / clarification:** Current state and remaining gap: what works, where it was verified, known differences and remaining acceptance conditions. + +### How should earlier evidence appear when newer work supersedes it? + +| Option | +|--------| +| Current evidence first, history expandable (Recommended) | +| Full history alongside current evidence | +| Separate history index | + +**User’s choice / clarification:** Current evidence first, history expandable; retain older results with clear revision and superseded labels. + +### How should open discrepancies be ordered within a capability? + +| Option | +|--------| +| Player impact first (Recommended) | +| Route order | +| Newest findings first | + +**User’s choice / clarification:** Player impact first: failures blocking or visibly disrupting play precede subtler differences and missing verification. + +### More on evidence navigation, or next area? + +| Option | +|--------| +| Next area | +| More on evidence navigation | + +**User’s choice / clarification:** Next area: Original and Windows access. + +## Original and Windows access + +### What Windows environment is available for this phase? + +| Option | +|--------| +| A local Windows PC | +| A local Windows VM | +| None currently | + +**User’s choice / clarification:** A local Windows PC; the user can run a prepared test package and return results. + +### How should Windows checks be run? + +| Option | +|--------| +| One local test bundle per checkpoint (Recommended) | +| Guided sessions | +| Written checklist | + +**User’s choice / clarification:** One local test bundle per checkpoint, with a launcher collecting revision details, logs and captures; packages and captures remain local and transfer uses a local method. + +### Can the Windows PC also run a separate generated copy of the original? + +| Option | +|--------| +| Yes, try it on that PC (Recommended) | +| Use Linux/Wine for original captures | +| Original-game execution is unavailable for now | + +**User’s choice / clarification:** Yes, try it on that PC, using a separate generated copy and recording execution/rendering limitations. + +### How should hands-on capture sessions be scheduled? + +| Option | +|--------| +| Prepare everything, then one combined session per checkpoint (Recommended) | +| Original captures first, port checks later | +| Short sessions as needed | + +**User’s choice / clarification:** Prepare everything, then one combined session per checkpoint, bundling original-reference captures and port checks with clear steps and collecting results together. + +### Finish execution access or discuss further? + +| Option | +|--------| +| Finish this area | +| More on execution access | + +**User’s choice / clarification:** User clarification: Local testing on my windows machine will have the original game running via dxwnd. + +### Finish this area or discuss the DxWnd setup further? + +| Option | +|--------| +| Finish this area | +| Discuss the DxWnd setup further | + +**User’s choice / clarification:** Finish this area. Original reference execution uses DxWnd; record its version/configuration with captures and distinguish wrapper effects from native Windows port checks. + +## Agent discretion + +No explicit product-choice delegation. Implementation mechanics remain for research/planning within the captured decisions. + +## Deferred Ideas + +None. diff --git a/docs/compatibility.md b/docs/compatibility.md index ae919fd..e680bbf 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -1,5 +1,14 @@ # Compatibility and validation +## Planned Phase 1 capture setup — 2026-11-12 + +The user has a local Windows PC for combined reference/port checkpoint sessions. +Original-game reference execution is planned through DxWnd on a generated copy; +record Windows, DxWnd version/settings and capture limitations. Native Windows +port results remain distinct. This is setup availability and a discussion decision, +not a new launch, capture, original-comparison or native Windows verification +receipt. Existing verification claims and open acceptance dependencies remain. + 2026-11-07 normal-callback checkpoint:30 complete emitted original/C# fixture snapshots match exact float32 values, raw angle arguments/results and getter order. The inherited ceiling/reflection/angular component remains outside live diff --git a/docs/decisions.md b/docs/decisions.md index f31892d..4ce00e5 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1,5 +1,17 @@ # Decisions +## Phase 1 comparison decisions — 2026-11-12 + +Use full lab → VR04 → lab → outside journeys plus focused normal/edge-input +replays, with equal natural/skipped dialogue and separate fresh/retained coverage. +Review original/port playback together with optional overlays, actual timing drift +and switchable audio. Browse evidence by capability with current gaps first and +expandable revision history; order discrepancies by player impact. Prepare one +local bundle and combined Windows session per checkpoint. The original runs from +a generated copy through DxWnd, with version/settings recorded; port-native +receipts remain separate. Full decisions are in +`../.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md`. + ## Full reconstruction planning — 2026-11-12 The user scoped GSD planning to the remaining full reconstruction and explicitly diff --git a/docs/progress.md b/docs/progress.md index 3de297e..0a422d8 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -1,5 +1,14 @@ # Progress — 2026-11-07 +## Phase 1 discussion complete — 2026-11-12 + +Phase 1 context and the discussion audit are captured in +`../.planning/phases/01-reproducible-fidelity-baseline/`. Decisions cover full-route +and focused comparisons, paired playback, a capability-led evidence ledger and +combined local Windows sessions. The original will run through DxWnd on the +user’s Windows PC; record wrapper configuration separately from port receipts. +Next: `$gsd-plan-phase 1`. No new runtime or platform verification is established. + ## Planning initialization — 2026-11-12 GSD onboarding and full-reconstruction planning are initialized in diff --git a/docs/tasks.md b/docs/tasks.md index 89beafe..e50283e 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -4,7 +4,9 @@ - [x] Initialize full remaining reconstruction scope, research,33 requirements and8 playable-slice phases in `../.planning/`. -- [ ] Discuss/plan phase1: Reproducible Fidelity Baseline. Keep original/native +- [x] Discuss phase1: Reproducible Fidelity Baseline; capture all four areas and + the Windows/DxWnd setup in `../.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md`. +- [ ] Plan phase1 (`$gsd-plan-phase 1`). Keep original/native Windows access dependencies open; independent source-backed recovery may continue under the explicit roadmap exception. - [ ] Execute the roadmap with current evidence/admission gates; initialization