Core & Enterprise
How Pocketto splits into a local-first Core and an optional Enterprise adapter, with a hard boundary on who owns state and who touches GitHub.
Pocketto splits into two independently installed pieces with a hard ownership boundary:
- Core is local-first. It commits lifecycle state and neutral events locally and never calls
gh: it does not create or reconcile GitHub resources, does not merge pull requests, and does not close issues. - Enterprise is a separately installed, opt-in adapter. It consumes Core's durable events and owns all remote reconciliation: the approved-spec issue, phase PR summaries and findings, stacked phase PR publication, and the final tasklist. It is fail-closed before any remote operation and never merges a PR or closes an issue. Humans keep those gates.
Missing or incompatible Enterprise never blocks Core work: events remain durable locally for later replay.
The compatibility matrix
| Core | Enterprise | Result |
|---|---|---|
| v3 Core + v3 Enterprise | v3 | Legacy pair remains operational with a v4 upgrade warning. |
| v4 Core + v4 Enterprise | v4 | Supported split and lifecycle contract. |
| v4 Core + absent Enterprise | none | Supported local-first Core; events remain pending and no GitHub call occurs. |
| v3 Core + v4 Enterprise | v4 | Enterprise fails closed with Core upgrade guidance; Core remains usable. |
| v4 Core + v3 Enterprise | v3 | Adapter fails closed with Enterprise upgrade guidance; pending events are preserved. |
In this section
Core architecture
The 15 skills, the CLI envelope, the artifact tree, and the lazy Enterprise boundary.
Local-first behavior
What works with zero remote, and what Core will never do.
Enterprise setup
Consent-first onboarding, mode init, adapter registration, preflight.
Integration boundaries
Who owns what: the event → action routing table.
GitHub synchronization
Issues, phase PRs, stacked branches, tasklists, in practice.
Compatibility and versioning
The five independent protocol versions and pinning rules.
Lifecycle events
The neutral event model and the lifecycle CLI.
Recovery and rollback
Repair, drain, disable, without destroying state.
Human authorization
Every gate that stays with a person.
Related documentation
- Lifecycle events: the contract between Core and Enterprise
- create-pr: the user-triggered PR recorder
- Release surfaces: the manifest that enforces the split
create-pr
create-pr is the user-triggered Enterprise recorder that opens or reuses the GitHub pull request for a finished phase. It never merges or closes anything.
Core architecture
What Pocketto Core contains: the pipeline, standalone skills, Education, and the pocketto-pi CLI, plus the JSON envelope and the Enterprise boundary.