Skip to content

Latest commit

 

History

History
380 lines (295 loc) · 14.1 KB

getting-started.md

File metadata and controls

380 lines (295 loc) · 14.1 KB

Getting Started

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.

Before You Start

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 to review_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 --version

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

1. Start From A Real Tracked Change

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

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

2. Activate The Store, Capture The Change, And Open Review

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 --open

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

3. Read The Review In Five Stages

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.

4. Author Handoff — Claims And Evidence

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 json

The 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 json

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

5. Reviewer Pass — A Question And A Provisional Call

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 json

Keep 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 json

Keep 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 json

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

6. Author Response

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 json

Context 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 json

Both writes change the durable review record, not the captured content — so nothing is recaptured and the revision id does not change.

7. The Reviewer Replaces The Call

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 json

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

8. Land The Commit On The Same Revision

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 json

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

Where To Go Next

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