openplanr 2.2641.0 → 2.2641.1

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

@@ -10,7 +10,7 @@ item in full and judges it against the default branch and the calendar.
 **Select** fits the surviving items to the stated capacity and the next release
 cut, refutes the picks with three independent lenses, and writes the sprint.
 Perform the reasoning in this session; never delegate it to a model subprocess.
-The CLI (`planr sprint …`) stores what this skill decides. It is optional: when
+The CLI (`openplanr sprint …`) stores what this skill decides. It is optional: when
 it is unavailable, write the same files by hand in the shapes given in
 [sprint formats](planr-sprint/references/sprint-formats.md).
 
@@ -33,7 +33,7 @@ capability; it never blocks the run. Name every degraded input in `Issues`.
 | Git history and the code paths items cite | Evidence lens: stale, already fixed, premise false | Buckets rest on the items' own dates; say "not verified against code" |
 | Release profile (`.release/profile.md`: cut date, cadence, freezes) | Size the In-progress bucket to the cut; the sprint gets `releaseCut` | Ask once for a horizon; default to a two-week sprint from today |
 | Capacity (engineers × working days) | Fit the list and name the overflow | Ask once; default 1 engineer × 10 days, stated in the return |
-| Previous sprint or refinement note (`.planr/sprints/SPRINT-NNN/refinement.json`) | Carry `leftovers`; `planr sprint diff` is possible | First run, no diff |
+| Previous sprint or refinement note (`.planr/sprints/SPRINT-NNN/refinement.json`) | Carry `leftovers`; `openplanr sprint diff` is possible | First run, no diff |
 | Last Operate cycle | Rank its unfinished actions alongside | Skipped silently |
 | Linear or GitHub connector | Push statuses on approval, read PR state | Local files only; report the external step as not run |
 
@@ -89,7 +89,7 @@ the cheapest refutations.
 
 Carry the previous Operate cycle's unfinished actions explicitly. Include the
 release cut itself as work; when it has no artifact yet, file it with
-`planr quick create "Release cut <date>"` so the sprint contains only artifact
+`openplanr quick create "Release cut <date>"` so the sprint contains only artifact
 ids.
 
 ## Step 4: Refute the In-progress bucket
@@ -113,9 +113,9 @@ Write the three durable outputs (formats in
 them.
 
 ```bash
-planr sprint create --data sprint.json --json                  # name, releaseCut, capacityDays, startDate
-planr sprint refinement SPRINT-NNN --data refinement.json --json # validates, stores the note and JSON, fills the sprint body
-planr sprint diff SPRINT-MMM SPRINT-NNN                          # when a previous run exists
+openplanr sprint create --data sprint.json --json                  # name, releaseCut, capacityDays, startDate
+openplanr sprint refinement SPRINT-NNN --data refinement.json --json # validates, stores the note and JSON, fills the sprint body
+openplanr sprint diff SPRINT-MMM SPRINT-NNN                          # when a previous run exists
 ```
 
 `refinement.json` must satisfy [the schema](planr-sprint/schemas/refinement.schema.json); the
@@ -130,16 +130,16 @@ write-back, or leave the proposal as written.
 ## Step 6: On approval, apply
 
 ```bash
-planr sprint apply SPRINT-NNN --dry-run          # show the status and priority changes
-planr sprint apply SPRINT-NNN --yes --commit     # one commit: chore(planr): refine backlog for SPRINT-NNN
+openplanr sprint apply SPRINT-NNN --dry-run          # show the status and priority changes
+openplanr sprint apply SPRINT-NNN --yes --commit     # one commit: chore(planr): refine backlog for SPRINT-NNN
 ```
 
 Where a connector is configured, push each changed item afterwards
-(`planr linear push <id>`, `planr github push <id>`) and report the ones that
+(`openplanr linear push <id>`, `openplanr github push <id>`) and report the ones that
 were not pushed. When the CLI is unavailable, apply the same status changes with
 the repository's own vocabulary and commit them with the same message.
 
-Close a finished sprint with `planr sprint close SPRINT-NNN`; it records the
+Close a finished sprint with `openplanr sprint close SPRINT-NNN`; it records the
 leftovers the next run carries.
 
 ## Rules from production use
@@ -151,7 +151,7 @@ leftovers the next run carries.
   the question that unblocks them.
 - The list must fit the stated capacity; if it does not, say what was cut.
 - No new migration in a hand deploy unless the sprint says so explicitly.
-- Use the repository's own status vocabulary (`planr update --help` lists it);
+- Use the repository's own status vocabulary (`openplanr update --help` lists it);
   never introduce a second one.
 - The note and the JSON are the durable output; the chat return is a view of
   them. That is what keeps the third run from re-arguing the first two.
@@ -178,7 +178,7 @@ and identify incomplete evidence or blocked inputs with their recovery action.
 The note and JSON remain complete and unchanged in shape. Omit empty chat sections;
 different summary wording never causes another sprint creation or write-back.
 
-`planr status` shows the active sprint with its cut and progress; the dashboard
+`openplanr status` shows the active sprint with its cut and progress; the dashboard
 (`planr-dashboard`) renders the sprint from the same frontmatter and checkboxes.
 
 ## Reference files

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

@@ -7,7 +7,7 @@ alwaysApply: false
 
 Inspect delivery state read-only in the active session. Read the repository's
 planning artifacts, task statuses, dependency graph, current branch, and relevant
-runtime markers directly. Use the optional deterministic `planr status --json`
+runtime markers directly. Use the optional deterministic `openplanr status --json`
 utility when available, but do not require it or a semantic subprocess.
 
 Add GitHub or Linear lookups only when the user requests live remote state. Keep

package/lib/host-packages/cursor/openplanr/rules/planr-sync/scripts/names.mjs

@@ -0,0 +1,8 @@
+// @ts-check
+// The planning folder and command names that every package and generated copy reads.
+
+/** @type {typeof import('./names.d.mts').PLANNING_FOLDER} */
+export const PLANNING_FOLDER = '.planr';
+
+/** @type {typeof import('./names.d.mts').CLI_COMMAND} */
+export const CLI_COMMAND = 'openplanr';

package/lib/host-packages/cursor/openplanr/rules/planr-sync/scripts/sync.mjs

@@ -5,6 +5,7 @@ import { access, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { CLI_COMMAND, PLANNING_FOLDER } from './names.mjs';
 
 const execFileAsync = promisify(execFile);
 const LINEAR_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
@@ -109,7 +110,7 @@ async function readJsonInput(value, stdin) {
 }
 
 async function inspectLocal(cwd) {
-  const candidates = ['.planr/config.json', '.openplanr/config.json'];
+  const candidates = [`${PLANNING_FOLDER}/config.json`, '.openplanr/config.json'];
   const roots = [];
   for (const candidate of candidates) {
     try {
@@ -146,7 +147,7 @@ export async function runPortableSync(
   } else if (args.provider === 'linear') {
     throw new IntegrationError(
       'E_SYNC_USAGE',
-      'Linear synchronization runs through a Linear connector or the planr CLI (planr linear push, planr linear sync).',
+      `Linear synchronization runs through a Linear connector or the ${CLI_COMMAND} CLI (${CLI_COMMAND} linear push, ${CLI_COMMAND} linear sync).`,
     );
   } else {
     throw new IntegrationError(

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

@@ -14,17 +14,17 @@ Resolution order:
 
 1. use a host-native GitHub or Linear connector when available;
 2. otherwise, for GitHub, use the packaged deterministic helper;
-3. otherwise, for Linear, use the `planr linear` terminal utility when the user has
-   installed it; `planr github` and `planr sync` are optional equivalents for the rest.
+3. otherwise, for Linear, use the `openplanr linear` terminal utility when the user has
+   installed it; `openplanr github` and `openplanr sync` are optional equivalents for the rest.
 
 Linear through the CLI:
 
-- the user runs `planr linear init` in a terminal once; it prompts for a personal
+- the user runs `openplanr linear init` in a terminal once; it prompts for a personal
   access token, which the CLI stores;
-- audit with `planr linear sync --dry-run`, which reads Linear without writing;
-- before a real `planr linear sync`, ask how conflicts should resolve and pass
+- audit with `openplanr linear sync --dry-run`, which reads Linear without writing;
+- before a real `openplanr linear sync`, ask how conflicts should resolve and pass
   `--on-conflict local` or `--on-conflict linear`; without a prompt it favors Linear;
-- `planr linear push <artifact-id>` creates or updates Linear issues; preview with
+- `openplanr linear push <artifact-id>` creates or updates Linear issues; preview with
   `--dry-run`. Quick tasks and backlog items need `linear.standaloneProjectId` in the
   project config when no terminal prompt is available.
 

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

@@ -16,6 +16,12 @@ import {
   writeFileSync
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+// packages/protocol/src/names.mjs
+var PLANNING_FOLDER = ".planr";
+var CLI_COMMAND = "openplanr";
+
+// packages/artifact/lib/artifact/owner-custody.mjs
 function custodyError(message, code = "E_OWNER_CUSTODY_LOCATION") {
   return Object.assign(new Error(message), { code, status: 400 });
 }
@@ -115,6 +121,8 @@ function writeCustody(path, record, { label = "Owner" } = {}) {
 }
 
 export {
+  PLANNING_FOLDER,
+  CLI_COMMAND,
   ensurePrivateDirectory,
   readCustody,
   writeCustody

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

@@ -52,6 +52,10 @@ import {
   readJson,
   reviewDigest
 } from "./design-shared-artifact-support-dependencies-design-support-protocol-contracts-3d9b1a86.mjs";
+import {
+  CLI_COMMAND,
+  PLANNING_FOLDER
+} from "./design-owner-custody.mjs";
 import {
   planrHome
 } from "./design-runtime-home.mjs";
@@ -410,8 +414,8 @@ ${fence}`;
 var { createDesignReviewExport, serializeDesignReviewExport } = reviewExportTools();
 
 // packages/design/lib/design/review.mjs
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
-import { dirname as dirname4, join as join4, relative, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
+import { dirname as dirname4, join as join5, relative, resolve as resolve3 } from "node:path";
 
 // packages/artifact/lib/artifact/review-server.mjs
 import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from "node:fs";
@@ -1456,7 +1460,7 @@ function readReviewServerState(path) {
     throw artifactError(
       ARTIFACT_ERROR_CODES.LOOPBACK_STATE,
       "Local Studio owner state is unsafe or malformed. The original record was preserved.",
-      "Run planr doctor and recover the owner record before starting or stopping this service."
+      `Run ${CLI_COMMAND} doctor and recover the owner record before starting or stopping this service.`
     );
   }
 }
@@ -1533,6 +1537,34 @@ async function stopArtifactReviewServer(instanceId, { env = process.env, fetchIm
   return controlRequest({ state }, "/internal/v1/shutdown", { method: "POST", fetchImpl });
 }
 
+// packages/protocol/src/planning-folder.mjs
+import { existsSync as existsSync2, readdirSync as readdirSync2, statSync } from "node:fs";
+import { join as join2 } from "node:path";
+var FOREIGN_FILES = Object.freeze(["planr.config.json", "board.html"]);
+var GOAL_DIRECTORIES = Object.freeze(["tasks", "plans"]);
+var isDirectory = (path) => existsSync2(path) && statSync(path).isDirectory();
+function foreignPlanningFolderSigns(projectRoot2) {
+  const folder = join2(projectRoot2, PLANNING_FOLDER);
+  if (!isDirectory(folder) || existsSync2(join2(folder, "config.json"))) return [];
+  const signs = FOREIGN_FILES.filter((name) => existsSync2(join2(folder, name)));
+  for (const name of GOAL_DIRECTORIES) {
+    const directory = join2(folder, name);
+    if (isDirectory(directory) && readdirSync2(directory).some((entry) => entry.endsWith("-goal.md")))
+      signs.push(`*-goal.md files in ${name}`);
+  }
+  return signs;
+}
+function planningFolderConflict(projectRoot2) {
+  const signs = foreignPlanningFolderSigns(projectRoot2);
+  if (signs.length === 0) return null;
+  return Object.freeze({
+    code: "E_PLANNING_FOLDER_FOREIGN",
+    problem: `The ${PLANNING_FOLDER} folder in this project wasn't created by OpenPlanr: it has ${signs.join(", ")} and no OpenPlanr config.json. OpenPlanr wrote nothing there.`,
+    fix: `Move or rename that folder, or use ${CLI_COMMAND} in a project without it, then retry.`,
+    signs: Object.freeze(signs)
+  });
+}
+
 // packages/design/lib/design/design-plan-handoff.mjs
 var clone = (value) => JSON.parse(canonicalizeJson(value));
 function prepareDesignPlanHandoff(handoff, { subject } = {}) {
@@ -1571,7 +1603,7 @@ function prepareDesignPlanHandoff(handoff, { subject } = {}) {
 // packages/design/lib/design/implementation-handoff.mjs
 import { createHash, randomUUID } from "node:crypto";
 import {
-  existsSync as existsSync2,
+  existsSync as existsSync3,
   mkdirSync,
   readFileSync as readFileSync2,
   realpathSync,
@@ -1579,7 +1611,7 @@ import {
   rmSync as rmSync2,
   writeFileSync
 } from "node:fs";
-import { dirname as dirname2, join as join2, resolve as resolve2, sep } from "node:path";
+import { dirname as dirname2, join as join3, resolve as resolve2, sep } from "node:path";
 
 // packages/design/lib/design/implementation-handoff-markdown.mjs
 var line = (value) => String(value).replaceAll("\r\n", "\n").replaceAll("\r", "\n").trim().replaceAll("\n", " ").replace(/([\\`*_[\]<>#|])/gu, "\\$1");
@@ -1832,19 +1864,19 @@ function createRepositorySourceResolver(root) {
   };
 }
 function implementationHandoffPaths(root) {
-  const directory = join2(resolve2(root), "implementation-handoff");
+  const directory = join3(resolve2(root), "implementation-handoff");
   return Object.freeze({
     directory,
-    draftJson: join2(directory, "draft.json"),
-    draftMarkdown: join2(directory, "draft.md"),
-    journal: join2(directory, "draft-publication.json"),
-    current: join2(directory, "current.json"),
-    history: join2(directory, "versions")
+    draftJson: join3(directory, "draft.json"),
+    draftMarkdown: join3(directory, "draft.md"),
+    journal: join3(directory, "draft-publication.json"),
+    current: join3(directory, "current.json"),
+    history: join3(directory, "versions")
   });
 }
 function recoverImplementationHandoffDraft(root) {
   const paths = implementationHandoffPaths(root);
-  if (!existsSync2(paths.journal)) return false;
+  if (!existsSync3(paths.journal)) return false;
   const journal = JSON.parse(readFileSync2(paths.journal, "utf8"));
   const value = assertImplementationHandoffProjection(journal.package);
   if (journal.markdown !== value.markdown)
@@ -1857,14 +1889,14 @@ function recoverImplementationHandoffDraft(root) {
 function readImplementationHandoffDraft(root, { allowMissing = true } = {}) {
   const paths = implementationHandoffPaths(root);
   recoverImplementationHandoffDraft(root);
-  if (!existsSync2(paths.draftJson)) {
+  if (!existsSync3(paths.draftJson)) {
     if (allowMissing) return null;
     throw new Error("No implementation handoff draft exists.");
   }
   const value = assertImplementationHandoffProjection(
     JSON.parse(readFileSync2(paths.draftJson, "utf8"))
   );
-  if (!existsSync2(paths.draftMarkdown))
+  if (!existsSync3(paths.draftMarkdown))
     throw new Error("Implementation handoff Markdown is missing.");
   if (readFileSync2(paths.draftMarkdown, "utf8") !== value.markdown)
     throw new Error("Implementation handoff JSON and Markdown projections differ.");
@@ -1899,15 +1931,15 @@ function importImplementationHandoffPackage(input, { resolveSource } = {}) {
 // packages/design/lib/design/implementation-handoff-approval.mjs
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import {
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdirSync as mkdirSync2,
-  readdirSync as readdirSync2,
+  readdirSync as readdirSync3,
   readFileSync as readFileSync3,
   renameSync as renameSync2,
   rmSync as rmSync3,
   writeFileSync as writeFileSync2
 } from "node:fs";
-import { dirname as dirname3, join as join3 } from "node:path";
+import { dirname as dirname3, join as join4 } from "node:path";
 var DIGEST2 = /^sha256:[a-f0-9]{64}$/u;
 var ID = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
 var APPROVE_CAPABILITY = "design:implementation-handoff:approve";
@@ -1996,20 +2028,20 @@ function implementationHandoffApprovalPaths(root) {
   const base = implementationHandoffPaths(root);
   return Object.freeze({
     ...base,
-    events: join3(base.directory, "events"),
-    journal: join3(base.directory, "lifecycle-publication.json")
+    events: join4(base.directory, "events"),
+    journal: join4(base.directory, "lifecycle-publication.json")
   });
 }
 function archivePaths(root, value) {
-  const directory = join3(implementationHandoffPaths(root).history, packageKey(value));
+  const directory = join4(implementationHandoffPaths(root).history, packageKey(value));
   return {
     directory,
-    json: join3(directory, "handoff.json"),
-    markdown: join3(directory, "handoff.md")
+    json: join4(directory, "handoff.json"),
+    markdown: join4(directory, "handoff.md")
   };
 }
 function eventPath(root, requestId) {
-  return join3(implementationHandoffApprovalPaths(root).events, `${requestKey(requestId)}.json`);
+  return join4(implementationHandoffApprovalPaths(root).events, `${requestKey(requestId)}.json`);
 }
 function readJson2(path, fallback = void 0) {
   try {
@@ -2043,13 +2075,13 @@ function pointerFor(value, status, eventId, extra = {}) {
 }
 function writeLifecycleJournal(root, journal) {
   const paths = implementationHandoffApprovalPaths(root);
-  if (existsSync3(paths.journal)) recoverImplementationHandoffApproval(root);
+  if (existsSync4(paths.journal)) recoverImplementationHandoffApproval(root);
   atomicText2(paths.journal, jsonBytes2(journal));
   return recoverImplementationHandoffApproval(root);
 }
 function recoverImplementationHandoffApproval(root) {
   const paths = implementationHandoffApprovalPaths(root);
-  if (!existsSync3(paths.journal)) return false;
+  if (!existsSync4(paths.journal)) return false;
   const journal = readJson2(paths.journal);
   if (journal.kind !== "openplanr-design-implementation-handoff-lifecycle-publication" || journal.schemaVersion !== "1.0.0")
     throw new TypeError("The implementation handoff lifecycle journal is invalid.");
@@ -2080,16 +2112,16 @@ function readImplementationHandoffVersion(root, identity) {
 function listImplementationHandoffHistory(root) {
   recoverImplementationHandoffApproval(root);
   const directory = implementationHandoffPaths(root).history;
-  if (!existsSync3(directory)) return [];
-  return readdirSync2(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map(
-    (entry) => assertImplementationHandoffProjection(readJson2(join3(directory, entry.name, "handoff.json")))
+  if (!existsSync4(directory)) return [];
+  return readdirSync3(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map(
+    (entry) => assertImplementationHandoffProjection(readJson2(join4(directory, entry.name, "handoff.json")))
   ).sort((left, right) => left.version - right.version || left.id.localeCompare(right.id));
 }
 function readImplementationHandoffLifecycle(root) {
   recoverImplementationHandoffApproval(root);
   const paths = implementationHandoffApprovalPaths(root);
   const current = readJson2(paths.current, null);
-  const events = existsSync3(paths.events) ? readdirSync2(paths.events).filter((name) => name.endsWith(".json")).map((name) => readJson2(join3(paths.events, name))).sort(
+  const events = existsSync4(paths.events) ? readdirSync3(paths.events).filter((name) => name.endsWith(".json")).map((name) => readJson2(join4(paths.events, name))).sort(
     (left, right) => left.at.localeCompare(right.at) || left.eventId.localeCompare(right.eventId)
   ) : [];
   return Object.freeze({ current, history: listImplementationHandoffHistory(root), events });
@@ -2561,7 +2593,7 @@ function validateState(value, current) {
 function projectRoot(root) {
   let candidate = root;
   while (true) {
-    if (existsSync4(join4(candidate, ".planr")) || existsSync4(join4(candidate, ".git")))
+    if (existsSync5(join5(candidate, PLANNING_FOLDER)) || existsSync5(join5(candidate, ".git")))
       return candidate;
     const parent = dirname4(candidate);
     if (parent === candidate) return root;
@@ -2606,7 +2638,7 @@ function proposeImplementationPackage(file, env) {
       designSpecPath(current.root),
       ...(current.sourceFiles ?? []).map((path) => resolve3(current.root, path))
     ])
-  ].filter((path) => existsSync4(path));
+  ].filter((path) => existsSync5(path));
   const sources = paths.map((path, index) => {
     const logicalPath = relative(repository, path).replaceAll("\\", "/");
     const extension = logicalPath.split(".").pop()?.toLowerCase();
@@ -2652,7 +2684,10 @@ function proposeImplementationPackage(file, env) {
   };
 }
 async function persistDesignTaste(current, state) {
-  const path = join4(projectRoot(current.root), ".planr/design-system/taste.json");
+  const root = projectRoot(current.root);
+  const conflict = planningFolderConflict(root);
+  if (conflict) throw new PipelineError(conflict.code, conflict.problem, conflict.fix);
+  const path = join5(root, `${PLANNING_FOLDER}/design-system/taste.json`);
   const release = await acquireStartLock(`${path}.lock`);
   try {
     const taste = readJson(path, { designs: {} });
@@ -2693,7 +2728,7 @@ async function saveDesignState(file, { state, revision, stateVersion }) {
     throw Object.assign(new Error("The design changed. Reload before saving feedback."), {
       statusCode: 409
     });
-  const path = join4(current.root, ".design/studio-state.json");
+  const path = join5(current.root, ".design/studio-state.json");
   const release = await acquireStartLock(`${path}.lock`);
   try {
     current = currentDesign(file);
@@ -2731,7 +2766,7 @@ var readBody = async (req) => JSON.parse(await readRequestBody(req, { maxBytes:
 var readImplementationBody = async (req) => JSON.parse(await readRequestBody(req, { maxBytes: 5 * 1024 * 1024, encoding: "utf8" }));
 async function startDesignReview(file, options = {}) {
   const { root } = currentDesign(file);
-  const release = await acquireStartLock(join4(root, ".design/start.lock"));
+  const release = await acquireStartLock(join5(root, ".design/start.lock"));
   try {
     return await startDesignReviewUnlocked(file, options);
   } finally {
@@ -2752,7 +2787,7 @@ async function startDesignReviewUnlocked(file, {
   let current = currentDesign(file);
   const applyInitialView = async () => {
     if (view === void 0) return;
-    const saved = readJson(join4(current.root, ".design/studio-state.json"), {
+    const saved = readJson(join5(current.root, ".design/studio-state.json"), {
       state: {},
       stateVersion: 0
     });
@@ -2762,7 +2797,7 @@ async function startDesignReviewUnlocked(file, {
       state: { ...saved.state, view }
     });
   };
-  const stateFile = join4(current.root, ".design/server.json");
+  const stateFile = join5(current.root, ".design/server.json");
   const old = readJson(stateFile, null);
   const services = (await listArtifactReviewServers({ env, fetchImpl })).filter(
     (service) => service.kind === "design" && service.projectRoot === current.root
@@ -2839,7 +2874,7 @@ async function startDesignReviewUnlocked(file, {
       session.designRevision = current.revision;
     },
     renderDocument({ model, base }) {
-      const state = readJson(join4(current.root, ".design/studio-state.json"), {
+      const state = readJson(join5(current.root, ".design/studio-state.json"), {
         state: {}
       }).state;
       const stalePins = readDesignFeedback(file, env).pins.filter((pin) => pin.stale);
@@ -2892,7 +2927,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
           respond(res, 200, readDesignHandoff(file, { env }));
         } else if (route === "design-implementation-handoff" && req.method === "GET") {
           const design = currentDesign(file);
-          const unlock = await acquireStartLock(join4(design.root, ".design/render.lock"));
+          const unlock = await acquireStartLock(join5(design.root, ".design/render.lock"));
           try {
             const root = dirname4(designSpecPath(design.root));
             let proposal = null;
@@ -2938,7 +2973,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
             ].includes(input.action))
               throw new Error("Unknown implementation package action.");
             const initial = currentDesign(file);
-            const unlock = await acquireStartLock(join4(initial.root, ".design/render.lock"));
+            const unlock = await acquireStartLock(join5(initial.root, ".design/render.lock"));
             try {
               const design = currentDesign(file);
               const root = dirname4(designSpecPath(design.root));
@@ -3103,7 +3138,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
           else if (action === "recovery")
             result = await exportDesignShareRecovery(file, {
               ...options,
-              output: join4(
+              output: join5(
                 env.HOME ?? process.env.HOME,
                 "Downloads",
                 `openplanr-design-recovery-${Date.now()}.json`
@@ -3112,7 +3147,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
           else result = await manageDesignShare(file, action, options);
           respond(res, 200, result);
         } else if (route === "design-status" && req.method === "GET") {
-          const ready = readJson(join4(current.root, ".design/browser-ready.json"), null);
+          const ready = readJson(join5(current.root, ".design/browser-ready.json"), null);
           respond(res, 200, {
             ok: true,
             documentId: current.document.id,
@@ -3123,7 +3158,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
           });
         } else if (route === "design-state" && req.method === "GET") {
           respond(res, 200, {
-            ...readJson(join4(current.root, ".design/studio-state.json"), {
+            ...readJson(join5(current.root, ".design/studio-state.json"), {
               state: {},
               stateVersion: 0
             }),
@@ -3136,7 +3171,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
           const loadedArtifacts = new Set(Array.isArray(value?.artifacts) ? value.artifacts : []);
           if (value.revision !== current.revision || value.status !== "ready" || !Array.isArray(value.artifacts) || value.artifacts.length === 0 || loadedArtifacts.size !== value.artifacts.length || value.artifacts.some((id) => !current.entries.some((entry) => entry.artifactId === id)))
             throw new Error("Browser readiness must identify loaded design artboards.");
-          atomicJson(join4(current.root, ".design/browser-ready.json"), {
+          atomicJson(join5(current.root, ".design/browser-ready.json"), {
             status: "ready",
             revision: current.revision,
             artifacts: value.artifacts,
@@ -3145,7 +3180,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
           });
           respond(res, 200, { ok: true });
         } else if (route === "design-export" && req.method === "GET") {
-          const state = readJson(join4(current.root, ".design/studio-state.json"), {
+          const state = readJson(join5(current.root, ".design/studio-state.json"), {
             state: {}
           }).state;
           res.writeHead(200, {
@@ -3269,8 +3304,8 @@ async function resolveDesignPins(file, { pinIds, summary, env = process.env }) {
         "One or more requested pins do not exist."
       );
     writeArtifactReviewState(path, createReviewLedger({ ...ledger, reviews: revisions }));
-    const history = readJson(join4(current.root, ".design/review-history.json"), []);
-    atomicJson(join4(current.root, ".design/review-history.json"), [
+    const history = readJson(join5(current.root, ".design/review-history.json"), []);
+    atomicJson(join5(current.root, ".design/review-history.json"), [
       ...history,
       {
         revision: current.revision,

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

@@ -20,6 +20,7 @@ import {
   createChunkedWorkspaceClient
 } from "./design-chunked-workspace-client.mjs";
 import {
+  PLANNING_FOLDER,
   ensurePrivateDirectory,
   readCustody,
   writeCustody
@@ -80,7 +81,7 @@ function custodyLocation(file, options = {}, { allowMissing = false } = {}) {
   const root = resolve(options.custodyRoot ?? join(planrHome(env), "design-shares"));
   let project = current.root;
   for (let candidate = current.root; dirname(candidate) !== candidate; candidate = dirname(candidate)) {
-    if (existsSync(join(candidate, ".git")) || existsSync(join(candidate, ".planr"))) {
+    if (existsSync(join(candidate, ".git")) || existsSync(join(candidate, PLANNING_FOLDER))) {
       project = candidate;
       break;
     }
@@ -684,7 +685,7 @@ function inside(base, candidate) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
 }
 function parseablePlanrConfig(root) {
-  const path = join2(root, ".planr", "config.json");
+  const path = join2(root, PLANNING_FOLDER, "config.json");
   if (!existsSync3(path)) return false;
   try {
     if (lstatSync2(path).isSymbolicLink()) return false;
@@ -813,7 +814,11 @@ function resolveArtifactReviewDestination({
   }
   const projectRoot = findArtifactProjectRoot(cwd, { env });
   if (projectRoot) {
-    const directory2 = assertSafeDestination(projectRoot, [".planr", "artifacts", artifactId]);
+    const directory2 = assertSafeDestination(projectRoot, [
+      PLANNING_FOLDER,
+      "artifacts",
+      artifactId
+    ]);
     return Object.freeze({
       kind: "project",
       artifactId,
@@ -1799,7 +1804,7 @@ async function importDesignShareRecovery(file, { input, ...options } = {}) {
       const pending = custody.pendingCreate ?? custody.pendingMutation.body;
       const destination = join3(root, "uploads", custody.id, pending.operationId);
       if (existsSync4(destination)) {
-        const { spoolChunkReader: spoolChunkReader2 } = await import("./design-runtime-support-5cb7531bede8.mjs");
+        const { spoolChunkReader: spoolChunkReader2 } = await import("./design-runtime-support-336900df0d39.mjs");
         const reader = spoolChunkReader2(destination, pending);
         for (const part of pending.manifest.chunks) await reader(part.index);
       } else await copyUploadSpool(custody, destination);

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

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/design",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "private": true,
   "type": "module",
   "description": "Canonical OpenPlanr design helpers and design-loop engine",
@@ -46,8 +46,8 @@
     "node": ">=20.19.0"
   },
   "dependencies": {
-    "@openplanr/artifact": "0.6.3",
-    "@openplanr/protocol": "0.10.1"
+    "@openplanr/artifact": "0.6.4",
+    "@openplanr/protocol": "0.10.2"
   },
   "scripts": {
     "test": "node --test --test-concurrency=2 tests/*.test.mjs",

package/lib/host-packages/cursor/openplanr/runtime/design/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",
@@ -27,6 +27,14 @@
       "types": "./src/semver.d.mts",
       "import": "./src/semver.mjs"
     },
+    "./names": {
+      "types": "./src/names.d.mts",
+      "import": "./src/names.mjs"
+    },
+    "./planning-folder": {
+      "types": "./src/planning-folder.d.mts",
+      "import": "./src/planning-folder.mjs"
+    },
     "./contracts": {
       "types": "./src/contracts.d.mts",
       "import": "./src/contracts.mjs"