@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/docs/releasing.md

@@ -0,0 +1,140 @@
+# Releasing
+
+The package name is `@uchibeke/gallivant`; the executable is `gallivant`. The repository is
+`uchibeke/gallivant`. Before announcing a version, confirm npm publication and a
+passing consumer smoke check. A public GitHub repository alone does not make the
+npm command work.
+
+## One-time launch setup
+
+1. Review all branches and Git history, author metadata, issues, PR discussions,
+   Actions logs and artifacts for private material before changing visibility.
+   Removing a file from the current checkout does not remove historical copies.
+   Retain history unless a specific disclosure requires cleanup; coordinate any
+   rewrite with open PRs and active runs that reference existing commits. After
+   the owner accepts the reviewed exposure, make the repository public and enable
+   GitHub private vulnerability reporting. These are owner actions, not effects
+   of a PR merge.
+2. Create a GitHub Actions environment named `npm`, restricted to release tags
+   and `main`, with a required maintainer reviewer. Only release jobs receive
+   publishing authority; pull-request tests get read-only permissions.
+   Enable the `main` ruleset with pull requests, the four portability checks,
+   and protection against deletion and force pushes. Read back both settings:
+   merely referencing `environment: npm` in YAML does not create protection.
+3. For a package that does not exist yet, arrange the initial npm publication
+   credential with the npm owner. If needed, set a short-lived granular
+   `NPM_TOKEN` in the protected `npm` environment, scoped as narrowly as npm
+   permits. Never put it in the repository or a PR.
+   A local `npm login` is not authentication for GitHub Actions. Do not publish
+   the release locally to bypass this setup: the release's provenance is
+   generated in supported CI, not by the developer's terminal.
+4. Once the package exists, configure its npm trusted publisher for GitHub owner
+   `uchibeke`, repository `gallivant`, workflow `release.yml`, environment `npm`.
+   Permit direct `npm publish`, which is what this workflow runs. Validate a new
+   trusted publisher within two days or recreate it after expiry; configure it
+   shortly before the next planned release. An identical-version rerun skips
+   publication and does not validate OIDC. Remove the
+   bootstrap token after a successful OIDC release, then require 2FA and disallow
+   traditional token publishing in the package settings. Trusted publishing
+   needs npm 11.5.1+ and Node 22.14+; the workflow uses Node 24 and npm 11. See
+   [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) and
+   [provenance](https://docs.npmjs.com/generating-provenance-statements/).
+5. Merge the reviewed release changes, verify CI, then publish. Repository
+   visibility, npm ownership and environment protection must be checked in their
+   respective settings; a workflow file alone does not configure them.
+
+Read-only preflight (authenticated repository administration access is required
+for environment and ruleset details):
+
+```sh
+gh repo view uchibeke/gallivant --json visibility,defaultBranchRef
+gh api repos/uchibeke/gallivant/environments/npm
+gh api repos/uchibeke/gallivant/environments/npm/deployment-branch-policies
+gh api repos/uchibeke/gallivant/branches/main --jq '{protected,protection}'
+gh api repos/uchibeke/gallivant/rulesets
+npm whoami --registry=https://registry.npmjs.org
+npm view @uchibeke/gallivant version --registry=https://registry.npmjs.org
+```
+
+An absent package is expected before the first publication. An absent `npm`
+environment or disabled branch protection is unfinished release setup.
+
+### Staged publishing is a different workflow
+
+npm now supports `npm stage publish` and explicit maintainer approval with 2FA.
+It requires npm 11.15+ and Node 22.14+. Staging a new package creates a **public
+`0.0.0-stage` placeholder**; it is not a dry run. The staged version's contents
+remain private until approval. See [npm staged publishing](https://docs.npmjs.com/staged-publishing/).
+
+This repository's release workflow publishes directly after the GitHub
+environment approval. It does not stage, approve, or poll staged versions.
+Do not configure its trusted publisher as stage-only or use staging as an
+implicit bootstrap step. Adopting that route requires a separately reviewed
+workflow that records the stage ID and waits for approval before creating the
+GitHub release. Until then, use the documented CI bootstrap credential route.
+
+## Release a version
+
+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.
+
+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.
+
+Choose one trigger:
+
+```sh
+# From an up-to-date main checkout; replace the example with package.json's version.
+git tag -a v0.2.0 -m 'Release 0.2.0'
+git push origin v0.2.0
+
+# Or dispatch against main; the workflow uses main's package version.
+gh workflow run release.yml --repo uchibeke/gallivant --ref main
+```
+
+Every release runs the Node 22/24 × Linux/macOS matrix: lint, the offline test
+suite, native isolation checks, and a clean installation of the actual tarball.
+Publishing requires a public repository, an exact tag/version match (or manual
+dispatch from `main`), and a commit reachable from `main`. An existing tag must
+point to that exact commit. The protected environment gates publication.
+
+The workflow packs the tested source, publishes to npm with provenance, then
+creates a GitHub release with the tarball. No publish occurs on an ordinary PR
+or version edit. A rerun accepts an existing npm version only when its SHA-512
+integrity matches the freshly packed artifact. A registry error fails closed;
+an existing version must also advertise provenance. Missing provenance is not
+repaired by rerunning this workflow, and different bytes require a new version.
+For an older tagged release, rerun its
+original workflow rather than dispatching newer `main` with the old version.
+
+## Verify before announcing
+
+```sh
+npm view @uchibeke/gallivant version dist.integrity dist.attestations
+npm install -g @uchibeke/gallivant
+gallivant --version
+gallivant --help
+```
+
+Compare the registry's integrity with the workflow tarball and inspect the
+attestation's source repository, commit and workflow. Run `npm audit signatures`
+in a clean project that installed the released version to verify registry
+signatures and available provenance. Metadata presence alone is not signature
+verification; see [npm provenance verification](https://docs.npmjs.com/generating-provenance-statements/#verifying-provenance-attestations).
+
+After publication is verified, update the README and installation guide to put
+the tested npm install command first and remove the first-release-pending notes
+(including this page). Keep the source-install alternative.
+
+Use a clean test account/home and the [getting-started guide](install.md) for one
+small real PR. Confirm implementation, feedback-driven continuation, CI and the
+completion receipt; automated installation checks use fixtures and do not prove
+paid-provider access. Recheck anonymous GitHub access and all README links.
+Announcement drafts are in [launch.md](launch.md).
+
+For local validation without publishing: `npm run lint`, `npm test`, and
+`npm run test:install`. The last command packs and installs under a disposable
+directory, exercises setup and PRD commands outside the source tree, and imports
+every declared module export. It makes registry requests but no model calls.

package/docs/runtime-environment.md

@@ -0,0 +1,113 @@
+# Node runtime and harness shells
+
+This contract covers local implementation through Claude, Codex, Gemini,
+OpenCode and Goose, plus the coordinator's local tooling. Hosted Agents compute
+uses its configured environment/packages instead; local paths are not uploaded
+as runtime grants. Preparation has a separate limited-authority
+[boundary](preparation.md). For setup start with [installation](install.md), then
+use this guide when a harness shell selects a different Node or package manager.
+
+## Why this is needed
+
+A harness executable and the Node used by its Bash tools are separate choices.
+Earlier fixes made coordinator verification use a non-login POSIX shell and
+named the exact configured harness executable in each session. Neither prevented
+Claude's saved shell environment from selecting another Node installation.
+On an ARM64 Mac, that selected an x64 Node under Rosetta while the checkout had
+ARM64 native dependencies; sandbox reads also blocked the intended Node under
+the operator's version-manager directory.
+
+Native dependencies must match the Node process that installs and executes them,
+including its platform, architecture and supported ABI. Hardware architecture or
+a lockfile alone does not establish that match. Do not copy an alternative Rollup
+binary into `node_modules` or change the lockfile to hide a mismatched interpreter.
+
+## Shared runtime contract
+
+Gallivant's local implementation adapters prepend the directory containing the
+Node executable that launched Gallivant to PATH. Start and resume share this
+implementation. Executable discovery checks inherited PATH first, then the
+operator's login shell with `command -v`, then non-login `/bin/sh -c`. The fallback
+does not source login profiles, which may contain shell-specific syntax. Missing or empty PATH
+gets `/usr/bin:/bin` for the fallback lookup. Relative PATH entries do not grant
+executable discovery from the checkout. Linux does not require zsh. Paths with
+spaces and apostrophes are shell-quoted.
+
+Claude can rebuild PATH from a shell snapshot. Its SessionStart hook therefore
+appends the runtime path to `CLAUDE_ENV_FILE`, which Claude applies to subsequent
+Bash commands. This uses the documented
+[session environment mechanism](https://code.claude.com/docs/en/hooks#persist-environment-variables).
+The original settings and hooks are preserved. Building or rebuilding a launch
+description creates no files. At actual dispatch the runner exclusively creates
+`runtime-settings.json` (0600) in its private run directory (0700), outside the
+agent checkout. Original settings are not edited. Exit and failed-launch handling
+remove owned snapshots; coordinator observation, settlement and the next launch
+also recover cleanup after a restart. Unknown process ownership or surviving tool
+processes retain the file until absence is confirmed. Tool-free preparation never
+receives this settings overlay or its hooks.
+
+PATH alone is insufficient when `blockReadsOutsideWorkingDirectories` prevents
+the shell from reaching a version-manager installation. The snapshot adds
+[sandbox read allowances](https://code.claude.com/docs/en/sandboxing) for the exact
+running Node executable and recognized npm, pnpm and Corepack package roots
+resolved from sibling executables. It does not grant writes, permit network
+destinations, expose the home directory, change model selection, or turn off
+APort hooks. Existing denies remain in the settings. Administrators can still
+prevent runtime access through managed policy; that requires operator correction,
+not disabling the sandbox or replacing dependencies with another architecture.
+
+Package-manager code is executable, operator-trusted tooling. Install Gallivant
+using the Node version intended for its work, not a project-controlled Node
+binary. Restart the daemon after changing installations. Repositories requiring
+a different Node version must explicitly provision that toolchain; this change
+does not infer one from untrusted repository files or run a version manager.
+
+npm's upper- and lower-case cache variables point to
+`.cache/gallivant/npm` inside the checkout, outside the directory that `npm ci`
+removes. Actual dispatch creates an ignore file inside that cache so cache files
+do not become repository changes; it refuses symlink paths and conflicting ignore
+files. Building a launch description remains free of filesystem writes. The existing npm user
+config isolation is retained. This does not grant access to home caches or copy
+registry tokens. A custom package manager or native runtime with additional
+libraries can still need operator-approved paths. Other harnesses receive the
+same initial PATH/cache contract but retain their own native shell behavior.
+Remote/cloud adapters run on another machine and are not assigned local paths.
+
+## Diagnosing a mismatch
+
+Run this in the affected harness's tool shell before installing dependencies:
+
+```sh
+command -v node npm npx pnpm
+node -p 'JSON.stringify({execPath:process.execPath,platform:process.platform,arch:process.arch,version:process.version,abi:process.versions.modules,cache:process.env.npm_config_cache})'
+```
+
+Compare the result with the selected runtime printed by the session hook. If it
+differs or a read is denied, preserve the error and fix the host runtime/access
+configuration first. Once the intended interpreter is accessible and selected,
+use the repository's documented locked install to rebuild any dependencies left
+by a different interpreter. This change does not repair existing `node_modules`
+automatically. Already-running sessions retain their launch environment; after
+installing the fix, restart the daemon and resume the same task through the normal
+controls so the next session invocation receives the new setup.
+
+## Verification
+
+`node --test test/runtime-environment.test.mjs` exercises actual shell execution
+with a conflicting Node, all five local start/resume adapters, quoting, portable
+discovery, preservation of security settings, actual child-process cleanup,
+failed launches, restart recovery, and refusal of agent-writable snapshots.
+`npm test` includes this file and all existing suites, including remote adapter
+tests. The runtime-portability
+workflow runs the full suite on Ubuntu and macOS with Node 22 and 24. CI installs
+Bubblewrap and activates Ubuntu's packaged sandbox-helper AppArmor profile on
+Linux, and selects Command Line Tools on macOS before running
+`node test/verification-host.mjs`. This preflight must prove the real filesystem
+and network boundary; failing isolation never becomes an unsandboxed fallback.
+
+`GALLIVANT_RUNTIME_LIVE=yes node test/runtime-environment-live.mjs` is an opt-in
+Claude probe using configured authentication and guards. It allows one run with
+a $2 ceiling and verifies actual Bash-tool output rather than assistant claims.
+It does not install packages, access customer data or weaken security settings.
+Native checks for other providers and Linux are separate from local fixture
+coverage; a green fixture does not prove their credentials or model access.