Pocket Enterprise
Pocket Enterprise is an optional, additive adapter for teams that explicitly choose remote lifecycle synchronization. Install the Enterprise role beside its matching Core role; it does not bundle or copy Core skills.
Core principle: Core commits local state and neutral lifecycle events first. Core does not call
, does not merge pull requests, and does not close issues. The adapter validates compatibility before any external operation, reconciles events deterministically, and leaves ambiguous ownership for a human.
Release and compatibility
The
manifest has schema
and defines exactly
,
,
, and
. Enterprise roles are deltas requiring their matching Core role. Release versions are package
, CLI
,
, lifecycle schema
, adapter contract
, and surface manifest
; these are independent version boundaries.
| Core | Enterprise | Result |
|---|
| v3 | v3 | Legacy installation remains operational with a v4 warning. |
| v4 | v4 | Supported. |
| v4 | absent | Core remains local-first; pending events are retained without GitHub calls. |
| v3 | v4 | Enterprise fails closed with Core upgrade guidance; v3 Core remains usable. |
| v4 | v3 | The adapter fails closed with Enterprise upgrade guidance; pending v4 events are retained. |
The v4 preflight warns about legacy v3 installations; an unchanged v3 binary cannot warn about a future release. Never infer consent from a remote or credentials. A registration must declare adapter contract
; reinstall the adapter after upgrading, because a contract
registration fails preflight with
ENTERPRISE_ADAPTER_CONTRACT_MISMATCH
. Follow
for setup, phase-branch options, and registration.
Activation and preflight
Run the Enterprise preflight from the project root:
bash
node enterprise/cli.js preflight <project-root> --json
is in the pocketto-pi package root, not in the project being checked. The command above is a checkout of this repository. A project that depends on the npm package runs
node node_modules/pocketto-pi/enterprise/cli.js preflight <project-root> --json
.
Continue only when it confirms a compatible Core installation and registered adapter. Missing Core, an unsupported contract, malformed registration, or a missing executable is fail-closed: make no GitHub call and follow the install/upgrade action in the error. Preflight is read-only.
Core provides the lifecycle commands with
:
bash
pocketto-pi lifecycle transition <spec_dir> <event-type> --artifact <root>:<kind>:<relative-path>:<sha256> --json --contract 3
pocketto-pi lifecycle drain <spec_dir> --json --contract 3
pocketto-pi lifecycle repair <spec_dir> --json --contract 3
pocketto-pi lifecycle migrate <spec_dir> --from v3 --json --contract 3
commits local state and a durable event before optional delivery.
replays pending events in revision order and creates no event.
reconciles lifecycle-owned projection fields only when task state is recoverable; it does not emit or dispatch an event. Run
only after a successful Enterprise preflight. If Enterprise is absent or unavailable, Core work remains successful and event IDs remain available for replay.
Lifecycle routing
Core emits only neutral event names and artifact references. The event journal and protocol boundary are defined in
references/lifecycle-contract.md
.
| Event | Enterprise-owned action |
|---|
| Reconcile the approved spec with its owned issue; see references/issue-reconciliation.md
|
| Reconcile an existing phase PR and its proof; see references/phase-reconciliation.md
|
| Stacked plans only. Publish the closed phase PR with its stack identity, summary, findings, and stack proof, pushing its phase branch only with consent; see references/phase-reconciliation.md
|
| Reconcile the final tasklist proof on the linked issue; see references/phase-reconciliation.md
|
The adapter owns GitHub IDs, credentials, and remote proof in Enterprise-owned metadata. Core lifecycle records contain no GitHub IDs or credentials. Enterprise issue reconciliation may create one issue for
; it does not create an issue for phase or closure events.
is a separate, explicit user-triggered recorder; for stacked plans it runs
, the same publisher the
handler uses.
Ownership and human gates
- Issue, PR, comment, and remote tasklist synchronization belongs to this Enterprise adapter. Core makes no GitHub calls.
- Never copy or modify a Core skill to add remote behavior; keep Core source canonical and install Enterprise only as its declared additive delta.
- Do not guess when an issue, PR, marker, or owner is ambiguous. Stop with an actionable manual-resolution request and make no mutation.
- The adapter never merges a PR or closes an issue. Those actions remain human-controlled.
Migration and rollback
Active v3 plans with progress stay on the v3 CLI/Enterprise path. Migration is explicit:
bash
pocketto-pi lifecycle migrate <spec_dir> --from v3 --json --contract 3
Only a pristine v3 plan with no execution progress can migrate. Progress or a non-pristine plan returns
without changing files or making remote calls; finish the plan under v3. No v3 progress is silently converted.
To roll back Enterprise, disable or remove the adapter while retaining Core and the authoritative
. Preserve
,
, pending lifecycle events, and remote markers. Core continues locally. Pin a faulty adapter to the last compatible v4 release, correct it, then replay pending events with
pocketto-pi lifecycle drain <spec_dir> --json --contract 3
using their original IDs. Do not delete lifecycle state, rewrite v3 plans, or automatically downgrade v4 state.