Fieldheld Recorder

A stdlib-only CLI that turns an autonomous coding run into a reviewable, replayable evidence bundle: intent, diff, command log, verification, reviewer checklist, and bounded rollback. Built on one principle -- the doer never attests to its own success, so verification stays independent of the agent.

The bundled synthetic sample runs with no third-party dependencies, no network access, and no provider account -- everything works end-to-end on a fresh clone. (The optional pr-review command fetches public PR metadata via your local gh CLI; nothing else touches the network.)

It turns an agent-style run into an evidence bundle:

• what the run intended to do
• what inputs it used
• what commands or modeled actions happened
• what changed
• what verification passed or failed
• what a reviewer should inspect
• what can be rolled back

This first candidate is synthetic-only. It records a modeled coding-agent-style run against a tiny calculator fixture and emits public-safe sample artifacts. It does not wrap live agents or provider tools.

If You Only Have 60 Seconds

Fieldheld Recorder answers one review question:

What did this autonomous run intend, what changed, what evidence was produced,
what passed, what should a reviewer inspect, and what rollback is actually
bounded?

Run the sample:

python3 -m fieldheld_recorder.sample
python3 -m fieldheld_recorder.verify_sample
python3 -m fieldheld_recorder verify-sample-determinism

Then open:

less samples/fieldheld-sample-run/review_packet.md
less samples/fieldheld-sample-run/evidence_packet.md

Those two files are the fastest way to understand the public artifact.

If you are reviewing the contract, start with docs/CRITIQUE_REQUEST.md. It narrows the ask to evidence-gate failures and missing review fields.

If you only want to review the GitHub PR workflow, use docs/PR_REVIEW_CRITIQUE_REQUEST.md. The fastest side-by-side path is docs/PR_REVIEW_FIXTURE_MATRIX.md.

For the fastest artifact path, use docs/REVIEWER_PACKET_INDEX.md.

For the core technical argument, read docs/PASSING_TESTS_IS_NOT_ENOUGH.md.

If you are comparing this to traces or observability tools, read docs/TRACE_VS_EVIDENCE.md.

Artifact Map

Fieldheld Recorder is not trying to replace traces, tests, or diffs. It ties them together into a reviewer-facing bundle:

flowchart LR
    A[Run intent] --> B[Modeled actions]
    B --> C[Diff]
    B --> D[Command log]
    C --> E[Verification report]
    D --> E
    E --> F[Evidence packet]
    C --> F
    F --> G[Review packet]
    H[Artifact manifest] --> F
    H --> G
    I[Rollback notes] --> G

Loading

The important output is not one file. It is the relationship between intent, actions, artifacts, verification, review, and rollback boundaries.

Demo

Watch the short synthetic demo:

Fieldheld Recorder: Evidence Bundles for Governable Autonomy

The video shows the sample generator, verifier, evidence packet, review packet, and run record. It is a public-safe synthetic demo, not a live agent adapter.

Quick Start

Run the sample without installing anything:

python3 -m fieldheld_recorder.sample
python3 -m fieldheld_recorder.verify_sample

This rewrites samples/ deterministically. In module mode, the verifier prints a JSON report. Success is indicated by:

{
  "passed": true
}

Or install the local CLI:

python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/fieldheld-recorder run-sample
.venv/bin/fieldheld-recorder verify-sample

Expected installed-CLI verifier result:

verified 245 checks

What the verdict looks like

The accepted sample run records a real, inspectable verdict. Trimmed from samples/fieldheld-sample-run/:

# run_record.json
run_id      : fieldheld-sample-run
intent      : Record a bounded synthetic coding-agent-style run with reviewable evidence.
adapter     : synthetic_sample
provenance  : synthetic_sample
final_status: accepted

# review_packet.md (Decision section)
- Final status: accepted
- Reviewer action: Accept the run after inspecting the diff, verification, and policy gate.
- Provider calls executed: false
- Effect boundary: file_scoped_synthetic
- Rollback scope: recorded_git_diff_only

The rejected, escalated, blocked, and vague samples carry the same shape with a different verdict, so a reviewer can see why trust was or was not granted.

See QUICKSTART.md for the shortest complete walkthrough.

GitHub PR Review Bundle

Generate a public-safe review bundle for a GitHub pull request using the local GitHub CLI:

fieldheld-recorder pr-review --repo camirian/fieldheld-recorder --pr 19
fieldheld-recorder verify-pr-review --bundle-dir fieldheld-pr-review
fieldheld-recorder inspect-pr-review --bundle-dir fieldheld-pr-review
fieldheld-recorder verify-review-outcome --bundle-dir fieldheld-pr-review

This writes:

fieldheld-pr-review/
  artifact_manifest.json
  changed_files.json
  commands.log
  file_diffs.json
  pr_metadata.json
  review_outcome.json
  review_request.md
  reviewer_packet.md
  risk_summary.json
  run_record.json
  status_checks.json

The first slice uses public PR metadata only. It does not read private files, fetch secrets, or claim production approval.

verify-pr-review checks the generated bundle contract, manifest hashes, bounded diff limits, status-check consistency, and reviewer-packet sections. It does not approve the pull request.

inspect-pr-review prints the bundle status, risk reasons, check summary, diff coverage, files to open next, and the reviewer question without dumping the raw JSON. If the bundle is missing, malformed, or out of sync with its manifest, it also prints repair hints before the failed verifier checks.

verify-review-outcome validates a filled review_outcome.json worksheet. It allows the worksheet's manifest hash to drift after review, but the rest of the bundle must still verify.

It also surfaces PR-specific review traps such as missing status checks, vague intent, review-required decisions, high-risk file classes, large change sets, incomplete changed-file metadata, incomplete diff context, and non-successful check conclusions. See docs/GITHUB_PR_REVIEW_BUNDLE.md. For the artifact and decision contract, see docs/PR_REVIEW_CONTRACT_V0_2.md.

Agent Run Receipt

The agent-run receipt fixture scores one synthetic coding run as a review aid:

python3 -m fieldheld_recorder score-agent-run samples/agent-run-receipts/agent-run-receipt.codex.json
python3 -m fieldheld_recorder verify-agent-run-receipts

Tracked examples cover a verified run, an unverified run, and a no-op run. The scores are deterministic, token and cost fields are static estimates, prompt bodies are excluded by default, and unverified output fails closed instead of being promoted to success. The receipt is not a billing ledger, provider usage report, benchmark, telemetry product, model comparison, or compliance score.

Fleet Triage

Triage many recent agent runs at once -- "which of last night's runs do I actually need to look at?" Fleet scans Claude Code session transcripts, scores each run by a deterministic suspicion signal (changed code but ran no tests, did not end cleanly, large surface, edited test files), and sorts the most suspicious first:

fieldheld-recorder fleet --since-hours 24
fieldheld-recorder fleet --redact          # mask repo/branch/intent for sharing
fieldheld-recorder fleet --json            # raw JSON instead of the board

For every suspect run, the board prints a paste-ready verify-run command with the run's repository path already filled in:

verify: fieldheld-recorder verify-run --repo /path/to/repo --base <PASTE_PRE_RUN_REF> --test-cmd '<PASTE_TEST_CMD>'

Fill in the pre-run base ref and your test command to get the independent verdict. Fleet deliberately does not guess the base ref or test command from the transcript -- inventing them would fabricate a verdict, and the whole point is that the agent never attests to its own success. Fleet is triage, not proof; pair the suspicious few with verify-run for the hard verdict.

Fleet is read-only and stdlib-only. It scans ~/.claude/projects by default; --redact masks the repository path, branch, and intent so the board can be shared safely.

Release Boundary Check

Before any public upload, scan the extracted source candidate rather than only the working tree:

python3 -m fieldheld_recorder.release_boundary /path/to/extracted-source-candidate
fieldheld-recorder verify-release-boundary --path /path/to/extracted-source-candidate

The checker is read-only. It fails on local caches, build outputs, local environment files, seller/admin material, private planning or local report material, key-shaped access material, binary artifacts, and public claims that exceed the current synthetic/local boundary. It does not publish or package anything.

For the current public claim boundary, see docs/PUBLIC_CLAIM_AUDIT.md.

What To Open First

Generated examples are written under:

samples/
  summary.json
  adversarial-corpus.json
  sample-target-repo/
  fieldheld-pr-review-adversarial/
  fieldheld-pr-review-low-risk-docs/
  fieldheld-pr-review-sample/
  fieldheld-pr-review-self-demo/
  fieldheld-sample-run/
  fieldheld-sample-run-rejected/
  fieldheld-sample-run-escalated/
  fieldheld-sample-run-blocked/
  fieldheld-sample-run-vague/
  fieldheld-sample-run-live-envelope/

Start with these files:

less samples/summary.json
less samples/fieldheld-sample-run/evidence_packet.md
less samples/fieldheld-sample-run/review_packet.md
less samples/fieldheld-sample-run/run_record.json
less samples/fieldheld-sample-run/artifact_manifest.json
less samples/fieldheld-sample-run/git.diff
less samples/fieldheld-pr-review-sample/reviewer_packet.md

The accepted sample passes verification and policy. The rejected sample fails verification. The escalated, blocked, vague, and live-envelope samples show that verification passing is not enough when a policy gate requires human review or blocks trust.

The adversarial corpus names the synthetic hard-negative traps covered by the public sample: verification failure, policy-sensitive change, forbidden effect, rollback overclaim, verification overtrust, vague intent, unrelated diffs, weak provenance, and stale evidence.

The PR-review sample under samples/fieldheld-pr-review-sample/ is a deterministic public fixture for the GitHub PR review workflow. It can be inspected without GitHub CLI authentication or network access.

Artifact Set

Each sample run writes:

• run_record.json - structured run metadata, intent, inputs, outputs, steps, boundary, replay command, and final status
• artifact_manifest.json - SHA-256 hashes, byte sizes, roles, classifications, replay inclusion, and rollback inclusion
• trace.jsonl - ordered event trace in newline-delimited JSON
• commands.log - summarized command execution evidence
• git.diff - modeled code change
• sample_verification.json - pass/fail checks for the run
• sample_policy.json - public-safety and execution-boundary statement
• policy_gate_report.json - policy gate decision for accepted, rejected, escalated, or blocked trust
• human_escalation_record.json - reviewer action when the policy gate needs human judgment
• loop_stage_summary.json - bounded loop-stage summary for the run
• kill_switch_boundary.md - what stops or holds trust and what remains out of rollback scope
• evidence_packet.md - human-readable evidence summary
• review_packet.md - reviewer checklist and decision surface
• rollback.sh - bounded rollback script for modeled git-tracked changes

The sample root also writes adversarial-corpus.json, a public-safe index of hard-negative review traps and the sample runs that exercise them.

The sample root also writes fieldheld-pr-review-sample/, a deterministic public-safe PR-review bundle with pr_metadata.json, changed_files.json, file_diffs.json, status_checks.json, risk_summary.json, review_outcome.json, review_request.md, run_record.json, reviewer_packet.md, commands.log, artifact_manifest.json, and sample_verification.json. Its review_request.md is the short shareable ask for a cold reviewer: what to inspect, what question to answer, where to record the outcome, and what useful critique looks like. Its reviewer_packet.md includes a review decision checklist that maps risk reasons, status-check evidence, and diff coverage into explicit accept/reject/request-changes prompts. Its review_outcome.json is an unrecorded template a reviewer can fill with accept, reject, request_changes, or needs_followup.

Read docs/ARTIFACT_GUIDE.md for a field-by-field guide to the evidence bundle.

Read docs/RUN_REVIEW_CHECKLIST.md for a short human review checklist for deciding whether to accept, reject, or escalate a sample run.

Read docs/CRITIQUE_REQUEST.md for the specific technical critique request.

Read docs/PR_REVIEW_CRITIQUE_REQUEST.md for the narrow critique request for the GitHub PR review bundle.

Read docs/REVIEWER_PACKET_INDEX.md for the fastest path through the sample artifacts and trust decisions.

Read docs/PASSING_TESTS_IS_NOT_ENOUGH.md for the argument behind the evidence-gate sample.

Read docs/TRACE_VS_EVIDENCE.md for the short comparison between traces, logs, and evidence-gated review decisions.

Read docs/ARTIFACT_WALKTHROUGH.md for an annotated review of the accepted sample bundle.

Read docs/AGENT_RUN_RECORD_SPEC.md for the public v0.1 run-record contract used by the sample.

Read docs/RELEASE_NOTE.md and docs/LIVE_ADAPTER_BOUNDARY.md for the current synthetic baseline boundary and the smallest future live-adapter boundary.

Why This Exists

Agent traces and test logs are useful, but they do not always answer the review questions a human needs before trusting autonomous work:

• what was the intent?
• what changed?
• what evidence supports the result?
• what failed or remained uncertain?
• what can be replayed?
• what can be rolled back?

Fieldheld Recorder is the first small public baseline for that evidence contract.

For the longer explanation, read docs/WHY_FIELDHELD_RECORDER.md.

Artifact Contract

Public run_record.json examples use the Agent Evidence Kernel run-record fields:

run_id
intent
producer
adapter
replay_command
input_artifacts
output_artifacts
generation_steps
tool_or_model_steps
environment_boundary
execution_limits
failure_capture
verification_notes
final_status

Public artifact_manifest.json entries use:

root_label
relative_path
artifact_role
classification
sha256
byte_size
generated_by
included_in_replay
included_in_rollback

Allowed classifications are:

input
generated
derived_report
review_surface
verification_output
excluded_recursive_artifact

The detailed v0.1 contract lives in docs/AGENT_RUN_RECORD_SPEC.md.

Boundaries

• Synthetic sample only.
• No network calls.
• No provider account required.
• No hosted service.
• No package publishing from this local candidate.
• No live adapter.
• No legal, compliance, safety, or deployment certification.
• Rollback is limited to modeled git-tracked file changes.
• External effects are not reversed.

See docs/OPERATING_BOUNDARIES.md for the full boundary model.

Current Status

This is a public baseline for inspecting the artifact contract and demoing the review workflow. It is not yet a live agent wrapper.

The current CLI name is fieldheld-recorder.

The broader Fieldheld direction is to make autonomous work governable: replayable, reviewable, rollbackable, and accountable.

Support

Best effort. No SLA. No warranty.

License

Apache-2.0. See LICENSE.