skillspec progress — Record execution evidence for a run

The progress family of subcommands maintains the execution evidence ledger for a SkillSpec-guided run. All subcommands write to or read from <run-dir>/execution.jsonl, the append-only file that trace align uses to verify obligations. The key rule: use progress checkpoint --quiet for all routine successful evidence rows. It keeps the ledger exact without making the user watch a progress-command parade and without hand-authoring event files. Use progress record only as an escape hatch for failures, blockers, debugging, or explicit proof-detail requests that cannot be expressed with typed checkpoint flags.

`progress checkpoint`

Appends several routine successful progress and proof events to execution.jsonl in one atomic checkpoint. This is the preferred path for recording satisfied requirements, completed phases, fulfilled routes, answered elicitations, and attached evidence.

skillspec progress checkpoint <run-dir> \
  [--requirement-satisfied <phase>/<requirement>=<kind>:<ref>] \
  [--phase-completed <phase>=<kind>:<ref>] \
  [--route-fulfilled <id>=<kind>:<ref>] \
  [--route-check-completed <id>=<kind>:<ref>] \
  [--after-success-completed <id>=<kind>:<ref>] \
  [--obligation-satisfied <id>=<kind>:<ref>] \
  [--elicitation-answered <id>=<kind>:<ref>] \
  [--evidence-attached <kind>:<ref>] \
  [--checkpoint <label>] \
  [--quiet] \
  [--summary] \
  [--json]

All --requirement-satisfied, --phase-completed, --route-fulfilled, --route-check-completed, --after-success-completed, --obligation-satisfied, --elicitation-answered, and --evidence-attached flags are repeatable.

Options

Flag	Type	Default	Description
`<run-dir>`	path	(required)	Trace run directory containing `execution.jsonl`.
`--requirement-satisfied`	`PHASE/REQUIREMENT=KIND:REF`	(repeatable)	Record a `requirement_satisfied` event. `KIND` is the evidence kind (e.g. `command`, `file`, `trace`); `REF` is the evidence reference.
`--phase-completed`	`PHASE=KIND:REF`	(repeatable)	Record a `phase_completed` event for the named phase.
`--route-fulfilled`	`ID=KIND:REF`	(repeatable)	Record a `route_fulfilled` event for the named route id.
`--route-check-completed`	`ID=KIND:REF`	(repeatable)	Record a `route_check_completed` event for the named check id.
`--after-success-completed`	`ID=KIND:REF`	(repeatable)	Record an `after_success_completed` event for the named closure id.
`--obligation-satisfied`	`ID=KIND:REF`	(repeatable)	Record an `obligation_satisfied` event for the named obligation id.
`--elicitation-answered`	`ID=KIND:REF`	(repeatable)	Record an `elicitation_answered` event for the named elicitation id.
`--evidence-attached`	`KIND:REF`	(repeatable)	Record an `evidence_attached` event with no phase or requirement scope.
`--checkpoint`	string	(none)	Human-readable checkpoint label written to the batch report.
`--quiet`	flag	off	Suppress all output. Successful quiet checkpoints produce no stdout. Use this for normal agent execution.
`--summary`	flag	off	Print a compact summary instead of full event detail. Use for debugging or proof inspection only.
`--json`	flag	off	Emit the batch report as JSON.

Example

Record a satisfied requirement, completed phase, and fulfilled route in one checkpoint:

skillspec progress checkpoint .skillspec/traces/run-1712345678-12345 \
  --requirement-satisfied qa_and_proof/validate_spec=command:validate.log \
  --phase-completed qa_and_proof=trace:execution.jsonl \
  --route-fulfilled prove_skill_value=trace:execution.jsonl \
  --checkpoint "qa phase complete" \
  --quiet

`progress record`

Appends one structured event to <run-dir>/execution.jsonl. This is a low-level escape hatch for failures, blockers, debugging, or explicit proof-detail requests. For routine successful rows, use progress checkpoint --quiet.

skillspec progress record <run-dir> <event> [<phase>] [<requirement>] \
  [--id <id>] \
  [--status <status>] \
  [--evidence-kind <kind>] \
  [--evidence-ref <ref>] \
  [--source-skill <id>] \
  [--message <text>] \
  [--quiet] \
  [--json]

Options

Flag	Type	Default	Description
`<run-dir>`	path	(required)	Trace run directory.
`<event>`	event name	(required)	Event name. See the event table below.
`[phase]`	string	(none)	Phase id. Required when `<event>` is phase- or requirement-scoped.
`[requirement]`	string	(none)	Requirement id within the phase.
`--id`	string	(none)	Obligation, route, elicitation, or handoff id.
`--status`	string	(none)	Outcome status, e.g. `pass`, `fail`, `blocked`.
`--evidence-kind`	string	(none)	Kind of evidence artifact, e.g. `command`, `file`, `trace`.
`--evidence-ref`	string	(none)	Path, id, or reference for the evidence artifact.
`--source-skill`	string	(none)	Skill id that produced this event when recording cross-skill evidence.
`--message`	string	(none)	Free-text annotation.
`--quiet`	flag	off	Suppress output.
`--json`	flag	off	Echo the written event as JSON.

Example

Record a failed requirement with evidence:

skillspec progress record .skillspec/traces/run-1712345678-12345 \
  requirement-failed qa_and_proof validate_spec \
  --status fail \
  --evidence-kind command \
  --evidence-ref validate.log \
  --message "schema validation rejected two fields"

`progress stats`

Appends a stats_collected event with workspace and token metrics. Use this so quiet trace align can report measured consumption, savings, and economy when running --summary.

skillspec progress stats <run-dir> \
  [--workspace <name>] \
  [--workspace-stats-json <path>] \
  [--workspace-stats-report <path>] \
  [--total-tokens <n>] \
  [--context-tokens <n>] \
  [--query-result-tokens <n>] \
  [--response-tokens-cached <n>] \
  [--saved-tokens <n>] \
  [--reduction-percent <pct>] \
  [--agent-visible-tokens <n>] \
  [--artifact-tokens-preserved <n>] \
  [--avoided-tokens <n>] \
  [--metrics-source <source>] \
  [--phase <id>] \
  [--requirement <id>] \
  [--message <text>] \
  [--quiet] \
  [--json]

Options

Flag	Type	Default	Description
`<run-dir>`	path	(required)	Trace run directory.
`--workspace`	string	(none)	Workspace name to record alongside the stats.
`--workspace-stats-json`	path	(none)	Path to a JSON workspace stats file. Parsed for token fields.
`--workspace-stats-report`	path	(none)	Path to a plain-text workspace stats report. Parsed for token fields.
`--total-tokens`	integer	(none)	Total API request+response tokens.
`--context-tokens`	integer	(none)	One-time context-window tokens consumed during exploration.
`--query-result-tokens`	integer	(none)	Tokens in extracted query results.
`--response-tokens-cached`	integer	(none)	Cached response/source tokens before query reduction.
`--saved-tokens`	integer	(none)	Tokens saved by query reduction or cache reuse.
`--reduction-percent`	float	(none)	Percent reduction from cached/source tokens to query-result tokens.
`--agent-visible-tokens`	integer	(none)	Number of tokens visible in the agent context at this checkpoint.
`--artifact-tokens-preserved`	integer	(none)	Total token count of artifacts preserved outside the context window.
`--avoided-tokens`	integer	(none)	Tokens avoided by using SkillSpec instead of full-context execution. Defaults to `artifact_tokens_preserved - agent_visible_tokens` when both are supplied.
`--metrics-source`	string	(none)	Source label for the metrics, e.g. `estimated`, `measured`.
`--phase`	string	(none)	Phase id to associate with this stats event.
`--requirement`	string	(repeatable)	Requirement id(s) satisfied by recording this event. Requires `--phase`.
`--message`	string	(none)	Free-text annotation.
`--quiet`	flag	off	Suppress output. Use during normal agent execution.
`--json`	flag	off	Echo the written event as JSON.

Example

Record estimated direct-run token metrics quietly:

skillspec progress stats .skillspec/traces/run-1712345678-12345 \
  --agent-visible-tokens 190 \
  --artifact-tokens-preserved 96190 \
  --avoided-tokens 96000 \
  --metrics-source estimated \
  --quiet

`progress final-response`

Appends a final_response_sent event that proves the final answer included the required sections: result, evidence, alignment status, and token savings. Run this immediately before sending the final response to the user.

skillspec progress final-response <run-dir> \
  [--result] \
  [--evidence] \
  [--alignment] \
  [--token-savings] \
  [--phase <id>] \
  [--requirement <id>] \
  [--message <text>] \
  [--quiet] \
  [--json]

Options

Flag	Type	Default	Description
`<run-dir>`	path	(required)	Trace run directory.
`--result`	flag	off	Final response includes a result section.
`--evidence`	flag	off	Final response includes an evidence section.
`--alignment`	flag	off	Final response includes an alignment status or report path.
`--token-savings`	flag	off	Final response includes token math.
`--phase`	string	(none)	Phase id to associate with this event.
`--requirement`	string	(repeatable)	Requirement id(s) satisfied by recording this event. Requires `--phase`.
`--message`	string	(none)	Free-text annotation.
`--quiet`	flag	off	Suppress output. Use during normal agent execution.
`--json`	flag	off	Echo the written event as JSON.

Example

Record that the final response included all required sections:

skillspec progress final-response .skillspec/traces/run-1712345678-12345 \
  --result \
  --evidence \
  --alignment \
  --token-savings \
  --quiet

`progress show`

Reads the decision trace and execution.jsonl, computes a progress.json snapshot, and reports completed, current, blocked, and remaining phases. Use this as an internal gate check; do not surface it in normal execution unless details are needed for a blocker or failure.

skillspec progress show <path> \
  --run <run-dir> \
  [--quiet] \
  [--json]

Options

Flag	Type	Default	Description
`<path>`	path	(required)	Path to the `skill.spec.yml` file.
`--run`	directory path	(required)	Trace run directory whose `execution.jsonl` to evaluate.
`--quiet`	flag	off	Skip transcript output; still writes `progress.json` to the run directory.
`--json`	flag	off	Emit the progress report as JSON.

Example

skillspec progress show ./skill.spec.yml \
  --run .skillspec/traces/run-1712345678-12345 \
  --quiet

`progress batch`

Appends several structured progress and proof events from an existing JSONL or JSON array file to execution.jsonl. Use this only when a JSONL or JSON array proof artifact was already captured at a natural phase boundary — not to manufacture missing route, obligation, elicitation, or phase proof after alignment.

skillspec progress batch <run-dir> \
  --file <jsonl-or-json-array> \
  [--checkpoint <label>] \
  [--quiet] \
  [--summary] \
  [--json]

Options

Flag	Type	Default	Description
`<run-dir>`	path	(required)	Trace run directory.
`--file`	path	(required)	Path to a JSONL file or a JSON array file containing execution events. `--events` is a compatibility alias.
`--checkpoint`	string	(none)	Human-readable label for this batch.
`--quiet`	flag	off	Suppress output for successful batches.
`--summary`	flag	off	Print a compact summary. Use for debugging or proof inspection only.
`--json`	flag	off	Emit the batch report as JSON.

Example

skillspec progress batch .skillspec/traces/run-1712345678-12345 \
  --file .skillspec/traces/run-1712345678-12345/final-proof.jsonl \
  --checkpoint "checkpointing evidence" \
  --quiet

Event Reference

progress record and progress batch accept the following event values. Hyphens and underscores are both accepted (e.g. requirement-satisfied and requirement_satisfied are equivalent).

Event	Meaning
`phase-started`	A declared phase has begun.
`requirement-started`	Work began for a phase requirement.
`requirement-satisfied`	A phase requirement has structured proof.
`requirement-failed`	A phase requirement failed.
`stats-collected`	Workspace or token metrics were recorded. Prefer `progress stats --quiet`.
`obligation-satisfied`	A route, forbid, elicitation, or other obligation has explicit proof.
`route-fulfilled`	The selected route was fulfilled.
`route-check-completed`	A route-local check completed.
`after-success-completed`	A scheduled after-success closure completed.
`elicitation-answered`	A required elicitation was answered.
`elicitation-waived`	A required elicitation was explicitly waived.
`evidence-attached`	Extra evidence was attached to the run.
`handoff-started`	A declared handoff began.
`handoff-completed`	A declared handoff completed.
`phase-completed`	A declared phase completed.
`phase-blocked`	A declared phase cannot continue.
`final-response-sent`	The final answer was sent. Prefer `progress final-response --quiet`.

The events final_response_sent, forbidden_action, forbidden_action_observed, and forbid_violated are accepted by progress batch (which uses a broader allowlist) but are not valid for progress record. Use progress batch to append a pre-captured JSONL file containing those event types, or use the dedicated progress final-response subcommand for final-response proof.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec progress — Record execution evidence for a run

`progress checkpoint`

Options

Example

`progress record`

Options

Example

`progress stats`

Options

Example

`progress final-response`

Options

Example

`progress show`

Options

Example

`progress batch`

Options

Example

Event Reference

​progress checkpoint

​Options

​Example

​progress record

​Options

​Example

​progress stats

​Options

​Example

​progress final-response

​Options

​Example

​progress show

​Options

​Example

​progress batch

​Options

​Example

​Event Reference

`progress checkpoint`

Options

Example

`progress record`

Options

Example

`progress stats`

Options

Example

`progress final-response`

Options

Example

`progress show`

Options

Example

`progress batch`

Options

Example

Event Reference