Hancom visual qa accelerator

Hancom Visual QA Accelerator

Use this skill to prepare many HWPX checks without GUI work, then finish them in one explicitly approved foreground burst. It does not create or edit documents; pair it with the local HWPX/Hancom skill that owns authoring and the actual visual judgment.

Hard boundaries

• Keep python-hwpx pinned to 2.24.0.
• Never rebuild ZIP/XML manually, use LibreOffice headless, use Word COM, lower Hancom security, or start background Hancom COM.
• Judge the non-GUI gate only by validate_document_plan().ok, lint_layout().ok, and validate_editor_open_safety().ok.
• Treat manifest fallback warnings as normal; do not investigate them.
• Open Hancom only from burst-start, after all non-GUI work is complete and the user has approved the foreground burst.
• Never inherit a receipt for submission/final-delivery work.
• Never accept a receipt without matching file, plan, runtime, gate-script, environment, review scope, unexpired TTL, and existing image evidence.
• Never treat a generic accessibility match for 보안 as a warning dialog; require an owned modal and an exact warning phrase.
• Never auto-steal a burst lease or terminate an Hwp process the orchestrator did not launch.
• Never treat a PID or HWND alone as ownership. Recheck the recorded creation time, executable identity, and complete expected window set immediately before cleanup; read identity and terminate through the same process handle, and never post WM_CLOSE.
• If an Hwp process already exists or appears during a burst, preserve the user's windows, stop automatic progression, and require a new explicit foreground action.

Workflow

1. Read references/workflow.md.
2. Create one manifest containing every HWPX and its authoring plan or planPath.
3. Run hancom_qa_orchestrator.py enqueue, then prepare. These background commands pin manifest/document/plan hashes and run the three non-GUI gates without opening Hancom.
4. Stop on GATED_REJECT. Inspect status, then ask for one explicit approval before any foreground action.
5. Run burst-start once. It creates a nonce-bound lease, obtains the environment fingerprint through the real GUI boundary, finalizes cache/live decisions, verifies that no Hwp process exists, and direct-opens the first live document.
6. Confirm the returned windowTitle, activate that exact window immediately before capture, scan for exact owned warning modals, inspect all required pages, and take only final evidence image(s).
7. Submit the observed result with burst-review. A passing review requires the title match, at least one checked page range, and at least one absolute evidence path. The orchestrator stages and verifies the receipt before committing it, closes only its owned Hwp tree, and opens the next document only when no other Hwp process exists.
8. Use recover --confirm-stale only for a stale persistent lease. It clears partial opener/review data, never terminates Hwp, and requires a fresh foreground approval afterward.
9. For later non-submission runs only, opt in to receipt inheritance at enqueue. Use --submission for final/submission review; cached results must remain zero.

Fail-closed behavior

• A changed file after queue creation must fail the opener or receipt recorder by SHA mismatch.
• prepare cannot bypass an interrupted foreground lease; explicit stale recovery is required.
• Missing or expired evidence returns the document to live review.
• Evidence changed between observation and receipt commit leaves the real receipt store unchanged; cooperating batches sharing a receipt store are serialized by an OS lock.
• A crash-left command-lock sidecar does not deadlock the batch because ownership is an OS lock, not file existence.
• A lease release interrupted between deletion and the final state write remains recoverable through its recorded releasePending intent.
• Environment, plan, gate script, version, or scope mismatch returns the document to live review.
• Direct-open failure does not authorize extra keystrokes; use the documented Launcher fallback with at most one calibration screenshot.
• A receipt is reuse evidence, not proof that later edits are visually correct.

Resources

• scripts/prepare_visual_qa_queue.py: batch plan/layout/editor-open gates and cache evaluation; its gate hash covers all three scripts.
• scripts/start_hancom_visual_qa.py: environment fingerprint and SHA-pinned direct opener.
• scripts/visual_qa_receipts.py: atomic receipt recording and validation.
• scripts/hancom_qa_orchestrator.py: resumable batch state, background preparation, foreground lease, review staging, and explicit recovery.
• references/workflow.md: commands, schemas, GUI budget, and portability notes.