@cleocode/cleo 2026.3.66 → 2026.3.67

package/dist/cli/commands/detect-drift.js

@@ -0,0 +1,387 @@
+/**
+ * detect-drift command - Documentation drift detection for LLM agents
+ * @epic T4698
+ * @task T4705
+ *
+ * Exit codes:
+ *   0 - No drift detected (all checks pass)
+ *   1 - Warnings only (documentation exists but needs attention)
+ *   2 - Errors detected (missing documentation or critical drift)
+ *
+ * Output: LAFS-compliant JSON envelope for agent consumption
+ */
+// CLI-only: detect-drift runs local static analysis; session.context.drift is a different operation
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getErrorMessage } from '@cleocode/contracts';
+import { cliOutput } from '../renderers/index.js';
+function findProjectRoot() {
+    // Start from CWD, not the CLI file location. When installed via npm,
+    // the CLI bundle is in node_modules — walking up from there finds the
+    // npm package dir instead of the user's project (#78).
+    let currentDir = process.cwd();
+    while (currentDir !== '/') {
+        if (existsSync(join(currentDir, 'package.json'))) {
+            return currentDir;
+        }
+        const parent = dirname(currentDir);
+        if (parent === currentDir)
+            break;
+        currentDir = parent;
+    }
+    return process.cwd();
+}
+export function registerDetectDriftCommand(program) {
+    program
+        .command('detect-drift')
+        .description('Detect documentation drift against TypeScript source of truth')
+        .action(async () => {
+        const projectRoot = findProjectRoot();
+        const result = {
+            summary: {
+                totalChecks: 0,
+                passed: 0,
+                warnings: 0,
+                errors: 0,
+                exitCode: 0,
+            },
+            checks: [],
+            recommendations: [],
+        };
+        const addCheck = (name, status, message, issues = []) => {
+            result.checks.push({ name, status, message, issues });
+            result.summary.totalChecks++;
+            if (status === 'pass')
+                result.summary.passed++;
+            if (status === 'warn') {
+                result.summary.warnings++;
+                result.summary.exitCode = Math.max(result.summary.exitCode, 1);
+            }
+            if (status === 'fail') {
+                result.summary.errors++;
+                result.summary.exitCode = 2;
+            }
+        };
+        const safeRead = (path) => {
+            try {
+                return readFileSync(path, 'utf-8');
+            }
+            catch {
+                return '';
+            }
+        };
+        // Check 1: Gateway-to-spec sync
+        try {
+            const specPath = join(projectRoot, 'docs', 'specs', 'CLEO-OPERATIONS-REFERENCE.md');
+            const queryPath = join(projectRoot, 'src', 'mcp', 'gateways', 'query.ts');
+            const mutatePath = join(projectRoot, 'src', 'mcp', 'gateways', 'mutate.ts');
+            if (!existsSync(specPath)) {
+                addCheck('Gateway-to-spec sync', 'fail', 'CLEO-OPERATIONS-REFERENCE.md missing', [
+                    {
+                        severity: 'error',
+                        category: 'spec',
+                        message: 'Operations reference specification not found',
+                        file: specPath,
+                        recommendation: 'Create docs/specs/CLEO-OPERATIONS-REFERENCE.md with canonical operation definitions',
+                    },
+                ]);
+            }
+            else if (!existsSync(queryPath) || !existsSync(mutatePath)) {
+                addCheck('Gateway-to-spec sync', 'fail', 'MCP gateway files missing', [
+                    {
+                        severity: 'error',
+                        category: 'implementation',
+                        message: 'MCP gateway files not found',
+                        file: queryPath,
+                        recommendation: 'Verify src/mcp/gateways/query.ts and mutate.ts exist',
+                    },
+                ]);
+            }
+            else {
+                const specContent = safeRead(specPath);
+                const queryContent = safeRead(queryPath);
+                const mutateContent = safeRead(mutatePath);
+                // Extract operations from spec
+                const specOpsMatch = specContent.match(/## `([a-z_]+)`/g) || [];
+                const specOps = specOpsMatch.map((m) => m.replace(/## `|`/g, ''));
+                // Extract operations from gateways
+                const queryOpsMatch = queryContent.match(/case '([a-z_]+)':/g) || [];
+                const mutateOpsMatch = mutateContent.match(/case '([a-z_]+)':/g) || [];
+                const gatewayOps = [
+                    ...queryOpsMatch.map((m) => m.replace(/case '|':/g, '')),
+                    ...mutateOpsMatch.map((m) => m.replace(/case '|':/g, '')),
+                ];
+                // Find mismatches
+                const specOnly = specOps.filter((op) => !gatewayOps.includes(op));
+                const gatewayOnly = gatewayOps.filter((op) => !specOps.includes(op));
+                if (specOnly.length === 0 && gatewayOnly.length === 0) {
+                    addCheck('Gateway-to-spec sync', 'pass', `All ${specOps.length} operations synchronized`);
+                }
+                else {
+                    const issues = [];
+                    if (specOnly.length > 0) {
+                        issues.push({
+                            severity: 'warning',
+                            category: 'spec-coverage',
+                            message: `${specOnly.length} operations in spec but not in gateways: ${specOnly.join(', ')}`,
+                            recommendation: 'Add missing operation handlers to MCP gateways or remove from spec',
+                        });
+                    }
+                    if (gatewayOnly.length > 0) {
+                        issues.push({
+                            severity: 'warning',
+                            category: 'implementation-coverage',
+                            message: `${gatewayOnly.length} operations in gateways but not in spec: ${gatewayOnly.join(', ')}`,
+                            recommendation: 'Document missing operations in CLEO-OPERATIONS-REFERENCE.md',
+                        });
+                    }
+                    addCheck('Gateway-to-spec sync', 'warn', `Found ${specOnly.length + gatewayOnly.length} operation mismatches`, issues);
+                }
+            }
+        }
+        catch (e) {
+            addCheck('Gateway-to-spec sync', 'fail', `Error: ${getErrorMessage(e)}`, [
+                {
+                    severity: 'error',
+                    category: 'system',
+                    message: getErrorMessage(e),
+                    recommendation: 'Check file permissions and paths',
+                },
+            ]);
+        }
+        // Check 2: CLI-to-core sync
+        try {
+            const cliDir = join(projectRoot, 'src', 'cli', 'commands');
+            const coreDir = join(projectRoot, 'src', 'core');
+            if (!existsSync(cliDir)) {
+                addCheck('CLI-to-core sync', 'fail', 'CLI commands directory missing', [
+                    {
+                        severity: 'error',
+                        category: 'structure',
+                        message: 'src/cli/commands/ directory not found',
+                        recommendation: 'Verify TypeScript source structure is intact',
+                    },
+                ]);
+            }
+            else if (!existsSync(coreDir)) {
+                addCheck('CLI-to-core sync', 'fail', 'Core directory missing', [
+                    {
+                        severity: 'error',
+                        category: 'structure',
+                        message: 'src/core/ directory not found',
+                        recommendation: 'Verify TypeScript source structure is intact',
+                    },
+                ]);
+            }
+            else {
+                const files = readdirSync(cliDir).filter((f) => f.endsWith('.ts') && !f.includes('.test.'));
+                addCheck('CLI-to-core sync', 'pass', `Found ${files.length} CLI command implementations`);
+            }
+        }
+        catch (e) {
+            addCheck('CLI-to-core sync', 'fail', `Error: ${getErrorMessage(e)}`);
+        }
+        // Check 3: Domain handler coverage
+        try {
+            const domainsDir = join(projectRoot, 'src', 'mcp', 'domains');
+            if (!existsSync(domainsDir)) {
+                addCheck('Domain handler coverage', 'fail', 'MCP domains directory missing', [
+                    {
+                        severity: 'error',
+                        category: 'structure',
+                        message: 'src/mcp/domains/ not found',
+                        recommendation: 'Verify MCP domain handlers are in place',
+                    },
+                ]);
+            }
+            else {
+                const files = readdirSync(domainsDir).filter((f) => f.endsWith('.ts'));
+                addCheck('Domain handler coverage', 'pass', `Found ${files.length} domain handlers`);
+            }
+        }
+        catch (e) {
+            addCheck('Domain handler coverage', 'fail', `Error: ${getErrorMessage(e)}`);
+        }
+        // Check 4: Capability matrix
+        try {
+            const matrixPath = join(projectRoot, 'src', 'dispatch', 'lib', 'capability-matrix.ts');
+            if (!existsSync(matrixPath)) {
+                addCheck('Capability matrix', 'fail', 'Capability matrix missing', [
+                    {
+                        severity: 'error',
+                        category: 'configuration',
+                        message: 'src/dispatch/lib/capability-matrix.ts not found',
+                        recommendation: 'Create capability matrix to document supported operations',
+                    },
+                ]);
+            }
+            else {
+                addCheck('Capability matrix', 'pass', 'Capability matrix exists');
+            }
+        }
+        catch (e) {
+            addCheck('Capability matrix', 'fail', `Error: ${getErrorMessage(e)}`);
+        }
+        // Check 5: Schema validation
+        try {
+            const schemaPath = join(projectRoot, 'src', 'store', 'schema.ts');
+            if (!existsSync(schemaPath)) {
+                addCheck('Schema validation', 'fail', 'Schema definition missing', [
+                    {
+                        severity: 'error',
+                        category: 'data-model',
+                        message: 'src/store/schema.ts not found',
+                        recommendation: 'Create schema definition for database tables',
+                    },
+                ]);
+            }
+            else {
+                const content = safeRead(schemaPath);
+                const tableCount = (content.match(/CREATE TABLE/g) || []).length;
+                if (tableCount === 0) {
+                    addCheck('Schema validation', 'warn', 'Schema file exists but no CREATE TABLE statements', [
+                        {
+                            severity: 'warning',
+                            category: 'data-model',
+                            message: 'No SQL table definitions found in schema.ts',
+                            recommendation: 'Add CREATE TABLE statements for all database entities',
+                        },
+                    ]);
+                }
+                else {
+                    addCheck('Schema validation', 'pass', `Schema defines ${tableCount} tables`);
+                }
+            }
+        }
+        catch (e) {
+            addCheck('Schema validation', 'fail', `Error: ${getErrorMessage(e)}`);
+        }
+        // Check 6: Canonical identity
+        try {
+            const visionPath = join(projectRoot, 'docs', 'concepts', 'CLEO-VISION.md');
+            const specPath = join(projectRoot, 'docs', 'specs', 'PORTABLE-BRAIN-SPEC.md');
+            const issues = [];
+            if (!existsSync(visionPath)) {
+                issues.push({
+                    severity: 'error',
+                    category: 'vision',
+                    message: 'Vision document missing',
+                    file: visionPath,
+                    recommendation: 'Create docs/concepts/CLEO-VISION.md with project vision',
+                });
+            }
+            if (!existsSync(specPath)) {
+                issues.push({
+                    severity: 'error',
+                    category: 'spec',
+                    message: 'Portable Brain spec missing',
+                    file: specPath,
+                    recommendation: 'Create docs/specs/PORTABLE-BRAIN-SPEC.md with canonical pillars',
+                });
+            }
+            if (issues.length > 0) {
+                addCheck('Canonical identity', 'fail', 'Canonical documents missing', issues);
+            }
+            else {
+                const specContent = safeRead(specPath);
+                const requiredPillars = [
+                    'Portable Memory',
+                    'Provenance by Default',
+                    'Interoperable Interfaces',
+                    'Deterministic Safety',
+                    'Cognitive Retrieval',
+                ];
+                const missingPillars = requiredPillars.filter((p) => !specContent.includes(p));
+                if (missingPillars.length > 0) {
+                    addCheck('Canonical identity', 'fail', `Missing ${missingPillars.length} canonical pillars`, [
+                        {
+                            severity: 'error',
+                            category: 'vision',
+                            message: `Missing pillars: ${missingPillars.join(', ')}`,
+                            file: specPath,
+                            recommendation: 'Add all five canonical pillars to PORTABLE-BRAIN-SPEC.md',
+                        },
+                    ]);
+                }
+                else {
+                    addCheck('Canonical identity', 'pass', 'All canonical pillars documented');
+                }
+            }
+        }
+        catch (e) {
+            addCheck('Canonical identity', 'fail', `Error: ${getErrorMessage(e)}`);
+        }
+        // Check 7: Agent injection template
+        try {
+            const injectionPath = join(projectRoot, '.cleo', 'templates', 'CLEO-INJECTION.md');
+            if (!existsSync(injectionPath)) {
+                addCheck('Agent injection', 'fail', 'Agent injection template missing', [
+                    {
+                        severity: 'error',
+                        category: 'agent-support',
+                        message: 'CLEO-INJECTION.md not found',
+                        file: injectionPath,
+                        recommendation: 'Create agent injection template or run cleo init',
+                    },
+                ]);
+            }
+            else {
+                const content = safeRead(injectionPath);
+                if (content.length < 100) {
+                    addCheck('Agent injection', 'warn', 'Agent injection template appears incomplete', [
+                        {
+                            severity: 'warning',
+                            category: 'agent-support',
+                            message: 'Template file is unusually short',
+                            recommendation: 'Verify template contains required agent instructions',
+                        },
+                    ]);
+                }
+                else {
+                    addCheck('Agent injection', 'pass', 'Agent injection template exists');
+                }
+            }
+        }
+        catch (e) {
+            addCheck('Agent injection', 'fail', `Error: ${getErrorMessage(e)}`);
+        }
+        // Check 8: Exit codes
+        try {
+            const exitCodesPath = join(projectRoot, 'src', 'types', 'exit-codes.ts');
+            if (!existsSync(exitCodesPath)) {
+                addCheck('Exit codes', 'fail', 'Exit codes definition missing', [
+                    {
+                        severity: 'error',
+                        category: 'protocol',
+                        message: 'src/types/exit-codes.ts not found',
+                        recommendation: 'Create exit codes enum for CLI protocol compliance',
+                    },
+                ]);
+            }
+            else {
+                const content = safeRead(exitCodesPath);
+                const codeCount = (content.match(/= \d+/g) || []).length;
+                addCheck('Exit codes', 'pass', `${codeCount} exit codes defined`);
+            }
+        }
+        catch (e) {
+            addCheck('Exit codes', 'fail', `Error: ${getErrorMessage(e)}`);
+        }
+        // Generate top-level recommendations based on findings
+        if (result.summary.errors > 0) {
+            result.recommendations.push('Address all ERROR-level issues before proceeding');
+            result.recommendations.push('Run cleo detect-drift --json for structured output');
+        }
+        if (result.summary.warnings > 0) {
+            result.recommendations.push('Review WARNING-level issues for documentation improvements');
+        }
+        if (result.summary.errors === 0 && result.summary.warnings === 0) {
+            result.recommendations.push('Documentation is synchronized with implementation');
+        }
+        // Output via LAFS-compliant cliOutput
+        cliOutput(result, { command: 'detect-drift' });
+        // Exit with appropriate code for scripting
+        process.exit(result.summary.exitCode);
+    });
+}
+//# sourceMappingURL=detect-drift.js.map

package/dist/cli/commands/detect-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-drift.js","sourceRoot":"","sources":["../../../src/cli/commands/detect-drift.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/detect.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI detect command — re-detect project type and update project-context.json.
+ *
+ * Standalone lightweight command that runs project detection without
+ * the full init or upgrade flow. Updates .cleo/project-context.json
+ * with fresh detection results.
+ */
+import type { ShimCommand as Command } from '../commander-shim.js';
+export declare function registerDetectCommand(program: Command): void;
+//# sourceMappingURL=detect.d.ts.map

package/dist/cli/commands/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/detect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGnE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiB5D"}

package/dist/cli/commands/detect.js

@@ -0,0 +1,24 @@
+/**
+ * CLI detect command — re-detect project type and update project-context.json.
+ *
+ * Standalone lightweight command that runs project detection without
+ * the full init or upgrade flow. Updates .cleo/project-context.json
+ * with fresh detection results.
+ */
+import { ensureProjectContext, getProjectRoot } from '@cleocode/core/internal';
+import { cliOutput } from '../renderers/index.js';
+export function registerDetectCommand(program) {
+    program
+        .command('detect')
+        .description('Re-detect project type and update project-context.json')
+        .action(async () => {
+        const projectRoot = getProjectRoot();
+        const result = await ensureProjectContext(projectRoot, { staleDays: 0 });
+        cliOutput({
+            action: result.action,
+            path: result.path,
+            details: result.details,
+        }, { command: 'detect' });
+    });
+}
+//# sourceMappingURL=detect.js.map

package/dist/cli/commands/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../../src/cli/commands/detect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE/E,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,wDAAwD,CAAC;SACrE,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;QAEzE,SAAS,CACP;YACE,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,EACD,EAAE,OAAO,EAAE,QAAQ,EAAE,CACtB,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/docs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI docs command - documentation management with drift detection and gap checking.
+ * Ported from scripts/docs.sh
+ * @task T4551
+ * @epic T4545
+ */
+import type { ShimCommand as Command } from '../commander-shim.js';
+/**
+ * Register the docs command.
+ * @task T4551
+ */
+export declare function registerDocsCommand(program: Command): void;
+//# sourceMappingURL=docs.d.ts.map

package/dist/cli/commands/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/docs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,WAAW,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAwHnE;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4E1D"}

package/dist/cli/commands/docs.js

@@ -0,0 +1,169 @@
+/**
+ * CLI docs command - documentation management with drift detection and gap checking.
+ * Ported from scripts/docs.sh
+ * @task T4551
+ * @epic T4545
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CleoError, formatError, getAgentOutputsAbsolute, readJson } from '@cleocode/core/internal';
+import { cliOutput } from '../renderers/index.js';
+/**
+ * Get list of script files from scripts/ directory.
+ * @task T4551
+ */
+async function getScriptNames(projectRoot) {
+    const scriptsDir = join(projectRoot, 'scripts');
+    try {
+        const files = await readdir(scriptsDir);
+        return files
+            .filter((f) => f.endsWith('.sh'))
+            .map((f) => f.replace('.sh', ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get command names from COMMANDS-INDEX.json.
+ * @task T4551
+ */
+async function getIndexedCommands(projectRoot) {
+    const indexPath = join(projectRoot, 'docs', 'commands', 'COMMANDS-INDEX.json');
+    const index = await readJson(indexPath);
+    if (!index)
+        return [];
+    return index.commands.map((c) => c.name).sort();
+}
+/**
+ * Run drift detection between scripts and documentation index.
+ * @task T4551
+ */
+async function detectDrift(projectRoot) {
+    const scripts = await getScriptNames(projectRoot);
+    const indexed = await getIndexedCommands(projectRoot);
+    const scriptSet = new Set(scripts);
+    const indexSet = new Set(indexed);
+    const missingFromIndex = scripts.filter((s) => !indexSet.has(s));
+    const missingFromScripts = indexed.filter((i) => !scriptSet.has(i));
+    const warnings = [];
+    if (missingFromIndex.length > 0) {
+        warnings.push(`${missingFromIndex.length} scripts not in COMMANDS-INDEX.json`);
+    }
+    if (missingFromScripts.length > 0) {
+        warnings.push(`${missingFromScripts.length} index entries without scripts`);
+    }
+    let status = 'clean';
+    if (missingFromIndex.length > 0 || missingFromScripts.length > 0) {
+        status = missingFromIndex.length > 5 ? 'error' : 'warning';
+    }
+    return { status, missingFromIndex, missingFromScripts, warnings };
+}
+/**
+ * Run gap-check validation for review docs.
+ * @task T4551
+ */
+async function runGapCheck(_projectRoot, filterId) {
+    const reviewDir = getAgentOutputsAbsolute();
+    const results = [];
+    try {
+        const files = await readdir(reviewDir);
+        const reviewFiles = files.filter((f) => f.endsWith('.md'));
+        for (const file of reviewFiles) {
+            // Check filter
+            if (filterId && !file.includes(filterId))
+                continue;
+            const filePath = join(reviewDir, file);
+            const content = await readFile(filePath, 'utf-8');
+            // Extract task ID from filename (e.g., T2402-protocol-spec.md)
+            const taskMatch = file.match(/^(T\d+)/);
+            const taskId = taskMatch ? taskMatch[1] : 'UNKNOWN';
+            const gaps = [];
+            // Check for required sections
+            if (!content.includes('## Summary')) {
+                gaps.push('Missing ## Summary section');
+            }
+            if (!content.includes('**Task**:') && !content.includes('**Task:**')) {
+                gaps.push('Missing Task provenance header');
+            }
+            if (gaps.length > 0) {
+                results.push({ file, taskId, gaps });
+            }
+        }
+    }
+    catch {
+        // Review directory might not exist
+    }
+    return results;
+}
+/**
+ * Register the docs command.
+ * @task T4551
+ */
+export function registerDocsCommand(program) {
+    const docsCmd = program
+        .command('docs')
+        .description('Documentation management: drift detection and gap validation');
+    docsCmd
+        .command('sync')
+        .description('Run drift detection between scripts and docs index')
+        .option('--quick', 'Quick check (commands only)')
+        .option('--strict', 'Exit with error on any drift')
+        .action(async (opts) => {
+        try {
+            const projectRoot = process.cwd();
+            const result = await detectDrift(projectRoot);
+            cliOutput({
+                status: result.status,
+                missingFromIndex: result.missingFromIndex,
+                missingFromScripts: result.missingFromScripts,
+                warnings: result.warnings,
+            }, {
+                command: 'docs',
+                message: result.status === 'clean'
+                    ? 'Documentation is in sync'
+                    : `Drift detected: ${result.warnings.join('; ')}`,
+            });
+            if (opts['strict'] && result.status !== 'clean') {
+                process.exit(result.status === 'error' ? 2 : 1);
+            }
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+    docsCmd
+        .command('gap-check')
+        .description('Validate knowledge transfer from review docs to canonical docs')
+        .option('--epic <id>', 'Filter by epic ID')
+        .option('--task <id>', 'Filter by task ID')
+        .action(async (opts) => {
+        try {
+            const projectRoot = process.cwd();
+            const filterId = opts['epic'] ?? opts['task'];
+            const gaps = await runGapCheck(projectRoot, filterId);
+            if (gaps.length === 0) {
+                cliOutput({ gapCount: 0, results: [] }, { command: 'docs', message: 'No documentation gaps found' });
+            }
+            else {
+                cliOutput({
+                    gapCount: gaps.length,
+                    results: gaps,
+                }, { command: 'docs', message: `Found ${gaps.length} document(s) with gaps` });
+            }
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=docs.js.map

package/dist/cli/commands/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../../src/cli/commands/docs.ts"],"names":[],"mappings":"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"}