113 lines
11 KiB
Markdown
113 lines
11 KiB
Markdown
---
|
||
phase: 01-reproducible-fidelity-baseline
|
||
plan: "02"
|
||
type: execute
|
||
wave: 2
|
||
depends_on: ["01-01"]
|
||
files_modified:
|
||
- tools/recon/fidelity_review.py
|
||
- tools/recon/fidelity_viewer/index.html
|
||
- tools/recon/fidelity_viewer/viewer.mjs
|
||
- tools/recon/fidelity_viewer/style.css
|
||
- tests/test_fidelity_review.py
|
||
- tests/fidelity-viewer.test.mjs
|
||
autonomous: true
|
||
requirements: [EVID-02, EVID-03, EVID-04]
|
||
estimate:
|
||
tokens: 32000
|
||
raw_tokens: 32000
|
||
tasks: 2
|
||
confidence: low
|
||
must_haves:
|
||
truths:
|
||
- "A tester opens a local scenario with paired original/port playback and corresponding image, audio and input/event links per D-05."
|
||
- "Raw captures are unobstructed by default; annotations and provenance-bound image differences are optional overlays per D-06."
|
||
- "Selecting an event seeks each recording to its own observed time; both play at actual speed with separate elapsed clocks, event drift and playback drift per D-07."
|
||
- "The reviewer switches corresponding original/port audio with at most one source audible and visible review gain per D-08."
|
||
- "Missing, buffering, rejected-play, decoding and asymmetric-end states remain visible and preserve the full recording tails."
|
||
artifacts:
|
||
- path: tools/recon/fidelity_review.py
|
||
provides: "Contained local review export/server"
|
||
- path: tools/recon/fidelity_viewer/viewer.mjs
|
||
provides: "Testable paired media controller and capability navigation renderer"
|
||
- path: tests/fidelity-viewer.test.mjs
|
||
provides: "Built-in Node media-state tests without dependency installation"
|
||
key_links:
|
||
- from: tools/recon/fidelity_review.py
|
||
to: tools/recon/fidelity_receipts.py
|
||
via: "Only validated receipt/artifact identities enter generated review data"
|
||
- from: tools/recon/fidelity_viewer/viewer.mjs
|
||
to: "Generated review.json and contained media"
|
||
via: "Actual per-side event times and exclusive mute state"
|
||
prohibitions:
|
||
- statement: "MUST NOT manufacture apparent parity by retiming recordings, hiding drift, mixing both soundtracks or presenting synthetic media as an original reference."
|
||
status: unresolved
|
||
reason: "Spec-less recall; descriptor-less and flagged-unverified pending real playback judgment."
|
||
---
|
||
|
||
<objective>
|
||
Deliver the local paired review workflow per D-05–D-08. This is a filesystem-based tool, with a contained loopback viewer only where browser seeking requires it.
|
||
|
||
Artifacts this phase produces in this plan: fidelity_review.py CLI export and serve; generated review.json, index.html and copied/link-validated media under artifacts/fidelity/review; viewer.mjs exports createPairController and renderCapabilities; index.html/style.css; counted Python export/server tests and Node media-state tests. No hosted site or external integration.
|
||
</objective>
|
||
<execution_context>
|
||
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
|
||
@/home/cristian/.codex/gsd-core/templates/summary.md
|
||
</execution_context>
|
||
<context>
|
||
@.planning/PROJECT.md
|
||
@.planning/ROADMAP.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-01-SUMMARY.md
|
||
</context>
|
||
<tasks>
|
||
<task type="tracer" tdd="true" id="01-02-01">
|
||
<name>Open one validated local pair with real media links and event selection</name>
|
||
<files>tools/recon/fidelity_review.py, tools/recon/fidelity_viewer/index.html, tools/recon/fidelity_viewer/viewer.mjs, tests/test_fidelity_review.py, tests/fidelity-viewer.test.mjs</files>
|
||
<read_first>01-RESEARCH.md Pattern 3 and Security Domain; 01-01-SUMMARY.md receipt interfaces; tools/recon/fidelity_receipts.py; docs/evidence/scenarios.json; 01-CONTEXT.md D-05–D-08.</read_first>
|
||
<behavior>At least 10 Python tests export and serve one valid imported pair end to end, preserve synthetic labels, reject traversal/symlinks/absolute or remote references and escaping labels, test GET/HEAD/byte-range seeking, and forbid write methods. Initial Node tests exercise event alignment, actual-speed playback, artifact links and failed play with media doubles.</behavior>
|
||
<action>Create tests before implementation. Export a self-contained review tree from validated receipts and their hashed artifacts; expose a real CLI flow from import output to generated review index and paired native media elements. Use one existing genuine port artifact where present and clearly labeled synthetic audiovisual pair fixtures for plumbing; display missing original reference explicitly. Retain raw recordings and derivative ancestry. Include links to original/port recordings, source audio, lossless stills and traces per D-05. Validate event correspondence and finite in-range timestamps before seeking. For local serving, bind loopback only, serve only the generated review root, reject resolved symlink escapes and unsupported methods, implement bounded GET/HEAD byte-range responses so seeking is exercised by tests; never expose repository/original roots or a write endpoint. Use textContent/escaped rendering and contained relative links, never imported HTML/commands. The browser shows scope/platform/synthetic/missing labels beside results, and no successful export or fixture is an acceptance receipt. Add capability-navigation rendering consuming the ledger model contract recorded in SKELETON.md, without inventing ledger facts.</action>
|
||
<acceptance_criteria>A CLI subprocess export plus local HTTP test opens both fixture media links and event metadata; malicious paths/labels cannot escape or execute; missing original is visible; generated media is local and properly classified.</acceptance_criteria>
|
||
<verify>
|
||
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_review.py"); assert s.countTestCases() >= 10,"fewer than 10 review tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
|
||
<fails_when>Nonzero exit, fewer than 10 tests, failed CLI/export/range test, or a traversal/write-method negative case is accepted.</fails_when>
|
||
<automated>node --test tests/fidelity-viewer.test.mjs</automated>
|
||
<fails_when>Nonzero exit, zero tests or absence of a positive pass count; any media alignment/link/classification test fails.</fails_when>
|
||
</verify>
|
||
<done>One explicitly classified pair travels from validated receipt through local export/serving to the paired reviewer; no external request is required.</done>
|
||
</task>
|
||
<task type="auto" tdd="true" id="01-02-02">
|
||
<name>Complete truthful timing, exclusive audio, optional overlays and failure interaction</name>
|
||
<files>tools/recon/fidelity_viewer/index.html, tools/recon/fidelity_viewer/viewer.mjs, tools/recon/fidelity_viewer/style.css, tests/fidelity-viewer.test.mjs, tests/test_fidelity_review.py</files>
|
||
<read_first>The pair controller created in task 01-02-01; 01-CONTEXT.md D-06–D-08; 01-RESEARCH.md Pattern 3 and Meaningful Negative Cases.</read_first>
|
||
<behavior>At least 16 Node tests cover both elapsed clocks, event versus playback drift, rate 1.0 after seek/play/recovery, exclusive audio switch, default gain 1, labeled adjusted gain, missing/buffering/decode/play-rejection states, asynchronous seek readiness, asymmetric ends/tails, overlays default off and viewport mismatch. The test runner asserts its own nonzero count.</behavior>
|
||
<action>Keep video surfaces unobstructed by default and make annotation/difference layers separately opt-in per D-06. Event selection pauses both, waits for readiness, seeks each side independently to its own observed marker and resumes only on explicit review action at playbackRate 1 per D-07. Display absolute recording elapsed times, aligned-event elapsed offsets, scenario-event drift with uncertainty and browser playback drift separately. No periodic follower seeking, duration normalization or hidden timing correction. Expose per-side manual controls and raw media links. On buffering/missing/decode/play rejection pause the pair and show the cause; if one side ends, preserve and make the longer tail playable instead of trimming it. Mute both before selecting one soundtrack at corresponding times per D-08; gain starts unadjusted, is visibly labeled review-only when changed, and never changes recorded media. Optional image differences require matched lossless frame identity, viewport/aspect and crop metadata; explain mismatches and avoid numerical fidelity claims from lossy video. Add keyboard-accessible controls, readable narrow-window layout and explicit empty review states. Keep raw captures and elapsed time visible throughout.</action>
|
||
<acceptance_criteria>Sixteen or more behavior tests pass; both tracks always remain at real speed; at most one soundtrack is audible; initial overlays are off; failures and longer tails remain accessible. Browser/real-audio judgment remains an end-of-phase human check.</acceptance_criteria>
|
||
<verify>
|
||
<automated>node --test tests/fidelity-viewer.test.mjs</automated>
|
||
<fails_when>Nonzero exit, fewer than 16 declared/executed tests, missing positive test summary, or any drift/rate/audio/error/overlay assertion fails.</fails_when>
|
||
<human-check>During the single combined session, open real paired media in the actual browser; hear each source separately, seek observed markers, inspect asymmetric tails and toggle overlays. Record browser/version/codec failures and leave affected review acceptance open.</human-check>
|
||
</verify>
|
||
<done>The paired reviewer implements D-05–D-08 with tested state handling; actual codec/audio playback is listed for the one final session without creating an earlier user request.</done>
|
||
</task>
|
||
</tasks>
|
||
<threat_model>
|
||
ASVS level 1; high/critical unresolved threats block acceptance. No package installs.
|
||
|
||
| Boundary | Description |
|
||
|---|---|
|
||
| Imported evidence → HTML/media | Labels and paths become local browser content |
|
||
| Loopback HTTP → generated files | Only the contained generated tree is readable |
|
||
|
||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||
|---|---|---|---|---|---|
|
||
| T-01-04 | Information disclosure | fidelity_review server | high | mitigate | Loopback only, root containment, symlink rejection, bounded byte ranges, read-only methods |
|
||
| T-01-05 | Tampering | Viewer text/media links | high | mitigate | Escaped/text rendering, local relative URL allowlist and no receipt commands/HTML execution |
|
||
| T-01-06 | Spoofing | Pair controller | medium | mitigate | Visible evidence category, raw clocks, rate 1 and explicit missing/uncertainty states |
|
||
| T-01-SC | Tampering | Package installation | high | mitigate | Built-in browser/Node/Python only; no npm/pip additions |
|
||
</threat_model>
|
||
<verification>Run counted Python and Node checks. First real-media browser acceptance occurs with final combined session; fixture playback is tooling evidence only.</verification>
|
||
<success_criteria>Local paired review exposes visual/audio/event correspondence without concealing drift or inventing original execution.</success_criteria>
|
||
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md with local invocation and measured checks.</output>
|