wndi1130-dot/hancom-visual-qa-accelerator

Hancom Visual QA Accelerator

Use this skill to compress repeated HWPX visual QA without weakening the final visual gate. It does not create or edit documents; pair it with the local HWPX/Hancom skill that owns authoring and GUI review.

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 after all non-GUI work is complete, and only for visualQueue items.
• 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.
• If an Hwp process already exists, preserve the user's windows and use the host Hancom skill's isolated Launcher fallback.

Workflow

1. Read references/workflow.md.
2. Run scripts/start_hancom_visual_qa.py environment through the same host/sandbox/permission boundary that will run open, and retain its environment fingerprint.
3. Run scripts/prepare_visual_qa_queue.py on a manifest containing each HWPX and its authoring plan. Add --require-plan when every item must have a plan.
4. Stop on rejected items. Open only the resulting visualQueue.
5. When no Hwp process exists, call scripts/start_hancom_visual_qa.py open with the queued SHA and environment fingerprint. Confirm the returned windowTitle, activate that exact window immediately before capture, scan for exact owned warning modals, inspect all required pages, and take only the final evidence image(s).
6. Record only pending live reviews with the observed environment fingerprint. The recorder binds every evidence image by SHA-256; then validate the store with --require-evidence.
7. For later non-submission runs only, opt in with --allow-receipt-inheritance. Omit it by default. Use --submission for final/submission review.

Fail-closed behavior

• A changed file after queue creation must fail the opener or receipt recorder by SHA mismatch.
• Missing or expired evidence returns the document to live review.
• 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.
• references/workflow.md: commands, schemas, GUI budget, and portability notes.