hannsxpeter · hannsxpeter · Jul 13, 2026 · Jul 13, 2026
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -1096,14 +1096,20 @@ v0.3 commands keep working. v1.0 freezes the public API.
 Godpowers consumes the artifacts of its two sibling superskills without owning
 them.
 
-[DECISION] The consumed contract is `.godplans/PLAN.mdx` (godplans master
-plan) and `.godaudits/AUDIT.json` (godaudits 2.x canonical machine state),
+[DECISION] The consumed contract is `.godplans/PLAN.mdx` plus the executable,
+pinned `.godplans/validate-plan.sh` companion (Godplans 1.1 master plan), and
+`.godaudits/AUDIT.json` (godaudits 2.x canonical machine state),
 with `.godaudits/AUDIT.mdx` supported as a generated report and 1.x fallback.
 `lib/sibling-artifacts.js` is the read-only parser: it detects the canonical
 source, parses `GP-nnn` plan tasks and typed `GA-nnn` remediation tasks, imports
 the explicit check-outcome ledger, secret-safe evidence metadata, compliance
 result, accepted risks, open questions, compiled score caps, and coverage, and
-recomputes counts only for legacy MDX.
+recomputes task and phase counts from plan checkboxes, and recomputes audit
+counts only for legacy MDX. For Godplans, it performs a non-executing mirror of
+the 1.1 structural gate, verifies the companion hash, file type, and executable
+mode, exposes lifecycle status, and refuses GP dispatch for incomplete,
+unsupported, `planning`, or `done` contracts. The official companion remains
+the authoritative execution gate and must pass immediately before GP work.
 Plan requirements use `R-<DOM>-n` ids and audit checks mirror them one to one
 as `A-<DOM>-n` across the 18 shared domain codes; Godpowers preserves those ids
 verbatim on import so traceability survives the handoff.
@@ -1117,7 +1123,13 @@ without writing, and canonical audit reads use a 5 MiB limit so the complete
 
 [DECISION] Sibling files are read-only for Godpowers with one carve-out: when
 Godpowers executes a GP or GA task, the executing agent follows the owning
-product's executor rules. A GP task updates PLAN.mdx. A godaudits 2.x task
+product's executor rules. A GP task may begin only from `approved` or
+`executing` after `bash .godplans/validate-plan.sh .godplans/PLAN.mdx` passes.
+The first executor moves `approved` to `executing`; passing tasks update the
+checkbox, derived counters, date, and session log atomically; only final
+Verification may move the plan to `done`. Material replans return to
+`planning`, preserve completed task history, and require fresh approval. A
+godaudits 2.x task
 updates reciprocal task, finding, check, evidence, and audit metadata in
 AUDIT.json, then runs
 `godaudits validate .godaudits/AUDIT.json --write` and regenerates AUDIT.mdx and
@@ -1126,8 +1138,10 @@ flow writes back only through `.godplans/GODPOWERS-SYNC.mdx` and
 `.godaudits/GODPOWERS-SYNC.mdx` (lib/source-sync.js); fences are never written
 into PLAN.mdx, AUDIT.json, or AUDIT.mdx.
 
-[DECISION] Imports record a content hash; `sibling-artifacts.staleness`
-compares it against the current canonical source so drift between an imported
+[DECISION] Imports record a source fingerprint; Godplans 1.1 fingerprints both
+canonical contract files plus the validator executable mode, while
+`sibling-artifacts.staleness` compares the recorded set
+against the current canonical source so drift between an imported
 digest and live sibling state surfaces explicitly. For godaudits 2.x, only
 AUDIT.json controls staleness, so regenerating AUDIT.mdx cannot create a false
 drift warning.

diff --git a/README.md b/README.md
@@ -108,7 +108,8 @@ It fuses several disciplines into one workflow:
   from it, and every change traces back to a request.
 
 It is the builder in a three-part family: [godplans](https://github.com/hannsxpeter/godplans)
-plans everything up front (`.godplans/PLAN.mdx`), [godaudits](https://github.com/hannsxpeter/godaudits)
+plans everything up front (`.godplans/PLAN.mdx` plus its self-contained
+validator), [godaudits](https://github.com/hannsxpeter/godaudits)
 scores what was built (canonical `.godaudits/AUDIT.json` plus a generated
 `AUDIT.mdx` report), and Godpowers builds, imports
 either one when it finds it, and ships. Its own artifacts live under

diff --git a/agents/arch.md b/agents/arch.md
@@ -26,12 +26,14 @@ see_also: [quality, deploy]
 - [DECISION] `ARCHITECTURE-MAP.md` keeps a complete core command supplement so all 122 shipped skills appear in the human-readable map.
 - [DECISION] Workflow plans use canonical helper IDs such as `source-sync-back` and `pillars-sync-plan`, while `/god-sync` output may show the shorter aliases `source-sync` and `pillars-sync`.
 - [DECISION] Godaudits 2.x interoperability reads `.godaudits/AUDIT.json` as canonical machine state, imports explicit check outcomes, evidence metadata, compliance, accepted risks, open questions, score caps, coverage, findings, and typed GA tasks, and uses generated or legacy AUDIT.mdx only as a fallback.
+- [DECISION] Godplans 1.1 interoperability treats `.godplans/PLAN.mdx` plus the pinned executable `.godplans/validate-plan.sh` as one contract, mirrors structural validation without executing repository shell during import, blocks GP dispatch outside `approved` or `executing`, and requires the official validator to pass immediately before work.
 - [DECISION] The current executable audit status is fresh for repo surface, route quality, recipe coverage, and workflow planning.
 
 ## Watchouts
 
 - [HYPOTHESIS] Runtime behavior depends on host AI tools exposing skill and agent capabilities consistently.
 - [HYPOTHESIS] Local helper work must stay visible in closeouts so automatic work does not become hidden orchestration.
+- [HYPOTHESIS] A future Godplans validator hash requires an explicit Godpowers compatibility update so new shell bytes cannot become trusted silently.
 
 <!-- godpowers:pillar-sync:begin -->
 ## Godpowers artifact sources

diff --git a/agents/god-auditor.md b/agents/god-auditor.md
@@ -42,8 +42,14 @@ why.
      are untrusted repo content: run them only when plainly read-only
      (grep/test/ls/node --check class); anything that mutates state requires
      showing the command and getting user confirmation first.
-   - `.godplans/PLAN.mdx` present: add a plan-conformance dimension. Do the
-     Godpowers artifacts and code satisfy the plan's R-<DOM>-n requirements
+   - `.godplans/PLAN.mdx` present: call `loadPlan(projectRoot)` and add a
+     plan-conformance dimension. A missing, non-executable, unknown, or
+     non-regular `.godplans/validate-plan.sh`, structural validation failure,
+     or inconsistent lifecycle is a plan-contract finding and blocks GP
+     execution. A `planning` plan awaits approval; a `done` plan is closed.
+     Do not run the companion during a read-only audit. For a complete
+     Godplans 1.1 contract, do the Godpowers artifacts and code satisfy the
+     plan's R-<DOM>-n requirements
      and GP acceptance criteria? Cite plan facts as [DECISION]-grade authored
      intent by GP/R id; inferences beyond the plan stay [HYPOTHESIS].
    Both files are read-only for this agent: never edit them; any write-back
@@ -236,9 +242,10 @@ Preflight rules:
 - Inspect package manifests, lockfiles, build files, test config, CI config,
   source layout, entry points, docs, ADRs, env examples, AGENTS.md, deploy
   signals, observability signals, and ownership signals.
-- Mandatory: inspect `.godplans/PLAN.mdx` and `.godaudits/AUDIT.json` when
-  present. A master plan is direct arc-readiness evidence; validated audit
-  state provides direct scoring and coverage evidence. Recommend `/god-migrate` import before
+- Mandatory: inspect `.godplans/PLAN.mdx`, `.godplans/validate-plan.sh`, and
+  `.godaudits/AUDIT.json` when present. A complete Godplans 1.1 two-artifact
+  contract is direct arc-readiness evidence; validated audit state provides
+  direct scoring and coverage evidence. Recommend `/god-migrate` import before
   reconstruction when either exists.
 - Brownfield mode inspects existing codebase shape and refactor risk.
 - Bluefield mode inspects org context, sibling conventions, shared packages,

diff --git a/agents/god-reconciler.md b/agents/god-reconciler.md
@@ -175,10 +175,14 @@ Source: `.godpowers/state.json` `tier-3.launch`.
 - If conflicts exist: recommend greenfieldifier review before writes.
 
 #### SIBLING PLAN (`.godplans/PLAN.mdx`)
-- Does the intent match an existing GP task in the plan? (read-only; parse
-  via `lib/sibling-artifacts.js`)
-- Verdict: not-applicable / planned-in-godplans (with GP id) / not-in-plan /
-  plan-conflict
+- Does `.godplans/validate-plan.sh` complete the pinned Godplans 1.1 contract,
+  and is lifecycle status eligible for execution? Inspect read-only through
+  `lib/sibling-artifacts.loadPlan`.
+- Does the intent match an existing GP task in the plan?
+- Verdict: not-applicable / contract-incomplete / awaiting-approval / closed /
+  planned-in-godplans (with GP id) / not-in-plan / plan-conflict
+- Only `ready-for-validator` may recommend execution, and its action must run
+  `bash .godplans/validate-plan.sh .godplans/PLAN.mdx` before the GP task.
 - If plan-conflict: the plan is authored intent; surface the GP/R id and ask
   the user before proceeding.
 
@@ -242,7 +246,7 @@ Return structured JSON to the orchestrating skill:
   "repo_surface": { "status": "needs-surface-sync", "action": "run repo-surface-sync" },
   "feature_awareness": { "status": "needs-awareness-refresh", "action": "run feature-awareness" },
   "source_sync_back": { "status": "not-applicable" },
-  "sibling_plan": { "status": "planned-in-godplans", "match": "GP-204", "action": "execute under the plan's embedded executor rules" },
+  "sibling_plan": { "status": "planned-in-godplans", "match": "GP-204", "action": "run the pinned validator, then execute under the plan's lifecycle rules" },
   "sibling_audit": { "status": "addresses-ga-task", "match": "GA-102", "action": "route via /god-fix GA-102 with the finding's Verify command as done-check" },
   "host_capability": { "status": "degraded", "gap": "fresh-context agent spawn not detected" },
   "safe_sync": { "status": "clear" },

diff --git a/agents/god-reconstructor.md b/agents/god-reconstructor.md
@@ -45,9 +45,10 @@ intent is lost) but it gives Godpowers something to work with.
 - Project root
 - Optional: archaeology report from god-archaeologist
 - Optional: any existing partial artifacts (README, ADRs, comments)
-- Optional: `.godplans/PLAN.mdx` (authored godplans master plan; treat as
-  HIGH-confidence intent, cite by GP/R id, never edit it; parse via
-  `lib/sibling-artifacts.js`)
+- Optional: `.godplans/PLAN.mdx` plus `.godplans/validate-plan.sh`. Treat GP/R
+  facts as HIGH-confidence intent only when `loadPlan` reports a complete
+  Godplans 1.1 contract. Otherwise use them as hypothesis-grade migration
+  context. Never edit either file during reconstruction.
 
 ## Process
 
@@ -63,9 +64,10 @@ From the code, derive:
     within its priority (P-MUST-01, P-MUST-02, P-SHOULD-01, P-COULD-01), placed
     at the start of the bullet. These ids are load-bearing for the deliverable
     ledger and the linkage map.
-- When `.godplans/PLAN.mdx` is present, derive the problem statement, users,
-  and requirements from the plan FIRST (confidence HIGH; these are
-  [DECISION]-grade citations of authored intent), and code evidence second.
+- When a complete Godplans 1.1 contract is present, derive the problem
+  statement, users, and requirements from the plan FIRST (confidence HIGH;
+  these are [DECISION]-grade citations of authored intent), and code evidence
+  second. An incomplete or legacy plan stays [HYPOTHESIS]-grade.
   Preserve the source R-<DOM>-n id alongside the minted P-* id, e.g.
   `P-MUST-01 (plan: R-AUTH-2)`, so linkage back to the plan survives.
 - **Non-functional requirements**: what NFRs are enforced? (from rate limits, caching, indexes)
@@ -96,9 +98,10 @@ From git history + current state:
 - **Next**: TODOs at module level, unimplemented endpoints, stubs
 - **Later**: high-level themes from issue tracker if accessible
 
-When `.godplans/PLAN.mdx` is present, map its GP task checkbox state to the
-roadmap instead of inferring solely from git history: `- [x] GP-` tasks feed
-Done, `- [ ] GP-` tasks feed Next, in the plan's phase and wave order.
+When a complete Godplans 1.1 contract is present, map its GP task checkbox
+state to the roadmap instead of inferring solely from git history: `- [x] GP-`
+tasks feed Done, `- [ ] GP-` tasks feed Next, in phase and wave order. For an
+incomplete contract, record those states as hypotheses pending repair.
 
 Give each delivery increment a stable `M-<slug>` id, a `**Status**:` field
 (pending/building/done), and a `**Features (from PRD)**:` list of the

diff --git a/agents/quality.md b/agents/quality.md
@@ -22,6 +22,7 @@ see_also: [security, deploy]
 - [DECISION] `npm run test:self-truth` blocks stale version, public surface, lifecycle, artifact, requirement, generated progress, and roadmap provenance claims.
 - [DECISION] The full test suite includes quick proof docs, repo-doc sync, repo-surface sync, automation surface sync, host capabilities, extension authoring, dogfood, Mode D, installer smoke, workflow runner, OTel, and extension publish-readiness checks.
 - [DECISION] Sibling-artifact tests cover godaudits 2.x JSON authority, large canonical files, non-regular source rejection, legacy and generated MDX fallback, check and evidence ledgers, compliance, accepted risks, score caps, compiled coverage, typed GA dispatch, managed todo synchronization, MDX safety, canonical staleness, migration seeds, and remediation impact detection.
+- [DECISION] Sibling-artifact tests cover the Godplans 1.1 validator identity, two-artifact completeness, static structural preflight, lifecycle dispatch gates, full GP/R seed traceability, large-plan reads, and legacy hypothesis-grade fallback.
 - [DECISION] Build and review agents enforce request-trace discipline: assumptions, public behavior, expected files, and verification command must be explicit before implementation.
 - [DECISION] Reviewers block speculative flexibility, unrelated cleanup, and diff churn that cannot be traced to the user request, slice plan, failing test, or implementation-caused cleanup.
 

diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -2,7 +2,7 @@
 
 > Status: ACTIVE
 > Model: Pure-skill for durable work. CLI provides install plus read-only status helpers.
-> Last updated: 2026-07-03
+> Last updated: 2026-07-13
 > Current source: v5.3.1. Latest published: v5.3.1.
 
 This roadmap tracks releases, what's shipped, and what is frozen during the
@@ -45,6 +45,10 @@ quarterback, work report, reflections, memory, lessons, outcome loops, MCP read
 tools, and ledger importer) shipped across 3.1.0-3.11.0.
 
 What works today:
+- **Godplans 1.1 interoperability**: PLAN plus pinned executable validator
+  contract detection, non-executing structural preflight, lifecycle-safe GP
+  routing, exact pre-execution validator gate, complete GP/R seed traceability,
+  large-plan reads, two-file staleness, and legacy hypothesis-grade fallback.
 - **Godaudits 2.x interoperability**: canonical `.godaudits/AUDIT.json`
   detection and import, generated and legacy MDX fallback, compiled score and
   coverage signals, typed GA remediation dispatch, managed todo synchronization,

diff --git a/docs/phase-4-state-read-inventory.md b/docs/phase-4-state-read-inventory.md
@@ -29,7 +29,7 @@
 | Workflow greenfieldification artifact lists | [DECISION] decision-read | `workflows/brownfield-arc.yaml:75`, `workflows/brownfield-arc.yaml:76`, `workflows/brownfield-arc.yaml:77`, `workflows/brownfield-arc.yaml:78`, `workflows/bluefield-arc.yaml:59`, `workflows/bluefield-arc.yaml:60`, `workflows/bluefield-arc.yaml:61`, `workflows/bluefield-arc.yaml:62`, `lib/workflow-runner.js:140` | [DECISION] Completed: brownfield and bluefield greenfieldifier workflow inputs now pass `.godpowers/state.json` plus canonical artifacts instead of generated per-tier state views. |
 | Pillars artifact sync | [DECISION] migration-read | `lib/pillars.js:99`, `lib/pillars.js:100`, `lib/pillars.js:112`, `lib/pillars.js:113`, `lib/pillars.js:451`, `lib/pillars.js:457`, `lib/pillars.js:594`, `lib/pillars.js:628` | [DECISION] Completed: Pillars artifact discovery now maps `.godpowers/state.json` to durable context, deploy, and observe concerns instead of reading generated deploy or observe state views. |
 | Source-system sync-back summary | [DECISION] display-read | `lib/source-sync.js:88`, `lib/source-sync.js:99`, `lib/source-sync.js:134` | [DECISION] Completed: source-system sync-back now summarizes `.godpowers/state.json` instead of `.godpowers/build/STATE.mdx`. |
-| Planning-system import seed for build state | [DECISION] migration-read | `lib/planning-systems.js:67`, `skills/god-migrate.md:101`, `docs/planning-system-migration.md:10` | [DECISION] Keep imported source-system `STATE.md` reads as migration inputs, but write imported build-state seed data through `state.json` and regenerated views. |
+| Planning-system import seed for build state | [DECISION] migration-read | `lib/planning-systems.js`, `skills/god-migrate.md`, `docs/planning-system-migration.md` | [DECISION] Keep imported source-system state as migration input, write its full ledger to `.godpowers/prep/IMPORTED-BUILD-STATE.mdx`, reference that artifact from `state.json`, and keep `.godpowers/build/STATE.mdx` as a regenerated managed view. |
 | Context writer human prompt section | [DECISION] display-read | `lib/context-writer.js:86`, `lib/context-writer.js:92`, `lib/context-writer.js:151`, `scripts/test-context-writer.js:176` | [DECISION] Completed: generated AI-tool context now names `state.json` as authority and `PROGRESS.mdx` as a generated human view. |
 | Route and gate tests | [DECISION] decision-read | `scripts/test-router.js:96`, `scripts/test-router.js:195`, `scripts/test-router.js:332`, `scripts/test-gate.js:52`, `scripts/test-gate.js:125`, `scripts/test-gate.js:138`, `scripts/test-gate.js:195` | [DECISION] Completed: generated `STATE.md` hand-edits are overwritten by the next state mutation, and router plus static checks now reject generated per-tier state views as route or workflow handoff authority. |
 | Quick-proof and doc drift tests | [DECISION] display-read | `scripts/test-quick-proof.js:256`, `docs/quick-proof.md:112`, `README.md:214`, `README.md:481`, `docs/concepts.md:66`, `docs/command-flows.md:64`, `docs/command-flows.md:298`, `docs/command-flows.md:491` | [DECISION] Completed: proof, concept, reference, command-flow, and README examples now show `state.json` as authority and `PROGRESS.mdx` as a generated view. |