ticket-execution

name	ticket-execution
description	Follow the required ticket lifecycle for this repo. Use when an agent is advancing a ticket through planning, review, implementation, QA, deterministic smoke testing, and closeout and needs the repo-specific stage rules.

Ticket Execution

Before enforcing the lifecycle, call skill_ping with skill_id: "ticket-execution" and scope: "project".

Required order:

1. ticket lookup
2. planning
3. plan review
4. implementation
5. code review
6. security review when relevant
7. QA
8. deterministic smoke test
9. handoff and closeout

Core rules:

• resolve the ticket through ticket_lookup first and read transition_guidance before calling ticket_update
• if ticket_lookup.bootstrap.status is not ready, stop normal lifecycle routing, run environment_bootstrap, then rerun ticket_lookup before any ticket_update
• if bootstrap still is not ready after that rerun, return a blocker; do not improvise raw shell installation or lifecycle workarounds
• if repeated bootstrap proofs show the same command trace but it still omits the dependency-group or extra flags the repo layout requires, stop retrying and route a managed bootstrap defect instead of bypassing environment_bootstrap
• the team leader owns ticket_claim and ticket_release; the team leader claims and releases write leases; specialists work inside the already-active ticket lease and return a blocker if no lease exists
• use ticket_update for stage movement; do not probe alternate stage or status values to see what passes
• when ticket_update returns the same lifecycle error twice, stop and return a blocker instead of inventing a workaround
• when ticket_lookup.transition_guidance.current_state_blocker reports stale-stage drift and recommended_ticket_update is present, execute that exact update first; do not jump directly to a later closeout transition from the stale manifest stage
• stage artifacts belong to the specialist for that stage:
  • planner writes planning
  • implementer writes implementation
  • reviewers write review
  • QA writes qa
  • smoke_test is the only legal producer of smoke-test
• if the ticket acceptance criteria already define executable smoke commands, treat those commands as canonical smoke scope; let smoke_test infer them or pass the exact canonical command instead of improvising broader full-suite smoke or ad hoc narrower test_paths
• if execution or validation cannot run, return a blocker or open risk; do not convert expected results into PASS evidence
• do not claim that a command ran unless its output is present in the canonical artifact
• slash commands are human entrypoints, not internal autonomous workflow tools
• if an external orchestration service groups ticket work into a downstream phase, end that phase with an explicit PR or reviewable diff instead of treating ticket progression as an implicit merge permission
• phase grouping, PR numbers, reviewer assignment, and merge policy are orchestration-owned overlay state, not fields in tickets/manifest.json or .opencode/state/workflow-state.json
• if review rejection, stage-gate evidence, or restart guidance suggests managed workflow drift instead of ordinary source defects, request scafforge-audit rather than looping blind retries

Transition contract:

• planning:
  • required proof before exit: a registered planning artifact
  • next legal transition: ticket_update stage=plan_review
• plan_review:
  • required proof before exit: the plan exists and approval is recorded in workflow state while the ticket remains in plan_review
  • first legal approval step: ticket_update stage=plan_review approved_plan=true
  • do not combine initial approval and the implementation transition in one call
  • next legal transition after approval: ticket_update stage=implementation
• implementation:
  • required proof before exit: a registered implementation artifact with compile, syntax, import, or test output
  • next legal transition: ticket_update stage=review
• review:
  • required proof before exit: at least one registered review artifact
  • next legal transition: ticket_update stage=qa
  • latest review verdict must be PASS or APPROVED; FAIL, REJECT, BLOCKED, or an unclear verdict must route back to implementation or manual inspection before QA
  • setup/bootstrap review artifacts must include direct command output for the required toolchain checks, including Java version output from java -version or javac -version, Android build-tool output from aapt2 version, d8 --version, and zipalign usage/version commands, debug keystore output, export-template output, and verbose Godot headless load output when project.godot exists. Environment variables, ls-only file existence, permission-policy excuses, indirect proof through Godot, or deferred validation claims are not enough.
  • setup/bootstrap review artifacts must not approve validation commands that are only "identified", "not yet applicable", or deferred to later tickets unless that deferral is explicit in the canonical ticket acceptance.
• qa:
  • required proof before exit: a registered QA artifact with raw command output
  • next legal transition: ticket_update stage=smoke-test
  • latest QA verdict must be PASS or APPROVED; FAIL, REJECT, BLOCKED, or an unclear verdict must route back to implementation or manual inspection before smoke-test
  • visual-proof repos require structured visual proof in the QA artifact. visual_proof_status: PASS must list existing repo-local screenshot, render, capture, or video files in visual_proof_evidence; /tmp paths and other files outside the repo do not count as final evidence. Non-final visual tickets may use visual_proof_status: DEFERRED only when an open FINISH-VALIDATE-001 owns runtime capture and the QA artifact includes executable headless/build evidence plus reviewed surfaces and no rubric blockers.
  • final visual tickets must also include visual_proof_screen_analysis and visual_proof_visible_content; the visible-content field must name concrete readable labels, controls, game objects, or primary content visible in the evidence. Android/emulator final proof must include visual_proof_post_overlay: true after system overlays are dismissed, and must not pass with overlay, launcher, black, gray, uniform, near-blank, clipped, or unreadable screenshots.
  • final finish-validation tickets must include visual_proof_asset_content when the finish contract requires ship-ready visuals, authored content, cartoon/picture/sprite/object/environment assets, or no-placeholder visual output. Box-only, label-only, or colored-rectangle UI proof is a blocker.
  • final finish-validation tickets must include audio_runtime_proof when the finish contract requires voice, music, spoken prompts, sound effects, or feedback audio. File counts, non-empty audio files, code references, and wiring evidence alone are proxy evidence and must not pass.
  • final finish-validation tickets must include gameplay_proof when the finish contract requires a game, playable loop, learning round, progression path, reward, mission, wave, or similar state change. Source inspection and button-handler existence alone are proxy evidence and must not pass.
• smoke-test:
  • required proof before exit: a current smoke-test artifact produced by smoke_test
  • next legal transition: ticket_update stage=closeout status=done
  • DEFERRED smoke test: if the acceptance commands require functionality from another ticket that is not yet done, use smoke_test(smoke_deferred_until=[ticket_ids]) only when every deferred ticket can be claimed before the current ticket reaches done. Never defer to a ticket that directly or transitively depends on the current ticket; that is a circular closeout blocker and must be fixed in the current ticket or moved to a separate prerequisite ticket. The ticket stays in smoke-test stage. Do NOT use command_override to scope-narrow around missing functionality. Do NOT close the ticket while smoke is DEFERRED. Re-run smoke_test for this ticket after all deferred_until tickets reach done status.
  • command_override scope constraint: command_override is rejected if the ticket's acceptance criteria specify commands whose executables are not covered by the override. This is a configuration error, not a test failure. Resolution: either include the required executables in command_override, or use smoke_deferred_until only when the missing functionality belongs to a claimable ticket that does not depend on the current ticket.
• closeout:
  • required proof before exit: a passing smoke-test artifact
  • expected final state: status=done

Failure recovery paths:

• Review FAIL, REJECT, or BLOCKED: route back to implementation, address the review findings, then return to review
• Review verdict unclear: stop progression and inspect the current review artifact manually before any ticket_update
• QA FAIL, REJECT, or BLOCKED: route back to implementation, fix the QA findings, then return through review and qa
• QA verdict unclear: stop progression and inspect the current QA artifact manually before any ticket_update
• Smoke-test FAIL with failure_classification: test_failure: route back to implementation and fix the product issue
• Smoke-test FAIL with failure_classification: missing_executable or host-surface runtime_setup: run environment_bootstrap and treat the failure as an environment blocker first
• Smoke-test FAIL with failure_classification: syntax_error or configuration_error: treat the smoke tool surface as the blocker; do not route that failure straight to implementation
• Smoke-test DEFERRED (passed: null, deferred: true): the smoke test is explicitly waiting on other tickets. Continue working on other ready tickets in parallel. Re-run smoke_test for this ticket after all deferred_until tickets close. Do not treat this as an error or block all other work.
• smoke_test rejects smoke_deferred_until as a circular closeout blocker: route the current ticket back to implementation and fix the missing surface in the current ticket, even if the approved plan previously claimed the gap was deferred. Re-run review, QA, and smoke-test after the implementation fix.
• repeated downstream review rejection caused by workflow contradiction, missing legal-next-move guidance, or repo/package boundary confusion: stop phase retry churn and request scafforge-audit

Remediation ticket closeout:

• when a remediation ticket carries finding_source, treat it as a remediation or reverification ticket
• identify the original finding code before closeout and rerun the command or check that originally produced that finding
• include the rerun output and whether the original error signature is gone in the closeout evidence
• if the finding-specific rerun still fails, do not close the ticket; route back to implementation with the fresh command output
• if the finding-specific rerun passes, also confirm adjacent quality gates that previously passed still remain green
• for process-remediation or reverification tickets, keep smoke-test scope limited to checks that are valid at the repo's current backlog state; do not broaden smoke into a product boot command that is expected to fail because prerequisite feature tickets are still unfinished

Verification state semantics:

• suspect: normal in-flight state, or a ticket returned to implementation after new findings
• smoke_verified: a passing smoke-test artifact exists, but closeout has not completed yet
• trusted: closeout completed with current passing evidence
• reverified: historical completion was re-proven after drift or process-version change
• invalidated: accepted historical completion was disproven by later defect intake

Parallel rules:

• keep each ticket sequential through its own stage order
• only advance tickets in parallel when parallel_safe is true, overlap_risk is low, and dependencies are already satisfied

Process-change rules:

• if pending_process_verification is true and ticket_lookup.process_verification.clearable_now is true, clear the stale flag immediately via the recommended ticket_update(..., pending_process_verification: false) on the current writable ticket before any other lifecycle or split-parent action
• if pending_process_verification is true and ticket_lookup.process_verification.clearable_now is not true, verify affected done tickets before trusting their completion
• if repair_follow_on.outcome is managed_blocked, stop ordinary lifecycle routing and surface the canonical blocker before continuing ticket work
• repair_follow_on.outcome == source_follow_up does not by itself block the active open ticket from continuing
• after repo-local repair, resume ordinary lifecycle work only after current revalidation and refreshed restart surfaces expose one legal next move again
• migration follow-up tickets must come from backlog-verifier proof through ticket_create, not raw manifest edits
• use ticket_create(source_mode=split_scope) when an open or reopened parent ticket needs planned child decomposition
• if a split parent still lacks its own planning artifact or recorded plan approval, keep the parent foregrounded until that setup is complete before activating a parallel child lane
• use ticket_reconcile when evidence proves an existing follow-up graph is stale or contradictory
• when ticket_reconcile is superseding or relinking an open split_scope child from the currently claimed parent ticket, the parent lease is the authoritative write lease; do not try to claim both tickets in sequential mode
• previously completed tickets are not fully trusted again until backlog verification says so
• when post-completion defect intake invalidates the ticket's accepted contract, the team leader must refresh or re-affirm the stale canonical acceptance criteria and/or summary through ticket_update(acceptance=[...], summary="...") before review, QA, smoke-test, closeout, or handoff can be treated as truthful
• package-defect wait states such as package-change-pending belong to external orchestration, not to canonical repo workflow state

Bootstrap gate:

• bootstrap readiness is a pre-lifecycle execution gate for every validation-heavy stage
• when bootstrap is missing, failed, or stale, the next required action is environment_bootstrap, not a stage transition or non-Wave-0 write claim
• only Wave 0 setup work may claim a write-capable lease before bootstrap is ready
• after bootstrap succeeds, rerun ticket_lookup and follow its refreshed transition_guidance