---
phase: 1
slug: extraction
status: draft
nyquist_compliant: false
wave_0_complete: false
created: 2026-05-02
---

# Phase 1 — Validation Strategy

> Per-phase validation contract for feedback sampling during execution.

---

## Test Infrastructure

| Property | Value |
|----------|-------|
| **Framework** | vitest (Wave 0 installs — no test infra in repo yet) |
| **Config file** | `tools/extract-gmd/vitest.config.ts` (Wave 0) |
| **Quick run command** | `pnpm --filter ./tools/extract-gmd test -- --run` |
| **Full suite command** | `pnpm --filter ./tools/extract-gmd test -- --run --coverage` |
| **Estimated runtime** | ~30 seconds (full); ~5 seconds (quick) |

---

## Sampling Rate

- **After every task commit:** Run quick run command (single-file or single-suite scope where possible)
- **After every plan wave:** Run full suite command
- **Before `/gsd-verify-work`:** Full suite must be green AND `pnpm extract:verify` (SHA256 manifest check) passes for both source `.gmd` files
- **Max feedback latency:** 30 seconds

---

## Per-Task Verification Map

> Filled by planner per task. Every task must declare `<automated>` verify command OR Wave 0 dependency on a fixture/test stub.

| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
| 1-XX-XX | XX | N | EXT-XX | — | N/A (no production trust boundary in extractor; legal/IP gate at commit) | unit/integration | `pnpm --filter ./tools/extract-gmd test ...` | ❌ W0 | ⬜ pending |

*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*

---

## Wave 0 Requirements

- [ ] `tools/extract-gmd/package.json` — declare `vitest`, `tsx`, `sharp`, `zlib` (node builtin), `@types/node`; pin versions
- [ ] `tools/extract-gmd/vitest.config.ts` — vitest config (coverage thresholds, test file glob)
- [ ] `tools/extract-gmd/tsconfig.json` — strict TS, Node 22 lib
- [ ] `tools/extract-gmd/test/fixtures/README.md` — fixture provenance and reproducibility notes
- [ ] `tools/extract-gmd/test/fixtures/golden-tiny.gmd` — hand-crafted minimal `.gmd` v530 (1 sprite, 1 script, 1 object event with one DnD action) plus expected output tree
- [ ] `tools/extract-gmd/test/fixtures/iso8859-sentinel.gmd` — fixture with non-ASCII string in resource name to lock encoding (cp1252 / ISO-8859-1)
- [ ] `tools/extract-gmd/test/snapshot/` — snapshot baseline directory for golden tree diff
- [ ] LateralGM 1.8.234 reference clone or vendored Action_ID library XMLs at `tools/extract-gmd/data/action-ids.json` — derived from `org/lateralgm/resources/library/default/`
- [ ] `tools/extract-gmd/test/oracle/probe.java` (Wave 5) — minimal Java probe to print resource counts per block; runtime cross-check oracle
- [ ] CI: `pnpm extract:verify` script invocable from repo root (Phase 5 wires it into GitHub Actions; Phase 1 ships the script)

---

## Manual-Only Verifications

| Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------|
| LateralGM oracle agreement on real `BN Online Client 5-8.gmd` and `Master 5-4.gmd` | EXT-02, EXT-03 | LateralGM has no documented headless export CLI; project ships a custom Java probe (Wave 5) — running it requires JVM presence on dev machine | Run `java -cp lateralgm-1.8.234.jar:probe ProbeMain <input.gmd>`; compare resource counts per block to `extracted/<source>/MANIFEST.sha256` header counts |
| WinXP VM + GM 5.3a IDE Rank-3 fallback procedure | EXT-08 | Documentation-only deliverable per D-04; no automated check meaningful | Reviewer reads `decomp/TOOLS.md`, confirms procedure references wiki/15 and is reproducible from a cold start |
| `extracted/` artefacts not pushed publicly | CONCERNS.md §Legal/IP | Legal gate, not a code property | Pre-push manual check; repo stays private through Phase 7 per CLAUDE.md hard rule #8 |

---

## Validation Sign-Off

- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
- [ ] Wave 0 covers all MISSING references
- [ ] No watch-mode flags
- [ ] Feedback latency < 30s
- [ ] `nyquist_compliant: true` set in frontmatter

**Approval:** pending