openplanr 2.2641.1 → 3.0.0

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

@@ -0,0 +1,167 @@
+// Credential classification for delegated context. Findings never carry the matched value.
+import { createHash } from 'node:crypto';
+
+/**
+ * Recognizable credential formats; rejected everywhere, including tests and placeholders.
+ * Case-sensitive: each prefix has a fixed case, and `github_pat_` and `sk-` bodies need an
+ * uppercase letter or digit.
+ */
+export const CREDENTIAL_FORMAT =
+  /-----BEGIN (?:[A-Z ]* )?PRIVATE KEY(?: BLOCK)?-----|"private_key"\s*:\s*"-----BEGIN|(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}\b|(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{20,}(?![A-Za-z0-9])|(?<![A-Za-z0-9])github_pat_(?=[A-Za-z0-9_]*[A-Z0-9])[A-Za-z0-9_]{20,}\b|(?<![A-Za-z0-9])sk-(?:proj-)?(?=[A-Za-z0-9_-]*[A-Z0-9])[A-Za-z0-9_-]{24,}\b|(?<![A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{20,}/u;
+
+// `word` is the credential word findings report as `key`; the rest of a name may hold a value.
+const CREDENTIAL_NAME =
+  '(?<name>(?:[A-Za-z_][A-Za-z0-9_-]*?)?(?<word>API[_-]?KEY|ACCESS[_-]?TOKEN|AUTH[_-]?TOKEN|CLIENT[_-]?SECRET|PRIVATE[_-]?KEY|PASSWORD|TOKEN|SECRET(?:[_-]?KEY)?))';
+const QUOTED_ASSIGNMENT = new RegExp(
+  `(?:^|[^A-Za-z0-9_])${CREDENTIAL_NAME}["']?\\s*[:=]\\s*(?<quote>["'\`])(?<value>(?:(?!\\k<quote>|\\$\\{)[^\\r\\n\\\\]|\\\\.){16,})\\k<quote>`,
+  'giu',
+);
+const UNQUOTED_ASSIGNMENT = new RegExp(
+  `^[ \\t]*(?<exported>export[ \\t]+)?${CREDENTIAL_NAME}(?<before>[ \\t]*)(?<operator>[:=])(?<after>[ \\t]*)(?!process\\.env(?:\\.|\\[)|import\\.meta\\.env(?:\\.|\\[)|Deno\\.env\\.|os\\.environ|env\\.)(?<value>[^\\s"'\`#()\\[\\]{}$]{16,})[ \\t]*(?:#[^\\r\\n]*)?\\r?$`,
+  'gimu',
+);
+const PLACEHOLDER =
+  /^(?:example(?:[-_].*)?|placeholder(?:[-_].*)?|your[-_].*|(?:change|replace)[-_]me(?:[-_].*)?|(?:dummy|fake|mock|test|never[-_]return)[-_](?:api[-_]?key|access[-_]?token|auth[-_]?token|client[-_]?secret|password|token|secret(?:[-_]?key)?))$/iu;
+// A lowercase marker followed only by words and short numbers, one of them a credential noun.
+const DESCRIBED_PLACEHOLDER =
+  /^(?:dummy|fake|mock|test|fixture|synthetic|never[-_]return)(?:[-_. ](?:[a-z]+|\d{1,4}))+[-_.]?$/u;
+const CREDENTIAL_NOUN = /[-_. ](?:secret|key|token|password|credential)s?(?=[-_. ]|$)/u;
+const SHELL_NAME = /^[A-Z][A-Z0-9_]*$/u;
+const IDENTIFIER_WORD = /[A-Z]{2,}(?![a-z])\d{0,2}|[A-Z]?[a-z]+\d{0,2}|[A-Z]\d{0,2}|\d{1,2}/gu;
+
+const CODE_EXTENSIONS = new Set(
+  'c cc cjs cpp cs cts dart go groovy h hpp java js jsx kt kts lua m mjs mm mts php py rb rs scala svelte swift ts tsx vue'.split(
+    ' ',
+  ),
+);
+const CONFIG_EXTENSIONS = new Set(
+  'bash cfg conf env fish hcl ini json json5 jsonc properties ps1 sh tf toml xml yaml yml zsh'.split(
+    ' ',
+  ),
+);
+const CONFIG_NAMES = new Set(['dockerfile', 'makefile', 'procfile']);
+
+/** The syntax that decides whether an unquoted value is a literal: code, config, or free text. */
+export function credentialSyntax(path) {
+  if (typeof path !== 'string' || !path) return 'text';
+  const name = path.split('/').at(-1).toLowerCase();
+  if (CONFIG_NAMES.has(name) || name.startsWith('.env')) return 'config';
+  const extension = name.includes('.') ? name.split('.').at(-1) : '';
+  if (CODE_EXTENSIONS.has(extension)) return 'code';
+  if (CONFIG_EXTENSIONS.has(extension)) return 'config';
+  return 'text';
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function position(content, index) {
+  const before = content.slice(0, index);
+  return { line: before.split('\n').length, column: index - before.lastIndexOf('\n') };
+}
+
+// Reads like a code identifier: whole words, digits only at word ends, at most one one-letter word.
+function codeIdentifier(value) {
+  if (!/^[A-Za-z_$][\w$]*$/u.test(value) || value.length > 64) return false;
+  let singleLetters = 0;
+  for (const part of value.split(/[_$]+/u).filter(Boolean)) {
+    const words = part.match(IDENTIFIER_WORD) ?? [];
+    if (words.join('') !== part) return false;
+    singleLetters += words.filter((word) => word.replace(/\d+$/u, '').length <= 1).length;
+  }
+  return singleLetters <= 1;
+}
+
+function memberPath(value) {
+  const segments = value.replace(/!$/u, '').split(/[!?]?\./u);
+  return segments.length > 1 && segments.every(codeIdentifier);
+}
+
+// An unquoted value is a literal unless its syntax makes it a reference, type or expression.
+// Multi-line strings in code read like text, so an unterminated identifier stays a literal.
+function unquotedLiteral(raw, operator, syntax) {
+  if (syntax === 'config' || (syntax === 'text' && operator === '=')) return true;
+  const terminated = /[;,]$/u.test(raw);
+  const value = terminated ? raw.slice(0, -1) : raw;
+  if (memberPath(value)) return !(terminated || syntax === 'code');
+  return !(terminated && codeIdentifier(value));
+}
+
+// `export NAME=` is a shell line in any file, and so is an uppercase `NAME=value` without spaces
+// unless it ends in `,` like a keyword argument.
+function shellAssignment({ exported, name, before, operator, after, value }) {
+  if (exported) return true;
+  return operator === '=' && !before && !after && SHELL_NAME.test(name) && !value.endsWith(',');
+}
+
+function placeholder(value) {
+  return (
+    PLACEHOLDER.test(value) || (DESCRIBED_PLACEHOLDER.test(value) && CREDENTIAL_NOUN.test(value))
+  );
+}
+
+/**
+ * Classifies credential material in `bytes` from `origin` ({ path?, label?, syntax?, resolvable? }).
+ * Findings report location, rule, classification, confidence and explanation, never values.
+ * `resolvable: false` marks text that no resolution can admit, such as a correction.
+ */
+export function classifyCredentials(bytes, origin = {}) {
+  const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes), 'utf8');
+  const content = buffer.toString('utf8');
+  const label = origin.label ?? origin.path ?? 'text';
+  const syntax = origin.syntax ?? credentialSyntax(origin.path);
+  const resolvable = origin.resolvable !== false;
+  const findings = [];
+  const add = (rule, index, key, details) => {
+    const { line, column } = position(content, index);
+    findings.push({
+      id: `cred_${sha256(`${label}\n${rule}\n${line}:${column}\n${key ?? ''}`).slice(0, 16)}`,
+      rule,
+      ...details,
+      location: { ...(origin.path ? { path: origin.path } : {}), line, column },
+      ...(key ? { key } : {}),
+    });
+  };
+  for (const match of content.matchAll(new RegExp(CREDENTIAL_FORMAT.source, 'gu')))
+    add('credential-format', match.index, null, {
+      classification: 'credential',
+      confidence: 'high',
+      resolvable: false,
+      explanation:
+        'A recognizable credential or private key format cannot be delegated; remove it from the source.',
+    });
+  const literal = ({ index, 0: text, groups: { name, word } }) =>
+    add('credential-assignment', index + text.indexOf(name), word, {
+      classification: 'possible-credential',
+      confidence: 'medium',
+      resolvable,
+      explanation: `${word} is assigned a literal that is neither a reference nor a recognized placeholder; ${resolvable ? 'resolve this finding only if the value is not a credential' : 'remove the value or replace it with a reference'}.`,
+    });
+  for (const match of content.matchAll(QUOTED_ASSIGNMENT))
+    if (!placeholder(match.groups.value)) literal(match);
+  for (const match of content.matchAll(UNQUOTED_ASSIGNMENT)) {
+    const { operator, value } = match.groups;
+    const lineSyntax = shellAssignment(match.groups) ? 'config' : syntax;
+    if (unquotedLiteral(value, operator, lineSyntax) && !placeholder(value.replace(/[;,]$/u, '')))
+      literal(match);
+  }
+  return { contentDigest: `sha256:${sha256(buffer)}`, syntax, findings };
+}
+
+/**
+ * Splits findings into those an explicit resolution covers and the rest. A resolution names one
+ * resolvable finding and the exact content digest it was recorded for; changed bytes invalidate it.
+ */
+export function resolveFindings(classification, resolutions = []) {
+  const accepted = new Set(
+    resolutions
+      .filter((resolution) => resolution?.contentDigest === classification.contentDigest)
+      .map((resolution) => resolution.id),
+  );
+  const applied = [];
+  const remaining = [];
+  for (const finding of classification.findings)
+    (finding.resolvable && accepted.has(finding.id) ? applied : remaining).push(finding);
+  return { applied, remaining };
+}

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

@@ -39,7 +39,7 @@ export function preparationPresentation(preview) {
   return {
     phase: 'preview',
     headline: `${taskLabel(preview.selector)} is ready for review before dispatch.`,
-    context: `${preview.inventory.length} copied file(s); ${preview.omissions.length} omission(s).`,
+    context: `${preview.inventory.length} copied file(s); ${preview.omissions.length} omission(s); ${preview.credentialResolutions?.length ?? 0} accepted credential resolution(s).`,
     writableRepository: preview.writableRepository,
     worktreePath: preview.worktreePath,
     selectedPaths: preview.selectedPaths,
@@ -49,6 +49,7 @@ export function preparationPresentation(preview) {
       : 'Legacy run has no recorded integration scope; supply explicit paths at review. The worktree is not a filesystem sandbox.',
     inventory: preview.inventory,
     omissions: preview.omissions,
+    credentialResolutions: preview.credentialResolutions ?? [],
     blockers: preview.blockers ?? [],
     planning: preview.planning ?? null,
     helper: preview.helper ?? null,
@@ -61,7 +62,7 @@ export function preparationPresentation(preview) {
     destination: preview.destination,
     ...(preview.executionPolicy ? { executionPolicy: preview.executionPolicy } : {}),
     nextAction:
-      'Review required sources, optional omissions, planning location, integration scope, and destination before dispatch.',
+      'Review required sources, optional omissions, accepted credential resolutions, planning location, integration scope, and destination before dispatch.',
   };
 }
 

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-contract.mjs

@@ -2,6 +2,7 @@
 import { createHash } from 'node:crypto';
 import { isAbsolute, sep } from 'node:path';
 import { assertCredentialFreeText } from './context.mjs';
+import { CREDENTIAL_FORMAT } from './credentials.mjs';
 import { updateRunRecord } from './run-record.mjs';
 
 const MAX_HANDOFF_TEXT = 4096;
@@ -16,9 +17,6 @@ export const SHA256 = /^[a-f0-9]{64}$/u;
 
 const RESULT_STATES = new Set(['completed', 'blocked', 'question']);
 
-const CREDENTIAL =
-  /-----BEGIN (?:[A-Z ]* )?PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\bgh[pousr]_[A-Za-z0-9_]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b|\bxox[baprs]-[A-Za-z0-9-]{20,}/iu;
-
 export class DelegateRunError extends Error {
   constructor(code, message, runId = null, details = null) {
     super(message);
@@ -68,7 +66,7 @@ export function boundedText(value, label) {
     typeof value !== 'string' ||
     !value.trim() ||
     Buffer.byteLength(value, 'utf8') > MAX_HANDOFF_TEXT ||
-    CREDENTIAL.test(value)
+    CREDENTIAL_FORMAT.test(value)
   ) {
     throw new DelegateRunError(
       'E_DELEGATE_INPUT',
@@ -152,7 +150,7 @@ function validQuestion(question) {
     typeof question.text !== 'string' ||
     !question.text.trim() ||
     Buffer.byteLength(question.text, 'utf8') > MAX_HANDOFF_TEXT ||
-    CREDENTIAL.test(question.text) ||
+    CREDENTIAL_FORMAT.test(question.text) ||
     (question.options !== undefined &&
       (!Array.isArray(question.options) ||
         question.options.length > 12 ||
@@ -160,7 +158,7 @@ function validQuestion(question) {
           (option) =>
             typeof option !== 'string' ||
             Buffer.byteLength(option, 'utf8') > 256 ||
-            CREDENTIAL.test(option),
+            CREDENTIAL_FORMAT.test(option),
         )))
   )
     return false;
@@ -181,7 +179,7 @@ export function resultShape(result, expectedSessionId = null) {
   ) {
     return null;
   }
-  if (CREDENTIAL.test(result.summary)) return null;
+  if (CREDENTIAL_FORMAT.test(result.summary)) return null;
   if (result.status === 'blocked' && !result.summary.trim()) return null;
   if (result.status === 'question' && !validQuestion(result.question)) return null;
   if (

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-preparation.mjs

@@ -58,7 +58,7 @@ async function inspectWorktreeDependencies(worktreePath) {
 }
 
 export async function probeDelegateHost({ repositoryRoot, env = process.env } = {}) {
-  const nodeReady = Number(process.versions.node.split('.')[0]) >= 20;
+  const nodeReady = Number(process.versions.node.split('.')[0]) >= 22;
   const options = {
     env: { PATH: env.PATH, HOME: env.HOME, USER: env.USER, TMPDIR: env.TMPDIR },
     cwd: repositoryRoot,
@@ -128,7 +128,7 @@ export async function probeDelegateHost({ repositoryRoot, env = process.env } =
   }
   return {
     ready: nodeReady && gitReady,
-    node: { ready: nodeReady, minimumMajor: 20 },
+    node: { ready: nodeReady, minimumMajor: 22 },
     git: { ready: gitReady, ...(gitDiagnostic ? { diagnostic: gitDiagnostic } : {}) },
     repository,
     engines,
@@ -143,6 +143,7 @@ export async function prepareDelegateRun({
   selectedFiles = [],
   optionalFiles = [],
   readOnlyRepositories = [],
+  credentialResolutions = [],
   selectedPaths,
   scopePaths,
   preservePaths = [],
@@ -166,7 +167,7 @@ export async function prepareDelegateRun({
   if (!host.ready || !host.repository?.ready)
     throw new DelegateRunError(
       'E_DELEGATE_PREREQUISITE',
-      'Node 20+, Git, and a repository with a commit are required before task collection.',
+      'Node 22+, Git, and a repository with a commit are required before task collection.',
       null,
       host,
     );
@@ -199,6 +200,7 @@ export async function prepareDelegateRun({
     selectedFiles,
     optionalFiles,
     readOnlyRepositories,
+    credentialResolutions,
   });
   const integrationScopePaths = scopePaths === undefined ? null : integrationPaths(scopePaths);
   let identity = profileIdentity(prepared);

package/lib/host-packages/cursor/openplanr/rules/planr-delegate/scripts/run-record.mjs

@@ -14,6 +14,7 @@ import {
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
+import { CREDENTIAL_FORMAT } from './credentials.mjs';
 import { captureFileState } from './custody.mjs';
 
 export const RUN_RECORD_SCHEMA_VERSION = '2.0.0';
@@ -21,8 +22,6 @@ export const MAX_RUN_RECORD_BYTES = 64 * 1024;
 export const CLOSED_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
 const RUN_ID = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$/u;
-const CREDENTIAL =
-  /-----BEGIN (?:[A-Z ]* )?PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\bgh[pousr]_[A-Za-z0-9_]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b|\bxox[baprs]-[A-Za-z0-9-]{20,}/iu;
 
 const execute = promisify(execFile);
 
@@ -74,7 +73,7 @@ function encoded(record) {
   if (bytes.length > MAX_RUN_RECORD_BYTES) {
     throw new RunRecordError('E_RUN_LIMIT', 'Delegated run record exceeds its private size limit.');
   }
-  if (CREDENTIAL.test(bytes.toString('utf8'))) {
+  if (CREDENTIAL_FORMAT.test(bytes.toString('utf8'))) {
     throw new RunRecordError('E_RUN_CREDENTIAL', 'Credential material cannot enter a run record.');
   }
   return bytes;

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

@@ -15,7 +15,7 @@ Ordinary implementation remains with `planr-ship`.
 Resolve [runner.mjs](planr-delegate/scripts/runner.mjs) from this installed skill. Call it through
 Node as `node <installed-skill>/scripts/runner.mjs <action>`, with one JSON object
 on stdin. Alternatively, include `action` in that object and omit the command-line
-action; conflicting actions are rejected. `probe` discovers Node 20+, Git, installed
+action; conflicting actions are rejected. `probe` discovers Node 22+, Git, installed
 CLIs and optional profiles; an OpenPlanr checkout or public CLI command is not
 needed. Reuse normal signed-in authentication. Preserve selection precedence:
 explicit engine/profile, saved choice, then a sole compatible native choice; ask
@@ -44,6 +44,13 @@ Capacity and duration remain unverified without matching measurements. For a lar
 local task, select only relevant sources or split the task before a new preparation;
 never silently omit, truncate or replace a required source with a summary.
 
+If `prepare` reports `E_CAPSULE_SECRET`, show its masked findings (path, line, rule,
+confidence); never edit, redact or drop a required source to pass the check. For a
+resolvable finding, ask whether that exact value is a credential. Only when the user
+confirms it is not, prepare again with `credentialResolutions` naming that finding's
+`id` and `contentDigest`. Recognizable credential formats, private keys and credential
+files are never resolvable: ask the user to remove the credential from the source.
+
 Call `prepare` with the engine/profile, context and explicit integration scope.
 Show its engine, model selection, known provider or native-managed routing,
 trusted configuration, working directory and context inventory once before

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

@@ -2,7 +2,7 @@
 
 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 20 or later, with no global CLI, provider credentials or runtime downloads.
+Node.js 22.13 or later, with no global CLI, provider credentials or runtime downloads.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 

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

@@ -2,7 +2,7 @@
 
 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 20 or later, with no global CLI, provider credentials or runtime downloads.
+Node.js 22.13 or later, with no global CLI, provider credentials or runtime downloads.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 

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

@@ -2,7 +2,7 @@
 
 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 20 or later, with no global CLI, provider credentials or runtime downloads.
+Node.js 22.13 or later, with no global CLI, provider credentials or runtime downloads.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 

package/lib/host-packages/cursor/openplanr/rules/planr-diagram/references/diagram-sharing.md

@@ -13,7 +13,7 @@ review. Preview the exact diagram title, source revision, elements, connections,
 destination and retention before creating it. Use `--yes` only when the user has
 already authorized that publication. The stable URL and generated access token
 are separate; copy the token through the local studio's **Share diagram** dialog,
-never into a URL, prompt, ordinary output or repository file. Owner credentials
+never into a URL, prompt, ordinary output or repository file. Owner keys
 are saved privately outside the project. The review remains available until the
 owner revokes or deletes it and works while the local studio is stopped.
 

package/lib/host-packages/cursor/openplanr/rules/planr-doctor/references/upgrade.md

@@ -52,6 +52,10 @@ Shape (the fields this skill reads):
 - `upgrade-available` or `incompatible` → act. First **record the `installed`
   block as the before state** — the honest diff at the end depends on it. When
   only `nextSteps` is non-empty, skip to step 3.
+- `agents-behind` → the CLI is current and a coding agent's OpenPlanr install
+  needs updating. Record the `installed` block, then skip to step 3.
+- `aligned` with non-empty `nextSteps` → the versions match, but an install needs
+  the `openplanr doctor` commands listed. Skip to step 3.
 
 ## 2. Upgrade the CLI and obtain the next steps
 
@@ -90,6 +94,10 @@ this file.** Other shapes:
   `openplanr upgrade status --json` and use its `nextSteps`.
 - An `openplanr doctor` command: planning that agent's update failed, and `detail`
   says why. Relay it and run `openplanr doctor --json`.
+- An `openplanr doctor --fix` command: a file in that agent's runtime package was
+  changed outside OpenPlanr, and `detail` names it. Run it, show the user the
+  repair preview, and rerun it with `--yes` only after they confirm. The changed
+  files are backed up before they are replaced.
 
 `pluginHalfCommands` repeats the commands for older readers; read `nextSteps`.
 

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

@@ -36,7 +36,10 @@ skill's job, then reporting what actually changed — never what was merely
 attempted.
 
 1. **Decide.** Run `openplanr upgrade status --json` and read `status`. If it is
-   `aligned` or `unknown`, there is nothing to drive — report it and stop.
+   `aligned` or `unknown` with empty `nextSteps`, there is nothing to drive —
+   report it and stop. If it is `agents-behind`, or `aligned` with `nextSteps`,
+   the CLI is already current: run its `nextSteps` commands in order, as step 3
+   describes, without upgrading the CLI.
    Record the reported `installed` versions; that is the before state.
 2. **Own half, prescribe half.** If `status` is `upgrade-available` or
    `incompatible`, confirm with the user (this upgrades the npm CLI), then run

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

@@ -46,9 +46,11 @@ matches. Never overwrite a prior cycle implicitly.
 ```
 
 `cycle.md` records the effective scope, roster, repository revision when relevant, and the outcome
-of each lens. If the directory is ignored by Git, continue locally and mention that in the report;
-do not ask the user to change ignore rules. Report an exact filesystem error only when the cycle
-workspace cannot be created or written.
+of each lens. An advisor lens run on its own creates the same layout with a one-lens roster and an
+unsynthesized `board-report.md`, so every review the dashboard lists has one shape.
+If the directory is ignored by Git, continue locally and mention that in the report; do not ask the
+user to change ignore rules. Report an exact filesystem error only when the cycle workspace cannot be
+created or written.
 
 ## Build shared context once
 

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

@@ -78,8 +78,14 @@ Write stories and tasks directly in the repository's active planning mode.
   deleted ID. The packaged [planning ID helper](planr-plan/scripts/planning-ids.mjs) may
   inspect or reserve IDs; it never generates content.
 - Give each story stable acceptance IDs starting at `AC-001`.
-- Create one Tech task when no design surface applies; create one UI and one
-  Tech task when it does. Never exceed two tasks for one story.
+- Split each story into tasks that are coherent and independently verifiable.
+  Separate by ownership first: UI work is a `UI` task for the frontend role and
+  server, data, or integration work is a `Tech` task for the backend role.
+  Within one owner, split further only for a real output dependency, a distinct
+  verification surface, or reviewable size. Most stories need one Tech task,
+  plus one UI task when a design surface applies; never fragment one coherent
+  change into tasks that cannot be verified alone, and never fold unrelated work
+  into one task.
 - Map every acceptance ID through `acceptanceRefs` and name it with a concrete
   verification statement under `## Test Requirements`.
 - Set `reviewRisks` and `browserSurfaces` from repository evidence; use empty
@@ -111,8 +117,8 @@ instead of repeating every path in chat.
 - **Checks:** frontmatter, ID and acceptance coverage checks actually performed.
 - **Issues:** unresolved inputs or material assumptions, with their impact and recovery step; omit when empty.
 - **Next:** the exact ready task selector and a copy-ready host-native
-  invocation such as `$planr-ship T-NNN` (Codex/ChatGPT) or
-  `/planr-ship T-NNN` (Claude Code).
+  invocation such as `/planr:ship T-NNN` (Claude Code), `$planr:ship T-NNN`
+  (Codex/ChatGPT) or the `planr-ship` rule (Cursor).
 
 Mention the planning layout or consulted lenses only when they explain a material
 choice. Different summary wording never requires another planning run.

package/lib/host-packages/cursor/openplanr/rules/planr-sprint/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-sprint.mdc

@@ -35,7 +35,7 @@ capability; it never blocks the run. Name every degraded input in `Issues`.
 | 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`; `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 |
+| Linear or GitHub connection ([tracker connections](planr-sprint/references/tracker-connections.md)) | Update linked issues on approval, read PR state | Local files only; report the external step as not run and name the connection to add |
 
 ## Step 0: Frame the run
 
@@ -134,9 +134,10 @@ openplanr sprint apply SPRINT-NNN --dry-run          # show the status and prior
 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
-(`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
+Then update the issue linked to each changed item through the host's Linear or
+GitHub connection, with the status mapping in
+[tracker connections](planr-sprint/references/tracker-connections.md), and report the items that
+were not updated. 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 `openplanr sprint close SPRINT-NNN`; it records the

package/lib/host-packages/cursor/openplanr/rules/planr-status/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-status.mdc

@@ -10,9 +10,10 @@ planning artifacts, task statuses, dependency graph, current branch, and relevan
 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
-local results useful when credentials or connectors are unavailable. Report
-counts, ready and blocked work, dependency problems, and the most useful next
+Add GitHub or Linear lookups only when the user requests live remote state, through
+the host's connections as described in [tracker connections](planr-status/references/tracker-connections.md).
+Keep local results useful when a connection is unavailable, and name the one to add.
+Report counts, ready and blocked work, dependency problems, and the most useful next
 action. Do not repair artifacts, start Plan or Ship, or change lifecycle state.
 
 When the OpenPlanr dashboard is running (`planr-dashboard`), the same delivery