openplanr 2.2641.0 → 2.2641.2

package/lib/host-packages/cursor/openplanr/rules/planr-sync/references/tracker-connections.md

@@ -0,0 +1,70 @@
+# GitHub and Linear connections
+
+These skills store and read no GitHub or Linear credentials. Remote steps run through a
+connection the host already has; the planning files stay the source of truth.
+
+## Use the host's connection
+
+- **Linear:** the host's Linear connection, whose tools read, create and update issues.
+- **GitHub:** the host's GitHub connection, or the GitHub CLI when
+  `gh auth status --hostname github.com` succeeds.
+
+Never ask the user for a token, read one from the environment or a file, or put one in a
+command, URL or file.
+
+## When a connection is missing
+
+Finish the local work first. Then report the remote step as not run and give the one
+line for the current host:
+
+| Host | Linear | GitHub |
+| --- | --- | --- |
+| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
+| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+
+Ask the user to try again once connected; never retry the remote step on your own.
+
+## Status mapping
+
+| Local status | Linear workflow state | GitHub issue |
+| --- | --- | --- |
+| `planning`, `pending` | Unstarted (for example Todo) | open |
+| `in-progress` | Started (for example In Progress) | open |
+| `done` | Completed (for example Done) | closed |
+| Backlog `open` | Backlog, else Unstarted | open |
+| Backlog `closed` | Completed | closed |
+| Backlog `promoted` | Leave as it is | Leave as it is |
+
+When reading state back, write only a status the item's type allows. A backlog item takes
+`open` or `closed` and keeps `promoted`.
+
+- Linear Completed or Canceled sets `done`, or `closed` for a backlog item. Started sets
+  `in-progress`, and Triage, Backlog or Unstarted sets `planning` for features and stories
+  and `pending` for quick tasks; a backlog item takes `open` from any of these. Epics and
+  task files keep their status.
+- A closed GitHub issue sets `done`, or `closed` for a backlog item. An open issue sets
+  `in-progress` for a `done` item and `open` for a `closed` backlog item; other statuses
+  stay as they are.
+
+## Links
+
+A linked item records its tracker identity in frontmatter. Update a linked item through
+that identity instead of creating another, and record the identity of everything you
+create.
+
+- **GitHub:** each item is one issue, recorded as `githubIssue`.
+- **Linear:** use the shapes the OpenPlanr CLI uses, so its later pushes reuse what you
+  create:
+  - An epic is a Linear project (`linearProjectId`, `linearProjectIdentifier`,
+    `linearProjectUrl`). When its `linearMappingStrategy` is `milestone-of` or `label-on`,
+    it is a milestone in an existing project (`linearMilestoneId`) or a team label
+    (`linearLabelId`) instead, and every issue under it carries that milestone
+    (`linearProjectMilestoneId`) or label (`linearLabelIds`).
+  - A feature, quick task or backlog item is one issue (`linearIssueId`,
+    `linearIssueIdentifier`, `linearIssueUrl`). A story is a sub-issue of its feature's
+    issue (`linearParentIssueId`).
+  - All task files of one feature share one task-list issue: a sub-issue of the feature's
+    issue whose checklist merges every task file, recorded in each task file. Its state is
+    Completed when every task file is `done`, Unstarted when every one is `pending`, and
+    Started otherwise.

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 { 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 the host's Linear connection.",
     );
   } else {
     throw new IntegrationError(

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

@@ -6,31 +6,22 @@ alwaysApply: false
 # OpenPlanr Sync
 
 Reconcile local planning artifacts and, when requested, GitHub or Linear state.
-Reason about conflicts in this active session; deterministic mapping and GitHub
-transport may use a host connector or the packaged [sync helper](planr-sync/scripts/sync.mjs).
-Local and GitHub work never require the OpenPlanr CLI.
+Reason about conflicts in this active session. Local and GitHub work never require
+the OpenPlanr CLI.
 
-Resolution order:
+Remote steps run through the host's own connections, as described in
+[tracker connections](planr-sync/references/tracker-connections.md), which also holds the status
+mapping and what to tell the user when a connection is missing:
 
-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.
-
-Linear through the CLI:
-
-- the user runs `planr 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
-  `--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
-  `--dry-run`. Quick tasks and backlog items need `linear.standaloneProjectId` in the
-  project config when no terminal prompt is available.
+- GitHub: the host's GitHub connection, or, when the GitHub CLI is signed in, the
+  packaged [sync helper](planr-sync/scripts/sync.mjs), which creates and edits issues through `gh`;
+  close or reopen an issue with `gh issue close` or `gh issue reopen`. `openplanr github`
+  is an optional equivalent; `openplanr sync` only repairs local cross-references.
+- Linear: the host's Linear connection.
 
 Audit is read-only by default. Apply local changes only when the request asks for
 reconciliation, and push remote changes only when the request asks for external
-synchronization. If credentials are unavailable, complete local reconciliation
+synchronization. If a connection is unavailable, complete local reconciliation
 and report only the external step that could not run.
 
 ## Return

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";
@@ -420,8 +424,12 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 var here = dirname(fileURLToPath(new URL("./runtime/packages/artifact/lib/artifact/review-server.mjs", import.meta.url).href));
 var STAGE_RUNTIME_PATH = join(here, "..", "..", "templates", "artifact-review-stage.js");
-var ARTIFACT_REVIEW_SERVER_VERSION = 2;
+var ARTIFACT_REVIEW_SERVER_VERSION = 3;
 var ARTIFACT_REVIEW_SERVER_KIND = "artifact-review";
+var CONTROL_HEADER = "x-openplanr-control";
+var CONTROLLABLE_SERVER_VERSIONS = /* @__PURE__ */ new Set([2, ARTIFACT_REVIEW_SERVER_VERSION]);
+var EXPORT_ONLY_SERVER_VERSIONS = /* @__PURE__ */ new Set([1]);
+var AUTHORIZATION_CONTROL_VERSIONS = /* @__PURE__ */ new Set([1, 2]);
 var CONTROL_WINDOW_BYTES = 64 * 1024 * 1024;
 var ARTIFACT_REVIEW_MAX_CONTROL_BYTES = Math.ceil((MAX_ARTIFACT_HTML_BYTES * 2 + ARTIFACT_REVIEW_MAX_STATE_BYTES) / CONTROL_WINDOW_BYTES) * CONTROL_WINDOW_BYTES;
 var ARTIFACT_REVIEW_MAX_STATE_BYTES2 = ARTIFACT_REVIEW_MAX_STATE_BYTES;
@@ -477,6 +485,12 @@ var PERMISSIONS_POLICY = [
 function artifactError(code, message, fix = "", details) {
   return new PipelineError(code, message, fix, details);
 }
+function artifactReviewControlHeaders(controlToken) {
+  return { [CONTROL_HEADER]: controlToken };
+}
+function stateControlHeaders(state) {
+  return AUTHORIZATION_CONTROL_VERSIONS.has(state.serverVersion) ? { authorization: `Bearer ${state.controlToken}` } : artifactReviewControlHeaders(state.controlToken);
+}
 function reviewStateDir(env = process.env) {
   return join(planrHome(env), "artifact-daemon");
 }
@@ -559,9 +573,9 @@ function parseRequestPath(rawUrl) {
   });
   return { segments, trailingSlash };
 }
-function bearerToken(req) {
-  const value = req.headers?.authorization;
-  return typeof value === "string" && value.startsWith("Bearer ") ? value.slice(7) : "";
+function presentedControlToken(req) {
+  const value = req.headers?.[CONTROL_HEADER];
+  return typeof value === "string" ? value : "";
 }
 function cloneAndValidateEnvelope(envelope) {
   let cloned;
@@ -871,7 +885,7 @@ function createArtifactReviewServer({
         return;
       }
       if (internal) {
-        if (!timingSafeTokenEqual(bearerToken(req), controlToken)) {
+        if (!timingSafeTokenEqual(presentedControlToken(req), controlToken)) {
           sendJson(res, 403, { ok: false, error: "forbidden" });
           return;
         }
@@ -1445,7 +1459,7 @@ function createArtifactReviewServer({
   return controller;
 }
 function validState(value, requestedPort, { allowLegacy = false } = {}) {
-  return value?.schemaVersion === "1.0.0" && value.kind === ARTIFACT_REVIEW_SERVER_KIND && (value.serverVersion === ARTIFACT_REVIEW_SERVER_VERSION || allowLegacy && value.serverVersion === 1) && Number.isInteger(value.pid) && value.pid > 0 && Number.isInteger(value.port) && value.port > 0 && value.port <= 65535 && (requestedPort === 0 || value.port === requestedPort) && isCapabilityToken(value.instanceId, { bytes: SESSION_ID_BYTES }) && isCapabilityToken(value.controlToken, { bytes: CONTROL_TOKEN_BYTES });
+  return value?.schemaVersion === "1.0.0" && value.kind === ARTIFACT_REVIEW_SERVER_KIND && (CONTROLLABLE_SERVER_VERSIONS.has(value.serverVersion) || allowLegacy && EXPORT_ONLY_SERVER_VERSIONS.has(value.serverVersion)) && Number.isInteger(value.pid) && value.pid > 0 && Number.isInteger(value.port) && value.port > 0 && value.port <= 65535 && (requestedPort === 0 || value.port === requestedPort) && isCapabilityToken(value.instanceId, { bytes: SESSION_ID_BYTES }) && isCapabilityToken(value.controlToken, { bytes: CONTROL_TOKEN_BYTES });
 }
 function readReviewServerState(path) {
   try {
@@ -1456,7 +1470,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.`
     );
   }
 }
@@ -1469,7 +1483,7 @@ async function controlRequest(descriptor, path, { method, body, fetchImpl } = {}
   const response = await fetchImpl(`http://${LOOPBACK_HOST}:${descriptor.state.port}${path}`, {
     method,
     headers: {
-      authorization: `Bearer ${descriptor.state.controlToken}`,
+      ...stateControlHeaders(descriptor.state),
       ...body === void 0 ? {} : { "content-type": "application/json" }
     },
     ...body === void 0 ? {} : { body: JSON.stringify(body) },
@@ -1533,6 +1547,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 +1613,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 +1621,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 +1874,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 +1899,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 +1941,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 +2038,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 +2085,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 +2122,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 +2603,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 +2648,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 +2694,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 +2738,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 +2776,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 +2797,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 +2807,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
@@ -2817,7 +2862,12 @@ async function startDesignReviewUnlocked(file, {
   server = createArtifactReviewServer({
     env,
     serverMetadata: { kind: "design", projectRoot: current.root },
-    prepareSource: (options) => prepareArtifactDocument({ ...options, allowLocalForms: true }),
+    prepareSource: (options) => prepareArtifactDocument({
+      ...options,
+      allowLocalForms: true,
+      prototypeState: true,
+      screenId: current.entries.find((entry) => entry.artifactId === options.artifactId)?.screenId ?? options.artifactId
+    }),
     async refreshSession(session) {
       current = currentDesign(file);
       if (session.designRevision === current.revision) return;
@@ -2839,7 +2889,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 +2942,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 +2988,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 +3153,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 +3162,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 +3173,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 +3186,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 +3195,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, {
@@ -3179,7 +3229,7 @@ ${renderArtifactParentRuntime({ ...options, adapterRuntimeUrl: `${base}api/desig
     const registered = await fetchImpl(`${origin}/internal/v1/sessions`, {
       method: "POST",
       headers: {
-        authorization: `Bearer ${server.controlToken}`,
+        ...artifactReviewControlHeaders(server.controlToken),
         "content-type": "application/json"
       },
       body: JSON.stringify({
@@ -3269,8 +3319,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,