@uchibeke/gallivant 0.2.1 → 0.3.0

package/docs/git-hosts.md

@@ -0,0 +1,294 @@
+# Git host boundary
+
+For a GitHub review mirror that delivers through Bitbucket, see the [explicit branch promotion workflow](bitbucket-promotion.md). It preserves reviewed commits and uses the existing host/review services.
+
+`github.com` supports task dispatch. Bitbucket's explicit no-reviewer path
+completed live local Codex tasks through PR publication and receipt acceptance
+on disposable public and private repositories, but its coding session could
+read the selected merge-capable token file. General Bitbucket dispatch remains
+unqualified while credential isolation is repaired. Independent Bitbucket
+review and clean Linux installation also remain unvalidated. Other hosts remain
+unsupported. The synthetic adapter in
+`test/git-host.test.mjs` is an offline contract fixture, not a supported host.
+
+`lib/host_definitions.mjs` owns the static host catalogue. `lib/hosts.mjs` binds
+its declarations to Node transport implementations. Portable views and task
+profiles read the same declarations without importing Node or credential code. It is independent of both the harness
+registry and execution transports. Shared code obtains `hostApi(context)` and
+selects a repository for dispatch through `context.hosts.select(...)`. Setup and
+transport tools use `inspect(...)` or `inspectRemote(...)`; these do not qualify
+the host for dispatch. The old `context.gh`
+property is retained as an integration/test compatibility seam. New lifecycle
+code must not use it. GitHub CLI commands, wire normalization, prompt commands,
+learning endpoints and rulesets belong to `lib/gh.mjs`, `lib/hosts/github.mjs`
+and the GitHub diagnostics feature module.
+
+## Identity and compatibility
+
+`repository.mjs` parses HTTPS, HTTP (historical GitHub input, upgraded before use),
+scp-style SSH and `ssh://` input. It rejects ambiguous authorities, ports,
+queries, fragments, encoded path characters, traversal and unsupported schemes.
+It never embeds rejected input in errors. HTTPS userinfo is discarded; it is
+never a credential source. Canonical records contain `host`, `path`,
+`remoteIdentity` (`host/owner/repository`) and `key`.
+
+The historical GitHub key remains `owner/repository`; another qualified host's
+key is `host/owner/repository`. Entry IDs, worktree paths and run folder names
+include that key. Existing GitHub IDs, branch prefixes, cursors, receipt hashes,
+PR metadata and chain ownership tokens are read without rewriting them.
+Review/inline/comment IDs keep their old cursor keys, such as `review:42`.
+A short handle still works when it identifies exactly one entry. Ambiguity
+requires `host/owner/repository#number`. Contradictory saved identities and duplicate
+PR ownership stop with a backup/reconciliation instruction; no automatic
+migration, cursor reset or redispatch repairs them.
+
+## Adapter declaration
+
+Each registry declaration supplies:
+
+| Field | Contract |
+| --- | --- |
+| `host`, `id` | Canonical authority and stable completion-evidence adapter ID |
+| `capabilities` | Required evidence and optional decoration, separately declared |
+| `credential(config, repository)` | Resolve current API/HTTPS authorization for the bound host; never cache at daemon boot |
+| `remote(repository)` | Verified clone URL, protocol, host and repository path |
+| `create(options)` | Repository/API operations with injected transport and credentials |
+| `parsePr(url)`, `prUrl(repository, number)` | Strict PR routing and canonical UI links |
+| `prompts` | Host-specific create, inspect, CI-log and receipt-edit instructions |
+| `dataContract` | `host-records-v1` |
+
+Required capabilities are `pullRequests`, `reviews`, `comments`, `checks`,
+`diff`, `mergeProof` and `recovery`. Missing required capabilities fail closed.
+`labels` is optional: an adapter without labels does not block readiness.
+GitHub retains its existing retry semantics for label writes. Learning and
+ruleset operations are GitHub features, not mandatory adapter methods.
+
+Repository operations cover branch/default-branch and permission reads, exact
+ref/ancestry proof, file reads, PR view/list/diff, review/comment pages, comments,
+body/title/recovery writes, ready-for-review and idempotent publication.
+`fileAtStrict` distinguishes a missing file from inaccessible or incomplete
+content. The shared chain engine requires the exact merge commit to be an
+ancestor of the intended base; a closed PR never authorizes a successor.
+
+First-party review additionally requires `reviewEvidence(repo, pr, head, base,
+maxBytes)`: complete diff and before/after changed-file content, including
+deletions, bound to exact head, base and merge-base IDs. Qualification and
+reconciliation refuse adapters without this operation before launching a
+first-party reviewer or reusing its clearance. External-only and explicit
+no-reviewer policies do not require this method. Evidence reads and policy/dispute label writes
+use the same repository registry and credential binding as other lifecycle
+operations. Review jobs and verdicts remain coordinator-owned.
+
+## Domain records and completeness
+
+Every normalized record carries `source` (host and adapter), `actor` (login and
+bot flag), `eventId`, `headSha`, `createdAt` and `updatedAt`. Unknown optional
+values are explicit nulls. Review/comment records also carry `at`, `reviewId`
+and `replyTo`. Their original numeric `id` remains stable for saved cursors.
+CI records expose `outcome: passed | failed | pending`, name, URL and optional
+run ID. Wire-specific CI classification exists only in the adapter.
+
+PRs retain the established domain field names (`headRefOid`, `headRefName`,
+`baseRefName`, `state`, `mergeCommit`, `mergedAt`, `statusCheckRollup`, body,
+author and URL). These are contract fields, not permission to import a host
+client. The GitHub adapter keeps legacy event aliases for existing consumers;
+the review engine accepts the canonical actor, head and timestamp fields too.
+
+A list is either a complete array or `{ items, complete: true }`. Incomplete
+pages, absent CI, rate limits, authentication failures and unreadable diffs
+throw before a readiness decision. GitHub pagination uses bounded subprocess
+output; PR list/check limits are refused at their cap. Shared retries preserve
+cursors, dispatch ownership and the last known decision. Optional decorations
+never supply review, CI or merge evidence. The shared loop has one reviewer
+verdict and one CI outcome predicate for every qualified host.
+
+## Transport and provider binding
+
+The shared Git layer clones with native `git clone --filter=blob:none`. The
+GitHub policy converts accepted GitHub SSH/HTTP inputs to verified HTTPS; no
+shared Git method constructs a GitHub URL. Existing fetch, base selection,
+operator commit identity, isolated configuration and push behavior remain.
+Origin and push destinations are checked against the repository identity before
+credentialed network operations.
+
+The HTTPS helper reads Git's requested protocol, host and repository path before
+returning the bound token. It resets repository credential helpers, refuses
+redirects and receives secrets only through environment variables. Clone URLs,
+argv, committed files and public diagnostics contain no token. A run clears
+inherited API tokens and SSH channels. Bitbucket supports an explicitly selected
+SSH key for coordinator Git operations; an SSH key alone cannot authorize the PR
+API. The coordinator may clone and push over selected SSH or HTTPS. The coding
+session receives neither the repository API token nor the SSH key. Its bounded
+checkout mailbox requests validated push and PR operations from the coordinator.
+Coordinator Git disables checkout hooks before using a privileged credential.
+Setup never grants a sandbox extra key paths.
+GitHub resolution order remains configured token file, daemon environment,
+then `gh auth token`, with explicit-file failure refusing fallback. Resolution
+happens for each operation so reauthentication works without restarting.
+
+Providers declare `repositoryAccess`: `local-worktree`, `snapshot`, or
+`bound-host` with allowed authorities. The shared pre-dispatch check enforces it
+before clone or paid preparation. A local-worktree provider needs no adapter
+change to use another qualified host. No host-by-harness switch table exists.
+
+## Regression evidence
+
+`test/git-host.test.mjs` exercises canonical identity, saved state, collisions,
+normalized feedback, provider access, native clone, token isolation, failure
+preservation and a synthetic host through readiness and chain merge proof.
+`test/git-host-architecture.test.mjs` rejects direct host CLI/API imports or
+prompt commands and a second host-specific review/CI branch in shared modules.
+The existing review, recovery, receipt, chain and execution suites retain
+coverage for bounded retries and idempotent writes. All these tests are offline
+and make no model calls.
+
+
+## Bitbucket Cloud setup
+
+Configure credentials explicitly in `git_hosts["bitbucket.org"]`. Existing
+`github_token_file` resolution is unchanged and is never tried for Bitbucket.
+No `gh` installation or GitHub sign-in is required for a Bitbucket-only config.
+Use an Atlassian account API token; repository access tokens are not required.
+Request `read:repository:bitbucket`, `write:repository:bitbucket`,
+`read:pullrequest:bitbucket` and `write:pullrequest:bitbucket`, limited to the
+selected workspace where available. Reads do not prove write scopes: diagnostics
+report them as unknown until the corresponding write, which surfaces permission
+errors and never silently switches credentials.
+
+```json
+{
+  "git_hosts": {
+    "bitbucket.org": {
+      "api": {
+        "email": "operator@example.com",
+        "token_file": "~/.config/repository-access/bitbucket-api-token"
+      },
+      "git": { "transport": "https" }
+    }
+  },
+  "repos": [{ "repo": "bitbucket.org/workspace/repository", "base": "release/v2" }]
+}
+```
+
+Keep the existing harness, operator identity, worktrees and other config settings.
+Token files must be private (`chmod 600`). HTTPS Git uses the selected API token
+unless `git.token_file` explicitly selects a separate private token file. Git's
+helper returns the token only for HTTPS on `bitbucket.org` and the exact repository;
+it uses the account-token Git username `x-bitbucket-api-token-auth`. API requests
+use account email plus token over HTTPS to `api.bitbucket.org`, with redirects
+refused. API and Git authorization may differ, but the base commit observed through
+Git must match the API repository and base.
+
+For SSH, use this `git` block instead:
+
+```json
+{
+  "transport": "ssh",
+  "ssh_key": "~/.config/repository-access/bitbucket-key",
+  "known_hosts": "~/.config/repository-access/bitbucket-known-hosts"
+}
+```
+
+Select an unencrypted dedicated key that the coordinator can read, with mode 600.
+No SSH agent or global SSH configuration is used. The dedicated known-hosts file
+must contain only `ssh.bitbucket.org` entries matching Atlassian's published
+SHA256 fingerprints. Get candidate public keys from `https://bitbucket.org/site/ssh`,
+select the `ssh.bitbucket.org` lines and independently check their fingerprints
+against [Atlassian's SSH host-key documentation](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/).
+Do not accept an unverified `ssh-keyscan` result. A host-key rotation stops access
+until the published pins and selected file are reviewed. Strict verification is
+always enabled. Existing `git@bitbucket.org:workspace/repo.git` origins and the
+new `git@ssh.bitbucket.org:workspace/repo.git` origins resolve to one Cloud identity;
+clones use the new endpoint described in [Atlassian's SSH migration notice](https://developer.atlassian.com/cloud/bitbucket/changelog/).
+Self-hosted servers, custom SSH aliases and alternate ports are unsupported.
+
+Run `init` from the checkout to bind the API repository UUID and workspace UUID
+under the host's `repositories` map, or run `doctor` for read-only diagnostics.
+Setup checks repository access, the selected base, effective account push role,
+PR reads, comments when a PR exists, branch restrictions where visible, and native
+Git access to the same base. The account role comes from the
+[authenticated user's repository permissions](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-user-workspaces-workspace-permissions-repositories-get),
+filtered by repository UUID, using repository read scope without workspace-admin access.
+An archive flag, if supplied, is enforced; the Cloud
+repository schema does not currently expose that flag consistently, so absence
+is reported as unknown. A missing API credential reports missing PR/comment
+capability even when an SSH key is configured. A successful transport check is
+followed by an explicit failed dispatch check. No paid model probe is needed for
+this milestone, and `init` does not recommend starting a task on an unqualified host.
+
+API credentials are reread for every operation. A changed email, account UUID on
+successive permission reads, repository UUID,
+workspace UUID, canonical slug or API clone target stops access. Restore the
+previous binding, or inspect the new identity and explicitly edit the binding;
+setup never silently migrates a renamed or transferred repository.
+
+## Bitbucket evidence and publication bounds
+
+`lib/hosts/bitbucket.mjs` owns API shape and pagination differences. PR snapshots
+include source/destination UUIDs, branches and commits, draft state, host state
+(`OPEN`, `MERGED`, `DECLINED` or `SUPERSEDED`), title/description, diff, comments,
+reviewer participants, tasks and statuses tied to the current head. Declined and
+superseded PRs normalize to `CLOSED`, preserving `hostState`. UUID-based actor
+identity avoids nickname ambiguity. These observations do not qualify reviewer
+trust, CI policy, recovery or merge proof for dispatch.
+Build statuses use the [documented commit link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commit-statuses/#api-repositories-workspace-repo-slug-commit-commit-statuses-get)
+to confirm the queried repository and head; missing or mismatched links stop the snapshot.
+PR list responses omit reviewer and participant collections. Bounded list results
+are expanded through repository-scoped PR detail reads before normalization;
+preflight also reads the selected PR's details before checking comment access.
+Missing or inaccessible detail records stop the operation, and a failed read after
+publication preserves the unresolved write until reconciliation succeeds.
+
+Reads are bounded to 100 pages and 10,000 items per collection, 4 MiB per JSON
+response, a diff smaller than 16 MiB, and 20 seconds per request. Missing fields,
+cycles, changed filters, size inconsistencies, rate limits, foreign pagination,
+redirects and changed PR identity/head during a snapshot produce explicit errors.
+The documented diff redirect is allowed only into the same repository's diff
+endpoint. Failures never become empty reviews or successful checks.
+
+Publication uses the existing public-text validator, exact repository UUIDs and
+source/base names. It checks PRs in all states before every publication, updates one matching open PR,
+and refuses forks, closed predecessors, conflicting bases or duplicate ownership.
+Writes address immutable workspace/repository UUIDs so a concurrent slug change
+cannot redirect a write into a replacement repository. Every write is
+followed by reconciliation, including timeouts after acceptance. An unresolved
+create remains blocked in that adapter instance until a matching PR is observed;
+a restart still reads before any write. Concurrent publication in one instance
+is refused. There is no fork creation, merge, force push or repository-settings API.
+Comments are never automatically retried after an uncertain write.
+
+Offline coverage: `test/bitbucket.test.mjs`, `test/bitbucket-fixture.mjs` and
+`test/host-transport-contract.test.mjs`. The shared contract assertions run against
+both production adapters with injected wire responses. No fixture test calls a
+model or writes to a live repository. Live review-loop qualification remains a
+separate milestone.
+
+API references: [repositories](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/),
+[pull requests](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/),
+and [account-token authentication](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/).
+
+## Review-loop implementation and ship gate
+
+The [Bitbucket review guide](bitbucket-review.md) supersedes transport-only setup
+examples for reviewer/trust/check policy. `init --host-config <json> --base <branch>`
+can bootstrap an empty config, with an explicit reviewer (or `null`) and stable
+trusted UUIDs. The adapter now implements review normalization, required task
+blockers, recovery operations and merge ancestry. The explicit no-reviewer
+dispatch path has [disposable live observations](audit/bitbucket-review-qualification.md),
+but credential isolation failed; independent review and clean Linux installation
+remain unvalidated. Do not enable general dispatch from these observations.
+
+`prView` may include `feedback: { complete: true, headSha, reviews, inline, comments }`.
+The shared loop consumes this one coherent snapshot; adapters without it retain
+the previous collection methods. Strict records declare `headBinding: "exact"`
+and an explicit `verdict`; PR-wide required tasks declare `required: true` and
+`headBinding: "pull-request"`. Stable `sequence` values disambiguate verdicts that
+share a timestamp. `strictIdentity` requests recorded branch/base/head and terminal
+merge checks. These are domain contract fields, not host-name branches in the
+scheduler. GitHub's historical event keys and review interpretation are retained.
+
+A future GitLab adapter must implement the same complete records, explicit policy,
+strict URL/credential binding, publication, file reads, and merge proof. Add its
+static definition/implementation and shared-contract tests, then qualify it live
+with a compatible provider. Until then GitLab and unregistered hosts fail before
+dispatch. Host, harness and inference provider remain separate configuration axes.

package/docs/guardrails.md

@@ -309,3 +309,59 @@ that a tool call was denied. The historical findings are linked below.
 ## Follow-ups filed against APort
 
 The historical [decision record](https://github.com/uchibeke/gallivant/blob/main/docs/audit/DECISIONS.md) lists: multi-file `apply_patch` in the Codex hook, `git push` refspec parsing, control-plane paths blocked by default, a non-interactive local passport install, and a Repository Guard slice that blocks pushes rather than reporting merges.
+
+## Reviewer authority
+
+The opt-in first-party reviewer uses the restricted native preparation boundary in a fresh session with supplied evidence only. Image jobs additionally require their own capability qualification and a verified coordinator-created copy. Its profile denies tools, escalation, delegation and tool network access; setup/start verify effective native policy and require a live qualification record. A private HOME or a prompt alone is not sufficient. The model cannot write task policy, state, files, Git refs, PRs or approvals. The coordinator validates exact-input structured output; public agent text is never an independent host actor. Unknown or partial output fails closed. See [review isolation, evidence and monetary limitations](first-party-review.md) and [unmet live qualification](audit/first-party-review.md). Review grants no merge or deployment authority.
+
+Repository identity, credential transport and PR evidence are defined by the
+[Git host contract](git-hosts.md). GitHub and Bitbucket Cloud can dispatch;
+Bitbucket's live no-reviewer path has been qualified on a disposable public
+repository. Independent Bitbucket review remains unvalidated. Existing IDs and
+chain ownership are retained without a state migration.
+
+## Independent Bitbucket reviewer credentials
+
+Coding sessions receive only their repository-bound coding credential. Reviewer
+credentials belong on an isolated reviewer machine, OS account, or container.
+The independent publisher accepts only the configured stable actor and prepared
+exact head; a successful Pipeline without a posted verdict is silence.
+See [reviewer isolation and publication](bitbucket-review.md#independent-local-codex-reviewer).
+Setup never installs a pipeline, creates a token, or authorizes inference.
+
+## Keep working artifacts out of pull requests
+
+Every local harness receives the same publication policy and generated `commit-msg` hook. The hook examines the
+NUL-delimited staged file list and rejects task scratch directories, conventional work logs, audit/evidence notes,
+and carried task inputs. Removing those files is allowed; preserve any carried files locally because the brief and
+snapshot checks still need them. The hook is refreshed at start and on every resumed/fix run. Hosted file results
+are checked before writing them, and the coordinator checks the complete remote PR diff before expensive first-party review and before readiness, even when the optional output-content scan is disabled. An unreadable or malformed diff is retried and
+never treated as clean. A prohibited file schedules a normal corrective round with its exact path.
+
+Requested audit reports, screenshots and other evidence are still valid deliverables. The operator names exact
+paths in the approved brief's [`publish_files`](prd.md) list. The coordinator uses its saved snapshot, never a
+session-edited whitelist. Before upgrading or restarting the daemon for existing runs, review retained deliverables in reserved directories.
+The operator must name their exact paths in `publish_files` and accept the updated saved brief through the usual
+`resume --resnapshot` flow at a safe resume boundary. Do not edit a running session's snapshot or grandfather all
+existing files. Without those prior approved exceptions, the new guard will request cleanup instead of readiness.
+
+Use a temporary directory outside the repository for scratch files. Runner command/session logs remain in task
+storage; concise verification results belong in the PR receipt. Keep durable release/rollback instructions in the
+project docs without appending a running execution diary. This policy does not inspect arbitrary prose or provide
+an isolation boundary: an agent with Git credentials can bypass local hooks and push, but reserved work-artifact
+paths will not pass the coordinator's readiness check. A clean check is cached only for its exact head, base and approved policy, so review polls do not repeatedly fetch
+the diff. Normal rechecks also inspect legacy ready entries; no PR is automatically rewritten.
+
+First-party reviewers receive carried text inputs from the coordinator's immutable `readSource` snapshots, with
+content digests in their private evidence. They do not fetch those files from remote HEAD or the mutable session
+checkout. These inputs follow the existing capture, per-job input and review-job caps; missing or oversized input
+is reported explicitly, never silently omitted. Keep source context concise: it accompanies each source/visual
+review piece and the final synthesis. The complete brief plus private source context and review metadata must fit the
+configured per-job input cap (at most 100,000 serialized UTF-8 bytes). Larger private sources must be narrowed or
+split into separately approved tasks; do not commit them as a workaround. Required image evidence remains in Git at its approved output paths.
+
+`openai-agents` transports all approved inputs privately with their original hashes, but only explicit output overlays
+are forced into a result. Verification permits private inputs to remain untracked or unstaged only while their bytes
+and modes exactly match the coordinator snapshots. Editing, staging, deleting or substituting them fails publication.
+Codex Cloud's Git-only input transport cannot provide this privacy for new/changed inputs and refuses before commit
+or push; its dispatch is separately unavailable until repository binding is qualified. See [codex-cloud.md](codex-cloud.md).

package/docs/install.md

@@ -49,10 +49,10 @@ cd /path/to/your/repository
 npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
 ```
 
-This setup flow requires **0.2.1 or newer**. On 2026-10-20, npm's `latest` was
-still 0.2.0: its `init` creates the config only, so repository registration and
-`doctor` must be done separately. A maintainer must [publish 0.2.1](releasing.md)
-before the command above provides the flow below; setup does not publish it.
+This setup flow requires **0.2.1 or newer**. Check npm's current release with
+`npm view @uchibeke/gallivant version`. Source changes on `main` reach this
+command through a [versioned release](releasing.md); setup itself does not publish
+a package.
 
 `npx` downloads the published `@uchibeke/gallivant` package into npm's cache and
 runs its `gallivant` command. Nothing is installed globally, no `gallivant`
@@ -302,7 +302,7 @@ bypassed. See [guardrails.md](guardrails.md#codex-git-writes-need-automatic-appr
 ## 9. First task
 
 Before dispatch, confirm the repository, target branch, permitted changes and
-spending limits. The default `max_iterations` is 30 automatic fix rounds;
+spending limits. The default `max_iterations` is 60 automatic fix rounds;
 `max_budget_usd` defaults to 5 and gives Claude a native per-run dollar cap.
 Other local harnesses do not enforce an equivalent dollar cap. Use your provider's
 spend controls and review [budget semantics](config.md) before unattended work.
@@ -331,9 +331,9 @@ gallivant task start TASK_ID --revision REVISION --run
 gallivant start
 ```
 
-Alternatively, add `--run` to the original `task` request to authorize
-implementation as soon as preparation and any clarifications succeed. The task
-service starts the daemon; `gallivant start` with no path also opens the dashboard.
+Preparation always returns for review, including when the original request
+contains `--run`. Approve the visible ready revision with the separate start
+command above. The task service starts the daemon; `gallivant start` with no path also opens the dashboard.
 Read [task operations](tasks.md) for selected context, revisions, recovery and costs.
 
 ### From a written brief
@@ -396,3 +396,13 @@ Watch `gallivant status` after the start run ends: the entry moves from `impleme
 | `<worktrees>/<repo>/<prd>` | one partial clone per PRD; durable until you delete it |
 
 Override the home directory with `GALLIVANT_HOME` to run a second instance.
+
+## Bitbucket-only first run
+
+Bitbucket setup uses Node, Git, a selected local harness, an account API token,
+and explicit reviewer or no-reviewer policy. It does not require `gh` sign-in.
+Follow the [first-run commands](bitbucket-review.md#first-setup-including-a-checkout-with-no-existing-configuration),
+including separate SSH and API credentials when using SSH Git. Setup checks
+transport access; a live public repository run has reached ready with explicit
+no-reviewer policy. Independent review and a clean Linux installation have not
+been qualified. Check `gallivant doctor` before starting your own repository.

package/docs/network-recovery.md

@@ -1,5 +1,14 @@
 # Network failures and recovery
 
+The coordinator normally retains a successful local provider health check for
+five minutes, so a long coordinator cycle does not immediately expire it. A due,
+pending, failed or timed-out check still fences dispatch. An explicit
+`execution.progressMs` setting controls this interval and remains authoritative.
+Provider readiness refreshes on its own timer while a long coordinator cycle
+is still processing. A pending or failed refresh continues to block dispatch.
+Messages and resume requests remain queued while a readiness check is pending;
+an actual failed check still reports failure for the operator to repair.
+
 `ENOTFOUND` means a hostname lookup failed. `EAI_AGAIN` indicates a temporary
 resolver failure. Neither proves that a provider is down, credentials expired,
 or APort denied a tool call. DNS can affect one hostname while other sites work.

package/docs/openai-agents.md

@@ -85,7 +85,8 @@ entry, prepare and inspect a brief first, then follow the returned next action:
 ```sh
 gallivant task "Document the existing test commands in CONTRIBUTING.md. Change documentation only." \
   --harness openai-agents --verify 'git diff --check'
-# Add --run to authorize implementation once the brief passes readiness.
+# Review the ready draft, then substitute its returned task ID and revision:
+gallivant task start TASK_ID --revision REVISION --run
 ```
 
 Natural-language intake uses the selected provider's versioned preparation

package/docs/prd.md

@@ -76,6 +76,27 @@ These keys beyond `status` and `harness` are read if present:
   editing a document it was handed, and the list is part of the contract: adding or removing a file stops the entry
   the way an edited criterion does. See [config.md](config.md#files-a-brief-carries-sources) for how it differs from
   `context_paths`.
+- `publish_files` is an optional list of **exact output files** that would otherwise match the task-artifact policy:
+
+  ```yaml
+  publish_files:
+    - docs/audit/requested-security-report.md
+    - docs/evidence/export-dialog.png
+  ```
+
+  Use it only for reports, evidence or carried documents the operator explicitly wants in the PR. It does not list
+  ordinary implementation files or tests. No globs, directories, absolute paths or more than 100 entries are accepted.
+  The saved, approved brief supplies these exceptions; editing the session's copy cannot grant permission. Changing
+  the list changes the contract and uses the normal `prd-changed` repair/approval flow.
+
+  Task work logs, session transcripts, scratch files, audit chronology and review/handoff notes belong outside Git.
+  Create scratch space with `mktemp -d`; put concise verification results in the PR receipt. Keep lasting project
+  documentation and release/rollback instructions concise. The commit hook and final remote PR-diff check reject
+  conventional work-artifact paths (including `docs/audit/`, `docs/evidence/`, `docs/verification/`, `WORK_LOG.md`,
+  `NOTES.md`, and carried `sources`) unless listed here. Deletions remain allowed so an existing PR can be cleaned.
+  Required image evidence must remain committed at its explicitly approved paths; deleting it would invalidate review.
+  This is a path hygiene check, not a semantic content scanner: do not rename work logs to evade it.
+
 - `context_paths` gives this one brief read access to directories outside its checkout, added to whatever
   `config.json` already lists rather than replacing it. Comma-separated, or a `[a, b]` list:
 
@@ -128,7 +149,7 @@ file in your checkout are two files, and until this existed nothing compared the
 the run finished against criteria nobody was asking for and the PR arrived satisfying a document that had changed.
 
 So the two are compared, and what happens depends on what you changed. The comparison is in the contract's own terms:
-the acceptance criteria, Verify commands, `harness`, `context_paths`, `sources`,
+the acceptance criteria, Verify commands, `harness`, `context_paths`, `sources`, `publish_files`,
 and the **Coordinator delivery contract** when present. The ownership section
 keeps a natural-language publication instruction separate from provider work.
 It is validated and fingerprinted too; malformed edits cannot be silently ignored.
@@ -138,7 +159,7 @@ request bytes remain exact.
 | What you changed | What happens |
 |---|---|
 | Anything outside those contract fields: the Problem prose, a reworded story, a new Out of scope bullet | Nothing stops. The snapshot follows your edit so later prompts carry your current wording, the log says it happened, and you are not told. Stopping a run to ask about a typo fix would be worse than useless. |
-| A criterion, a Verify command, the harness, `context_paths`, `sources` or coordinator delivery ownership | The entry stops with `prd-changed` before the gate runs, and `gallivant why` names each difference. |
+| A criterion, a Verify command, the harness, `context_paths`, `sources`, `publish_files` or coordinator delivery ownership | The entry stops with `prd-changed` before the gate runs, and `gallivant why` names each difference. |
 | The ORDER of two criteria, without changing a word of either | Also `prd-changed`. Criteria are numbered by position, and the receipt on the open PR attests `ac-1` and `ac-2` by those numbers, so swapping two of them leaves the receipt attesting each criterion with the other's evidence. |
 | The file no longer passes the contract | `prd-illegal`. Fix the file and `gallivant ready` it again; it cannot become the brief the gate judges as it stands. |
 | The file is gone from your checkout | `prd-gone`. Restore it, or `gallivant remove` the entry. |

package/docs/preparation.md

@@ -16,7 +16,7 @@ Preparation and implementation are separate capabilities:
 | Claude Code | Tools disabled | Local checkout |
 | Codex | Isolated native profile, Codex 0.160.0+ | Local checkout |
 | OpenAI Agents API | Text only, no tools or environment | Hosted sandbox |
-| Gemini CLI, OpenCode, Goose | Unavailable; use `new` → `ready` → `start` | Local checkout |
+| Gemini CLI, OpenCode, Goose | Unavailable through the harness; the configured [model route](task-profiles.md#planner-routes) can draft, or use `new` → `ready` → `start` | Local checkout |
 | Codex Cloud | Unavailable | New dispatch blocked on environment/repository verification |
 
 An adapter's presence does not prove the configured account can use its selected

package/docs/release-qualification.md

@@ -16,7 +16,7 @@ the accessible actual demo recording URL. Do not substitute generated images.
 
 ```sh
 npm run release:preflight -- --config "$PACKAGE_CONFIG" --setup "$SETUP_EVIDENCE"
-npm run release:package -- --config "$PACKAGE_CONFIG" --out "$RELEASE_DIR" --core-version 0.2.0 --source-commit "$SOURCE_COMMIT" --deployment "$DEPLOYMENT_RECORD" --evidence "$LIVE_EVIDENCE"
+npm run release:package -- --config "$PACKAGE_CONFIG" --out "$RELEASE_DIR" --core-version 0.3.0 --source-commit "$SOURCE_COMMIT" --deployment "$DEPLOYMENT_RECORD" --evidence "$LIVE_EVIDENCE"
 npm run release:validate -- --out "$RELEASE_DIR"
 ```
 

package/docs/releasing.md

@@ -81,10 +81,25 @@ GitHub release. Until then, use the documented CI bootstrap credential route.
 
 ## Release a version
 
+Merging a PR to `main` does not bump the version, create a tag or publish a
+package. There is no scheduled release or automatic version-bump PR. Prepare a
+version-bump PR, wait for its checks, merge it, then trigger the workflow and
+approve the protected `npm` environment. A newer source checkout with an already
+published version cannot refresh that npm version: the tag and tarball guards
+deliberately require the original commit and bytes.
+
 Update the version with `npm version patch --no-git-tag-version` (or `minor`),
 which updates `package.json` and `npm-shrinkwrap.json`. Include release notes in
 the PR and merge it after CI passes. Do not bump the version for a retry.
 
+Update `CORE_VERSION` in `lib/task_delivery_contract.mjs` to the same version.
+For a minor release, review and update its pre-1.0 compatibility window, the
+handshake tests and the packaging examples in [task delivery](task-delivery.md)
+and [release qualification](release-qualification.md). Other minor versions
+require explicit migration; keep the exact artifact pin and wire-schema guards.
+Run the full portability suite, including plugin packaging and release assembly,
+before publishing: the npm install smoke alone does not exercise those builders.
+
 The workflow follows the guardrails repository's pattern: validate the release
 ref, test before publishing, and permit recovery without replacing published
 versions. This single-package project does not need its multi-registry dispatcher.
@@ -93,8 +108,8 @@ Choose one trigger:
 
 ```sh
 # From an up-to-date main checkout; replace the example with package.json's version.
-git tag -a v0.2.1 -m 'Release 0.2.1'
-git push origin v0.2.1
+git tag -a v0.3.0 -m 'Release 0.3.0'
+git push origin v0.3.0
 
 # Or dispatch against main; the workflow uses main's package version.
 gh workflow run release.yml --repo uchibeke/gallivant --ref main

package/docs/task-delivery.md

@@ -19,7 +19,7 @@ runner.
 
 ## Installed exports
 
-Core `0.2.0`, task schema `1`, execution schema `1`, operation schema `1`.
+Core `0.3.0`, task schema `1`, execution schema `1`, operation schema `1`.
 The candidate digest comes from the emitted `runtime.json`/`manifest.json`;
 pin the artifact produced from the eventual human-merged commit, not this branch.
 
@@ -218,7 +218,7 @@ Before wake-up, migrate/pin the exact runtime artifact. Supply the emitted
 The coordinator refuses a different active-job digest. Compatible patches keep
 task/provider/brief identities; drain jobs before staging a different artifact.
 No running code is silently upgraded. The public API's pre-1.0 compatibility
-window is `0.2.x`, with operation/task/execution wire schemas all `1`; other
+window is `0.3.x`, with operation/task/execution wire schemas all `1`; other
 versions need migration.
 
 The portable contracts/views/wake envelope have no Node dependencies. The complete
@@ -267,9 +267,9 @@ changes and remain development fixtures:
 npm ci --ignore-scripts
 node bin/package-plugin.mjs --config /private/aport-package.json --validate-public
 npm run package:plugin -- --config /private/aport-package.json --out /private/candidate \
-  --core-version 0.2.0 --source-commit <40-character-merged-commit>
+  --core-version 0.3.0 --source-commit <40-character-merged-commit>
 # For development only, add --internal; keep fixture:true in the config.
-npm install --ignore-scripts --prefix /private/candidate-runtime /private/candidate/uchibeke-gallivant-0.2.0.tgz
+npm install --ignore-scripts --prefix /private/candidate-runtime /private/candidate/uchibeke-gallivant-0.3.0.tgz
 node /private/candidate-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs check \
   --home /durable/preview --manifest /private/candidate/runtime.json
 node /private/previous-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs backup \