@uchibeke/gallivant 0.2.1 → 0.3.0

package/README.md

@@ -19,10 +19,10 @@ Run this inside the Git checkout you want to work in:
 npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
 ```
 
-The setup flow below requires **0.2.1 or newer**. At verification on 2026-10-20,
-npm's `latest` was still 0.2.0, whose `init` only creates the config. A maintainer
-must [publish 0.2.1](docs/releasing.md) before this command provides repository
-registration, repeat safety and the diagnostic report described below.
+The setup flow below requires **0.2.1 or newer**. `npx` runs npm's latest published
+version. Changes merged on `main` become available through npm after a
+[versioned release](docs/releasing.md); check the registry with
+`npm view @uchibeke/gallivant version`.
 
 `init` writes a private config at `~/.gallivant/config.json`, records this
 repository, creates a separate directory for task checkouts, and ends with the
@@ -62,8 +62,8 @@ from you or an account with a third party.
 
 - **Reviewer.** The default loop waits for the Codex GitHub review integration
   (`chatgpt-codex-connector[bot]`). Enable it on the repository, configure
-  another reviewer, or set `"reviewer": null` in the config to rely on CI and
-  trusted human feedback. Without one of these, the first PR waits for a review
+  another reviewer, or opt into a [qualified first-party reviewer](docs/first-party-review.md).
+  Explicit legacy no-review needs both `"reviewer": null` and `review.legacy_no_review: true`. Without one of these, the first PR waits for a review
   that never arrives. See [the reviewer key](docs/config.md#the-reviewer-object).
 - **Branch protection.** `doctor` prints the `gh api` call that creates a
   ruleset blocking direct and force pushes to the default branch. Run it
@@ -80,14 +80,17 @@ from you or an account with a third party.
 
 ```sh
 gallivant task "Document how to run the existing tests in CONTRIBUTING.md. Use the commands already defined in the repository. Change documentation only." \
-  --harness codex --verify 'git diff --check' --run
+  --harness codex --verify 'git diff --check'
+# Review the draft, then substitute its returned task ID and revision:
+gallivant task start TASK_ID --revision REVISION --run
 gallivant start
 ```
 
-What happens: `task` uses your harness to prepare a brief, which is a paid
-inference call, and may ask you questions. `--run` authorizes implementation
-once the brief is ready; omit it to read the draft first and follow the printed
-`Next` action. The agent then works in a clone under `~/.gallivant-worktrees`,
+`task` uses your harness to prepare a brief, which is a paid inference call,
+and may ask you questions. Review the draft and answer any questions, then use
+its printed `Next` action to approve that revision with `task start --run`.
+Preparation always returns for review, even if its command includes `--run`.
+The agent then works in a clone under `~/.gallivant-worktrees`,
 pushes a branch, opens a PR against the default branch, and the daemon watches CI
 and the reviewer, sending each round of feedback back to the same session.
 `gallivant start` opens the dashboard at **http://127.0.0.1:8791** and keeps
@@ -119,7 +122,7 @@ and the same review loop. [Writing briefs](docs/prd.md) · [Task commands](docs/
 2. Each tick (every two minutes by default) the daemon reads CI and reviewer
    state. A blocking review or a failing check starts a fix round in the same
    agent session, and the fix is pushed to the same PR.
-3. Rounds stop at `max_iterations` (30 by default), when the reviewer stays
+3. Rounds stop at `max_iterations` (60 by default), when the reviewer stays
    silent for `stall_hours`, or when a run exceeds its timeout. Every stop is
    recorded with a reason you can read with `gallivant why`.
 4. **Ready** means the configured checks, reviewer and acceptance gate passed.
@@ -210,7 +213,7 @@ for the installed version's flags.
   daemon, including when execution is hosted. Gallivant is not a managed service.
 - **Your accounts pay for inference.** Subscriptions and API credits differ.
   There is no automatic provider fallback. Review [limits](docs/config.md) before
-  unattended work; the default review allowance is 30 rounds.
+  unattended work; the default review allowance is 60 rounds.
 - **Your permissions apply.** Scope GitHub access to the required repositories.
   Harness permissions, OS sandboxing and optional APort checks are different
   controls. [Security boundaries](docs/guardrails.md).
@@ -223,9 +226,20 @@ for the installed version's flags.
 
 ## Documentation
 
-[Getting started](docs/install.md) · [Agent setup](docs/agent-setup.md) ·
-[Commands](docs/commands.md) · [Configuration](docs/config.md) ·
-[Dashboard](docs/app.md) · [All guides](docs/README.md)
+| Need | Guide |
+| --- | --- |
+| Install and run your first task | [Getting started](docs/install.md) |
+| Start from a request, answer questions, inspect results | [Natural-language tasks](docs/tasks.md) |
+| Select the typed delivery profile and planner route for a request | [Typed delivery profiles](docs/task-profiles.md) |
+| Write a brief or define noncoding acceptance checks | [PRD contract](docs/prd.md) |
+| Use API-backed hosted execution | [OpenAI Agents](docs/openai-agents.md) |
+| Dashboard messages, controls and recovery | [Dashboard](docs/app.md) · [Commands](docs/commands.md) |
+| Models, credentials, limits and notifications | [Configuration](docs/config.md) |
+| Plan sequential work | [Chains](docs/chains.md) |
+| Embed task delivery in another application | [Task-delivery package](docs/task-delivery.md) |
+| Understand internals or recorded qualification | [Documentation index](docs/README.md) |
+| Set up from an agent | [Agent setup](docs/agent-setup.md) |
+| Release, contribute or report a vulnerability | [Releasing](docs/releasing.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) |
 
 **Asking a coding agent to set this up?** Give it the
 [setup-agent instructions](docs/agent-setup.md). They cover inspection, the
@@ -238,3 +252,11 @@ hosted service or publish a chat plugin.
 
 [Contributing](CONTRIBUTING.md) · [Security reports](SECURITY.md) ·
 [Releasing](docs/releasing.md) · [Apache-2.0 license](LICENSE)
+
+## Bitbucket Cloud
+
+Bitbucket Cloud tasks support the same independent local Codex review service as GitHub. The adapter captures an exact same-repository PR comparison through Bitbucket's commit, diffstat, merge-base and source APIs, then the shared service divides large evidence into bounded jobs. Activation still requires a successful live route qualification; until that and the disposable private/public review matrix pass, keep an existing run's explicit legacy no-review policy. A prior public disposable run qualified PR publication and receipt acceptance only, not semantic review. See the [setup, activation limits and troubleshooting guide](docs/bitbucket-review.md). Bitbucket-only setup needs no GitHub sign-in and does not install a pipeline or alter repository settings.
+
+## First-party review (opt-in)
+
+New tasks can pin `external-required`, `first-party-required`, or `both-required`. Repositories with the configured external reviewer retain their existing default. First-party review requires a separately qualified restricted route; it never claims Git-host bot approval. GitHub and Bitbucket Cloud are the only evidence adapters currently implemented. See [selection, qualification and migration](docs/first-party-review.md) and the [current live qualification gap](docs/audit/first-party-review.md). Existing no-review runs keep that requirement until the audited policy command changes them and disclose the absence of semantic review.

package/SECURITY.md

@@ -17,3 +17,12 @@ they need. Automatic approval is not equivalent to an operating-system sandbox.
 The [OpenAI Agents API adapter](docs/openai-agents.md) keeps service credentials
 on the coordinator and publishes returned artifacts through that coordinator.
 Its hosted execution controls differ from local harness hooks and sandboxes.
+
+## Bitbucket reviewer isolation
+
+Use a separate reviewer account and keep its publication credential outside the
+coding process's filesystem and environment access. A private file readable by
+the coding identity does not provide isolation. The review model receives the
+prepared diff and a read-only checkout; an operator publishes its exact-head
+verdict. See [reviewer setup](docs/bitbucket-review.md#independent-local-codex-reviewer).
+Bitbucket dispatch remains disabled pending live qualification.

package/bin/gallivant.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // CLI entry. Parses arguments, builds the context, calls one command. No logic lives here.
+import { reviewCommand } from "../lib/commands/review.mjs";
 import { acquireCliMutation } from "../lib/daemon.mjs";
 import { parseArgs } from "node:util";
 import { makeContext } from "../lib/context.mjs";
@@ -28,7 +29,7 @@ import { safeDisplay } from "../lib/learning_data.mjs";
 
 const HELP = `gallivant: give an agent a task, let the review loop run, go outside.
 
-  gallivant init [--harness codex|claude] [--worktrees <directory>]
+  gallivant init [--harness codex|claude] [--worktrees <directory>] [--host-config <json>] [--base <branch>]
                                          set up the repository you are in: private config, this repo in repos,
                                          then doctor's report. Safe to repeat; never signs in or overwrites settings
   gallivant --version                    print the installed version
@@ -51,15 +52,18 @@ const HELP = `gallivant: give an agent a task, let the review loop run, go outsi
                                          write a starting PRD into docs/prds/ of the repo you are in
   gallivant task [prepare] "<request>" [--stdin] [--dir <checkout>] [--repo <owner/repo>]
                 [--base <branch>] [--harness <name>] [--context <file>] [--request-id <id>] [--run] [--json]
-                [--completion-target delivery_ready|integrated] [--verify <command>] [--no-daemon]
-                                         prepare an isolated brief; --run authorizes its exact ready revision
+                [--completion-target delivery_ready|integrated] [--delivery pull_request] [--route harness|model]
+                [--verify <command>] [--no-daemon]
+                                         prepare an isolated brief for review; approve later with task start --run
+                                         --delivery selects the typed delivery profile (the only delivery authority);
+                                         --route drafts through the connected harness or the operator's bounded model route
                                          Claude, Codex and OpenAI Agents support isolated preparation.
                                          Other local harnesses use written PRDs; Codex Cloud dispatch is unavailable
   gallivant task answer <task-id> --revision <n> --request-id <answer-id> --answer <question-id=text>
                                          resume saved questions; --answer, --context and --verify may repeat
   gallivant task inspect <task-id> [--json] | task list [--json]
   gallivant task resume|validate|start <task-id> --revision <n> [--run] [--no-daemon] [--json]
-                                         shared versioned operations; start needs prior or --run authorization
+                                         shared versioned operations; start --run approves the reviewed revision
   gallivant ready <prd.md> [--check]     check the PRD against the contract; flip it to ready when it passes
   gallivant start [prd.md] [--no-daemon] [--no-server] [--no-open] [--port 8791] [--base <branch>]
                                          start the daemon and dashboard, then open it; optionally start a ready PRD
@@ -67,6 +71,7 @@ const HELP = `gallivant: give an agent a task, let the review loop run, go outsi
   gallivant register <pr-url> [--harness <name>] [--session <id>] [--worktree <dir>]
                                          watch a hand-made PR; on an existing entry, reset it
   gallivant chain <name> <prd1.md> <prd2.md> ... [--base <branch>]
+  gallivant chain <name> --after <pr-url|handle> <next.md> ...
                                          queue ready PRDs; each starts after the previous PR is merged
   gallivant chain [<name>] [--cancel | --retry [--resnapshot]]
                                          inspect chains, stop future work, or retry after fixing a blocker
@@ -81,6 +86,15 @@ const HELP = `gallivant: give an agent a task, let the review loop run, go outsi
                                          --resnapshot makes an edited brief the one the gate judges
                                          --fresh-session replaces retired learned memory after settlement
   gallivant recheck <handle>           queue a PR recheck without resetting its budget
+  gallivant review retry <handle> --reason <text>
+                                         retry confirmed incomplete or coordinator-cancelled review; retain pieces and limits
+  gallivant review qualify --repo <owner/repo> [--capability text|image] [--run [--wait] [--retry --reason <text>]]
+                                         inspect qualification; --run launches a bounded probe; --wait records its exit before returning
+  gallivant review status <handle>     show pinned policy, owned verdict and unresolved review evidence
+  gallivant review policy <handle> --mode external-required|first-party-required|both-required --reason "..."
+                                         explicitly replace policy and re-evaluate the current head
+  gallivant review dispute <handle> --finding <id> --reason "..."
+                                         record a dispute for a person; never accepts the author's own dispute
   gallivant cancel <handle>            stop further dispatch; request provider cancellation
   gallivant say <handle> --note "..." [--interrupt]
                                          send an update in the same session; --interrupt stops the active run first
@@ -94,15 +108,17 @@ const OPTIONS = {
   send: { type: "boolean" }, probe: { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
   "no-server": { type: "boolean" }, "no-open": { type: "boolean" }, foreground: { type: "boolean" }, worktrees: { type: "string" },
   "no-daemon": { type: "boolean" }, note: { type: "string" }, resnapshot: { type: "boolean" }, "fresh-session": { type: "boolean" }, interrupt: { type: "boolean" },
-  base: { type: "string" }, harness: { type: "string" }, session: { type: "string" }, worktree: { type: "string" }, dir: { type: "string" }, port: { type: "string" },
-  cancel: { type: "boolean" }, retry: { type: "boolean" },
+  base: { type: "string" }, after: { type: "string" }, harness: { type: "string" }, session: { type: "string" }, worktree: { type: "string" }, dir: { type: "string" }, port: { type: "string" },
+  cancel: { type: "boolean" }, retry: { type: "boolean" }, wait: { type: "boolean" },
   run: { type: "boolean" }, stdin: { type: "boolean" }, repo: { type: "string" }, revision: { type: "string" },
   "request-id": { type: "string" }, context: { type: "string", multiple: true },
-  "completion-target": { type: "string" },
+  "completion-target": { type: "string" }, delivery: { type: "string" }, route: { type: "string" },
   answer: { type: "string", multiple: true }, verify: { type: "string", multiple: true },
   since: { type: "string" }, until: { type: "string" }, "dry-run": { type: "boolean" },
   mode: { type: "string" }, status: { type: "string" }, from: { type: "string" }, reason: { type: "string" },
+  "host-config": { type: "string" },
   "key-path": { type: "string" }, "ssh-keygen": { type: "string" }, "learning-budget": { type: "string" },
+  finding: { type: "string" }, capability: { type: "string" },
 };
 
 async function dispatch(argv) {
@@ -111,9 +127,10 @@ async function dispatch(argv) {
   const [cmd, arg] = positionals;
   if (values.version) { console.log(VERSION); return 0; }
   if (values.help || !cmd || cmd === "help") { console.log(HELP); return 0; }
+  if (values.after !== undefined && (cmd !== "chain" || !values.after.trim())) throw new Error("--after requires a registered PR URL or handle when queuing a new chain");
   if (cmd === "init") {
     if (arg) throw new Error("init takes no positional argument; run it from inside the target checkout");
-    const r = await init({ harness: values.harness, worktrees: values.worktrees });
+    const r = await init({ harness: values.harness, worktrees: values.worktrees, hostConfig: values["host-config"], base: values.base });
     const report = renderDoctor(r.doctor);
     console.log(renderInit(r, report));
     // Doctor's exit code, so a script or an agent reading only the status knows whether setup still has open items.
@@ -165,7 +182,7 @@ async function dispatch(argv) {
     }
   }
   const ctx = makeContext();
-  const mutating = ["start", "resume", "register", "remove", "recheck", "say", "cancel"].includes(cmd) || cmd === "chain" && (positionals.length > 2 || values.cancel || values.retry);
+  const mutating = ["start", "resume", "register", "remove", "recheck", "say", "cancel"].includes(cmd) || cmd === "review" && arg !== "status" || cmd === "chain" && (positionals.length > 2 || values.cancel || values.retry);
   const owner = mutating ? acquireCliMutation(ctx.home) : null;
   try {
   if (cmd === "recheck" || cmd === "say" || cmd === "cancel") {
@@ -180,6 +197,11 @@ async function dispatch(argv) {
     return 0;
   }
   switch (cmd) {
+    case "review": {
+      const result = await reviewCommand(ctx, { action: arg, handle: positionals[2], repo: values.repo, mode: values.mode, reason: values.reason, finding: values.finding, run: values.run, capability: values.capability, retry: values.retry, wait: values.wait });
+      console.log(JSON.stringify(result, null, 2));
+      return result.qualified === false ? 1 : 0;
+    }
     case "chain": {
       const paths = positionals.slice(2);
       const operation = paths.length > 0 || values.retry;
@@ -188,7 +210,8 @@ async function dispatch(argv) {
       if (values.retry && paths.length) throw new Error("--retry uses the existing plan; do not pass PRD paths");
       if ((values.cancel || values.retry) && !arg) throw new Error("a chain name is required");
       if (values.base && !paths.length) throw new Error("--base is set when queuing a new chain");
-      if (paths.length) await queueChain(ctx, { name: arg, paths, base: values.base });
+      if (values.after && (!paths.length || values.retry || values.cancel)) throw new Error("--after is set only when queuing a new chain with ready PRD paths");
+      if (paths.length) await queueChain(ctx, { name: arg, paths, base: values.base, after: values.after });
       else if (values.cancel) cancelChain(ctx, arg);
       else if (values.retry) await retryChain(ctx, { name: arg, resnapshot: values.resnapshot });
       console.log(renderChains(ctx, arg));

package/bin/promote-bitbucket.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFile, writeFile } from "node:fs/promises";
+import { makeContext } from "../lib/context.mjs";
+import { promote } from "../lib/promotion.mjs";
+import { makePromotionTransfer } from "../lib/promotion_git.mjs";
+
+const help = `Usage: npm run promote:bitbucket -- --github-pr URL --bitbucket-repo bitbucket.org/workspace/repo [--bitbucket-pr N] [--base main] [--branch name] [--out plan.json]
+Default: read-only dry run. Inspect the plan, then add --apply --expected-plan DIGEST.
+Merged sources use retained exact acceptance. If the reported base changed, --accepted-plan plan.json supplies an optional archived-base fallback.
+No force push, merge or deployment. See docs/bitbucket-promotion.md.`;
+let transfer;
+try {
+  const { values } = parseArgs({ options: {
+    "github-pr": { type: "string" }, "bitbucket-repo": { type: "string" }, "bitbucket-pr": { type: "string" },
+    base: { type: "string" }, branch: { type: "string" }, out: { type: "string" }, "accepted-plan": { type: "string" },
+    apply: { type: "boolean", default: false }, "expected-plan": { type: "string" }, help: { type: "boolean", short: "h" },
+  } });
+  if (values.help) console.log(help);
+  else {
+    if (!values["github-pr"] || !values["bitbucket-repo"]) throw new Error(help);
+    if (values.apply && values.out) throw new Error("--out saves a dry-run plan only; omit it when applying");
+    let acceptedPlan;
+    if (values["accepted-plan"]) {
+      const text = await readFile(values["accepted-plan"], "utf8");
+      if (Buffer.byteLength(text) > 1_048_576) throw new Error("Accepted plan is oversized");
+      acceptedPlan = JSON.parse(text);
+    }
+    const ctx = makeContext({ readOnly: true });
+    transfer = await makePromotionTransfer(ctx);
+    const result = await promote(ctx, {
+      githubPr: values["github-pr"], bitbucketRepo: values["bitbucket-repo"],
+      ...(values["bitbucket-pr"] !== undefined ? { bitbucketPr: Number(values["bitbucket-pr"]) } : {}),
+      branch: values.branch, base: values.base, acceptedPlan, apply: values.apply, expectedPlan: values["expected-plan"],
+    }, transfer);
+    if (values.out) await writeFile(values.out, `${JSON.stringify(result.plan, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    console.log(JSON.stringify(result, null, 2));
+  }
+} catch (error) { console.error(error.message); process.exitCode = 1; }
+finally { await transfer?.close(); }

package/bin/task-pr.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { prOperation } from "../lib/pr_operation.mjs";
+try {
+  const result = await prOperation(process.argv.slice(2));
+  console.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/bin/task-review.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { makeBitbucketReviewProducer } from "../lib/hosts/bitbucket_review_producer.mjs";
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: Object.fromEntries(["config", "url", "input", "result"].map(key => [key, { type: "string" }])) });
+  if (positionals.length !== 1 || !["prepare", "publish"].includes(positionals[0]) || !values.config || !values.url) throw new Error("Use task-review prepare|publish --config <private-reviewer-config> --url <exact-PR-URL> [--input <prepared-json> --result <verdict-json>]");
+  const json = path => JSON.parse(readFileSync(path, "utf8"));
+  const producer = makeBitbucketReviewProducer({ config: json(values.config) });
+  const result = positionals[0] === "prepare" ? await producer.prepare(values.url) : await producer.publish(values.url, json(values.input), json(values.result));
+  console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/docs/README.md

@@ -17,9 +17,11 @@ requirements and checks.
 | Install, configure access and complete a first task | [Getting started](install.md) |
 | Ask an agent to inspect, install and verify setup | [Agent setup](agent-setup.md) |
 | Describe work, answer questions, inspect a draft and authorize execution | [Natural-language tasks](tasks.md) |
+| Choose the typed delivery profile, planner route and review a prepared task | [Typed delivery profiles](task-profiles.md) |
 | Write a brief with acceptance criteria, source files and verification commands | [PRD contract](prd.md) |
 | Find commands, monitor progress, message or resume a run | [Commands](commands.md) |
 | Configure repositories, credentials, harnesses and execution limits | [Configuration](config.md) |
+| Request and verify Codex reviews against the current commit | [Codex review procedure](codex-review.md) |
 | Use the local dashboard and understand product boundaries | [Application](app.md) |
 | Run coding work on an API-backed hosted environment | [OpenAI Agents API](openai-agents.md) |
 | Understand the unavailable Codex Cloud dispatch and its required qualification | [Codex Cloud](codex-cloud.md) |

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.