openplanr 3.0.1 → 3.1.0

package/lib/schemas/v1.0.0/spec.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.0.0/spec.schema.json",
+  "title": "OpenPlanr SPEC frontmatter (v1.0.0)",
+  "description": "JSON Schema for the YAML frontmatter of a SPEC-NNN-{slug}.md artifact in spec-driven mode. Validates the canonical shape produced by `planr spec shape` / `planr spec decompose` and the planr-pipeline specification-agent.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "title",
+    "slug",
+    "schemaVersion",
+    "status",
+    "priority",
+    "created",
+    "updated",
+    "ui_files",
+    "tech_dependencies"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^(SPEC|FEAT)-\\d{3}$",
+      "description": "Feature/Spec identifier. SPEC-NNN in spec-driven mode (e.g. SPEC-001), FEAT-NNN in default mode (e.g. FEAT-001). Scoped to the parent project."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable spec title."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "description": "URL-safe lowercase slug used in the spec directory path."
+    },
+    "schemaVersion": {
+      "const": "1.0.0",
+      "description": "Pinned to the OpenPlanr Protocol reader version."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "shaping",
+        "shaped",
+        "decomposing",
+        "decomposed",
+        "ready-for-pipeline",
+        "in-pipeline",
+        "done"
+      ],
+      "description": "Current lifecycle state of the spec."
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["P0", "P1", "P2", "P3"],
+      "description": "Priority tier."
+    },
+    "milestone": {
+      "type": "string",
+      "description": "Optional milestone label (e.g. v1.0)."
+    },
+    "po": {
+      "type": "string",
+      "description": "Optional spec owner identifier (typically an email)."
+    },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) of spec creation."
+    },
+    "updated": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) bumped on every edit."
+    },
+    "ui_files": {
+      "type": "array",
+      "description": "Array of PNG paths under design/ for UI-bearing specs. Empty array when the spec has no UI surface.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "tech_dependencies": {
+      "type": "array",
+      "description": "Informational list of upstream technical dependencies. Empty array when none.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "specificationContract": {
+      "const": "professional-specification@1.0.0",
+      "description": "Optional marker for a decision-complete professional specification. Legacy specifications omit it and remain readable."
+    },
+    "review_specialists": {
+      "type": "array",
+      "maxItems": 5,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["security-reviewer", "performance-reviewer", "migration-reviewer", "api-contract-reviewer", "data-integrity-reviewer"]
+      },
+      "description": "Optional explicitly declared planning-review specialists in canonical registry order."
+    },
+    "kanbanosId": {
+      "type": "string",
+      "minLength": 8,
+      "pattern": "^[A-Za-z0-9_-]{8,128}$",
+      "description": "Optional opaque entity id on the kanbanos hosted board, written back by the sync tool after a successful push (the linearId precedent from the OpenPlanr CLI Linear integration). Sync-tool-owned: humans and planning agents never author or edit it by hand. Absent until the artifact is first pushed. See ADR-012."
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Optional digest of the artifact content at the last successful board sync, written back by the sync tool alongside kanbanosId so drift between file and board is detectable. Same sha256:<hex> shape as operating-evidence-index-item@1.3.0. Sync-tool-owned: humans and planning agents never author or edit it by hand. See ADR-012."
+    }
+  }
+}

package/lib/schemas/v1.0.0/story.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.0.0/story.schema.json",
+  "title": "OpenPlanr User Story frontmatter (v1.0.0)",
+  "description": "JSON Schema for the YAML frontmatter of a user story artifact. Accepts both planr-pipeline modes via a top-level `oneOf` over the parent reference: spec-driven user stories (US-NNN-{slug}.md under <SPEC_DIR>/stories/) carry `specId: \"SPEC-NNN\"` and live scoped to a parent SPEC; default-mode user stories (output/feats/feat-{slug}/us-N/us-N.md) carry `featureSlug: \"<slug>\"` and live scoped to a parent feature folder. Exactly one of the two parent-reference fields must be present per story; the other must be absent.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "title",
+    "slug",
+    "schemaVersion",
+    "status",
+    "created",
+    "updated"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^US-\\d{3}$",
+      "description": "User Story identifier (e.g. US-001). Scoped to the parent SPEC (spec-driven) or parent feature (default mode)."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable story title."
+    },
+    "specId": {
+      "type": "string",
+      "pattern": "^SPEC-\\d{3}$",
+      "description": "ID of the parent spec this story belongs to. Spec-driven mode only — must be absent in default mode."
+    },
+    "featureSlug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "description": "Slug of the parent feature folder this story belongs to. Default mode only — must be absent in spec-driven mode."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "description": "URL-safe lowercase slug used in the story file name."
+    },
+    "schemaVersion": {
+      "const": "1.0.0",
+      "description": "Pinned to the OpenPlanr Protocol reader version."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "implementing", "done", "blocked"],
+      "description": "Current lifecycle state of the story."
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["P0", "P1", "P2", "P3"],
+      "description": "Optional priority tier (inherits from parent spec when absent)."
+    },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) of story creation."
+    },
+    "updated": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) bumped on every edit."
+    },
+    "kanbanosId": {
+      "type": "string",
+      "minLength": 8,
+      "pattern": "^[A-Za-z0-9_-]{8,128}$",
+      "description": "Optional opaque entity id on the kanbanos hosted board, written back by the sync tool after a successful push (the linearId precedent from the OpenPlanr CLI Linear integration). Sync-tool-owned: humans and planning agents never author or edit it by hand. Absent until the artifact is first pushed. See ADR-012."
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Optional digest of the artifact content at the last successful board sync, written back by the sync tool alongside kanbanosId so drift between file and board is detectable. Same sha256:<hex> shape as operating-evidence-index-item@1.3.0. Sync-tool-owned: humans and planning agents never author or edit it by hand. See ADR-012."
+    }
+  },
+  "oneOf": [
+    {
+      "title": "spec-driven story → requires specId, forbids featureSlug",
+      "required": ["specId"],
+      "not": { "required": ["featureSlug"] }
+    },
+    {
+      "title": "default-mode story → requires featureSlug, forbids specId",
+      "required": ["featureSlug"],
+      "not": { "required": ["specId"] }
+    }
+  ]
+}

package/lib/schemas/v1.0.0/task.schema.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.0.0/task.schema.json",
+  "title": "OpenPlanr Task frontmatter (v1.0.0)",
+  "description": "JSON Schema for the YAML frontmatter of a task artifact. Encodes two orthogonal correlations via `allOf`: (1) type-to-agent — UI tasks use frontend-agent, Tech tasks use backend-agent or db-agent; (2) parent reference — spec-driven tasks (T-NNN-{slug}.md under <SPEC_DIR>/tasks/) carry `specId: \"SPEC-NNN\"` (with a `storyId` pointing at a US-NNN within that SPEC), default-mode tasks (output/feats/feat-{slug}/us-N/tasks/task-N.md) carry `featureSlug: \"<slug>\"` instead of specId. Exactly one of the two parent-reference fields must be present per task; the other must be absent.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "title",
+    "storyId",
+    "slug",
+    "schemaVersion",
+    "type",
+    "agent",
+    "status",
+    "created",
+    "updated"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^T-\\d{3}$",
+      "description": "Task identifier (e.g. T-001). Scoped to the parent SPEC (spec-driven) or parent User Story (default mode)."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable task title."
+    },
+    "storyId": {
+      "type": "string",
+      "pattern": "^US-\\d{3}$",
+      "description": "ID of the parent User Story this task belongs to."
+    },
+    "specId": {
+      "type": "string",
+      "pattern": "^SPEC-\\d{3}$",
+      "description": "ID of the grandparent spec this task ultimately belongs to. Spec-driven mode only — must be absent in default mode."
+    },
+    "featureSlug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "description": "Slug of the parent feature folder this task ultimately belongs to. Default mode only — must be absent in spec-driven mode."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "description": "URL-safe lowercase slug used in the task file name."
+    },
+    "schemaVersion": {
+      "const": "1.0.0",
+      "description": "Pinned to the OpenPlanr Protocol reader version."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["UI", "Tech"],
+      "description": "UI = frontend-bearing task; Tech = backend / data / infra task."
+    },
+    "agent": {
+      "type": "string",
+      "enum": ["frontend-agent", "backend-agent", "db-agent"],
+      "description": "DEV agent responsible for executing this task. Must correlate with `type` (see allOf type/agent branch)."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "in-progress", "done", "blocked"],
+      "description": "Current lifecycle state of the task."
+    },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) of task creation."
+    },
+    "updated": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date (YYYY-MM-DD) bumped on every edit."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "1-3 sentence explanation of why this task exists and why these specific files were chosen. Populated by the specification-agent during decomposition. Read by qa-agent to check implementation drift."
+    },
+    "dependsOn": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^T-\\d{3}$" },
+      "uniqueItems": true,
+      "default": [],
+      "description": "Task IDs (within the same parent) that must reach status done before this task is dispatched. Optional; absent/empty means no declared dependency."
+    },
+    "preserve": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["repositoryKey", "path"],
+        "properties": {
+          "repositoryKey": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "path": { "type": "string", "minLength": 1 }
+        }
+      },
+      "uniqueItems": true,
+      "description": "Optional machine-enforceable repository-relative Preserve boundaries. New SHIP closure runs require this property to be explicitly present (an empty array is valid); legacy body prose remains human guidance only."
+    },
+    "review_risks": {
+      "type": "array",
+      "items": { "type": "string", "enum": ["security", "performance", "migration", "api-contract", "data-integrity"] },
+      "uniqueItems": true,
+      "description": "Optional reviewed specialist risk declarations. The deterministic SHIP classifier, not the caller, maps these IDs into the frozen consolidated roster."
+    },
+    "browser_surfaces": {
+      "type": "array",
+      "items": { "type": "string", "enum": ["ui", "authentication", "session", "navigation", "network"] },
+      "uniqueItems": true,
+      "description": "Optional reviewed browser-sensitive surfaces. Any declared entry makes browser QA mandatory for the SHIP candidate."
+    },
+    "kanbanosId": {
+      "type": "string",
+      "minLength": 8,
+      "pattern": "^[A-Za-z0-9_-]{8,128}$",
+      "description": "Optional opaque entity id on the kanbanos hosted board, written back by the sync tool after a successful push (the linearId precedent from the OpenPlanr CLI Linear integration). Sync-tool-owned: humans and planning agents never author or edit it by hand. Absent until the artifact is first pushed. See ADR-012."
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Optional digest of the artifact content at the last successful board sync, written back by the sync tool alongside kanbanosId so drift between file and board is detectable. Same sha256:<hex> shape as operating-evidence-index-item@1.3.0. Sync-tool-owned: humans and planning agents never author or edit it by hand. See ADR-012."
+    }
+  },
+  "allOf": [
+    {
+      "title": "type-to-agent correlation",
+      "oneOf": [
+        {
+          "title": "UI task → frontend-agent",
+          "properties": {
+            "type": { "const": "UI" },
+            "agent": { "const": "frontend-agent" }
+          },
+          "required": ["type", "agent"]
+        },
+        {
+          "title": "Tech task → backend-agent or db-agent",
+          "properties": {
+            "type": { "const": "Tech" },
+            "agent": { "enum": ["backend-agent", "db-agent"] }
+          },
+          "required": ["type", "agent"]
+        }
+      ]
+    },
+    {
+      "title": "parent-reference correlation (mode-dependent)",
+      "oneOf": [
+        {
+          "title": "spec-driven task → requires specId, forbids featureSlug",
+          "required": ["specId"],
+          "not": { "required": ["featureSlug"] }
+        },
+        {
+          "title": "default-mode task → requires featureSlug, forbids specId",
+          "required": ["featureSlug"],
+          "not": { "required": ["specId"] }
+        }
+      ]
+    }
+  ]
+}

package/lib/schemas/v1.7.0/spec.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.7.0/spec.schema.json",
+  "x-openplanr-contract": {
+    "id": "spec",
+    "version": "1.7.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "title",
+    "slug",
+    "schemaVersion",
+    "status",
+    "priority",
+    "created",
+    "updated",
+    "ui_files",
+    "tech_dependencies"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^(?:SPEC|FEAT)-\\d{3,}$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "schemaVersion": {
+      "const": "1.7.0"
+    },
+    "status": {
+      "enum": [
+        "pending",
+        "shaping",
+        "shaped",
+        "decomposing",
+        "decomposed",
+        "ready-for-pipeline",
+        "in-pipeline",
+        "done"
+      ]
+    },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "priority": {
+      "enum": [
+        "P0",
+        "P1",
+        "P2",
+        "P3"
+      ]
+    },
+    "milestone": {
+      "type": "string"
+    },
+    "po": {
+      "type": "string"
+    },
+    "ui_files": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "tech_dependencies": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "specificationContract": {
+      "const": "professional-specification@1.0.0"
+    },
+    "review_specialists": {
+      "type": "array",
+      "maxItems": 5,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "security-reviewer",
+          "performance-reviewer",
+          "migration-reviewer",
+          "api-contract-reviewer",
+          "data-integrity-reviewer"
+        ]
+      }
+    },
+    "kanbanosId": {
+      "type": "string",
+      "minLength": 8,
+      "pattern": "^[A-Za-z0-9_-]{8,128}$"
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    }
+  }
+}

package/lib/schemas/v1.7.0/story.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.7.0/story.schema.json",
+  "x-openplanr-contract": {
+    "id": "story",
+    "version": "1.7.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "title",
+    "slug",
+    "schemaVersion",
+    "status",
+    "created",
+    "updated",
+    "acceptanceCriteria"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^US-\\d{3,}$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "schemaVersion": {
+      "const": "1.7.0"
+    },
+    "status": {
+      "enum": [
+        "pending",
+        "implementing",
+        "in-progress",
+        "done",
+        "blocked"
+      ]
+    },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "specId": {
+      "type": "string",
+      "pattern": "^SPEC-\\d{3,}$"
+    },
+    "featureSlug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "statement"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^AC-\\d{3,}$"
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "required": [
+        "specId"
+      ],
+      "not": {
+        "required": [
+          "featureSlug"
+        ]
+      }
+    },
+    {
+      "required": [
+        "featureSlug"
+      ],
+      "not": {
+        "required": [
+          "specId"
+        ]
+      }
+    }
+  ]
+}