openplanr 2.3.0 → 2.5.0

package/lib/host-packages/cursor/openplanr/rules/planr-plan/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/cursor/openplanr/rules/planr-plan/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/cursor/openplanr/rules/planr-plan.mdc

@@ -49,6 +49,11 @@ report the changed inputs and obtain the missing decision only when it affects t
 requested plan. Never silently substitute a newer draft for an approved snapshot.
 A missing review handoff does not block ordinary planning from a clear specification.
 
+When the request carries an approved implementation package, read
+[the design handoff contract](references/design-handoff.md). Validate that the
+package is still the current approved version before treating its numbered
+requirements as scope. A missing package leaves ordinary Plan unchanged.
+
 For a consequential unresolved choice, use the host's structured question
 interface. Ask at most three short, mutually exclusive questions at once. If the
 host has no structured question interface, ask one concise chat question.
@@ -88,6 +93,13 @@ Validate all frontmatter and acceptance coverage before finishing. If a helper
 is unavailable, inspect existing IDs and validate the same invariants directly;
 do not route semantic work to a CLI fallback.
 
+For approved design input, author the complete story and task bytes before
+touching target paths, then commit those bytes and the sibling
+`design-lineage.json` through the public atomic planning-lineage helper described
+in the reference. A failed requirement-to-acceptance-to-task mapping writes
+nothing. This deterministic commit validates content; it does not generate the
+plan or invoke another phase.
+
 ## Return
 
 - **Outcome:** what is implementation-ready.

package/lib/host-packages/cursor/openplanr/rules/planr-ship/references/design-lineage.md

@@ -0,0 +1,26 @@
+# Use design lineage during Ship
+
+`design-lineage.json` is optional. Its absence is normal and must not change an
+ordinary Ship run.
+
+When present, validate the sidecar and compare its package identity with the exact
+approved implementation handoff. Load only mappings whose `taskIds` include the
+selected task. From that subset, load only the referenced `REQ-NNN` requirements
+and their source records. Do not ingest unrelated screens, requirements, package
+versions, or complete design documents.
+
+Treat the context as **current** when lineage, immutable package history, and the
+current approved pointer identify the same package; **stale** when the exact
+package is missing, changed, superseded, revoked, or disagrees with the sidecar;
+and **absent** when there is no sidecar.
+
+Carry current requirement statements, verification intents, accessibility and
+responsive expectations into the implementation and checks. For stale context,
+name the mismatch and use the evidence only as historical context; never silently
+upgrade it to approved scope. The selected task, parents, and repository rules
+remain authoritative.
+
+Ship is a later, separate user invocation. Reading lineage never starts Plan,
+another task, release, publication, deployment, or a Git operation. Delivery
+status is a read-only projection of the approved package, lineage, task state, and
+Ship closure. Never write delivery state back into an approved package.

package/lib/host-packages/cursor/openplanr/rules/planr-ship.mdc

@@ -18,6 +18,11 @@ when present, and specification. Also read repository instructions, ADRs,
 planning rules, applicable stack guidance, relevant design/database context,
 implementation code, tests, and interfaces produced by declared dependencies.
 
+Read [the design lineage contract](references/design-lineage.md). If the selected
+planning root contains `design-lineage.json`, load only the selected task's mapped
+requirements and source references, and report whether the exact approved package
+is current or stale. Its absence leaves the ordinary task context unchanged.
+
 Only `dependsOn` defines semantic ordering. When a dependency has not produced
 the interface this task consumes, report that concrete gap. Never infer a
 dependency from order or overlapping paths. Isolate independent executions when
@@ -62,6 +67,10 @@ Run the strongest applicable focused checks while working, then the relevant
 regression checks. Fix failures caused by the change and rerun affected checks.
 Read [the result contract](references/result-contract.md) before reporting.
 
+Do not write progress into an approved design package. The studio derives
+approved, planned, implementing, and verified state from canonical planning and
+Ship artifacts after this separate invocation.
+
 ## Return
 
 Return the existing five fields: