HitKeep QA

Treat AGENTS.md as repository policy and the live hk QA catalog as workflow truth. Never reproduce the gate matrix, commands, tags, or tool versions in this skill or in a contribution plan.

Select

Use hk_qa_plan whenever it is callable. If it is absent or fails, report whether registration, startup, workspace routing, or task reload is blocking MCP and obtain explicit user approval before using an equivalent CLI action. After approval, discover the planning command through ./hk qa --help and request --output json.

• Use changed while iterating.
• Use complete before declaring contributor work complete; it runs the deepest locally appropriate gates for affected areas.
• Use pr only for exact unchanged CI parity.
• Use full when release risk, cloud-tagged behavior, container behavior, or the request explicitly requires exhaustive validation.

Before starting an expensive completion profile after source edits, run the smallest cheap hygiene selection from the same source-bound plan unless that unchanged source snapshot already has passing hygiene evidence. This preflight is not completion evidence; it prevents expensive shards from running against source already known to fail basic checks.

Honor planner escalation. Query hitkeep-dev://catalog/qa or the structured CLI catalog for current profiles and gate definitions rather than guessing or copying commands.

Use hk_run_status to observe the returned run and request bounded cursor-addressed run or gate logs. Use hk_run_cancel only for the intended exact observed active run.

Run and Observe

1. Inspect hk_context and known run status for equivalent active QA work before starting another.
2. Persist a source-bound plan with hk_qa_plan, then pass its required plan_id to hk_run_start. Use a structured CLI action with --detach --output json only after the MCP blocker has been reported and the user has approved fallback. Keep the returned workspace ID and run ID.
3. Poll hk_run_status rather than restarting a slow run or assuming client disconnect stopped it.
4. On failure, request the bounded run tail, then a bounded gate-specific view from hk_run_status. Open the complete local artifact only when that context is insufficient.
5. Fix the root cause and rerun the smallest relevant selection from the live catalog before rerunning the required profile.
6. Let all selected gates finish; one failure must not hide independent results. Cancel only the intended validated run.

Reuse a passing required-profile run only when its source snapshot is unchanged. A fallback approval resumes only the blocked plan or run; when that operation reaches a terminal state, report and stop unless the user explicitly requested broader implementation work.

QA source checks never rewrite files. When they report formatting or Go migration drift, route the explicit write through the developer CLI, review the changed paths, and then rerun the failed gate.

Completion Report

Report the workspace ID, profile, stable gate IDs, final run status, and any gates that could not run with the concrete reason. A green focused run does not replace required PR or exhaustive evidence. Keep passing output compact; retain run IDs and artifact paths instead of pasting logs.