tenbo-dashboard 0.9.0 → 0.10.1

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.1",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",

package/scripts/bin-output.test.ts

@@ -42,4 +42,33 @@ 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' },
+    ]);
+  });
+
+  it('prints items help without running the query', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'items', '--help'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).toContain('Usage: tenbo-dashboard items');
+    expect(result.stdout).toContain('--fields <a,b>');
+    expect(result.stdout).not.toContain('ed-001');
+  });
 });

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);
   }