Status: Experimental / Provisional
First published: 2026-08-24
Current release: 2026-08-26
Protocol: Portable Persistent Goal Protocol (PPGP)
PPGP defines a portable continuity protocol for long-running coding-agent work.
A conforming implementation SHOULD allow a fresh compatible agent to recover an active software goal without requiring the human operator to reconstruct the previous conversation.
PPGP is model-vendor neutral and repository-oriented.
The terms MUST, MUST NOT, SHOULD, SHOULD NOT and MAY describe protocol requirements and recommendations.
PPGP defines logical roles, not mandatory filenames.
Long-lived mission, authority, invariants and non-negotiable project constraints.
It SHOULD change rarely.
Current project direction, completed goals, future goals, dependencies and deferred work.
It SHOULD describe state and direction, not preserve a full execution diary.
Durable facts that future agents would otherwise need to rediscover.
Good candidates include architectural decisions, non-obvious invariants, validated operational facts, expensive failed approaches worth avoiding, durable repository conventions, authority decisions and recurring failure modes.
A MEMORY item SHOULD change future behavior.
Temporary working memory for exactly one active goal.
It SHOULD remain compact enough for a fresh agent to recover the goal in one read.
Minimum fields:
GOAL
WHY
PHASE
DEFINITION_OF_DONE
FROZEN_DECISIONS
INVARIANTS
VERIFIED_CURRENT_STATE
COMPLETED
REMAINING
BLOCKERS
HUMAN_AUTHORITY_REQUIRED
VERIFICATION_EVIDENCE
NEXT_EXECUTABLE_ACTION
ACTIVE_GOAL is the primary repository-visible hot state for recovery of unfinished work.
A fresh agent SHOULD be able to recover an active goal from current ACTIVE_GOAL plus selectively relevant durable state and evidence without requiring a prior distill operation.
Implementations SHOULD update ACTIVE_GOAL after material state changes often enough that abrupt interruption does not force substantial human reconstruction or unnecessary repetition of verified work.
PPGP does not require persistence after every trivial action. Checkpoint frequency is implementation-dependent and SHOULD balance recovery fidelity against state-maintenance overhead.
ACTIVE_GOAL MUST NOT become the permanent chronological history.
ACTIVE_GOAL MUST be removed after successful closure and distillation.
Git or the repository's equivalent history is the forensic record of what actually changed.
PPGP memory SHOULD preserve meaning and current state rather than duplicating Git chronology.
A substantial PPGP goal follows:
THINK -> FREEZE -> EXECUTE -> HARDEN -> SHIP -> DISTILL -> CLOSED
Inspect, research, compare alternatives and determine an executable strategy.
Record the selected strategy, critical invariants, Definition of Done and authority boundaries.
After FREEZE, an agent SHOULD NOT reopen strategy merely because another agent would have chosen differently.
Replanning is justified when new evidence materially invalidates a frozen assumption.
Perform the work autonomously within the frozen strategy and delegated authority.
Attack the implementation through tests, edge cases, security review, independent review or other relevant verification.
HARDEN improves the selected solution. It is not a default invitation to redesign it.
Verify the implementation in the environment required by the Definition of Done.
When production behavior is part of the Definition of Done, local success alone MUST NOT close the goal.
Move durable information into ROADMAP, MEMORY or CONSTITUTION as appropriate.
Discard temporary chronology and redundant execution detail.
DISTILL is a consolidation and garbage-collection phase. It is not the primary survival mechanism for an unfinished goal.
If a session is interrupted before DISTILL, current ACTIVE_GOAL state SHOULD still be sufficient to recover the active goal when combined with relevant repository evidence.
A goal is CLOSED only after synchronous Definition-of-Done requirements are verified and temporary working memory has been garbage-collected.
Inside a goal, implementations SHOULD use:
RETRIEVE -> ACT -> VERIFY -> DELTA
Load only the state and evidence relevant to the current decision.
Perform the next bounded action.
Check observable evidence rather than relying on model confidence.
Record only material state changes needed for continuation.
A DELTA SHOULD update repository-visible hot state when the change would materially affect recovery after interruption.
The loop repeats until the current phase exit condition is met.
A fresh agent SHOULD start from a minimal boot packet:
GOAL_CONTRACT
+ HOT_STATE
+ RELEVANT_MEMORY
+ RELEVANT_EVIDENCE
The implementation SHOULD avoid loading the complete project history unless required.
A recovery sequence SHOULD inspect, as relevant:
- repository agent instructions;
- ACTIVE_GOAL;
- selectively relevant durable memory;
git status;- recent relevant commits;
- verification evidence;
- NEXT_EXECUTABLE_ACTION.
If ACTIVE_GOAL says the strategy is frozen, recovery SHOULD resume execution rather than restart THINK by default.
Abrupt interruption before DISTILL MUST NOT by itself be treated as loss of the active goal if current repository-visible hot state exists.
When technical claims conflict, implementations SHOULD prefer more direct evidence.
A useful default order is:
production/runtime behavior
> automated verification
> current repository implementation
> Git history
> ACTIVE_GOAL
> durable MEMORY
> ROADMAP
> conversation claims
> agent recollection
CONSTITUTION remains authoritative for project policy and authority, but technical documentation MUST be corrected when contradicted by observable reality.
PPGP uses four blocker classes.
Reversible technical or implementation problem.
Action: solve autonomously.
Propagation, crawler refresh, external processing or another event that may complete later.
Action: record it. Do not block synchronous goal closure unless the Definition of Done explicitly requires it.
Requires human/product/legal/financial/account authority.
Action: escalate with the smallest decision required.
Required information or resource is genuinely unavailable and no safe autonomous path exists.
Action: escalate only after autonomous alternatives are exhausted.
Agents MUST NOT promote routine Type A decisions to Type C solely to avoid responsibility.
The default is agent autonomy inside established authority.
Human escalation SHOULD be reserved for matters such as irreversible destructive actions, legal or financial commitments, unavailable credentials or external authorization, genuinely ambiguous product policy, brand or governance authority, material changes to frozen architecture, and actions outside delegated permissions.
Routine debugging, reversible refactors, test failures and ordinary implementation choices SHOULD NOT require human interruption.
PPGP does not require multiple agents.
A second agent SHOULD be introduced only when its expected independent information gain exceeds communication and coordination cost.
Useful examples include adversarial review, security review, linguistic review, architecture challenge and independent verification.
A reviewer SHOULD receive the artifact, requirements and relevant facts without unnecessary exposure to the implementer's self-assessment.
Handoffs SHOULD prefer compact structured state or deltas over narrative transcripts.
Example:
PPGP/0.1.2
G=8
P=HARDEN
F:
strategy=frozen
seo_ready=page
D:
ja_review=PASS
tests=PASS
B:
master_text=AUTH
E:
commit=8f3d55b
N:
review_de
ship
The exact encoding is not normative.
The invariant is that the handoff remain unambiguous, portable, auditable and cheaper than replaying the conversation.
Opaque model-specific gibberish is NOT required for PPGP conformance.
Before closing a goal, every material ACTIVE_GOAL fact SHOULD be classified:
strategic authority/invariant -> CONSTITUTION
current/future direction -> ROADMAP
durable reusable lesson -> MEMORY
temporary execution detail -> discard
Git remains the detailed forensic archive.
Failure to distill MAY increase long-term state noise or rediscovery cost, but it SHOULD NOT make a still-active, correctly checkpointed goal unrecoverable.
After successful distillation, ACTIVE_GOAL MUST be deleted.
Implementations MAY measure:
- HIG: Human Interruptions per Completed Goal.
- TPG: Tokens per Completed Goal.
- RSR: Recovery Success Rate.
- VWR: Verified Work Rate.
- MCR: Memory Compression Ratio.
PPGP v0.1.2 defines these metrics but makes no benchmark claim.
A PPGP implementation MUST NOT require a specific model provider.
It MAY integrate with native model compaction, Agent Skills, MCP, vector or semantic retrieval, IDE-specific hooks, provider-specific memory, and multi-agent orchestration.
Such integrations are optional accelerators. The repository-visible control state SHOULD remain sufficient for recovery by another compatible agent.
PPGP logical roles may be mapped to existing project documents.
A common mapping is:
CONSTITUTION -> docs/MASTER.md
ROADMAP -> docs/ROADMAP.md
MEMORY -> docs/PROJECT_MEMORY.md
ACTIVE_GOAL -> docs/ACTIVE_GOAL.md
FORENSICS -> Git
Implementations SHOULD reuse equivalent existing documents instead of creating duplicate sources of truth.
A useful PPGP recovery test is:
- Agent A begins a substantial goal.
- Agent A records current ACTIVE_GOAL state after at least one material verified change.
- Context is compacted, lost or deliberately removed before DISTILL.
- Agent B starts without the prior conversation.
- Agent B reads repository-visible PPGP state.
- Agent B correctly identifies the goal, phase, frozen decisions, verified state, remaining work, blockers and next executable action.
- Agent B continues without asking the human to reconstruct prior history.
- The goal is eventually verified, distilled and closed.
A system that cannot pass this recovery test SHOULD NOT claim robust PPGP continuity.
Passing one recovery test demonstrates recovery under that tested condition only. It does not establish universal effectiveness or superiority.
PPGP uses semantic specification versions.
v0.x releases are experimental and may change incompatibly.
The community is encouraged to report failures before the protocol is declared stable.