openplanr 3.1.1 → 3.3.0

package/dist/utils/slugify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slugify.d.ts","sourceRoot":"","sources":["../../src/utils/slugify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CAmB5D"}
+{"version":3,"file":"slugify.d.ts","sourceRoot":"","sources":["../../src/utils/slugify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/utils/slugify.js

@@ -1,26 +1,2 @@
-/**
- * Convert text to a URL/filename-safe slug.
- *
- * `maxLength` caps the slug (default 80) so filenames stay well under
- * the OS limit (255 chars) even after the ID prefix and `.md` extension.
- * The slug is trimmed at the last whole word boundary to avoid cut-off words.
- */
-export function slugify(text, maxLength = 80) {
-    let slug = text
-        .toLowerCase()
-        .trim()
-        .replace(/[^\w\s-]/g, '')
-        .replace(/[\s_]+/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-+|-+$/g, '');
-    if (slug.length > maxLength) {
-        slug = slug.slice(0, maxLength);
-        // Trim at last whole-word boundary to avoid cut-off words
-        const lastDash = slug.lastIndexOf('-');
-        if (lastDash > 0) {
-            slug = slug.slice(0, lastDash);
-        }
-    }
-    return slug;
-}
+export { slugify } from '../../lib/backlog-item.mjs';
 //# sourceMappingURL=slugify.js.map

package/dist/utils/slugify.js.map

@@ -1 +1 @@
-{"version":3,"file":"slugify.js","sourceRoot":"","sources":["../../src/utils/slugify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,SAAS,GAAG,EAAE;IAClD,IAAI,IAAI,GAAG,IAAI;SACZ,WAAW,EAAE;SACb,IAAI,EAAE;SACN,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE3B,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC5B,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAChC,0DAA0D;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjB,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"slugify.js","sourceRoot":"","sources":["../../src/utils/slugify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC"}

package/docs/CLI.md

@@ -243,6 +243,30 @@ openplanr spec shape SPEC-001
 
 ---
 
+#### `openplanr spec validate`
+
+Check one spec file against the specification contract. It reads the file and writes nothing.
+
+```bash
+openplanr spec validate SPEC-001
+openplanr spec validate SPEC-001 --json
+```
+
+| Option     | Description                                                     | Required |
+| ---------- | --------------------------------------------------------------- | -------- |
+| `<specId>` | Spec ID to check                                                | Yes      |
+| `--json`   | Print `{ ok, specId, file, violations[] }` instead of text      | No       |
+
+**Rules:**
+1. **`path`** — the file is `SPEC-NNN-{slug}/SPEC-NNN-{slug}.md`, and its frontmatter `id` and `slug` match that path.
+2. **`frontmatter`** — the frontmatter is valid against the Protocol spec schema for the `schemaVersion` it declares (`1.0.0` or `1.7.0`): every required key (including `id`), allowed values, no unknown keys. A missing or unsupported `schemaVersion` is an error that lists the supported versions.
+3. **`headings`** — the 13 contract headings, from `## Context & Goal` to `## Notes for Decomposition`, appear in order, and `## Scope Boundaries` has `### In Scope` and `### Out of Scope`. Other headings may sit between them.
+4. **`acceptance-ids`** — every top-level item under `## Acceptance Criteria` starts with a unique `AC-NNN` id (a checkbox and bold markers before it are fine).
+
+Each violation is printed with the file, the rule, and what was found. The command exits 1 when there is any violation or the spec is not found, and 0 otherwise.
+
+---
+
 #### `openplanr spec sync`
 
 Validate spec integrity and auto-fix safe inconsistencies. Use after manual edits, interrupted work, or when in doubt.
@@ -322,12 +346,20 @@ openplanr spec attach-design SPEC-001 --files login.png signup.png
 
 #### `openplanr spec promote`
 
-Validate that a spec is ready for handoff to `planr-pipeline` (has stories, tasks, non-trivial body) and print the next-step pipeline command. Updates SPEC frontmatter `status: ready-for-pipeline`.
+Validate that a spec is ready for handoff (has stories, tasks, and a non-trivial body), mark the spec ready-for-pipeline by writing `status: "ready-for-pipeline"` into its frontmatter, and print the next-step pipeline command.
 
 ```bash
 openplanr spec promote SPEC-001
+openplanr spec promote SPEC-001 --dry-run   # validate and print the handoff; write nothing
 ```
 
+| Option      | Description                                                                     | Required |
+| ----------- | ------------------------------------------------------------------------------- | -------- |
+| `<specId>`  | Spec ID to promote                                                              | Yes      |
+| `--dry-run` | Validate and print the handoff command without marking the spec ready-for-pipeline | No    |
+
+To check a spec's structure without changing its status, use `openplanr spec validate`.
+
 After promotion, run from any configured runtime:
 
 ```text
@@ -694,6 +726,65 @@ Cursor uses Composer handoff with sequential fallback.
 
 ---
 
+### `openplanr ship checks`
+
+List the checks a change needs for a tier, without running them. Sources are the
+GitHub Actions workflows, husky (`.husky/pre-commit`, `.husky/pre-push`) and
+pre-commit hooks, package scripts, and the task's `## Test Requirements`.
+
+```bash
+openplanr ship checks --task .planr/tasks/T-012-parser.md --json
+openplanr ship checks --tier push --json
+```
+
+| Option          | Description                                                    | Default                                   |
+| --------------- | -------------------------------------------------------------- | ----------------------------------------- |
+| `--task <path>` | Task file whose Test Requirements to include                   | none                                      |
+| `--tier <tier>` | `task`, `story`, `push` or `planning`                          | `planning` for a `.planr`-only change, else `task` |
+| `--base <ref>`  | Compare against the merge base with this ref                   | `origin/HEAD`, then `main`                |
+| `--json`        | Print the `openplanr-ship-checks` result (schema `1.1.0`)      | `false`                                   |
+
+**Tiers:**
+
+- `planning`: `openplanr spec sync --dry-run` and `openplanr sync --dry-run`, tagged
+  `report-only` because both exit 0 when they report problems.
+- `task`: Test Requirements commands, pre-commit hooks, and the CI build when the
+  change touches a package entry point, a build script, a `tsconfig*.json` or a
+  bundler config. Without a task command, the `test`, `typecheck` and `lint`
+  scripts are listed as `fallback`.
+- `story`: `task` plus every `run` step of the pull-request and merge-queue
+  workflows whose path filters match the change.
+- `push`: `story` without path filters, plus push workflows and pre-push hooks.
+
+Each CI step is kept verbatim with its `cwd` (step, then job, then workflow
+`working-directory`). Install steps and `uses` steps are skipped. A static matrix
+is expanded; other `${{ }}` expressions are tagged `needs-review`. A check is
+`tracked-only` when its command, its package script, or a script file either one
+runs directly mentions `lint-staged`, `ls-files`, `--cached` or `--staged`;
+deeper calls are not followed. `relatedTests` lists test files that mention a
+name the change exports, a `.command()` name, or a route path.
+
+`coverage` names changed files that a passing run may not have checked.
+`trackedOnly.unseen` lists untracked files when any check is `tracked-only`
+(warning `UNTRACKED_NOT_SEEN`); `git add -N` makes them visible.
+`typescript.uncovered` lists new `.ts`, `.tsx`, `.mts` and `.cts` files outside
+`.planr/` that no `tsconfig*.json` root file set includes (`files`, `include`,
+`exclude`, `extends`, and `references` one level deep; warning `TS_NOT_COVERED`).
+A file reached only through an import is still reported, and the command does
+not check which tsconfig CI runs. A tsconfig that TypeScript reports errors for
+raises `TSCONFIG_ERROR` with its first message, and a config whose `extends`
+cannot be read adds no coverage. To read tsconfigs, the command loads the
+`typescript` package that Node resolves from the project root, which can be a
+copy in a parent directory, and that runs the package's code; it never executes
+checks. When Node cannot resolve `typescript` there, `typescript` is `null` with
+the info diagnostic `TYPESCRIPT_UNAVAILABLE`.
+
+`complete` is `false` when any diagnostic is an `error`, for example a workflow
+that fails to parse: the listed checks are then not the full CI set. The command
+exits 1 for an unknown tier, a missing `--task` file or a directory outside git.
+
+---
+
 ### `openplanr sync`
 
 Validate and repair cross-references across all artifacts.
@@ -1286,6 +1377,9 @@ For semantic decomposition, invoke the installed `planr:plan` skill. After revie
     "backlog": "BL",
     "sprint": "SPRINT"
   },
-  "createdAt": "2026-03-26"
+  "createdAt": "2026-03-26",
+  "findings": { "unattended": "report" }
 }
 ```
+
+`findings.unattended` decides what Ship and Investigate do with findings outside the task when nobody can answer: `report` (the default) lists them, `file` files each one as a backlog item. Settings OpenPlanr doesn't know are kept when it saves the file.

package/lib/backlog-item.d.mts

@@ -0,0 +1,49 @@
+/** Normalised fields of one backlog item. */
+export interface BacklogFields {
+  readonly title: string;
+  readonly priority: string;
+  readonly tags: readonly string[];
+  readonly description: string;
+  readonly acceptanceCriteria?: string | readonly string[];
+  readonly notes?: string;
+  readonly epicId?: string;
+}
+
+/** One open backlog item; `path` is project-relative. */
+export interface OpenBacklogItem {
+  readonly id: string;
+  readonly title: string;
+  readonly status: string;
+  readonly path: string;
+}
+
+/** The command that installs the OpenPlanr CLI. */
+export declare const CLI_INSTALL_COMMAND: 'npm install -g openplanr';
+/** The one-time line shown after filing without the CLI. */
+export declare const CLI_HINT: string;
+
+/** Reserves the next `PREFIX-NNN` in `dir`, one past the highest file or reservation; never reissues a removed ID. */
+export declare function reserveNextId(dir: string, prefix: string): Promise<string>;
+/** Converts text to a filename-safe slug of at most `maxLength` characters, cut at a word boundary. */
+export declare function slugify(text: string, maxLength?: number): string;
+/** Normalises raw input; throws when the title is empty. */
+export declare function backlogFields(input: Record<string, unknown>): BacklogFields;
+/** Renders the default backlog item Markdown. */
+export declare function renderBacklogItem(id: string, fields: BacklogFields, date: string): string;
+/** Reserves an ID and writes the item into `backlogDir`. */
+export declare function writeBacklogItem(
+  backlogDir: string,
+  prefix: string,
+  fields: BacklogFields,
+  date: string,
+): Promise<{ id: string; filePath: string }>;
+/** Creates an item in the backlog folder configured by `<projectDir>/.planr/config.json`. */
+export declare function createBacklogItem(
+  projectDir: string,
+  input: Record<string, unknown>,
+  date?: string,
+): Promise<{ id: string; title: string; artifactPath: string }>;
+/** Lists backlog items whose status is not `closed` or `done`. */
+export declare function listOpenBacklog(projectDir: string): Promise<OpenBacklogItem[]>;
+/** Returns the install hint and records it in `.planr/config.json`, or null once it has been shown in this project. */
+export declare function takeCliHint(projectDir: string): Promise<string | null>;

package/lib/backlog-item.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// @ts-check
+// The one backlog item writer: the CLI imports it, and skills run it when no CLI is installed.
+
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Holds one empty file per issued ID, so the ID of a removed artifact is never issued again. */
+const ISSUED_IDS_DIR = '.issued-ids';
+const CLOSED_STATUSES = new Set(['closed', 'done']);
+
+/** @type {typeof import('./backlog-item.d.mts').CLI_INSTALL_COMMAND} */
+export const CLI_INSTALL_COMMAND = 'npm install -g openplanr';
+/** @type {typeof import('./backlog-item.d.mts').CLI_HINT} */
+export const CLI_HINT = `Install the OpenPlanr CLI to manage these items: ${CLI_INSTALL_COMMAND}`;
+
+/** @type {typeof import('./backlog-item.d.mts').reserveNextId} */
+export async function reserveNextId(dir, prefix) {
+  const issuedDir = join(dir, ISSUED_IDS_DIR);
+  await mkdir(issuedDir, { recursive: true });
+  const pattern = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}-(\\d{3,})`, 'u');
+  let next = 1;
+  for (const directory of [dir, issuedDir]) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const match = entry.isDirectory() ? null : pattern.exec(entry.name);
+      if (match) next = Math.max(next, Number.parseInt(match[1], 10) + 1);
+    }
+  }
+  for (; ; next++) {
+    const id = `${prefix}-${String(next).padStart(3, '0')}`;
+    try {
+      await writeFile(join(issuedDir, id), '', { flag: 'wx' });
+      return id;
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'EEXIST') throw error;
+    }
+  }
+}
+
+/** @type {typeof import('./backlog-item.d.mts').slugify} */
+export function slugify(text, maxLength = 80) {
+  let slug = text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (slug.length > maxLength) {
+    slug = slug.slice(0, maxLength);
+    // Trim at the last whole-word boundary to avoid cut-off words.
+    const lastDash = slug.lastIndexOf('-');
+    if (lastDash > 0) slug = slug.slice(0, lastDash);
+  }
+  return slug;
+}
+
+/** @param {unknown} value */
+function strings(value) {
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  if (typeof value === 'string')
+    return value
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean);
+  return [];
+}
+
+/** @param {unknown} value */
+function optionalText(value) {
+  return value === undefined || value === null || value === '' ? undefined : value;
+}
+
+const PRIORITIES = Object.freeze(['critical', 'high', 'medium', 'low']);
+
+/** Bad backlog input; the code lets the CLI report it as an input error, not a crash. */
+class BacklogInputError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'BacklogInputError';
+    this.code = 'E_BACKLOG_INVALID';
+  }
+}
+
+/** @type {typeof import('./backlog-item.d.mts').backlogFields} */
+export function backlogFields(input) {
+  const title = String(input.title ?? input.name ?? '').trim();
+  if (!title) throw new BacklogInputError('A backlog item needs a non-empty title.');
+  const priority = String(input.priority ?? 'medium');
+  if (!PRIORITIES.includes(priority))
+    throw new BacklogInputError(
+      `Backlog priority ${JSON.stringify(priority)} is not valid; use one of ${PRIORITIES.join(', ')}.`,
+    );
+  const criteria = optionalText(input.acceptanceCriteria);
+  const notes = optionalText(input.notes);
+  const epicId = optionalText(input.epicId);
+  return {
+    title,
+    priority,
+    tags: strings(input.tags),
+    description: String(input.description ?? title),
+    ...(criteria === undefined
+      ? {}
+      : { acceptanceCriteria: Array.isArray(criteria) ? criteria.map(String) : String(criteria) }),
+    ...(notes === undefined ? {} : { notes: String(notes) }),
+    ...(epicId === undefined ? {} : { epicId: String(epicId) }),
+  };
+}
+
+/** @type {typeof import('./backlog-item.d.mts').renderBacklogItem} */
+export function renderBacklogItem(id, fields, date) {
+  const quote = JSON.stringify;
+  const lines = [
+    '---',
+    `id: ${quote(id)}`,
+    `title: ${quote(fields.title)}`,
+    `priority: ${quote(fields.priority)}`,
+    `tags: [${fields.tags.map((tag) => quote(tag)).join(', ')}]`,
+    'status: "open"',
+    `created: ${quote(date)}`,
+    `updated: ${quote(date)}`,
+    ...(fields.epicId ? [`epicId: ${quote(fields.epicId)}`] : []),
+    '---',
+    '',
+    `# ${id}: ${fields.title}`,
+    '',
+  ];
+  /** @param {string} heading @param {string} body @param {boolean} [spaced] */
+  const section = (heading, body, spaced = false) =>
+    lines.push(`## ${heading}`, ...(spaced ? [''] : []), body, '');
+  if (fields.tags.length > 0)
+    section('Tags', fields.tags.map((tag) => `- ${tag}`).join('\n'), true);
+  // A description with its own sections stands alone instead of nesting under another heading.
+  if (/^## /u.test(fields.description)) lines.push(fields.description, '');
+  else if (fields.description !== fields.title) section('Description', fields.description);
+  if (fields.acceptanceCriteria !== undefined && fields.acceptanceCriteria.length > 0)
+    section(
+      'Acceptance Criteria',
+      Array.isArray(fields.acceptanceCriteria)
+        ? fields.acceptanceCriteria.map((criterion) => `- ${criterion}`).join('\n')
+        : fields.acceptanceCriteria,
+    );
+  if (fields.notes) section('Notes', fields.notes);
+  lines.push('---', `_Close when done: \`openplanr backlog update ${id} --status closed\`_`, '');
+  return lines.join('\n');
+}
+
+/** @type {typeof import('./backlog-item.d.mts').writeBacklogItem} */
+export async function writeBacklogItem(backlogDir, prefix, fields, date) {
+  await mkdir(backlogDir, { recursive: true });
+  const id = await reserveNextId(backlogDir, prefix);
+  const filePath = join(backlogDir, `${id}-${slugify(fields.title)}.md`);
+  await writeFile(filePath, renderBacklogItem(id, fields, date));
+  return { id, filePath };
+}
+
+/** @param {string} projectDir */
+async function projectConfig(projectDir) {
+  const configPath = join(projectDir, '.planr', 'config.json');
+  let raw;
+  try {
+    raw = await readFile(configPath, 'utf8');
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT')
+      throw new Error(
+        `No OpenPlanr project at ${projectDir}: ${configPath} is missing. Run \`openplanr init\` or pass the project root.`,
+      );
+    throw error;
+  }
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${configPath} is not valid JSON: ${/** @type {Error} */ (error).message}`);
+  }
+  return { configPath, raw, config };
+}
+
+/** @param {string} projectDir */
+async function projectBacklog(projectDir) {
+  const { config } = await projectConfig(projectDir);
+  const agile = String(config.outputPaths?.agile ?? '.planr').replaceAll('\\', '/');
+  return {
+    backlogDir: resolve(projectDir, agile, 'backlog'),
+    prefix: String(config.idPrefix?.backlog ?? 'BL'),
+    templateOverrides:
+      typeof config.templateOverrides === 'string' ? config.templateOverrides : undefined,
+  };
+}
+
+/** @param {string} projectDir @param {string} filePath */
+const relativePath = (projectDir, filePath) => relative(projectDir, filePath).split(sep).join('/');
+
+/** @type {typeof import('./backlog-item.d.mts').createBacklogItem} */
+export async function createBacklogItem(
+  projectDir,
+  input,
+  date = new Date().toISOString().split('T')[0],
+) {
+  const { backlogDir, prefix } = await projectBacklog(projectDir);
+  const fields = backlogFields(input);
+  const { id, filePath } = await writeBacklogItem(backlogDir, prefix, fields, date);
+  return { id, title: fields.title, artifactPath: relativePath(projectDir, filePath) };
+}
+
+/**
+ * Top-level scalar frontmatter fields; double-quoted values are read as JSON strings.
+ * @param {string} text
+ * @param {string} filePath
+ */
+function frontmatter(text, filePath) {
+  const block = /^---\n([\s\S]*?)\n---/u.exec(text.replace(/\r\n/gu, '\n'))?.[1] ?? '';
+  /** @type {Record<string, string>} */
+  const fields = {};
+  for (const line of block.split('\n')) {
+    const match = /^(\w+):\s*(.*)$/u.exec(line);
+    if (!match) continue;
+    const value = match[2].trim();
+    if (!value.startsWith('"')) {
+      fields[match[1]] = value.replace(/^'(.*)'$/u, '$1');
+      continue;
+    }
+    try {
+      fields[match[1]] = String(JSON.parse(value));
+    } catch (error) {
+      throw new Error(
+        `${filePath}: frontmatter field "${match[1]}" is not a valid quoted string: ${/** @type {Error} */ (error).message}`,
+      );
+    }
+  }
+  return fields;
+}
+
+/** @type {typeof import('./backlog-item.d.mts').listOpenBacklog} */
+export async function listOpenBacklog(projectDir) {
+  const { backlogDir } = await projectBacklog(projectDir);
+  let names;
+  try {
+    names = await readdir(backlogDir);
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return [];
+    throw error;
+  }
+  const items = [];
+  for (const name of names.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))) {
+    const match = /^([A-Z]+-\d{3,})-.+\.md$/u.exec(name);
+    if (!match) continue;
+    const filePath = join(backlogDir, name);
+    const fields = frontmatter(await readFile(filePath, 'utf8'), filePath);
+    const status = fields.status ?? 'open';
+    if (CLOSED_STATUSES.has(status)) continue;
+    items.push({
+      id: fields.id ?? match[1],
+      title: fields.title ?? name.slice(match[1].length + 1, -3).replace(/-/g, ' '),
+      status,
+      path: relativePath(projectDir, filePath),
+    });
+  }
+  return items;
+}
+
+/** @type {typeof import('./backlog-item.d.mts').takeCliHint} */
+export async function takeCliHint(projectDir) {
+  const { configPath, raw, config } = await projectConfig(projectDir);
+  if (config.findings?.cliHintShown === true) return null;
+  const next = { ...config, findings: { ...config.findings, cliHintShown: true } };
+  const indent = /\n(\t| +)"/u.exec(raw)?.[1] ?? '  ';
+  await writeFile(configPath, `${JSON.stringify(next, null, indent)}\n`);
+  return CLI_HINT;
+}
+
+/** @param {string} source */
+async function readInput(source) {
+  const text =
+    source === '-'
+      ? await new Promise((done, fail) => {
+          let value = '';
+          process.stdin.setEncoding('utf8');
+          process.stdin.on('data', (chunk) => {
+            value += chunk;
+          });
+          process.stdin.on('end', () => done(value));
+          process.stdin.on('error', fail);
+        })
+      : await readFile(resolve(source), 'utf8');
+  const parsed = JSON.parse(String(text));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+    throw new Error('Backlog input must be one JSON object with at least a title.');
+  return parsed;
+}
+
+const USAGE =
+  'Usage: backlog-item.mjs add --project <dir> --data <file|->\n       backlog-item.mjs list --project <dir> --open\n';
+
+/** @param {string[]} argv */
+async function main(argv) {
+  const [command, ...rest] = argv;
+  /** @type {Record<string, string | boolean>} */
+  const options = {};
+  for (let index = 0; index < rest.length; index += 1) {
+    const flag = rest[index];
+    if (flag === '--open') options.open = true;
+    else if (flag === '--project' || flag === '--data')
+      options[flag.slice(2)] = rest[++index] ?? '';
+    else throw new Error(`Unknown argument: ${flag}\n${USAGE}`);
+  }
+  const projectDir = resolve(String(options.project ?? '.'));
+  if (command === 'add') {
+    if (typeof options.data !== 'string' || !options.data)
+      throw new Error(`add needs --data.\n${USAGE}`);
+    const { templateOverrides } = await projectBacklog(projectDir);
+    const result = await createBacklogItem(projectDir, await readInput(options.data));
+    const cliHint = await takeCliHint(projectDir);
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        action: 'backlog.created',
+        ...result,
+        ...(templateOverrides ? { templateOverrideIgnored: true } : {}),
+        ...(cliHint ? { cliHint } : {}),
+      })}\n`,
+    );
+    return;
+  }
+  if (command === 'list' && options.open) {
+    process.stdout.write(`${JSON.stringify({ items: await listOpenBacklog(projectDir) })}\n`);
+    return;
+  }
+  throw new Error(USAGE);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}

package/lib/host-packages/adapter-registry.json

@@ -2,12 +2,12 @@
   "kind": "host-native-adapter-registry",
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
-  "pipelineVersion": "0.59.1",
-  "pluginVersion": "3.1.1",
+  "pipelineVersion": "0.61.0",
+  "pluginVersion": "3.3.0",
   "adapters": [
     {
       "id": "claude-code",
-      "version": "3.1.1",
+      "version": "3.3.0",
       "capabilityLevel": "product",
       "installScopes": [
         "user",
@@ -19,7 +19,7 @@
     },
     {
       "id": "codex",
-      "version": "3.1.1",
+      "version": "3.3.0",
       "capabilityLevel": "product",
       "installScopes": [
         "user",
@@ -31,7 +31,7 @@
     },
     {
       "id": "cursor",
-      "version": "3.1.1",
+      "version": "3.3.0",
       "capabilityLevel": "workflow",
       "installScopes": [
         "project"

package/lib/host-packages/capability-map.json

@@ -1,7 +1,7 @@
 {
   "kind": "openplanr-capability-map",
   "schemaVersion": "1.0.0",
-  "pluginVersion": "3.1.1",
+  "pluginVersion": "3.3.0",
   "families": [
     {
       "id": "planning",
@@ -339,7 +339,7 @@
       "id": "planr-investigate",
       "name": "investigate",
       "family": "diagnostics",
-      "description": "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery.",
+      "description": "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, including before any fix, not planned feature delivery.",
       "useWhen": [
         "Investigate a bug, regression, error, or unexplained behavior",
         "Reproduce a defect, establish its root cause, or apply a bounded fix",
@@ -471,7 +471,7 @@
       "id": "planr-ship",
       "name": "ship",
       "family": "implementation",
-      "description": "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work.",
+      "description": "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work, or to plan and implement an accepted change. Invoke before editing files for the requested change. Not for planning only, landing, release, or work handed to another coding agent.",
       "useWhen": [
         "Implement a plan, specification, task, fix, or clearly stated local request",
         "Build and verify the requested repository change",

package/lib/host-packages/claude/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
     "name": "OpenPlanr"
   },
   "metadata": {
-    "version": "3.1.1",
+    "version": "3.3.0",
     "description": "Generated local OpenPlanr package."
   },
   "plugins": [
     {
       "name": "planr",
       "source": "./openplanr",
-      "version": "3.1.1",
+      "version": "3.3.0",
       "description": "Close the loop from intent to delivery. Plan, design, build, review, and operate from durable context in your repository.",
       "strict": true
     }

package/lib/host-packages/claude/openplanr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "displayName": "OpenPlanr",
-  "version": "3.1.1",
+  "version": "3.3.0",
   "description": "Close the loop from intent to delivery. Plan, design, build, review, and operate from durable context in your repository.",
   "author": {
     "name": "OpenPlanr",