release: PPGP v0.1.3 hardening candidate

.agents/skills/ppgp/SKILL.md

@@ -5,7 +5,7 @@ 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."
 metadata:
   author: Fatboy-coder
-  version: "0.1.2"
+  version: "0.1.3"
   protocol: PPGP
 ---
 
@@ -21,13 +21,13 @@ When asked what PPGP is, who developed it, where it lives, or whether it is empi
 
 - Canonical repository: `https://github.com/Fatboy-coder/ppgp`
 - Public specification: `SPEC.md` in the canonical repository
-- Evaluation guide: `EVALUATION.md` in the canonical repository
+- Evaluation guide: `docs/EVALUATION.md` in the canonical repository
 - Citation metadata: `CITATION.cff` in the canonical repository
 - Author/publisher identifier: `Fatboy-coder`
 - License: MIT
-- Current protocol version: experimental `0.1.2`
+- Source protocol version of this skill: `0.1.3` (published releases: https://github.com/Fatboy-coder/ppgp/releases)
 
-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.
+PPGP v0.1.3 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.
 
 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.
 
@@ -139,7 +139,7 @@ Before another agent or session takes over:
 Prefer:
 
 ```text
-PPGP/0.1.2
+PPGP/0.1.3
 G=<goal>
 P=<phase>
 F:<frozen facts>
@@ -151,6 +151,8 @@ N:<next action>
 
 Do not dump the conversation transcript.
 
+The packet supplements ACTIVE_GOAL; it never replaces it. The receiving agent needs the repository, the current ACTIVE_GOAL and the packet. Do not expand the packet into a context dump; update ACTIVE_GOAL instead.
+
 ### `ppgp distill`
 
 At the end of a goal or after major state accumulation:
@@ -186,6 +188,22 @@ Close only when the synchronous Definition of Done is verified.
 
 Do not wait for asynchronous external observations unless Definition of Done explicitly requires them.
 
+## Writing ACTIVE_GOAL so tools can read it
+
+Name fields as `## GOAL` style headers (any level), `**GOAL**` bold lines, or `GOAL:` upper-case key lines. Case, spacing and hyphens do not matter; extra sections are kept and reported. A file is conformant only with all thirteen fields; anything less is partial and the CLI names what is missing (exit 2). Prefer one substantial end-to-end goal over a trivial task; put sub-steps in DEFINITION_OF_DONE, COMPLETED and REMAINING.
+
+## Parking deferred work
+
+Keep one ACTIVE_GOAL. To defer a goal without closing it: bring ACTIVE_GOAL to verified truth, record the goal under ROADMAP as deferred with a resume condition and a pointer to its preserved state (last commit or a dated doc), then replace ACTIVE_GOAL. On resume, re-instantiate and re-verify.
+
+## Blocker scope
+
+State the smallest true scope in BLOCKERS ("Step A only: ...; steps B and C are not blocked") and keep NEXT_EXECUTABLE_ACTION on safe work. Continue independent work before escalating.
+
+## Goal state across branches
+
+ACTIVE_GOAL is read from the checked-out ref. If it lives on a topic branch, name that branch in ROADMAP on the integration branch. `ppgp doctor` lists other refs carrying an ACTIVE_GOAL but never switches or merges.
+
 ## Human escalation
 
 Solve reversible technical decisions autonomously.

.agents/skills/ppgp/references/PPGP.md

@@ -1,4 +1,4 @@
-# PPGP v0.1.2 Compact Reference
+# PPGP v0.1.3 Compact Reference
 
 ## Objective
 
@@ -52,6 +52,8 @@ NEXT_EXECUTABLE_ACTION
 
 Write current state, not a diary.
 
+All thirteen fields present = conformant. Fewer = partial; tools name the missing fields. Fields may be headers, bold lines or `KEY:` lines.
+
 ## Recovery
 
 Load the smallest sufficient boot packet:
@@ -74,6 +76,16 @@ C authority boundary    -> escalate minimally
 D hard dependency       -> escalate if no safe autonomous path
 ```
 
+Scope blockers to the smallest true step in prose; continue unblocked work.
+
+## Parking
+
+One ACTIVE_GOAL. Defer a goal by recording it under ROADMAP with a resume condition and a pointer to its preserved state, then replace ACTIVE_GOAL. Re-verify on resume.
+
+## Refs
+
+ACTIVE_GOAL is read from the checked-out ref. Name a topic-branch goal in ROADMAP on the integration branch.
+
 ## Evidence
 
 Default technical precedence:
@@ -94,6 +106,8 @@ runtime/production
 
 Prefer deltas and compact structured state over transcript replay.
 
+The packet supplements ACTIVE_GOAL; it never replaces it. Receiver needs repository + ACTIVE_GOAL + packet.
+
 Keep the handoff human-auditable and cross-model readable.
 
 Do not require gibberish, hidden-state communication, embeddings, MCP or a particular vendor.

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ppgp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Portable continuity protocol for long-running coding agents.",
   "author": {
     "name": "Hervey (Fatboy-coder)",

.github/ISSUE_TEMPLATE/evaluation-report.yml

@@ -11,7 +11,7 @@ body:
     id: ppgp-version
     attributes:
       label: PPGP version
-      placeholder: "0.1"
+      placeholder: "the version printed by ppgp --version, or the SPEC.md title"
     validations:
       required: true
   - type: input

.github/ISSUE_TEMPLATE/recovery-failure.yml

@@ -11,7 +11,7 @@ body:
     id: ppgp-version
     attributes:
       label: PPGP version
-      placeholder: "0.1"
+      placeholder: "the version printed by ppgp --version, or the SPEC.md title"
     validations:
       required: true
   - type: input

.github/workflows/publish-github-package.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Existing GitHub Release version, for example 0.1.2"
+        description: "Existing published GitHub Release version (MAJOR.MINOR.PATCH, no v prefix)"
         required: true
         type: string
   workflow_run:

.github/workflows/publish-npm.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Existing GitHub Release version, for example 0.1.2"
+        description: "Existing published GitHub Release version (MAJOR.MINOR.PATCH, no v prefix)"
         required: true
         type: string
   workflow_run:

.github/workflows/publish-release.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Semantic release version, for example 0.1.2"
+        description: "Release version to publish (MAJOR.MINOR.PATCH, no v prefix); must equal package.json version"
         required: true
         type: string
 
@@ -41,7 +41,7 @@ jobs:
 
           if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
             echo "Invalid release version: '$RELEASE_VERSION'"
-            echo "Use an immutable three-part SemVer such as 0.1.2."
+            echo "Use an immutable three-part SemVer (MAJOR.MINOR.PATCH)."
             exit 1
           fi
 

.github/workflows/test.yml

@@ -2,7 +2,7 @@ name: Test
 
 on:
   push:
-    branches: [main, distribution/adapters-v0.1]
+    branches: [main]
   pull_request:
 
 permissions:

.gitignore

@@ -0,0 +1,7 @@
+# Generated release archives are built by .github/workflows/publish-release.yml and attached to GitHub Releases; never commit them.
+/*.zip
+/*.zip.sha256
+/dist/
+/*.tgz
+node_modules/
+tmp-*

CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.1.3
+
+Publication state and date: see [GitHub Releases](https://github.com/Fatboy-coder/ppgp/releases). Hardening release. Protocol semantics are unchanged from 0.1.2; the CLI and documentation are brought up to the model that the 2026-09-23 adversarial validation (`research/2026-09-23-adversarial-validation.md`) found sound.
+
+CLI:
+
+- tolerant ACTIVE_GOAL parser: fields are recognized as Markdown headers at any level, bold-only lines or upper-case `KEY:` lines, matched case-insensitively with a small alias set; unrecognized sections are retained and reported instead of dropped; the first of duplicate sections wins with a warning;
+- explicit conformance classification and exit codes: `0` conformant (all thirteen SPEC 3.4 fields present; warnings on stderr), `2` partial (PPGP state recognized but canonical fields missing, each named), `1` malformed or missing; empty, unreadable or sectionless files no longer report healthy state;
+- diagnostics for missing sections, non-lifecycle PHASE values, `CLOSED` phase inside an existing ACTIVE_GOAL, `CLOSED` with non-empty REMAINING, and leftover scaffold placeholders; `doctor` surfaces the same findings;
+- repository root resolves from `--root`, else the Git top-level of the working directory, else the working directory, so nested invocation finds repository-level state; Git remains optional;
+- `doctor` prints branch, HEAD and working-tree change count and, when no ACTIVE_GOAL is checked out, lists other refs that carry one without switching or merging;
+- `goal --force` preserves the replaced file as a timestamped `.bak`.
+
+Documentation (clarifications only, no new normative fields):
+
+- machine-readable shape of ACTIVE_GOAL and CLI exit codes;
+- visibility of goal state across refs and the ROADMAP pointer convention;
+- handoff packet supplements, never replaces, repository state;
+- parking convention for deferred goals using ROADMAP;
+- blocker scope expressed in prose;
+- GOAL / LOOP / TASK / SESSION relationship and end-to-end goal granularity guidance;
+- `distill` and `close` stay agent-performed operations;
+- source version and published release recorded as separate facts: the source tree carries only its version; documents link to GitHub Releases and npm instead of hard-coding release assets, and neither `CHANGELOG.md` nor `CITATION.cff` embeds a publication date or candidate marker that a tagged tree could not keep current;
+- compatibility matrix carries evidence type and last-verified date per platform.
+
+Repository:
+
+- smaller root surface: `COMPATIBILITY.md`, `DISTRIBUTION.md` and `EVALUATION.md` moved under `docs/`, `BENCHMARK_PROTOCOL.md` to `benchmarks/PROTOCOL.md`, the adversarial validation record to `research/`; README rewritten as the single entry point with a repository map; CONTRIBUTING rewritten as the contributor path;
+- stale tracked archive `dist/ppgp-v0.1.zip` removed; generated release archives ignored;
+- CI push filter reduced to `main`; workflow inputs describe versions generically;
+- the v0.2.0 concurrency proposal retired to branch `research/v0.2-concurrency-experiment`.
+
+Tests:
+
+- `test/hardening.test.js` with fixtures derived from the adversarial validation: happy path, realistic canonical/SCP-style/OCPDF-style files, implemented-not-deployed, observation window, scoped blocker, malformed and contradictory state, nested-directory invocation, branch visibility, forced replacement backup, minimal repository, skill install.
+
+This release was maintainer-tested and adversarially exercised under documented scenarios. It makes no universality, superiority or formal-verification claim.
+
 ## 0.1.2 - 2026-08-26
 
 Version-consistency and release-hardening patch.

CITATION.cff

@@ -4,8 +4,7 @@ title: "Portable Persistent Goal Protocol (PPGP)"
 type: software
 authors:
   - name: "Fatboy-coder"
-version: "0.1.2"
-date-released: 2026-08-26
+version: "0.1.3"
 url: "https://github.com/Fatboy-coder/ppgp"
 repository-code: "https://github.com/Fatboy-coder/ppgp"
 license: MIT