openplanr 2.2641.0 → 2.2641.1

package/lib/host-packages/openai/openplanr/skills/sprint/references/sprint-formats.md

@@ -3,7 +3,7 @@
 Three durable outputs and one chat return. The CLI writes the first three from
 the two JSON inputs below; when it is unavailable, write the same files by hand.
 
-## `sprint.json` (input to `planr sprint create --data`)
+## `sprint.json` (input to `openplanr sprint create --data`)
 
 ```json
 {
@@ -17,7 +17,7 @@ the two JSON inputs below; when it is unavailable, write the same files by hand.
 
 `endDate` defaults to `releaseCut`, or to `startDate` plus the duration when no
 cut is known. `status` may be `planned` or `active` (default). Omit `taskIds`
-and `batches`; `planr sprint refinement` fills them from the refinement
+and `batches`; `openplanr sprint refinement` fills them from the refinement
 document.
 
 ## Sprint artifact
@@ -64,11 +64,11 @@ refinedAt: "2026-09-17"
 - [ ] **QT-194** Release cut 25 Sep · hours · [view](../quick/QT-194-release-cut-25-sep.md)
 
 ## Retrospective
-_Complete this section when closing the sprint with `planr sprint close SPRINT-004`._
+_Complete this section when closing the sprint with `openplanr sprint close SPRINT-004`._
 ```
 
 Each task line is `- [ ] **ID** title · effort · [view](relative path)`.
-`planr status`, `planr sprint close` and the dashboard read these lines; tick a
+`openplanr status`, `openplanr sprint close` and the dashboard read these lines; tick a
 box when the item ships. `releaseCut` is absent when no release profile exists;
 `capacityDays` and `refinedAt` are absent until a refinement is recorded.
 
@@ -84,20 +84,20 @@ run can diff against it:
 - **Refuter verdicts**: every correction verbatim, with its lens.
 - **In progress** by batch, then **Plan next**, **Blocked** and **Close or
   demote** in full, since only In progress goes into the sprint.
-- **Leftovers** (after `planr sprint close`) and **Applied** (after
-  `planr sprint apply`).
+- **Leftovers** (after `openplanr sprint close`) and **Applied** (after
+  `openplanr sprint apply`).
 
 ## Machine-readable copy
 
 `.planr/sprints/SPRINT-NNN/refinement.json`: the document described in
 [the refinement contract](refinement-contract.md), validated against the JSON
 Schema packaged as `schemas/refinement.schema.json` (linked from the skill
-entrypoint). The dashboard, `planr sprint diff` and `planr sprint apply` consume
+entrypoint). The dashboard, `openplanr sprint diff` and `openplanr sprint apply` consume
 it.
 
 ## Status write-back
 
-Only on approval through the structured question. `planr sprint apply
+Only on approval through the structured question. `openplanr sprint apply
 SPRINT-NNN --yes --commit` writes each close, demote or blocked row's
 `targetStatus`, `targetPriority` and `blockedBy` to the artifacts and commits the
 sprint, the note, the JSON and the changed artifacts as one commit:

package/lib/host-packages/openai/openplanr/skills/sprint/schemas/refinement.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openplanr.dev/schemas/skills/planr-sprint/refinement.schema.json",
   "title": "OpenPlanr sprint refinement document",
-  "description": "One backlog refinement run: inputs, every open item's judgement, the four buckets, the in-progress batches and the refuter corrections. Written by the planr-sprint skill and validated by planr sprint refinement.",
+  "description": "One backlog refinement run: inputs, every open item's judgement, the four buckets, the in-progress batches and the refuter corrections. Written by the planr-sprint skill and validated by openplanr sprint refinement.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "sprintId", "refinedAt", "inputs", "items", "buckets"],
@@ -102,7 +102,7 @@
       }
     },
     "leftovers": {
-      "description": "Written by planr sprint close.",
+      "description": "Written by openplanr sprint close.",
       "type": "array",
       "items": {
         "type": "object",
@@ -115,7 +115,7 @@
       }
     },
     "applied": {
-      "description": "Written by planr sprint apply.",
+      "description": "Written by openplanr sprint apply.",
       "type": "object",
       "additionalProperties": false,
       "required": ["at", "updates"],

package/lib/host-packages/openai/openplanr/skills/status/SKILL.md

@@ -8,7 +8,7 @@ license: MIT
 
 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/openai/openplanr/skills/sync/SKILL.md

@@ -15,17 +15,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/openai/openplanr/skills/sync/openplanr.skill.json

@@ -24,6 +24,17 @@
       ],
       "executable": true
     },
+    {
+      "path": "scripts/names.mjs",
+      "kind": "script",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
     {
       "path": "agents/openai.yaml",
       "kind": "agent-metadata",

package/lib/host-packages/openai/openplanr/skills/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/openai/openplanr/skills/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/integrations.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/names.d.mts

@@ -0,0 +1,4 @@
+/** Folder at a project root that holds its OpenPlanr planning files. */
+export declare const PLANNING_FOLDER: '.planr';
+/** Command name that help, usage, errors and next-step hints show. */
+export declare const CLI_COMMAND: 'openplanr';

package/lib/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/planning-folder.d.mts

@@ -0,0 +1,14 @@
+export { PLANNING_FOLDER } from './names.mjs';
+
+/** Why OpenPlanr refuses to write into a project's planning folder. */
+export interface PlanningFolderConflict {
+  readonly code: 'E_PLANNING_FOLDER_FOREIGN';
+  readonly problem: string;
+  readonly fix: string;
+  readonly signs: readonly string[];
+}
+
+/** Signs that `<projectRoot>/.planr`, which lacks OpenPlanr's config.json, is a folder OpenPlanr didn't create; empty when OpenPlanr may write there. */
+export declare function foreignPlanningFolderSigns(projectRoot: string): string[];
+/** The refusal for writing into a planning folder OpenPlanr didn't create, or null when OpenPlanr may write there. */
+export declare function planningFolderConflict(projectRoot: string): PlanningFolderConflict | null;

package/lib/planning-folder.mjs

@@ -0,0 +1,40 @@
+// @ts-check
+// Recognizes a planning folder OpenPlanr didn't create, so OpenPlanr never writes into it.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { CLI_COMMAND, PLANNING_FOLDER } from './names.mjs';
+
+export { PLANNING_FOLDER };
+
+const FOREIGN_FILES = Object.freeze(['planr.config.json', 'board.html']);
+const GOAL_DIRECTORIES = Object.freeze(['tasks', 'plans']);
+
+const isDirectory = (path) => existsSync(path) && statSync(path).isDirectory();
+
+/** @type {typeof import('./planning-folder.d.mts').foreignPlanningFolderSigns} */
+export function foreignPlanningFolderSigns(projectRoot) {
+  const folder = join(projectRoot, PLANNING_FOLDER);
+  if (!isDirectory(folder) || existsSync(join(folder, 'config.json'))) return [];
+  const signs = FOREIGN_FILES.filter((name) => existsSync(join(folder, name)));
+  for (const name of GOAL_DIRECTORIES) {
+    const directory = join(folder, name);
+    if (
+      isDirectory(directory) &&
+      readdirSync(directory).some((entry) => entry.endsWith('-goal.md'))
+    )
+      signs.push(`*-goal.md files in ${name}`);
+  }
+  return signs;
+}
+
+/** @type {typeof import('./planning-folder.d.mts').planningFolderConflict} */
+export function planningFolderConflict(projectRoot) {
+  const signs = foreignPlanningFolderSigns(projectRoot);
+  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),
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openplanr",
-  "version": "2.2641.0",
+  "version": "2.2641.1",
   "description": "Deterministic OpenPlanr utilities for planning storage, validation, rendering, setup, diagnostics, and GitHub/Linear synchronization",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -19,9 +19,9 @@
     }
   },
   "bin": {
-    "planr": "./bin/planr.js",
-    "openplanr": "./bin/planr.js",
-    "opr": "./bin/planr.js"
+    "openplanr": "./bin/openplanr.js",
+    "opr": "./bin/openplanr.js",
+    "planr": "./bin/planr.js"
   },
   "publishConfig": {
     "access": "public",
@@ -115,7 +115,7 @@
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "planr-pipeline": "0.55.11"
+    "planr-pipeline": "0.56.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",