openplanr 3.5.0 → 3.6.0

package/lib/host-packages/claude/openplanr/runtime/operate/scripts/validate-note.mjs

@@ -1,39 +0,0 @@
-#!/usr/bin/env node
-
-import { existsSync, realpathSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { inspectOperateReviewNote } from './operate-review-note.mjs';
-
-function option(argv, name, fallback) {
-  const index = argv.indexOf(name);
-  return index >= 0 ? argv[index + 1] : fallback;
-}
-
-export async function runOperateReviewNoteValidator(argv = process.argv.slice(2)) {
-  const file = argv[0];
-  if (!file)
-    throw new Error(
-      'Usage: validate-note.mjs <markdown> --profile <profile> [--contract-version <version>]',
-    );
-  const result = inspectOperateReviewNote(await readFile(resolve(file), 'utf8'), {
-    profile: option(argv, '--profile', 'board-report'),
-    contractVersion: option(argv, '--contract-version', 'auto'),
-  });
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-  if (!result.ok) process.exitCode = 1;
-  return result;
-}
-
-if (
-  process.argv[1] &&
-  existsSync(resolve(process.argv[1])) &&
-  realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))
-) {
-  runOperateReviewNoteValidator().catch((error) => {
-    process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`);
-    process.exitCode = 1;
-  });
-}

package/lib/host-packages/claude/openplanr/skills/ceo-review/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/chair-review/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/challenger-review/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/cmo-review/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/coo-review/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/cpo-review/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/cto-review/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/investigate/scripts/backlog-item.mjs

@@ -1,339 +0,0 @@
-#!/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/claude/openplanr/skills/operate/scripts/validate-note.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Generated package-relative launcher; no global runtime or invocation downloads.
-import { existsSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runOperateReviewNoteValidator as run } from "../../../runtime/operate/scripts/validate-note.mjs";
-export * from "../../../runtime/operate/scripts/validate-note.mjs";
-if (process.argv[1] && existsSync(resolve(process.argv[1])) &&
-  realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) {
-  try { await run(process.argv.slice(2)); }
-  catch (error) { process.stderr.write(`${error.code ?? 'E_OPERATE_NOTE'}: ${error.message}\n`); process.exitCode = 1; }
-}

package/lib/host-packages/claude/openplanr/skills/plan/scripts/planning-ids.mjs

@@ -1,166 +0,0 @@
-#!/usr/bin/env node
-
-import { open, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
-
-const KINDS = Object.freeze(['SPEC', 'US', 'T']);
-const EMPTY = Object.freeze({ SPEC: 1, US: 1, T: 1 });
-const wait = (milliseconds) => new Promise((done) => setTimeout(done, milliseconds));
-const format = (kind, value) => `${kind}-${String(value).padStart(3, '0')}`;
-
-async function scanMaxima(root) {
-  const maxima = { SPEC: 0, US: 0, T: 0 };
-  const visit = async (directory) => {
-    let entries;
-    try {
-      entries = await readdir(directory, { withFileTypes: true });
-    } catch (error) {
-      if (error.code === 'ENOENT') return;
-      throw error;
-    }
-    for (const entry of entries) {
-      const match = /^(SPEC|US|T)-(\d{3,})(?:-|\.|$)/u.exec(entry.name);
-      if (match) maxima[match[1]] = Math.max(maxima[match[1]], Number(match[2]));
-      if (entry.isDirectory() && !entry.name.startsWith('.')) await visit(resolve(directory, entry.name));
-    }
-  };
-  await visit(root);
-  return maxima;
-}
-
-async function readSequence(root) {
-  try {
-    const value = JSON.parse(await readFile(resolve(root, '.id-sequence.json'), 'utf8'));
-    if (
-      value.kind !== 'planning-id-sequence'
-      || value.protocolVersion !== '1.7.0'
-      || KINDS.some((kind) => !Number.isSafeInteger(value.next?.[kind]) || value.next[kind] < 1)
-    ) throw new Error('Invalid planning ID sequence.');
-    return value;
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    throw error;
-  }
-}
-
-async function currentSequence(root) {
-  const [stored, maxima] = await Promise.all([readSequence(root), scanMaxima(root)]);
-  return {
-    kind: 'planning-id-sequence',
-    schemaVersion: '1.0.0',
-    protocolVersion: '1.7.0',
-    next: Object.fromEntries(
-      KINDS.map((kind) => [kind, Math.max(stored?.next[kind] ?? EMPTY[kind], maxima[kind] + 1)]),
-    ),
-  };
-}
-
-function parseArgs(argv) {
-  const options = { root: '.planr/specs', preview: false, counts: { SPEC: 0, US: 0, T: 0 } };
-  for (let index = 0; index < argv.length; index += 1) {
-    const value = argv[index];
-    if (value === '--root') options.root = argv[++index];
-    else if (value === '--preview') options.preview = true;
-    else if (value === '--spec' || value === '--stories' || value === '--tasks') {
-      const kind = value === '--spec' ? 'SPEC' : value === '--stories' ? 'US' : 'T';
-      const count = Number(argv[++index]);
-      if (!Number.isSafeInteger(count) || count < 0) throw new Error(`${value} must be a non-negative integer.`);
-      options.counts[kind] = count;
-    } else throw new Error(`Unknown argument: ${value}`);
-  }
-  return options;
-}
-
-const shellQuote = (value) => (/^[\w./-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`);
-
-/** Returns the nearest `.planr/config.json` at or above `directory` and the specs folder it configures. */
-async function configuredRoot(directory) {
-  for (let current = directory; ; current = dirname(current)) {
-    const configPath = join(current, '.planr', 'config.json');
-    const raw = await readFile(configPath, 'utf8').catch((error) => {
-      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
-      throw error;
-    });
-    if (raw !== null) {
-      let agile;
-      try {
-        agile = JSON.parse(raw).outputPaths?.agile ?? '.planr';
-      } catch (error) {
-        throw new Error(`Project config ${configPath} is not valid JSON: ${error.message}`);
-      }
-      if (typeof agile !== 'string') throw new Error(`Project config ${configPath} has a non-string outputPaths.agile.`);
-      return { configPath, expected: resolve(current, agile, 'specs') };
-    }
-    if (dirname(current) === current) return null;
-  }
-}
-
-/** Accepts only an existing directory that the nearest project config names as its planning folder. */
-async function assertPlanningRoot(planningRoot) {
-  const project = await configuredRoot(planningRoot);
-  if (!project) {
-    throw new Error(`Planning root ${planningRoot} is not inside an OpenPlanr project: no .planr/config.json in it or any parent directory.`);
-  }
-  const { configPath, expected } = project;
-  if (planningRoot !== expected) {
-    throw new Error(`Planning root ${planningRoot} is not the planning folder configured by ${configPath}, which expects ${expected}.`);
-  }
-  const status = await stat(planningRoot).catch((error) => {
-    if (error.code === 'ENOENT') return null;
-    throw error;
-  });
-  if (!status) {
-    throw new Error(
-      `Planning root ${planningRoot} does not exist; ${configPath} expects it. Create it with \`mkdir -p ${shellQuote(planningRoot)}\`, or fix outputPaths.agile in ${configPath}.`,
-    );
-  }
-  if (!status.isDirectory()) throw new Error(`Planning root ${planningRoot} is not a directory; ${configPath} expects a directory there.`);
-}
-
-async function reserve({ root, preview, counts }) {
-  const planningRoot = resolve(root);
-  await assertPlanningRoot(planningRoot);
-  const run = async () => {
-    const sequence = await currentSequence(planningRoot);
-    const ids = Object.fromEntries(
-      KINDS.map((kind) => [kind, Array.from(
-        { length: counts[kind] },
-        (_, index) => format(kind, sequence.next[kind] + index),
-      )]),
-    );
-    if (!preview) {
-      for (const kind of KINDS) sequence.next[kind] += counts[kind];
-      const temporary = resolve(planningRoot, `.id-sequence.${process.pid}.${Date.now()}.tmp`);
-      await writeFile(temporary, `${JSON.stringify(sequence, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
-      await rename(temporary, resolve(planningRoot, '.id-sequence.json'));
-    }
-    return { kind: 'planning-id-reservation', schemaVersion: '1.0.0', preview, ids };
-  };
-
-  if (preview) return run();
-  const lockPath = resolve(planningRoot, '.id-sequence.lock');
-  let handle;
-  for (let attempt = 0; attempt < 200; attempt += 1) {
-    try {
-      handle = await open(lockPath, 'wx', 0o600);
-      break;
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-      await wait(25);
-    }
-  }
-  if (!handle) throw new Error('Timed out waiting for the planning ID allocator.');
-  try {
-    return await run();
-  } finally {
-    await handle.close();
-    await unlink(lockPath).catch(() => undefined);
-  }
-}
-
-try {
-  process.stdout.write(`${JSON.stringify(await reserve(parseArgs(process.argv.slice(2))), null, 2)}\n`);
-} catch (error) {
-  process.stderr.write(`E_PLANNING_ID_RESERVATION: ${error.message}\n`);
-  process.exitCode = 1;
-}