@libar-dev/architect 1.0.0-pre.3

package/dist/api/scope-validator.js

@@ -0,0 +1,293 @@
+/**
+ * @architect
+ * @architect-pattern ScopeValidatorImpl
+ * @architect-status completed
+ * @architect-implements DataAPIDesignSessionSupport
+ * @architect-uses ProcessStateAPI, MasterDataset, StubResolverImpl
+ * @architect-used-by ProcessAPICLIImpl
+ * @architect-target src/api/scope-validator.ts
+ * @architect-arch-role service
+ * @architect-arch-context api
+ * @architect-arch-layer application
+ *
+ * ## ScopeValidator — Pre-flight Session Readiness Checker
+ *
+ * Pure function composition over ProcessStateAPI and MasterDataset.
+ * Runs a checklist of prerequisite validations before starting a
+ * design or implementation session.
+ *
+ * **When to Use:** When running pre-flight checks before a session via the `scope-validate` CLI subcommand.
+ */
+import { QueryApiError } from './types.js';
+import { getPatternName, findPatternByName, firstImplements } from './pattern-helpers.js';
+import { findStubPatterns, resolveStubs, extractDecisionItems } from './stub-resolver.js';
+import { VALID_PROCESS_STATUS_SET } from '../taxonomy/index.js';
+import { isPatternComplete } from '../taxonomy/normalized-status.js';
+// ---------------------------------------------------------------------------
+// Valid statuses for FSM transition checks
+// ---------------------------------------------------------------------------
+const VALID_STATUSES = VALID_PROCESS_STATUS_SET;
+// ---------------------------------------------------------------------------
+// Main Entry Point
+// ---------------------------------------------------------------------------
+export function validateScope(api, dataset, options) {
+    const { patternName, scopeType, baseDir, strict } = options;
+    const pattern = api.getPattern(patternName);
+    if (pattern === undefined) {
+        throw new QueryApiError('PATTERN_NOT_FOUND', `Pattern not found: "${patternName}"`);
+    }
+    const rawChecks = [];
+    if (scopeType === 'implement') {
+        rawChecks.push(checkDependenciesCompleted(api, patternName));
+        rawChecks.push(checkDeliverablesDefined(api, patternName));
+        rawChecks.push(checkFsmAllowsTransition(api, patternName));
+        rawChecks.push(checkDesignDecisionsRecorded(dataset, patternName));
+        rawChecks.push(checkExecutableSpecsSet(api, patternName));
+    }
+    else {
+        rawChecks.push(checkStubsFromDepsExist(dataset, patternName, baseDir));
+    }
+    // DD-4: --strict promotes WARN → BLOCKED
+    const checks = strict === true
+        ? rawChecks.map((c) => (c.severity === 'WARN' ? { ...c, severity: 'BLOCKED' } : c))
+        : rawChecks;
+    const blockerCount = checks.filter((c) => c.severity === 'BLOCKED').length;
+    const warnCount = checks.filter((c) => c.severity === 'WARN').length;
+    let verdict;
+    if (blockerCount > 0) {
+        verdict = 'blocked';
+    }
+    else if (warnCount > 0) {
+        verdict = 'warnings';
+    }
+    else {
+        verdict = 'ready';
+    }
+    return {
+        pattern: getPatternName(pattern),
+        scopeType,
+        checks,
+        verdict,
+        blockerCount,
+        warnCount,
+    };
+}
+// ---------------------------------------------------------------------------
+// Text Formatter (co-located per PDR-002 DD-7)
+// ---------------------------------------------------------------------------
+export function formatScopeValidation(result) {
+    const sections = [];
+    sections.push(`=== SCOPE VALIDATION: ${result.pattern} (${result.scopeType}) ===`);
+    const checkLines = result.checks.map((c) => {
+        const blockers = c.blockerNames !== undefined && c.blockerNames.length > 0
+            ? `\n    Blockers: ${c.blockerNames.join(', ')}`
+            : '';
+        return `[${c.severity}] ${c.label}: ${c.detail}${blockers}`;
+    });
+    sections.push('=== CHECKLIST ===\n' + checkLines.join('\n'));
+    let verdictText;
+    if (result.verdict === 'blocked') {
+        const blockerDetails = result.checks
+            .filter((c) => c.severity === 'BLOCKED')
+            .map((c) => `- ${c.label}: ${c.detail}`);
+        verdictText =
+            `BLOCKED: ${result.blockerCount} blocker(s) prevent ${result.scopeType} session` +
+                '\n' +
+                blockerDetails.join('\n');
+    }
+    else if (result.verdict === 'warnings') {
+        verdictText = `READY (with ${result.warnCount} warning(s)): ${result.scopeType} session can proceed`;
+    }
+    else {
+        verdictText = `READY: All checks passed for ${result.scopeType} session`;
+    }
+    sections.push('=== VERDICT ===\n' + verdictText);
+    return sections.join('\n\n') + '\n';
+}
+// ---------------------------------------------------------------------------
+// Composable Check Functions — Implementation Session
+// ---------------------------------------------------------------------------
+export function checkDependenciesCompleted(api, patternName) {
+    const deps = api.getPatternDependencies(patternName);
+    const dependsOn = deps?.dependsOn ?? [];
+    if (dependsOn.length === 0) {
+        return {
+            id: 'dependencies-completed',
+            label: 'Dependencies completed',
+            severity: 'PASS',
+            detail: 'No dependencies',
+        };
+    }
+    const blockers = [];
+    for (const depName of dependsOn) {
+        const depPattern = api.getPattern(depName);
+        const status = depPattern?.status ?? 'unknown';
+        if (!isPatternComplete(depPattern?.status)) {
+            blockers.push(`${depName} (${status})`);
+        }
+    }
+    if (blockers.length === 0) {
+        return {
+            id: 'dependencies-completed',
+            label: 'Dependencies completed',
+            severity: 'PASS',
+            detail: `${dependsOn.length}/${dependsOn.length} completed`,
+        };
+    }
+    return {
+        id: 'dependencies-completed',
+        label: 'Dependencies completed',
+        severity: 'BLOCKED',
+        detail: `${dependsOn.length - blockers.length}/${dependsOn.length} completed`,
+        blockerNames: blockers,
+    };
+}
+export function checkDeliverablesDefined(api, patternName) {
+    const deliverables = api.getPatternDeliverables(patternName);
+    if (deliverables.length > 0) {
+        return {
+            id: 'deliverables-defined',
+            label: 'Deliverables defined',
+            severity: 'PASS',
+            detail: `${deliverables.length} deliverable(s) found`,
+        };
+    }
+    return {
+        id: 'deliverables-defined',
+        label: 'Deliverables defined',
+        severity: 'BLOCKED',
+        detail: 'No deliverables found in Background table',
+    };
+}
+export function checkFsmAllowsTransition(api, patternName) {
+    const pattern = api.getPattern(patternName);
+    const status = pattern?.status;
+    if (status === undefined || !VALID_STATUSES.has(status)) {
+        return {
+            id: 'fsm-allows-transition',
+            label: 'FSM allows transition',
+            severity: 'BLOCKED',
+            detail: `Unknown status: ${status ?? 'undefined'}`,
+        };
+    }
+    // Pattern is already active — no transition needed for implement session
+    if (status === 'active') {
+        return {
+            id: 'fsm-allows-transition',
+            label: 'FSM allows transition',
+            severity: 'PASS',
+            detail: 'Already active — no transition needed',
+        };
+    }
+    const isValid = api.isValidTransition(status, 'active');
+    if (isValid) {
+        return {
+            id: 'fsm-allows-transition',
+            label: 'FSM allows transition',
+            severity: 'PASS',
+            detail: `${status} → active is valid`,
+        };
+    }
+    const check = api.checkTransition(status, 'active');
+    const alternatives = check.validAlternatives ?? [];
+    const altText = alternatives.length > 0 ? ` Valid from: ${alternatives.join(', ')}` : '';
+    return {
+        id: 'fsm-allows-transition',
+        label: 'FSM allows transition',
+        severity: 'BLOCKED',
+        detail: `${status} → active is not valid.${altText}`,
+    };
+}
+export function checkDesignDecisionsRecorded(dataset, patternName) {
+    const stubs = findStubPatterns(dataset);
+    const lowerName = patternName.toLowerCase();
+    const patternStubs = stubs.filter((s) => {
+        const implName = firstImplements(s);
+        return implName?.toLowerCase() === lowerName;
+    });
+    let totalDecisions = 0;
+    for (const stub of patternStubs) {
+        const decisions = extractDecisionItems(stub.directive.description);
+        totalDecisions += decisions.length;
+    }
+    if (totalDecisions > 0) {
+        return {
+            id: 'design-decisions-recorded',
+            label: 'Design decisions recorded',
+            severity: 'PASS',
+            detail: `${totalDecisions} decision(s) found in ${patternStubs.length} stub(s)`,
+        };
+    }
+    return {
+        id: 'design-decisions-recorded',
+        label: 'Design decisions recorded',
+        severity: 'WARN',
+        detail: 'No PDR/AD references found in stubs',
+    };
+}
+export function checkExecutableSpecsSet(api, patternName) {
+    const pattern = api.getPattern(patternName);
+    if (pattern?.behaviorFile !== undefined) {
+        return {
+            id: 'executable-specs-set',
+            label: 'Executable specs location set',
+            severity: 'PASS',
+            detail: pattern.behaviorFile,
+        };
+    }
+    return {
+        id: 'executable-specs-set',
+        label: 'Executable specs location set',
+        severity: 'WARN',
+        detail: 'No @executable-specs tag found',
+    };
+}
+// ---------------------------------------------------------------------------
+// Composable Check Functions — Design Session
+// ---------------------------------------------------------------------------
+export function checkStubsFromDepsExist(dataset, patternName, baseDir) {
+    const pattern = findPatternByName(dataset.patterns, patternName);
+    const dependsOn = pattern?.dependsOn ?? [];
+    if (dependsOn.length === 0) {
+        return {
+            id: 'stubs-from-deps-exist',
+            label: 'Stubs from dependencies exist',
+            severity: 'PASS',
+            detail: 'No dependencies to check',
+        };
+    }
+    const allStubs = findStubPatterns(dataset);
+    const depsWithoutStubs = [];
+    for (const depName of dependsOn) {
+        const lowerDep = depName.toLowerCase();
+        const depStubs = allStubs.filter((s) => {
+            const implName = firstImplements(s);
+            return implName?.toLowerCase() === lowerDep;
+        });
+        if (depStubs.length === 0) {
+            depsWithoutStubs.push(depName);
+            continue;
+        }
+        const resolved = resolveStubs(depStubs, baseDir);
+        const anyExists = resolved.some((r) => r.targetExists);
+        if (!anyExists) {
+            depsWithoutStubs.push(depName);
+        }
+    }
+    if (depsWithoutStubs.length === 0) {
+        return {
+            id: 'stubs-from-deps-exist',
+            label: 'Stubs from dependencies exist',
+            severity: 'PASS',
+            detail: `All ${dependsOn.length} dependencies have stubs`,
+        };
+    }
+    return {
+        id: 'stubs-from-deps-exist',
+        label: 'Stubs from dependencies exist',
+        severity: 'WARN',
+        detail: `${depsWithoutStubs.length}/${dependsOn.length} dependencies lack stubs`,
+        blockerNames: depsWithoutStubs,
+    };
+}
+//# sourceMappingURL=scope-validator.js.map

package/dist/api/scope-validator.js.map

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

package/dist/api/stub-resolver.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @architect
+ * @architect-pattern StubResolverImpl
+ * @architect-status active
+ * @architect-implements DataAPIStubIntegration
+ * @architect-uses ProcessStateAPI
+ * @architect-used-by ProcessAPICLIImpl
+ *
+ * ## StubResolver — Design Stub Discovery and Resolution
+ *
+ * Identifies design session stubs in the MasterDataset and resolves them
+ * against the filesystem to determine implementation status.
+ *
+ * Stub identification heuristic:
+ * - Source file path contains `/stubs/` (lives in stubs directory), OR
+ * - Pattern has a `targetPath` field (from @architect-target tag)
+ *
+ * Resolution uses a `fileExists` callback (defaulting to `fs.existsSync()`) on
+ * targetPath — not pipeline data — because target files may not have `@architect`
+ * annotations. The callback enables testing without filesystem side effects.
+ *
+ * **When to Use:** When querying design stub status via the `stubs` CLI subcommand or when checking stub resolution in scope validation.
+ */
+import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js';
+import type { MasterDataset } from '../validation-schemas/master-dataset.js';
+/**
+ * Result of resolving a single stub against the filesystem.
+ */
+export interface StubResolution {
+    /** The stub's pattern name */
+    readonly stubName: string;
+    /** Source file path of the stub */
+    readonly stubFile: string;
+    /** Target implementation path (from @architect-target) */
+    readonly targetPath: string;
+    /** Design session that created this stub (from @architect-since) */
+    readonly since: string | undefined;
+    /** Parent pattern this stub implements (from @architect-implements) */
+    readonly implementsPattern: string | undefined;
+    /** Whether the target file exists on disk */
+    readonly targetExists: boolean;
+}
+/**
+ * Summary of all stubs grouped by the pattern they implement.
+ */
+export interface StubSummary {
+    /** Pattern name that stubs implement */
+    readonly pattern: string;
+    /** All stubs for this pattern */
+    readonly stubs: readonly StubResolution[];
+    /** Count of resolved (target exists) stubs */
+    readonly resolvedCount: number;
+    /** Count of unresolved (target missing) stubs */
+    readonly unresolvedCount: number;
+}
+/**
+ * A single extracted decision item from stub description text.
+ */
+export interface DecisionItem {
+    /** Decision ID (e.g., "AD-1") */
+    readonly id: string;
+    /** Description text */
+    readonly description: string;
+    /** Referenced PDR number, if any */
+    readonly pdr: string | undefined;
+}
+/**
+ * A pattern reference to a PDR.
+ */
+export interface PdrReference {
+    /** Pattern name referencing the PDR */
+    readonly pattern: string;
+    /** Where the reference was found */
+    readonly source: 'description' | 'seeAlso';
+    /** Source file path */
+    readonly filePath: string;
+}
+/**
+ * Identify stub patterns from the MasterDataset.
+ *
+ * A pattern is a stub if:
+ * 1. Its source file path contains '/stubs/' (lives in stubs directory), OR
+ * 2. It has a `targetPath` field (from @architect-target tag)
+ */
+export declare function findStubPatterns(dataset: MasterDataset): readonly ExtractedPattern[];
+/**
+ * Resolve stubs against the filesystem to determine implementation status.
+ *
+ * For each stub pattern with a `targetPath`:
+ * - Resolves the path relative to baseDir
+ * - Checks if the target file exists via `fileExists` callback
+ * - Extracts stub metadata (since, implementsPattern)
+ */
+export declare function resolveStubs(stubs: readonly ExtractedPattern[], baseDir: string, fileExists?: (path: string) => boolean): readonly StubResolution[];
+/**
+ * Group stub resolutions by the pattern they implement.
+ *
+ * Stubs that share the same `implementsPattern` value are grouped together.
+ * Stubs without an `implementsPattern` are grouped under their own stubName.
+ */
+export declare function groupStubsByPattern(resolutions: readonly StubResolution[]): readonly StubSummary[];
+/**
+ * Extract AD-N decision items from a pattern's description text.
+ *
+ * Parses JSDoc description for references like:
+ * - `AD-1: Unified action model (PDR-011)`
+ * - `AD-5: Router maps command types to orchestrator`
+ */
+export declare function extractDecisionItems(description: string): readonly DecisionItem[];
+/**
+ * Cross-reference all patterns that mention a specific PDR number.
+ *
+ * Scans pattern descriptions and seeAlso references
+ * for `PDR-{number}` occurrences.
+ */
+export declare function findPdrReferences(patterns: readonly ExtractedPattern[], pdrNumber: string): readonly PdrReference[];
+//# sourceMappingURL=stub-resolver.d.ts.map

package/dist/api/stub-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-resolver.d.ts","sourceRoot":"","sources":["../../src/api/stub-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAO7E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,gBAAgB,EAAE,CAIpF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAClC,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAoB,GACjD,SAAS,cAAc,EAAE,CAe3B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,cAAc,EAAE,GACrC,SAAS,WAAW,EAAE,CAyBxB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE,CAoBjF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,SAAS,EAAE,MAAM,GAChB,SAAS,YAAY,EAAE,CAgCzB"}

package/dist/api/stub-resolver.js

@@ -0,0 +1,154 @@
+/**
+ * @architect
+ * @architect-pattern StubResolverImpl
+ * @architect-status active
+ * @architect-implements DataAPIStubIntegration
+ * @architect-uses ProcessStateAPI
+ * @architect-used-by ProcessAPICLIImpl
+ *
+ * ## StubResolver — Design Stub Discovery and Resolution
+ *
+ * Identifies design session stubs in the MasterDataset and resolves them
+ * against the filesystem to determine implementation status.
+ *
+ * Stub identification heuristic:
+ * - Source file path contains `/stubs/` (lives in stubs directory), OR
+ * - Pattern has a `targetPath` field (from @architect-target tag)
+ *
+ * Resolution uses a `fileExists` callback (defaulting to `fs.existsSync()`) on
+ * targetPath — not pipeline data — because target files may not have `@architect`
+ * annotations. The callback enables testing without filesystem side effects.
+ *
+ * **When to Use:** When querying design stub status via the `stubs` CLI subcommand or when checking stub resolution in scope validation.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getPatternName, firstImplements } from './pattern-helpers.js';
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+/**
+ * Identify stub patterns from the MasterDataset.
+ *
+ * A pattern is a stub if:
+ * 1. Its source file path contains '/stubs/' (lives in stubs directory), OR
+ * 2. It has a `targetPath` field (from @architect-target tag)
+ */
+export function findStubPatterns(dataset) {
+    return dataset.patterns.filter((p) => p.source.file.includes('/stubs/') || p.targetPath !== undefined);
+}
+/**
+ * Resolve stubs against the filesystem to determine implementation status.
+ *
+ * For each stub pattern with a `targetPath`:
+ * - Resolves the path relative to baseDir
+ * - Checks if the target file exists via `fileExists` callback
+ * - Extracts stub metadata (since, implementsPattern)
+ */
+export function resolveStubs(stubs, baseDir, fileExists = existsSync) {
+    return stubs.map((stub) => {
+        const targetPath = stub.targetPath ?? '';
+        const absoluteTarget = targetPath !== '' ? resolve(baseDir, targetPath) : '';
+        const targetExists = targetPath !== '' && fileExists(absoluteTarget);
+        return {
+            stubName: getPatternName(stub),
+            stubFile: stub.source.file,
+            targetPath,
+            since: stub.since,
+            implementsPattern: firstImplements(stub),
+            targetExists,
+        };
+    });
+}
+/**
+ * Group stub resolutions by the pattern they implement.
+ *
+ * Stubs that share the same `implementsPattern` value are grouped together.
+ * Stubs without an `implementsPattern` are grouped under their own stubName.
+ */
+export function groupStubsByPattern(resolutions) {
+    const groups = new Map();
+    for (const resolution of resolutions) {
+        const key = resolution.implementsPattern ?? resolution.stubName;
+        const existing = groups.get(key);
+        if (existing !== undefined) {
+            existing.push(resolution);
+        }
+        else {
+            groups.set(key, [resolution]);
+        }
+    }
+    const summaries = [];
+    for (const [pattern, stubs] of groups) {
+        const resolvedCount = stubs.filter((s) => s.targetExists).length;
+        summaries.push({
+            pattern,
+            stubs,
+            resolvedCount,
+            unresolvedCount: stubs.length - resolvedCount,
+        });
+    }
+    return summaries.sort((a, b) => a.pattern.localeCompare(b.pattern));
+}
+/**
+ * Extract AD-N decision items from a pattern's description text.
+ *
+ * Parses JSDoc description for references like:
+ * - `AD-1: Unified action model (PDR-011)`
+ * - `AD-5: Router maps command types to orchestrator`
+ */
+export function extractDecisionItems(description) {
+    const items = [];
+    const regex = /AD-(\d+):\s*(.+?)(?:\s*\(PDR-(\d+)\))?$/gm;
+    let match = regex.exec(description);
+    while (match !== null) {
+        const adNum = match[1];
+        const desc = match[2];
+        const pdrNum = match[3];
+        if (adNum !== undefined && desc !== undefined) {
+            items.push({
+                id: `AD-${adNum}`,
+                description: desc.trim(),
+                pdr: pdrNum !== undefined ? `PDR-${pdrNum}` : undefined,
+            });
+        }
+        match = regex.exec(description);
+    }
+    return items;
+}
+/**
+ * Cross-reference all patterns that mention a specific PDR number.
+ *
+ * Scans pattern descriptions and seeAlso references
+ * for `PDR-{number}` occurrences.
+ */
+export function findPdrReferences(patterns, pdrNumber) {
+    const references = [];
+    const pdrTag = `PDR-${pdrNumber}`;
+    for (const pattern of patterns) {
+        const displayName = getPatternName(pattern);
+        // Check description text (lives on the directive)
+        if (pattern.directive.description.includes(pdrTag)) {
+            references.push({
+                pattern: displayName,
+                source: 'description',
+                filePath: pattern.source.file,
+            });
+        }
+        // Check seeAlso references (top-level on ExtractedPattern)
+        if (pattern.seeAlso !== undefined) {
+            for (const ref of pattern.seeAlso) {
+                if (ref.includes(pdrTag)) {
+                    references.push({
+                        pattern: displayName,
+                        source: 'seeAlso',
+                        filePath: pattern.source.file,
+                    });
+                    break; // One reference per pattern per source
+                }
+            }
+        }
+    }
+    return references;
+}
+//# sourceMappingURL=stub-resolver.js.map

package/dist/api/stub-resolver.js.map

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

package/dist/api/summarize.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern PatternSummarizerImpl
+ * @architect-status active
+ * @architect-implements DataAPIOutputShaping
+ * @architect-uses ProcessStateAPI
+ * @architect-used-by OutputPipeline, ProcessAPICLIImpl
+ * @architect-arch-role service
+ * @architect-arch-context api
+ * @architect-arch-layer application
+ *
+ * ## PatternSummarizer — Compact Pattern Projection
+ *
+ * Projects the full ExtractedPattern (~3.5KB per pattern) down to a
+ * PatternSummary (~100 bytes) for list queries. Reduces CLI output
+ * from ~594KB to ~4KB for typical codebases.
+ *
+ * Uses Zod schema-first pattern: PatternSummarySchema defines the type,
+ * and PatternSummary is inferred from it.
+ *
+ * **When to Use:** When projecting full ExtractedPattern data down to compact summaries for list and overview queries.
+ */
+import { z } from 'zod';
+import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js';
+/**
+ * Compact projection of ExtractedPattern for list queries.
+ *
+ * Fields selected for maximum information density at minimum size:
+ * - patternName: identifies the pattern
+ * - status: FSM state (roadmap/active/completed/deferred)
+ * - category: domain classification
+ * - phase: roadmap phase number (for sequencing)
+ * - file: source file path (for navigation)
+ * - source: typescript or gherkin (for filtering)
+ */
+export declare const PatternSummarySchema: z.ZodObject<{
+    patternName: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    category: z.ZodString;
+    phase: z.ZodOptional<z.ZodNumber>;
+    file: z.ZodString;
+    source: z.ZodEnum<{
+        gherkin: "gherkin";
+        typescript: "typescript";
+    }>;
+}, z.core.$strip>;
+export type PatternSummary = z.infer<typeof PatternSummarySchema>;
+/**
+ * Valid field names for PatternSummary, used by --fields validation.
+ */
+export declare const SUMMARY_FIELDS: ReadonlySet<string>;
+/**
+ * Derive source type from file extension.
+ */
+export declare function deriveSource(filePath: string): 'typescript' | 'gherkin';
+/**
+ * Project an ExtractedPattern to a compact PatternSummary.
+ *
+ * - `patternName` prefers explicit @architect-pattern tag, falls back to `name`
+ * - `source` is derived from file extension (.feature -> gherkin, else typescript)
+ * - Optional fields (status, phase) are included when present, omitted when undefined
+ *
+ * @param pattern - Full ExtractedPattern from the pipeline
+ * @returns Compact PatternSummary (~100 bytes JSON)
+ */
+export declare function summarizePattern(pattern: ExtractedPattern): PatternSummary;
+/**
+ * Project an array of ExtractedPatterns to compact summaries.
+ *
+ * @param patterns - Array of ExtractedPatterns
+ * @returns Array of PatternSummary objects
+ */
+export declare function summarizePatterns(patterns: readonly ExtractedPattern[]): readonly PatternSummary[];
+//# sourceMappingURL=summarize.d.ts.map

package/dist/api/summarize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.d.ts","sourceRoot":"","sources":["../../src/api/summarize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAOnF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAO/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAO7C,CAAC;AAMH;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAS1E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,SAAS,cAAc,EAAE,CAE3B"}