This guide takes one real tracked change from capture to a complete paired author/reviewer loop:
capture the change, open it in Pointbreak Review, record the author's handoff, let a reviewer ask a
question and make a call, answer it, and land the commit on the same exact Revision. Along the way it
introduces the five Review stages in plain language:
Work -> Claims -> Evidence -> Questions -> Call.
Change-store transition: normal Review reads and writes require an activated Change-ready store. A new or legacy store reports
migration_required; the explicit activation below creates a verified external backup, acknowledges the exact migration plan, and sets the minimum reader toreview_change_revision_v1. Pointbreak v0.9 readers cannot open the store after that transition.
Install Pointbreak by the supported route in installation.md, then verify the binary:
pointbreak --versionYou also need Git and jq. The commands below are written for a macOS or Linux shell; on Windows,
run them in Git Bash or WSL.
Pointbreak reviews your own work, not a sample. If a repository of yours already has a modified tracked file, use it and skip the scratch block below.
Otherwise, create a disposable repository with a committed baseline, then modify the tracked file so there is a real change to review:
mkdir first-review
cd first-review
git init
git config user.name "First Review"
git config user.email "first-review@example.invalid"
git config commit.gpgsign false
printf '%s\n' 'First useful Review' > onboarding.txt
git add onboarding.txt
git commit -m "chore: add onboarding baseline"
printf '%s\n' 'First useful Review' 'Checks are evidence, not a verdict.' > onboarding.txtgit status --short now shows M onboarding.txt: a real modification to an already tracked file,
which is exactly what a first review should look at.
First inspect the store profile. A fresh repository reports migration_required:
pointbreak change profile --format json | jq .Activate it through a reviewed dry run and a fresh external backup directory. The backup path must be absent or empty. The signing key is required only for the irreversible activation record; Review facts continue to use their own actor identities below.
ACTIVATION_DIR=$(mktemp -d "${TMPDIR:-/tmp}/pointbreak-first-review.XXXXXX")
DRY_RUN="$ACTIVATION_DIR/dry-run.json"
BACKUP_DIR="$ACTIVATION_DIR/pre-activation-backup"
pointbreak key init --name first-review-activation
pointbreak change migrate-dry-run --repo . --format json > "$DRY_RUN"
MANIFEST_HASH=$(jq -r '.manifestHash' "$DRY_RUN")
COHORT_MANIFEST_HASH=$(jq -r '.roots[0].cohortManifestHash' "$DRY_RUN")
pointbreak change migrate \
--repo . \
--dry-run "$DRY_RUN" \
--ack-manifest "$MANIFEST_HASH" \
--ack-cohort-manifest "$COHORT_MANIFEST_HASH" \
--ack-minimum-reader review_change_revision_v1 \
--ack-v0-9-unsupported \
--backup "$BACKUP_DIR" \
--operation-id first-review-activation \
--sign-key first-review-activation \
--format json | jq .
pointbreak change profile --format json | jq .The final profile reports availability: ready. Keep ACTIVATION_DIR until you no longer need its
dry run, migration receipt, and pre-activation backup.
Now capture the tracked change:
CAPTURE=$(pointbreak capture --summary "Explain evidence in first-use guidance" --format json)
printf '%s\n' "$CAPTURE" | jq .The capture freezes the current diff as a revision and prints a JSON document describing it. The summary is an immutable discovery label: lists and Review use it to identify the revision, and it never changes revision identity. Later facts attach to the same revision; nothing edits the label in place.
Keep the stable Change id, exact Revision id, and safe writer cursor from the capture output for the rest of the walkthrough:
CHANGE_ID=$(printf '%s\n' "$CAPTURE" | jq -r '.changeId')
REVISION_ID=$(printf '%s\n' "$CAPTURE" | jq -r '.revision.id')
REVIEW_CURSOR=$(printf '%s\n' "$CAPTURE" | jq -r '.reviewCursor.token')Now open Review:
pointbreak inspect --openReview is a local, read-only projection of the durable review record: it renders revisions, diffs, and recorded facts, and it never executes commands or writes to the store. Right now it shows one Change under your summary, with one exact Revision and its changed file and rows. That is the first useful Review — and notice what the review itself did not require: no author or reviewer actor id, no review track, no trust enrollment, and no reading of raw event files.
inspect is a foreground server: leave it running, keep Review open in this browser tab, and run
every later command in a second terminal. Each step below appears in Review after a refresh.
Every Pointbreak review answers five questions, in this order, and each stage is owned by one flattened command family:
| Stage | Question it answers | Command family |
|---|---|---|
| Work | What changed? | capture, change, inspect |
| Claims | What does an author or reviewer assert? | observation |
| Evidence | What was checked? | validation |
| Questions | What still needs judgment? | input-request, change attention |
| Call | What is the current assessment? | assessment |
Two supporting nouns complete the picture: change attention lists outstanding judgment across
the store, and association records where the reviewed work landed. After the capture, Work is
populated and the other stages are empty. The rest of this guide fills them in.
The first authored fact must say who wrote it and which review lane owns it. An actor answers "who wrote this?"; a track answers "which review lane owns it?". Set both now — they were deliberately not needed to see the first Review:
export POINTBREAK_ACTOR_ID="actor:agent:first-review-author"
AUTHOR_TRACK="agent:first-review-author"Record the author's claim about the change:
pointbreak observation add \
--review-cursor "$REVIEW_CURSOR" \
--track "$AUTHOR_TRACK" \
--title "First-use guidance distinguishes evidence" \
--body "The tracked change explains that checks are evidence rather than a verdict." \
--format jsonThe first authored fact may print a diagnostic that a signing key was generated for the actor.
Pointbreak signs writes automatically; signed-but-untrusted is an advisory state, not an error, and
nothing blocks on it. When you later want Review to show this writer as trusted, run
pointbreak key enroll <name> — it stages the key in .pointbreak/allowed-signers.json for human
review. Enrollment is optional and nothing in this walkthrough requires it.
Now run a real check and record its result:
git diff --check
pointbreak validation add \
--review-cursor "$REVIEW_CURSOR" \
--track "$AUTHOR_TRACK" \
--check-name "git diff --check" \
--status passed \
--command "git diff --check" \
--exit-code 0 \
--summary "The captured tracked change has no whitespace errors." \
--format jsonValidation is evidence, not a verdict: it records that a command actually ran against the captured content and what it reported. It is never an assessment, a merge signal, or a task-completion verdict — the Call stage stays empty until a reviewer makes one. Record a validation only for a command you actually ran.
Refresh Review: Claims and Evidence now carry the author's observation and check, attributed to the author's track.
A reviewer reads before writing: open Review, look at Work, Claims, and Evidence first. Reviewer facts then get their own actor and track, introduced here at the handoff and not before:
export POINTBREAK_ACTOR_ID="actor:agent:first-review-reviewer"
REVIEWER_TRACK="agent:first-review-reviewer"The reviewer records an independent claim and re-runs the check rather than trusting the author's record:
pointbreak observation add \
--review-cursor "$REVIEW_CURSOR" \
--track "$REVIEWER_TRACK" \
--title "The added sentence is user-visible" \
--body "The added line is wording a reader will quote; it should be deliberate." \
--format json
git diff --check
pointbreak validation add \
--review-cursor "$REVIEW_CURSOR" \
--track "$REVIEWER_TRACK" \
--check-name "reviewer git diff --check" \
--status passed \
--command "git diff --check" \
--exit-code 0 \
--summary "The reviewer independently reran the whitespace check." \
--format jsonKeep the reviewer observation id from the first command's output (the observationId field):
REVIEWER_OBSERVATION_ID="obs:sha256:<the id from the observation output>"A question that needs the author's judgment becomes a durable input request, not a chat message:
pointbreak input-request open \
--review-cursor "$REVIEW_CURSOR" \
--track "$REVIEWER_TRACK" \
--title "Confirm the wording boundary" \
--reason manual-decision-required \
--mode advisory \
--body "Is the new sentence the exact wording the guide should quote?" \
--format jsonKeep its id (the inputRequestId field):
INPUT_REQUEST_ID="input-request:sha256:<the id from the open output>"The reviewer closes the pass with a provisional call that links what it rests on:
pointbreak assessment add \
--review-cursor "$REVIEW_CURSOR" \
--track "$REVIEWER_TRACK" \
--assessment needs-clarification \
--summary "The change is sound, but the quoted wording needs an explicit answer." \
--related-observation "$REVIEWER_OBSERVATION_ID" \
--related-input-request "$INPUT_REQUEST_ID" \
--format jsonKeep the assessment id (the assessmentId field):
PROVISIONAL_ASSESSMENT_ID="assess:sha256:<the id from the assessment output>"Refresh Review: Questions shows the open request, Call shows needs-clarification, and the open
question also appears under attention — outstanding judgment, not a gate.
The author answers the question where it was asked. The durable answer lives on the request itself:
export POINTBREAK_ACTOR_ID="actor:agent:first-review-author"
pointbreak input-request respond "$INPUT_REQUEST_ID" \
--outcome approved \
--reason "Yes - the sentence is exactly what the guide should quote." \
--format jsonContext worth keeping beyond the answer goes into a follow-up observation on the author's track:
pointbreak observation add \
--review-cursor "$REVIEW_CURSOR" \
--track "$AUTHOR_TRACK" \
--title "Quoted wording is final" \
--body "The sentence is the exact wording the guide quotes; no further edit is planned." \
--format jsonBoth writes change the durable review record, not the captured content — so nothing is recaptured and the revision id does not change.
The provisional call is answered, but one obligation remains open, so the reviewer records it as an explicit follow-up request before replacing the call:
export POINTBREAK_ACTOR_ID="actor:agent:first-review-reviewer"
pointbreak input-request open \
--review-cursor "$REVIEW_CURSOR" \
--track "$REVIEWER_TRACK" \
--title "Re-check the wording after the next guide edit" \
--reason insufficient-evidence \
--mode operative \
--body "If the guide sentence changes, re-run this walkthrough against the new wording." \
--format jsonKeep the new request id as FOLLOW_UP_REQUEST_ID, then replace the provisional call:
FOLLOW_UP_REQUEST_ID="input-request:sha256:<the id from the open output>"
pointbreak assessment add \
--review-cursor "$REVIEW_CURSOR" \
--track "$REVIEWER_TRACK" \
--assessment accepted-with-follow-up \
--summary "Accepted; the follow-up re-check remains open." \
--replaces "$PROVISIONAL_ASSESSMENT_ID" \
--related-input-request "$FOLLOW_UP_REQUEST_ID" \
--format json--replaces is the only thing that retires an earlier assessment. Refresh Review: Call shows
accepted-with-follow-up as current with needs-clarification visibly replaced — the history is
kept, not rewritten — and the operative follow-up keeps the Change visible under attention until
someone resolves it.
The reviewed content is ready to land. Commit it, select the exact Revision against that immutable commit, and let Pointbreak prove the content relation before recording the landing:
git add onboarding.txt
git commit -m "docs: clarify first Review evidence"
export POINTBREAK_ACTOR_ID="actor:agent:first-review-author"
LANDED_COMMIT=$(git rev-parse HEAD)
LANDING_CURSOR=$(pointbreak change select "$CHANGE_ID" \
--revision "$REVISION_ID" \
--source "commit:$LANDED_COMMIT" \
--format json | jq -r '.token')
pointbreak association land \
--review-cursor "$LANDING_CURSOR" \
--track "$AUTHOR_TRACK" \
--commit "$LANDED_COMMIT" \
--format jsonRefresh Review one last time. The revision id is unchanged, the landing shows the exact commit, and every fact recorded above still reads against the same exact Revision. Committing already-reviewed content is a landing, never new work: capture a replacement Revision in the same Change only when the content itself changes. A commit that lands what was reviewed is always an association on the same Revision.
- CLI reference lists commands, options, output schemas, and V1 limitations.
- Review workflow explains when to reach for capture, observations, input requests, assessments, history, and revision reads in a real review.
- Storage model explains the durable record underneath: append-only review facts, immutable snapshots, and rebuildable projections.
- Input request model explains operative and advisory requests.
- Assessment model explains assessment values and replacement behavior.
- Signing UX explains automatic signing, the trust ladder, and enrollment.
- Agent authoring explains how coding agents leave the same review record.