docs(01): create verified fidelity baseline plans

This commit is contained in:
UnixNight committed 2026-11-12 17:38:34 -05:00
1 parent 36f24e4474
commit cf64b8ce18
21 files changed
+1473 -32

No files matched your search

@@ -0,0 +1,62 @@
# Evidence Walking Skeleton — Neutron GamePort
Phase 01 · Planned 2026-11-12 · No implementation or new runtime proof implied.
**As a** tester, **I want to** reproduce identified original and port comparison scenarios and inspect their evidence, **so that** I can understand exactly what the current reconstruction proves on each native platform.
This roadmap-derived story framing was supplied by the orchestrator. This is an established native game; its Phase 1 skeleton is the local evidence workflow, without unrelated database, account, routing or deployment scaffolding.
## Capability to prove end to end
Verify authoritative inventory → stage a generated copy → identify actual port bytes → collect/import one honestly classified receipt → inspect local review output. Actual original/native acceptance remains dependent on identified runtime captures and human review.
## Architectural contract
| Decision | Choice | Reason |
|---|---|---|
| Game runtime | Existing .NET 10, SDL3, Silk.NET.Vulkan/Vulkan 1.3+ | Preserve gameplay and current platform design |
| Evidence orchestration | Python stdlib CLI modules under tools/recon | Existing bounded local-tool patterns; no new packages |
| Persistence | Versioned JSON metadata and immutable local hashed artifacts | Actual disk read/write replaces an unrelated database requirement |
| Viewer | Plain HTML/CSS/native media plus testable ES module | Paired recordings, real time, exclusive audio |
| Local access | Contained read-only loopback viewer with GET/HEAD ranges | Browser seeking without hosted services or original-directory exposure |
| Native launch | Local shell / package-free PowerShell and cmd | User Windows PC does not need Python or SDK |
| Auth | No accounts; filesystem containment | A local evidence workflow, not a multi-user service |
| Original reference | Generated copy through actual identified DxWnd | Wrapper provenance remains separate from native port |
| Human gate | One complete session after all preparation | D-13–D-16; actual results required for acceptance |
| Reversibility | Versioned formats, retained raw artifacts, generated views | Shared contracts are costly to change but migrations remain bounded |
## Shared interfaces for parallel execution
Plan 01-01 owns fidelity_receipts.py and scenarios.json. Downstream plans consume those contracts and must not edit them in parallel. Any demonstrated contract correction returns to the owning plan/integrator before consumers continue.
Receipt schema_version 1 carries receipt_id/session_id/case_id, evidence_kind (static, inferred, component, managed, port_fixture, native_port, original_dxwnd, wine, cross_publish, synthetic), status (incomplete, failed, captured, reviewed), source/build/dirty/diff identity, executable/package/resource/original/launcher hashes, platform and observation method, invocation/cwd, wall/monotonic clocks, artifacts/derivatives, event markers with uncertainty, limitations and explicit acceptance. Reviewed status alone never implies full matrix acceptance. Normalized paths, finite times and actual platform/method compatibility are mandatory.
Scenario contract has eight fresh/retained × natural/skipped × ordinary/edge cells, each requiring a continuous lab→VR04→lab→outside run and focused observations. Every side/platform/cell is independently auditable. A retained case carries one session/continuation identity; fresh launches are independent. Original input annotations remain manually observed unless proven otherwise.
Capability export contract is schema_version, capabilities[] with id/group/requirement_ids/summary/verified_scope/differences/acceptance/source_links/scenario_ids/evidence/current/history/discrepancies. Evidence entries retain receipt identity, revision/content/platform/scope and supersedes/reason. Discrepancies carry impact blocking/disruptive/subtle/missing_verification and stable ID ties. Viewer plan 01-02 consumes this contract; ledger plan 01-03 exports it without shared file writes. The authoritative source is docs/evidence/capabilities.json, not generated Markdown or review JSON.
All CLI commands print counted summaries and nonzero invalid/strict-gap exits. `--allow-open` validates structure while visibly reporting pending acceptance; `--require-complete` cannot succeed without actual native/original and human evidence. New source paths, symbols, CLI names and generated artifacts are enumerated in each plan's “Artifacts this phase produces” paragraph.
## Execution graph and ownership
| Wave | Plans | Owned slice |
|---|---|---|
| 1 | 01-01 | Preservation, receipts and complete protocol |
| 2 | 01-02, 01-03, 01-04 | Viewer; ledger; passive port observer, with zero file overlap |
| 3 | 01-05 | Complete Windows checkpoint/collector |
| 4 | 01-06 | Native Linux capture and evidence |
| 5 | 01-07 | Readiness, one combined session, strict audit and status integration |
Every plan begins with a production tracer and then expands the same capability. There are 15 tasks; no task modifies more than five files. Estimates use measured calibration factor 1, sample_count 0, confidence low. No previous GSD summaries/verify commands or graph context exist.
## Walking-skeleton verification
- Real filesystem read/write and CLI receipt inspection are proven in 01-01.
- Actual local media interaction is wired in 01-02 and reviewed with real recordings in 01-07.
- Existing runtime input/event ownership is observed in 01-04, without changing movement/body algorithms.
- The documented full local workflow is package preparation → checkpoint ready → native capture → local import/review → strict audit. Exact commands and failure signals are in plans.
- Any missing original/native access or backstop evidence remains open/human_needed. Tools completion does not complete Phase 1 acceptance.
## Preserved boundaries for later phases
Movement/rotation/body policies, TSK ordering correction, normal landing bank, actor admission and lab/outside compatibility remain unchanged. Broader source-backed work may proceed only under the roadmap access exception while Phase 1 acceptance remains open. New gadgets, online runtime services, cloud CI and artifact uploads remain outside this phase.