@openplanr/protocol 0.2.0

package/registry/professional-skills.json

@@ -0,0 +1,115 @@
+{
+  "kind": "professional-skills",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.1.0",
+  "catalogVersion": "1.0.0",
+  "digestAlgorithm": "sha256",
+  "skills": [
+    {
+      "skillId": "planr-browser-qa",
+      "sourceOwner": "skills",
+      "sourceVersion": "1.0.0",
+      "sourceSnapshot": "---\nname: planr-browser-qa\ndescription: Run structured browser-backed QA for real routes, forms, viewports, accessibility, console, and network behavior. Use for UI, authentication, session, navigation, or browser-network changes, and whenever SHIP declares the browser gate mandatory.\n---\n\n# Planr Browser QA\n\n1. Use only an active SHIP run whose frozen gate set requires browser QA.\n2. Require a registered trusted browser runtime adapter before execution. The portable `prepare-browser-qa` and `record-browser-qa` CLI paths intentionally return `E_BROWSER_QA_TRUSTED_HOST_REQUIRED`; stop and hand off instead of fabricating a host, attestation, result, or digest.\n3. Through that adapter, establish the ephemeral session and engine-owned runtime capability before the result, then exercise only the declared routes, forms, viewports, accessibility, console, and network checks. Never persist credentials or session secrets.\n4. Let the same adapter verify raw screenshot, trace, accessibility, console, and network bytes and submit the runtime-attested result through the engine-owned recording path. Caller-authored JSON or rehashed evidence cannot certify PASS.\n5. If a mandatory browser, trusted adapter, or session is unavailable, retain a blocking result; never skip, infer PASS, open review, add reviewers, register a correction, or write lifecycle truth.\n",
+      "sourceDigest": "sha256:7ec450ada7f5bfca3e094ef1ab2bd6cedf8706299dae9d6426da5cb98428c776",
+      "contracts": {
+        "inputs": [{ "id": "browser-qa-gate", "version": "1.0.0" }, { "id": "browser-qa-session", "version": "1.0.0" }],
+        "outputs": [{ "id": "browser-qa-result", "version": "1.0.0" }]
+      },
+      "authorityClass": "quality-evidence",
+      "triggerPolicy": {
+        "include": ["test this UI in a real browser", "verify routes, forms, accessibility, console, and network behavior"],
+        "exclude": ["unit-test-only backend work", "requests to approve, land, publish, or release"],
+        "deferTo": ["planr-ship", "planr-land"]
+      },
+      "cliRequirements": [
+        { "id": "pipeline-prepare-browser-qa", "argv": ["pipeline", "prepare-browser-qa", "<feature>"], "requiredOptions": ["--run-id", "--json"] },
+        { "id": "pipeline-record-browser-qa", "argv": ["pipeline", "record-browser-qa", "<feature>"], "requiredOptions": ["--run-id", "--generation", "--result-file", "--json"], "inputOptions": ["--session-file"] }
+      ],
+      "hosts": [
+        { "host": "claude-code", "entrypoint": "/planr-pipeline:planr-browser-qa", "path": "skills/planr-browser-qa/SKILL.md" },
+        { "host": "codex", "entrypoint": "$planr-browser-qa", "path": "adapters/codex/skills/planr-browser-qa/SKILL.md" },
+        { "host": "cursor", "entrypoint": "planr-browser-qa", "path": "adapters/cursor/rules/openplanr-browser-qa.mdc" }
+      ]
+    },
+    {
+      "skillId": "planr-investigate",
+      "sourceOwner": "skills",
+      "sourceVersion": "1.0.0",
+      "sourceSnapshot": "---\nname: planr-investigate\ndescription: Reproduce and prove a root cause, or apply one authorized bounded fix with regression evidence. Use when asked to diagnose a bug, investigate an error, establish causality, or fix a defect from an immutable diagnosis receipt.\n---\n\n# Planr Investigate\n\n1. Create one closed `diagnose` or `fix` request. Diagnose start, command-backed experiments, and verification require a registered runtime adapter with the engine-issued read-only command host; on `E_INVESTIGATION_COMMAND_HOST_REQUIRED`, stop and hand off rather than executing commands independently.\n2. Start a fix only from the exact proven diagnosis receipt and unchanged baseline. Run `planr pipeline investigate start <feature> --request-file <path|-> --json` in an interactive owner terminal and confirm the exact request digest; caller-authored authority JSON cannot replace the one-shot capability.\n3. Advance non-command observations, hypotheses, diagnosis, and bounded change records with `planr pipeline investigate advance <feature> --run-id <runId> --event-file <path|-> --json`. Command-backed experiments and `investigate verify` must remain with the trusted adapter.\n4. Finalize with `planr pipeline investigate finalize <feature> --run-id <runId> --json` and stop at its immutable receipt.\n5. Diagnose mode is read-only. Never invent evidence, edit outside the declared scope, approve, start SHIP, land, publish, release, or author lifecycle markers.\n",
+      "sourceDigest": "sha256:4fc6fdfb7b088ba185eea26ce1e7feb28a6cb469669d53d218a322bc9fea5b55",
+      "contracts": {
+        "inputs": [{ "id": "investigation-request", "version": "1.0.0" }],
+        "outputs": [{ "id": "investigation-receipt", "version": "1.0.0" }]
+      },
+      "authorityClass": "diagnose-or-authorized-fix",
+      "triggerPolicy": {
+        "include": ["diagnose this bug and prove the root cause", "apply a bounded fix from the accepted diagnosis"],
+        "exclude": ["unscoped feature implementation", "requests to approve, land, publish, or release"],
+        "deferTo": ["planr-spec", "planr-ship", "planr-land"]
+      },
+      "cliRequirements": [
+        { "id": "pipeline-investigate-start", "argv": ["pipeline", "investigate", "start", "<feature>"], "requiredOptions": ["--request-file", "--json"] },
+        { "id": "pipeline-investigate-advance", "argv": ["pipeline", "investigate", "advance", "<feature>"], "requiredOptions": ["--run-id", "--event-file", "--json"] },
+        { "id": "pipeline-investigate-verify", "argv": ["pipeline", "investigate", "verify", "<feature>"], "requiredOptions": ["--run-id", "--json"] },
+        { "id": "pipeline-investigate-finalize", "argv": ["pipeline", "investigate", "finalize", "<feature>"], "requiredOptions": ["--run-id", "--json"] }
+      ],
+      "hosts": [
+        { "host": "claude-code", "entrypoint": "/planr-pipeline:planr-investigate", "path": "skills/planr-investigate/SKILL.md" },
+        { "host": "codex", "entrypoint": "$planr-investigate", "path": "adapters/codex/skills/planr-investigate/SKILL.md" },
+        { "host": "cursor", "entrypoint": "planr-investigate", "path": "adapters/cursor/rules/openplanr-investigate.mdc" }
+      ]
+    },
+    {
+      "skillId": "planr-plan-review",
+      "sourceOwner": "skills",
+      "sourceVersion": "1.0.0",
+      "sourceSnapshot": "---\nname: planr-plan-review\ndescription: Run one finite digest-bound professional review of a prepared Planr plan with CEO, engineering, design, and DevEx perspectives. Use after a professional specification is planned and before the owner decides whether PLAN may proceed to SHIP.\n---\n\n# Planr Plan Review\n\n1. Run `planr pipeline prepare-plan-review <feature> --json` and present the exact plan digest, scope, roster, and unresolved prerequisites.\n2. Start once with `planr pipeline start-plan-review <feature> --runtime <runtimeId> --json`. Use the frozen CEO, engineering, design, and DevEx roster as one consolidated batch.\n3. Submit only declared review events through `planr pipeline advance-plan-review <feature> --run-id <runId> --event-file <path|-> --json`. Do not create parallel or late review loops.\n4. Preserve findings, dissent, and uncertainty in the immutable receipt. Never claim owner approval, approve PLAN to SHIP, start SHIP, edit planning truth directly, land, publish, or release.\n5. Return the receipt and exact owner-facing decision boundary. The owner remains the only R1 authority.\n",
+      "sourceDigest": "sha256:a196877214e5b787d19e5f5805159e25f72da1a9ccacf8b89916bfc22bfba37a",
+      "contracts": {
+        "inputs": [{ "id": "professional-specification", "version": "1.0.0" }],
+        "outputs": [{ "id": "planning-review-receipt", "version": "1.0.0" }]
+      },
+      "authorityClass": "review-evidence",
+      "triggerPolicy": {
+        "include": ["professionally review this prepared plan", "challenge this plan with CEO, engineering, design, and DevEx perspectives"],
+        "exclude": ["approve the plan for the owner", "implement, ship, land, publish, or release the plan"],
+        "deferTo": ["planr-plan", "planr-ship", "planr-land"]
+      },
+      "cliRequirements": [
+        { "id": "pipeline-prepare-plan-review", "argv": ["pipeline", "prepare-plan-review", "<feature>"], "requiredOptions": ["--json"] },
+        { "id": "pipeline-start-plan-review", "argv": ["pipeline", "start-plan-review", "<feature>"], "requiredOptions": ["--runtime", "--json"] },
+        { "id": "pipeline-advance-plan-review", "argv": ["pipeline", "advance-plan-review", "<feature>"], "requiredOptions": ["--run-id", "--event-file", "--json"] }
+      ],
+      "hosts": [
+        { "host": "claude-code", "entrypoint": "/planr-pipeline:planr-plan-review", "path": "skills/planr-plan-review/SKILL.md" },
+        { "host": "codex", "entrypoint": "$planr-plan-review", "path": "adapters/codex/skills/planr-plan-review/SKILL.md" },
+        { "host": "cursor", "entrypoint": "planr-plan-review", "path": "adapters/cursor/rules/openplanr-plan-review.mdc" }
+      ]
+    },
+    {
+      "skillId": "planr-spec",
+      "sourceOwner": "skills",
+      "sourceVersion": "1.0.0",
+      "sourceSnapshot": "---\nname: planr-spec\ndescription: Turn vague product or engineering intent into a measurable professional Planr specification with constraints, evidence expectations, failure modes, and rollback. Use when requirements are unclear or a new feature needs bounded scope before PLAN.\n---\n\n# Planr Spec\n\n1. Invoke the installed public `planr spec` flow with the user's intent or file. Let OpenPlanr own questioning, IDs, persistence, and validation.\n2. Resolve measurable outcomes, constraints, evidence expectations, failure modes, rollback, and explicit exclusions through the returned guided interaction. Do not invent approval or implementation authority.\n3. Require the resulting artifact to declare `professional-specification@1.0.0`; surface typed missing inputs instead of silently filling them.\n4. Stop with the professional specification ready for human review. Never auto-chain PLAN, plan review, SHIP, implementation, landing, publication, deployment, or release.\n",
+      "sourceDigest": "sha256:aaf628d67ed69e5078e4c6321cc2510649a001f255a8716a414f03d8106114c9",
+      "contracts": {
+        "inputs": [{ "id": "intent", "version": "1.0.0" }],
+        "outputs": [{ "id": "professional-specification", "version": "1.0.0" }]
+      },
+      "authorityClass": "planning-write",
+      "triggerPolicy": {
+        "include": ["turn this vague idea into a measurable specification", "define scope, evidence, failure modes, and rollback before planning"],
+        "exclude": ["review an existing plan", "implement, ship, land, publish, or release a feature"],
+        "deferTo": ["planr-plan", "planr-plan-review", "planr-ship", "planr-land"]
+      },
+      "cliRequirements": [
+        { "id": "spec-create", "argv": ["spec", "<intent-or-file>"], "requiredOptions": [] }
+      ],
+      "hosts": [
+        { "host": "claude-code", "entrypoint": "/planr-pipeline:planr-spec", "path": "skills/planr-spec/SKILL.md" },
+        { "host": "codex", "entrypoint": "$planr-spec", "path": "adapters/codex/skills/planr-spec/SKILL.md" },
+        { "host": "cursor", "entrypoint": "planr-spec", "path": "adapters/cursor/rules/openplanr-spec.mdc" }
+      ]
+    }
+  ]
+}

package/registry/roles.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "1.0.0",
+  "roles": [
+    { "id": "db-agent", "phase": "po-preflight", "activation": "conditional", "capability": "analysis-high", "writeBoundary": "output/db/schema.json only; database is read-only", "source": "agents/db-agent.md" },
+    { "id": "designer-agent", "phase": "po", "activation": "conditional", "capability": "analysis-high", "writeBoundary": "design-spec.md only", "source": "agents/designer-agent.md" },
+    { "id": "specification-agent", "phase": "po", "activation": "always", "capability": "analysis-high", "writeBoundary": "stories and task specifications only", "source": "agents/specification-agent.md" },
+    { "id": "entity-scaffold-agent", "phase": "po-preflight", "activation": "manual", "capability": "analysis-high", "writeBoundary": "output/src persistence scaffolding only", "source": "agents/entity-scaffold-agent.md" },
+    { "id": "frontend-agent", "phase": "dev", "activation": "conditional", "capability": "implementation-high", "writeBoundary": "task Create/Modify UI paths only", "source": "agents/frontend-agent.md" },
+    { "id": "backend-agent", "phase": "dev", "activation": "conditional", "capability": "implementation-high", "writeBoundary": "task Create/Modify tech paths only", "source": "agents/backend-agent.md" },
+    { "id": "qa-agent", "phase": "qa", "activation": "always", "capability": "read-only-qa", "writeBoundary": "none; returns one structured review result", "source": "agents/qa-agent.md" },
+    { "id": "devops-agent", "phase": "post-build", "activation": "conditional", "capability": "analysis-high", "writeBoundary": "declared infrastructure configuration only; never deploy", "source": "agents/devops-agent.md" },
+    { "id": "doc-gen-agent", "phase": "post-build", "activation": "conditional", "capability": "analysis-high", "writeBoundary": "Docs feature output only", "source": "agents/doc-gen-agent.md" }
+  ]
+}

package/registry/ship-review-specialists.json

@@ -0,0 +1,42 @@
+{
+  "kind": "ship-review-specialist-registry",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.1.0",
+  "specialists": [
+    {
+      "id": "security",
+      "triggers": ["authentication", "authorization", "credentials", "permissions", "security"],
+      "capabilities": ["candidate.read", "evidence.read", "finding.contribute"],
+      "resultKind": "specialist-review-result",
+      "authority": "read-only-consolidated-review"
+    },
+    {
+      "id": "performance",
+      "triggers": ["benchmark", "budget", "latency", "performance"],
+      "capabilities": ["candidate.read", "evidence.read", "finding.contribute"],
+      "resultKind": "specialist-review-result",
+      "authority": "read-only-consolidated-review"
+    },
+    {
+      "id": "migration",
+      "triggers": ["migration", "rollback", "schema-transition"],
+      "capabilities": ["candidate.read", "evidence.read", "finding.contribute"],
+      "resultKind": "specialist-review-result",
+      "authority": "read-only-consolidated-review"
+    },
+    {
+      "id": "api-contract",
+      "triggers": ["api", "contract", "network", "route", "schema"],
+      "capabilities": ["candidate.read", "evidence.read", "finding.contribute"],
+      "resultKind": "specialist-review-result",
+      "authority": "read-only-consolidated-review"
+    },
+    {
+      "id": "data-integrity",
+      "triggers": ["data-write", "database", "persistence", "receipt", "storage"],
+      "capabilities": ["candidate.read", "evidence.read", "finding.contribute"],
+      "resultKind": "specialist-review-result",
+      "authority": "read-only-consolidated-review"
+    }
+  ]
+}

package/schemas/v1.0.0/design-approved.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.0.0/design-approved.schema.json",
+  "title": "OpenPlanr design-loop approval record (v1.0.0)",
+  "description": "Written as approved.json in the session dir when the user approves a variant on the board (\"We'll run with Option X\"). Records WHAT was approved and WHERE the approved output was copied INTO the repo (exploration artifacts themselves stay in user space). The design loop STOPs after writing this (R1) — a human invokes the next phase.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "boardId",
+    "sessionId",
+    "approvedVariant",
+    "approvedPath",
+    "provider",
+    "target",
+    "approvedAt",
+    "copiedTo"
+  ],
+  "properties": {
+    "schema_version": { "const": "1.0.0", "description": "Schema version pin." },
+    "boardId": { "type": "string", "minLength": 1, "description": "Board the approval came from." },
+    "sessionId": { "type": "string", "minLength": 1, "description": "The approved variant's session id." },
+    "approvedVariant": { "type": "string", "minLength": 1, "description": "Variant id, e.g. \"B\"." },
+    "approvedPath": { "type": "string", "minLength": 1, "description": "Absolute path of the approved artifact in the session dir." },
+    "provider": { "type": "string", "enum": ["openai", "claude-svg"], "description": "Provider that produced the approved artifact." },
+    "target": { "type": "string", "minLength": 1, "description": "What was designed (logo, brand-sheet, screen, og-image, …)." },
+    "approvedAt": { "type": "string", "minLength": 1, "description": "ISO timestamp." },
+    "copiedTo": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo destinations the approved output (+ derivatives like favicon set / production SVG) was copied to."
+    },
+    "notes": { "type": "string", "description": "Optional approval notes from the overall textarea." }
+  }
+}

package/schemas/v1.0.0/design-feedback.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.0.0/design-feedback.schema.json",
+  "title": "OpenPlanr design-loop feedback (v1.0.0)",
+  "description": "The board↔agent file handshake. The board writes feedback.json (Submit / Approve) or feedback-pending.json (Regenerate / Remix / More-like-this) NEXT TO the board HTML; the agent reads it only after the user says they're done in the blocking AskUserQuestion. feedback-pending.json is consumed (deleted) on read. `ratings` and `comments` are keyed by variant id (A, B, …) — dynamic keys, so they are open objects here; value shapes are enforced by lib/design-engine/feedback.mjs. Pins carry normalized 0..1 region coords; the ≤1 upper bound is clamped at write time (the schema subset has no `maximum`).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "boardId",
+    "publishedAt",
+    "regenerated",
+    "ratings",
+    "comments",
+    "pins"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0.0",
+      "description": "Schema version pin."
+    },
+    "boardId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The board this feedback belongs to (daemon registry id)."
+    },
+    "publishedAt": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO timestamp the feedback was written by the board."
+    },
+    "preferred": {
+      "type": "string",
+      "description": "Variant id the user picked in the approve bar (e.g. \"A\"). Absent until chosen."
+    },
+    "ratings": {
+      "type": "object",
+      "description": "Per-variant star rating 1..5, keyed by variant id."
+    },
+    "comments": {
+      "type": "object",
+      "description": "Per-variant free-text comment, keyed by variant id."
+    },
+    "overall": {
+      "type": "string",
+      "description": "Overall-direction textarea content."
+    },
+    "regenerated": {
+      "type": "boolean",
+      "description": "true when this is a feedback-pending.json round (the user asked for another generation pass) rather than a final submit."
+    },
+    "regenerateAction": {
+      "type": "string",
+      "enum": ["iterate", "remix", "more-like"],
+      "description": "Which regeneration the user asked for. Required by code when regenerated=true."
+    },
+    "remixSpec": {
+      "type": "object",
+      "description": "Remix instructions, e.g. { layoutFrom: \"A\", colorsFrom: \"B\", note }. Open shape; interpreted by the loop procedure."
+    },
+    "authors": {
+      "type": "array",
+      "description": "the roster of reviewers who contributed to this board. Each appears once, keyed by display name. Identity is a LOCAL display name + deterministic avatar only — no account, no auth, no PII.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Reviewer display name (the merge + avatar key)."
+          },
+          "color": {
+            "type": "string",
+            "description": "Avatar background token/value derived deterministically from the name (e.g. \"--avatar-3\")."
+          },
+          "initials": {
+            "type": "string",
+            "description": "1–2 letter initials shown in the avatar."
+          },
+          "lastSeen": {
+            "type": "string",
+            "description": "ISO timestamp the author last contributed."
+          }
+        }
+      }
+    },
+    "pins": {
+      "type": "array",
+      "description": "Region annotations — the core of \"fix exactly this part\".",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "author", "variant", "x", "y", "w", "h", "comment", "intent"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "stable item id (12-char sha256 hex prefix of author+createdAt+comment). The merge key together with `author`; assigned by normalizeLegacy for legacy items."
+          },
+          "author": {
+            "type": "string",
+            "minLength": 1,
+            "description": "the reviewer who created this pin (display name). Legacy/unattributed items normalize to \"Anonymous\"."
+          },
+          "variant": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Variant id (design-loop) or screen id (design-review) the pin sits on."
+          },
+          "x": { "type": "number", "minimum": 0, "description": "Left edge, normalized 0..1 of the variant's rendered box." },
+          "y": { "type": "number", "minimum": 0, "description": "Top edge, normalized 0..1." },
+          "w": { "type": "number", "minimum": 0, "description": "Width, normalized 0..1 (0 for a point pin)." },
+          "h": { "type": "number", "minimum": 0, "description": "Height, normalized 0..1 (0 for a point pin)." },
+          "comment": { "type": "string", "minLength": 1, "description": "What the user wants done here." },
+          "intent": {
+            "type": "string",
+            "enum": ["fix", "improve", "question"],
+            "description": "How the agent should treat the pin."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["open", "addressed", "resolved"],
+            "description": "lifecycle of the pin as tracked feedback. Defaults to \"open\" when absent."
+          },
+          "createdAt": {
+            "type": "string",
+            "description": "ISO timestamp the pin was created (also feeds the stable id)."
+          },
+          "screen": {
+            "type": "string",
+            "description": "design-review only: the artifact screen/section id the pin maps to (e.g. \"s-dashboard\")."
+          },
+          "replies": {
+            "type": "array",
+            "description": "short threaded replies on this pin so feedback is a tracked conversation, not a write-once note.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["author", "comment"],
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "optional stable reply id (the reply-level merge key). Absent on legacy/optimistic replies; mergeFeedback() falls back to a content signature (author+comment+createdAt) so the append/dedup stays idempotent without it."
+                },
+                "author": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Reviewer who wrote the reply (display name)."
+                },
+                "comment": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Reply text."
+                },
+                "createdAt": {
+                  "type": "string",
+                  "description": "ISO timestamp the reply was written."
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/v1.0.0/design-manifest.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.0.0/design-manifest.schema.json",
+  "title": "OpenPlanr design manifest — finalized.json (v1.0.0)",
+  "description": "Metadata written alongside a generated design artifact by /planr-pipeline:design, at <design-dir>/finalized.json. The discriminator field is `design_format`, NOT `format` (the latter is a reserved JSON-Schema keyword). Cross-field rules (framework 'react' only for canvas) are enforced by lib/design/manifest.mjs validateManifest, not expressible in this schema subset.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "design_format",
+    "source",
+    "content_provenance",
+    "framework",
+    "screens",
+    "screen_count",
+    "iterations",
+    "generated_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0.0",
+      "description": "Schema version pin."
+    },
+    "design_format": {
+      "type": "string",
+      "enum": ["prototype", "walkthrough", "canvas"],
+      "description": "Which renderer produced the artifact."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["spec", "png", "describe"],
+      "description": "How the design was sourced (mirrors the --from flag)."
+    },
+    "content_provenance": {
+      "type": "string",
+      "enum": ["spec", "inferred"],
+      "description": "Whether screen content came from the spec or was inferred to fill a thin spec."
+    },
+    "framework": {
+      "type": "string",
+      "enum": ["vanilla", "react"],
+      "description": "Render substrate. prototype/walkthrough = vanilla + Pretext; canvas = react."
+    },
+    "screens": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Ordered screen names rendered in the artifact."
+    },
+    "screen_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Length of screens (denormalized for quick status reads)."
+    },
+    "iterations": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of evolve passes applied to this artifact."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
+    },
+    "nav_mode": {
+      "type": "string",
+      "enum": ["anchor", "lazy"],
+      "description": "Walkthrough navigation mode; omitted for non-walkthrough formats."
+    },
+    "screen_name": {
+      "type": "string",
+      "description": "Primary screen / output-directory basename."
+    },
+    "branch": {
+      "type": "string",
+      "description": "Git branch at generation time."
+    },
+    "spec_id": {
+      "type": "string",
+      "description": "Owning SPEC/FEAT id (e.g. SPEC-015)."
+    },
+    "html_file": {
+      "type": "string",
+      "description": "Primary artifact filename (e.g. finalized.html, canvas.html)."
+    },
+    "pretext_tier": {
+      "type": "string",
+      "description": "Pretext API tier chosen for vanilla formats."
+    }
+  }
+}

package/schemas/v1.0.0/design-session.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.0.0/design-session.schema.json",
+  "title": "OpenPlanr design-loop session (v1.0.0)",
+  "description": "One variant's generation lineage, persisted as session-<variant>.json in the session dir (user space, ~/.planr/designs/<project>/<target>-<date>/) — NOT /tmp, so a session can be revisited. For provider=openai, lastResponseId chains the Responses API so `iterate` refines instead of regenerating. For provider=claude-svg the chain is the file itself (the agent edits the artifact); lastResponseId stays null.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "id",
+    "provider",
+    "target",
+    "originalBrief",
+    "briefVersions",
+    "feedbackHistory",
+    "outputPaths",
+    "regionEdits",
+    "createdAt",
+    "updatedAt"
+  ],
+  "properties": {
+    "schema_version": { "const": "1.0.0", "description": "Schema version pin." },
+    "id": { "type": "string", "minLength": 1, "description": "Session id (e.g. \"logo-2026-06-10-A\")." },
+    "provider": {
+      "type": "string",
+      "enum": ["openai", "claude-svg"],
+      "description": "Which provider owns this session's generation chain."
+    },
+    "target": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What is being designed: logo, brand-sheet, screen, og-image, …"
+    },
+    "project": { "type": "string", "description": "Project slug the exploration belongs to." },
+    "originalBrief": { "type": "string", "minLength": 1, "description": "The first brief, verbatim." },
+    "briefVersions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Every brief revision, oldest→newest (the original is index 0)."
+    },
+    "feedbackHistory": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The feedback text applied at each iterate round, oldest→newest."
+    },
+    "outputPaths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Absolute artifact path per round, oldest→newest (last = current)."
+    },
+    "regionEdits": {
+      "type": "array",
+      "description": "Pin-driven edits applied to this session (design-review rounds).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["at", "pins", "summary"],
+        "properties": {
+          "at": { "type": "string", "minLength": 1, "description": "ISO timestamp of the edit round." },
+          "screen": { "type": "string", "description": "Screen/section id the round targeted, when scoped." },
+          "pins": { "type": "array", "items": { "type": "object" }, "description": "The pins (design-feedback shape) that drove the edit." },
+          "summary": { "type": "string", "minLength": 1, "description": "One line: what was changed." }
+        }
+      }
+    },
+    "lastResponseId": {
+      "type": ["string", "null"],
+      "description": "openai provider: the Responses API id to chain via previous_response_id. null for claude-svg."
+    },
+    "createdAt": { "type": "string", "minLength": 1, "description": "ISO timestamp." },
+    "updatedAt": { "type": "string", "minLength": 1, "description": "ISO timestamp of the last round." }
+  }
+}