tenbo-dashboard 0.9.0 → 0.10.0

package/bin/tenbo-dashboard.mjs

@@ -41,9 +41,12 @@ const commands = {
   'init-check': 'scripts/init-check.ts',
   sync: 'scripts/sync.ts',
   archive: 'scripts/archive.ts',
+  'commit-ready': 'scripts/commit-ready.ts',
   item: 'scripts/item.ts',
   items: 'scripts/items.ts',
+  list: 'scripts/items.ts',
   next: 'scripts/next.ts',
+  'work-queue': 'scripts/work-queue.ts',
   context: 'scripts/context.ts',
   hook: 'scripts/hook.ts',
 };
@@ -89,8 +92,13 @@ Usage:
                                    [--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]
+                                   [--verification <status>] [--goal <goal>]
+                                   [--type <type>] [--priority <p0|p1|p2|p3>]
+                                   [--layer <id>] [--fields <a,b>] [--summary] [--json]
+  tenbo-dashboard list             Alias for items
   tenbo-dashboard next             Show next actionable roadmap items [--json]
+  tenbo-dashboard work-queue       Compact agent task flow [--status <a,b>]
+                                   [--type <type>] [--json]
   tenbo-dashboard context feature  Fetch agent planning context for a natural-language request
                                    --query "<request>" [--json]
   tenbo-dashboard validate         Run validation rules
@@ -102,6 +110,8 @@ Usage:
   tenbo-dashboard hook install     Install opt-in pre-commit validation hook
                                    [--dry-run] [--force]
   tenbo-dashboard hook uninstall   Remove the tenbo pre-commit hook (idempotent)
+  tenbo-dashboard commit-ready     Report branch, diff, validation, and staging gates
+                                   without committing [--json]
   tenbo-dashboard --version        Print package version
   tenbo-dashboard help             Show this help
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",

package/scripts/bin-output.test.ts

@@ -42,4 +42,18 @@ describe('bin output', () => {
     const payload = JSON.parse(result.stdout);
     expect(payload.items[0].item.risks[0]).toHaveLength(12_000);
   });
+
+  it('supports list as an alias for items', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'list', '--status', 'done', '--fields', 'id,title,status', '--json'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).items).toEqual([
+      { id: 'ed-001', title: 'Large Output', status: 'done' },
+    ]);
+  });
 });

package/scripts/cliArgs.ts

@@ -0,0 +1,30 @@
+export function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+export function readOption(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+export 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 positionalArgs(args: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      if (args[i + 1] && !args[i + 1].startsWith('--')) i++;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}

package/scripts/cliResult.ts

@@ -11,15 +11,19 @@ export function ok(stdout: string): CliResult {
   return { stdout, stderr: '', exitCode: 0 };
 }
 
-export function fail(error: string, message: string, json: boolean, retryable = false): CliResult {
+export function fail(error: string, message: string, json: boolean, retryable = false, exitCode = 1): CliResult {
   if (json) {
     return {
       stdout: '',
       stderr: `${JSON.stringify({ ok: false, error, message, retryable })}\n`,
-      exitCode: 1,
+      exitCode,
     };
   }
-  return { stdout: '', stderr: `${message}\n`, exitCode: 1 };
+  return { stdout: '', stderr: `${message}\n`, exitCode };
+}
+
+export function misuse(message: string, json: boolean): CliResult {
+  return fail('invalid_args', message, json, false, 2);
 }
 
 export function serialize(payload: unknown, json: boolean, text: string): CliResult {

package/scripts/commit-ready.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { runCommitReadyCli } from './commit-ready';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-commit-ready-cli-'));
+  spawnSync('git', ['init', '-q'], { cwd: dir });
+  spawnSync('git', ['checkout', '-q', '-b', 'main'], { cwd: dir });
+  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('commit-ready CLI', () => {
+  it('reports branch, dirty files, diff check, and validation without committing', () => {
+    const result = runCommitReadyCli(dir, ['--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      branch: expect.objectContaining({ current: 'main' }),
+      diff_check: expect.objectContaining({ exitCode: 0 }),
+      validation: expect.objectContaining({ errors: 0 }),
+    });
+    expect(payload.dirty_files.length).toBeGreaterThan(0);
+    expect(payload.recommended_gates).toContain('git diff --check');
+  });
+});

package/scripts/commit-ready.ts

@@ -0,0 +1,69 @@
+import { spawnSync } from 'node:child_process';
+import { readState } from '../src/api/lib/tenboFs';
+import { validate } from '../src/api/lib/validator';
+import { hasFlag } from './cliArgs';
+import { handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+function runGit(repoRoot: string, args: string[]) {
+  const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8' });
+  return {
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function parseStatus(stdout: string): { current: string | null; upstream?: string; dirtyFiles: string[] } {
+  const lines = stdout.split(/\r?\n/).filter(Boolean);
+  const header = lines[0] ?? '';
+  const unbornMatch = header.match(/^## No commits yet on (.+)$/);
+  if (unbornMatch) {
+    return {
+      current: unbornMatch[1],
+      dirtyFiles: lines.slice(1),
+    };
+  }
+  const branchMatch = header.match(/^## ([^.\s]+)(?:\.\.\.([^\s]+))?/);
+  return {
+    current: branchMatch?.[1] ?? null,
+    ...(branchMatch?.[2] ? { upstream: branchMatch[2] } : {}),
+    dirtyFiles: lines.slice(1),
+  };
+}
+
+export function runCommitReadyCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  try {
+    const status = runGit(repoRoot, ['status', '--short', '--branch']);
+    const parsed = parseStatus(status.stdout);
+    const diffCheck = runGit(repoRoot, ['diff', '--check']);
+    const staged = runGit(repoRoot, ['diff', '--cached', '--name-only']);
+    const validation = validate(readState(repoRoot));
+    const payload = {
+      ok: true,
+      branch: {
+        current: parsed.current,
+        upstream: parsed.upstream ?? null,
+      },
+      dirty_files: parsed.dirtyFiles,
+      staged_files: staged.stdout.split(/\r?\n/).filter(Boolean),
+      diff_check: diffCheck,
+      validation: {
+        errors: validation.errors.length,
+        warnings: validation.warnings.length,
+      },
+      recommended_gates: [
+        'git diff --check',
+        'tenbo-dashboard validate',
+        'git diff --cached --check',
+      ],
+    };
+    return serialize(payload, json, `branch: ${payload.branch.current ?? 'unknown'}\ndirty files: ${payload.dirty_files.length}\nvalidation: ${payload.validation.errors} errors, ${payload.validation.warnings} warnings\n`);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runCommitReadyCli(repoRootFromCwd(), process.argv.slice(2)));
+}

package/scripts/context.test.ts

@@ -68,7 +68,7 @@ describe('context CLI', () => {
   it('rejects feature context requests without a query', () => {
     const result = runContextCli(dir, ['feature', '--json']);
 
-    expect(result.exitCode).toBe(1);
+    expect(result.exitCode).toBe(2);
     expect(JSON.parse(result.stderr)).toMatchObject({
       ok: false,
       error: 'invalid_args',

package/scripts/context.ts

@@ -1,15 +1,6 @@
 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];
-}
+import { hasFlag, readOption } from './cliArgs';
+import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
 
 export function runContextCli(repoRoot: string, args: string[]): CliResult {
   const json = hasFlag(args, '--json');
@@ -18,7 +9,7 @@ export function runContextCli(repoRoot: string, args: string[]): CliResult {
   try {
     if (command === 'feature') {
       const query = readOption(args, '--query');
-      if (!query) return fail('invalid_args', 'Usage: tenbo context feature --query "<request>" [--json]', json);
+      if (!query) return misuse('Usage: tenbo context feature --query "<request>" [--json]', json);
       const bundle = resolveFeatureContext(repoRoot, query);
       return serialize(
         bundle,
@@ -27,7 +18,7 @@ export function runContextCli(repoRoot: string, args: string[]): CliResult {
       );
     }
 
-    return fail('invalid_args', 'Usage: tenbo context feature --query "<request>" [--json]', json);
+    return misuse('Usage: tenbo context feature --query "<request>" [--json]', json);
   } catch (err) {
     return handleCliError(err, json);
   }

package/scripts/item.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { tmpdir } from 'node:os';
 import { runItemCli } from './item';
@@ -21,6 +21,13 @@ beforeEach(() => {
     '    layer: app',
     '    status: next',
     '    description: first item',
+    '    type: refactor',
+    '    done_when:',
+    '      - First item lands.',
+    '    files_to_read:',
+    '      - src/app.ts',
+    '    risks:',
+    '      - May overlap active work.',
     '',
   ].join('\n'));
 });
@@ -49,6 +56,67 @@ describe('item CLI', () => {
     });
   });
 
+  it('prints an active task brief as compact JSON', () => {
+    const result = runItemCli(dir, ['brief', 'ed-001', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      item: {
+        id: 'ed-001',
+        title: 'First',
+        status: 'next',
+        type: 'refactor',
+        layer: 'app',
+      },
+      files_to_read: ['src/app.ts'],
+      acceptance_criteria: ['First item lands.'],
+      risks: ['May overlap active work.'],
+    });
+    expect(payload.item).not.toHaveProperty('description');
+  });
+
+  it('prints a handoff prompt for another agent', () => {
+    const result = runItemCli(dir, ['handoff', 'ed-001', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      item_id: 'ed-001',
+    });
+    expect(payload.prompt).toContain('Files to read');
+    expect(payload.prompt).toContain('src/app.ts');
+    expect(payload.prompt).toContain('Acceptance criteria');
+    expect(payload.prompt).toContain('First item lands.');
+    expect(payload.prompt).toContain('Non-goals');
+    expect(payload.prompt).toContain('Completion rules');
+  });
+
+  it('adds a note when existing notes are a YAML sequence', () => {
+    writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+      'items:',
+      '  - id: ed-001',
+      '    title: First',
+      '    layer: app',
+      '    status: next',
+      '    description: first item',
+      '    notes:',
+      '      - Existing list note',
+      '',
+    ].join('\n'));
+
+    const result = runItemCli(dir, ['add-note', 'ed-001', 'Added from CLI', '--json']);
+    const roadmap = readFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), 'utf8');
+    const today = new Date().toISOString().slice(0, 10);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout).item.notes).toContain('- Existing list note');
+    expect(JSON.parse(result.stdout).item.notes).toContain(`- ${today}: Added from CLI`);
+    expect(roadmap).toContain(`- ${today}: Added from CLI`);
+  });
+
   it('sets verification status and evidence', () => {
     const result = runItemCli(dir, [
       'verify',
@@ -67,6 +135,79 @@ describe('item CLI', () => {
     });
   });
 
+  it('checks item evidence without mutating verification metadata', () => {
+    const result = runItemCli(dir, ['verify', 'ed-001', '--check', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      item_id: 'ed-001',
+      verdict: 'likely_open',
+    });
+    expect(findRoadmap()).not.toContain('verification:');
+  });
+
+  it('reports inconsistent evidence for done items missing hygiene fields', () => {
+    writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+      'items:',
+      '  - id: ed-001',
+      '    title: First',
+      '    layer: app',
+      '    status: done',
+      '    description: first item',
+      '',
+    ].join('\n'));
+
+    const result = runItemCli(dir, ['verify', 'ed-001', '--check', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      verdict: 'inconsistent',
+      missing: expect.arrayContaining(['verification', 'doc_update']),
+    });
+  });
+
+  it('sets doc_update from the CLI', () => {
+    const dated = runItemCli(dir, ['doc-update', 'ed-001', '--date', 'today', '--json']);
+    const skipped = runItemCli(dir, ['doc-update', 'ed-001', '--skipped', '--reason', 'No docs changed.', '--json']);
+    const today = new Date().toISOString().slice(0, 10);
+
+    expect(dated.exitCode).toBe(0);
+    expect(JSON.parse(dated.stdout).item.doc_update).toBe(today);
+    expect(skipped.exitCode).toBe(0);
+    expect(JSON.parse(skipped.stdout).item.doc_update).toBe('skipped — No docs changed.');
+  });
+
+  it('completes an item from the CLI in one roadmap transaction', () => {
+    const result = runItemCli(dir, [
+      'complete',
+      'ed-001',
+      '--evidence',
+      'npm test -- --run',
+      '--doc-update',
+      'today',
+      '--commit',
+      'abc123',
+      '--json',
+    ]);
+    const today = new Date().toISOString().slice(0, 10);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload.item).toMatchObject({
+      status: 'done',
+      doc_update: today,
+      links: ['commit:abc123'],
+      verification: {
+        status: 'verified',
+        evidence: ['npm test -- --run'],
+      },
+    });
+    expect(payload.item.notes).toContain(`- ${today}: Completed with evidence: npm test -- --run`);
+    expect(payload.validation).toHaveProperty('errors');
+  });
+
   it('returns a structured error for missing items', () => {
     const result = runItemCli(dir, ['show', 'ed-999', '--json']);
 
@@ -76,4 +217,18 @@ describe('item CLI', () => {
       error: 'not_found',
     });
   });
+
+  it('returns misuse exit code for unknown item commands', () => {
+    const result = runItemCli(dir, ['unknown', 'ed-001', '--json']);
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      ok: false,
+      error: 'invalid_args',
+    });
+  });
 });
+
+function findRoadmap(): string {
+  return readFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), 'utf8');
+}

package/scripts/item.ts

@@ -1,34 +1,21 @@
 import {
   addItemNote,
+  completeItem,
   findItem,
   linkItemCommit,
+  setItemDocUpdate,
   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;
-}
+import { summarizeItem } from '../src/api/lib/itemProjection';
+import { checkItemEvidence } from '../src/api/lib/itemEvidence';
+import { hasFlag, positionalArgs, readOption, readRepeated } from './cliArgs';
+import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
 
 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);
+  const [command, itemId, value] = positionalArgs(args);
+  if (!command || !itemId) return misuse('Usage: tenbo item <show|set-status|add-note|verify|link-commit> <item-id>', json);
 
   try {
     if (command === 'show') {
@@ -36,21 +23,77 @@ export function runItemCli(repoRoot: string, args: string[]): CliResult {
       return serialize({ ok: true, scope: located.scopeId, item: located.item }, json, `${itemId}: ${located.item.title} (${located.item.status})\n`);
     }
 
+    if (command === 'brief') {
+      const located = findItem(repoRoot, itemId);
+      const item = located.item;
+      return serialize({
+        ok: true,
+        scope: located.scopeId,
+        item: summarizeItem(located),
+        files_to_read: item.files_to_read ?? [],
+        acceptance_criteria: item.done_when ?? [],
+        risks: item.risks ?? [],
+        verification_commands: [
+          `tenbo-dashboard item verify ${item.id} --check --json`,
+        ],
+        completion_commands: [
+          `tenbo-dashboard item complete ${item.id} --evidence "<evidence>" --doc-update today --json`,
+        ],
+      }, json, `${item.id}: ${item.title} (${item.status})\n`);
+    }
+
+    if (command === 'handoff') {
+      const located = findItem(repoRoot, itemId);
+      const item = located.item;
+      const files = item.files_to_read?.length ? item.files_to_read.map((file) => `- ${file}`).join('\n') : '- Read the linked item/spec first.';
+      const criteria = item.done_when?.length ? item.done_when.map((entry) => `- ${entry}`).join('\n') : '- Satisfy the roadmap item description.';
+      const risks = item.risks?.length ? item.risks.map((entry) => `- ${entry}`).join('\n') : '- No known overlap risks recorded.';
+      const prompt = [
+        `Implement ${item.id}: ${item.title}`,
+        '',
+        'Files to read',
+        files,
+        '',
+        'Non-goals',
+        '- Do not broaden scope beyond this roadmap item.',
+        '- Do not edit unrelated roadmap items or user changes.',
+        '',
+        'Overlap risks',
+        risks,
+        '',
+        'Acceptance criteria',
+        criteria,
+        '',
+        'Verification commands',
+        `- tenbo-dashboard item verify ${item.id} --check --json`,
+        '- Run focused tests for touched code.',
+        '',
+        'Completion rules',
+        `- Use tenbo-dashboard item complete ${item.id} --evidence "<evidence>" --doc-update today --json when the item is actually complete.`,
+        '- Report tests run and any residual risks.',
+      ].join('\n');
+      return serialize({ ok: true, item_id: item.id, scope: located.scopeId, prompt }, json, `${prompt}\n`);
+    }
+
     if (command === 'set-status') {
-      if (!value) return fail('invalid_args', 'Usage: tenbo item set-status <item-id> <status>', json);
+      if (!value) return misuse('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);
+      if (!value) return misuse('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') {
+      if (hasFlag(args, '--check')) {
+        const report = checkItemEvidence(repoRoot, itemId);
+        return serialize(report, json, `${itemId} evidence: ${report.verdict}\n`);
+      }
       const status = readOption(args, '--status');
-      if (!status) return fail('invalid_args', 'Usage: tenbo item verify <item-id> --status <status> [--evidence <text>] [--note <text>]', json);
+      if (!status) return misuse('Usage: tenbo item verify <item-id> --status <status> [--evidence <text>] [--note <text>]', json);
       const result = setItemVerification(repoRoot, itemId, {
         status,
         evidence: readRepeated(args, '--evidence'),
@@ -59,13 +102,42 @@ export function runItemCli(repoRoot: string, args: string[]): CliResult {
       return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} verification: ${result.item.verification?.status}\n`);
     }
 
+    if (command === 'doc-update') {
+      const date = readOption(args, '--date');
+      const skipped = hasFlag(args, '--skipped');
+      const reason = readOption(args, '--reason');
+      if (!date && !skipped) return misuse('Usage: tenbo item doc-update <item-id> --date <today|YYYY-MM-DD> OR --skipped --reason "<text>"', json);
+      if (skipped && !reason) return misuse('Usage: tenbo item doc-update <item-id> --skipped --reason "<text>"', json);
+      const today = new Date().toISOString().slice(0, 10);
+      const docUpdate = skipped ? `skipped — ${reason}` : date === 'today' ? today : date;
+      const result = setItemDocUpdate(repoRoot, itemId, docUpdate ?? today);
+      return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} doc_update: ${result.item.doc_update}\n`);
+    }
+
+    if (command === 'complete') {
+      const evidence = readRepeated(args, '--evidence');
+      const docUpdateArg = readOption(args, '--doc-update');
+      const commit = readOption(args, '--commit');
+      const verificationStatus = readOption(args, '--verification');
+      if (evidence.length === 0) return misuse('Usage: tenbo item complete <item-id> --evidence "<text>" [--doc-update today|YYYY-MM-DD] [--commit <sha>] [--verification <status>]', json);
+      const today = new Date().toISOString().slice(0, 10);
+      const docUpdate = docUpdateArg === 'today' ? today : docUpdateArg;
+      const result = completeItem(repoRoot, itemId, {
+        evidence,
+        ...(docUpdate ? { docUpdate } : {}),
+        ...(commit ? { commit } : {}),
+        ...(verificationStatus ? { verificationStatus } : {}),
+      });
+      return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} completed\n`);
+    }
+
     if (command === 'link-commit') {
-      if (!value) return fail('invalid_args', 'Usage: tenbo item link-commit <item-id> <sha>', json);
+      if (!value) return misuse('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);
+    return misuse(`unknown item command: ${command}`, json);
   } catch (err) {
     return handleCliError(err, json);
   }

package/scripts/items.test.ts

@@ -28,7 +28,20 @@ beforeEach(() => {
     '    title: Second',
     '    layer: app',
     '    status: next',
+    '    type: feature',
     '    description: second item',
+    '    notes: |',
+    '      - 2026-06-14: Long implementation note that summary should not dump wholesale.',
+    '  - id: ed-003',
+    '    title: Third',
+    '    layer: app',
+    '    status: later',
+    '    type: refactor',
+    '    priority: p1',
+    '    description: third item',
+    '    verification:',
+    '      status: verified',
+    '      updated_at: 2026-06-15T10:00:00.000Z',
     '',
   ].join('\n'));
 });
@@ -43,4 +56,57 @@ describe('items CLI', () => {
     const payload = JSON.parse(result.stdout);
     expect(payload.items.map((entry: { item: { id: string } }) => entry.item.id)).toEqual(['ed-001']);
   });
+
+  it('filters by type and comma-separated statuses with selected fields', () => {
+    const result = runItemsCli(dir, [
+      '--type',
+      'refactor',
+      '--status',
+      'next,later',
+      '--fields',
+      'id,title,status,priority,layer,verification',
+      '--json',
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload.items).toEqual([
+      {
+        id: 'ed-003',
+        title: 'Third',
+        status: 'later',
+        priority: 'p1',
+        layer: 'app',
+        verification: 'verified',
+      },
+    ]);
+  });
+
+  it('returns compact summaries without changing full JSON by default', () => {
+    const summary = runItemsCli(dir, ['--status', 'next', '--summary', '--json']);
+    const full = runItemsCli(dir, ['--status', 'next', '--json']);
+
+    expect(summary.exitCode).toBe(0);
+    expect(JSON.parse(summary.stdout).items).toEqual([
+      expect.objectContaining({
+        id: 'ed-002',
+        title: 'Second',
+        status: 'next',
+        type: 'feature',
+        layer: 'app',
+      }),
+    ]);
+    expect(JSON.parse(summary.stdout).items[0]).not.toHaveProperty('description');
+    expect(JSON.parse(full.stdout).items[0].item.description).toBe('second item');
+  });
+
+  it('returns misuse errors for invalid status lists and fields', () => {
+    const badStatus = runItemsCli(dir, ['--status', 'next,unknown', '--json']);
+    const badField = runItemsCli(dir, ['--fields', 'id,nope', '--json']);
+
+    expect(badStatus.exitCode).toBe(2);
+    expect(JSON.parse(badStatus.stderr)).toMatchObject({ ok: false, error: 'invalid_args' });
+    expect(badField.exitCode).toBe(2);
+    expect(JSON.parse(badField.stderr)).toMatchObject({ ok: false, error: 'invalid_args' });
+  });
 });

package/scripts/items.ts

@@ -1,27 +1,47 @@
 import { listItems, type ListItemFilters } from '../src/api/lib/roadmapStore';
-import { fail, handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+import { parseItemFields, projectItem, summarizeItem } from '../src/api/lib/itemProjection';
+import { hasFlag, readOption } from './cliArgs';
+import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
 
-function hasFlag(args: string[], flag: string): boolean {
-  return args.includes(flag);
-}
+const STATUSES = new Set(['now', 'next', 'later', 'done', 'dropped']);
 
-function readOption(args: string[], flag: string): string | undefined {
-  const i = args.indexOf(flag);
-  if (i === -1) return undefined;
-  return args[i + 1];
+function readStatusFilter(value: string | undefined): ListItemFilters['status'] {
+  if (!value) return undefined;
+  const statuses = value.split(',').map((status) => status.trim()).filter(Boolean);
+  for (const status of statuses) {
+    if (!STATUSES.has(status)) throw new Error(`invalid status: ${status}`);
+  }
+  return statuses as ListItemFilters['status'];
 }
 
 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'),
-  };
+  const summary = hasFlag(args, '--summary');
+  const fieldsArg = readOption(args, '--fields');
   try {
+    const filters: ListItemFilters = {
+      status: readStatusFilter(readOption(args, '--status')),
+      verification: readOption(args, '--verification') as ListItemFilters['verification'],
+      goal: readOption(args, '--goal'),
+      type: readOption(args, '--type') as ListItemFilters['type'],
+      priority: readOption(args, '--priority') as ListItemFilters['priority'],
+      layer: readOption(args, '--layer'),
+    };
     const items = listItems(repoRoot, filters);
+    if (fieldsArg) {
+      const fields = parseItemFields(fieldsArg);
+      const projected = items.map((entry) => projectItem(entry, fields));
+      return serialize({ ok: true, items: projected }, json, `${projected.map((entry) => `${entry.id} ${entry.status} ${entry.title}`).join('\n')}${projected.length ? '\n' : ''}`);
+    }
+    if (summary) {
+      const projected = items.map((entry) => summarizeItem(entry));
+      return serialize({ ok: true, items: projected }, json, `${projected.map((entry) => `${entry.id} ${entry.status} ${entry.title}`).join('\n')}${projected.length ? '\n' : ''}`);
+    }
     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) {
+    if (err instanceof Error && (err.message.startsWith('invalid field:') || err.message.startsWith('invalid status:'))) {
+      return misuse(err.message, json);
+    }
     return handleCliError(err, json);
   }
 }

package/scripts/next.test.ts

@@ -27,6 +27,11 @@ beforeEach(() => {
     '    status: next',
     '    priority: p0',
     '    description: second item',
+    '    type: refactor',
+    '    done_when:',
+    '      - Next work lands.',
+    '    files_to_read:',
+    '      - src/next.ts',
     '',
   ].join('\n'));
 });
@@ -41,4 +46,22 @@ describe('next CLI', () => {
     const payload = JSON.parse(result.stdout);
     expect(payload.items.map((entry: { item: { id: string } }) => entry.item.id)).toEqual(['ed-002']);
   });
+
+  it('returns compact agent summary for next work', () => {
+    const result = runNextCli(dir, ['--agent-summary', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload.recommended_sequence).toEqual(['ed-002']);
+    expect(payload.items).toEqual([
+      expect.objectContaining({
+        id: 'ed-002',
+        title: 'Second',
+        status: 'next',
+        type: 'refactor',
+        priority: 'p0',
+      }),
+    ]);
+    expect(payload.items[0]).not.toHaveProperty('description');
+  });
 });

package/scripts/next.ts

@@ -1,10 +1,28 @@
 import { listNextItems } from '../src/api/lib/roadmapStore';
+import { summarizeItem } from '../src/api/lib/itemProjection';
+import { hasFlag } from './cliArgs';
 import { handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
 
 export function runNextCli(repoRoot: string, args: string[]): CliResult {
-  const json = args.includes('--json');
+  const json = hasFlag(args, '--json');
+  const agentSummary = hasFlag(args, '--agent-summary');
   try {
     const items = listNextItems(repoRoot);
+    if (agentSummary) {
+      const projected = items.map((entry) => summarizeItem(entry));
+      return serialize({
+        ok: true,
+        recommended_sequence: projected.map((item) => item.id),
+        items: projected,
+        verification: projected.map((item) => ({
+          id: item.id,
+          commands: [
+            `tenbo-dashboard item brief ${item.id} --json`,
+            `tenbo-dashboard item verify ${item.id} --check --json`,
+          ],
+        })),
+      }, json, `${projected.map((entry) => `${entry.id} ${entry.status} ${entry.title}`).join('\n')}${projected.length ? '\n' : ''}`);
+    }
     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);

package/scripts/work-queue.test.ts

@@ -0,0 +1,65 @@
+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 { runWorkQueueCli } from './work-queue';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-work-queue-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: Active Refactor',
+    '    layer: app',
+    '    status: now',
+    '    type: refactor',
+    '    priority: p2',
+    '    description: active refactor',
+    '    done_when:',
+    '      - Refactor lands.',
+    '    files_to_read:',
+    '      - src/app.ts',
+    '  - id: ed-002',
+    '    title: Later Refactor',
+    '    layer: app',
+    '    status: later',
+    '    type: refactor',
+    '    priority: p1',
+    '    description: later refactor',
+    '  - id: ed-003',
+    '    title: Later Feature',
+    '    layer: app',
+    '    status: later',
+    '    type: feature',
+    '    description: later feature',
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('work-queue CLI', () => {
+  it('returns compact actionable candidates filtered by type and status', () => {
+    const result = runWorkQueueCli(dir, ['--type', 'refactor', '--status', 'now,later', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      recommended_sequence: ['ed-001', 'ed-002'],
+    });
+    expect(payload.items).toEqual([
+      expect.objectContaining({ id: 'ed-001', title: 'Active Refactor', status: 'now', type: 'refactor' }),
+      expect.objectContaining({ id: 'ed-002', title: 'Later Refactor', status: 'later', type: 'refactor' }),
+    ]);
+    expect(payload.items[0]).not.toHaveProperty('description');
+  });
+});

package/scripts/work-queue.ts

@@ -0,0 +1,58 @@
+import { listItems, type ListItemFilters } from '../src/api/lib/roadmapStore';
+import { summarizeItem } from '../src/api/lib/itemProjection';
+import { comparePriority } from '../src/api/lib/priority';
+import { hasFlag, readOption } from './cliArgs';
+import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+const STATUSES = new Set(['now', 'next', 'later', 'done', 'dropped']);
+
+function readStatusFilter(value: string | undefined): ListItemFilters['status'] {
+  if (!value) return ['now', 'next'];
+  const statuses = value.split(',').map((status) => status.trim()).filter(Boolean);
+  for (const status of statuses) {
+    if (!STATUSES.has(status)) throw new Error(`invalid status: ${status}`);
+  }
+  return statuses as ListItemFilters['status'];
+}
+
+function statusRank(status: string): number {
+  return status === 'now' ? 0 : status === 'next' ? 1 : status === 'later' ? 2 : 3;
+}
+
+export function runWorkQueueCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  try {
+    const filters: ListItemFilters = {
+      status: readStatusFilter(readOption(args, '--status')),
+      type: readOption(args, '--type') as ListItemFilters['type'],
+      priority: readOption(args, '--priority') as ListItemFilters['priority'],
+      layer: readOption(args, '--layer'),
+      verification: readOption(args, '--verification') as ListItemFilters['verification'],
+      goal: readOption(args, '--goal'),
+    };
+    const located = listItems(repoRoot, filters)
+      .sort((a, b) => statusRank(a.item.status) - statusRank(b.item.status) || comparePriority(a.item, b.item) || a.item.id.localeCompare(b.item.id));
+    const items = located.map((entry) => summarizeItem(entry));
+    const payload = {
+      ok: true,
+      recommended_sequence: items.map((item) => item.id),
+      blockers: [],
+      items,
+      verification: items.map((item) => ({
+        id: item.id,
+        commands: [
+          `tenbo-dashboard item brief ${item.id} --json`,
+          `tenbo-dashboard item verify ${item.id} --check --json`,
+        ],
+      })),
+    };
+    return serialize(payload, json, `${items.map((item) => `${item.id} ${item.status} ${item.title}`).join('\n')}${items.length ? '\n' : ''}`);
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith('invalid status:')) return misuse(err.message, json);
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runWorkQueueCli(repoRootFromCwd(), process.argv.slice(2)));
+}

package/src/api/lib/itemEvidence.ts

@@ -0,0 +1,49 @@
+import { findItem } from './roadmapStore';
+
+export type ItemEvidenceVerdict = 'likely_done' | 'likely_open' | 'needs_review' | 'inconsistent';
+
+export interface ItemEvidenceReport {
+  ok: true;
+  item_id: string;
+  verdict: ItemEvidenceVerdict;
+  status: string;
+  missing: string[];
+  signals: string[];
+}
+
+export function checkItemEvidence(repoRoot: string, itemId: string): ItemEvidenceReport {
+  const located = findItem(repoRoot, itemId);
+  const item = located.item;
+  const missing: string[] = [];
+  const signals: string[] = [];
+
+  if (item.verification?.status) signals.push(`verification:${item.verification.status}`);
+  if (item.doc_update) signals.push(`doc_update:${item.doc_update}`);
+  if (item.links?.some((link) => link.startsWith('commit:'))) signals.push('commit_link');
+  if (item.notes?.trim()) signals.push('notes');
+  if (item.done_when?.length) signals.push(`done_when:${item.done_when.length}`);
+  if (item.files_to_read?.length) signals.push(`files_to_read:${item.files_to_read.length}`);
+
+  if (item.status === 'done') {
+    if (!item.verification?.status) missing.push('verification');
+    if (!item.doc_update) missing.push('doc_update');
+    return {
+      ok: true,
+      item_id: item.id,
+      verdict: missing.length > 0 ? 'inconsistent' : 'likely_done',
+      status: item.status,
+      missing,
+      signals,
+    };
+  }
+
+  const hasDoneEvidence = item.verification?.status === 'verified' || Boolean(item.doc_update);
+  return {
+    ok: true,
+    item_id: item.id,
+    verdict: hasDoneEvidence ? 'needs_review' : 'likely_open',
+    status: item.status,
+    missing,
+    signals,
+  };
+}

package/src/api/lib/itemProjection.ts

@@ -0,0 +1,79 @@
+import type { Item, Priority, Status, VerificationStatus } from '../../types';
+import type { LocatedItem } from './roadmapStore';
+
+export interface ItemSummaryRecord {
+  id: string;
+  title: string;
+  status: Status;
+  scope: string;
+  layer?: string;
+  layers?: string[];
+  type?: Item['type'];
+  priority?: Priority;
+  verification?: VerificationStatus;
+  risk_count?: number;
+  done_when_count?: number;
+  latest_note?: string;
+}
+
+export const ITEM_FIELD_NAMES = [
+  'id',
+  'title',
+  'status',
+  'scope',
+  'layer',
+  'layers',
+  'type',
+  'priority',
+  'verification',
+  'risk_count',
+  'done_when_count',
+  'latest_note',
+] as const;
+
+export type ItemFieldName = typeof ITEM_FIELD_NAMES[number];
+
+const ITEM_FIELD_SET = new Set<string>(ITEM_FIELD_NAMES);
+
+export function parseItemFields(value: string): ItemFieldName[] {
+  const fields = value.split(',').map((field) => field.trim()).filter(Boolean);
+  for (const field of fields) {
+    if (!ITEM_FIELD_SET.has(field)) throw new Error(`invalid field: ${field}`);
+  }
+  return fields as ItemFieldName[];
+}
+
+function latestNote(notes: string | undefined): string | undefined {
+  if (!notes) return undefined;
+  const lines = notes.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  return lines.at(-1)?.replace(/^- /, '');
+}
+
+export function summarizeItem(entry: LocatedItem): ItemSummaryRecord {
+  const item = entry.item;
+  return {
+    id: item.id,
+    title: item.title,
+    status: item.status,
+    scope: entry.scopeId,
+    ...(item.layer ? { layer: item.layer } : {}),
+    ...(item.layers ? { layers: item.layers } : {}),
+    ...(item.type ? { type: item.type } : {}),
+    ...(item.priority ? { priority: item.priority } : {}),
+    ...(item.verification?.status ? { verification: item.verification.status } : {}),
+    ...(item.risks ? { risk_count: item.risks.length } : {}),
+    ...(item.done_when ? { done_when_count: item.done_when.length } : {}),
+    ...(latestNote(item.notes) ? { latest_note: latestNote(item.notes) } : {}),
+  };
+}
+
+export function projectItem(entry: LocatedItem, fields?: ItemFieldName[]): Partial<ItemSummaryRecord> {
+  const summary = summarizeItem(entry);
+  if (!fields || fields.length === 0) return summary;
+  const projected: Partial<ItemSummaryRecord> = {};
+  for (const field of fields) {
+    const value = summary[field];
+    if (value !== undefined) projected[field] = value as never;
+  }
+  return projected;
+}

package/src/api/lib/roadmapStore.test.ts

@@ -4,10 +4,12 @@ import path from 'node:path';
 import { tmpdir } from 'node:os';
 import {
   addItemNote,
+  completeItem,
   findItem,
   linkItemCommit,
   listItems,
   listNextItems,
+  setItemDocUpdate,
   setItemStatus,
   setItemVerification,
 } from './roadmapStore';
@@ -119,6 +121,33 @@ describe('roadmapStore', () => {
     expect(result.item.links).toEqual(['commit:7fc09a5']);
   });
 
+  it('sets doc_update to a date or skipped reason', () => {
+    const dated = setItemDocUpdate(dir, 'ed-001', '2026-06-28');
+    const skipped = setItemDocUpdate(dir, 'ed-001', 'skipped — No docs changed.');
+
+    expect(dated.item.doc_update).toBe('2026-06-28');
+    expect(skipped.item.doc_update).toBe('skipped — No docs changed.');
+  });
+
+  it('completes an item with evidence, doc update, and commit link in one mutation', () => {
+    const result = completeItem(dir, 'ed-001', {
+      evidence: ['npm test -- --run'],
+      docUpdate: '2026-06-28',
+      commit: 'abc123',
+      now: () => new Date('2026-06-28T12:00:00.000Z'),
+    });
+
+    expect(result.item.status).toBe('done');
+    expect(result.item.doc_update).toBe('2026-06-28');
+    expect(result.item.links).toEqual(['commit:abc123']);
+    expect(result.item.notes).toContain('- 2026-06-28: Completed with evidence: npm test -- --run');
+    expect(result.item.verification).toMatchObject({
+      status: 'verified',
+      evidence: ['npm test -- --run'],
+      updated_at: '2026-06-28T12:00:00.000Z',
+    });
+  });
+
   it('lists next work in status and priority order', () => {
     const items = listNextItems(dir);
 

package/src/api/lib/roadmapStore.ts

@@ -6,7 +6,7 @@ import { readState } from './tenboFs';
 import { invalidate as invalidateCache } from './parseCache';
 import { validate } from './validator';
 import { comparePriority } from './priority';
-import type { Item, Status, VerificationStatus, ValidateResult } from '../../types';
+import type { Item, Priority, Status, VerificationStatus, ValidateResult } from '../../types';
 
 export type RoadmapErrorCode = 'not_found' | 'conflict' | 'invalid_status' | 'invalid_args';
 
@@ -36,9 +36,12 @@ export interface WriteResult {
 }
 
 export interface ListItemFilters {
-  status?: Status;
+  status?: Status | Status[];
   verification?: VerificationStatus;
   goal?: string;
+  type?: Item['type'];
+  priority?: Priority;
+  layer?: string;
 }
 
 interface RoadmapFileRef {
@@ -120,6 +123,19 @@ function validateVerificationStatus(status: string): VerificationStatus {
   throw new RoadmapStoreError('invalid_status', `invalid verification status: ${status}`);
 }
 
+function normalizeNotes(notes: unknown): string {
+  if (!notes) return '';
+  if (typeof notes === 'string') return notes.trimEnd();
+  if (Array.isArray(notes)) {
+    return notes
+      .map((entry) => String(entry).trim())
+      .filter(Boolean)
+      .map((entry) => entry.startsWith('- ') ? entry : `- ${entry}`)
+      .join('\n');
+  }
+  return String(notes).trimEnd();
+}
+
 function mutateItem(
   repoRoot: string,
   itemId: string,
@@ -178,7 +194,8 @@ export function addItemNote(
   const now = opts.now ?? (() => new Date());
   const date = now().toISOString().slice(0, 10);
   return mutateItem(repoRoot, itemId, (item) => {
-    const prefix = item.notes && item.notes.trim().length > 0 ? `${item.notes.trimEnd()}\n` : '';
+    const existing = normalizeNotes(item.notes);
+    const prefix = existing.length > 0 ? `${existing}\n` : '';
     return { notes: `${prefix}- ${date}: ${note}` };
   }, opts);
 }
@@ -213,12 +230,58 @@ export function linkItemCommit(repoRoot: string, itemId: string, commit: string,
   }, opts);
 }
 
+export function setItemDocUpdate(repoRoot: string, itemId: string, docUpdate: string, opts?: MutationOptions): WriteResult {
+  return mutateItem(repoRoot, itemId, () => ({ doc_update: docUpdate }), opts);
+}
+
+export function completeItem(
+  repoRoot: string,
+  itemId: string,
+  opts: MutationOptions & {
+    evidence: string[];
+    docUpdate?: string;
+    commit?: string;
+    verificationStatus?: VerificationStatus | string;
+    now?: () => Date;
+  },
+): WriteResult {
+  const now = opts.now ?? (() => new Date());
+  const date = now().toISOString().slice(0, 10);
+  const updatedAt = now().toISOString();
+  const status = validateVerificationStatus(opts.verificationStatus ?? 'verified');
+  return mutateItem(repoRoot, itemId, (item) => {
+    const existingNotes = normalizeNotes(item.notes);
+    const evidenceText = opts.evidence.length ? opts.evidence.join('; ') : 'No evidence supplied';
+    const note = `- ${date}: Completed with evidence: ${evidenceText}`;
+    const links = item.links ?? [];
+    const commitLink = opts.commit ? `commit:${opts.commit}` : undefined;
+    return {
+      status: 'done',
+      notes: existingNotes ? `${existingNotes}\n${note}` : note,
+      verification: {
+        status,
+        updated_at: updatedAt,
+        ...(opts.evidence.length ? { evidence: opts.evidence } : {}),
+      },
+      ...(opts.docUpdate ? { doc_update: opts.docUpdate } : {}),
+      ...(commitLink ? { links: links.includes(commitLink) ? links : [...links, commitLink] } : {}),
+    };
+  }, opts);
+}
+
 export function listItems(repoRoot: string, filters: ListItemFilters = {}): LocatedItem[] {
   const out: LocatedItem[] = [];
+  const statuses = Array.isArray(filters.status) ? filters.status : filters.status ? [filters.status] : [];
   for (const ref of readRoadmapRefs(repoRoot)) {
     for (const item of ref.items) {
-      if (filters.status && item.status !== filters.status) continue;
+      if (statuses.length > 0 && !statuses.includes(item.status)) continue;
       if (filters.verification && item.verification?.status !== filters.verification) continue;
+      if (filters.type && item.type !== filters.type) continue;
+      if (filters.priority && item.priority !== filters.priority) continue;
+      if (filters.layer) {
+        const layerRefs = [item.layer, ...(item.layers ?? []), ...(item.affects ?? [])].filter(Boolean);
+        if (!layerRefs.includes(filters.layer)) continue;
+      }
       if (filters.goal) {
         const goalRef = item.goal_ref;
         const matchesGoal = Array.isArray(goalRef) ? goalRef.includes(filters.goal) : goalRef === filters.goal;