@taskset/cli 3.0.3 → 5.1.0

package/dist/cli.js

@@ -1,7 +1,8 @@
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { TaskIdSchema, TaskPrioritySchema, TaskRiskSchema, TaskStatusSchema, TaskTimestampSchema, } from '@taskset/contracts';
-import { buildTaskIndex, createSnapshot, createTask, deleteTask, diagnoseRepository, discoverRepository, generateViews, initializeRepository, listSnapshots, normalizeRepositoryPath, queryTasks, RepositoryPathError, readTask, restoreSnapshot, serializeTaskFile, TASK_SORT_DIRECTIONS, TASK_SORT_KEYS, TaskQuerySchema, updateTask, } from '@taskset/core';
+import { DocumentIdSchema, DocumentStatusSchema, DocumentTimestampSchema, TaskIdSchema, TaskPrioritySchema, TaskRiskSchema, TaskStatusSchema, TaskTimestampSchema, } from '@taskset/contracts';
+import { buildDocumentGraph, buildTaskIndex, createDocument, createSnapshot, createTask, DOCUMENT_SORT_DIRECTIONS, DOCUMENT_SORT_KEYS, DocumentQuerySchema, deleteDocument, deleteTask, diagnoseRepository, discoverRepository, executeDocumentBatch, generateViews, importDocument, initializeRepository, listDocuments, listSnapshots, migrateTaskIds, normalizeDocumentKind, normalizeRepositoryPath, queryDocuments, queryTasks, RepositoryPathError, readDocument, readTask, restoreSnapshot, serializeDocumentFile, serializeTaskFile, syncRepository, TASK_SORT_DIRECTIONS, TASK_SORT_KEYS, TaskQuerySchema, updateDocument, updateTask, } from '@taskset/core';
 import * as z from 'zod';
 const USAGE = `Usage:
   taskset init [--cwd <path>]
@@ -16,12 +17,22 @@ const USAGE = `Usage:
   taskset task update <task-id> [metadata options]
   taskset task status <task-id> <status> [--json] [--cwd <path>]
   taskset task delete <task-id> [--remove-dependencies] [--json] [--cwd <path>]
+  taskset task migrate-ids [--json] [--cwd <path>]
+  taskset sync [--concurrency <count>] [--json] [--cwd <path>]
+  taskset document create <story|flow|decision|adr|dr|research|runbook> --title <title> [metadata options]
+  taskset document import <markdown-path> [--type <type>] [--move]
+  taskset document batch <manifest.json> [--concurrency <count>] [--json]
+  taskset document list [type] [query options]
+  taskset document show <document-id> [--type <type>] [--include-derived] [--json]
+  taskset document update <document-id> [metadata options] [--type <type>]
+  taskset document status <document-id> <status> [--type <type>] [--json]
+  taskset document delete <document-id> [--type <type>] [--remove-dependencies] [--json]
 
 Metadata options:
   --status --priority --order --owner --team --estimate --effort --risk --due-date
   --label --assignee --reviewer --depends-on --related --duplicate
   --parent --file --directory --project --body
-  Repeat array options. Task updates clear arrays with --clear-dependencies,
+  Repeat array options. Task and document updates clear arrays with --clear-dependencies,
   --clear-labels, --clear-assignees, --clear-reviewers, --clear-related,
   --clear-files, --clear-directories, or --clear-projects. Clear scalar
   relationships with --clear-parent or --clear-owner.
@@ -56,31 +67,97 @@ const CommonValuesSchema = z.strictObject({
     cwd: CwdSchema,
     json: JsonSchema,
 });
-const CreateValuesSchema = z.strictObject({
+const ConcurrencySchema = z.coerce.number().int().min(1).max(32).optional();
+const DocumentKindInputSchema = TrimmedStringSchema.transform((value, context) => {
+    try {
+        return normalizeDocumentKind(value);
+    }
+    catch (error) {
+        context.addIssue({
+            code: 'custom',
+            message: error instanceof Error ? error.message : 'Invalid document type',
+        });
+        return z.NEVER;
+    }
+});
+const DocumentInputSchema = z.strictObject({
+    type: DocumentKindInputSchema,
     title: TrimmedStringSchema,
-    status: TaskStatusSchema.optional(),
+    status: DocumentStatusSchema.optional(),
     priority: TaskPrioritySchema.optional(),
-    order: z.coerce.number().finite().nonnegative().optional(),
-    label: StringListSchema.optional(),
-    'depends-on': TaskIdListSchema.optional(),
-    file: StringListSchema.optional(),
+    order: z.number().finite().nonnegative().optional(),
+    labels: StringListSchema.optional(),
+    dependsOn: TaskIdListSchema.optional(),
+    files: StringListSchema.optional(),
     owner: TrimmedStringSchema.optional(),
-    assignee: StringListSchema.optional(),
-    reviewer: StringListSchema.optional(),
+    assignees: StringListSchema.optional(),
+    reviewers: StringListSchema.optional(),
     team: TrimmedStringSchema.optional(),
-    estimate: z.coerce.number().int().nonnegative().optional(),
-    effort: z.coerce.number().finite().nonnegative().optional(),
+    estimate: z.number().int().nonnegative().optional(),
+    effort: z.number().finite().nonnegative().optional(),
     risk: TaskRiskSchema.optional(),
-    'due-date': TaskTimestampSchema.optional(),
+    dueDate: DocumentTimestampSchema.optional(),
     related: TaskIdListSchema.optional(),
-    duplicate: TaskIdListSchema.optional(),
+    duplicates: TaskIdListSchema.optional(),
     parent: TaskIdSchema.optional(),
-    directory: StringListSchema.optional(),
-    project: StringListSchema.optional(),
+    directories: StringListSchema.optional(),
+    projects: StringListSchema.optional(),
     body: z.string().optional(),
-    cwd: CwdSchema,
-    json: JsonSchema,
 });
+const DocumentUpdateSchema = z
+    .strictObject({
+    title: TrimmedStringSchema.optional(),
+    status: DocumentStatusSchema.optional(),
+    priority: TaskPrioritySchema.nullable().optional(),
+    order: z.number().finite().nonnegative().nullable().optional(),
+    labels: StringListSchema.optional(),
+    dependsOn: TaskIdListSchema.optional(),
+    files: StringListSchema.optional(),
+    owner: TrimmedStringSchema.nullable().optional(),
+    assignees: StringListSchema.optional(),
+    reviewers: StringListSchema.optional(),
+    team: TrimmedStringSchema.nullable().optional(),
+    estimate: z.number().int().nonnegative().nullable().optional(),
+    effort: z.number().finite().nonnegative().nullable().optional(),
+    risk: TaskRiskSchema.nullable().optional(),
+    dueDate: DocumentTimestampSchema.nullable().optional(),
+    related: TaskIdListSchema.optional(),
+    duplicates: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.nullable().optional(),
+    directories: StringListSchema.optional(),
+    projects: StringListSchema.optional(),
+    body: z.string().optional(),
+})
+    .refine((input) => Object.keys(input).length > 0, 'Document update requires at least one field');
+const DocumentBatchSchema = z
+    .array(z.discriminatedUnion('action', [
+    z.strictObject({ action: z.literal('create'), input: DocumentInputSchema }),
+    z.strictObject({
+        action: z.literal('import'),
+        sourcePath: TrimmedStringSchema,
+        options: z
+            .strictObject({
+            type: DocumentKindInputSchema.optional(),
+            title: TrimmedStringSchema.optional(),
+            move: z.boolean().optional(),
+        })
+            .optional(),
+    }),
+    z.strictObject({
+        action: z.literal('update'),
+        id: TrimmedStringSchema,
+        type: DocumentKindInputSchema.optional(),
+        input: DocumentUpdateSchema,
+    }),
+    z.strictObject({
+        action: z.literal('export'),
+        id: TrimmedStringSchema,
+        type: DocumentKindInputSchema.optional(),
+        targetPath: TrimmedStringSchema,
+        overwrite: z.boolean().optional(),
+    }),
+]))
+    .min(1);
 const UPDATE_CLEAR_PAIRS = [
     ['priority', 'clear-priority'],
     ['order', 'clear-order'],
@@ -101,6 +178,153 @@ const UPDATE_CLEAR_PAIRS = [
     ['directory', 'clear-directories'],
     ['project', 'clear-projects'],
 ];
+const DocumentCreateValuesSchema = z.strictObject({
+    title: TrimmedStringSchema,
+    status: DocumentStatusSchema.optional(),
+    priority: TaskPrioritySchema.optional(),
+    order: z.coerce.number().finite().nonnegative().optional(),
+    label: StringListSchema.optional(),
+    'depends-on': TaskIdListSchema.optional(),
+    file: StringListSchema.optional(),
+    owner: TrimmedStringSchema.optional(),
+    assignee: StringListSchema.optional(),
+    reviewer: StringListSchema.optional(),
+    team: TrimmedStringSchema.optional(),
+    estimate: z.coerce.number().int().nonnegative().optional(),
+    effort: z.coerce.number().finite().nonnegative().optional(),
+    risk: TaskRiskSchema.optional(),
+    'due-date': DocumentTimestampSchema.optional(),
+    related: TaskIdListSchema.optional(),
+    duplicate: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    directory: StringListSchema.optional(),
+    project: StringListSchema.optional(),
+    body: z.string().optional(),
+    cwd: CwdSchema,
+    json: JsonSchema,
+});
+const DocumentUpdateValuesSchema = z
+    .strictObject({
+    title: TrimmedStringSchema.optional(),
+    status: DocumentStatusSchema.optional(),
+    priority: TaskPrioritySchema.optional(),
+    order: z.coerce.number().finite().nonnegative().optional(),
+    label: StringListSchema.optional(),
+    'depends-on': TaskIdListSchema.optional(),
+    file: StringListSchema.optional(),
+    owner: TrimmedStringSchema.optional(),
+    assignee: StringListSchema.optional(),
+    reviewer: StringListSchema.optional(),
+    team: TrimmedStringSchema.optional(),
+    estimate: z.coerce.number().int().nonnegative().optional(),
+    effort: z.coerce.number().finite().nonnegative().optional(),
+    risk: TaskRiskSchema.optional(),
+    'due-date': DocumentTimestampSchema.optional(),
+    related: TaskIdListSchema.optional(),
+    duplicate: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    directory: StringListSchema.optional(),
+    project: StringListSchema.optional(),
+    body: z.string().optional(),
+    type: TrimmedStringSchema.optional(),
+    'clear-priority': z.boolean().optional(),
+    'clear-order': z.boolean().optional(),
+    'clear-labels': z.boolean().optional(),
+    'clear-dependencies': z.boolean().optional(),
+    'clear-files': z.boolean().optional(),
+    'clear-owner': z.boolean().optional(),
+    'clear-assignees': z.boolean().optional(),
+    'clear-reviewers': z.boolean().optional(),
+    'clear-team': z.boolean().optional(),
+    'clear-estimate': z.boolean().optional(),
+    'clear-effort': z.boolean().optional(),
+    'clear-risk': z.boolean().optional(),
+    'clear-due-date': z.boolean().optional(),
+    'clear-related': z.boolean().optional(),
+    'clear-duplicates': z.boolean().optional(),
+    'clear-parent': z.boolean().optional(),
+    'clear-directories': z.boolean().optional(),
+    'clear-projects': z.boolean().optional(),
+    cwd: CwdSchema,
+    json: JsonSchema,
+})
+    .superRefine((values, context) => {
+    for (const [valueKey, clearKey] of UPDATE_CLEAR_PAIRS) {
+        if (values[valueKey] !== undefined && values[clearKey]) {
+            context.addIssue({
+                code: 'custom',
+                path: [clearKey],
+                message: `Cannot set and clear ${valueKey} in the same update`,
+            });
+        }
+    }
+    const nonControlKeys = Object.keys(values).filter((key) => key !== 'cwd' && key !== 'json' && key !== 'type');
+    if (nonControlKeys.length === 0) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Document update requires at least one field option',
+        });
+    }
+});
+const DocumentListValuesSchema = z.strictObject({
+    status: z.array(DocumentStatusSchema).optional(),
+    priority: z.array(TaskPrioritySchema).optional(),
+    label: StringListSchema.optional(),
+    owner: StringListSchema.optional(),
+    assignee: StringListSchema.optional(),
+    reviewer: StringListSchema.optional(),
+    team: StringListSchema.optional(),
+    risk: z.array(TaskRiskSchema).optional(),
+    project: StringListSchema.optional(),
+    'depends-on': TaskIdSchema.optional(),
+    related: TaskIdSchema.optional(),
+    duplicate: TaskIdSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    file: StringListSchema.optional(),
+    directory: StringListSchema.optional(),
+    'estimate-min': z.coerce.number().finite().nonnegative().optional(),
+    'estimate-max': z.coerce.number().finite().nonnegative().optional(),
+    'effort-min': z.coerce.number().finite().nonnegative().optional(),
+    'effort-max': z.coerce.number().finite().nonnegative().optional(),
+    'due-before': DocumentTimestampSchema.optional(),
+    'due-after': DocumentTimestampSchema.optional(),
+    'created-before': DocumentTimestampSchema.optional(),
+    'created-after': DocumentTimestampSchema.optional(),
+    'updated-before': DocumentTimestampSchema.optional(),
+    'updated-after': DocumentTimestampSchema.optional(),
+    search: z.string().optional(),
+    sort: z.enum(DOCUMENT_SORT_KEYS).optional(),
+    direction: z.enum(DOCUMENT_SORT_DIRECTIONS).optional(),
+    impact: z.boolean().optional(),
+    'include-derived': z.boolean().optional(),
+    cwd: CwdSchema,
+    json: JsonSchema,
+});
+const CreateValuesSchema = z.strictObject({
+    title: TrimmedStringSchema,
+    status: TaskStatusSchema.optional(),
+    priority: TaskPrioritySchema.optional(),
+    order: z.coerce.number().finite().nonnegative().optional(),
+    label: StringListSchema.optional(),
+    'depends-on': TaskIdListSchema.optional(),
+    file: StringListSchema.optional(),
+    owner: TrimmedStringSchema.optional(),
+    assignee: StringListSchema.optional(),
+    reviewer: StringListSchema.optional(),
+    team: TrimmedStringSchema.optional(),
+    estimate: z.coerce.number().int().nonnegative().optional(),
+    effort: z.coerce.number().finite().nonnegative().optional(),
+    risk: TaskRiskSchema.optional(),
+    'due-date': TaskTimestampSchema.optional(),
+    related: TaskIdListSchema.optional(),
+    duplicate: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    directory: StringListSchema.optional(),
+    project: StringListSchema.optional(),
+    body: z.string().optional(),
+    cwd: CwdSchema,
+    json: JsonSchema,
+});
 const UpdateValuesSchema = z
     .strictObject({
     title: TrimmedStringSchema.optional(),
@@ -263,6 +487,13 @@ function taskRecordJson(record, derived) {
         ...(derived ? { derived } : {}),
     };
 }
+function documentRecordJson(record, derived) {
+    return {
+        relativePath: record.relativePath,
+        ...record.document.metadata,
+        ...(derived ? { derived } : {}),
+    };
+}
 function writeTaskRecord(record, json, stdout) {
     if (json) {
         stdout(`${JSON.stringify(taskRecordJson(record), null, 2)}\n`);
@@ -271,6 +502,14 @@ function writeTaskRecord(record, json, stdout) {
         stdout(`${record.task.metadata.id}\n`);
     }
 }
+function writeDocumentRecord(record, json, stdout) {
+    if (json) {
+        stdout(`${JSON.stringify(documentRecordJson(record), null, 2)}\n`);
+    }
+    else {
+        stdout(`${record.document.metadata.id}\n`);
+    }
+}
 function warningWriter(stderr) {
     return (warning) => stderr(`warning: ${warning.message}\n`);
 }
@@ -374,6 +613,103 @@ function updateInputFromValues(repository, values) {
         ...(values.body !== undefined ? { body: values.body } : {}),
     };
 }
+function documentUpdateInputFromValues(repository, values) {
+    return {
+        ...(values.title !== undefined ? { title: values.title } : {}),
+        ...(values.status !== undefined ? { status: values.status } : {}),
+        ...(values['clear-priority']
+            ? { priority: null }
+            : values.priority !== undefined
+                ? { priority: values.priority }
+                : {}),
+        ...(values['clear-order']
+            ? { order: null }
+            : values.order !== undefined
+                ? { order: values.order }
+                : {}),
+        ...(values['clear-labels']
+            ? { labels: [] }
+            : values.label !== undefined
+                ? { labels: values.label }
+                : {}),
+        ...(values['clear-dependencies']
+            ? { dependsOn: [] }
+            : values['depends-on'] !== undefined
+                ? { dependsOn: values['depends-on'] }
+                : {}),
+        ...(values['clear-files']
+            ? { files: [] }
+            : values.file !== undefined
+                ? { files: normalizeMutationPaths(repository, values.file) }
+                : {}),
+        ...(values['clear-owner']
+            ? { owner: null }
+            : values.owner !== undefined
+                ? { owner: values.owner }
+                : {}),
+        ...(values['clear-assignees']
+            ? { assignees: [] }
+            : values.assignee !== undefined
+                ? { assignees: values.assignee }
+                : {}),
+        ...(values['clear-reviewers']
+            ? { reviewers: [] }
+            : values.reviewer !== undefined
+                ? { reviewers: values.reviewer }
+                : {}),
+        ...(values['clear-team']
+            ? { team: null }
+            : values.team !== undefined
+                ? { team: values.team }
+                : {}),
+        ...(values['clear-estimate']
+            ? { estimate: null }
+            : values.estimate !== undefined
+                ? { estimate: values.estimate }
+                : {}),
+        ...(values['clear-effort']
+            ? { effort: null }
+            : values.effort !== undefined
+                ? { effort: values.effort }
+                : {}),
+        ...(values['clear-risk']
+            ? { risk: null }
+            : values.risk !== undefined
+                ? { risk: values.risk }
+                : {}),
+        ...(values['clear-due-date']
+            ? { dueDate: null }
+            : values['due-date'] !== undefined
+                ? { dueDate: values['due-date'] }
+                : {}),
+        ...(values['clear-related']
+            ? { related: [] }
+            : values.related !== undefined
+                ? { related: values.related }
+                : {}),
+        ...(values['clear-duplicates']
+            ? { duplicates: [] }
+            : values.duplicate !== undefined
+                ? { duplicates: values.duplicate }
+                : {}),
+        ...(values['clear-parent']
+            ? { parent: null }
+            : values.parent !== undefined
+                ? { parent: values.parent }
+                : {}),
+        ...(values['clear-directories']
+            ? { directories: [] }
+            : values.directory !== undefined
+                ? { directories: normalizeMutationPaths(repository, values.directory) }
+                : {}),
+        ...(values['clear-projects']
+            ? { projects: [] }
+            : values.project !== undefined
+                ? { projects: values.project }
+                : {}),
+        ...(values.body !== undefined ? { body: values.body } : {}),
+    };
+}
 export async function runCli(args, context = {}) {
     const cwd = path.resolve(context.cwd ?? process.cwd());
     const stdout = context.stdout ?? ((value) => process.stdout.write(value));
@@ -443,6 +779,23 @@ export async function runCli(args, context = {}) {
                 : `Generated ${result.files.length} views in ${result.directory}\n`);
             return 0;
         }
+        if (command === 'sync') {
+            const parsed = parseArgs({
+                args: commandArgs,
+                allowPositionals: false,
+                options: { ...commonOptionDefinitions, concurrency: { type: 'string' } },
+            });
+            const values = parseSchema(z.strictObject({ ...CommonValuesSchema.shape, concurrency: ConcurrencySchema }), parsed.values, 'sync options');
+            const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+            const result = await syncRepository(repository, {
+                concurrency: values.concurrency,
+                onProgress: (progress) => stderr(`sync ${progress.phase}: ${progress.completed}/${progress.total} (${progress.percent}%)\n`),
+            });
+            stdout(values.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : `Synced ${result.migrations.length} migrations and generated views\n`);
+            return 0;
+        }
         if (command === 'snapshot') {
             if (subcommand === 'create' || subcommand === 'list') {
                 const parsed = parseArgs({
@@ -497,9 +850,323 @@ export async function runCli(args, context = {}) {
             }
             throw new CliUsageError(`Unknown snapshot command "${subcommand ?? ''}"`);
         }
+        if (command === 'document' || command === 'doc') {
+            if (subcommand === 'batch') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: { ...commonOptionDefinitions, concurrency: { type: 'string' } },
+                });
+                const [manifestPath] = requirePositionals(parsed.positionals, 1, 'exactly one batch manifest path');
+                const values = parseSchema(z.strictObject({ ...CommonValuesSchema.shape, concurrency: ConcurrencySchema }), parsed.values, 'document batch options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const validatedManifestPath = parseSchema(z.string(), manifestPath, 'document batch manifest path');
+                const raw = JSON.parse(await readFile(path.resolve(repository.rootDirectory, validatedManifestPath), 'utf8'));
+                const operations = parseSchema(DocumentBatchSchema, raw, 'document batch manifest');
+                const results = await executeDocumentBatch(repository, operations, {
+                    concurrency: values.concurrency,
+                    onProgress: (progress) => stderr(`document ${progress.action}: ${progress.completed}/${progress.total} (${progress.percent}%)\n`),
+                });
+                stdout(values.json
+                    ? `${JSON.stringify(results, null, 2)}\n`
+                    : `${results.map((result) => result.relativePath).join('\n')}\n`);
+                return 0;
+            }
+            if (subcommand === 'create') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: { ...metadataOptionDefinitions, ...commonOptionDefinitions },
+                });
+                const [rawType] = requirePositionals(parsed.positionals, 1, 'exactly one document type');
+                const values = parseSchema(DocumentCreateValuesSchema, parsed.values, 'document create options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await createDocument(repository, {
+                    type: normalizeDocumentKind(parseSchema(z.string(), rawType, 'document type')),
+                    title: values.title,
+                    ...(values.status ? { status: values.status } : {}),
+                    ...(values.priority ? { priority: values.priority } : {}),
+                    ...(values.order !== undefined ? { order: values.order } : {}),
+                    ...(values.label ? { labels: values.label } : {}),
+                    ...(values['depends-on'] ? { dependsOn: values['depends-on'] } : {}),
+                    ...(values.file ? { files: normalizeMutationPaths(repository, values.file) } : {}),
+                    ...(values.owner ? { owner: values.owner } : {}),
+                    ...(values.assignee ? { assignees: values.assignee } : {}),
+                    ...(values.reviewer ? { reviewers: values.reviewer } : {}),
+                    ...(values.team ? { team: values.team } : {}),
+                    ...(values.estimate !== undefined ? { estimate: values.estimate } : {}),
+                    ...(values.effort !== undefined ? { effort: values.effort } : {}),
+                    ...(values.risk ? { risk: values.risk } : {}),
+                    ...(values['due-date'] ? { dueDate: values['due-date'] } : {}),
+                    ...(values.related ? { related: values.related } : {}),
+                    ...(values.duplicate ? { duplicates: values.duplicate } : {}),
+                    ...(values.parent ? { parent: values.parent } : {}),
+                    ...(values.directory
+                        ? { directories: normalizeMutationPaths(repository, values.directory) }
+                        : {}),
+                    ...(values.project ? { projects: values.project } : {}),
+                    ...(values.body !== undefined ? { body: values.body } : {}),
+                }, { onWarning });
+                writeDocumentRecord(record, values.json, stdout);
+                return 0;
+            }
+            if (subcommand === 'import') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: {
+                        ...commonOptionDefinitions,
+                        type: { type: 'string' },
+                        title: { type: 'string' },
+                        move: { type: 'boolean' },
+                    },
+                });
+                const [sourcePath] = requirePositionals(parsed.positionals, 1, 'exactly one Markdown path');
+                const values = parseSchema(z.strictObject({
+                    type: TrimmedStringSchema.optional(),
+                    title: TrimmedStringSchema.optional(),
+                    move: z.boolean().optional(),
+                    cwd: CwdSchema,
+                    json: JsonSchema,
+                }), parsed.values, 'document import options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await importDocument(repository, parseSchema(z.string(), sourcePath, 'document import path'), {
+                    ...(values.type ? { type: normalizeDocumentKind(values.type) } : {}),
+                    ...(values.title ? { title: values.title } : {}),
+                    move: values.move,
+                });
+                stdout(values.json ? `${JSON.stringify(record, null, 2)}\n` : `${record.relativePath}\n`);
+                return 0;
+            }
+            if (subcommand === 'list') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: {
+                        cwd: { type: 'string' },
+                        json: { type: 'boolean' },
+                        status: { type: 'string', multiple: true },
+                        priority: { type: 'string', multiple: true },
+                        label: { type: 'string', multiple: true },
+                        owner: { type: 'string', multiple: true },
+                        assignee: { type: 'string', multiple: true },
+                        reviewer: { type: 'string', multiple: true },
+                        team: { type: 'string', multiple: true },
+                        risk: { type: 'string', multiple: true },
+                        project: { type: 'string', multiple: true },
+                        'depends-on': { type: 'string' },
+                        related: { type: 'string' },
+                        duplicate: { type: 'string' },
+                        parent: { type: 'string' },
+                        file: { type: 'string', multiple: true },
+                        directory: { type: 'string', multiple: true },
+                        'estimate-min': { type: 'string' },
+                        'estimate-max': { type: 'string' },
+                        'effort-min': { type: 'string' },
+                        'effort-max': { type: 'string' },
+                        'due-before': { type: 'string' },
+                        'due-after': { type: 'string' },
+                        'created-before': { type: 'string' },
+                        'created-after': { type: 'string' },
+                        'updated-before': { type: 'string' },
+                        'updated-after': { type: 'string' },
+                        search: { type: 'string' },
+                        sort: { type: 'string' },
+                        direction: { type: 'string' },
+                        impact: { type: 'boolean' },
+                        'include-derived': { type: 'boolean' },
+                    },
+                });
+                if (parsed.positionals.length > 1)
+                    throw new CliUsageError('Expected at most one document type');
+                const values = parseSchema(DocumentListValuesSchema, parsed.values, 'document list options');
+                const typeFilter = parsed.positionals[0]
+                    ? normalizeDocumentKind(parsed.positionals[0])
+                    : undefined;
+                const query = parseSchema(DocumentQuerySchema, {
+                    ...(typeFilter ? { types: [typeFilter] } : {}),
+                    ...(values.status ? { statuses: values.status } : {}),
+                    ...(values.priority ? { priorities: values.priority } : {}),
+                    ...(values.label ? { labels: values.label } : {}),
+                    ...(values.owner ? { owners: values.owner } : {}),
+                    ...(values.assignee ? { assignees: values.assignee } : {}),
+                    ...(values.reviewer ? { reviewers: values.reviewer } : {}),
+                    ...(values.team ? { teams: values.team } : {}),
+                    ...(values.risk ? { risks: values.risk } : {}),
+                    ...(values.project ? { projects: values.project } : {}),
+                    ...(values['depends-on'] ? { dependsOn: values['depends-on'] } : {}),
+                    ...(values.related ? { related: values.related } : {}),
+                    ...(values.duplicate ? { duplicate: values.duplicate } : {}),
+                    ...(values.parent ? { parent: values.parent } : {}),
+                    ...(values.file ? { files: values.file } : {}),
+                    ...(values.directory ? { directories: values.directory } : {}),
+                    ...(values['estimate-min'] !== undefined
+                        ? { estimateMin: values['estimate-min'] }
+                        : {}),
+                    ...(values['estimate-max'] !== undefined
+                        ? { estimateMax: values['estimate-max'] }
+                        : {}),
+                    ...(values['effort-min'] !== undefined ? { effortMin: values['effort-min'] } : {}),
+                    ...(values['effort-max'] !== undefined ? { effortMax: values['effort-max'] } : {}),
+                    ...(values['due-before'] ? { dueBefore: values['due-before'] } : {}),
+                    ...(values['due-after'] ? { dueAfter: values['due-after'] } : {}),
+                    ...(values['created-before'] ? { createdBefore: values['created-before'] } : {}),
+                    ...(values['created-after'] ? { createdAfter: values['created-after'] } : {}),
+                    ...(values['updated-before'] ? { updatedBefore: values['updated-before'] } : {}),
+                    ...(values['updated-after'] ? { updatedAfter: values['updated-after'] } : {}),
+                    ...(values.search !== undefined ? { text: values.search } : {}),
+                    ...(values.sort ? { sortBy: values.sort } : {}),
+                    ...(values.direction ? { direction: values.direction } : {}),
+                    ...(values.impact ? { impact: true } : {}),
+                }, 'document list query');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const result = await queryDocuments(repository, query);
+                const derivedGraph = values['include-derived']
+                    ? buildDocumentGraph(await listDocuments(repository))
+                    : undefined;
+                const serialize = (record) => documentRecordJson(record, derivedGraph?.derive(record.document.metadata.id));
+                if (values.json) {
+                    stdout(`${JSON.stringify(values.impact
+                        ? {
+                            direct: result.direct.map(serialize),
+                            impacted: result.impacted.map(serialize),
+                        }
+                        : result.direct.map(serialize), null, 2)}\n`);
+                }
+                else {
+                    for (const record of result.direct) {
+                        stdout(`${values.impact ? 'direct\t' : ''}${record.document.metadata.id}\t${record.document.metadata.type}\t${record.document.metadata.status}\t${record.document.metadata.title}\n`);
+                    }
+                    for (const record of result.impacted) {
+                        stdout(`impact\t${record.document.metadata.id}\t${record.document.metadata.type}\t${record.document.metadata.status}\t${record.document.metadata.title}\n`);
+                    }
+                }
+                return 0;
+            }
+            if (subcommand === 'show') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: {
+                        ...commonOptionDefinitions,
+                        type: { type: 'string' },
+                        'include-derived': { type: 'boolean' },
+                    },
+                });
+                const [id] = requirePositionals(parsed.positionals, 1, 'exactly one document ID');
+                const values = parseSchema(z.strictObject({
+                    ...CommonValuesSchema.shape,
+                    type: TrimmedStringSchema.optional(),
+                    'include-derived': z.boolean().optional(),
+                }), parsed.values, 'document show options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const validatedId = parseSchema(DocumentIdSchema, id, 'document ID');
+                const record = await readDocument(repository, validatedId, values.type ? normalizeDocumentKind(values.type) : undefined);
+                if (values.json) {
+                    const derived = values['include-derived']
+                        ? buildDocumentGraph(await listDocuments(repository)).derive(validatedId)
+                        : undefined;
+                    stdout(`${JSON.stringify({
+                        relativePath: record.relativePath,
+                        metadata: record.document.metadata,
+                        body: record.document.body,
+                        ...(derived ? { derived } : {}),
+                    }, null, 2)}\n`);
+                }
+                else {
+                    stdout(serializeDocumentFile(record.document));
+                }
+                return 0;
+            }
+            if (subcommand === 'update') {
+                const clearDefinitions = Object.fromEntries(UPDATE_CLEAR_PAIRS.map(([, clear]) => [clear, { type: 'boolean' }]));
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: {
+                        ...metadataOptionDefinitions,
+                        ...clearDefinitions,
+                        ...commonOptionDefinitions,
+                        type: { type: 'string' },
+                    },
+                });
+                const [documentId] = requirePositionals(parsed.positionals, 1, 'exactly one document ID');
+                const validatedDocumentId = parseSchema(DocumentIdSchema, documentId, 'document ID');
+                const values = parseSchema(DocumentUpdateValuesSchema, parsed.values, 'document update options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await updateDocument(repository, validatedDocumentId, documentUpdateInputFromValues(repository, values), values.type ? normalizeDocumentKind(values.type) : undefined, { onWarning });
+                writeDocumentRecord(record, values.json, stdout);
+                return 0;
+            }
+            if (subcommand === 'status') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: { ...commonOptionDefinitions, type: { type: 'string' } },
+                });
+                const [documentId, status] = requirePositionals(parsed.positionals, 2, 'a document ID and status');
+                const validatedDocumentId = parseSchema(DocumentIdSchema, documentId, 'document ID');
+                const validatedStatus = parseSchema(DocumentStatusSchema, status, 'document status');
+                const values = parseSchema(z.strictObject({ ...CommonValuesSchema.shape, type: TrimmedStringSchema.optional() }), parsed.values, 'document status options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await updateDocument(repository, validatedDocumentId, { status: validatedStatus }, values.type ? normalizeDocumentKind(values.type) : undefined, { onWarning });
+                writeDocumentRecord(record, values.json, stdout);
+                return 0;
+            }
+            if (subcommand === 'delete') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: {
+                        ...commonOptionDefinitions,
+                        type: { type: 'string' },
+                        'remove-dependencies': { type: 'boolean' },
+                    },
+                });
+                const [documentId] = requirePositionals(parsed.positionals, 1, 'exactly one document ID');
+                const validatedDocumentId = parseSchema(DocumentIdSchema, documentId, 'document ID');
+                const values = parseSchema(z.strictObject({
+                    cwd: CwdSchema,
+                    json: JsonSchema,
+                    type: TrimmedStringSchema.optional(),
+                    'remove-dependencies': z.boolean().optional(),
+                }), parsed.values, 'document delete options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await deleteDocument(repository, validatedDocumentId, values.type ? normalizeDocumentKind(values.type) : undefined, {
+                    removeDependencies: values['remove-dependencies'],
+                    onWarning,
+                });
+                if (values.json) {
+                    stdout(`${JSON.stringify({ deleted: true, ...documentRecordJson(record) }, null, 2)}\n`);
+                }
+                else {
+                    stdout(`${validatedDocumentId}\n`);
+                }
+                return 0;
+            }
+            throw new CliUsageError(`Unknown document command "${subcommand ?? ''}"`);
+        }
         if (command !== 'task') {
             throw new CliUsageError(`Unknown command "${command}"`);
         }
+        if (subcommand === 'migrate-ids') {
+            const parsed = parseArgs({
+                args: subcommandArgs,
+                allowPositionals: false,
+                options: commonOptionDefinitions,
+            });
+            const values = parseSchema(CommonValuesSchema, parsed.values, 'task migrate-ids options');
+            const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+            const migrations = await migrateTaskIds(repository, {
+                onProgress: (progress) => stderr(`migration ${progress.phase}: ${progress.completed}/${progress.total} (${progress.percent}%)\n`),
+            });
+            if (values.json)
+                stdout(`${JSON.stringify(migrations, null, 2)}\n`);
+            else
+                for (const migration of migrations)
+                    stdout(`${migration.from}\t${migration.to}\n`);
+            return 0;
+        }
         if (subcommand === 'create') {
             const parsed = parseArgs({
                 args: subcommandArgs,