openplanr 3.2.0 → 3.4.0

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

@@ -1,12 +1,12 @@
 ---
-description: "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work."
+description: "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work, or to plan and implement an accepted change. Invoke before editing files for the requested change. Not for planning only, landing, release, or work handed to another coding agent."
 alwaysApply: false
 ---
 
 # OpenPlanr Ship
 
-Produce an implementation-complete local repository in this active coding
-session. Landing and release preparation belong to `planr-land`. Ordinary
+Produce an implementation-complete local repository in this active coding session.
+Landing and release preparation belong to `planr-land`. Ordinary
 Ship stays host-native. Do not delegate implementation to a command-line or model subprocess. If the user explicitly asks another coding agent to implement,
 hand off to `planr-delegate` before implementation. That separate opt-in workflow
 previews the selected context, writable repository, profile, and destination;
@@ -18,7 +18,8 @@ For a selector, locate exactly one task and read it completely. Then follow its
 `storyId` and `specId` to the parent story, acceptance criteria, Gherkin file
 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.
+implementation code, tests, and interfaces produced by declared dependencies. Read any
+`.planr/conventions/<area>.md`, indexed from AGENTS.md, for the areas this task touches.
 
 Read [the design lineage contract](planr-ship/references/design-lineage.md). If the selected
 planning root contains `design-lineage.json`, load only the selected task's mapped
@@ -39,17 +40,40 @@ context is sufficient; missing planning files do not create a gate.
 
 ## Implement with native roles
 
-Use the host's read, edit, shell, browser, and test capabilities. When native
-agents are available, dispatch only the applicable frontend, backend, database,
-QA, DevOps, and documentation roles inside this session. Give each role its
-owned outcome, relevant context paths, and explicit file coordination boundary.
-Run independent work in parallel. Host-native role agents remain part of this
-Ship session and do not invoke the separate `planr-delegate` helper. When native
-agents are unavailable, perform the same lenses sequentially in the active agent.
+The main session owns scope, decisions, integration, and final verification.
+Use the host's read, edit, shell, browser, and test capabilities inside this session.
+Keep small coherent changes in this session. Delegate only a self-contained
+outcome that benefits from context isolation, a distinct capability boundary,
+or independent parallel work; agent availability alone is not a reason to dispatch.
+
+Frontend and backend own substantial bounded implementation assignments.
+Persistence implementation, including a task carrying the legacy `db-agent`
+identity, belongs to backend with the relevant database guidance; preserve the
+task's recorded identity. Database is optional read-only introspection when
+repository schemas are insufficient, never migration implementation. Keep small
+documentation updates with their implementation; delegate substantial documentation
+or requested configuration work separately. DevOps never deploys. Entity
+scaffolding remains manual, on explicit request.
+
+Use a separate QA reviewer for authorization, credentials, data-loss risk,
+migrations, public contracts, release behavior, or substantial delegated
+implementation. Small low-risk edits use focused verification in the main session.
+QA retains verification tools, subject to role policy and session permissions.
+
+Select the exact registered identity from the host's roster; Claude plugin
+agents use names such as `planr:planr-backend` and `planr:planr-qa`. Give each worker
+its outcome, the absolute task path with `MODE` and, in spec-driven mode, `SPEC_DIR`,
+authoritative paths, relevant decisions, file ownership, verification requirements,
+and concise return expectations. Parallel workers need disjoint
+writes or an agreed interface. Explain the delegation's purpose briefly in
+commentary. Host-native workers do not invoke the separate `planr-delegate` helper.
+When the host lacks the native role, perform the work sequentially in this session
+and disclose capability limitations; never claim an unavailable specialist ran.
 
 Integrate the complete change, then verify behavior. `reviewRisks` and
 `browserSurfaces` select useful checks; empty arrays are normal and neither field
-is a workflow gate.
+is a workflow gate. Re-run the cheap checks a worker reports as passed, and compare
+its `changed` list with `git diff --name-only` plus untracked files; report any difference.
 
 ## Discover and run verification
 
@@ -64,9 +88,14 @@ Run `openplanr ship checks --json --task <task-path>` (omit `--task` for a direc
 request; add `--tier story` or `--tier push` before pushing) and run its `checks`
 from each `cwd`. The command never executes checks or writes files. When
 `complete` is `false`, report its error diagnostics and treat the check set as
-incomplete: a pass is not CI-equivalent. Without the CLI, the packaged read-only
-[verification discovery helper](planr-ship/scripts/discover-verification.mjs) may list
-candidates. Resolve it relative to this `SKILL.md` and run
+incomplete: a pass is not CI-equivalent. Act on warning diagnostics too; each names
+the files or checks it affects. A diagnostic that a check could not run, such as
+`TYPESCRIPT_UNAVAILABLE`, is not a pass: name that check in `checks` and verify its
+concern yourself where you can (for a new test file, confirm some tsconfig includes
+it). For a `package-contents` check, account for every `expectFiles` entry in the
+tarball's `files`: packed or deliberately left out. Without
+the CLI, the packaged read-only [verification discovery helper](planr-ship/scripts/discover-verification.mjs)
+may list candidates. Resolve it relative to this `SKILL.md` and run
 `node <helper> --project <repository-root> --task <task-path>`; omit `--task` for a
 direct request. It never executes checks or writes files. If both are unavailable,
 inspect those four sources directly. Missing commands are diagnostics, not a
@@ -76,6 +105,8 @@ Run the strongest applicable focused checks while working, then the relevant
 regression checks. Run each check on its own or under `set -o pipefail`, and judge
 it by its own exit code; to shorten output, write it to a log and read the tail.
 Fix failures caused by the change and rerun affected checks.
+For an acceptance check written or changed for this task, follow
+[fail-first](planr-ship/references/fail-first.md) and report what it proved in that check's result.
 Read [the result contract](planr-ship/references/result-contract.md) before reporting.
 
 Report defects you notice outside the task as [findings](planr-ship/references/findings.md),
@@ -94,10 +125,12 @@ behavior, link material changes by purpose, and summarize actual verification.
 Retain complete file inventories and command diagnostics in their existing
 results instead of reproducing them in chat.
 
-- **Outcome:** `completed`, `partial`, or `blocked`, followed by what now works.
+- **Outcome:** `completed`, `partial`, `blocked`, or `awaiting-acceptance` (repository
+  work done; acceptance needs a run only the owner can do), followed by what now works.
 - **Task:** task ID and path, or `direct-request`.
-- **Changed:** material paths grouped by purpose.
-- **Checks:** command, `passed`, `failed`, or `not-run`, plus a concise result.
+- **Changed:** material paths grouped by purpose, files outside Create and Modify apart.
+- **Checks:** command, `passed`, `failed`, or `not-run`, plus a concise result and the
+  acceptance IDs it covers; list acceptance criteria no check covers.
 - **Issues:** blockers with problem, impact, and next action, or `none`; then
   findings outside the task, each with its disposition.
 

package/lib/host-packages/cursor/openplanr/rules/planr-spec/references/specification-contract.md

@@ -30,7 +30,9 @@ template:
 
 Keep evidence and rollback as useful planning context, not approval gates or
 receipt requirements. A risk-specialist section may be empty when no specialist
-lens applies.
+lens applies. Under `## Notes for Decomposition`, list each decision made without
+an answer as a bullet starting `Assumption:` that names the decision and the
+alternative not taken.
 
 For a repository intentionally using default mode, write
 `input/specs/spec-{slug}.md` and preserve its active schema. Do not create a

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

@@ -22,6 +22,12 @@ mutually exclusive questions at once and put the recommended option first. If
 the host lacks that interface, ask one concise chat question. Do not present a
 long prose questionnaire.
 
+If no one can answer, as in a headless run, do not ask: choose the
+repository-backed default, or the recommended one when the repository does not
+settle it, and record each such choice as a bullet starting `Assumption:` under
+`## Notes for Decomposition`, naming the decision and the alternative not taken.
+Record a decision you settle inside a functional requirement the same way.
+
 When native agents are available, use the specification role to consolidate the
 contract and dispatch database or designer roles only when their lens affects
 the decision. Otherwise perform those lenses sequentially in the active agent.

package/lib/host-packages/cursor/openplanr/runtime/design/scripts/design-artifact-shell.mjs

@@ -1,9 +1,7 @@
 import {
-  digestArtifactEnvelope
-} from "./design-shared-artifact-support-protocol-contracts-ea2cd15e.mjs";
-import {
+  digestArtifactEnvelope,
   validateJson
-} from "./design-shared-protocol-contracts-b5f28f94.mjs";
+} from "./design-shared-artifact-support-protocol-contracts-9f6918b0.mjs";
 
 // packages/artifact/lib/artifact/ui/shell.mjs
 import { readFileSync as readFileSync2 } from "node:fs";

package/lib/host-packages/cursor/openplanr/runtime/design/scripts/design-document.mjs

@@ -1,3 +1,18 @@
+import {
+  DESIGN_DOCUMENT_SCHEMA,
+  assertDesignDocument,
+  bundleLocalDocument,
+  initialFrameHeight,
+  inspectLocalDocumentBody,
+  loadReviewContext,
+  parse,
+  parseFragment,
+  resolveLocalDocumentFile,
+  reviewDigest,
+  reviewFingerprints,
+  serialize,
+  validateDesignProps
+} from "./design-shared-artifact-support-dependencies-design-support-protocol-contracts-d707e49b.mjs";
 import {
   AA_NORMAL,
   contrastRatio,
@@ -6,6 +21,15 @@ import {
   renderArtifactShellDocument,
   renderPlanrMark
 } from "./design-artifact-shell.mjs";
+import {
+  ARTIFACT_ERROR_CODES,
+  ARTIFACT_MAX_SOURCES,
+  ARTIFACT_MAX_VIEWS,
+  PipelineError,
+  createSharedArtifactEnvelope,
+  digestArtifactEnvelope,
+  resolveArtifactHtml
+} from "./design-shared-artifact-support-protocol-contracts-9f6918b0.mjs";
 import {
   ARTIFACT_FRAME_GUARD_TEMPLATE,
   ARTIFACT_HOST_GUARD_TEMPLATE,
@@ -14,38 +38,16 @@ import {
 import {
   atomicBytes,
   atomicJson,
-  bundleLocalDocument,
   currentDesign,
   designSpecPath,
   hash,
   json,
-  loadReviewContext,
-  parse,
-  parseFragment,
   readJson,
-  recoverDesignPublication,
-  resolveLocalDocumentFile,
-  reviewDigest,
-  reviewFingerprints,
-  serialize
-} from "./design-shared-artifact-support-dependencies-design-support-protocol-contracts-3d9b1a86.mjs";
+  recoverDesignPublication
+} from "./design-shared-design-support-0bac378d.mjs";
 import {
   acquireStartLock
 } from "./design-loopback-server.mjs";
-import {
-  ARTIFACT_ERROR_CODES,
-  ARTIFACT_MAX_SOURCES,
-  ARTIFACT_MAX_VIEWS,
-  PipelineError,
-  createSharedArtifactEnvelope,
-  digestArtifactEnvelope,
-  resolveArtifactHtml
-} from "./design-shared-artifact-support-protocol-contracts-ea2cd15e.mjs";
-import {
-  DESIGN_DOCUMENT_SCHEMA,
-  assertDesignDocument,
-  initialFrameHeight
-} from "./design-shared-protocol-contracts-b5f28f94.mjs";
 
 // packages/design/lib/design/frame-size.mjs
 function designFrameLabel(frame) {
@@ -1620,6 +1622,15 @@ function lintDesign(html, opts = {}) {
   const { designSystem = null } = opts;
   const errors = [];
   const warnings = [];
+  if (opts.screen) {
+    const values = Object.hasOwn(opts.variant?.props ?? {}, opts.screen.id) ? opts.variant.props[opts.screen.id] : {};
+    errors.push(
+      ...validateDesignProps({
+        screens: [opts.screen],
+        variants: [{ props: { [opts.screen.id]: values } }]
+      }).map((message) => ({ rule: "invalid-instance-prop", level: "error", message }))
+    );
+  }
   const decls = [...styleBlockDecls(html), ...inlineStyleDecls(html)];
   for (const d of decls) {
     if (SPACING_PROP.test(d.prop)) {
@@ -1693,6 +1704,57 @@ function lintDesign(html, opts = {}) {
     summary: `${errors.length} error(s), ${warnings.length} warning(s)`
   };
 }
+function withoutRootTheme(html) {
+  if (!/theme-(?:light|dark)|data-theme/iu.test(html)) return null;
+  const body = inspectLocalDocumentBody(html);
+  if (!body) return null;
+  const edits = [];
+  for (const { name, value } of body.attrs) {
+    const location = body.location.attrs?.[name];
+    if (!location) continue;
+    let replacement;
+    if (name === "data-theme" && ["light", "dark"].includes(value)) replacement = "";
+    if (name === "class") {
+      const raw = html.slice(location.startOffset, location.endOffset);
+      const quoted = /^(class\s*=\s*)(["'])([\s\S]*)\2$/iu.exec(raw);
+      if (quoted) {
+        const kept = quoted[3].replace(/(^|\s)theme-(?:light|dark)(?=\s|$)/gu, "$1");
+        if (kept !== quoted[3]) replacement = `${quoted[1]}${quoted[2]}${kept}${quoted[2]}`;
+      } else if (/^class\s*=\s*theme-(?:light|dark)$/iu.test(raw)) replacement = "";
+    }
+    if (replacement !== void 0) edits.push({ ...location, replacement });
+  }
+  if (!edits.length) return null;
+  let normalized = html;
+  for (const { startOffset, endOffset, replacement } of edits.sort(
+    (a, b) => b.startOffset - a.startOffset
+  ))
+    normalized = normalized.slice(0, startOffset) + replacement + normalized.slice(endOffset);
+  return normalized;
+}
+function lintThemeOnlySources(sources) {
+  const warnings = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const { screenId, source, html } of sources) {
+    const normalized = withoutRootTheme(html);
+    if (normalized === null) continue;
+    const key = JSON.stringify({
+      html: normalized,
+      styles: source.styles ?? [],
+      scripts: source.scripts ?? []
+    });
+    const previous = seen.get(key);
+    if (previous && previous.screenId !== screenId && previous.source !== source.html && previous.html !== html)
+      warnings.push({
+        rule: "theme-only-source",
+        level: "warn",
+        screenId,
+        message: `Screens ${previous.screenId} (${previous.source}) and ${screenId} (${source.html}) differ only by a root theme marker; declare a theme prop and share one source.`
+      });
+    else seen.set(key, { screenId, source: source.html, html });
+  }
+  return warnings;
+}
 function lintCanvasData(data, { frames } = {}) {
   const errors = [];
   for (const section of data?.sections || []) {
@@ -2434,8 +2496,19 @@ function prepareDesignDocument(file, { readSource, passive = false, maxBytes } =
     ])
   );
   for (const variant of document2.variants.filter((item) => item.status === "ready")) {
+    const themeWarnings = lintThemeOnlySources(
+      document2.screens.map((screen) => {
+        const source = variant.sources?.[screen.id] ?? screen.source;
+        return {
+          screenId: screen.id,
+          source,
+          html: sourceContents.get(source.html).toString("utf8")
+        };
+      })
+    );
     for (const screenId of document2.screenOrder) {
       const screen = document2.screens.find((item) => item.id === screenId);
+      const values = Object.hasOwn(variant.props ?? {}, screenId) ? variant.props[screenId] : {};
       const bundled = bundleLocalDocument({
         root,
         source: variant.sources?.[screenId] ?? screen.source,
@@ -2443,6 +2516,14 @@ function prepareDesignDocument(file, { readSource, passive = false, maxBytes } =
         screenId,
         readSource,
         passive,
+        ...screen.props ? {
+          screenProps: Object.fromEntries(
+            Object.entries(screen.props).map(([name, declaration]) => [
+              name,
+              Object.hasOwn(values, name) ? values[name] : declaration.default
+            ])
+          )
+        } : {},
         ...maxBytes === void 0 ? {} : { maxBytes }
       });
       if (document2.frames.some(({ height }) => height === "auto"))
@@ -2465,8 +2546,12 @@ function prepareDesignDocument(file, { readSource, passive = false, maxBytes } =
           );
       }
       const report = lintDesign(bundled.html, {
-        designSystem: document2.designSystem
+        designSystem: document2.designSystem,
+        screen,
+        variant
       });
+      report.warnings.push(...themeWarnings.filter((item) => item.screenId === screenId));
+      report.summary = `${report.errors.length} error(s), ${report.warnings.length} warning(s)`;
       lint.push({ variantId: variant.id, screenId, ...report });
       for (const anchor of screen.anchors ?? []) {
         if (!bundled.html.includes(`data-planr-id="${anchor}"`) && !bundled.html.includes(`id="${anchor}"`))