Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
162 lines (125 loc) · 6.27 KB

GETTING_STARTED.md

File metadata and controls

162 lines (125 loc) · 6.27 KB
Raw

Getting Started With ClaimBound

ClaimBound 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.

ClaimBound 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 ClaimBound result says:

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

A bad ClaimBound 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 claimbound doctor
uv run --extra dev python -m pytest -n auto
uv run claimbound validate-all
uv run --extra dev python scripts/claimbound_validate_evidence_card.py \
  docs/evidence_cards/CLAIMBOUND-NASA-POWER-D103-2026-04-29.json

Common Commands

Command What it does
uv run claimbound 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 claimbound new-track Alias for new; kept for people who think in "track" language.
uv run claimbound run-root --protocol-id ... --source-url ... Creates a local-only run directory under $HOME/claimbound_runs/ with raw/, logs/, hashes/, reports/ and transcripts/.
uv run claimbound demo eea-source-audit Runs the EEA source-audit demo helper and writes a sanitized report under the demo run root.
uv run claimbound 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 claimbound 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 claimbound validate-tree docs/track_families/<ID>_TREE.json Validates optional v3 tree overlays for related manual tracks.
uv run claimbound 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/claimbound_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 claimbound validate-frontier docs/track_families/<ID>_FRONTIER.json Validates a compact frontier/tombstone ledger for related R&D families.
uv run python scripts/claimbound_validate_family_frontier.py docs/track_families/<ID>_FRONTIER.json Script entrypoint for the same frontier validation.
uv run claimbound validate-all Validates all committed evidence cards, the registry index and any optional *_FAMILY_LEDGER.json or *_FRONTIER.json files.
uv run claimbound 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 claimbound 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 claimbound new

Non-interactive:

uv run claimbound 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 claimbound 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 claimbound_runs/ there) with standard raw/, logs/, hashes/, reports/ and transcripts/ folders, plus RUN_CONTEXT.md, DEVIATIONS.md and LOCAL_MANIFEST.md.

Read Next