openplanr 2.2640.9 → 2.2641.1

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

@@ -11,7 +11,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](references/sprint-formats.md).
 
@@ -34,7 +34,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 |
 
@@ -90,7 +90,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
@@ -114,9 +114,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](schemas/refinement.schema.json); the
@@ -131,16 +131,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
@@ -152,7 +152,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.
@@ -179,7 +179,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/openai/openplanr/skills/sprint/references/refinement-contract.md

@@ -2,10 +2,10 @@
 
 The refinement document is the durable record of one run: what was read, how
 each item was judged, what was selected and what the refuters changed. The CLI
-validates it (`planr sprint refinement <id> --data`), stores it as
+validates it (`openplanr sprint refinement <id> --data`), stores it as
 `.planr/sprints/SPRINT-NNN/refinement.json`, renders `refinement.md` from it
-and fills the sprint body from its batches. `planr sprint diff`, `planr sprint
-close` and `planr sprint apply` read it back.
+and fills the sprint body from its batches. `openplanr sprint diff`, `openplanr sprint
+close` and `openplanr sprint apply` read it back.
 
 ## Item record
 
@@ -26,7 +26,7 @@ One entry per open item, whether or not it is selected.
 | `bucket` | `inProgress`, `planNext`, `blocked` or `closeOrDemote`. |
 | `reason` | One clause: why the item sits in that bucket. |
 | `evidence` | For close-or-demote rows: `file:line`, PR number or date. |
-| `targetStatus` / `targetPriority` | What `planr sprint apply` writes, in the repository's own vocabulary (`planr update --help`). Priority applies to backlog items only. |
+| `targetStatus` / `targetPriority` | What `openplanr sprint apply` writes, in the repository's own vocabulary (`openplanr update --help`). Priority applies to backlog items only. |
 
 ## Scoring
 
@@ -149,6 +149,6 @@ A pick that fails a lens moves or drops, and the correction is recorded in
 
 `inputs.sources` names what was read; `inputs.defaulted` names every value
 taken from a default instead of the repository or the user. The CLI adds
-`leftovers[]` on `planr sprint close` and `applied` on `planr sprint apply`;
+`leftovers[]` on `openplanr sprint close` and `applied` on `openplanr sprint apply`;
 never write those yourself. Unknown fields are rejected, so keep notes in
 `inputs.notes` or in the item's `reason`.

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.2640.9",
+  "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.10"
+    "planr-pipeline": "0.56.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",