@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Use macOS or Linux with Node 22 or 24. Install dependencies with
+`npm ci --ignore-scripts`. Run `npm run lint`, `npm test` and `npm run test:install`
+before opening a pull request. Native isolation tests need Command Line Tools on
+macOS or Bubblewrap with user namespaces allowed on Linux; see
+`.github/workflows/runtime-portability.yml` for the tested host setup.
+
+`npm test` uses fixtures and disposable repositories. Live harness suites are
+separate opt-in commands: they need authenticated provider access and can spend
+credits. Do not include credentials, private run logs, local config or customer
+content in a contribution. Follow [SECURITY.md](SECURITY.md) for vulnerabilities.
+
+Keep orchestration in shared services so CLI, daemon and UI use the same rules.
+Preserve each adapter's supported continuation, bounded retries, ownership checks, sandbox
+refusals and human merge gates. Add focused regressions for correctness fixes,
+and update the relevant command/configuration documentation when behavior changes.
+
+[The documentation index](docs/README.md) separates current operator guides from
+implementation PRDs, plans and dated evidence. Update guides with behavior changes;
+preserve queued brief/source contracts and historical test results. New provider
+support must state preparation and implementation capabilities separately, along
+with credentials, permissions, costs, continuation and qualification limits.
+
+Describe the user-visible problem, the resulting behavior and the checks you ran.
+An implemented adapter is not a live-qualified provider; record that distinction.

package/LICENSE

@@ -0,0 +1,204 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (which shall not include Communications that are clearly marked or
+   otherwise designated in writing by the copyright owner as "Not a Work").
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution".
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+---
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright 2026 Gallivant contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# Gallivant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Give an agent a task. Let the review loop run. Go outside.**
+
+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
+                                 ↑___________|
+```
+
+## Set up in one command
+
+Run this inside the Git checkout you want to work in:
+
+```sh
+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.
+
+`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.
+
+Before you run it you need:
+
+| 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` |
+
+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.
+
+`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:
+
+```sh
+npm install -g @uchibeke/gallivant
+```
+
+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 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
+  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
+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
+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`,
+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
+
+```sh
+gallivant new add-csv-export
+# Edit docs/prds/add-csv-export.md: outcome, scope, acceptance criteria and checks.
+gallivant ready docs/prds/add-csv-export.md --check
+gallivant ready docs/prds/add-csv-export.md
+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` (30 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 |
+| --- | --- |
+| Follow runs | `gallivant start` or `gallivant status` |
+| Correct the agent | **Send message** on its dashboard page; context and existing work are preserved |
+| Inspect a stop | `gallivant why <handle>` |
+| Continue after fixing a blocker | `gallivant resume <handle>` or **Resume agent** |
+| Refresh review and CI | **Recheck PR**; this does not resume a failed agent |
+| Keep the dashboard without opening a browser | `gallivant start --no-open` |
+| Run only the daemon | `gallivant start --no-server` |
+| Stop monitoring and the standalone dashboard | `gallivant down`; existing agent processes continue |
+
+If services fail to start after a task is accepted, retry `gallivant start`
+without the PRD path. Do not submit the same task again.
+
+Temporary connection failures have bounded same-session recovery. For DNS errors,
+use `gallivant doctor --network https://api.anthropic.com` with your provider's
+actual HTTPS origin. [Recovery and troubleshooting](docs/network-recovery.md).
+
+## More than one task
+
+```sh
+gallivant chain launch docs/prds/foundation.md docs/prds/integration.md docs/prds/launch.md
+```
+
+The next milestone starts only after its predecessor is merged into the planned
+base. You can plan longer work while retaining the merge decision.
+[Chaining tasks](docs/chains.md).
+
+## 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 |
+| Codex CLI (`codex`) | Your host | Yes, 0.160.0+ | Recommended; live usage evidence |
+| Gemini CLI (`gemini`) | Your host | Written PRDs only | Adapter implemented; unattended end-to-end qualification incomplete |
+| OpenCode (`opencode`) | Your host | Written PRDs only | Adapter implemented; unattended end-to-end qualification incomplete |
+| Goose (`goose`) | Your host | Written PRDs only | Adapter implemented; unattended end-to-end qualification incomplete |
+| OpenAI Agents API (`openai-agents`) | OpenAI-hosted sandbox | Yes, text-only | Hosted adapter implemented; eligible API account, explicit model/environment and live qualification required |
+| Codex Cloud (`codex-cloud`) | Codex Cloud | No | New dispatch disabled until the selected environment's repository binding can be verified |
+
+Local Codex, Codex Cloud and the Agents API are distinct integrations. Local
+Codex and Claude work independently of the Cloud dispatch restriction.
+`openai-agents` supports remote progress, continuation, cancellation and artifact
+retrieval; the coordinator verifies returned changes and publishes the PR.
+Implemented transport support is not a claim that every account has access or
+that the full live lifecycle has passed qualification.
+
+For local harnesses, provider and model selection belongs to that harness's own
+configuration. Gallivant has no general per-task local model router and does not
+turn a provider API key into a configured harness automatically. Hosted Agents
+requires an explicit authorized model; there is no automatic model fallback.
+[Hosted setup](docs/install.md#hosted-agents-api-instead-of-a-local-cli) ·
+[Detailed capabilities](docs/config.md#execution-providers) ·
+[Recorded qualification](https://github.com/uchibeke/gallivant/blob/main/docs/audit/harness-live-validation.md).
+
+## Feature map
+
+| Capability | What you can do | Guide |
+| --- | --- | --- |
+| Task intake | Prepare a brief from a request, answer clarification questions, inspect revisions and authorize the ready task | [Tasks](docs/tasks.md) |
+| Written briefs and context | Define acceptance criteria, verification commands and carried source files | [PRDs](docs/prd.md) |
+| Review loop | Watch CI and trusted feedback, continue corrections, recover bounded connection failures and inspect stops | [Commands](docs/commands.md), [recovery](docs/network-recovery.md) |
+| Run controls | Message, resume, recheck or cancel from the CLI/dashboard; inspect saved progress and logs | [Dashboard](docs/app.md) |
+| Sequential plans | Queue dependent briefs with a merge gate between milestones | [Chains](docs/chains.md) |
+| Completion checks | Evaluate acceptance evidence with APort or the explicit local evaluator; choose review handoff or watching for merge | [Guardrails](docs/guardrails.md), [milestones](docs/tasks.md#choose-the-delivery-milestone) |
+| Notifications | Configure transition notifications through ntfy | [Configuration](docs/config.md) |
+| Embedding and integrations | Use versioned task-delivery operations, Node coordination, MCP and plugin packaging; deployment is separate | [Task delivery](docs/task-delivery.md) |
+| Review learning | Collect historical feedback and inspect candidates; rule activation remains unqualified | [Learning](docs/learning.md) |
+
+The [command index](docs/commands.md#command-index) covers every top-level CLI
+command and points to the task and learning subcommands. Run `gallivant --help`
+for the installed version's flags.
+
+## What to expect
+
+- **Your machine coordinates the work.** Keep it awake, online and running the
+  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.
+- **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).
+- **Ready does not mean merged.** Natural-language tasks default to stopping at a
+  qualified review handoff. Choose `integrated` to keep watching for your merge.
+  Written-PRD runs retain their monitoring behavior. No mode authorizes automatic
+  merge, release or deployment. [Delivery milestones](docs/tasks.md#choose-the-delivery-milestone).
+- **Learning is experimental.** Review feedback can be collected, but production
+  activation of learned rules is not qualified. [Learning](docs/learning.md).
+
+## 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)
+
+**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
+hosted service or publish a chat plugin.
+
+[Contributing](CONTRIBUTING.md) · [Security reports](SECURITY.md) ·
+[Releasing](docs/releasing.md) · [Apache-2.0 license](LICENSE)

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security
+
+Report suspected vulnerabilities through
+[GitHub private vulnerability reporting](https://github.com/uchibeke/gallivant/security/advisories/new).
+If private reporting is unavailable, open an issue requesting a private contact
+channel without disclosing the vulnerability. Do not include credentials,
+exploit payloads or private run logs in a public issue.
+
+Include the version/commit, affected command, platform, reproduction and expected
+permission boundary. Remove tokens and personal data. Fixes target the current
+release; there is no separate long-term support branch yet.
+
+Read [the guardrails](docs/guardrails.md) before unattended operation. Local
+dashboard access is trusted operator access. Local implementation workers receive
+the configured GitHub credential; scope it to the repositories and operations
+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.