feat: PPGP v0.2.0 portfolio coordination release candidate

[Fatboy-coder]

PPGP v0.2.0 release-candidate implementation, extracted from real multi-agent coordination and recovery failures and reconciled with an independent Codex design proposal.

What v0.2 adds

• optional PORTFOLIO / WORKSTREAM coordination while preserving the v0.1.x single-ACTIVE_GOAL path
• PHASE separated from neutral RUN_STATE
• RUNNABLE | RUNNING | WAITING | RECOVERY_REQUIRED | PARKED | COMPLETED
• typed/scoped wait conditions (EXTERNAL | AUTHORITY | TECHNICAL; ACTION | WORKSTREAM | GOAL | PROJECT)
• action-scoped authority gates (REQUIRED | GRANTED | CONSUMED | REVOKED)
• explicit acyclic dependencies
• execution leases with monotonically increasing generations
• reference JSON state with integer revisions and stale-write rejection
• local exclusive checkout claims in the Git common directory
• checkout/branch validation and foreign-dirty-work protection
• non-destructive abrupt takeover
• SESSION_ONLY / HOST_DURABLE / REPO_DURABLE / REMOTE_DURABLE recovery classes
• recovery-time workspace observation distinguishing tracked state, untracked state, ownership and sensitivity when those dimensions matter
• explicit durability promotion so an older REMOTE_DURABLE checkpoint does not upgrade newer HOST_DURABLE edits
• claim/mechanism/evidence/canonical-state consistency before closure
• explicit rule that session/UI labels and narrative state do not silently supersede observed canonical state
• copy-first reversible migration with one canonical source after cutover
• progressive-disclosure coordination reference
• reference portfolio/workstream JSON Schemas
• v0.2 conformance/evaluation cases

Core invariants

PORTFOLIO != WORKSTREAM != LEASE HOLDER != CHECKOUT
executor unavailable != workstream blocked
blocked action != blocked workstream
blocked workstream != blocked project

Recovery invariant:

OBSERVE
-> PRESERVE
-> RECONCILE
-> VERIFY
-> PROMOTE DURABILITY
-> CONTINUE

Newly observed recovery evidence

Incident 001 now includes the completed real recovery sequence:

• one workstream continued safely in an isolated worktree while another checkout remained occupied;
• an external dependency blocked only the remote action, not useful local engineering;
• the executor disappeared with newer dirty work that was HOST_DURABLE while an older checkpoint was already REMOTE_DURABLE;
• the returning executor recovered the existing diff instead of rebuilding from memory;
• focused/full verification passed;
• explicit-path staging preserved foreign/sensitive local artifacts;
• a new commit was pushed and only then was the recovered work promoted to REMOTE_DURABLE;
• a misleading session/UI uncommitted changes display was reconciled against direct VCS evidence without destructive normalization.

These observations produced new evaluation cases for UI/VCS disagreement, foreign untracked sensitive state, durability promotion and claim/mechanism/evidence/canonical-state consistency.

Reference implementation boundary

PPGP core does not require JSON, Git worktrees, MCP, a database, lock service or orchestrator.

The official CLI uses .ppgp/ JSON as a reference implementation. Local CLI mutations use observed revisions plus local mutation locks. Multi-machine writers require an atomic/CAS adapter or equivalent runtime mechanism.

The richer workspace observation profile is recovery guidance, not a new mandatory committed schema.

The original paired A/B recovery benchmark remains explicitly versioned to PPGP v0.1.2. It has not been relabeled as a v0.2 coordination benchmark. v0.2 coordination evaluation cases live in EVALUATION.md.

Verification baseline

Release-candidate commit 6dda7d0 previously passed on GitHub Actions:

• Ubuntu: npm test PASS
• Ubuntu: installed-package CLI test PASS
• Windows: npm test PASS
• Windows: installed-package CLI test PASS

The recovery-evidence delta after that RC is documentation/protocol guidance only; final CI on the current head remains the release gate.

Review focus before merge/release

Please challenge especially:

1. blocker/wait scoping and portfolio aggregation semantics;
2. lease-generation takeover/fencing semantics;
3. checkout claim safety under concurrent worktrees;
4. tracked/untracked/ownership/sensitivity workspace observation during recovery;
5. HOST_DURABLE -> REPO_DURABLE -> REMOTE_DURABLE promotion semantics;
6. migration/rollback boundary after cutover;
7. reference-CLI CAS guarantees versus manual JSON editing;
8. local lock behavior after an abrupt process death;
9. claim/mechanism/evidence/canonical-state consistency;
10. whether initial executor assignment deserves a distinct future workstream claim command instead of using handoff/assignment semantics.

Release boundary

This PR remains a draft release candidate. It does not create the immutable v0.2.0 GitHub Release/tag and does not publish @fatboy-coder/ppgp@0.2.0 to npm. Those steps remain gated on final independent review and current-head CI.

No superiority, universality, peer-review, or vendor-endorsement claim is made.