# Re-extraction popup and operator guidance — 2026-09-08

Owner decision: implement now, with the choices and instructions in a popup, not inline in
the Uploads table. This extends Q-EX-18 / extraction spec §4.7; no automatic bulk re-extraction.

- The row's Re-extract button opens the shared dialog. Opening, cancelling and invalid
  submission do not queue anything. Both Portuguese and English are supported.
- **Guided re-extraction:** mandatory 1–2000-character guidance (whitespace-only and control
  characters other than line breaks/tab rejected server-side). Queues one fresh job only
  when no extraction for the document is queued/running. Existing tenant/company access
  and quarantine/duplicate/discard restrictions remain in force.
- **Technical retry:** no new instructions required. Keeps the latest job's guidance. If
  this failed intake already has exactly one future queued job and none running, atomically
  brings that job forward instead of creating a second one. Attempts, payload and lane pauses
  are unchanged. A concurrently claimed or already-due attempt refuses rescheduling.
- Guidance travels in immutable job payload JSON (`operatorGuidance`), the request audit and
  every produced `ProcessingEvidence` element. Evidence history displays it. A retry retains
  it; a new guided job records new guidance without changing previous jobs or evidence.
- The runner appends JSON-encoded review context with explicit precedence for EXTRACT.md,
  printed-document evidence, output validation and sandbox restrictions. No permissions,
  tools, executable paths, contract, validator, model or extraction skill package change.
  Guidance identifies what to verify; it is not a source of replacement facts.
- Each attempt's existing prompt hash covers the actual guided prompt. Ordinary extraction
  and unguided retry retain the exact baseline prompt and package hash.
- Current extracted results are replaced only by the existing successful completion path;
  manual corrections and historical evidence remain unchanged.

## Quality boundary

Guided runs are a new operator-assisted path, not evidence of the frozen baseline's quality.
They do not retroactively alter bench scores or supply held-out validation for extraction v1.
No fresh held-out set was used here. The accepted sealed end-to-end persistence acceptance set
must cover guided correction separately. Unit/integration/browser tests use synthetic Preview
fixtures and canned CLI responses; they cannot establish real-model obedience to guidance.

## Verification

Final unfiltered `local/test.ps1` run with Playwright 1.62.1 / matching Chromium 1234:
**1006 passed, 0 failed, 0 skipped** (Platform 506, Argus 236, Browser 150,
API 56, TenantIsolation 58). Browser scenarios cover PT/EN at 1440/390 pixels, required
guidance, cancellation/focus restoration, technical mode, and confirmed guided submission
persisting the expected payload on a synthetic Preview fixture. Platform tests cover
guidance validation, audit/payload retention, prompt hashing, evidence and the validator
boundary, and bringing forward one pending job without changing its attempt count/payload.

The first full run had 1005 passes and one failure in the untouched Argus
`ReportingTheSamePairTwiceReusesTheOpenItem` test (human-state trigger refusal). It passed
isolated and in the final unfiltered run; no assertion or production trigger was changed.
Desktop EN/mobile PT screenshots were inspected, followed by one bounded layout/validation
feedback adjustment and confirmation. No production deployment or document mutation occurred
as part of implementing this popup.