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.

[Fatboy-coder]

Adversarial validation update (2026-09-23):

The published v0.1.2 protocol was stress-tested across context loss, handoff, interruption recovery, external observation windows, single-goal stress, independent projects, OCPDF/SCP cross-project references, stale/false completion cases, malformed state, Git/worktree cases, self-hosting and minimal-project ceremony.

No reproducible core protocol semantic failure was demonstrated in the tested scenarios. Several concepts implemented in this draft — RUN_STATE, DoD levels, first-class waits/gates, DEPENDS_ON, TARGET, MISSION and a goal registry — were not shown necessary by that campaign.

The current evidence therefore supports keeping v0.1.2 semantics and pursuing a v0.1.3 hardening candidate focused on parser/diagnostics, Git root/ref visibility, documentation and regression tests.

This PR should remain research/draft material rather than the default release path unless new reproducible evidence demonstrates a core limitation that requires the richer coordination model.

Canonical record now on main: ADR-style validation report in ADVERSARIAL_VALIDATION.md and updated ROADMAP.md (merge commit f7858d8).

[Fatboy-coder]

Closing this draft as superseded by evidence, with the work preserved.

• The exact head of this branch, af5a2daceae41b2acca40299ca072be5b0613b16, is preserved unchanged on branch research/v0.2-concurrency-experiment (verified with git ls-remote). Nothing was merged, squashed or rewritten.
• The 2026-09-23 adversarial validation of the published v0.1.2 package (research/2026-09-23-adversarial-validation.md on the v0.1.3 branch) did not reproduce a core semantic failure that requires the richer portfolio / workstream / lease / checkout-claim model proposed here. Seventeen of eighteen scenarios were representable with the existing thirteen-field ACTIVE_GOAL model; the failures found were in the CLI and documentation.
• The evidence-backed release path is therefore the v0.1.3 hardening candidate (PR release: PPGP v0.1.3 hardening candidate #12): same protocol, tolerant parser with strict conformance, diagnostics, root discovery, ref visibility, regression suite.

If a future reproducible failure shows that v0.1.x cannot safely express a real concurrent workflow, this branch is the starting point. Until then it is research, not the next release. ROADMAP.md on the v0.1.3 branch records this.

[Fatboy-coder]

Superseded by evidence; preserved on research/v0.2-concurrency-experiment. See the comment above.