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.
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¶
- Pick a narrow claim.
- Confirm the official public source and source boundary.
- Record rights, attribution and payload-handling notes.
- Freeze the protocol, target, baselines, controls and acceptance gate.
- Run the track or complete the checklist.
- Publish the exact status, including negative, blocked or insufficient coverage outcomes.
- Create a compact evidence card.
- Add the card to the public registry only after validation.
Valid Result Statuses¶
Use the documented result_status values:
PASSED_UNDER_PROTOCOLNEGATIVE_RESULT_UNDER_PROTOCOLBLOCKED_SOURCEINSUFFICIENT_COVERAGEREPRODUCED_OUTCOME(rare; most cards record gate outcomes instead)
Record reproduction separately in reproduction_level:
not independently reproducedREPRODUCED_OUTCOMEREPRODUCED_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.