tenbo-dashboard 0.8.0 → 0.9.0

package/README.md

@@ -38,6 +38,14 @@ Surfaces the things that would otherwise become tech debt nobody mentions: overs
 The same package ships commands the skill uses behind the scenes — also runnable directly:
 
 ```bash
+npx tenbo-dashboard item show sk-030 --json
+npx tenbo-dashboard item set-status sk-030 done
+npx tenbo-dashboard item add-note sk-030 "Implemented; live verification pending"
+npx tenbo-dashboard item verify sk-030 --status pending_live --evidence "npm test -- --run"
+npx tenbo-dashboard item link-commit sk-030 7fc09a5
+npx tenbo-dashboard items --status done --verification pending_live --json
+npx tenbo-dashboard next --json
+npx tenbo-dashboard context feature --query "help me build X" --json
 npx tenbo-dashboard validate          # Schema + consistency checks
 npx tenbo-dashboard init-check        # Strict completeness check after fresh init
 npx tenbo-dashboard metrics --all     # Recompute scope metrics + health findings
@@ -45,6 +53,12 @@ npx tenbo-dashboard next-id <prefix>  # Allocate next roadmap item ID
 npx tenbo-dashboard --version         # Print the installed version
 ```
 
+Installed packages also expose a shorter `tenbo` binary alias for the same commands.
+
+`context feature` is the agent-facing read path. It returns likely scope/layers,
+matching roadmap items, active work, goal refs, recommended files, and freshness warnings
+as one JSON payload so agents do not have to re-read every roadmap file by hand.
+
 ## What is tenbo?
 
 An AI cofounder that gives your coding assistant persistent project memory — architecture docs, roadmaps, and health signals that survive across sessions. Available as a Claude Code skill and as a Cursor rule package; both editors share the same `.tenbo/` data and the same companion dashboard. The dashboard is the optional visual companion; the skill / rule is the always-on conversational brain.

package/bin/tenbo-dashboard.mjs

@@ -41,6 +41,10 @@ const commands = {
   'init-check': 'scripts/init-check.ts',
   sync: 'scripts/sync.ts',
   archive: 'scripts/archive.ts',
+  item: 'scripts/item.ts',
+  items: 'scripts/items.ts',
+  next: 'scripts/next.ts',
+  context: 'scripts/context.ts',
   hook: 'scripts/hook.ts',
 };
 
@@ -78,6 +82,17 @@ Usage:
   tenbo-dashboard                  Launch the dashboard (http://localhost:5174)
   tenbo-dashboard serve            Same as bare invocation (also: 'start', 'dev')
   tenbo-dashboard sync             Refresh tenbo state after a change (metrics + init-check + validate, surfaces new findings)
+  tenbo-dashboard item show <id> [--json]
+  tenbo-dashboard item set-status <id> <now|next|later|done|dropped> [--json]
+  tenbo-dashboard item add-note <id> "<note>" [--json]
+  tenbo-dashboard item verify <id> --status <not_required|pending_live|verified|failed>
+                                   [--evidence "<text>"] [--note "<text>"] [--json]
+  tenbo-dashboard item link-commit <id> <sha> [--json]
+  tenbo-dashboard items            Query roadmap items [--status <status>]
+                                   [--verification <status>] [--goal <goal>] [--json]
+  tenbo-dashboard next             Show next actionable roadmap items [--json]
+  tenbo-dashboard context feature  Fetch agent planning context for a natural-language request
+                                   --query "<request>" [--json]
   tenbo-dashboard validate         Run validation rules
   tenbo-dashboard init-check       Strict completeness check for fresh init (errors on missing skeletons, file_count:0, etc)
   tenbo-dashboard next-id <prefix> Allocate next roadmap item ID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,8 @@
     "node": ">=18"
   },
   "bin": {
-    "tenbo-dashboard": "./bin/tenbo-dashboard.mjs"
+    "tenbo-dashboard": "./bin/tenbo-dashboard.mjs",
+    "tenbo": "./bin/tenbo-dashboard.mjs"
   },
   "files": [
     "bin/",

package/scripts/bin-output.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-bin-output-'));
+  mkdirSync(path.join(dir, '.git'));
+  mkdirSync(path.join(dir, '.tenbo/scopes/editor/layers/app'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), 'scopes:\n  - id: editor\n    path: apps/editor\n    description: editor scope\ncross_cutting: []\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/architecture.yaml'), 'layers:\n  - id: app\n    name: App\n    description: application layer\n    files: ["src/**"]\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/layers/app/README.md'), '# App\n');
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), '# Overview\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+    'items:',
+    '  - id: ed-001',
+    '    title: Large Output',
+    '    layer: app',
+    '    status: done',
+    '    description: item with a large field',
+    '    risks:',
+    `      - ${'x'.repeat(12_000)}`,
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('bin output', () => {
+  it('flushes large JSON output before exiting', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'items', '--status', 'done', '--json'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload.items[0].item.risks[0]).toHaveLength(12_000);
+  });
+});

package/scripts/cliResult.ts

@@ -0,0 +1,55 @@
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+import { isRoadmapStoreError } from '../src/api/lib/roadmapStore';
+
+export interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export function ok(stdout: string): CliResult {
+  return { stdout, stderr: '', exitCode: 0 };
+}
+
+export function fail(error: string, message: string, json: boolean, retryable = false): CliResult {
+  if (json) {
+    return {
+      stdout: '',
+      stderr: `${JSON.stringify({ ok: false, error, message, retryable })}\n`,
+      exitCode: 1,
+    };
+  }
+  return { stdout: '', stderr: `${message}\n`, exitCode: 1 };
+}
+
+export function serialize(payload: unknown, json: boolean, text: string): CliResult {
+  return ok(json ? `${JSON.stringify(payload, null, 2)}\n` : text);
+}
+
+export function handleCliError(err: unknown, json: boolean): CliResult {
+  if (isRoadmapStoreError(err)) {
+    return fail(err.code, err.message, json, err.retryable);
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return fail('error', message, json);
+}
+
+export function repoRootFromCwd(cwd = process.cwd()): string {
+  return findRepoRoot(cwd) ?? cwd;
+}
+
+export function runMain(result: CliResult): void {
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.exitCode;
+}
+
+export function isMain(importMetaUrl: string): boolean {
+  try {
+    const invoked = process.argv[1] ? new URL(`file://${process.argv[1]}`).pathname : '';
+    const here = new URL(importMetaUrl).pathname;
+    return invoked === here;
+  } catch {
+    return false;
+  }
+}

package/scripts/context.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { runContextCli } from './context';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-context-cli-'));
+  mkdirSync(path.join(dir, '.git'));
+  mkdirSync(path.join(dir, '.tenbo/scopes/dashboard/layers/cli-tools'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), [
+    'scopes:',
+    '  - id: dashboard',
+    '    path: tenbo-dashboard',
+    '    description: dashboard and CLI package',
+    'cross_cutting: []',
+    '',
+  ].join('\n'));
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), [
+    '# Overview',
+    '',
+    '## Product goals',
+    '- **g1**: Give agents holistic context.',
+    '',
+  ].join('\n'));
+  writeFileSync(path.join(dir, '.tenbo/scopes/dashboard/architecture.yaml'), [
+    'layers:',
+    '  - id: cli-tools',
+    '    name: CLI Tools',
+    '    description: Commands for agents to fetch context.',
+    '    files: ["bin/**", "scripts/**"]',
+    '',
+  ].join('\n'));
+  writeFileSync(path.join(dir, '.tenbo/scopes/dashboard/layers/cli-tools/intent.md'), '# CLI Tools\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/dashboard/roadmap.yaml'), [
+    'items:',
+    '  - id: td-010',
+    '    title: Add context command',
+    '    layer: cli-tools',
+    '    status: next',
+    '    goal_ref: [g1]',
+    '    description: Add a context command for feature planning.',
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('context CLI', () => {
+  it('prints feature context as JSON', () => {
+    const result = runContextCli(dir, ['feature', '--query', 'build a context command for agents', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      intent: 'feature',
+      recommendation: {
+        scope: 'dashboard',
+        layers: ['cli-tools'],
+      },
+    });
+    expect(payload.roadmap.matching_items.map((entry: { item: { id: string } }) => entry.item.id)).toEqual(['td-010']);
+  });
+
+  it('rejects feature context requests without a query', () => {
+    const result = runContextCli(dir, ['feature', '--json']);
+
+    expect(result.exitCode).toBe(1);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      ok: false,
+      error: 'invalid_args',
+    });
+  });
+});

package/scripts/context.ts

@@ -0,0 +1,38 @@
+import { resolveFeatureContext } from '../src/api/lib/contextResolver';
+import { fail, handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function readOption(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+export function runContextCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  const command = args.find((arg) => !arg.startsWith('--'));
+
+  try {
+    if (command === 'feature') {
+      const query = readOption(args, '--query');
+      if (!query) return fail('invalid_args', 'Usage: tenbo context feature --query "<request>" [--json]', json);
+      const bundle = resolveFeatureContext(repoRoot, query);
+      return serialize(
+        bundle,
+        json,
+        `${bundle.recommendation.confidence} confidence: ${bundle.recommendation.scope ?? 'unclassified'}${bundle.recommendation.layers.length ? `/${bundle.recommendation.layers.join(',')}` : ''}\n`,
+      );
+    }
+
+    return fail('invalid_args', 'Usage: tenbo context feature --query "<request>" [--json]', json);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runContextCli(repoRootFromCwd(), process.argv.slice(2)));
+}

package/scripts/item.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { runItemCli } from './item';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-item-cli-'));
+  mkdirSync(path.join(dir, '.git'));
+  mkdirSync(path.join(dir, '.tenbo/scopes/editor/layers/app'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), 'scopes:\n  - id: editor\n    path: apps/editor\n    description: editor scope\ncross_cutting: []\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/architecture.yaml'), 'layers:\n  - id: app\n    name: App\n    description: application layer\n    files: ["src/**"]\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/layers/app/README.md'), '# App\n');
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), '# Overview\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+    'items:',
+    '  - id: ed-001',
+    '    title: First',
+    '    layer: app',
+    '    status: next',
+    '    description: first item',
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('item CLI', () => {
+  it('prints canonical JSON for item show --json', () => {
+    const result = runItemCli(dir, ['show', 'ed-001', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      ok: true,
+      item: { id: 'ed-001', status: 'next' },
+      scope: 'editor',
+    });
+  });
+
+  it('sets status and prints concise text by default', () => {
+    const result = runItemCli(dir, ['set-status', 'ed-001', 'done']);
+
+    expect(result).toMatchObject({
+      exitCode: 0,
+      stdout: 'ed-001 status: done\n',
+      stderr: '',
+    });
+  });
+
+  it('sets verification status and evidence', () => {
+    const result = runItemCli(dir, [
+      'verify',
+      'ed-001',
+      '--status',
+      'pending_live',
+      '--evidence',
+      'npm test -- --run',
+      '--json',
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout).item.verification).toMatchObject({
+      status: 'pending_live',
+      evidence: ['npm test -- --run'],
+    });
+  });
+
+  it('returns a structured error for missing items', () => {
+    const result = runItemCli(dir, ['show', 'ed-999', '--json']);
+
+    expect(result.exitCode).toBe(1);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      ok: false,
+      error: 'not_found',
+    });
+  });
+});

package/scripts/item.ts

@@ -0,0 +1,76 @@
+import {
+  addItemNote,
+  findItem,
+  linkItemCommit,
+  setItemStatus,
+  setItemVerification,
+} from '../src/api/lib/roadmapStore';
+import { fail, handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function readOption(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+function readRepeated(args: string[], flag: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === flag && args[i + 1]) out.push(args[i + 1]);
+  }
+  return out;
+}
+
+export function runItemCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  const [command, itemId, value] = args.filter((arg) => arg !== '--json');
+  if (!command || !itemId) return fail('invalid_args', 'Usage: tenbo item <show|set-status|add-note|verify|link-commit> <item-id>', json);
+
+  try {
+    if (command === 'show') {
+      const located = findItem(repoRoot, itemId);
+      return serialize({ ok: true, scope: located.scopeId, item: located.item }, json, `${itemId}: ${located.item.title} (${located.item.status})\n`);
+    }
+
+    if (command === 'set-status') {
+      if (!value) return fail('invalid_args', 'Usage: tenbo item set-status <item-id> <status>', json);
+      const result = setItemStatus(repoRoot, itemId, value);
+      return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} status: ${result.item.status}\n`);
+    }
+
+    if (command === 'add-note') {
+      if (!value) return fail('invalid_args', 'Usage: tenbo item add-note <item-id> <note>', json);
+      const result = addItemNote(repoRoot, itemId, value);
+      return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} note added\n`);
+    }
+
+    if (command === 'verify') {
+      const status = readOption(args, '--status');
+      if (!status) return fail('invalid_args', 'Usage: tenbo item verify <item-id> --status <status> [--evidence <text>] [--note <text>]', json);
+      const result = setItemVerification(repoRoot, itemId, {
+        status,
+        evidence: readRepeated(args, '--evidence'),
+        note: readOption(args, '--note'),
+      });
+      return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} verification: ${result.item.verification?.status}\n`);
+    }
+
+    if (command === 'link-commit') {
+      if (!value) return fail('invalid_args', 'Usage: tenbo item link-commit <item-id> <sha>', json);
+      const result = linkItemCommit(repoRoot, itemId, value);
+      return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} linked commit: ${value}\n`);
+    }
+
+    return fail('invalid_args', `unknown item command: ${command}`, json);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runItemCli(repoRootFromCwd(), process.argv.slice(2)));
+}

package/scripts/items.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { runItemsCli } from './items';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-items-cli-'));
+  mkdirSync(path.join(dir, '.git'));
+  mkdirSync(path.join(dir, '.tenbo/scopes/editor/layers/app'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), 'scopes:\n  - id: editor\n    path: apps/editor\n    description: editor scope\ncross_cutting: []\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/architecture.yaml'), 'layers:\n  - id: app\n    name: App\n    description: application layer\n    files: ["src/**"]\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/layers/app/README.md'), '# App\n');
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), '# Overview\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+    'items:',
+    '  - id: ed-001',
+    '    title: First',
+    '    layer: app',
+    '    status: done',
+    '    description: first item',
+    '    verification:',
+    '      status: pending_live',
+    '      updated_at: 2026-06-14T10:00:00.000Z',
+    '  - id: ed-002',
+    '    title: Second',
+    '    layer: app',
+    '    status: next',
+    '    description: second item',
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('items CLI', () => {
+  it('filters by status and verification status as JSON', () => {
+    const result = runItemsCli(dir, ['--status', 'done', '--verification', 'pending_live', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload.items.map((entry: { item: { id: string } }) => entry.item.id)).toEqual(['ed-001']);
+  });
+});

package/scripts/items.ts

@@ -0,0 +1,35 @@
+import { listItems, type ListItemFilters } from '../src/api/lib/roadmapStore';
+import { fail, handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function readOption(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+export function runItemsCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  const filters: ListItemFilters = {
+    status: readOption(args, '--status') as ListItemFilters['status'],
+    verification: readOption(args, '--verification') as ListItemFilters['verification'],
+    goal: readOption(args, '--goal'),
+  };
+  try {
+    const items = listItems(repoRoot, filters);
+    return serialize({ ok: true, items }, json, `${items.map((entry) => `${entry.item.id} ${entry.item.status} ${entry.item.title}`).join('\n')}${items.length ? '\n' : ''}`);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.includes('--help')) {
+    runMain(fail('invalid_args', 'Usage: tenbo items [--status <status>] [--verification <status>] [--goal <goal>] [--json]', false));
+  }
+  runMain(runItemsCli(repoRootFromCwd(), args));
+}

package/scripts/next.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { runNextCli } from './next';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-next-cli-'));
+  mkdirSync(path.join(dir, '.git'));
+  mkdirSync(path.join(dir, '.tenbo/scopes/editor/layers/app'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), 'scopes:\n  - id: editor\n    path: apps/editor\n    description: editor scope\ncross_cutting: []\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/architecture.yaml'), 'layers:\n  - id: app\n    name: App\n    description: application layer\n    files: ["src/**"]\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/layers/app/README.md'), '# App\n');
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), '# Overview\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+    'items:',
+    '  - id: ed-001',
+    '    title: First',
+    '    layer: app',
+    '    status: later',
+    '    description: first item',
+    '  - id: ed-002',
+    '    title: Second',
+    '    layer: app',
+    '    status: next',
+    '    priority: p0',
+    '    description: second item',
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('next CLI', () => {
+  it('returns next work as JSON', () => {
+    const result = runNextCli(dir, ['--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload.items.map((entry: { item: { id: string } }) => entry.item.id)).toEqual(['ed-002']);
+  });
+});

package/scripts/next.ts

@@ -0,0 +1,16 @@
+import { listNextItems } from '../src/api/lib/roadmapStore';
+import { handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+export function runNextCli(repoRoot: string, args: string[]): CliResult {
+  const json = args.includes('--json');
+  try {
+    const items = listNextItems(repoRoot);
+    return serialize({ ok: true, items }, json, `${items.map((entry) => `${entry.item.id} ${entry.item.status} ${entry.item.title}`).join('\n')}${items.length ? '\n' : ''}`);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runNextCli(repoRootFromCwd(), process.argv.slice(2)));
+}