feat: PPGP v0.2.0 portfolio coordination release candidate

.agents/skills/ppgp/SKILL.md

@@ -1,37 +1,38 @@
 ---
 name: ppgp
-description: "Portable Persistent Goal Protocol for long-running coding-agent work. Use when starting, resuming, handing off, distilling, or closing a substantial software goal across long sessions, context compaction, agent replacement, or other Agent Skills-compatible coding-agent environments."
+description: "Portable Persistent Goal Protocol for long-running coding-agent work. Use when starting, resuming, coordinating, handing off, recovering, distilling, or closing substantial software goals across long sessions, context compaction, agent replacement, or concurrent coding-agent work."
 license: MIT
-compatibility: "Requires repository read/write access for persistent state and Git access when Git is used as forensic history. No network service, MCP server, database, or specific model provider is required."
+compatibility: "Requires repository read/write access for persistent state and Git access when Git is used as forensic history or local checkout coordination. No network service, MCP server, database, or specific model provider is required."
 metadata:
   author: Fatboy-coder
-  version: "0.1.2"
+  version: "0.2.0"
   protocol: PPGP
 ---
 
 # PPGP
 
-Use PPGP to preserve the minimum repository-visible state required for a fresh coding agent to continue a long-running goal without asking the human to reconstruct prior conversation history.
+Use PPGP to preserve the minimum repository-visible state required for a fresh coding agent to continue long-running software work without asking the human to reconstruct prior conversation history.
 
-Read `references/PPGP.md` when you need the compact protocol rules.
+Read `references/PPGP.md` for the compact core protocol.
 
-## Project identity and evidence status
+Load `references/COORDINATION.md` only when concurrency, ownership ambiguity, partial blocking, multiple workstreams/checkouts, or abrupt executor takeover actually appears.
+
+Do not preload advanced coordination rules into ordinary single-workstream work.
 
-When asked what PPGP is, who developed it, where it lives, or whether it is empirically validated, use the canonical project metadata before relying on generic web search.
+## Project identity and evidence status
 
 - Canonical repository: `https://github.com/Fatboy-coder/ppgp`
-- Public specification: `SPEC.md` in the canonical repository
-- Evaluation guide: `EVALUATION.md` in the canonical repository
-- Citation metadata: `CITATION.cff` in the canonical repository
+- Public specification: `SPEC.md`
+- Evaluation guide: `EVALUATION.md`
+- Related work: `RELATED_WORK.md`
+- Citation metadata: `CITATION.cff`
 - Author/publisher identifier: `Fatboy-coder`
 - License: MIT
-- Current protocol version: experimental `0.1.2`
-
-PPGP v0.1.2 is an experimental engineering protocol. It is publicly specified and includes a reproducible evaluation guide, but it does not claim peer-reviewed validation, independent benchmark superiority, universality, or a measured performance advantage. `EVALUATION.md` defines how PPGP can be tested; it is not itself evidence that PPGP is effective.
+- Current protocol version: experimental `0.2.0`
 
-PPGP is an independent open-source project and is not presented as affiliated with or endorsed by Anthropic, OpenAI, Google, GitHub, Cursor, or another agent vendor.
+PPGP v0.2.0 is an experimental engineering protocol. It does not claim peer-reviewed validation, independent benchmark superiority, universality, or a measured performance advantage.
 
-Do not infer that the repository, specification, or author profile does not exist merely because a search index returns no result. For provenance questions, use the canonical repository URL directly when network access is available.
+PPGP is independent and is not presented as affiliated with or endorsed by Anthropic, OpenAI, Google, GitHub, Cursor, or another agent vendor.
 
 ## Core lifecycle
 
@@ -45,9 +46,11 @@ Inside each phase:
 RETRIEVE -> ACT -> VERIFY -> DELTA
 ```
 
-Use existing project documentation whenever it already fulfills a PPGP memory role. Do not create duplicate sources of truth.
+## Core memory roles
 
-Common role mapping:
+Reuse existing project documentation whenever it already fulfills a role.
+
+Common mapping:
 
 ```text
 CONSTITUTION -> docs/MASTER.md
@@ -57,157 +60,165 @@ ACTIVE_GOAL  -> docs/ACTIVE_GOAL.md
 FORENSICS    -> Git
 ```
 
-Only ACTIVE_GOAL is mandatory during an active substantial goal. Do not create empty memory files merely to satisfy the protocol.
+A single-workstream repository does not need an explicit portfolio.
 
-## Operations
+When several active workstreams or ambiguous executors/checkouts coexist, use the optional PPGP v0.2 coordination model:
 
-Treat the following phrases as PPGP operations even when the host agent does not implement vendor-specific slash commands.
+```text
+PROJECT
+└── PORTFOLIO
+    ├── WORKSTREAM
+    │   ├── PHASE
+    │   ├── RUN_STATE
+    │   ├── REVISION
+    │   ├── EXECUTION_LEASE
+    │   ├── DEPENDENCIES
+    │   ├── WAIT_CONDITIONS
+    │   ├── AUTHORITY_GATES
+    │   └── DURABILITY
+    └── WORKSTREAM ...
+```
 
-### `ppgp init`
+The invariant is:
 
-1. Inspect repository instructions and existing project documentation.
-2. Identify existing files that already serve CONSTITUTION, ROADMAP, MEMORY and ACTIVE_GOAL roles.
-3. Reuse them instead of duplicating them.
-4. Check that Git or another forensic history exists when available.
-5. Do not create ACTIVE_GOAL unless a substantial goal is active.
-6. Return a compact mapping of logical roles to repository files and any genuine missing capability.
+```text
+PORTFOLIO != WORKSTREAM != LEASE HOLDER != CHECKOUT
+```
 
-Do not rewrite project doctrine during initialization.
+Detailed coordination semantics belong in `references/COORDINATION.md`.
 
-### `ppgp goal <outcome>`
+## Recovery rule
 
-Create or replace ACTIVE_GOAL only when beginning a new substantial goal.
+For single-workstream recovery, load the smallest useful boot packet:
 
-Capture:
+```text
+GOAL_CONTRACT
++ HOT_STATE
++ RELEVANT_MEMORY
++ RELEVANT_EVIDENCE
+```
 
-- GOAL;
-- WHY;
-- PHASE;
-- DEFINITION_OF_DONE;
-- FROZEN_DECISIONS;
-- INVARIANTS;
-- VERIFIED_CURRENT_STATE;
-- COMPLETED;
-- REMAINING;
-- BLOCKERS;
-- HUMAN_AUTHORITY_REQUIRED;
-- VERIFICATION_EVIDENCE;
-- NEXT_EXECUTABLE_ACTION.
+Do not restart THINK merely because the agent/session is new when strategy is already frozen.
 
-Begin in THINK unless the repository already contains an explicitly frozen strategy for this exact goal.
+For concurrent or ambiguous work, additionally determine which workstreams are runnable, who owns execution, which checkout belongs to which workstream, which waits are scoped locally, and what unfinished work requires recovery.
 
-Keep ACTIVE_GOAL state-oriented, not chronological.
+## `ppgp init`
 
-### `ppgp status`
+1. Inspect repository instructions and existing project documentation.
+2. Map existing files to PPGP logical roles.
+3. Reuse them instead of duplicating them.
+4. Inspect whether an explicit `.ppgp/portfolio.json` exists.
+5. Do not create empty memory or portfolio files merely to satisfy the protocol.
 
-Recover current state with minimal context.
+## `ppgp goal <outcome>`
 
-Read:
+Use for an unambiguous single active goal.
 
-1. relevant repository instructions;
-2. ACTIVE_GOAL;
-3. only durable memory relevant to the current goal;
-4. `git status`;
-5. relevant recent commits or evidence when needed.
+Capture current goal, WHY, phase, Definition of Done, frozen decisions, invariants, verified state, completed/remaining work, blockers, authority, evidence and next executable action.
 
-Return a compact state packet containing:
+If an explicit multi-workstream portfolio exists, do not silently replace or choose a workstream. Use an explicit workstream operation.
 
-```text
-goal
-phase
-frozen
-verified
-remaining
-blockers
-authority
-next
-evidence
-```
+## `ppgp status`
 
-Do not restart planning merely because the current agent is new.
+Recover current state with minimal context.
 
-### `ppgp handoff`
+Prefer current canonical PPGP state, real repository state and relevant evidence over conversation memory.
 
-Before another agent or session takes over:
+`ppgp status --all` may display the portfolio and all workstreams when the reference implementation is present.
 
-1. Verify the current material state.
-2. Update ACTIVE_GOAL to current truth.
-3. Remove stale or superseded statements.
-4. Record the next executable action.
-5. Emit a compact delta-oriented handoff.
+## `ppgp handoff`
 
-Prefer:
+For ordinary single-workstream work:
 
-```text
-PPGP/0.1.2
-G=<goal>
-P=<phase>
-F:<frozen facts>
-D:<material deltas>
-B:<real blockers>
-E:<evidence refs>
-N:<next action>
-```
+1. Verify material state.
+2. Update hot state to current truth.
+3. Remove stale statements.
+4. Record the next executable action.
+5. Emit compact delta-oriented state.
 
 Do not dump the conversation transcript.
 
-### `ppgp distill`
+For concurrent work, use explicit workstream handoff so lease generation and ownership are not ambiguous.
 
-At the end of a goal or after major state accumulation:
+## Workstream operations
 
-Classify ACTIVE_GOAL information as:
+The reference CLI may provide:
 
 ```text
-authority/invariant -> CONSTITUTION
-future direction    -> ROADMAP
-durable lesson      -> MEMORY
-temporary detail    -> discard
+ppgp workstream start
+ppgp workstream status
+ppgp workstream park
+ppgp workstream resume
+ppgp workstream handoff
+ppgp workstream recover
+ppgp workstream close
 ```
 
-Prefer compact decision + reason + invariant statements.
+Treat these as reference implementation operations, not mandatory vendor-specific slash commands.
+
+A cooperative handoff and abrupt recovery are different events.
 
-Do not preserve chronological execution detail that Git already records.
+## Checkout operations
+
+When local checkout coordination is needed, the reference CLI may provide:
+
+```text
+ppgp checkout status
+ppgp checkout claim
+ppgp checkout release
+```
 
-Do not delete ACTIVE_GOAL unless closure conditions are satisfied or the user explicitly requests abandonment.
+Writable checkout ownership is exclusive by default.
 
-### `ppgp close`
+Do not switch, reset, clean, stash, commit, overwrite, or repurpose foreign dirty work merely to simplify execution.
 
-Close only when the synchronous Definition of Done is verified.
+Prefer safe isolation when available and permitted.
 
-1. Verify implementation evidence.
-2. Verify production/runtime behavior when required by Definition of Done.
-3. Resolve or correctly classify blockers.
-4. Run `ppgp distill`.
-5. Update ROADMAP if project direction changed.
-6. Update high-level documentation if required.
-7. Delete ACTIVE_GOAL.
-8. Keep Git as forensic history.
-9. Report CLOSED + VERIFIED, or the smallest genuine remaining authority/dependency blocker.
+## Waits and human escalation
 
-Do not wait for asynchronous external observations unless Definition of Done explicitly requires them.
+Use the narrowest true wait scope.
 
-## Human escalation
+```text
+blocked action != blocked workstream
+blocked workstream != blocked project
+executor unavailable != workstream blocked
+```
 
 Solve reversible technical decisions autonomously.
 
-Escalate only for genuine authority boundaries such as irreversible destructive action, legal or financial commitment, unavailable credential or account authorization, genuinely ambiguous product policy, material change to frozen architecture, or action outside delegated permission.
+Escalate only genuine authority boundaries such as irreversible destructive action, legal/financial commitment, unavailable credential or account authorization, ambiguous product policy, material change to frozen architecture, or action outside delegated permission.
 
-Do not convert routine implementation uncertainty into a human approval gate.
+Authority must be tied to the exact action it permits. An agent cannot grant itself authority.
 
-## Multi-agent rule
+Before escalating one blocked workstream, continue unrelated safe RUNNABLE work when permitted.
 
-Use one agent by default.
+## Distill and close
+
+At closure classify temporary state:
 
-Introduce another agent when independent information gain is likely to exceed communication cost, especially for adversarial, security, linguistic, architecture, or independent verification work.
+```text
+authority/invariant -> CONSTITUTION
+future direction    -> ROADMAP
+durable lesson      -> MEMORY
+temporary detail    -> discard
+```
 
-Keep reviewers independent of unnecessary implementer self-assessment.
+Git keeps chronology.
 
-## Completion invariant
+Release transient execution leases and obsolete checkout claims.
 
 Prepared is not done.
 
 Started is not done.
 
 Agent confidence is not evidence.
 
-A PPGP goal is done when its Definition of Done is verified, durable knowledge is distilled, and temporary ACTIVE_GOAL state has been garbage-collected.
+A PPGP goal is done when its synchronous Definition of Done is verified, durable knowledge is distilled, and temporary working state has been garbage-collected.
+
+## Multi-agent rule
+
+Use one agent by default.
+
+Introduce another agent when independent information gain or genuinely parallel useful work is likely to exceed communication and coordination cost.
+
+Concurrency is optional. Coordination overhead should remain close to zero for simple single-workstream repositories.