long-run-harness-execution

name	long-run-harness-execution
description	Use when running multi-hour or multi-session agent workflows that require planner-generator-evaluator orchestration, resumable artifacts, and optimized tool selection.

Long-Run Harness Execution

Use this skill to execute long-running autonomous work with explicit contracts, independent evaluation, and resumable progress.

Bundled Resources

Load these resources before running orchestration:

Resource	Purpose
references/artifact-schema.md	Required fields and structure for run artifacts
references/checkpoint-recovery.md	Resume and blocked-state recovery policy
references/tool-selection-guide.md	Tier escalation decision guidance and logging
references/execution-phase-contract.md	Phase 0-6 fail-closed execution contract and recurring 0R checkpoints
templates/run-manifest-template.md	Seed manifest template
templates/backlog-template.md	Seed backlog template
templates/sprint-contract-template.md	Seed sprint contract template
templates/heartbeat-template.md	Seed heartbeat template
templates/resume-token-template.md	Seed resume token template
scripts/envelope_check.py	Deterministic required-field check for request/return envelopes

When To Use

• tasks are expected to run across long sessions
• scope is too large for single-pass implementation
• quality must be validated by an independent evaluator
• resumable state and deterministic handoff are required

Do not use this skill for small one-shot tasks.

Core Architecture

• coordinator orchestrates run lifecycle and escalation
• planner expands objectives into backlog and sprint contracts
• generator implements one sprint contract at a time
• evaluator validates independently and can fail the sprint
• coordinator mediates all planner/generator/evaluator handoffs

Tool Selection Optimization

Use the minimum-cost tool that can provide sufficient evidence.

Tier 0

• local read and search for repository facts and code patterns

Tier 1

• context7 for framework behavior uncertainty
• brave-search for external standards and prior art

Tier 2

• execute for deterministic checks and reproducible validation

Tier 3

• playwright for interaction verification only when acceptance criteria require it

Escalate tool tier only when prior tier evidence is insufficient, and record why.

Required Artifacts

• run-manifest.md
  • objective, constraints, acceptance criteria, stop conditions, budget limits
• backlog.md
  • prioritized items with dependencies and gate mapping
• sprint-contract.md
  • scope, done criteria, verification criteria for current sprint
• heartbeat.md
  • progress, blockers, next action, budget usage
• resume-token.md
  • last accepted sprint, unresolved defects, deterministic next step

All required artifact fields are valid only when present and non-empty.

Use the templates in templates/ as the default artifact shape.

Handoff Contract

Request Envelope

task_id: string
parent_task_id: string | null
caller_agent: string
target_agent: string
objective: string
constraints:
  - string
success_criteria:
  - string
input_context_ref:
  - path-or-artifact
timeout_s: number
max_turns: number
objective_signature: string

Return Envelope

status: done | blocked | needs-human | failed
sprint_state: accepted | failed | cancelled | needs-human | null
summary: string
artifacts:
  - path-or-artifact
failure_reason: string | null
next_agent: string | null
proof_refs:
  - path-or-command
gate_scores:
  functionality: number
  coverage: number
  regression: number
  evidence: number
overall_gate_result: pass | conditional | fail
defect_count: number
evaluator_independence_claim:
  basis: string
  potential_conflicts:
    - string
attempt_index: number
max_fix_attempts: number

Status Semantics

• status is transport state for envelope routing
• sprint_state is coordinator verdict for run progression
• done: all criteria met with proof
• blocked: dependency or proof gap prevents completion
• needs-human: decision or credential required from user
• failed: work completed but criteria not met

Evaluator scoring thresholds:

• pass: all gate scores >= 0.85 and no unresolved critical defect
• conditional: all gate scores >= 0.70, no critical defect, and <=2 non-critical defects
• fail: any gate score < 0.70 or any unresolved critical defect

Gate consistency rules:

• overall_gate_result must match gate_scores and defect_count
• mismatched gate payloads are treated as failed and returned for correction
• non-empty evaluator_independence_claim.potential_conflicts requires needs-human escalation

Retry and Escalation

1. enforce max_fix_attempts per sprint (default 2, hard max 3)
2. retry only while attempt_index < max_fix_attempts
3. if attempt_index >= max_fix_attempts, force sprint state to failed
4. escalate to user only for true human-only decisions or evaluator conflicts
5. stop run if budget, safety, or quality bounds are exceeded

Checkpoint Discipline

• use fail-closed checkpoints
• do not claim success without explicit proof
• use blocked state when proof is missing
• carry unresolved blockers into next-step guidance
• refresh heartbeat after each evaluator verdict
• refresh resume-token after each accepted sprint and before any context reset
• after each meaningful accepted sprint, provide concise closure, validation status, and one short next-step question
• wait for user confirmation before broadening scope beyond current sprint boundaries
• ask before dependency additions, destructive operations, or broad validation outside sprint criteria

Expansion Risk Tiers

Ask before expansion using tiered boundaries:

Tier	Trigger	Confirmation Requirement
LOW	Within approved sprint contract and touched-file verification scope	Continue at normal checkpoint cadence
MEDIUM	Additional modules or tests outside sprint contract	Ask one short next-step question and wait for explicit confirmation
HIGH	Architecture/public contract changes, dependencies, destructive operations, or broad validation	Ask before expansion and require explicit user confirmation

Verification Checklist

1. contracts are present and complete
2. status vocabulary is consistent
3. evaluator gate decision is explicit
4. heartbeat and resume-token reflect current state
5. tool tier escalations are justified

Quick deterministic checks:

• python scripts/envelope_check.py request <request_json>
• python scripts/envelope_check.py return <return_json>

Recommended Pairings

• workflow-governor for workflow-surface hygiene before or after rollout
• validate-skills for new skill validation
• subagent-orchestration-contracts for envelope consistency across agent surfaces
• use the bundled references and templates before first sprint dispatch