Enterprise setup
Consent-first onboarding for Pocket Enterprise: mode init, adapter registration, push-consent choices, and a read-only preflight before any change.
Enterprise adds remote lifecycle synchronization to a compatible Core installation. Onboarding is consent-first: a direct request to enable Enterprise is treated as consent; an ambiguous request gets an explanation first, and nothing changes until you decide.
Prerequisites
- The matching Core v4 role is installed. Enterprise is an additive delta, not a standalone workflow.
- Local prerequisites verified before any external operation:
gh auth status
git remote get-url originMissing authentication or no origin remote stops onboarding: nothing is partially initialized.
What enabling Enterprise does
Explained up front, before any change:
spec-approvedmay create or reconcile one issue for the approved spec.phase-completeupdates the phase summary and reconciles review findings on an existing PR (stacked plans defer this tophase-closed).phase-closedpublishes a stacked phase PR and, only with consent, pushes that phase branch fast-forward.plan-closedupserts the final tasklist proof on the linked issue.- The adapter never merges a PR or closes an issue.
- Enabling does not itself drain pending events: remote reconciliation happens when a lifecycle drain is run.
Configure the mode
npx -y pocketto-pi mode --json --contract 3 # read current mode
npx -y pocketto-pi mode init <project-root> --enterprise true --branch-strategy branch --create-pr true --file AGENTS.md --json --contract 3--branch-strategy:branchormain-local;--create-pr:trueorfalse(enables the separate create-pr recorder, so no PR is created automatically);--require-approvalis available if you want the gate.mode initvalidates the remote and writes the mode block to the selected memory file (AGENTS.mdorCLAUDE.md) plus.gitattributes. Both files may change.- Existing mode values are preserved, never overwritten with defaults.
Optional project templates:
npx -y pocketto-pi scaffold github --json --contract 3Existing user files are not overwritten. The pocket-plan label is created only when you request that setup step.
Register the adapter
Choose the phase-branch model before registration:
| Option | Values | Effect |
|---|---|---|
--phase-branches | stacked (default), none | stacked publishes each phase as a PR against its explicit base. Under main-local, a requested stacked is overridden to none with a warning. |
--push-consent | phase-branches | Durable consent for non-force pushes of Pocket phase branches only (pocket/<plan>/phase-<N>). Omit it to approve each pushed commit separately. |
node <package-root>/enterprise/cli.js install <project-root> --phase-branches stacked --push-consent phase-branches --json
node <package-root>/enterprise/cli.js preflight <project-root> --json # read-only verificationenterprise/cli.js lives in the pocketto-pi package root: for a project depending on the npm package, use node node_modules/pocketto-pi/enterprise/cli.js …. The install writes .pocket/lifecycle-adapter.json with the default portable runtime-token registration (@pocketto-runtime-argv-v1 + @pocketto-node + @pocketto-install-root/enterprise/dispatch.js), with no machine-specific absolute paths. A legacy absolute-path registration still works but reports ADAPTER_REGISTRATION_NOT_PORTABLE; reinstall after upgrading Core to migrate it.
Reinstall rules
Reinstall after upgrading Core (to runtime-token support) or after upgrading to an Enterprise release that declares adapter contract 2: a contract 1 registration fails preflight with ENTERPRISE_ADAPTER_CONTRACT_MISMATCH. Inspect the existing registration first: a default registration is replaced by reinstalling; a custom registration (--argv) is replaced only with your explicit authorization, reinstalling with the same --argv entries. Never run bare install over a custom registration.
Verify, then stop
preflight is read-only: it confirms compatible Core, lifecycle schema 2, adapter contract 2, registration, and executable, and reports non-blocking warnings verbatim. On any failure, stop before any remote operation and follow the install/upgrade guidance in the error. Do not run a drain as an automatic final step. Pending events remain local until you run:
npx -y pocketto-pi lifecycle drain <spec_dir> --json --contract 3Related documentation
Local-first behavior
Everything Pocketto Core does with no GitHub credentials, no remote, and no Enterprise install, plus the GitHub operations Core never performs.
Integration boundaries
The routing table between Pocketto Core and Enterprise: which lifecycle event triggers which Enterprise action, and what neither side ever does.