@uchibeke/gallivant 0.2.0 → 0.3.0

package/README.md

@@ -2,86 +2,105 @@
 
 **Give an agent a task. Let the review loop run. Go outside.**
 
-Gallivant turns repository tasks into reviewed pull requests. It starts an agent,
-watches CI and reviewer feedback, and continues the same session to fix issues.
-You can follow progress and send corrections from a local dashboard. **You decide
-what gets merged.**
-
-Use it for code, documentation, research or content that belongs in a GitHub
-repository. Start with a plain-language request or a written brief.
+Gallivant turns a repository task into a reviewed pull request. It runs a coding
+agent in a separate checkout, opens the PR, watches CI and reviewer feedback, and
+continues the same session until the PR is ready for you. You decide what merges.
 
 ```text
 Your task → agent works → PR → review + CI → fixes → ready for you
                                  ↑___________|
 ```
 
-## Install
-
-You need **macOS or Linux, Node 22+, Git, GitHub CLI and jq**. For your first run,
-use signed-in **Codex CLI 0.160.0+** or **Claude Code 2.1.263+**. Provider usage is
-billed to your own account. [Full prerequisites](docs/install.md).
+## Set up in one command
 
-Check the [registry version](https://www.npmjs.com/package/@uchibeke/gallivant). Once a
-version is available, install it with `npm install -g @uchibeke/gallivant`. If the package
-is not published yet, install from source:
+Run this inside the Git checkout you want to work in:
 
 ```sh
-git clone https://github.com/uchibeke/gallivant.git
-cd gallivant
-npm ci --ignore-scripts
-npm link
-gallivant --version
+npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
 ```
 
-[Release status and checks](docs/releasing.md).
+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`.
 
-## Set up
+`init` writes a private config at `~/.gallivant/config.json`, records this
+repository, creates a separate directory for task checkouts, and ends with the
+same report as `gallivant doctor`: one line per check and the exact fix for each
+failing one. Run it again in another repository to add that repository; nothing
+else in the config changes.
 
-```sh
-gh auth status
-codex login status                    # use Claude sign-in if you choose Claude
-gallivant init --harness codex         # or --harness claude
-gallivant doctor
-```
+Before you run it you need:
 
-`init` creates local configuration and a separate task-checkout directory. It
-preserves existing config, credentials and global agent settings. Follow the
-fixes from `doctor`; [setup instructions](docs/install.md) cover authentication,
-harness permissions and repository protection.
+| Prerequisite | Check | If it fails |
+| --- | --- | --- |
+| macOS or Linux, Node 22+, Git, jq | `node --version`, `git --version`, `jq --version` | install from your package manager |
+| GitHub CLI signed in | `gh auth status` | `gh auth login` |
+| Codex CLI 0.160.0+ signed in | `codex login status` | `codex login` |
+| or Claude Code 2.1.263+ signed in | `claude auth status` | `claude auth login` |
 
-Enable the Codex GitHub review integration on the target repository, or choose
-another reviewer. If you want CI and trusted human feedback without a review bot,
-explicitly configure `"reviewer": null`. The default waits for Codex review.
+A signed-out `gh` or harness stops `init` before it writes anything, and the
+message repeats the login command above. `init` never asks for passwords, tokens
+or browser cookies; sign in with each tool's own flow. Inference is billed to
+your own provider account.
 
-**Prefer an agent to handle setup?** Give it the
-[setup-agent instructions](docs/agent-setup.md). They cover inspection, installation,
-configuration, verification and the points where your input is required.
+`npx` downloads and runs the package on demand. Nothing is installed globally
+and no `gallivant` command is added to your PATH. If you want one:
 
-## Run your first task
+```sh
+npm install -g @uchibeke/gallivant
+```
 
-Inside a repository you can push to. This example uses Codex; if you configured
-Claude, replace `--harness codex` with `--harness claude` before running it:
+The rest of this page writes `gallivant`. With `npx`, read that as
+`npx --yes @uchibeke/gallivant`. Contributors who want to run from a source
+checkout: see [installing from source](docs/install.md#install-from-source).
+
+## Finish what setup cannot do for you
+
+`doctor` names these. `init` does not do them, because each needs a decision
+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 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
+  yourself. Setup never changes repository settings.
+- **Harness guardrails.** The APort hook for Claude or Codex is installed by its
+  own `npx @aporthq/aport-agent-guardrails` command, and Codex asks you to trust
+  the hook inside its own interface. Setup does not install hooks.
+  [Guardrails](docs/guardrails.md) explains what each control covers.
+- **Spend.** Defaults are 30 fix rounds per PR and a 5 USD per-run cap that
+  only Claude enforces natively. Review [limits](docs/config.md) before
+  unattended work.
+
+## Run a first task
 
 ```sh
-cd /path/to/your/repository
 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
 ```
 
-`task` prepares a brief and asks for missing information. `--run` authorizes
-implementation when that brief is ready, including after clarification. Omit it
-to inspect the draft first. Follow the printed `Next` action using your task's ID
-and revision. Preparation also uses inference.
-
-`gallivant start` opens **http://127.0.0.1:8791** and ensures the daemon is running.
-Without a PRD path, it does not submit another task. Closing the browser does not
-stop the work.
-
-With the default configuration, **ready** means the configured checks, reviewer
-and acceptance gate passed. Inspect status for skipped-gate warnings, review the
-PR and merge when you choose. Missing access, evidence or exhausted limits produce
-an inspectable stop instead.
+`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
+the daemon running; closing the browser does not stop the work.
+
+Expected outcome: a PR with a small CONTRIBUTING.md change and a completion
+receipt in its body, and `gallivant status` showing the entry as **ready** once
+checks, reviewer and the acceptance gate pass. You review and merge. Missing
+access, failing checks or an exhausted round allowance produce an inspectable
+stop instead; `gallivant why <handle>` explains it.
 
 ### Bring a written brief
 
@@ -96,6 +115,20 @@ gallivant start docs/prds/add-csv-export.md
 You do not have to write a PRD yourself. Both entry points use a validated brief
 and the same review loop. [Writing briefs](docs/prd.md) · [Task commands](docs/tasks.md).
 
+## How the review loop runs
+
+1. The agent implements the brief, runs the brief's verification commands and
+   opens the PR.
+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` (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.
+   Nothing merges automatically. Natural-language tasks stop at a review
+   handoff by default; choose `integrated` to keep watching until you merge.
+
 ## While it works
 
 | What you need | Action |
@@ -128,6 +161,9 @@ base. You can plan longer work while retaining the merge decision.
 
 ## Harness support
 
+`init --harness` accepts `codex` and `claude`. Other adapters are configured by
+hand in `config.json`; see [configuration](docs/config.md#execution-providers).
+
 | Harness (`harness` key) | Runs on | Prepare requests | Implementation status |
 | --- | --- | --- | --- |
 | Claude Code (`claude`) | Your host | Yes | Recommended; live usage evidence |
@@ -177,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).
@@ -190,9 +226,25 @@ 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
+`npx` command, the points where your login or decision is required, and what a
+setup run may not do on its own.
 
 Embedding the same workflow in another application? See
 [task delivery](docs/task-delivery.md). Installing this CLI does not deploy a
@@ -200,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";
@@ -15,7 +16,7 @@ import { newPrd } from "../lib/commands/new.mjs";
 import { resume } from "../lib/commands/resume.mjs";
 import { startServices } from "../lib/commands/start_services.mjs";
 import { trackerPort, stopTracker } from "../lib/tracker_process.mjs";
-import { init } from "../lib/commands/init.mjs";
+import { init, renderInit } from "../lib/commands/init.mjs";
 import { VERSION } from "../lib/fs.mjs";
 import { hasConfig } from "../lib/config.mjs";
 import { resolveHandle } from "../lib/state.mjs";
@@ -28,8 +29,9 @@ 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>]
-                                         create a private config; never overwrite settings or sign in for you
+  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
   gallivant doctor [--send] [--probe]   install checklist and health probe
   gallivant doctor --network <https-origin> [--json]   bounded DNS/HTTPS diagnosis
@@ -50,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
@@ -66,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
@@ -80,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
@@ -93,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) {
@@ -110,10 +127,14 @@ 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") {
-    const r = await init({ harness: values.harness, worktrees: values.worktrees });
-    console.log(`Created ${r.file}\nHarness: ${r.harness}\nWorktrees: ${r.config.worktrees}\n\nNext: gallivant doctor\nComplete the harness guardrail and repository setup before starting work:\n  https://github.com/uchibeke/gallivant/blob/main/docs/install.md\nPackaged templates:\n  ${r.templates.passport}\n  ${r.templates.sandbox}`);
-    return 0;
+    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, 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.
+    return report.exitCode;
   }
   if (values.foreground && cmd !== "serve") throw new Error("--foreground is available only with serve");
   if (values.foreground && values["no-server"]) throw new Error("--foreground cannot be combined with --no-server");
@@ -161,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") {
@@ -176,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;
@@ -184,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

@@ -1,7 +1,9 @@
 # Documentation
 
-Start with [installation and your first run](install.md), then choose how to
-describe the work. [Natural-language tasks](tasks.md) prepare a reviewable brief
+Start with [installation and your first run](install.md): inside the target
+checkout, `npx --yes @uchibeke/gallivant init --harness codex` (or
+`--harness claude`) writes the config, records the repository and prints the
+setup report. Then choose how to describe the work. [Natural-language tasks](tasks.md) prepare a reviewable brief
 from your request; [hand-authored PRDs](prd.md) let you write that brief directly.
 Both use the same validation, execution, GitHub review and completion workflow.
 Code, research and documentation can all be delivered as verifiable repository
@@ -15,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) |