@uchibeke/gallivant 0.2.0 → 0.3.0

package/docs/agent-setup.md

@@ -1,9 +1,10 @@
 # Let an agent set up Gallivant
 
-Give the prompt below to your coding agent. It can inspect prerequisites, install
-the CLI, create a private config and validate a first task. You handle account
-login and any required trust prompts. Setup does not need access to every private
-repository, and installing the CLI does not start a paid session.
+Give the prompt below to your coding agent. It can inspect prerequisites, run
+the published setup command, read the resulting report and validate a first task.
+You handle account login and any required trust prompts. Setup does not need
+access to every private repository, and running the setup command does not start
+a paid session.
 
 Start with **Codex or Claude and one repository**. Those are the harnesses supported
 by `gallivant init`. [Hosted Agents API](openai-agents.md) uses an explicit config
@@ -24,12 +25,15 @@ CLI --help and the docs matching the installed version. Prefer an already workin
 Codex or Claude setup. Preserve existing credentials, settings, running jobs,
 worktrees and uncommitted changes. Report proposed config changes without secrets.
 
-Install/configure the CLI and run the setup checks. If Gallivant is not yet
-published on npm, use the documented source installation. Do not overwrite an
-existing config, weaken security settings, install global hooks, change repository
-protections, sign into accounts or elevate privileges without the relevant user
-authorization. Never ask me to paste API keys or tokens into this conversation.
-Use the provider's login flow or a private credential file instead.
+From inside the target checkout, run the published setup command:
+npx --yes @uchibeke/gallivant init --harness codex (or --harness claude), then
+read its report. Do not clone the Gallivant repository or install it globally
+unless I ask. If the command stops because gh or the harness is signed out, tell
+me the exact login command it printed and wait; do not sign in for me. Do not
+overwrite an existing config, weaken security settings, install hooks, change
+repository protections or elevate privileges without my authorization. Never ask
+me to paste API keys or tokens into this conversation. Use the provider's login
+flow or a private credential file instead.
 
 Ask only for missing decisions: target repository and checkout, approved base
 branch, preferred available harness, first task scope, and allowed spending.
@@ -88,38 +92,45 @@ automatically commit, or switch a dirty checkout. Confirm which GitHub repositor
 and base branch the task should use; the current branch is not necessarily the
 approved PR target. Account login and Git identity belong to the user.
 
-## 2. Install and initialize
+## 2. Run the setup command
 
-Use the [current installation instructions](install.md#1-the-command). Before
-the first npm publication, install from source; `npm install -g @uchibeke/gallivant` is only
-an option after the package is published. Avoid `sudo npm install`; use a
-user-owned Node installation or prefix when global installation is not writable.
-Do not silently replace a different installed version while its daemon is running.
-
-After GitHub and the selected harness are signed in:
+Use the [current installation instructions](install.md#2-the-command). After
+GitHub and the selected harness are signed in, from inside the target checkout:
 
 ```sh
-gallivant --version
-gallivant --help
-gallivant init --harness codex
-gallivant doctor
+npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
 ```
 
-Use `--harness claude` for Claude. `init` is noninteractive; it creates a config
-only when none exists. It does not log in, install hooks or fix permissions.
-If a config exists, skip `init` and preserve its unrelated keys. The normal path
-is `~/.gallivant/config.json`; use `$GALLIVANT_HOME/config.json` if that variable is
-already set. Keep it private (mode `600`). Choose a worktrees directory outside
-the config home, using `init --worktrees /absolute/path` if needed.
-
-Before a real run, finish the [harness guardrail setup](install.md#6-aport-on-claude-code)
+`npx` runs the published package on demand; it installs nothing globally and
+does not clone this repository. `init` is noninteractive. It refuses, writing
+nothing, when the directory is not a GitHub checkout, `gh` or the harness is
+signed out, or the login cannot push to the repository; report the printed
+command to the user instead of working around it. Otherwise it creates
+`~/.gallivant/config.json` (mode 600) when none exists, records the current
+repository in `repos` once, creates the worktrees directory and prints the
+`doctor` report. Exit status `1` means checks remain, not that setup failed.
+
+With an existing config, `init` keeps every key as written and adds only the
+current repository. Do not edit unrelated keys. The normal path is
+`~/.gallivant/config.json`; use `$GALLIVANT_HOME/config.json` if that variable is
+already set. Pass `--worktrees /absolute/path` only on first creation; later
+runs refuse a different directory.
+
+If the user prefers a persistent command, `npm install -g @uchibeke/gallivant`
+is the documented option; ask before installing globally. Avoid `sudo npm
+install`; use a user-owned Node installation or prefix. Do not silently replace
+a different installed version while its daemon is running.
+
+Before a real run, finish the [harness guardrail setup](install.md#7-aport-on-claude-code)
 for the selected harness. Some steps require human interaction: for example,
 Codex's initial `/hooks` trust prompt cannot be automated. Report such a blocker
 instead of changing the enforcement level or bypassing it.
 
-Add the authorized repository to `repos` and its approved base where necessary,
-following [configuration](config.md#the-base-branch). Review the config diff without
-printing credentials. Confirm these decisions before dispatch:
+`init` records the repository without a base branch; its pull requests target
+the default branch unless the user chooses otherwise with `start --base` or a
+`{ "repo", "base" }` entry, following [configuration](config.md#the-base-branch).
+Review the config diff without printing credentials. Confirm these decisions
+before dispatch:
 
 | Decision | What must be established |
 |---|---|
@@ -129,8 +140,9 @@ printing credentials. Confirm these decisions before dispatch:
 | Completion evaluator | Default APort hosted confirmation needs network access. A local evaluator is an explicit user choice, not an automatic workaround for a failure. |
 | Cost | Confirm `max_iterations`, provider budget controls and allowed spend. `max_budget_usd` is a native per-run dollar cap for Claude; other local harnesses have no equivalent enforced dollar cap. |
 
-Run `gallivant doctor` again and report every failure. Do not treat “signed in
-(API unchecked)” as proof of inference access. `doctor` without extra flags checks
+Run `gallivant doctor` (or `npx --yes @uchibeke/gallivant doctor`) again and
+report every failure. Do not treat “signed in (API unchecked)” as proof of
+inference access. `doctor` without extra flags checks
 configuration, credentials and repository access without launching a model run.
 `doctor --probe` launches a real Claude sandbox test when Claude is configured;
 `doctor --send` sends a real notification. Use those only when authorized.
@@ -206,9 +218,11 @@ review and merge.
 
 ## What setup verification proves
 
-The package's `npm run test:install` smoke test installs the tarball into a
-throwaway directory, uses fixture CLI credentials, initializes a private config,
-loads the packaged PRD template, and checks an offline brief. It does not use a
-real account, invoke a model or certify a provider's current availability.
-A first authorized end-to-end task is still needed to verify the user's actual
-repository permissions, provider entitlement, sandbox, CI and review integration.
+The package's `npm run test:install` check packs the tarball and runs the
+README's `npx` setup command against it from a disposable repository, with
+fixture `gh` and `codex` commands and a throwaway home. It proves which binary
+ran, the config and directory permissions, repository registration, repeat
+safety and the printed next steps. It does not use a real account, invoke a
+model or certify a provider's current availability. A first authorized
+end-to-end task is still needed to verify the user's actual repository
+permissions, provider entitlement, sandbox, CI and review integration.

package/docs/architecture.md

@@ -38,6 +38,10 @@ lib/events.mjs           pure rules: what counts as an event, trust, reviewer ve
 lib/prompt.mjs           start, register and fix prompts; quoting and caps
 lib/harness.mjs          capability registry plus local argv, session, outcome and sign-in adapters
 lib/tasks.mjs            natural-language intake, revisions, validation, readiness and explicit execution consent
+lib/task_profile.mjs     portable typed delivery profile, deterministic delivery screen and planner tag coverage (vendored by Agent Passport)
+lib/task_model_route.mjs bounded text-only model route for drafting; pre-call allowance checks, usage-derived cost
+lib/task_model_config.mjs operator configuration and absolute ceilings for that route
+lib/task_repository_context.mjs read-only, bounded repository snapshot pinned to the prepared revision
 lib/task_delivery.mjs    authenticated host operation boundary; delegates to the same task service
 lib/execution.mjs        durable local/remote dispatch, ownership, observations and recovery
 lib/execution_result.mjs owned hosted artifact verification and coordinator publication
@@ -72,10 +76,10 @@ templates/               passport, Claude sandbox settings, PRD, tracker/{tracke
 
 ## Design rules
 
-New intake tasks targeting `delivery_ready` stop automatic observation and fixing
+Legacy review policies on intake tasks targeting `delivery_ready` stop automatic observation and fixing
 at the qualified saved handoff. Explicit queued recheck/resume/message controls
 reopen the workflow. `integrated` targets and legacy written-PRD runs retain
-monitoring. `completionStopsAutomation` and the exported `coordinatorEntryActive`
+monitoring. Version-1 review policies keep ready deliveries monitored so late trusted feedback and changed input can revoke readiness. `completionStopsAutomation` and the exported `coordinatorEntryActive`
 keep core and host schedulers aligned. The review transitions below apply while
 an entry is monitored; malformed or incomplete delivery proof cannot mark it
 finished or suppress work.
@@ -215,7 +219,7 @@ For each registry entry that is not `done`:
 6. **Dispatch.** Past the cap, stop with `iterations`. Otherwise recreate the checkout if it is gone, merge the base branch into the work branch, build the fix prompt, resume the session (or start one for a registered PR), move the cursor to the newest event and record the ids dispatched at that instant, record the run.
 
    The merge is where a round of work starts from the current base rather than from wherever the base was when the branch was cut, and it is a merge rather than a rebase for three reasons that all live in this codebase. A rebase of a pushed branch can only move with a force-push, which the rules every session is given forbid. `reviewerVerdict` clears a head only when the commit the reviewer named is that head, so a rewrite makes every prior clearance describe a commit that no longer exists, and the reviewer's inline comments are anchored to those same commits. And step 7 reads a head the loop did not put there as a person's push, so a daemon force-push would look to the daemon itself like a stranger pushing. A merge moves the head forward, keeps every reviewed commit an ancestor, and needs no `--force`. An outstanding review therefore does not hold it up, which is the point: a rebase would have had to wait for the review, and that is a deadlock where the reviewer waits for a fix and the fix waits for the reviewer. The merge commit stays local until the session pushes, so nothing on GitHub moves, the reviewer clock is not reset and the round is still counted from the session's own push. It is recorded the moment it succeeds rather than by the save at the end of this step, because four things after it can return early and a merge nobody recorded is a change to a checkout with nothing to explain it. A conflict is aborted and the entry stops with `base-conflict` naming the base, because a half-merged checkout handed to a session as if it were clean is the worst thing this step could leave, and a conflict does not resolve on its own so retrying every tick would loop forever. Four things that would refuse identically on every poll stop the entry instead of looping: a checkout that cannot be recreated (`no-worktree`, with the cause as the event), a harness that refuses the configured `context_paths` (`context-paths`), no GitHub credential (`no-credential`) and no git identity on the machine (`no-identity`, whose event is the two `git config --global` commands that fix it). None of them resolves on its own, and the entry would otherwise redispatch the same feedback every poll with nothing notified. One invariant orders the rest of this step: **a spawned run must be recorded before anything else can fail.** Everything that can throw, the checkout and the ready-label removal included, happens before the spawn, and the registry write that owns the run comes immediately after it with no `await` in between. A process the registry does not know about is the worst state the dispatch can leave, because the settle step reads it as an unrelated leftover and the feedback that caused it is still new, so the same feedback spawns a second fixer when the first one exits. The label removal is the one write that can therefore hold a dispatch back, and holding it back is bounded: five consecutive failures stop the entry with `stuck`. `gh.removeLabel` throws by default and swallows only gh's own "label not found", which is what makes that bound reachable at all: the lenient behaviour was once the default, one of the two callers omitted the flag, and a GitHub that refused the write resolved as though the label had merely been absent.
-7. **Ready.** First, a head nobody told the loop about. Both watching states go through the same check, in one place: `fixed_sha` follows the head, the reviewer clock resets to the push and the nudge becomes available again, because the reviewer has not seen this commit. A `ready` entry also leaves ready with the label off, since its verdict, its green checks and its accepted receipt all describe a commit that is not the head any more. Handling it for `ready` alone used to leave a `pr-open` entry judging the new head with the old head's age, so the same tick that noticed the push could stop it as `reviewer-silent` on a wait that expired before the commit existed, and the nudge already spent on the old head was never reissued. Then, for a `pr-open` entry: no events, no run, not a draft, every check green (none counts as green), reviewer clear or absent. Then the brief, compared with the operator's own copy: this is the only place the daemon reads their working tree, and it is here because this is where the contract is about to be used to certify something. A contract that moved stops the entry with `prd-changed` and the difference named, before the gate runs and without setting `gate_skipped`, which describes the other thing entirely (a PR that reached READY with the gate unrun, where this entry is not reaching ready at all). An edit outside the contract re-takes the snapshot, notifies nobody and carries on. Then the completion gate (`deliverable.mjs`): the PR body's receipt must attest every acceptance criterion of the PRD with evidence; a deny starts a receipt round. A receipt whose shape is wrong is one of those denies, not an exception. The output scan needs the whole diff, so a diff that cannot be read or reaches the 16 MiB scan cap is no decision at all. Large hosted payloads are sent in overlapping pieces within the API request limit, with full criteria and attestations on each; every piece must allow. Unreadable diffs and unavailable evaluators use the same bounded `entry.retry` mechanism as writes, with the cause visible in `status` and `why`; five consecutive failures stop as `needs-human`, without a fixer run or iteration. The label goes on before the registry says ready, so a label write that fails leaves the entry in `pr-open` to be retried rather than a ready PR carrying no label, and those retries are counted on the same `entry.retry` as every other declining write: a token that cannot write labels at all used to repeat the readiness judgement, the completion gate included, on every poll forever, while `status` said the entry was waiting on a reviewer who had already answered. Only then notify, once.
+7. **Ready.** First, a head nobody told the loop about. Both watching states go through the same check, in one place: `fixed_sha` follows the head, the reviewer clock resets to the push and the nudge becomes available again, because the reviewer has not seen this commit. A `ready` entry also leaves ready with the label off, since its verdict, its green checks and its accepted receipt all describe a commit that is not the head any more. Handling it for `ready` alone used to leave a `pr-open` entry judging the new head with the old head's age, so the same tick that noticed the push could stop it as `reviewer-silent` on a wait that expired before the commit existed, and the nudge already spent on the old head was never reissued. Then, for a `pr-open` entry: no events, no run, not a draft, checks settled and the pinned review policy satisfied. Version-1 policies require explicit zero-check CI authorization for an empty check response; legacy no-review is disclosed as absence of review. Then the brief, compared with the operator's own copy: this is the only place the daemon reads their working tree, and it is here because this is where the contract is about to be used to certify something. A contract that moved stops the entry with `prd-changed` and the difference named, before the gate runs and without setting `gate_skipped`, which describes the other thing entirely (a PR that reached READY with the gate unrun, where this entry is not reaching ready at all). An edit outside the contract re-takes the snapshot, notifies nobody and carries on. Then the completion gate (`deliverable.mjs`): the PR body's receipt must attest every acceptance criterion of the PRD with evidence; a deny starts a receipt round. A receipt whose shape is wrong is one of those denies, not an exception. The output scan needs the whole diff, so a diff that cannot be read or reaches the 16 MiB scan cap is no decision at all. Large hosted payloads are sent in overlapping pieces within the API request limit, with full criteria and attestations on each; every piece must allow. Unreadable diffs and unavailable evaluators use the same bounded `entry.retry` mechanism as writes, with the cause visible in `status` and `why`; five consecutive failures stop as `needs-human`, without a fixer run or iteration. The label goes on before the registry says ready, so a label write that fails leaves the entry in `pr-open` to be retried rather than a ready PR carrying no label, and those retries are counted on the same `entry.retry` as every other declining write: a token that cannot write labels at all used to repeat the readiness judgement, the completion gate included, on every poll forever, while `status` said the entry was waiting on a reviewer who had already answered. Only then notify, once.
 8. **Silence.** Reviewer configured and quiet since the last request: nudge once after `rereview_minutes`, stop with `reviewer-silent` after `stall_hours`. Draft conversion in step 3 starts a fresh reviewer window, so time spent as a draft does not count as reviewer silence.
 
 The reviewer clock (`rereview.at`) is when the reviewer was last asked about the current head, and all three of those timers measure from it. Its best available value is the head commit's committer date, which is when the commit was made and not when it arrived on the branch, so it is floored at `rereview_minutes` ago: a commit made on Monday and pushed on Thursday must not stop the PR for a silence the reviewer was never given a chance to break. The rule is `reviewerClock` in `events.mjs`, pure and in one place because the tick is not its only writer: `reconcile` sets the same field on a recovered entry and goes through the same function, so a PR whose last round comment is older than `stall_hours` is not stopped `reviewer-silent` on the first tick after a crash recovery for silence that accrued while no daemon was running to ask.
@@ -263,3 +267,7 @@ a successful version probe alone cannot establish unattended support.
 ## Adding a reviewer
 
 No code. Set `reviewer.login`, `reviewer.rereview_comment` and `reviewer.blocking_pattern` in config.
+
+## Coordinator-owned first-party review
+
+`review_policy.mjs` owns versioned task policy and input bindings; `review_evidence.mjs` captures complete snapshots and validates structured judgement. `first_party_review.mjs` advances keyed review jobs through the existing execution registry, in a separate session and allowance. The shared tick handles readiness, trusted external feedback and fix rounds. Review jobs do not create a second scheduler or publish independent approvals. Host adapters provide the same normalized evidence contract; only the existing GitHub boundary is implemented here. See [policy and recovery behavior](first-party-review.md), including native qualification and measured rollout limitations.

package/docs/bitbucket-promotion.md

@@ -0,0 +1,69 @@
+# Review on GitHub, deliver through Bitbucket
+
+`npm run promote:bitbucket` transfers an accepted GitHub PR's **original commits** to Bitbucket Cloud and creates or updates its Bitbucket PR. It uses Git transport, the existing host adapters and the same review/check policy as the coordinator. It does not copy files, create commits, force-push, merge, enable CI or deploy.
+
+This is an operator command from a Gallivant source checkout. Install dependencies with `npm ci`. Configure both hosts using the [Git host guide](git-hosts.md); Git push access and Bitbucket API repository/PR access are both required. The command uses the existing scoped credentials, including a configured Bitbucket SSH key. Never put a token in a repository URL or a plan file.
+
+## Before promotion
+
+- Register and finish the GitHub run. It must retain an exact accepted completion and review binding under an explicit review policy. A label, green CI or the PR author's statement alone is insufficient.
+- Stopped dispatch and queued/applying operator controls block promotion. Cancellation, messages, resume and recheck requests must be reconciled before accepted work can be delivered. These controls are checked again after plan validation and after a push; a cancellation during an already-running push can leave the branch updated, but prevents subsequent PR publication when observed.
+- Only the exact remotely reviewed commit is transferred. Local checkout edits, untracked carried research inputs, environment files and session logs are neither read nor included. The transfer uses its own disposable bare Git repository, so an operator checkout may remain dirty or may already have been removed after merge.
+- Specify the destination repository explicitly. No organization or repository mapping is inferred.
+- For an existing Bitbucket PR, supply its number. This updates that PR rather than creating a duplicate.
+- The Bitbucket base must have the same Git tree as the reviewed GitHub base. Its commit hash may differ because the two hosts merged earlier changes separately. Promote dependent work in order, after the preceding Bitbucket change has merged. Reconcile differing trees on GitHub and obtain review again.
+- An existing destination branch must be an ancestor of the reviewed source head. Divergence is not resolved automatically.
+
+GitHub Actions may remain disabled for a review-only mirror. Zero CI checks are accepted **only** when the source run's operator-approved review policy explicitly allows zero checks. Configured required checks still must exist and pass. Local test results and production release requirements are not replaced by that setting. Missing required external or first-party review blocks promotion.
+
+## Preview, approve and apply
+
+For an existing mapped PR:
+
+```sh
+npm run promote:bitbucket -- \
+  --github-pr https://github.com/example/app/pull/1 \
+  --bitbucket-repo bitbucket.org/example/app \
+  --bitbucket-pr 93 \
+  --out accepted-promotion.json
+```
+
+The default is a remote read-only dry run. It fetches into a disposable temporary Git repository and prints the source and destination heads, bases, exact title/body, review policy, check count and a SHA-256 `digest`. `--out` saves that plan locally with mode 600 and refuses to overwrite an existing file. Keep private plans outside your repository; they contain private PR prose and the previous destination PR text, which may include its task metadata. Transport credentials are never added to the plan.
+
+Inspect the complete plan, then rerun the same mapping with its digest:
+
+```sh
+npm run promote:bitbucket -- \
+  --github-pr https://github.com/example/app/pull/1 \
+  --bitbucket-repo bitbucket.org/example/app \
+  --bitbucket-pr 93 \
+  --apply --expected-plan DIGEST_FROM_THE_DRY_RUN
+```
+
+The digest is an exact human approval pin, not a substitute for fresh review evidence. Changed source code, review, checks, public text, destination branch, base or existing PR text requires another dry run. The command reads accepted state and operator controls from the run registry; it never writes that registry or starts another agent.
+
+For a new PR, omit `--bitbucket-pr`. The default destination branch is `work/github-OWNER-REPO-pr-N`; `--branch` and `--base` select explicit alternatives. Subsequent runs reuse an existing PR only when its repository, branch/base and source-review provenance match. Otherwise supply an explicit PR mapping. Closed, cross-repository or duplicate targets are rejected.
+
+The Bitbucket title and human-readable body come from the GitHub PR, with a source-review link and original commit SHA appended. Source task receipts and recovery/session metadata are removed because they do not authorize a new host/task. The source GitHub PR retains the complete evidence.
+
+## After merging on GitHub
+
+Run the same dry-run command after merge. When GitHub still supplies the original reviewed base, the coordinator's retained acceptance hash is checked directly against the original head, base, body, checks and policy. No pre-merge plan file is required. The accepted local record and fresh clear reviewer/check evidence remain mandatory; merging a PR before it was accepted does not manufacture that authority.
+
+Optionally save `--out accepted-promotion.json` while the PR is accepted and still open. If GitHub later reports a different base, that archived plan can reconstruct the original base using:
+
+```sh
+--accepted-plan /absolute/path/to/accepted-promotion.json
+```
+
+Use the new printed digest for `--apply --expected-plan ...`, keeping `--accepted-plan` on that command too when using the fallback. The reconstructed binding must exactly match the coordinator's retained acceptance hash. The plan cannot replace a missing local acceptance record or authorize changed code, body, checks or policy.
+
+The transferred head is the original reviewed PR head even when GitHub used squash or merge commits. The GitHub merge/squash commit is never described as reviewed or silently substituted. Squash merges can make subsequent branch histories diverge between hosts; prefer history-preserving merges for this bridge. A future branch that is not a fast-forward of its mapped Bitbucket branch must be reconciled and reviewed, not force-pushed.
+
+## Races and retries
+
+Apply rechecks the plan before pushing. A native pre-push guard checks the server-advertised old branch SHA; Git's ordinary fast-forward update then compares that SHA on the server. No force or force-with-lease option is used.
+
+There is no atomic transaction across GitHub and Bitbucket. The command rechecks evidence and destination after the push, before publishing the PR, and verifies the returned PR head/base. The publication adapter's final reconciliation read also enforces the approved PR absence or exact existing number and previous title/body. An observed concurrent creation or text edit stops publication. This adapter has no atomic conditional-update contract with Bitbucket: an edit between that final read and the write can still be overwritten without detection, so avoid concurrent PR editing during apply. If an operation fails, including a lost push response, the branch or PR may already have been updated; the error states that possibility. Inspect the target and rerun a dry run. Never respond with a force push. Bitbucket merge and deployment remain separate operator decisions and retain their normal release controls.
+
+This bridge supports GitHub to Bitbucket Cloud only. It does not automatically schedule promotion, accept unregistered PRs, establish live production readiness, or migrate CI/secrets/deployment configuration.

package/docs/bitbucket-review.md

@@ -0,0 +1,330 @@
+# Bitbucket Cloud review setup and qualification
+
+Bitbucket Cloud dispatch and complete first-party evidence capture are implemented.
+The independent local review route is still **live-unqualified** until the public
+and private disposable repository matrix records a genuine blocking verdict,
+same-session correction and fresh exact-head clearance. Earlier disposable runs
+proved regular PR publication and receipt acceptance with **no reviewer
+configured**; they are not review evidence. The private coding session could also
+read the coordinator's merge-capable API-token file by path, so that historical
+coding-credential hold remains separate from reviewer credential isolation. Do
+not migrate an existing legacy run or start unattended work on the strength of
+offline fixtures. See the [qualification record](audit/bitbucket-review-qualification.md).
+
+## First setup, including a checkout with no existing configuration
+
+Use Node 22 or later, Git, and an explicitly selected installed local Codex or
+Claude executable. Bitbucket setup does not require `gh` or GitHub sign-in.
+Version/sign-in diagnostics do not prove model access. Existing GitHub defaults
+and runs retain their previous review semantics.
+
+1. Obtain an Atlassian **account API token** scoped to the intended workspace,
+   with `read:repository:bitbucket`, `write:repository:bitbucket`,
+   `read:pullrequest:bitbucket`, and `write:pullrequest:bitbucket`. Save it in a
+   private file (`chmod 600`). Supply the account email separately. An account
+   API token can be used with a free-plan repository; this does not require a
+   workspace/repository access-token subscription or Agentic Pipelines.
+2. For HTTPS Git, the coordinator uses the selected token as
+   `x-bitbucket-api-token-auth`; the API uses account email/token Basic auth.
+   For SSH Git, keep the API token and select the explicit SSH key/verified
+   known-hosts file described in [Git host setup](git-hosts.md). SSH authentication
+   alone cannot read or write PRs. The coding session receives neither token nor
+   SSH key through environment variables: its bounded PR mailbox asks the
+   coordinator to push and publish. A same-user coding process can still read
+   the configured private files unless a separate boundary denies those reads.
+   HTTPS and Cloud SSH checkout origins identify
+   the same repository; self-hosted servers and SSH aliases remain unsupported.
+3. Write a host settings file outside the coding checkout. Example:
+
+```json
+{
+  "api": {
+    "email": "operator@example.com",
+    "token_file": "~/.config/repository-access/bitbucket-api-token"
+  },
+  "git": { "transport": "https" },
+  "trusted_authors": ["{11111111-1111-1111-1111-111111111111}"],
+  "reviewer": null,
+  "required_checks": ["Tests"]
+}
+```
+
+Replace the example UUID with the operator's stable Bitbucket UUID, not a nickname.
+Select `reviewer: null` deliberately; the local first-party path needs no separate
+Bitbucket reviewer account. After `init`, configure the repository entry for a
+new reviewed run:
+
+```json
+{
+  "repo": "bitbucket.org/workspace/repository",
+  "reviewer": null,
+  "review": {
+    "mode": "first-party-required",
+    "route": "codex",
+    "max_input_bytes": 100000,
+    "max_jobs": 2048,
+    "budget_usd": 100,
+    "zero_checks": false
+  }
+}
+```
+
+Keep `review.legacy_no_review: true` only for a deliberately unreviewed legacy
+run while live qualification is unavailable. That mode still enforces configured
+CI, trusted commands, unresolved required feedback and the completion receipt,
+but its readiness record says `none`; it is never independently reviewed. The
+example check name must exactly match the repository's build status name. An
+empty `required_checks` list does not waive CI for a version-1 policy: a repository
+with no checks must explicitly set `review.zero_checks: true`. Missing/partial
+responses, rate limits, outages and pending checks never pass.
+
+From the intended checkout:
+
+```sh
+gallivant init --harness codex --host-config /absolute/path/bitbucket-host.json --base release/v2
+gallivant doctor
+```
+
+`--host-config` imports settings for the verified checkout's host. It creates a
+new config, or accepts unchanged settings while preserving UUID bindings added
+by setup. JSON member order does not matter; changed or omitted policy and
+conflicting identity bindings are refused. `--base` is validated and saved on the repository entry.
+`init` binds repository/workspace UUIDs, reads the selected base and account push
+role, and verifies Git's base SHA against the API. `doctor` distinguishes unknown
+write scopes from observed read access. Only an actual write can prove Git push,
+PR creation and comment write permission. Setup never installs a pipeline,
+creates a credential, changes repository protection, or makes a paid model call.
+It reports dispatch availability separately from transport access.
+
+Host settings live under `git_hosts["bitbucket.org"]`. `repositories["workspace/repo"]`
+may override `api`, `git`, `reviewer`, `trusted_authors`, and `required_checks`,
+alongside the UUID binding. Each override replaces that setting, not another
+host's credentials. A `repos` object may override reviewer/trust/check policy;
+precedence is repository entry, host repository binding, host settings. Historical
+top-level reviewer/trust defaults apply only to GitHub. Reviewer objects for
+Bitbucket must supply every required field; the GitHub mention is rejected.
+
+## Independent local Codex reviewer
+
+The host adapter binds the repository UUID, PR number, full head and base object
+IDs, and merge base. It paginates `diffstat/<head>..<base>?topic=true`, compares
+that changed-path inventory to the complete raw comparison, and reads regular
+UTF-8 source at the merge base and head through `src/{commit}/{path}`. Added,
+modified, removed and renamed files all carry before/after text as applicable.
+Unsupported binary, subrepository, missing-patch, duplicate, truncated, stale,
+rate-limited, redirected and oversized evidence is refused. The coordinator
+captures bounded symlink target data as untrusted Git objects without following
+the link. Unsupported targets or ambiguous type transitions block review.
+The PR binding is read again after capture. The API token stays behind the host boundary and is not
+part of the reviewer prompt or environment.
+
+The coordinator requests bounded PNG and JPEG sides at the exact revisions and
+requires a separate image-capability qualification before launching visual jobs.
+It combines their validated reports with text review and whole-PR synthesis.
+The image qualification does not itself qualify the host or complete a PR review;
+the [disposable live screenshot review](audit/bitbucket-review-qualification.md#live-image-qualification-and-disposable-review-2026-11-03)
+reached a clear verdict after its owned outputs were recovered; the resend PR
+has not been rechecked. Preserve the original files and incomplete state when any
+capability or evidence is unavailable.
+
+Qualify the exact configured executable/provider route only after authorizing its
+separate paid challenge:
+
+```sh
+gallivant review qualify --repo bitbucket.org/workspace/repository
+gallivant review qualify --repo bitbucket.org/workspace/repository --run --wait
+gallivant review qualify --repo bitbucket.org/workspace/repository
+```
+
+The first and last commands are read-only. `--run` starts at most the one durable
+qualification job for that fingerprint; CLI version and sign-in checks alone do
+not prove selected-model access. Start refuses before author dispatch if the route
+cannot qualify.
+
+Qualification fingerprints use the adapter's selected provider environment,
+configuration, credentials and executable. Parent-agent session and tool-call
+IDs do not invalidate an existing qualification. The private Codex profile drops
+the desktop-only `daybreak` flag for CLI compatibility; strict inspection of
+effective permissions and managed policy remains required.
+
+For a settled existing run that still has the explicit legacy snapshot, use the
+audited transition and then recheck the same PR:
+
+```sh
+gallivant review policy HANDLE --mode first-party-required \
+  --reason "Enable the qualified independent local reviewer"
+gallivant recheck HANDLE
+```
+
+This is the only path that removes the saved legacy policy. It retains the task
+identity, original PRD snapshot, PR, checkout and implementation session. A
+failed route preflight changes nothing and launches no review. Do not edit an
+active WebBabyShower brief or local policy as an implementation test.
+
+Each reviewer job is a fresh restricted Codex execution with no implementation
+session, context mounts, tools, network, host/Git credential or publication
+authority. The 100,000-byte input cap applies to every job. Large evidence is
+split into immutable source/patch slices, including a single large lockfile or
+line; every slice repeats the aggregate identities and all acceptance criteria.
+Clearance requires every piece to complete and match. `max_jobs`, `budget_usd`
+and per-job timeout bound the aggregate. If the full change does not fit those
+bounds, the run stops with `review-incomplete`; no path or suffix is omitted.
+
+## External Bitbucket reviewer account
+
+This is an alternative external-review setup, not required by the local path.
+Use a separate Bitbucket account for the automated reviewer. Configure its stable
+UUID, never its display name, nickname, the coding account, or a Pipeline label:
+
+```json
+{
+  "reviewer": {
+    "actor_id": "{22222222-2222-2222-2222-222222222222}",
+    "rereview_comment": "Review the current commit and post a work-review verdict.",
+    "blocking_pattern": "\\bP[01]\\b"
+  }
+}
+```
+
+This fragment belongs in the coding coordinator's host/repository policy. The
+reviewer token does **not** belong there. On a separate operator-controlled
+reviewer machine, OS account, or isolated container, store another private config
+with the same policy and the **reviewer** account email/token in `api`. Its token
+needs repository read and PR read/write. The coding agent must have no filesystem,
+environment, secret-store or container access to that credential. A private file
+in a directory readable by the coding identity is not isolation. The review model
+needs only the prepared input and a read-only checkout, never publication secrets.
+Codex requires its own supported sign-in or provider credentials and actual model
+access; CLI installation/sign-in alone cannot qualify it.
+
+The installed `task-review` tool separates preparation and publication from
+inference. It never invokes a model, changes model/provider settings, or posts a
+review request. These review transport steps are covered by offline tests; the
+intervening Codex execution and end-to-end publication are still unqualified:
+
+```sh
+task-review prepare --config /private/reviewer-config.json \
+  --url https://bitbucket.org/workspace/repo/pull-requests/7 > review-input.json
+```
+
+In the isolated reviewer checkout, use the operator-selected Codex executable
+under the existing read-only review permissions to inspect the input's exact
+head and diff. Follow `review-input.json.instructions`. Save its actual response
+as `review-result.json`, containing only this JSON shape:
+
+```json
+{
+  "head_sha": "0123456789012345678901234567890123456789",
+  "verdict": "blocking",
+  "summary": "Concrete findings from reviewing this exact commit."
+}
+```
+
+A successful model execution is not a verdict. Outside the model process, publish
+its response with the separate reviewer credential:
+
+```sh
+task-review publish --config /private/reviewer-config.json \
+  --url https://bitbucket.org/workspace/repo/pull-requests/7 \
+  --input review-input.json --result review-result.json
+```
+
+Publication verifies the authenticated actor differs from the coding author and
+matches `reviewer.actor_id`. It rechecks repository UUIDs, PR number, branches,
+base, full head SHA and diff hash against the prepared input. An explicit retry
+reuses an identical verdict only while it remains the reviewer's latest decision.
+A superseded match causes a new publication, so blocking/clear/blocking decisions
+take effect even on the same head. Uncertain comment writes are not silently
+retried. Keep the real model transcript/run ID with qualification
+artifacts: a manually authored fixture result cannot prove a Codex review.
+An ordinary Pipeline can orchestrate these steps when an operator explicitly
+installs it, enables Pipelines, and configures provider and reviewer secrets in an
+isolated trusted job. Do not expose those secrets to arbitrary PR code or the
+coding step. No paid Agentic Pipelines capability is assumed or installed.
+
+The posted comment contains a `work-review` fenced JSON block. Only the configured
+actor and a complete exact current SHA can clear readiness. Abbreviations, old-head
+approvals, prose claiming a successful Pipeline, or a run with no posted verdict
+are silence. Native Bitbucket approvals do not identify a reviewed commit and
+cannot clear an automated-review gate. Native change requests and unresolved tasks
+remain blockers until their authors remove/resolve them, including after one fix
+round has consumed their events.
+
+Trusted humans can post `/fix ...`. Inline findings use a verified code link to
+the full source SHA or a standalone `Reviewed commit: <40-character-sha>` line.
+Unknown inline heads stop readiness with the source link rather than silently
+approving or dispatching a guessed head. A command explicitly naming an older head
+is ignored. Replies authored by the coding account do not become new fix requests.
+
+## Session PR operations and recovery
+
+`task-pr` is the bounded PR CLI used by Bitbucket start/fix/resume prompts. In a
+task session it writes a bounded request to the checkout's mailbox; the daemon
+verifies the saved repository, branch, base and PR identity, then uses its own
+Git and API credentials. `push`, `create`, `edit` and `comment` push committed
+HEAD through the coordinator before publication. `view` and `diff` are read
+operations. The agent receives no Git or PR token and no SSH key in its
+environment. Its observed ability to read the token file remains a dispatch
+blocker. The
+coordinator disables checkout hooks when running Git, so an agent-written
+pre-push hook cannot run with coordinator authority. The mailbox has no merge,
+deployment or repository-settings operation. Direct `task-pr` use outside an
+agent session still requires an explicitly bound API credential.
+The PR CLI created and reconciled a disposable private PR, read its exact head,
+posted a comment and updated its body. A separate live public task also used it
+to open and update a regular PR. See the [qualification record](audit/bitbucket-review-qualification.md).
+
+After the credential boundary is qualified, local PRD commands use the verified
+checkout, and `register` uses the exact PR
+URL. Host-qualified state/worktree keys
+prevent a same-named GitHub repository controlling a Bitbucket PR. Base overrides
+flow through clone, PR publication and later base updates. Use `gallivant doctor`
+to confirm access and policy before `gallivant start <prd> --base <branch>`.
+Hosted providers with a GitHub-bound environment are incompatible. A snapshot
+provider must pass the same publication and qualification checks as a local one.
+
+Bitbucket snapshots supply one coherent set of paginated comments, participants,
+required tasks and statuses for the head. The shared event cursor, bounded fix
+round, session continuation, completion gate and chain engine consume those
+records. Unreadable snapshots preserve cursors. A changed PR branch/base or a
+replacement repository stops with `pr-identity`. Declined/superseded PRs cannot
+become done. A merged PR must match the recorded head and its merge commit must
+be an ancestor of the intended base before completion or chain advancement.
+No command merges the PR, force-pushes, deploys or alters protections.
+
+## Troubleshooting
+
+- `NO_CREDENTIAL`: select the account email and private API-token file under the
+  correct host/repository. An SSH key, GitHub token or token file without an email
+  is insufficient. Restore scopes before retrying; do not broaden another host.
+- `reviewer.actor_id` / explicit reviewer errors: use the actual UUID and producer
+  configuration, or explicitly choose no-reviewer mode. Do not use `@codex review`.
+- `BB_INCOMPLETE`, `BB_STALE`, HTTP 429/5xx: restore API access or wait for the read
+  retry. Never clear a cursor or turn missing evidence into an empty collection.
+- `REVIEW_UNQUALIFIED`: confirm the exact `harness.codex.bin`, selected model and
+  provider access, then explicitly run `review qualify --repo ... --run`. Do not
+  substitute `--version`, sign-in status or an offline fixture.
+- `review-incomplete` / `REVIEW_INCOMPLETE`: inspect the named missing identity,
+  path, patch or required job count. For a large complete text change, raise
+  `max_jobs` and `budget_usd` only within an operator-approved bound, then select
+  the new policy explicitly. Unsupported binary, subrepository, malformed link, rate-limited,
+  redirected or stale evidence must be corrected; increasing a byte cap is not a
+  workaround.
+- Screenshot evidence: check `review qualify --repo ... --capability image` for
+  the exact route. Repair the reported native or provider issue before a separately
+  authorized `--run`; do not repeat an unchanged failed launch. PNG/JPEG limits
+  and all image sides still apply. Unsupported formats remain incomplete.
+- `pr-identity`: inspect source/base/repository/head and restore the recorded
+  identity. A decline or unproven merge needs operator reconciliation, not a new
+  paid run or an automatic chain advance.
+- Access probe fails: check the selected coordinator SSH key or HTTPS token and
+  the account API token for PR operations. The coding session receives neither.
+  Re-run `doctor`, then resume the existing task rather than starting a duplicate.
+- PR mailbox timeout: confirm the daemon is running and can read the selected
+  repository; retry the same `task-pr` operation. Do not give the coding session
+  a token to work around the mailbox.
+
+API semantics are based on Atlassian's [PR APIs](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/),
+[commit ancestry API](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commits/),
+[source metadata](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-source/),
+and [account API-token guidance](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/).