Document project skills and resources

.gitignore

@@ -5,3 +5,7 @@
 /.devenv.flake.nix
 /devenv.lock
 /game-data/
+
+# Python cache
+__pycache__/
+*.pyc

README.md

@@ -5,10 +5,12 @@ This repository contains a draft specification set for a Nintendo Switch static
 ## Contents
 - `specs/` contains the numbered specification series.
 - `crates/` holds the exploratory pipeline/runtime scaffolding.
+- `skills/` provides the Codex skill set used for validation workflows.
 - `ROADMAP.md` provides phased milestones and exit criteria.
 - `RESEARCH.md` lists research directions and required sources.
 - `docs/` contains development notes.
  - `docs/LEGAL-POLICY.md` defines legal use and asset separation rules.
+ - `docs/static-recomp-skills.md` documents the Codex skill set and project-level validation templates.
 
 ## How to Use the Specs
 - Read `specs/README.md` for ordering.
@@ -31,6 +33,7 @@ Legal and provenance policy:
 ## Samples and Flow Docs
 - `samples/memory-image/` shows the memory image initialization flow (segment blob + lifted module).
 - `docs/static-recompilation-flow.md` outlines a hypothetical macOS static recompilation flow and verification pipeline.
+- `docs/validation-matrix-template.md`, `docs/title-run-sheet-template.md`, `docs/thresholds/default.json`, `docs/batch-manifest-schema.md`, `docs/batch-manifest-schema.json`, and `docs/batch-pipeline-layout.md` are reusable validation templates.
 
 ## Back Pressure Hooks
 These hooks add fast, consistent feedback to keep the repo autonomous and reduce review churn. Hooks are defined in `.pre-commit-config.yaml` and can be run with `prek` (preferred) or `pre-commit`.

RESEARCH.md

@@ -83,6 +83,9 @@ Needed research:
 - nstool (XCI/NCA/NSO extraction): https://github.com/jakcron/nstool
 - Ghidra SLEIGH language reference (p-code semantics): https://github.com/NationalSecurityAgency/ghidra/blob/master/GhidraDocs/languages/html/sleigh.html
 - sleigh library (p-code lifting implementation): https://github.com/lifting-bits/sleigh
+- FFmpeg filter reference for SSIM/PSNR/EBU R128 audio analysis: https://manpages.debian.org/bookworm/ffmpeg/ffmpeg-filters.1.en.html
+- FFmpeg libvmaf filter usage notes: https://manpages.opensuse.org/Tumbleweed/ffmpeg/ffmpeg-filters.1.en.html
+- EBU R 128 loudness recommendation (audio loudness measurement): https://tech.ebu.ch/publications/r128
 
 ## Research Deliverables
 - A research summary for each category with sources.

docs/batch-manifest-schema.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "batch-manifest-schema.json",
+  "title": "Static Recomp Batch Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "batch_id",
+    "created_at",
+    "toolchain",
+    "titles"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "v1"
+    },
+    "batch_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "toolchain": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "pipeline_version": { "type": "string" },
+        "runtime_version": { "type": "string" },
+        "ffmpeg_version": { "type": "string" },
+        "emulator_version": { "type": "string" }
+      }
+    },
+    "global_defaults": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "resolution": { "type": "string" },
+        "frame_rate": { "type": "number" },
+        "audio_rate": { "type": "number" },
+        "renderer_settings": { "type": "string" },
+        "metrics_thresholds": { "$ref": "#/$defs/metrics_thresholds" }
+      }
+    },
+    "titles": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/title" }
+    }
+  },
+  "$defs": {
+    "metrics_thresholds": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "ssim_min": { "type": "number" },
+        "psnr_min": { "type": "number" },
+        "vmaf_min": { "type": "number" },
+        "audio_lufs_delta_max": { "type": "number" },
+        "audio_peak_delta_max": { "type": "number" }
+      }
+    },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provenance_record", "reference_captures", "input_traces"],
+      "properties": {
+        "provenance_record": { "type": "string" },
+        "reference_captures": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "input_traces": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scene_list", "targets"],
+      "properties": {
+        "scene_list": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "targets": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "resolution": { "type": "string" },
+            "frame_rate": { "type": "number" },
+            "audio_rate": { "type": "number" }
+          }
+        },
+        "metrics_thresholds": { "$ref": "#/$defs/metrics_thresholds" }
+      }
+    },
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "last_updated"],
+      "properties": {
+        "state": {
+          "type": "string",
+          "enum": ["pending", "running", "passed", "failed", "needs_review"]
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "notes": { "type": "string" }
+      }
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "report_path": { "type": "string" },
+        "metrics_dir": { "type": "string" },
+        "captures_dir": { "type": "string" }
+      }
+    },
+    "title": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title_id",
+        "title_name",
+        "version",
+        "region",
+        "inputs",
+        "validation",
+        "status"
+      ],
+      "properties": {
+        "title_id": { "type": "string" },
+        "title_name": { "type": "string" },
+        "version": { "type": "string" },
+        "region": { "type": "string" },
+        "build_id": { "type": "string" },
+        "inputs": { "$ref": "#/$defs/inputs" },
+        "validation": { "$ref": "#/$defs/validation" },
+        "status": { "$ref": "#/$defs/status" },
+        "artifacts": { "$ref": "#/$defs/artifacts" }
+      }
+    }
+  }
+}

docs/batch-manifest-schema.md

@@ -0,0 +1,115 @@
+# Batch Manifest Schema (v1)
+
+Machine-validated JSON schema: `docs/batch-manifest-schema.json`.
+
+This schema is intended for catalog-scale batch runs. It records per-title inputs,
+validation targets, and status. Store as JSON or TOML; keys below are canonical.
+
+## Top-level
+- `schema_version` (string, required): Use `v1`.
+- `batch_id` (string, required): Stable identifier for the run.
+- `created_at` (string, required): ISO 8601 timestamp.
+- `toolchain` (object, required): Versions for the pipeline and tools.
+- `global_defaults` (object, optional): Shared defaults for titles.
+- `titles` (array, required): Per-title records.
+
+## toolchain
+- `pipeline_version` (string)
+- `runtime_version` (string)
+- `ffmpeg_version` (string)
+- `emulator_version` (string, optional)
+
+## global_defaults
+- `resolution` (string, example: `1920x1080`)
+- `frame_rate` (number, example: `60`)
+- `audio_rate` (number, example: `48000`)
+- `renderer_settings` (string)
+- `metrics_thresholds` (object)
+
+## titles[]
+- `title_id` (string, required)
+- `title_name` (string, required)
+- `version` (string, required)
+- `region` (string, required)
+- `build_id` (string, optional)
+- `inputs` (object, required)
+- `validation` (object, required)
+- `status` (object, required)
+- `artifacts` (object, optional)
+
+## inputs
+- `provenance_record` (string, required): Path to provenance file.
+- `reference_captures` (array, required): List of reference capture ids.
+- `input_traces` (array, required): List of trace ids.
+
+## validation
+- `scene_list` (array, required): Scene ids used for comparison.
+- `targets` (object, required): Per-title overrides for resolution, fps, audio.
+- `metrics_thresholds` (object, optional): Per-title overrides.
+
+## status
+- `state` (string, required): `pending`, `running`, `passed`, `failed`, `needs_review`.
+- `last_updated` (string, required): ISO 8601 timestamp.
+- `notes` (string, optional)
+
+## artifacts
+- `report_path` (string, optional)
+- `metrics_dir` (string, optional)
+- `captures_dir` (string, optional)
+
+## Example (JSON)
+```json
+{
+  "schema_version": "v1",
+  "batch_id": "switch-2026-02-03",
+  "created_at": "2026-02-03T09:20:00Z",
+  "toolchain": {
+    "pipeline_version": "0.1.0",
+    "runtime_version": "0.1.0",
+    "ffmpeg_version": "6.1"
+  },
+  "global_defaults": {
+    "resolution": "1920x1080",
+    "frame_rate": 60,
+    "audio_rate": 48000,
+    "renderer_settings": "default",
+    "metrics_thresholds": {
+      "ssim_min": 0.95,
+      "psnr_min": 35.0,
+      "vmaf_min": 90.0,
+      "audio_lufs_delta_max": 2.0
+    }
+  },
+  "titles": [
+    {
+      "title_id": "TID-0001",
+      "title_name": "Example Title",
+      "version": "1.0.0",
+      "region": "US",
+      "build_id": "ABCD1234",
+      "inputs": {
+        "provenance_record": "provenance/TID-0001.toml",
+        "reference_captures": ["REF-001"],
+        "input_traces": ["TRACE-001"]
+      },
+      "validation": {
+        "scene_list": ["SCN-001", "SCN-002"],
+        "targets": {
+          "resolution": "1920x1080",
+          "frame_rate": 60,
+          "audio_rate": 48000
+        }
+      },
+      "status": {
+        "state": "pending",
+        "last_updated": "2026-02-03T09:20:00Z"
+      },
+      "artifacts": {
+        "report_path": "reports/TID-0001/summary.json",
+        "metrics_dir": "reports/TID-0001/metrics",
+        "captures_dir": "captures/TID-0001"
+      }
+    }
+  ]
+}
+```

docs/batch-pipeline-layout.md

@@ -0,0 +1,55 @@
+# Sample Pipeline Layout
+
+This is a recommended directory layout for batch execution. Adjust names to match
+local conventions, but keep the separation of inputs, captures, metrics, and reports.
+
+```
+workspace/
+  manifests/
+    batch-2026-02-03.json
+  inputs/
+    provenance/
+      TID-0001.toml
+    traces/
+      TRACE-001.json
+    references/
+      REF-001.mp4
+  builds/
+    TID-0001/
+      recomp/
+        Cargo.toml
+      logs/
+        build.log
+  runs/
+    TID-0001/
+      captures/
+        recomp.mp4
+      metrics/
+        ssim.log
+        psnr.log
+        vmaf.json
+        ref_ebur128.log
+        test_ebur128.log
+      reports/
+        summary.json
+        summary.txt
+      perf/
+        frame_times.csv
+        gpu_stats.json
+```
+
+## Per-title pipeline stages
+1. Intake
+   - Validate provenance file.
+   - Verify required reference captures and input traces exist.
+2. Build
+   - Run recompilation and capture build logs.
+3. Run + capture
+   - Execute with deterministic input trace.
+   - Store capture video/audio and raw logs.
+4. Compare
+   - Run A/V metrics and produce summary.
+5. Performance profile
+   - Capture frame-time and resource metrics.
+6. Report
+   - Emit per-title summary and update manifest status.