openplanr 2.3.0 → 2.5.0

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

@@ -51,3 +51,6 @@ the studio's encrypted Share flow. Preserve reviewer attribution.
 For company reviews and implementation handoff, follow
 [team-review.md](references/team-review.md). Keep review guidance outside product
 screens, preserve reviewer intent, and let the owner approve the refined handoff.
+Only an explicit **Continue to Plan** action may return the host-native Plan
+invocation for the current approved package. Preparing or approving a package
+does not write planning files, dispatch an agent, change Git, or start Ship.

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

@@ -70,3 +70,6 @@ Review for focused iteration on an existing direction.
 For company reviews and implementation handoff, follow
 [team-review.md](references/team-review.md). Keep review guidance outside product
 screens, preserve reviewer intent, and let the owner approve the refined handoff.
+After approval, **Continue to Plan** is one explicit owner action that returns a
+host-native `/planr:plan` or `$planr:plan` invocation bound to the exact package.
+It does not write planning files, dispatch an agent, change Git, or start Ship.

package/lib/host-packages/cursor/openplanr/rules/planr-diagram/references/diagram-document.md

@@ -76,6 +76,10 @@ messages, and events as named phases. After participant IDs, interleave phase
 event IDs and message relation IDs in `accessibility.readingOrder`. That order
 is the canonical timeline used by the renderer and editable projections.
 
+For a lane grammar, add a `lanes` collection of `{ "id", "label", "members" }`
+entries whose `members` list node IDs. Every member must exist, and the
+renderer draws each lane as a titled band holding those nodes.
+
 Write the draft to `<slug>.planr-diagram.json`, then run:
 
 ```sh

package/lib/host-packages/cursor/openplanr/rules/planr-diagram/references/diagram-intent-to-ir.md

@@ -37,6 +37,10 @@ reads at a glance.
   and `flowchart` a back edge pushes its target to the bottom of the canvas.
 - Use groups sparingly, at most one level, and never for the whole graph. Use
   at most one annotation; more than that draws connectors across the canvas.
+- Lanes are bands perpendicular to the flow: rows under `left-right`, columns
+  under `top-down`. Put every node in exactly one lane; a node outside all
+  lanes renders in an unbanded strip after the last lane. A step's position
+  along the flow is its relation rank, so a handoff lines up across lanes.
 
 Ask a question only if selecting a different answer would change the grammar,
 meaning, or audience. Infer presentation details from context and let the

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

@@ -28,6 +28,12 @@ question UI. Write one digestless Protocol 1.6 diagram draft from the bundled
 contract, then run the command below. The CLI validates it and adds the
 canonical digest; the skill must not calculate that digest itself.
 
+For "who does what, and when" between actors, use a lane grammar (`swimlane`
+or `process`): one lane per actor with its `members`, `left-right` so lanes
+read as rows, and relations for the handoffs. For a board (`kanban`,
+`story-map`), use `top-down` so lanes read as columns and leave `relations`
+empty; members stack in declared order.
+
 ```sh
 planr diagram render <file>.planr-diagram.json --json
 ```
@@ -51,6 +57,12 @@ a source branch of an existing generated set; rerender its manifest with
 
 ## Look before you hand over
 
+Every manifest result carries a `quality` object — `status`, `failedChecks`,
+`warningChecks`. Treat anything other than `pass` as unfinished work. An
+`invalid` set returns no `nextAction`: restructure and render again rather than
+opening the studio. A missing `quality` object means the report could not be
+read, which `warnings` explains; that set is unverified, not verified.
+
 A `pass` quality status is necessary, not sufficient. After every render, open
 the PNG or SVG the command lists and check four signatures: a label that reads as
 another node's caption, rectangles that overlap, a connector crossing the whole