# v1.6.1 Stabilization Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Prove and release the v1.6.1 validated-resumed AMD Windows pipeline with a deadlock-free HIP startup path and provenance-complete evidence.

**Architecture:** Fix deterministic local defects first with test-first changes in an isolated worktree. Then use the profile orchestrator itself as the acceptance harness: a fresh 10-page HIP run validates process/GPU behavior, and a clean full-profile resume binds the unchanged prediction tree to newly generated scores and evidence.

**Tech Stack:** Windows PowerShell 5.1, Python 3.11, pytest, uv, llama.cpp HIP, WSL Ubuntu2204, OmniDocBench v1.6.

## Global Constraints

- Execute tasks serially; an independent subagent must approve each task before the next begins.
- Preserve setup idempotency and the `PYTHONUTF8=1` scoring behavior.
- Formal full profiles run only from a clean git worktree.
- The full profile requires 1651 selected pages, coverage at least 0.998, at most 2 failed pages, and no failures outside the configured allowlist.
- Required raw metric thresholds are text Edit-distance < 0.10, reading-order Edit-distance < 0.20, TEDS > 0.85, and CDM > 0.85.
- Evidence level remains `validated resumed`; `clean-room` is forbidden without a fresh-checkout full inference.
- Do not push or publish a release without a separate explicit user request.

---

### Task 1: Make the release gate execute its declared checks

**Files:**
- Modify: `tests/test_release_gate.py`
- Modify: `scripts/release-gate.ps1`

**Interfaces:**
- Consumes: `pyproject.toml` containing `version = "<semver>"`.
- Produces: `$version` as a non-empty string, or `RELEASE GATE FAIL: pyproject.toml has no version declaration`.

- [ ] **Step 1: Write the failing execution test**

Add a Windows test that runs `release-gate.ps1 -Tag v-test-tag-that-does-not-exist`, asserts a nonzero exit, asserts the output contains `tag v-test-tag-that-does-not-exist does not exist`, and asserts it does not contain `Cannot index into a null array`.

- [ ] **Step 2: Run the test and verify RED**

Run: `.\.venv\Scripts\python.exe -m pytest -q tests\test_release_gate.py::test_release_gate_reads_version_before_tag_check`

Expected: FAIL because the current script raises `Cannot index into a null array` before checking the tag.

- [ ] **Step 3: Implement the minimal parser fix**

Use `[regex]::Match($pyproject, '(?m)^version = "([^"]+)"$')`, check `Success`, call `Fail` on absence, and assign group 1 to `$version`.

- [ ] **Step 4: Verify GREEN**

Run the focused test, then `tests/test_release_gate.py`; both must pass.

- [ ] **Step 5: Commit and independent review**

Commit only the release-gate test and implementation. Reviewer must provide separate spec-compliance and code-quality verdicts.

### Task 2: Remove the inherited-pipe deadlock at the orchestrator boundary

**Files:**
- Modify: `tests/test_windows_reproduce.py`
- Modify: `tests/test_backend_proof.py` or the closest existing VLM setup source-guard test
- Modify: `scripts/reproduce.ps1`
- Modify: `adapters/paddleocr-vl-1.6/01-vlm-server/setup.ps1`

**Interfaces:**
- Consumes: native executable path and joined PowerShell 5.1 argument string.
- Produces: live console output, deterministic `$proc.ExitCode`, and a hidden long-lived wrapper whose PID is persisted by server setup.

- [ ] **Step 1: Write failing source-invariant tests**

Assert the `Invoke-ReproNative` function block contains `-NoNewWindow` and no `-RedirectStandardOutput`/`-RedirectStandardError`. Assert the VLM launch block uses `Start-Process`, `-WindowStyle Hidden`, and `-PassThru`, and does not use `Invoke-CimMethod -ClassName Win32_Process`.

- [ ] **Step 2: Run the focused tests and verify RED**

Run the exact new tests. Expected: FAIL on the committed WMI/redirect implementation.

- [ ] **Step 3: Implement the minimal launch changes**

Replace redirected temporary-file execution in `Invoke-ReproNative` with `Start-Process -Wait -PassThru -NoNewWindow`. Restore the server wrapper to hidden `Start-Process -PassThru` and persist `$proc.Id`.

- [ ] **Step 4: Verify GREEN and regression suite**

Run the new focused tests, `tests/test_reproduce_harness.py`, and then the full 307-test suite. All must pass.

- [ ] **Step 5: Commit and independent review**

Commit the tests and minimal implementation. Reviewer must inspect the full task diff and confirm no exit-code, output, PID, or cleanup regression.

### Task 3: Prove the fresh HIP smoke path

**Files:**
- Runtime artifacts under `outputs/reproduction/hip-smoke-10/` and `predictions/paddleocrvl_hip_smoke_10/` only.

- [ ] **Step 1:** Seed locked bulk inputs from the main checkout without copying predictions or scores.
- [ ] **Step 2:** Run `scripts/reproduce.ps1 -Profile hip-smoke-10 -ForceInference -SeedFrom <main> -SkipCdmSetup`.
- [ ] **Step 3:** Pause at the mandatory GPU confirmation point and obtain human confirmation before continuing.
- [ ] **Step 4:** Verify 10/10 predictions, HIP backend proof, no CPU fallback, all metrics present, strict summary pass, and complete evidence hashes/provenance.
- [ ] **Step 5:** Have an independent subagent review artifacts and commands before marking complete.

### Task 4: Regenerate full-set provenance-bound evidence

**Files:**
- Runtime artifacts for `paddleocr-vl-hip-full-1651`; no prediction-content change is expected.

- [ ] **Step 1:** Record the existing full prediction-tree hash.
- [ ] **Step 2:** Run the clean formal profile with `-Resume`, seeding locked inputs as required and reusing the verified WSL CDM environment.
- [ ] **Step 3:** Confirm the post-run tree hash equals the pre-run hash; otherwise stop and investigate before accepting scores.
- [ ] **Step 4:** Verify Windows and WSL provenance sidecars, all four phase fingerprints, strict summary, artifact hashes, cross-platform agreement, page count, budgets, and thresholds.
- [ ] **Step 5:** Have an independent subagent audit the complete evidence pack.

### Task 5: Close the v1.6.1 release gate

**Files:**
- Create: `docs/release-v1.6.1.md`
- Modify only if generated drift exists: `README.md`, `README.zh-CN.md`
- Runtime release artifacts under `outputs/release/v1.6.1/`.

- [ ] **Step 1:** Write release notes with Verified devices, Unverified devices, Known limitations, and Evidence levels, explicitly labeling the full row `validated resumed`.
- [ ] **Step 2:** Validate benchmark and adapter schemas and regenerate benchmark tables.
- [ ] **Step 3:** Ensure the worktree is clean, create local tag `v1.6.1`, and run `scripts/release-gate.ps1 -Tag v1.6.1 -WriteArtifacts`.
- [ ] **Step 4:** Verify SBOM, SHA256SUMS, evidence manifest, tag/version equality, and a clean tree.
- [ ] **Step 5:** Have an independent subagent perform the final release audit. Do not push or publish.
