@libar-dev/architect 1.0.0-pre.3

package/dist/cli/process-api.js

@@ -0,0 +1,1550 @@
+#!/usr/bin/env node
+/**
+ * @architect
+ * @architect-core @architect-cli
+ * @architect-pattern ProcessAPICLIImpl
+ * @architect-status active
+ * @architect-implements ProcessStateAPICLI
+ * @architect-arch-role service
+ * @architect-arch-context cli
+ * @architect-arch-layer application
+ * @architect-uses ProcessStateAPI, MasterDataset, PipelineFactory, RulesQueryModule, PatternSummarizerImpl, FuzzyMatcherImpl, OutputPipelineImpl
+ * @architect-used-by npm scripts, Claude Code sessions
+ * @architect-usecase "When querying project state from CLI"
+ * @architect-usecase "When Claude Code needs real-time delivery state queries"
+ *
+ * ## architect - CLI Query Interface to ProcessStateAPI
+ *
+ * Exposes ProcessStateAPI methods as CLI subcommands with JSON output.
+ * Runs pipeline steps 1-8 (config -> scan -> extract -> transform),
+ * then routes subcommands to API methods.
+ *
+ * ### When to Use
+ *
+ * - When Claude Code needs real-time delivery state queries
+ * - When AI agents need structured JSON instead of regenerating markdown
+ * - When scripting architect queries in CI/CD
+ *
+ * ### Key Concepts
+ *
+ * - **Subcommand Routing**: CLI subcommands map to ProcessStateAPI methods
+ * - **JSON Output**: All output is JSON to stdout, errors to stderr
+ * - **Pipeline Reuse**: Steps 1-8 match architect-generate exactly
+ * - **QueryResult Envelope**: All output wrapped in success/error discriminated union
+ * - **Output Shaping**: 594KB -> 4KB via summarization and modifiers
+ */
+// ─── Error Convention ───────────────────────────────────────────────────
+// CLI modules use throw/catch + process.exit(). Pipeline modules use Result<T,E>.
+// See src/cli/error-handler.ts for the unified handler.
+// ────────────────────────────────────────────────────────────────────────
+import * as path from 'path';
+import * as fs from 'fs';
+import { applyProjectSourceDefaults, findConfigFile } from '../config/config-loader.js';
+import { buildMasterDataset, } from '../generators/pipeline/index.js';
+import { createProcessStateAPI } from '../api/process-state.js';
+import { createSuccess, createError, QueryApiError, } from '../api/types.js';
+import { computeCacheKey, tryLoadCache, writeCache, getCacheDir, cacheFileExists, } from './dataset-cache.js';
+import { handleCliError } from './error-handler.js';
+import { printVersionAndExit } from './version.js';
+import { CLI_SCHEMA } from './cli-schema.js';
+import { VALID_TRANSITIONS, isValidTransition as fsmIsValidTransition, getValidTransitionsFrom as fsmGetValidTransitionsFrom, } from '../validation/fsm/transitions.js';
+import { validateTransition as fsmValidateTransition, getProtectionSummary as fsmGetProtectionSummary, } from '../validation/fsm/validator.js';
+import { fuzzyMatchPatterns } from '../api/fuzzy-match.js';
+import { allPatternNames, getSequenceEntry, suggestPattern, firstImplements, getPatternName, } from '../api/pattern-helpers.js';
+import { findStubPatterns, resolveStubs, groupStubsByPattern, extractDecisionItems, findPdrReferences, } from '../api/stub-resolver.js';
+import { applyOutputPipeline, applyListFilters, validateModifiers, formatOutput, PATTERN_ARRAY_METHODS, DEFAULT_OUTPUT_MODIFIERS, } from './output-pipeline.js';
+import { assembleContext, buildDepTree, buildFileReadingList, buildOverview, isValidSessionType, } from '../api/context-assembler.js';
+import { formatContextBundle, formatDepTree, formatFileReadingList, formatOverview, } from '../api/context-formatter.js';
+import { computeNeighborhood, compareContexts, aggregateTagUsage, buildSourceInventory, findOrphanPatterns, } from '../api/arch-queries.js';
+import { analyzeCoverage, findUnannotatedFiles } from '../api/coverage-analyzer.js';
+import { validateScope, formatScopeValidation } from '../api/scope-validator.js';
+import { generateHandoff, formatHandoff, } from '../api/handoff-generator.js';
+import { execSync } from 'child_process';
+import { glob } from 'glob';
+import { startRepl } from './repl.js';
+import { queryBusinessRules } from '../api/rules-query.js';
+/**
+ * Handle position-independent flags (help, version, cache, dry-run, modifiers, format).
+ * These work regardless of position — before or after the subcommand.
+ *
+ * @returns Number of additional args consumed (0 for booleans, 1 for --value flags).
+ *          Returns -1 if the arg is not a position-independent flag.
+ */
+function handlePositionIndependentFlag(state, arg, nextArg) {
+    switch (arg) {
+        case '-h':
+        case '--help':
+            if (state.config.subcommand !== null) {
+                state.config.subcommandHelp = state.config.subcommand;
+            }
+            else {
+                state.config.help = true;
+            }
+            return 0;
+        case '-v':
+        case '--version':
+            state.config.version = true;
+            return 0;
+        case '--no-cache':
+            state.config.noCache = true;
+            return 0;
+        case '--dry-run':
+            state.config.dryRun = true;
+            return 0;
+        case '--names-only':
+            state.namesOnly = true;
+            return 0;
+        case '--count':
+            state.count = true;
+            return 0;
+        case '--fields':
+            if (!nextArg || nextArg.startsWith('-')) {
+                throw new Error(`${arg} requires a value (comma-separated field names)`);
+            }
+            state.fields = nextArg.split(',').map((f) => f.trim());
+            return 1;
+        case '--full':
+            state.full = true;
+            return 0;
+        case '--format':
+            if (nextArg !== 'json' && nextArg !== 'compact') {
+                throw new Error(`${arg} must be "json" or "compact"`);
+            }
+            state.config.format = nextArg;
+            return 1;
+        default:
+            return -1;
+    }
+}
+/**
+ * Handle position-dependent global flags (input, features, base-dir, workflow, session).
+ * These only apply before the subcommand is detected.
+ *
+ * @returns Number of additional args consumed (always 1 for these flags).
+ * @throws On unknown flag.
+ */
+function handleGlobalFlag(state, arg, nextArg) {
+    switch (arg) {
+        case '-i':
+        case '--input':
+            if (!nextArg || nextArg.startsWith('-')) {
+                throw new Error(`${arg} requires a value`);
+            }
+            state.config.input.push(nextArg);
+            return 1;
+        case '-f':
+        case '--features':
+            if (!nextArg || nextArg.startsWith('-')) {
+                throw new Error(`${arg} requires a value`);
+            }
+            state.config.features.push(nextArg);
+            return 1;
+        case '-b':
+        case '--base-dir':
+            if (!nextArg || nextArg.startsWith('-')) {
+                throw new Error(`${arg} requires a value`);
+            }
+            state.config.baseDir = nextArg;
+            return 1;
+        case '-w':
+        case '--workflow':
+            if (!nextArg || nextArg.startsWith('-')) {
+                throw new Error(`${arg} requires a value`);
+            }
+            state.config.workflowPath = nextArg;
+            return 1;
+        case '--session':
+            if (!nextArg || !isValidSessionType(nextArg)) {
+                throw new Error(`${arg} must be "planning", "design", or "implement"`);
+            }
+            state.config.sessionType = nextArg;
+            return 1;
+        default:
+            throw new Error(`Unknown option: ${arg}`);
+    }
+}
+/**
+ * Handle positional args: first becomes subcommand, rest become subArgs.
+ */
+function handlePositionalArg(state, arg) {
+    if (state.config.subcommand === null) {
+        state.config.subcommand = arg;
+        state.parsingFlags = false;
+    }
+    else {
+        state.config.subArgs.push(arg);
+    }
+}
+function parseArgs(argv = process.argv.slice(2)) {
+    const state = {
+        config: {
+            input: [],
+            features: [],
+            baseDir: process.cwd(),
+            workflowPath: null,
+            subcommand: null,
+            subArgs: [],
+            help: false,
+            version: false,
+            modifiers: { ...DEFAULT_OUTPUT_MODIFIERS },
+            format: 'json',
+            sessionType: null,
+            noCache: false,
+            dryRun: false,
+            subcommandHelp: null,
+        },
+        namesOnly: false,
+        count: false,
+        fields: null,
+        full: false,
+        parsingFlags: true,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        const nextArg = argv[i + 1];
+        // pnpm passes '--' as a literal arg separator — skip it
+        if (arg === '--') {
+            state.parsingFlags = false;
+            continue;
+        }
+        // Position-independent flags (work before and after subcommand)
+        const piConsumed = handlePositionIndependentFlag(state, arg, nextArg);
+        if (piConsumed >= 0) {
+            i += piConsumed;
+            continue;
+        }
+        // Position-dependent global flags (only before subcommand)
+        if (state.parsingFlags && arg.startsWith('-')) {
+            i += handleGlobalFlag(state, arg, nextArg);
+            continue;
+        }
+        // Positional: subcommand or subArg
+        handlePositionalArg(state, arg);
+    }
+    state.config.modifiers = {
+        namesOnly: state.namesOnly,
+        count: state.count,
+        fields: state.fields,
+        full: state.full,
+    };
+    return state.config;
+}
+// =============================================================================
+// Help
+// =============================================================================
+function formatHelpOptions(group) {
+    return group.options
+        .map((opt) => {
+        const short = opt.short !== undefined ? `${opt.short}, ` : '    ';
+        // Extract bare flag name (without value placeholder) for alignment
+        const flag = opt.flag.padEnd(24);
+        return `  ${short}${flag}${opt.description}`;
+    })
+        .join('\n');
+}
+function showHelp() {
+    const options = formatHelpOptions(CLI_SCHEMA.globalOptions);
+    const modifiers = formatHelpOptions(CLI_SCHEMA.outputModifiers);
+    const filters = formatHelpOptions(CLI_SCHEMA.listFilters);
+    const sessions = formatHelpOptions(CLI_SCHEMA.sessionOptions);
+    console.log(`
+architect - Query project state from annotated sources
+
+  Use this instead of reading generated markdown or launching explore agents.
+  Targeted queries use 5-10x less context than file reads.
+
+Usage: architect [options] <subcommand> [args...]
+
+Quick Start — Session Recipe:
+
+  1. overview                              Project health (progress, blockers)
+  2. scope-validate <pattern> implement    Pre-flight check (FSM, deps, prereqs)
+  3. context <pattern> --session design    Curated context bundle for the session
+
+Session Workflow Commands (text output — use these first):
+
+  overview                          Executive summary: progress, active phases, blockers
+  scope-validate <pat> <type>       Pre-flight readiness check (PASS/BLOCKED/WARN verdict)
+                                      Catches FSM violations and missing deps BEFORE you start.
+                                      Types: implement, design
+  context <pat> --session <type>    Curated context bundle tailored to session type
+                                      planning  — minimal: pattern metadata and spec file
+                                      design    — full: metadata, stubs, deps, deliverables
+                                      implement — focused: deliverables, FSM state, test files
+  dep-tree <pat> [--depth N]        Dependency chain with status
+  files <pat> [--related]           File reading list with implementation paths
+  handoff --pattern <pat>           Session-end state: deliverables, blockers, date
+                                      Options: --git (include recent commits), --session <id>
+
+Pattern Discovery (JSON output):
+
+  status                    Status counts and completion percentage
+  list [filters]            Filtered pattern listing (composable with modifiers below)
+  search <query>            Fuzzy name search with match scores
+  pattern <name>            Full detail for one pattern
+                              Warning: ~66KB for completed patterns — prefer 'context --session'
+  stubs [pattern]           Design stubs with target paths and resolution status
+  stubs --unresolved        Only stubs with missing target files
+  decisions <pattern>       AD-N design decisions from stub descriptions
+  pdr <number>              Cross-reference patterns mentioning a PDR number
+  rules [filters]           Business rules and invariants from feature specs
+                              --product-area <name>  Filter by product area
+                              --pattern <name>       Filter by pattern name
+                              --only-invariants      Only rules with explicit invariants
+
+Architecture Queries (JSON output):
+
+  arch neighborhood <pat>   What does this pattern touch? (uses/usedBy/sameContext)
+  arch blocking             What's stuck? Patterns blocked by incomplete deps
+  arch dangling             Broken references (pattern names that don't exist)
+  arch orphans              Isolated patterns with no relationships
+  arch coverage             Annotation completeness across input files
+  arch roles                All arch-roles with pattern counts
+  arch context [name]       Patterns in bounded context (list all if no name)
+  arch layer [name]         Patterns in architecture layer (list all if no name)
+  arch compare <c1> <c2>    Cross-context shared deps and integration points
+
+Design Review:
+
+  sequence [name]           Sequence diagram data for design reviews
+                              No args: list patterns with sequence annotations
+                              With name: steps, participants, data flow types
+
+Metadata & Inventory:
+
+  tags                      Tag usage report (counts per tag and value)
+  sources                   File inventory by type (TS, Gherkin, Stubs)
+  unannotated [--path dir]  TypeScript files missing @architect annotations
+  query <method> [args...]  Execute any query API method directly
+
+Options:
+
+${options}
+
+Output Modifiers (composable with any list/query):
+
+${modifiers}
+
+List Filters (for 'list' subcommand):
+
+${filters}
+
+Session Types (for 'context' and 'scope-validate'):
+
+${sessions}
+
+Common Recipes:
+
+  Starting a session:
+    architect overview
+    architect scope-validate MyPattern implement
+    architect context MyPattern --session implement
+
+  Finding what to work on:
+    architect list --status roadmap --names-only
+    architect arch blocking
+    architect query getRoadmapItems --names-only
+
+  Investigating a pattern:
+    architect search EventStore
+    architect dep-tree EventStoreDurability --depth 2
+    architect arch neighborhood EventStoreDurability
+    architect stubs EventStoreDurability
+
+  Design session prep:
+    architect context MyPattern --session design
+    architect decisions MyPattern
+    architect stubs --unresolved
+
+  Ending a session:
+    architect handoff --pattern MyPattern
+
+Session Types (for --session flag):
+
+  planning    Minimal: pattern metadata and spec file only
+  design      Full: metadata, description, stubs, deps, deliverables
+  implement   Focused: deliverables, FSM state, test files
+
+  Which session? Start coding -> implement. Complex decisions -> design.
+                 New pattern -> planning. Not sure -> run 'overview' first.
+
+Available API Methods (for 'query'):
+
+  Status:   getPatternsByNormalizedStatus, getPatternsByStatus, getStatusCounts,
+            getStatusDistribution, getCompletionPercentage
+  Phase:    getPatternsByPhase, getPhaseProgress, getActivePhases, getAllPhases
+  FSM:      isValidTransition, checkTransition, getValidTransitionsFrom,
+            getProtectionInfo
+  Pattern:  getPattern, getPatternDependencies, getPatternRelationships,
+            getRelatedPatterns, getApiReferences, getPatternDeliverables,
+            getPatternsByCategory, getCategories
+  Timeline: getPatternsByQuarter, getQuarters, getCurrentWork, getRoadmapItems,
+            getRecentlyCompleted
+  Raw:      getMasterDataset
+`);
+}
+/**
+ * Per-subcommand help: shows usage, flags, and examples for a specific subcommand.
+ * Looks up command narrative from CLI_SCHEMA.commandNarratives.
+ */
+function showSubcommandHelp(subcommand) {
+    // Search for the command in commandNarratives groups
+    const narratives = CLI_SCHEMA.commandNarratives;
+    if (narratives !== undefined) {
+        for (const group of narratives) {
+            for (const cmd of group.commands) {
+                if (cmd.command === subcommand) {
+                    console.log(`\narchitect ${subcommand} — ${cmd.description}\n`);
+                    console.log(`Usage: ${cmd.usageExample}\n`);
+                    if (cmd.details !== undefined) {
+                        console.log(cmd.details);
+                        console.log('');
+                    }
+                    if (cmd.expectedOutput !== undefined) {
+                        console.log(`Expected output: ${cmd.expectedOutput}\n`);
+                    }
+                    // Show applicable option groups
+                    const applicableGroups = getSubcommandOptionGroups(subcommand);
+                    for (const groupKey of applicableGroups) {
+                        const optGroup = CLI_SCHEMA[groupKey];
+                        if (optGroup !== undefined && 'options' in optGroup) {
+                            console.log(`${optGroup.title}:\n`);
+                            console.log(formatHelpOptions(optGroup));
+                            console.log('');
+                        }
+                    }
+                    return;
+                }
+            }
+        }
+    }
+    // Fallback: subcommand not found in narratives
+    console.log(`\nNo detailed help available for '${subcommand}'.`);
+    console.log('Run architect --help for the full command reference.\n');
+}
+/**
+ * Map subcommands to their applicable CLI option groups.
+ */
+function getSubcommandOptionGroups(subcommand) {
+    const mapping = {
+        context: ['sessionOptions'],
+        'scope-validate': ['sessionOptions'],
+        list: ['listFilters', 'outputModifiers'],
+        search: ['outputModifiers'],
+        query: ['outputModifiers'],
+        status: ['outputModifiers'],
+        pattern: ['outputModifiers'],
+        stubs: ['outputModifiers'],
+        decisions: ['outputModifiers'],
+        pdr: ['outputModifiers'],
+        rules: ['outputModifiers'],
+        tags: ['outputModifiers'],
+        sources: ['outputModifiers'],
+        arch: ['outputModifiers'],
+        sequence: ['outputModifiers'],
+    };
+    return mapping[subcommand] ?? [];
+}
+/**
+ * Execute dry-run: show pipeline scope (files, config, cache) without processing.
+ */
+async function executeDryRun(opts) {
+    const baseDir = path.resolve(opts.baseDir);
+    // Resolve globs to file lists
+    const tsFiles = await glob(opts.input, { cwd: baseDir });
+    const featureFiles = await glob(opts.features, { cwd: baseDir });
+    // Check config file
+    const configPath = await findConfigFile(baseDir);
+    // Check cache status
+    const cacheDir = getCacheDir(opts.baseDir);
+    const cacheInfo = cacheFileExists(cacheDir);
+    console.log('=== DRY RUN ===');
+    console.log(`Config: ${formatConfigStatus(configPath)}`);
+    console.log(`Base dir: ${baseDir}`);
+    console.log(`Input patterns: ${opts.input.join(', ')}`);
+    console.log(`Feature patterns: ${opts.features.join(', ')}`);
+    console.log(`TypeScript files: ${tsFiles.length}`);
+    console.log(`Feature files: ${featureFiles.length}`);
+    console.log(`Workflow: ${opts.workflowPath ?? 'default (6-phase-standard)'}`);
+    if (cacheInfo.exists) {
+        const sizeKb = cacheInfo.sizeBytes !== undefined
+            ? `${(cacheInfo.sizeBytes / 1024).toFixed(1)}KB`
+            : 'unknown';
+        console.log(`Cache: ${path.join(cacheDir, 'dataset.json')} (${sizeKb})`);
+    }
+    else {
+        console.log('Cache: none');
+    }
+    console.log(`Subcommand: ${opts.subcommand ?? '(none)'}`);
+    console.log('\nNo pipeline processing performed.');
+}
+// =============================================================================
+// Config File Default Resolution
+// =============================================================================
+/**
+ * If --input and --features are not provided, try to load defaults from config.
+ * Prefers loadProjectConfig() for repos with a project config file,
+ * falls back to filesystem auto-detection for repos without one.
+ */
+async function applyConfigDefaults(config) {
+    const applied = await applyProjectSourceDefaults(config);
+    if (applied) {
+        return;
+    }
+    // Fall back to existing filesystem auto-detection for repos without config
+    await applyConfigDefaultsFallback(config);
+}
+/**
+ * Filesystem-based auto-detection fallback for repos without a config file.
+ * Checks for conventional directory structures and applies defaults.
+ */
+async function applyConfigDefaultsFallback(config) {
+    const baseDir = path.resolve(config.baseDir);
+    if (config.input.length === 0) {
+        // Check for config file existence as signal to use defaults
+        const configPath = await findConfigFile(baseDir);
+        if (configPath !== null) {
+            config.input.push('src/**/*.ts');
+            // Also check for stubs directory
+            const stubsDir = path.join(baseDir, 'architect', 'stubs');
+            if (fs.existsSync(stubsDir)) {
+                config.input.push('architect/stubs/**/*.ts');
+            }
+        }
+    }
+    if (config.features.length === 0) {
+        const specsDir = path.join(baseDir, 'architect', 'specs');
+        if (fs.existsSync(specsDir)) {
+            config.features.push('architect/specs/*.feature');
+        }
+        const releasesDir = path.join(baseDir, 'architect', 'releases');
+        if (fs.existsSync(releasesDir)) {
+            config.features.push('architect/releases/*.feature');
+        }
+    }
+}
+function formatConfigStatus(configPath) {
+    return configPath !== null
+        ? `${path.basename(configPath)} (auto-detected)`
+        : 'none (filesystem fallback)';
+}
+// =============================================================================
+// Pipeline
+// =============================================================================
+async function buildPipeline(config) {
+    const result = await buildMasterDataset({
+        input: config.input,
+        features: config.features,
+        baseDir: config.baseDir,
+        mergeConflictStrategy: 'fatal',
+        ...(config.workflowPath !== null ? { workflowPath: config.workflowPath } : {}),
+    });
+    if (!result.ok) {
+        console.error(`Pipeline error [${result.error.step}]: ${result.error.message}`);
+        process.exit(1);
+    }
+    for (const w of result.value.warnings) {
+        console.warn(`⚠️  ${w.message}`);
+    }
+    return result.value;
+}
+// =============================================================================
+// FSM Short-Circuit (bypass pipeline for static FSM queries)
+// =============================================================================
+/**
+ * FSM methods that operate on static const data and do not need the pipeline.
+ * When `query <method>` matches one of these, we dispatch directly to the FSM
+ * module, saving the 2-5 second pipeline build.
+ */
+const FSM_SHORT_CIRCUIT_METHODS = new Set([
+    'isValidTransition',
+    'checkTransition',
+    'getValidTransitionsFrom',
+    'getProtectionInfo',
+]);
+/**
+ * Validate and parse a CLI string as a ProcessStatusValue.
+ * Rejects unknown status values with a helpful error message.
+ */
+function parseProcessStatus(value, usage, label) {
+    if (value === undefined) {
+        throw new QueryApiError('INVALID_ARGUMENT', usage);
+    }
+    if (!(value in VALID_TRANSITIONS)) {
+        const valid = Object.keys(VALID_TRANSITIONS).join(', ');
+        throw new QueryApiError('INVALID_ARGUMENT', `Unknown ${label}: "${value}". Expected one of: ${valid}`);
+    }
+    return value;
+}
+/**
+ * Attempt to handle an FSM query without building the pipeline.
+ *
+ * @returns The FSM result data if this is a short-circuit candidate, or
+ *          `undefined` if the query should go through the normal pipeline path.
+ */
+function tryFsmShortCircuit(subcommand, subArgs) {
+    if (subcommand !== 'query')
+        return undefined;
+    const methodName = subArgs[0];
+    if (methodName === undefined || !FSM_SHORT_CIRCUIT_METHODS.has(methodName)) {
+        return undefined;
+    }
+    const fsmArgs = subArgs.slice(1);
+    switch (methodName) {
+        case 'isValidTransition': {
+            const usage = 'Usage: architect query isValidTransition <fromStatus> <toStatus>';
+            const from = parseProcessStatus(fsmArgs[0], usage, 'fromStatus');
+            const to = parseProcessStatus(fsmArgs[1], usage, 'toStatus');
+            return fsmIsValidTransition(from, to);
+        }
+        case 'checkTransition': {
+            const from = fsmArgs[0];
+            const to = fsmArgs[1];
+            if (from === undefined || to === undefined) {
+                throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect query checkTransition <fromStatus> <toStatus>');
+            }
+            const result = fsmValidateTransition(from, to);
+            return {
+                from: result.from,
+                to: result.to,
+                valid: result.valid,
+                error: result.error,
+                validAlternatives: result.validAlternatives,
+            };
+        }
+        case 'getValidTransitionsFrom': {
+            const status = parseProcessStatus(fsmArgs[0], 'Usage: architect query getValidTransitionsFrom <status>', 'status');
+            return fsmGetValidTransitionsFrom(status);
+        }
+        case 'getProtectionInfo': {
+            const status = parseProcessStatus(fsmArgs[0], 'Usage: architect query getProtectionInfo <status>', 'status');
+            const summary = fsmGetProtectionSummary(status);
+            return {
+                status,
+                level: summary.level,
+                description: summary.description,
+                canAddDeliverables: summary.canAddDeliverables,
+                requiresUnlock: summary.requiresUnlock,
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+// =============================================================================
+// Subcommand Handlers
+// =============================================================================
+function handleStatus(api) {
+    return {
+        counts: api.getStatusCounts(),
+        completionPercentage: api.getCompletionPercentage(),
+        distribution: api.getStatusDistribution(),
+    };
+}
+function coerceArg(arg) {
+    const asInt = parseInt(arg, 10);
+    if (!isNaN(asInt) && String(asInt) === arg) {
+        return asInt;
+    }
+    return arg;
+}
+/**
+ * Require a string argument at the given index, throwing INVALID_ARGUMENT if missing.
+ */
+function requireStringArg(args, index, methodName) {
+    if (args[index] === undefined) {
+        throw new QueryApiError('INVALID_ARGUMENT', `${methodName} requires an argument at position ${index + 1}`);
+    }
+    return String(args[index]);
+}
+/**
+ * Require a numeric argument at the given index, throwing INVALID_ARGUMENT if missing or NaN.
+ */
+function requireNumberArg(args, index, methodName) {
+    if (args[index] === undefined) {
+        throw new QueryApiError('INVALID_ARGUMENT', `${methodName} requires a numeric argument at position ${index + 1}`);
+    }
+    const value = Number(args[index]);
+    if (isNaN(value)) {
+        throw new QueryApiError('INVALID_ARGUMENT', `${methodName} requires a numeric argument, got: "${String(args[index])}"`);
+    }
+    return value;
+}
+const API_METHODS = [
+    'getPatternsByNormalizedStatus',
+    'getPatternsByStatus',
+    'getStatusCounts',
+    'getStatusDistribution',
+    'getCompletionPercentage',
+    'getPatternsByPhase',
+    'getPhaseProgress',
+    'getActivePhases',
+    'getAllPhases',
+    'isValidTransition',
+    'checkTransition',
+    'getValidTransitionsFrom',
+    'getProtectionInfo',
+    'getPattern',
+    'getPatternDependencies',
+    'getPatternRelationships',
+    'getRelatedPatterns',
+    'getApiReferences',
+    'getPatternDeliverables',
+    'getPatternsByCategory',
+    'getCategories',
+    'getPatternsByQuarter',
+    'getQuarters',
+    'getCurrentWork',
+    'getRoadmapItems',
+    'getRecentlyCompleted',
+    'getMasterDataset',
+];
+/**
+ * Typed dispatch map: each entry invokes the API method with correct parameter types.
+ * The Record<ApiMethodName, ...> type ensures compile-time completeness — adding a
+ * method to API_METHODS without a dispatch entry causes a type error.
+ */
+const API_DISPATCH = {
+    // Status queries
+    getPatternsByNormalizedStatus: (api, args) => api.getPatternsByNormalizedStatus(requireStringArg(args, 0, 'getPatternsByNormalizedStatus')),
+    getPatternsByStatus: (api, args) => api.getPatternsByStatus(requireStringArg(args, 0, 'getPatternsByStatus')),
+    getStatusCounts: (api) => api.getStatusCounts(),
+    getStatusDistribution: (api) => api.getStatusDistribution(),
+    getCompletionPercentage: (api) => api.getCompletionPercentage(),
+    // Phase queries
+    getPatternsByPhase: (api, args) => api.getPatternsByPhase(requireNumberArg(args, 0, 'getPatternsByPhase')),
+    getPhaseProgress: (api, args) => api.getPhaseProgress(requireNumberArg(args, 0, 'getPhaseProgress')),
+    getActivePhases: (api) => api.getActivePhases(),
+    getAllPhases: (api) => api.getAllPhases(),
+    // FSM queries
+    isValidTransition: (api, args) => api.isValidTransition(requireStringArg(args, 0, 'isValidTransition'), requireStringArg(args, 1, 'isValidTransition')),
+    checkTransition: (api, args) => api.checkTransition(requireStringArg(args, 0, 'checkTransition'), requireStringArg(args, 1, 'checkTransition')),
+    getValidTransitionsFrom: (api, args) => api.getValidTransitionsFrom(requireStringArg(args, 0, 'getValidTransitionsFrom')),
+    getProtectionInfo: (api, args) => api.getProtectionInfo(requireStringArg(args, 0, 'getProtectionInfo')),
+    // Pattern queries
+    getPattern: (api, args) => api.getPattern(requireStringArg(args, 0, 'getPattern')),
+    getPatternDependencies: (api, args) => api.getPatternDependencies(requireStringArg(args, 0, 'getPatternDependencies')),
+    getPatternRelationships: (api, args) => api.getPatternRelationships(requireStringArg(args, 0, 'getPatternRelationships')),
+    getRelatedPatterns: (api, args) => api.getRelatedPatterns(requireStringArg(args, 0, 'getRelatedPatterns')),
+    getApiReferences: (api, args) => api.getApiReferences(requireStringArg(args, 0, 'getApiReferences')),
+    getPatternDeliverables: (api, args) => api.getPatternDeliverables(requireStringArg(args, 0, 'getPatternDeliverables')),
+    getPatternsByCategory: (api, args) => api.getPatternsByCategory(requireStringArg(args, 0, 'getPatternsByCategory')),
+    getCategories: (api) => api.getCategories(),
+    // Timeline queries
+    getPatternsByQuarter: (api, args) => api.getPatternsByQuarter(requireStringArg(args, 0, 'getPatternsByQuarter')),
+    getQuarters: (api) => api.getQuarters(),
+    getCurrentWork: (api) => api.getCurrentWork(),
+    getRoadmapItems: (api) => api.getRoadmapItems(),
+    getRecentlyCompleted: (api, args) => {
+        const limit = args[0] !== undefined ? Number(args[0]) : undefined;
+        return api.getRecentlyCompleted(limit);
+    },
+    // Raw access
+    getMasterDataset: (api) => api.getMasterDataset(),
+};
+function handleQuery(api, args) {
+    const methodName = args[0];
+    if (!methodName) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect query <method> [args...]\nMethods: ' + API_METHODS.join(', '));
+    }
+    if (!API_METHODS.includes(methodName)) {
+        throw new QueryApiError('UNKNOWN_METHOD', `Unknown API method: ${methodName}\nAvailable: ${API_METHODS.join(', ')}`);
+    }
+    const dispatch = API_DISPATCH[methodName];
+    const coercedArgs = args.slice(1).map(coerceArg);
+    return { methodName, result: dispatch(api, coercedArgs) };
+}
+function handlePattern(api, args) {
+    const name = args[0];
+    if (!name) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect pattern <name>');
+    }
+    const pattern = api.getPattern(name);
+    if (!pattern) {
+        const hint = suggestPattern(name, allPatternNames(api.getMasterDataset()));
+        throw new QueryApiError('PATTERN_NOT_FOUND', `Pattern not found: "${name}".${hint}`);
+    }
+    return {
+        ...pattern,
+        deliverables: api.getPatternDeliverables(name),
+        dependencies: api.getPatternDependencies(name),
+        relationships: api.getPatternRelationships(name),
+    };
+}
+/**
+ * Parse list-specific filter flags from subArgs.
+ */
+function parseListFilters(subArgs) {
+    let status = null;
+    let phase = null;
+    let category = null;
+    let source = null;
+    let archContext = null;
+    let productArea = null;
+    let limit = null;
+    let offset = null;
+    for (let i = 0; i < subArgs.length; i++) {
+        const arg = subArgs[i];
+        const next = subArgs[i + 1];
+        switch (arg) {
+            case '--status':
+                status = next ?? null;
+                i++;
+                break;
+            case '--phase': {
+                const parsed = next !== undefined ? parseInt(next, 10) : NaN;
+                if (isNaN(parsed)) {
+                    throw new QueryApiError('INVALID_ARGUMENT', `Invalid --phase value: "${next ?? ''}". Expected an integer.`);
+                }
+                phase = parsed;
+                i++;
+                break;
+            }
+            case '--category':
+                category = next ?? null;
+                i++;
+                break;
+            case '--source':
+                if (next === 'typescript' || next === 'ts') {
+                    source = 'typescript';
+                }
+                else if (next === 'gherkin' || next === 'feature') {
+                    source = 'gherkin';
+                }
+                i++;
+                break;
+            case '--limit': {
+                const parsed = next !== undefined ? parseInt(next, 10) : NaN;
+                if (isNaN(parsed) || parsed < 1) {
+                    throw new QueryApiError('INVALID_ARGUMENT', `Invalid --limit value: "${next ?? ''}". Expected a positive integer.`);
+                }
+                limit = parsed;
+                i++;
+                break;
+            }
+            case '--offset': {
+                const parsed = next !== undefined ? parseInt(next, 10) : NaN;
+                if (isNaN(parsed) || parsed < 0) {
+                    throw new QueryApiError('INVALID_ARGUMENT', `Invalid --offset value: "${next ?? ''}". Expected a non-negative integer.`);
+                }
+                offset = parsed;
+                i++;
+                break;
+            }
+            case '--arch-context':
+                archContext = next ?? null;
+                i++;
+                break;
+            case '--product-area':
+                productArea = next ?? null;
+                i++;
+                break;
+            default:
+                if (arg?.startsWith('-') === true) {
+                    console.warn(`Warning: Unknown flag '${arg}' ignored`);
+                }
+                break;
+        }
+    }
+    return { status, phase, category, source, archContext, productArea, limit, offset };
+}
+/**
+ * Generate contextual hint for empty list results.
+ */
+function generateEmptyHint(dataset, filters) {
+    if (filters.status !== null) {
+        const counts = dataset.counts;
+        const alternatives = [];
+        if (counts.active > 0 && filters.status !== 'active') {
+            alternatives.push(`${counts.active} active`);
+        }
+        if (counts.planned > 0 && filters.status !== 'roadmap') {
+            alternatives.push(`${counts.planned} roadmap`);
+        }
+        if (counts.completed > 0 && filters.status !== 'completed') {
+            alternatives.push(`${counts.completed} completed`);
+        }
+        if (alternatives.length > 0) {
+            // Pick the first available alternative for the suggestion command
+            const statusPriority = [
+                { status: 'active', count: counts.active },
+                { status: 'roadmap', count: counts.planned },
+                { status: 'completed', count: counts.completed },
+            ];
+            const altStatus = statusPriority.find((s) => s.count > 0 && s.status !== filters.status)?.status ?? 'active';
+            return `No ${filters.status} patterns. ${alternatives.join(', ')} exist. Try: list --status ${altStatus}`;
+        }
+    }
+    return undefined;
+}
+function handleList(dataset, subArgs, modifiers) {
+    const filters = parseListFilters(subArgs);
+    const filtered = applyListFilters(dataset, filters);
+    if (filtered.length === 0) {
+        const hint = generateEmptyHint(dataset, filters);
+        return { patterns: [], hint };
+    }
+    const input = { kind: 'patterns', data: filtered };
+    return applyOutputPipeline(input, modifiers);
+}
+function handleSearch(api, subArgs) {
+    const query = subArgs[0];
+    if (!query) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect search <query>');
+    }
+    const names = allPatternNames(api.getMasterDataset());
+    const matches = fuzzyMatchPatterns(query, names);
+    if (matches.length === 0) {
+        const hint = `No patterns matched "${query}".${suggestPattern(query, names)}`;
+        return { matches: [], hint };
+    }
+    return { matches };
+}
+async function handleArch(ctx) {
+    const args = ctx.subArgs;
+    const subCmd = args[0];
+    // Graph health commands work on relationshipIndex/validation, not archIndex
+    if (subCmd === 'dangling')
+        return ctx.validation.danglingReferences;
+    if (subCmd === 'orphans')
+        return findOrphanPatterns(ctx.dataset);
+    if (subCmd === 'blocking')
+        return buildOverview(ctx.dataset).blocking;
+    const archIndex = ctx.dataset.archIndex;
+    if (!archIndex || archIndex.all.length === 0) {
+        throw new QueryApiError('PATTERN_NOT_FOUND', 'No architecture data available. Ensure patterns have @architect-arch-role annotations.');
+    }
+    switch (subCmd) {
+        case 'roles':
+            return Object.entries(archIndex.byRole).map(([role, patterns]) => ({
+                role,
+                count: patterns.length,
+                patterns: patterns.map((p) => p.name),
+            }));
+        case 'context': {
+            const contextName = args[1];
+            if (!contextName) {
+                return Object.entries(archIndex.byContext).map(([ctxName, patterns]) => ({
+                    context: ctxName,
+                    count: patterns.length,
+                    patterns: patterns.map((p) => p.name),
+                }));
+            }
+            const contextPatterns = archIndex.byContext[contextName];
+            if (!contextPatterns) {
+                throw new QueryApiError('CATEGORY_NOT_FOUND', `Context not found: "${contextName}"\nAvailable: ${Object.keys(archIndex.byContext).join(', ')}`);
+            }
+            const ctxInput = { kind: 'patterns', data: contextPatterns };
+            return applyOutputPipeline(ctxInput, ctx.modifiers);
+        }
+        case 'layer': {
+            const layerName = args[1];
+            if (!layerName) {
+                return Object.entries(archIndex.byLayer).map(([layer, patterns]) => ({
+                    layer,
+                    count: patterns.length,
+                    patterns: patterns.map((p) => p.name),
+                }));
+            }
+            const layerPatterns = archIndex.byLayer[layerName];
+            if (!layerPatterns) {
+                throw new QueryApiError('CATEGORY_NOT_FOUND', `Layer not found: "${layerName}"\nAvailable: ${Object.keys(archIndex.byLayer).join(', ')}`);
+            }
+            const layerInput = { kind: 'patterns', data: layerPatterns };
+            return applyOutputPipeline(layerInput, ctx.modifiers);
+        }
+        case 'neighborhood': {
+            const patternName = args[1];
+            if (!patternName) {
+                throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect arch neighborhood <pattern>');
+            }
+            const neighborhood = computeNeighborhood(patternName, ctx.dataset);
+            if (neighborhood === undefined) {
+                const hint = suggestPattern(patternName, allPatternNames(ctx.dataset));
+                throw new QueryApiError('PATTERN_NOT_FOUND', `Pattern not found: "${patternName}".${hint}`);
+            }
+            return neighborhood;
+        }
+        case 'compare': {
+            const ctx1Name = args[1];
+            const ctx2Name = args[2];
+            if (!ctx1Name || !ctx2Name) {
+                throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect arch compare <ctx1> <ctx2>');
+            }
+            const comparison = compareContexts(ctx1Name, ctx2Name, ctx.dataset);
+            if (comparison === undefined) {
+                const available = Object.keys(archIndex.byContext).join(', ');
+                throw new QueryApiError('CONTEXT_NOT_FOUND', `Context not found. Available: ${available}`);
+            }
+            return comparison;
+        }
+        case 'coverage':
+            try {
+                return await analyzeCoverage(ctx.dataset, ctx.cliConfig.input, ctx.cliConfig.baseDir, ctx.registry);
+            }
+            catch (err) {
+                throw new QueryApiError('INVALID_ARGUMENT', `Coverage analysis failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        default:
+            throw new QueryApiError('UNKNOWN_METHOD', `Unknown arch subcommand: ${subCmd ?? '(none)'}\nAvailable: roles, context [name], layer [name], neighborhood <pattern>, compare <ctx1> <ctx2>, coverage, dangling, orphans, blocking`);
+    }
+}
+// =============================================================================
+// Stub Integration Handlers
+// =============================================================================
+function handleSequence(dataset, subArgs, modifiers) {
+    const index = dataset.sequenceIndex;
+    if (!index || Object.keys(index).length === 0) {
+        return { message: 'No patterns with sequence annotations found', patterns: [], count: 0 };
+    }
+    if (subArgs.length === 0) {
+        const patterns = Object.keys(index);
+        if (modifiers.count)
+            return { count: patterns.length };
+        if (modifiers.namesOnly)
+            return patterns;
+        return { patterns, count: patterns.length };
+    }
+    const patternName = subArgs[0] ?? '';
+    const entry = getSequenceEntry(dataset, patternName);
+    if (!entry) {
+        const available = Object.keys(index);
+        const hint = suggestPattern(patternName, available);
+        throw new QueryApiError('PATTERN_NOT_FOUND', `No sequence data for "${patternName}".${hint} Available: ${available.join(', ')}`);
+    }
+    return entry;
+}
+// =============================================================================
+function handleStubs(dataset, subArgs, baseDir) {
+    const stubs = findStubPatterns(dataset);
+    const resolutions = resolveStubs(stubs, baseDir);
+    // Parse optional pattern name and --unresolved flag
+    let patternFilter;
+    let unresolvedOnly = false;
+    for (const arg of subArgs) {
+        if (arg === '--unresolved') {
+            unresolvedOnly = true;
+        }
+        else {
+            patternFilter = arg;
+        }
+    }
+    let filtered = resolutions;
+    // Filter by pattern name if provided
+    if (patternFilter !== undefined) {
+        const lowerFilter = patternFilter.toLowerCase();
+        filtered = filtered.filter((r) => r.implementsPattern?.toLowerCase() === lowerFilter ||
+            r.stubName.toLowerCase() === lowerFilter);
+        if (filtered.length === 0) {
+            const stubNames = [...new Set(resolutions.map((r) => r.implementsPattern ?? r.stubName))];
+            const hint = suggestPattern(patternFilter, stubNames);
+            throw new QueryApiError('STUB_NOT_FOUND', `No stubs found for pattern: "${patternFilter}".${hint}`);
+        }
+    }
+    // Filter unresolved only
+    if (unresolvedOnly) {
+        filtered = filtered.filter((r) => !r.targetExists);
+    }
+    return groupStubsByPattern(filtered);
+}
+function handleDecisions(dataset, subArgs) {
+    const patternName = subArgs[0];
+    if (patternName === undefined) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Usage: decisions <pattern>');
+    }
+    // Find stubs implementing this pattern
+    const stubs = findStubPatterns(dataset);
+    const patternStubs = stubs.filter((s) => {
+        const implName = firstImplements(s);
+        return (implName?.toLowerCase() === patternName.toLowerCase() ||
+            getPatternName(s).toLowerCase() === patternName.toLowerCase());
+    });
+    if (patternStubs.length === 0) {
+        const stubNames = [...new Set(stubs.map((s) => firstImplements(s) ?? getPatternName(s)))];
+        const hint = suggestPattern(patternName, stubNames);
+        throw new QueryApiError('STUB_NOT_FOUND', `No decisions found for pattern: "${patternName}".${hint}`);
+    }
+    // Extract decisions from each stub's description
+    const decisions = patternStubs.map((stub) => ({
+        stub: getPatternName(stub),
+        file: stub.source.file,
+        since: stub.since,
+        decisions: extractDecisionItems(stub.directive.description),
+    }));
+    return {
+        pattern: patternName,
+        stubs: decisions,
+        totalDecisions: decisions.reduce((sum, d) => sum + d.decisions.length, 0),
+    };
+}
+function handlePdr(dataset, subArgs) {
+    const pdrNumber = subArgs[0];
+    if (pdrNumber === undefined) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Usage: pdr <number> (e.g., pdr 012)');
+    }
+    // Normalize: strip leading "PDR-" if user passed it
+    const normalizedNumber = pdrNumber.replace(/^PDR-/i, '').padStart(3, '0');
+    const references = findPdrReferences(dataset.patterns, normalizedNumber);
+    if (references.length === 0) {
+        throw new QueryApiError('PDR_NOT_FOUND', `No patterns reference PDR-${normalizedNumber}`);
+    }
+    return {
+        pdr: `PDR-${normalizedNumber}`,
+        referenceCount: references.length,
+        references,
+    };
+}
+// =============================================================================
+// Business Rules Handler
+// =============================================================================
+function parseRulesFilters(subArgs) {
+    let productArea = null;
+    let patternName = null;
+    let onlyInvariants = false;
+    for (let i = 0; i < subArgs.length; i++) {
+        const arg = subArgs[i];
+        if (arg === '--product-area') {
+            if (i + 1 >= subArgs.length || subArgs[i + 1]?.startsWith('-') === true) {
+                throw new QueryApiError('INVALID_ARGUMENT', '--product-area requires a value');
+            }
+            productArea = subArgs[++i] ?? null;
+        }
+        else if (arg === '--pattern') {
+            if (i + 1 >= subArgs.length || subArgs[i + 1]?.startsWith('-') === true) {
+                throw new QueryApiError('INVALID_ARGUMENT', '--pattern requires a value');
+            }
+            patternName = subArgs[++i] ?? null;
+        }
+        else if (arg === '--only-invariants') {
+            onlyInvariants = true;
+        }
+        else if (typeof arg === 'string' && arg.startsWith('-')) {
+            console.warn(`Warning: Unknown flag '${arg}' ignored`);
+        }
+    }
+    return { productArea, patternName, onlyInvariants };
+}
+function handleRules(ctx) {
+    const filters = parseRulesFilters(ctx.subArgs);
+    const result = queryBusinessRules(ctx.dataset, filters);
+    // Empty-result hint (delegated from query, applied per output modifier)
+    if (result.totalRules === 0 && (filters.productArea !== null || filters.patternName !== null)) {
+        if (ctx.modifiers.count) {
+            return { totalRules: 0, totalInvariants: 0, hint: result.hint };
+        }
+        if (ctx.modifiers.namesOnly) {
+            return { names: [], hint: result.hint };
+        }
+        return { productAreas: [], totalRules: 0, totalInvariants: 0, hint: result.hint };
+    }
+    // Handle output modifiers
+    if (ctx.modifiers.count) {
+        return { totalRules: result.totalRules, totalInvariants: result.totalInvariants };
+    }
+    if (ctx.modifiers.namesOnly) {
+        return result.allRuleNames;
+    }
+    return {
+        productAreas: result.productAreas,
+        totalRules: result.totalRules,
+        totalInvariants: result.totalInvariants,
+    };
+}
+// =============================================================================
+// Context Assembly Handlers (text output — ADR-008)
+// =============================================================================
+function parseSessionFromSubArgs(subArgs) {
+    const idx = subArgs.indexOf('--session');
+    if (idx === -1)
+        return null;
+    const val = subArgs[idx + 1];
+    if (val !== undefined && isValidSessionType(val))
+        return val;
+    return null;
+}
+function handleContext(ctx) {
+    const patternNames = [];
+    for (let i = 0; i < ctx.subArgs.length; i++) {
+        const arg = ctx.subArgs[i];
+        if (arg === '--session') {
+            i++; // skip the value
+            continue;
+        }
+        if (arg !== undefined && !arg.startsWith('-')) {
+            patternNames.push(arg);
+        }
+    }
+    if (patternNames.length === 0) {
+        throw new QueryApiError('CONTEXT_ASSEMBLY_ERROR', 'Usage: architect context <pattern> [pattern2...] [--session planning|design|implement]');
+    }
+    const sessionType = ctx.sessionType ?? parseSessionFromSubArgs(ctx.subArgs) ?? 'design';
+    const bundle = assembleContext(ctx.dataset, ctx.api, {
+        patterns: patternNames,
+        sessionType,
+        baseDir: ctx.baseDir,
+    });
+    return formatContextBundle(bundle);
+}
+function handleFiles(ctx) {
+    const patternName = ctx.subArgs.find((a) => !a.startsWith('-'));
+    if (patternName === undefined) {
+        throw new QueryApiError('CONTEXT_ASSEMBLY_ERROR', 'Usage: architect files <pattern> [--related]');
+    }
+    const includeRelated = ctx.subArgs.includes('--related');
+    const list = buildFileReadingList(ctx.dataset, patternName, includeRelated);
+    return formatFileReadingList(list);
+}
+function handleDepTreeCmd(ctx) {
+    const patternName = ctx.subArgs.find((a) => !a.startsWith('-'));
+    if (patternName === undefined) {
+        throw new QueryApiError('CONTEXT_ASSEMBLY_ERROR', 'Usage: architect dep-tree <pattern> [--depth N]');
+    }
+    // Parse --depth N
+    let maxDepth = 3;
+    const depthIdx = ctx.subArgs.indexOf('--depth');
+    if (depthIdx !== -1) {
+        const depthVal = ctx.subArgs[depthIdx + 1];
+        if (depthVal !== undefined) {
+            const parsed = parseInt(depthVal, 10);
+            if (!isNaN(parsed) && parsed > 0) {
+                maxDepth = Math.min(parsed, 10);
+            }
+        }
+    }
+    const tree = buildDepTree(ctx.dataset, {
+        pattern: patternName,
+        maxDepth,
+        includeImplementationDeps: true,
+    });
+    return formatDepTree(tree);
+}
+function handleOverviewCmd(ctx) {
+    const overview = buildOverview(ctx.dataset);
+    return formatOverview(overview);
+}
+// =============================================================================
+// Session Workflow Handlers (text output — ADR-008)
+// =============================================================================
+const VALID_SCOPE_TYPES = new Set(['implement', 'design']);
+function handleScopeValidate(ctx) {
+    // Parse pattern name (positional, first non-flag arg)
+    let patternName;
+    let scopeType = 'implement';
+    let strict = false;
+    for (let i = 0; i < ctx.subArgs.length; i++) {
+        const arg = ctx.subArgs[i];
+        if (arg === '--type') {
+            const val = ctx.subArgs[i + 1];
+            if (val !== undefined && VALID_SCOPE_TYPES.has(val)) {
+                scopeType = val;
+            }
+            else {
+                throw new QueryApiError('INVALID_ARGUMENT', `--type must be "implement" or "design", got: "${val ?? ''}"`);
+            }
+            i++;
+        }
+        else if (arg === '--strict') {
+            // DD-4: promotes WARN → BLOCKED (consistent with architect-guard --strict)
+            strict = true;
+        }
+        else if (arg !== undefined && !arg.startsWith('-')) {
+            if (patternName === undefined) {
+                patternName = arg;
+            }
+            else if (VALID_SCOPE_TYPES.has(arg)) {
+                // DD-6: positional scope type also accepted
+                scopeType = arg;
+            }
+        }
+    }
+    if (patternName === undefined) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect scope-validate <pattern> [implement|design] [--type implement|design] [--strict]');
+    }
+    const result = validateScope(ctx.api, ctx.dataset, {
+        patternName,
+        scopeType,
+        baseDir: ctx.baseDir,
+        strict,
+    });
+    return formatScopeValidation(result);
+}
+// 'review' is handoff-specific — not a global session type (parsed locally, not by top-level --session)
+const VALID_HANDOFF_SESSION_TYPES = new Set([
+    'planning',
+    'design',
+    'implement',
+    'review',
+]);
+function handleHandoff(ctx) {
+    let patternName;
+    let sessionType;
+    let useGit = false;
+    for (let i = 0; i < ctx.subArgs.length; i++) {
+        const arg = ctx.subArgs[i];
+        if (arg === '--pattern') {
+            patternName = ctx.subArgs[i + 1];
+            if (patternName === undefined) {
+                throw new QueryApiError('INVALID_ARGUMENT', '--pattern requires a value');
+            }
+            i++;
+        }
+        else if (arg === '--session') {
+            const val = ctx.subArgs[i + 1];
+            if (val !== undefined && VALID_HANDOFF_SESSION_TYPES.has(val)) {
+                sessionType = val;
+            }
+            else {
+                throw new QueryApiError('INVALID_ARGUMENT', `--session must be "planning", "design", "implement", or "review", got: "${val ?? ''}"`);
+            }
+            i++;
+        }
+        else if (arg === '--git') {
+            useGit = true;
+        }
+    }
+    // Also accept from top-level parsed --session
+    if (sessionType === undefined && ctx.sessionType !== null) {
+        sessionType = ctx.sessionType;
+    }
+    // Pattern name uses --pattern flag (not positional) to avoid ambiguity with --git and --session
+    if (patternName === undefined) {
+        throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect handoff --pattern <name> [--git] [--session planning|design|implement|review]');
+    }
+    // DD-2: git integration is opt-in — CLI handler owns the shell call
+    let modifiedFiles;
+    if (useGit) {
+        try {
+            const output = execSync('git diff --name-only HEAD', { encoding: 'utf-8' });
+            modifiedFiles = output
+                .trim()
+                .split('\n')
+                .filter((line) => line.length > 0);
+        }
+        catch (err) {
+            console.error(`Warning: git diff failed: ${err instanceof Error ? err.message : String(err)}. Handoff will not include modified files.`);
+            modifiedFiles = undefined;
+        }
+    }
+    const options = { patternName };
+    if (sessionType !== undefined) {
+        options.sessionType = sessionType;
+    }
+    if (modifiedFiles !== undefined) {
+        options.modifiedFiles = modifiedFiles;
+    }
+    const doc = generateHandoff(ctx.api, ctx.dataset, options);
+    return formatHandoff(doc);
+}
+// =============================================================================
+// Subcommand Router
+// =============================================================================
+async function routeSubcommand(ctx) {
+    switch (ctx.subcommand) {
+        case 'context':
+            return handleContext(ctx);
+        case 'files':
+            return handleFiles(ctx);
+        case 'dep-tree':
+            return handleDepTreeCmd(ctx);
+        case 'overview':
+            return handleOverviewCmd(ctx);
+        case 'scope-validate':
+            return handleScopeValidate(ctx);
+        case 'handoff':
+            return handleHandoff(ctx);
+        case 'status':
+            return handleStatus(ctx.api);
+        case 'query': {
+            const { methodName, result } = handleQuery(ctx.api, ctx.subArgs);
+            // Apply output pipeline for pattern-array methods
+            if (PATTERN_ARRAY_METHODS.has(methodName)) {
+                const input = {
+                    kind: 'patterns',
+                    data: result,
+                };
+                return applyOutputPipeline(input, ctx.modifiers);
+            }
+            return result;
+        }
+        case 'pattern':
+            return handlePattern(ctx.api, ctx.subArgs);
+        case 'list':
+            return handleList(ctx.dataset, ctx.subArgs, ctx.modifiers);
+        case 'search':
+            return handleSearch(ctx.api, ctx.subArgs);
+        case 'arch':
+            return handleArch(ctx);
+        case 'stubs':
+            return handleStubs(ctx.dataset, ctx.subArgs, ctx.cliConfig.baseDir);
+        case 'decisions':
+            return handleDecisions(ctx.dataset, ctx.subArgs);
+        case 'pdr':
+            return handlePdr(ctx.dataset, ctx.subArgs);
+        case 'rules':
+            return handleRules(ctx);
+        case 'tags':
+            return aggregateTagUsage(ctx.dataset);
+        case 'sources':
+            return buildSourceInventory(ctx.dataset);
+        case 'sequence':
+            return handleSequence(ctx.dataset, ctx.subArgs, ctx.modifiers);
+        case 'unannotated': {
+            let pathFilter;
+            for (let i = 0; i < ctx.subArgs.length; i++) {
+                if (ctx.subArgs[i] === '--path') {
+                    pathFilter = ctx.subArgs[i + 1];
+                    break;
+                }
+            }
+            try {
+                return await findUnannotatedFiles(ctx.cliConfig.input, ctx.cliConfig.baseDir, ctx.registry, pathFilter);
+            }
+            catch (err) {
+                throw new QueryApiError('INVALID_ARGUMENT', `Unannotated file scan failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        default:
+            throw new QueryApiError('UNKNOWN_METHOD', `Unknown subcommand: ${ctx.subcommand}\nAvailable: context, files, dep-tree, overview, scope-validate, handoff, status, query, pattern, list, search, arch, stubs, decisions, pdr, rules, tags, sources, sequence, unannotated`);
+    }
+}
+// =============================================================================
+// Main
+// =============================================================================
+/**
+ * Build extended query metadata from pipeline results.
+ */
+function buildQueryMetadataExtra(validation, cacheHit, cacheAgeMs, pipelineMs) {
+    return {
+        validation: {
+            danglingReferenceCount: validation.danglingReferences.length,
+            malformedPatternCount: validation.malformedPatterns.length,
+            unknownStatusCount: validation.unknownStatuses.length,
+            warningCount: validation.warningCount,
+        },
+        cache: cacheAgeMs !== undefined ? { hit: cacheHit, ageMs: cacheAgeMs } : { hit: cacheHit },
+        pipelineMs,
+    };
+}
+async function main() {
+    const opts = parseArgs();
+    if (opts.version) {
+        printVersionAndExit('architect');
+    }
+    if (opts.help || !opts.subcommand) {
+        showHelp();
+        process.exit(opts.help ? 0 : 1);
+    }
+    // Per-subcommand help (e.g., `architect context --help`)
+    if (opts.subcommandHelp !== null) {
+        showSubcommandHelp(opts.subcommandHelp);
+        process.exit(0);
+    }
+    // REPL mode: interactive multi-query session (manages its own pipeline lifecycle)
+    if (opts.subcommand === 'repl') {
+        await applyConfigDefaults(opts);
+        await startRepl({
+            input: opts.input,
+            features: opts.features,
+            baseDir: opts.baseDir,
+            workflowPath: opts.workflowPath,
+        });
+        return;
+    }
+    // Validate output modifiers before any expensive work
+    validateModifiers(opts.modifiers);
+    // FSM short-circuit: bypass pipeline for static FSM queries (2-5s saving)
+    if (opts.subcommand === 'query') {
+        const fsmResult = tryFsmShortCircuit(opts.subcommand, opts.subArgs);
+        if (fsmResult !== undefined) {
+            const envelope = createSuccess(fsmResult, 0);
+            const output = formatOutput(envelope, opts.format);
+            console.log(output);
+            return;
+        }
+    }
+    // Resolve config file defaults if --input and --features not provided
+    await applyConfigDefaults(opts);
+    if (opts.input.length === 0) {
+        console.error('Error: --input is required (or place architect.config.ts or architect.config.js in your project for auto-detection)');
+        console.error('');
+        console.error('Example:');
+        console.error('  architect -i "src/**/*.ts" status');
+        process.exit(1);
+    }
+    // Dry-run: show pipeline scope without executing
+    if (opts.dryRun) {
+        await executeDryRun(opts);
+        return;
+    }
+    // Pipeline execution with caching
+    const startMs = performance.now();
+    let pipelineResult;
+    let cacheHit = false;
+    let cacheAgeMs;
+    if (!opts.noCache) {
+        const cacheDir = getCacheDir(opts.baseDir);
+        const cacheKey = await computeCacheKey({
+            input: opts.input,
+            features: opts.features,
+            baseDir: opts.baseDir,
+            mergeConflictStrategy: 'fatal',
+            ...(opts.workflowPath !== null ? { workflowPath: opts.workflowPath } : {}),
+        });
+        const cached = await tryLoadCache(cacheKey, cacheDir);
+        if (cached !== undefined) {
+            pipelineResult = cached.result;
+            cacheHit = true;
+            cacheAgeMs = cached.ageMs;
+        }
+        else {
+            pipelineResult = await buildPipeline(opts);
+            void writeCache(pipelineResult, cacheKey, cacheDir);
+        }
+    }
+    else {
+        pipelineResult = await buildPipeline(opts);
+    }
+    const pipelineMs = Math.round(performance.now() - startMs);
+    const { dataset: masterDataset, validation } = pipelineResult;
+    // Build extended metadata for JSON responses
+    const extra = buildQueryMetadataExtra(validation, cacheHit, cacheAgeMs, pipelineMs);
+    // Create ProcessStateAPI
+    const api = createProcessStateAPI(masterDataset);
+    // Route and execute subcommand
+    const result = await routeSubcommand({
+        api,
+        dataset: masterDataset,
+        validation,
+        subcommand: opts.subcommand,
+        subArgs: opts.subArgs,
+        modifiers: opts.modifiers,
+        sessionType: opts.sessionType,
+        baseDir: path.resolve(opts.baseDir),
+        cliConfig: { input: opts.input, features: opts.features, baseDir: opts.baseDir },
+        registry: masterDataset.tagRegistry,
+    });
+    // Dual output path (ADR-008):
+    // Text commands (context, files, dep-tree, overview) return string → output directly.
+    // JSON commands return objects → wrap in QueryResult envelope.
+    if (typeof result === 'string') {
+        console.log(result);
+    }
+    else {
+        const envelope = createSuccess(result, masterDataset.counts.total, extra);
+        const output = formatOutput(envelope, opts.format);
+        console.log(output);
+    }
+}
+void main().catch((error) => {
+    // QueryApiError -> structured error envelope
+    if (error instanceof QueryApiError) {
+        const envelope = createError(error.code, error.message);
+        console.log(JSON.stringify(envelope, null, 2));
+        process.exit(1);
+        return;
+    }
+    handleCliError(error, 1);
+});
+//# sourceMappingURL=process-api.js.map