docs(01): create verified fidelity baseline plans
This commit is contained in:
1 parent
36f24e4474
commit
cf64b8ce18
21 files changed
+1473
-32
No files matched your search
@@ -0,0 +1,126 @@
|
||||
---
|
||||
phase: 01-reproducible-fidelity-baseline
|
||||
plan: "01"
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- tools/recon/fidelity.py
|
||||
- tools/recon/fidelity_receipts.py
|
||||
- tests/test_fidelity_sessions.py
|
||||
- docs/evidence/scenarios.json
|
||||
- tests/test_fidelity_scenarios.py
|
||||
autonomous: true
|
||||
requirements: [EVID-01, EVID-02, EVID-04]
|
||||
estimate:
|
||||
tokens: 34000
|
||||
raw_tokens: 34000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "A reviewer can stage and identify a pristine generated original installation without altering any original byte (EVID-01, D-15)."
|
||||
- "The protocol requires continuous lab → VR04 → lab → outside and focused dialogue-return, left/right banked-jump, landing and idle captures per D-01 and D-04."
|
||||
- "Natural/skipped dialogue and fresh/retained entry are equally required, independently identified dimensions per D-02 and D-03."
|
||||
- "Equal, nested, symlink-aliased and Windows case-aliased source/output paths fail before any staging write; sibling paths merely sharing a textual prefix remain distinct."
|
||||
- "Empty/missing inventories fail; single-file fixtures round-trip, while changed, missing and added files invalidate identity."
|
||||
- "Manifest order is canonical relative POSIX path order; case-colliding identities fail instead of acquiring filesystem-dependent order."
|
||||
- "Interrupted staging/import leaves an explicit incomplete diagnostic and no completed receipt; simultaneous same-session allocation has one winner, and duplicate receipt imports are idempotent only for byte-identical content."
|
||||
- "Typed receipt validation retains failures and missing evidence as open acceptance; D-13 Windows availability is not a runtime receipt."
|
||||
artifacts:
|
||||
- path: tools/recon/fidelity.py
|
||||
provides: "Local stage, identify, import and validate CLI"
|
||||
- path: tools/recon/fidelity_receipts.py
|
||||
provides: "Versioned receipt, identity, containment and atomic publication contract"
|
||||
- path: docs/evidence/scenarios.json
|
||||
provides: "Required baseline matrix and observed-event protocol"
|
||||
key_links:
|
||||
- from: tools/recon/fidelity.py
|
||||
to: tools/recon/inventory.py
|
||||
via: "Recorded original inventory checked before staging and after collection"
|
||||
- from: tools/recon/fidelity_receipts.py
|
||||
to: docs/evidence/scenarios.json
|
||||
via: "Stable case IDs and completeness rules"
|
||||
prohibitions:
|
||||
- statement: "MUST NOT sacrifice authoritative original bytes or execute the authoritative installation to make reference collection convenient."
|
||||
status: unresolved
|
||||
reason: "Spec-less recall: preservation is a project value; descriptor-less and flagged-unverified for review."
|
||||
---
|
||||
|
||||
<objective>
|
||||
**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.
|
||||
|
||||
Roadmap-derived framing supplied by the orchestrator. Prove the local evidence workflow from immutable inventory through generated copy, actual package identity, imported bounded evidence and a readable receipt. Establish the complete scenario contract before parallel consumers begin.
|
||||
|
||||
Artifacts this phase produces in this plan: fidelity.py CLI subcommands stage, identify, import and validate; fidelity_receipts.py functions stage_original, identify_tree, validate_receipt and import_receipt; schema_version 1 local JSON contracts; tests/test_fidelity_sessions.py; docs/evidence/scenarios.json; tests/test_fidelity_scenarios.py. Generated session/receipt/manifest outputs belong in artifacts/fidelity/ and remain ignored. These are new tooling interfaces, not recovered game interfaces.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
|
||||
@/home/cristian/.codex/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@AGENTS.md
|
||||
@.planning/PROJECT.md
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/REQUIREMENTS.md
|
||||
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
|
||||
@.planning/phases/01-reproducible-fidelity-baseline/01-RESEARCH.md
|
||||
@.planning/phases/01-reproducible-fidelity-baseline/01-PATTERNS.md
|
||||
@.planning/phases/01-reproducible-fidelity-baseline/SKELETON.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
<task type="tracer" tdd="true" id="01-01-01">
|
||||
<name>Stage one preserved session and review one honestly classified receipt end to end</name>
|
||||
<reversibility rating="costly">Versioned local records are shared by later tools; retaining raw inputs and explicit schema versions keeps migration bounded.</reversibility>
|
||||
<files>tools/recon/fidelity.py, tools/recon/fidelity_receipts.py, tests/test_fidelity_sessions.py</files>
|
||||
<read_first>tools/recon/inventory.py; tools/recon/reference_capture.py; scripts/package.sh; tests/test_extractors.py; docs/compatibility.md; docs/original-manifest.json; 01-RESEARCH.md sections Existing Analogs, Pattern 1 and Security Domain.</read_first>
|
||||
<behavior>At least 16 discovered tests cover a valid CLI stage→identify→import→validate round trip, changed/missing/added originals, empty/single-file manifests, two-direction path equality/overlap and sibling prefixes, symlink/drive/case escape, shell characters as inert paths, reuse/concurrent allocation, interruption, byte tampering, identical duplicate import and conflicting duplicate ID. Native acceptance rejects synthetic/component/Wine/cross-publish classifications.</behavior>
|
||||
<action>Create tests first, including one subprocess-level CLI round trip with tiny fixture trees. Implement stdlib-only tools with argument arrays, bounded subprocess/JSON sizes and streaming SHA-256. Reuse the existing inventory comparison without regenerating docs/original-manifest.json. Resolve and validate all roots before writing; reject symlink escapes, Windows normalized aliases, case collisions and source/output overlap in either direction. Allocate fresh session directories exclusively, stage in a temporary sibling and atomically publish after complete pre-run copy verification; failed/interrupted attempts retain diagnostics without publishing a completed receipt. Lock session/import publication and distinguish exact duplicate content from conflicting reuse. Stage a separate generated original copy per fresh run per D-15; retained cases keep one explicitly identified lifetime. Store pre-run copy identity, post-run copy changes and source pre/post inventory separately. Define receipt identity, evidence_kind, status, case/session IDs, actual executable/package/resource and launcher hashes, actual source/dirty/diff identity, native/platform category, invocation/cwd, clocks, artifacts/derivatives and open acceptance. Separate reported historical evidence from newly generated evidence. Exercise one real existing on-disk port package/report, verifying its actual bytes and reporting its recorded scope; if referenced artifacts are absent, explicitly retain missing/stale evidence rather than minting identity. Import an explicitly synthetic paired-media fixture only to exercise plumbing; it cannot qualify as original/native proof. The validate command prints a readable receipt summary with actual category, missing evidence and acceptance state, not just success. Preserve the legacy Wine harness classification and behavior. Establish read-only contained relative references and a documented allowed-receipt state machine for later consumers.</action>
|
||||
<acceptance_criteria>The CLI round trip yields a hashed receipt and readable summary; original/copy/package identities are distinct; every hostile/partial identity case is rejected without original writes; an existing report is labeled historical or missing exactly as found; synthetic paired fixtures remain in a separate test namespace; no completed acceptance results from a launcher exit code.</acceptance_criteria>
|
||||
<verify>
|
||||
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_sessions.py"); assert s.countTestCases() >= 16,"fewer than 16 session tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
|
||||
<fails_when>Nonzero exit, fewer than 16 discovered tests, any failed round-trip/security/classification case, or no test summary.</fails_when>
|
||||
<automated>python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json</automated>
|
||||
<fails_when>Nonzero exit or missing output Verified 539 unchanged original files.</fails_when>
|
||||
</verify>
|
||||
<done>One preserved session can be staged, identified, imported and inspected through the real CLI; all negative tests pass; genuine historical evidence and synthetic test data remain visibly distinct from new native acceptance.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true" id="01-01-02">
|
||||
<name>Make every required journey and lifetime cell explicit and reject incomplete evidence</name>
|
||||
<files>docs/evidence/scenarios.json, tests/test_fidelity_scenarios.py, tools/recon/fidelity.py, tools/recon/fidelity_receipts.py</files>
|
||||
<read_first>01-CONTEXT.md D-01 through D-04; .planning/REQUIREMENTS.md EVID-01 through EVID-04; the receipt interfaces created in task 01-01-01; docs/checkpoint/next-work-plan.md; docs/gameplay/main-menu-player-lifetime.md.</read_first>
|
||||
<behavior>At least 12 tests require all eight fresh/retained × natural/skipped × ordinary/edge cells, continuous and focused evidence for each, stable IDs/order, real retained-session continuity, and explicit skipped/aborted/missing cases. Equal counts with a missing cell, disconnected scene snapshots, reset timestamps and synthetic/native substitution fail completeness.</behavior>
|
||||
<action>Define schema-versioned scenarios.json with eight explicit matrix cells and a continuous journey plus focused replay obligations per cell per D-01–D-04. Ordinary runs use normal play; edge runs include held input spanning dialogue/RETURN, both bank directions, landing and idle. Natural and skipped dialogue are separate equal obligations per D-02. Fresh means an independently staged launch; retained means a recorded departure/return in the same session, including prerequisite setup and retained copy state, per D-03. Specify visible setup, actions, end condition and required media/event markers for startup/control, dialogue start/end/skip, first neutral/resumed held input, jump/bank/landing/idle, lab departure, VR04 entry/use, RETURN/cleanup, lab exit and outside arrival. Markers reference actual media time, monotonic elapsed time and observation method/uncertainty; simulation ticks stay separate. Original annotations are procedural/manual unless directly observed by a proven recorder. Allow truthful missing/failed results, but require all cells and artifacts for acceptance. Add validate --scenarios PATH --receipts ROOT with --allow-open for structural readiness and --require-complete for actual acceptance; both emit counts and missing case IDs, and the strict mode exits nonzero on gaps. Never invent universal timing/pixel/audio tolerances. Keep the existing TSK ordering correction, fresh direct-scene order and legitimate landing bank as protected observations rather than changes.</action>
|
||||
<acceptance_criteria>There are eight uniquely identified matrix cells with explicit continuous and focused obligations; validators detect omitted dimensions and broken retained continuity; structural readiness and evidence acceptance use visibly different verdicts.</acceptance_criteria>
|
||||
<verify>
|
||||
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_scenarios.py"); assert s.countTestCases() >= 12,"fewer than 12 scenario tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
|
||||
<fails_when>Nonzero exit, fewer than 12 discovered tests, or a missing matrix/continuity/classification negative case passes validation.</fails_when>
|
||||
</verify>
|
||||
<done>Every required baseline run has a stable executable procedure, complete artifact obligations and a validator that preserves missing acceptance.</done>
|
||||
</task>
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
ASVS level 1; unresolved high/critical threats block execution acceptance. No package installs are planned.
|
||||
|
||||
| Boundary | Description |
|
||||
|---|---|
|
||||
| Authoritative originals → generated session | Reads may produce writable copies only outside originals |
|
||||
| Imported local records → evidence index | Untrusted paths, classifications and identities become reviewable records |
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|---|---|---|---|---|---|
|
||||
| T-01-01 | Tampering | stage_original | high | mitigate | Resolve aliases before allocation; reject overlaps; verify recorded originals before/after and staged bytes before execution |
|
||||
| T-01-02 | Spoofing | validate_receipt/import_receipt | high | mitigate | Bind actual bytes, platform/method/scope and schema; reject promotion of synthetic/Wine/cross-publish; retain failures |
|
||||
| T-01-03 | Tampering | Session publication | high | mitigate | Exclusive allocation, atomic completed publication, bounded failure diagnostics and conflicting-ID rejection |
|
||||
| T-01-SC | Tampering | Package installation | high | mitigate | No new packages; any later proposed npm/pip/cargo install requires research legitimacy audit before execution |
|
||||
</threat_model>
|
||||
|
||||
<verification>Run both counted test suites and original inventory check. Confirm current tree baselines: these new tooling/tests do not exist at planning time, so no new behavior is claimed verified. CLI negative tests must demonstrate nonzero exits, not only raised internal exceptions.</verification>
|
||||
<success_criteria>Preservation and complete scenario contracts support independent viewer, ledger and native capture work without claiming new original/native execution.</success_criteria>
|
||||
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md with interfaces, actual test counts/durations and evidence boundaries.</output>
|
||||
Reference in new issue
Block a user