skillspec trace — Compact and align decision traces

The trace subcommands operate on the run directories created by decide, act, and run-loop when --trace-dir is supplied. Each run directory holds the append-only decision event files from a single routing decision, plus the execution evidence accumulated by progress subcommands. trace align is the primary verification step: it replays the decision trace against the current spec and checks structured execution evidence for every active obligation. trace compact rebuilds the summarized JSONL files from raw event files, which is useful after a run completes or when the run directory was written by multiple incremental commands.

Always use --quiet when running trace align during normal agent execution. Without --quiet, the command emits a full transcript of every check result, which is expensive in context tokens and not needed for routine proof. Quiet mode still writes alignment.json and the proof digest to the run directory and still exits non-zero on failures.

Run Directory Structure

Every trace run directory has the following layout:

.skillspec/traces/run-<timestamp>-<pid>/
├── events/                  # Append-only individual decision event files
│   ├── 000001.input_received.json
│   ├── 000002.route_selected.json
│   └── ...
├── trace.jsonl              # Compacted event stream (rebuilt by trace compact)
├── summary.json             # Compacted summary with event counts and fingerprints
├── execution.jsonl          # Execution evidence ledger (written by progress subcommands)
├── alignment.json           # Alignment report (written by trace align)
└── proof-digest.json        # Proof digest (written by trace align --proof-digest)

The events/ directory is the source of truth. trace.jsonl and summary.json are derived artifacts rebuilt by trace compact. execution.jsonl is separate from the decision trace — it records what the agent actually did during execution.

`trace align`

Replays the decision trace against the current spec and checks the structured execution evidence in execution.jsonl for all active obligations. Produces alignment.json in the run directory and optionally a proof-digest.json that lists missing proof rows grouped by obligation kind.

skillspec trace align <path> \
  --decision-trace <run-dir> \
  [--execution-trace <jsonl>]... \
  [--quiet] \
  [--summary] \
  [--proof-digest <path>] \
  [--json]

Options

Flag	Type	Default	Description
`<path>`	path	(required)	Path to the `skill.spec.yml` file.
`--decision-trace`	directory path	(required)	Run directory containing the decision trace events.
`--execution-trace`	path	(repeatable)	Path to an execution evidence JSONL file, typically `<run-dir>/execution.jsonl`. Repeat to supply multiple ledgers. Omit to run decision-only alignment.
`--quiet`	flag	off	Write `alignment.json` and the proof digest without producing transcript output. Preserves exit status. Use during normal agent execution.
`--summary`	flag	off	Print a compact alignment summary instead of the full check transcript. Use for debugging or explicit proof inspection only.
`--proof-digest`	path	(none)	Path where the proof digest JSON should be written. The digest groups missing proof rows by obligation kind with recommended event names and required fields.
`--json`	flag	off	Emit the alignment report as JSON and print paths to written files.

How alignment works

trace align runs two layers of checks:

Decision replay — Re-runs the current spec on the captured input hash and compares the result (route selection, matched rules, forbids, elicitations, after-success) against what the trace recorded. A mismatch means spec drift or a trace/spec mismatch.
Execution proof — Derives active obligations from the selected route and matched rules (route fulfillment, route checks, forbid non-violations, elicitation answers, after-success completions), then checks execution.jsonl for structured evidence that each obligation was met.

The overall status is one of:

pass — decision replay passed and all execution obligations have structured proof.
unproven — decision replay passed or had no failures, but one or more obligations lack proof.
fail — a deterministic decision check failed (spec drift) or execution evidence actively contradicts an obligation.

Examples

Quiet alignment during normal execution (recommended):

skillspec trace align ./skill.spec.yml \
  --decision-trace .skillspec/traces/run-1712345678-12345 \
  --execution-trace .skillspec/traces/run-1712345678-12345/execution.jsonl \
  --proof-digest .skillspec/traces/run-1712345678-12345/proof-digest.json \
  --quiet

Full JSON alignment report for scripting or CI:

skillspec trace align ./skill.spec.yml \
  --decision-trace .skillspec/traces/run-1712345678-12345 \
  --execution-trace .skillspec/traces/run-1712345678-12345/execution.jsonl \
  --json

Compact summary for manual debugging:

skillspec trace align ./skill.spec.yml \
  --decision-trace .skillspec/traces/run-1712345678-12345 \
  --execution-trace .skillspec/traces/run-1712345678-12345/execution.jsonl \
  --summary

Output (`--json`)

{
  "schema": "skillspec.align/v0",
  "ok": true,
  "status": "pass",
  "summary": {
    "scope": "decision_and_execution_trace",
    "decision_alignment": "pass",
    "execution_alignment": "pass",
    "conclusion": "decision alignment passed and supplied execution evidence proves every active obligation",
    "selected_route": "port_skill",
    "matched_rules": ["porting_tasks_use_port_route"],
    "decision_checks": { "total": 8, "pass": 8, "fail": 0, "unproven": 0 },
    "execution_obligations": { "total": 3, "pass": 3, "fail": 0, "unproven": 0 },
    "evidence_gaps": [],
    "phase_requirement_gaps": [],
    "completion": {
      "decision_replay": "pass",
      "phase_order": "pass",
      "requirements": "2/2 proven",
      "missing_proof": ["none"],
      "forbidden_actions": "no violations recorded",
      "alignment": "pass"
    },
    "tokens": { ... }
  },
  "spec": "./skill.spec.yml",
  "decision_trace": ".skillspec/traces/run-1712345678-12345",
  "execution_traces": [".skillspec/traces/run-1712345678-12345/execution.jsonl"],
  "checks": [...],
  "obligations": [...],
  "proof_rows": [...]
}

Field	Description
`status`	Overall result: `pass`, `unproven`, or `fail`.
`summary.decision_alignment`	Result of the decision replay layer.
`summary.execution_alignment`	Result of the execution proof layer, or `not_evaluated` if no execution trace was supplied.
`summary.evidence_gaps`	List of unproven obligations with the needed evidence type and recommended event.
`summary.phase_requirement_gaps`	Phase requirements with missing or failed proof rows.
`checks`	Individual decision replay check results.
`obligations`	Individual execution obligation results.
`proof_rows`	Per-obligation table of expected vs. observed evidence and status.

`trace compact`

Rebuilds trace.jsonl and summary.json from the append-only event files in <run-dir>/events/. Run this after a sequence of incremental trace writes, or when the compacted files are stale or missing.

skillspec trace compact <run-dir>

Options

Flag	Type	Default	Description
`<run-dir>`	directory path	(required)	Trace run directory containing an `events/` subdirectory.

trace compact always emits JSON reporting the run id, file paths, and event count.

Example

Compact a run directory after a multi-step guided run:

skillspec trace compact .skillspec/traces/run-1712345678-12345

Example output:

{
  "run_id": "run-1712345678-12345",
  "run_dir": ".skillspec/traces/run-1712345678-12345",
  "event_count": 7,
  "trace_jsonl": ".skillspec/traces/run-1712345678-12345/trace.jsonl",
  "summary_json": ".skillspec/traces/run-1712345678-12345/summary.json"
}

trace align automatically compacts the run directory before reading envelopes, so a manual trace compact call is not strictly required before alignment. It is useful for inspecting the run directory, sharing traces, or rebuilding after the events/ directory was populated by external tooling.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec trace — Compact and align decision traces

Run Directory Structure

`trace align`

Options

How alignment works

Examples

Output (`--json`)

`trace compact`

Options

Example

​Run Directory Structure

​trace align

​Options

​How alignment works

​Examples

​Output (--json)

​trace compact

​Options

​Example

Run Directory Structure

`trace align`

Options

How alignment works

Examples

Output (`--json`)

`trace compact`

Options

Example