openplanr 3.3.0 → 3.4.0

package/lib/host-packages/cursor/openplanr/rules/planr-design-loop/references/utilities.md

@@ -2,8 +2,10 @@
 
 Run the linked design helper from the skill entrypoint relative to the skill's
 directory. It contains deterministic operations and all required assets. It needs
-Node.js 22.13 or later, with no global CLI or provider credentials. Only `fonts fetch`
-downloads anything, and only when run; nothing is fetched when a design opens.
+Node.js 22.13 or later, with no provider credentials. Local design work needs no global
+CLI. Sharing a design for company review runs in the `openplanr` CLI, which holds the
+owner keys. Only `fonts fetch` downloads anything, and only when run; nothing is
+fetched when a design opens.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 
@@ -108,12 +110,16 @@ The design remains accessible when the local machine is offline. Owner authority
 saves automatically in a protected user-level file outside the project; recovery
 export is optional. Only copy the reviewer token through the explicit Share controls.
 
-The bundled utility supports `share`, `publish`, and `sync` with the same design
-document argument. `share` creates or retries a review, `publish` sends an explicitly
-requested new revision to the existing URL, and `sync` retrieves authenticated
-feedback. Run `--help` for access-management and recovery options. The public CLI
-equivalents are `openplanr artifact share`, `openplanr artifact publish`, and
-`openplanr artifact sync`. No global CLI is required for the bundled helper.
+Sharing needs the OpenPlanr CLI (`npm install -g openplanr`). The bundled utility's
+`share`, `publish`, `sync` and `manage` commands, the studio's Share dialog, and handoff
+decisions on a shared design all run `openplanr artifact` for the network step, so the
+helper itself reads no owner keys. `share` creates or retries a review, `publish` sends
+an explicitly requested new revision to the existing URL, and `sync` retrieves
+authenticated feedback. You can also run the CLI directly: `openplanr artifact share`,
+`publish`, `sync`, `status`, `manage`, `feedback` and `handoff`. Without the CLI,
+sharing commands stop with `E_DESIGN_SHARE_CLI_REQUIRED`, and feedback inspection
+still works but reports that sync was skipped. A helper and CLI with different sharing
+formats refuse with `E_DESIGN_SHARE_RUNTIME_MISMATCH`; update whichever is older.
 
 Retention is until the owner revokes or deletes the review, while the service is
 maintained. The owner can pause comments and rotate access tokens. Rotation blocks

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/references/utilities.md

@@ -2,8 +2,10 @@
 
 Run the linked design helper from the skill entrypoint relative to the skill's
 directory. It contains deterministic operations and all required assets. It needs
-Node.js 22.13 or later, with no global CLI or provider credentials. Only `fonts fetch`
-downloads anything, and only when run; nothing is fetched when a design opens.
+Node.js 22.13 or later, with no provider credentials. Local design work needs no global
+CLI. Sharing a design for company review runs in the `openplanr` CLI, which holds the
+owner keys. Only `fonts fetch` downloads anything, and only when run; nothing is
+fetched when a design opens.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 
@@ -108,12 +110,16 @@ The design remains accessible when the local machine is offline. Owner authority
 saves automatically in a protected user-level file outside the project; recovery
 export is optional. Only copy the reviewer token through the explicit Share controls.
 
-The bundled utility supports `share`, `publish`, and `sync` with the same design
-document argument. `share` creates or retries a review, `publish` sends an explicitly
-requested new revision to the existing URL, and `sync` retrieves authenticated
-feedback. Run `--help` for access-management and recovery options. The public CLI
-equivalents are `openplanr artifact share`, `openplanr artifact publish`, and
-`openplanr artifact sync`. No global CLI is required for the bundled helper.
+Sharing needs the OpenPlanr CLI (`npm install -g openplanr`). The bundled utility's
+`share`, `publish`, `sync` and `manage` commands, the studio's Share dialog, and handoff
+decisions on a shared design all run `openplanr artifact` for the network step, so the
+helper itself reads no owner keys. `share` creates or retries a review, `publish` sends
+an explicitly requested new revision to the existing URL, and `sync` retrieves
+authenticated feedback. You can also run the CLI directly: `openplanr artifact share`,
+`publish`, `sync`, `status`, `manage`, `feedback` and `handoff`. Without the CLI,
+sharing commands stop with `E_DESIGN_SHARE_CLI_REQUIRED`, and feedback inspection
+still works but reports that sync was skipped. A helper and CLI with different sharing
+formats refuse with `E_DESIGN_SHARE_RUNTIME_MISMATCH`; update whichever is older.
 
 Retention is until the owner revokes or deletes the review, while the service is
 maintained. The owner can pause comments and rotate access tokens. Rotation blocks

package/lib/host-packages/cursor/openplanr/rules/planr-investigate/references/fail-first.md

@@ -0,0 +1,40 @@
+# Fail-first
+
+A check proves an acceptance criterion only if it fails without the change.
+
+## Applies to
+
+A check mapped to an acceptance ID, or a test written for this task. For
+Investigate, the regression test for the fix.
+
+## Fail-first
+
+- Write or run the check before the implementation. It counts only when the
+  runner reports at least one failed assertion or test.
+- A load error does not count: a missing module, a syntax or compile error, "no
+  tests found", or a collection error. Report it as "fails only on load".
+- If the runner output is unclear, say so instead of guessing.
+- A test written after the code is `not-run` for fail-first. Never revert the
+  implementation to prove it.
+
+A check that already passes before the change: report "passes before the change;
+proves nothing", then narrow or strengthen the check yourself and record that in
+`checks`.
+
+## Seeded fault
+
+Off by default. Offer it only when an acceptance check is new code or fail-first
+failed only on load; the question's default is skip.
+
+1. Record `git status --porcelain` and confirm nothing staged (`git diff --cached --quiet`).
+2. Copy the target file outside the repository.
+3. Make one small edit that breaks behaviour the criterion names.
+4. Rebuild if the tests run built output.
+5. Run the check. It must fail on an assertion.
+6. Restore from the copy, and rebuild if step 4 did; never `git checkout`, which
+   also discards the uncommitted implementation.
+7. Confirm `cmp` against the copy, an identical `--porcelain` output, and nothing staged.
+
+A seed that survives goes in `checks` with a question whose default is "add a
+test for it". Report all of this in the existing `checks` result text: no new
+field, no new stop, no record file.

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

@@ -22,6 +22,7 @@ the requested outcome.
 When the user asked for a fix, implement the smallest coherent correction within the requested
 repository and run focused regression checks. Preserve unrelated work. Ask only when a missing
 product decision or an irreversible external action genuinely blocks progress.
+Prove the regression test with [fail-first](planr-investigate/references/fail-first.md).
 
 ## Findings outside the cause
 

package/lib/host-packages/cursor/openplanr/rules/planr-ship/references/fail-first.md

@@ -0,0 +1,40 @@
+# Fail-first
+
+A check proves an acceptance criterion only if it fails without the change.
+
+## Applies to
+
+A check mapped to an acceptance ID, or a test written for this task. For
+Investigate, the regression test for the fix.
+
+## Fail-first
+
+- Write or run the check before the implementation. It counts only when the
+  runner reports at least one failed assertion or test.
+- A load error does not count: a missing module, a syntax or compile error, "no
+  tests found", or a collection error. Report it as "fails only on load".
+- If the runner output is unclear, say so instead of guessing.
+- A test written after the code is `not-run` for fail-first. Never revert the
+  implementation to prove it.
+
+A check that already passes before the change: report "passes before the change;
+proves nothing", then narrow or strengthen the check yourself and record that in
+`checks`.
+
+## Seeded fault
+
+Off by default. Offer it only when an acceptance check is new code or fail-first
+failed only on load; the question's default is skip.
+
+1. Record `git status --porcelain` and confirm nothing staged (`git diff --cached --quiet`).
+2. Copy the target file outside the repository.
+3. Make one small edit that breaks behaviour the criterion names.
+4. Rebuild if the tests run built output.
+5. Run the check. It must fail on an assertion.
+6. Restore from the copy, and rebuild if step 4 did; never `git checkout`, which
+   also discards the uncommitted implementation.
+7. Confirm `cmp` against the copy, an identical `--porcelain` output, and nothing staged.
+
+A seed that survives goes in `checks` with a question whose default is "add a
+test for it". Report all of this in the existing `checks` result text: no new
+field, no new stop, no record file.

package/lib/host-packages/cursor/openplanr/rules/planr-ship/references/result-contract.md

@@ -2,11 +2,15 @@
 
 Return one concise human rendering backed by these five machine fields:
 
-1. `outcome`: `completed`, `partial`, or `blocked`, plus the achieved result.
+1. `outcome`: `completed`, `partial`, `blocked`, or `awaiting-acceptance` (repository
+   work done; acceptance needs a run only the owner can do), plus the achieved result.
 2. `task`: exact task identity and path, or `direct-request`.
-3. `changed`: material files grouped by purpose.
+3. `changed`: material files grouped by purpose; files outside the task's Create
+   and Modify lists form their own group.
 4. `checks`: each executed or applicable check with `passed`, `failed`, or
-   `not-run` and a concise result.
+   `not-run`, a concise result, and the acceptance IDs it covers. The result says
+   what fail-first proved, for example `failed before the change on an assertion;
+   seed in src/x.ts caught`.
 5. `issues`: `blockers` for this task, each with problem, impact, and next
    action, and `findings` outside the task, shaped as `findings.md` describes;
    use `none` when both are empty.

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

@@ -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
@@ -61,8 +62,9 @@ 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, authoritative paths, relevant decisions, file ownership, verification
-requirements, and concise return expectations. Parallel workers need disjoint
+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
@@ -70,7 +72,8 @@ 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
 
@@ -85,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
@@ -97,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),
@@ -115,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/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,40 +38,16 @@ import {
 import {
   atomicBytes,
   atomicJson,
-  bundleLocalDocument,
   currentDesign,
   designSpecPath,
   hash,
-  inspectLocalDocumentBody,
   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,
-  validateDesignProps
-} from "./design-shared-protocol-contracts-b5f28f94.mjs";
 
 // packages/design/lib/design/frame-size.mjs
 function designFrameLabel(frame) {