Skip to content

Getting Started With Protocolith

Protocolith is easiest to understand as a small evidence pipeline for one narrow claim.

If there is no evidence card, the statement is still only a claim.

Protocolith workflow

official source
  -> frozen protocol
  -> local payload handling outside this repository
  -> runner or manual checklist
  -> exact result status
  -> evidence card
  -> public registry entry

The Core Rule

Write the rules before looking at the outcome.

A good Protocolith result says:

Under protocol P, using official source S, candidate C received status R under
frozen gate G.

A bad Protocolith result says:

This model works generally.
This system is ready for deployment.
This method is better than all other methods.

Minimal Workflow

  1. Pick a narrow claim.
  2. Confirm the official public source and source boundary.
  3. Record rights, attribution and payload-handling notes.
  4. Freeze the protocol, target, baselines, controls and acceptance gate.
  5. Run the track or complete the checklist.
  6. Publish the exact status, including negative, blocked or insufficient coverage outcomes.
  7. Create a compact evidence card.
  8. Add the card to the public registry only after validation.

Valid Result Statuses

Use the documented result_status values:

  • PASSED_UNDER_PROTOCOL
  • NEGATIVE_RESULT_UNDER_PROTOCOL
  • BLOCKED_SOURCE
  • INSUFFICIENT_COVERAGE
  • REPRODUCED_OUTCOME (rare; most cards record gate outcomes instead)

Record reproduction separately in reproduction_level:

  • not independently reproduced
  • REPRODUCED_OUTCOME
  • REPRODUCED_OUTCOME_WITH_SOURCE_BYTE_DRIFT

Do not put source-byte drift in result_status. See result statuses.

Negative and blocked outcomes are useful. They prevent selective reporting and make source limits visible.

Minimal Local Check

uv sync --extra dev
uv run protocolith doctor
uv run --extra dev python -m pytest -n auto
uv run protocolith validate-all
uv run --extra dev python scripts/protocolith_validate_evidence_card.py \
  docs/evidence_cards/PLITH-NASA-POWER-D103-2026-04-29.json

Common Commands

Command What it does
uv run protocolith new Creates a draft request, protocol, playbook, checklist, operator declaration, draft card, family ledger and source-probe summary. Prompts interactively in a terminal.
uv run protocolith new-track Alias for new; kept for people who think in "track" language.
uv run protocolith run-root --protocol-id ... --source-url ... Creates a local-only run directory under $HOME/protocolith_runs/ with raw/, logs/, hashes/, reports/ and transcripts/.
uv run protocolith demo eea-source-audit Runs the EEA source-audit demo helper and writes a sanitized report under the demo run root.
uv run protocolith demo eea-manual-probe Runs the EEA AQ manual-track probe helper and writes a blocked-readiness summary under the demo run root.
uv run protocolith demo grok-source-audit Clones or reuses the public xai-org/grok-prompts repository in a local-only demo root, then writes source-audit metadata and hashes.
uv run protocolith validate-tree docs/track_families/<ID>_TREE.json Validates optional v3 tree overlays for related manual tracks.
uv run protocolith validate-family docs/track_families/<ID>_FAMILY_LEDGER.json Validates claim IDs, family budget, track modes and stop/closure structure for related R&D tracks.
uv run python scripts/protocolith_validate_family_ledger.py docs/track_families/<ID>_FAMILY_LEDGER.json Script entrypoint for the same family-ledger validation, useful in shell workflows.
uv run protocolith validate-frontier docs/track_families/<ID>_FRONTIER.json Validates a compact frontier/tombstone ledger for related R&D families.
uv run python scripts/protocolith_validate_family_frontier.py docs/track_families/<ID>_FRONTIER.json Script entrypoint for the same frontier validation.
uv run protocolith validate-all Validates all committed evidence cards, the registry index and any optional *_FAMILY_LEDGER.json or *_FRONTIER.json files.
uv run protocolith doctor Checks Python, git and repo layout on Windows, macOS or Linux.

These commands are useful for private local work too. Shell tools such as jq, curl and shasum are not required for the primary protocolith workflows. See platform support. A person or organization can keep raw payloads, prompt text, transcripts and logs inside a local run root, while publishing only the sanitized hashes and evidence card.

Create A New Scaffold

Interactive:

uv run protocolith new

Non-interactive:

uv run protocolith new \
  --source-url "https://example.org/source-docs" \
  --protocol-id "EXAMPLE_D001" \
  --domain "public-data" \
  --track-type "source_audit" \
  --execution-mode "MANUAL_NO_AI" \
  --out "docs/manual_audit/EXAMPLE_D001"

The scaffold is not evidence. It creates a request, protocol draft, playbook, checklist, operator declaration, draft card, R&D family ledger and source-probe summary so an operator can freeze the real protocol and run the track without missing common steps.

For related tracks, edit the generated family ledger before the second track runs. The ledger is where you list claim IDs, diagnostic versus proof mode, track budget, stop rules and closure decisions.

Prepare A Local Run Root

Manual and AI-assisted runs should keep raw payloads outside this repository:

uv run protocolith run-root \
  --protocol-id "EXAMPLE_D001" \
  --source-url "https://example.org/source-docs" \
  --operator "your-name-or-handle"

This creates a local-only directory under your home folder (by default protocolith_runs/ there) with standard raw/, logs/, hashes/, reports/ and transcripts/ folders, plus RUN_CONTEXT.md, DEVIATIONS.md and LOCAL_MANIFEST.md.