openplanr 2.3.0 → 2.5.0

package/lib/host-packages/claude/openplanr/skills/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/claude/openplanr/skills/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/claude/openplanr/skills/diagram/SKILL.md

@@ -29,6 +29,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
 ```
@@ -52,6 +58,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

package/lib/host-packages/claude/openplanr/skills/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/claude/openplanr/skills/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/claude/openplanr/skills/plan/SKILL.md

@@ -50,6 +50,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.
@@ -89,6 +94,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.