docs(01): capture phase context

This commit is contained in:
UnixNight committed 2026-11-12 12:11:35 -05:00
1 parent 9aa49970e4
commit 661e7c3299
6 files changed
+400 -1

No files matched your search

@@ -0,0 +1,136 @@
# Phase 1: Reproducible Fidelity Baseline - Context
**Gathered:** 2026-11-12
**Status:** Ready for planning
<domain>
## 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.
</domain>
<decisions>
## 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.
</decisions>
<canonical_refs>
## 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.
</canonical_refs>
<code_context>
## 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.
</code_context>
<specifics>
## 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.
</specifics>
<deferred>
## Deferred Ideas
None — discussion stayed within phase scope. Native execution and capture are
future execution tasks, not results established by this discussion.
</deferred>
---
*Phase: 01-reproducible-fidelity-baseline*
*Context gathered: 2026-11-12*
@@ -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.
+9
View File
@@ -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
+12
View File
@@ -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
+9
View File
@@ -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
+3 -1
View File
@@ -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