openplanr 2.4.0 → 2.5.0

package/lib/host-packages/openai/openplanr/skills/design/scripts/runtime/packages/protocol/schemas/v1.11.0/design-implementation-handoff.schema.json

@@ -0,0 +1,518 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.11.0/design-implementation-handoff.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-implementation-handoff",
+    "version": "1.11.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "const": "openplanr-design-implementation-handoff"
+    },
+    "schemaVersion": {
+      "const": "1.0.0"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "approved",
+        "superseded",
+        "revoked"
+      ]
+    },
+    "authority": {
+      "const": "prepare-plan"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "basis": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "designId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "sourceRevision": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "selectedVariant": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "readiness": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "status": {
+              "enum": [
+                "ready",
+                "attention",
+                "blocked",
+                "stale"
+              ]
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            }
+          },
+          "required": [
+            "status",
+            "digest"
+          ]
+        },
+        "reviewHandoff": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "version": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "contentDigest": {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            }
+          },
+          "required": [
+            "version",
+            "contentDigest"
+          ]
+        }
+      },
+      "required": [
+        "designId",
+        "sourceRevision",
+        "selectedVariant",
+        "readiness",
+        "reviewHandoff"
+      ]
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 160,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+          },
+          "kind": {
+            "enum": [
+              "design-revision",
+              "selected-direction",
+              "design-specification",
+              "rendered-verification",
+              "review-context",
+              "review-feedback",
+              "review-metadata",
+              "review-handoff",
+              "screen",
+              "frame",
+              "component",
+              "state",
+              "flow",
+              "token",
+              "review-decision",
+              "element-anchor"
+            ]
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096
+          },
+          "revision": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          },
+          "anchor": {
+            "oneOf": [
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "section": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+                  }
+                },
+                "required": [
+                  "section"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "screenId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+                  }
+                },
+                "required": [
+                  "screenId"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "screenId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+                  },
+                  "elementId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+                  }
+                },
+                "required": [
+                  "screenId",
+                  "elementId"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "reviewId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+                  },
+                  "pinId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+                  }
+                },
+                "required": [
+                  "reviewId",
+                  "pinId"
+                ]
+              }
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "kind",
+          "path"
+        ]
+      },
+      "maxItems": 10000
+    },
+    "requirements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^REQ-[0-9]{3,}$"
+          },
+          "kind": {
+            "enum": [
+              "behavior",
+              "visual-state",
+              "responsive",
+              "accessibility",
+              "content-data-assumption",
+              "constraint",
+              "verification-intent"
+            ]
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 16384
+          },
+          "sourceRefs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160,
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+            },
+            "maxItems": 256,
+            "minItems": 1
+          },
+          "verification": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 16384
+            },
+            "maxItems": 256,
+            "minItems": 1
+          }
+        },
+        "required": [
+          "id",
+          "kind",
+          "statement",
+          "sourceRefs",
+          "verification"
+        ]
+      },
+      "maxItems": 10000,
+      "minItems": 1
+    },
+    "contentDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "markdown": {
+      "type": "string",
+      "maxLength": 2097152
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "actorId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "approvedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "contentDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "authority": {
+          "const": "prepare-plan"
+        }
+      },
+      "required": [
+        "actorId",
+        "approvedAt",
+        "contentDigest",
+        "authority"
+      ]
+    },
+    "supersededBy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "contentDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        }
+      },
+      "required": [
+        "id",
+        "version",
+        "contentDigest"
+      ]
+    },
+    "revocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "actorId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "revokedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 16384
+        }
+      },
+      "required": [
+        "actorId",
+        "revokedAt",
+        "reason"
+      ]
+    }
+  },
+  "required": [
+    "kind",
+    "schemaVersion",
+    "id",
+    "version",
+    "status",
+    "authority",
+    "title",
+    "basis",
+    "sources",
+    "requirements",
+    "contentDigest",
+    "markdown"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "approved"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "approval"
+        ],
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "supersededBy"
+              ]
+            },
+            {
+              "required": [
+                "revocation"
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "superseded"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "approval",
+          "supersededBy"
+        ],
+        "not": {
+          "required": [
+            "revocation"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "revoked"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "approval",
+          "revocation"
+        ],
+        "not": {
+          "required": [
+            "supersededBy"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "draft"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "approval"
+              ]
+            },
+            {
+              "required": [
+                "supersededBy"
+              ]
+            },
+            {
+              "required": [
+                "revocation"
+              ]
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/design/scripts/runtime/packages/protocol/schemas/v1.11.0/design-planning-lineage.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.11.0/design-planning-lineage.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-planning-lineage",
+    "version": "1.11.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "const": "openplanr-design-planning-lineage"
+    },
+    "schemaVersion": {
+      "const": "1.0.0"
+    },
+    "handoff": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "contentDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        }
+      },
+      "required": [
+        "id",
+        "version",
+        "contentDigest"
+      ]
+    },
+    "specId": {
+      "type": "string",
+      "pattern": "^SPEC-[0-9]{3,}$"
+    },
+    "mappings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "requirementId": {
+            "type": "string",
+            "pattern": "^REQ-[0-9]{3,}$"
+          },
+          "acceptanceRefs": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "storyId": {
+                  "type": "string",
+                  "pattern": "^US-[0-9]{3,}$"
+                },
+                "acceptanceId": {
+                  "type": "string",
+                  "pattern": "^AC-[0-9]{3,}$"
+                }
+              },
+              "required": [
+                "storyId",
+                "acceptanceId"
+              ]
+            },
+            "maxItems": 256,
+            "minItems": 1
+          },
+          "taskIds": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^T-[0-9]{3,}$"
+            },
+            "maxItems": 256,
+            "minItems": 1
+          }
+        },
+        "required": [
+          "requirementId",
+          "acceptanceRefs",
+          "taskIds"
+        ]
+      },
+      "maxItems": 10000,
+      "minItems": 1
+    }
+  },
+  "required": [
+    "kind",
+    "schemaVersion",
+    "handoff",
+    "specId",
+    "mappings"
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/design-loop/openplanr.skill.json

@@ -363,6 +363,39 @@
         "cursor"
       ]
     },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.11.0/design-handoff-readiness.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.11.0/design-implementation-handoff.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.11.0/design-planning-lineage.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
     {
       "path": "scripts/runtime/packages/protocol/schemas/v1.11.0/design-review-metadata-payload.schema.json",
       "kind": "schema",

package/lib/host-packages/openai/openplanr/skills/design-loop/references/handoff.md

@@ -40,6 +40,41 @@ Generated previews and copied runtimes are separate from authored source. Follow
 the project's tracking conventions; never discard editable source or the prior
 working revision merely to clean generated output.
 
+## Implementation package custody
+
+After review feedback has explicit owner decisions and the current review handoff
+is approved, the owner may prepare an implementation package. The package is a
+compact navigation and acceptance aid; it never replaces the design document,
+screen sources, `design-spec.md`, verification record, review ledger or approved
+review handoff.
+
+- Keep source references repository-relative and bind them to their exact revision
+  and integrity value. A screen, component, state, flow, token, review decision or
+  element anchor must resolve exactly once inside the repository.
+- Keep canonical bodies in their owning files. Do not embed whole HTML documents,
+  screenshots, design documents, review ledgers or source code in the package.
+- Give every implementation requirement observable verification and one or more
+  stable source references. Requirement IDs derive from canonical requirement
+  content and ordered references; do not renumber them for presentation.
+- Treat `implementation-handoff/draft.json` as the machine record and
+  `implementation-handoff/draft.md` as its generated human projection. Never edit
+  the Markdown independently. Portable import validates JSON first and then exact
+  Markdown parity; optional source verification can run fully offline.
+- Drafting, regeneration, export and import grant no Plan, Ship, Git, release,
+  publication or deployment authority. Package approval and immutable history are
+  separate owner actions.
+- Approval binds the exact draft version and internal content identity loaded by
+  the owner. The confirmation describes the title, revision, requirement count,
+  unresolved nonblocking items and `Prepare Plan` effect; integrity values stay
+  out of the decision copy.
+- Approved packages live below `implementation-handoff/versions/` and never
+  change. `implementation-handoff/current.json` is a small lifecycle pointer;
+  supersession and revocation append auditable events without rewriting history.
+  Regeneration always creates a newer draft version. Exact request retries reuse
+  their completed result, while reused request IDs with different input conflict.
+- Approval authorizes only preparation for a later Plan invocation. It never
+  starts Plan, Ship, an agent, a Git write, publication, release or deployment.
+
 Return concise links to the studio, document/source, specification and quality
 result. State the selected direction and any decisions still open. Plan can read
 the specification and selected sources to create UI tasks; it must not re-extract