@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/cli/index.d.ts

@@ -1,6 +1,19 @@
 #!/usr/bin/env node
 /**
  * AI-SDLC CLI — entry point for the Commander-based CLI.
+ *
+ * AISDLC-78: replaces the literal `0.1.0` version with the real package
+ * version, prints a 3-line provenance block on `--version`, and adds an
+ * unknown-subcommand hint that points at the upgrade flow when version
+ * drift is detected.
  */
-export {};
+import { Command } from 'commander';
+import { type VersionTriple } from './versions.js';
+/**
+ * Build the Commander program. Exported so integration tests can drive
+ * the real argv pipeline (`--version`, unknown-subcommand) without
+ * invoking the bundled binary on disk. The bin shim below calls this
+ * exact factory at startup.
+ */
+export declare function buildProgram(versions: VersionTriple): Command;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 /**
  * AI-SDLC CLI — entry point for the Commander-based CLI.
+ *
+ * AISDLC-78: replaces the literal `0.1.0` version with the real package
+ * version, prints a 3-line provenance block on `--version`, and adds an
+ * unknown-subcommand hint that points at the upgrade flow when version
+ * drift is detected.
  */
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
@@ -14,24 +19,80 @@ import { complexityCommand } from './commands/complexity.js';
 import { costCommand } from './commands/cost.js';
 import { dashboardCommand } from './commands/dashboard.js';
 import { validateCommand } from './commands/validate.js';
-const program = new Command();
-program
-    .name('ai-sdlc')
-    .description('AI-SDLC Orchestrator — drive issues through the SDLC with AI agents')
-    .version('0.1.0')
-    .option('-c, --config <dir>', 'Config directory path', '.ai-sdlc')
-    .option('-f, --format <type>', 'Output format: table, json, minimal', 'table')
-    .option('-v, --verbose', 'Enable verbose output');
-program.addCommand(initCommand);
-program.addCommand(runCommand);
-program.addCommand(startCommand);
-program.addCommand(statusCommand);
-program.addCommand(healthCommand);
-program.addCommand(agentsCommand);
-program.addCommand(routingCommand);
-program.addCommand(complexityCommand);
-program.addCommand(costCommand);
-program.addCommand(dashboardCommand);
-program.addCommand(validateCommand);
-program.parse();
+import { resolveVersions, formatVersionBlock, upgradeHint, } from './versions.js';
+/**
+ * Build the Commander program. Exported so integration tests can drive
+ * the real argv pipeline (`--version`, unknown-subcommand) without
+ * invoking the bundled binary on disk. The bin shim below calls this
+ * exact factory at startup.
+ */
+export function buildProgram(versions) {
+    const program = new Command();
+    program
+        .name('ai-sdlc')
+        .description('AI-SDLC Orchestrator — drive issues through the SDLC with AI agents')
+        // Anchor commander's --version to the real package version so a user
+        // who just ran `npm i -g @ai-sdlc/orchestrator` sees the version they
+        // installed, not the literal that was hardcoded years ago.
+        .version(versions.cli, '-V, --version', 'Print the CLI version')
+        .option('-c, --config <dir>', 'Config directory path', '.ai-sdlc')
+        .option('-f, --format <type>', 'Output format: table, json, minimal', 'table')
+        .option('-v, --verbose', 'Enable verbose output');
+    // Override commander's default --version handler so we can emit the full
+    // 3-line block (CLI + orchestrator + plugin) instead of just the literal.
+    //
+    // IMPORTANT: commander 12's `.version()` registers its own
+    // `option:version` listener (in registration order) that writes the
+    // bare version string and calls `_exit`. Plain `.on()` would queue
+    // *after* commander's listener, so our 3-line block would never
+    // print. `prependListener` puts ours first; calling commander's own
+    // `_exit` here prevents the default listener from ever firing while
+    // still going through `exitOverride()` so tests can intercept.
+    // commander's Command extends EventEmitter; the .d.ts only re-exports
+    // .on/.once, so we reach for prependListener via the EventEmitter cast.
+    program.prependListener('option:version', () => {
+        const writeOut = program.configureOutput().writeOut ?? ((s) => process.stdout.write(s));
+        writeOut(`${formatVersionBlock(versions)}\n`);
+        program._exit(0, 'commander.version', versions.cli);
+    });
+    program.addCommand(initCommand);
+    program.addCommand(runCommand);
+    program.addCommand(startCommand);
+    program.addCommand(statusCommand);
+    program.addCommand(healthCommand);
+    program.addCommand(agentsCommand);
+    program.addCommand(routingCommand);
+    program.addCommand(complexityCommand);
+    program.addCommand(costCommand);
+    program.addCommand(dashboardCommand);
+    program.addCommand(validateCommand);
+    // Unknown-subcommand handler (AC #9): hint at version drift / upgrade so
+    // users who installed an outdated CLI find out fast.
+    program.on('command:*', (operands) => {
+        const unknown = operands[0] ?? '';
+        const writeErr = program.configureOutput().writeErr ?? ((s) => process.stderr.write(s));
+        writeErr(`Unknown subcommand: ${unknown}\n`);
+        writeErr('\n');
+        writeErr(`${upgradeHint(versions)}\n`);
+        writeErr('\n');
+        writeErr('Run `ai-sdlc --help` to see the available subcommands.\n');
+        program._exit(1, 'commander.unknownCommand', unknown);
+    });
+    return program;
+}
+// Bin entry: only run argv parsing when invoked as a script, not when the
+// module is imported by tests.
+//
+// `process.argv[1]` is the path Node resolved for the entry script.
+// When it ends with the compiled CLI bundle (`dist/cli/index.js`) we are
+// the main entry. When imported (e.g. via Vitest) argv[1] points at the
+// test runner, so we skip parsing.
+const isMainEntry = (() => {
+    const entry = process.argv[1] ?? '';
+    return entry.endsWith('cli/index.js') || entry.endsWith('cli/index.ts');
+})();
+if (isMainEntry) {
+    const program = buildProgram(resolveVersions());
+    program.parse();
+}
 //# sourceMappingURL=index.js.map

package/dist/cli/versions.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Version provenance — surface the running CLI, orchestrator runtime,
+ * and (optionally) plugin versions in one place so users can spot drift.
+ *
+ * Why this exists: the original CLI hardcoded `0.1.0` in commander while
+ * the published `@ai-sdlc/orchestrator` package was at 0.6.0+. Operators
+ * who ran `ai-sdlc --version` saw the stale literal and assumed the
+ * orchestrator itself was that old. AISDLC-78 anchors `--version` to
+ * the package.json that ships with the binary and warns when components
+ * disagree.
+ */
+export interface VersionTriple {
+    /** The CLI binary's reported version. Tracks the orchestrator package. */
+    cli: string;
+    /** The orchestrator runtime version (from @ai-sdlc/orchestrator/package.json). */
+    orchestrator: string;
+    /** The plugin version, if discoverable in the workspace. */
+    plugin?: string;
+    /** Whether any of the discoverable components disagree on version. */
+    drift: boolean;
+}
+export interface ResolveVersionsOptions {
+    /** Override the working directory used to discover the plugin. */
+    workDir?: string;
+    /** Inject an orchestrator package.json path (testing). */
+    orchestratorPackageJsonPath?: string;
+    /** Inject a plugin version (testing). */
+    pluginVersionOverride?: string;
+}
+/**
+ * Compute the active CLI/orchestrator/plugin versions.
+ *
+ * Drift detection: when at least two known components disagree on
+ * version string (case-insensitive), `drift` is set. The plugin is
+ * compared only when discovered.
+ */
+export declare function resolveVersions(opts?: ResolveVersionsOptions): VersionTriple;
+/**
+ * Render the canonical 3-line version block. Always emits a
+ * trailing newline. When drift is detected, appends a warning line
+ * pointing at the upgrade hint.
+ *
+ * The CLI and orchestrator rows are rendered separately even though
+ * today they always show the same number — both ship from the same
+ * `@ai-sdlc/orchestrator` package.json. The shape is intentionally
+ * future-proofed: when the CLI is split into a thinner veneer with
+ * its own version it will start to differ from the orchestrator
+ * runtime, and operators are then trained to read both rows. Until
+ * then a duplicate value is the honest answer.
+ */
+export declare function formatVersionBlock(versions: VersionTriple): string;
+/**
+ * Return the upgrade hint shown by unknown-subcommand handler and by
+ * version drift warnings. Centralised so tests can assert one string.
+ */
+export declare function upgradeHint(versions: VersionTriple): string;
+//# sourceMappingURL=versions.d.ts.map

package/dist/cli/versions.js

@@ -0,0 +1,128 @@
+/**
+ * Version provenance — surface the running CLI, orchestrator runtime,
+ * and (optionally) plugin versions in one place so users can spot drift.
+ *
+ * Why this exists: the original CLI hardcoded `0.1.0` in commander while
+ * the published `@ai-sdlc/orchestrator` package was at 0.6.0+. Operators
+ * who ran `ai-sdlc --version` saw the stale literal and assumed the
+ * orchestrator itself was that old. AISDLC-78 anchors `--version` to
+ * the package.json that ships with the binary and warns when components
+ * disagree.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const FALLBACK_VERSION = '0.0.0';
+function readPackageVersion(pkgPath) {
+    try {
+        if (!existsSync(pkgPath))
+            return undefined;
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the orchestrator package's own package.json. The CLI bundle
+ * lives at `dist/cli/index.js` so we walk up two levels.
+ */
+function findOrchestratorPackageJson() {
+    // import.meta.url points at the compiled CLI module location.
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Try ../package.json (when running from dist/cli/) and ../../package.json
+    // (when running from src/cli/ in tests via tsx).
+    const candidates = [
+        resolve(here, '..', 'package.json'),
+        resolve(here, '..', '..', 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+                if (pkg.name === '@ai-sdlc/orchestrator')
+                    return candidate;
+            }
+            catch {
+                // continue
+            }
+        }
+    }
+    return candidates[0];
+}
+/**
+ * Best-effort search for the plugin manifest. We look in the project
+ * working directory first (the common case for a co-located checkout),
+ * then a few well-known parent paths. Returns undefined silently when
+ * not found — the plugin is optional metadata.
+ */
+function findPluginVersion(workDir) {
+    const tries = [
+        join(workDir, 'ai-sdlc-plugin', 'plugin.json'),
+        join(workDir, '..', 'ai-sdlc-plugin', 'plugin.json'),
+        join(workDir, '..', '..', 'ai-sdlc-plugin', 'plugin.json'),
+    ];
+    for (const t of tries) {
+        const v = readPackageVersion(t);
+        if (v)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Compute the active CLI/orchestrator/plugin versions.
+ *
+ * Drift detection: when at least two known components disagree on
+ * version string (case-insensitive), `drift` is set. The plugin is
+ * compared only when discovered.
+ */
+export function resolveVersions(opts = {}) {
+    const orchPath = opts.orchestratorPackageJsonPath ?? findOrchestratorPackageJson();
+    const orchestrator = readPackageVersion(orchPath) ?? FALLBACK_VERSION;
+    // The CLI ships from the same package.json today, so cli === orchestrator
+    // by construction. Drift detection between cli/orchestrator is therefore
+    // a no-op until the CLI is split out (planned: a thinner veneer that
+    // versions independently of the runtime). We keep them logically
+    // separate so callers and tests don't have to change shape on that day.
+    const cli = orchestrator;
+    const plugin = opts.pluginVersionOverride ?? findPluginVersion(opts.workDir ?? process.cwd());
+    const observed = [cli, orchestrator, plugin].filter((v) => Boolean(v));
+    const drift = new Set(observed.map((v) => v.toLowerCase())).size > 1;
+    return { cli, orchestrator, plugin, drift };
+}
+/**
+ * Render the canonical 3-line version block. Always emits a
+ * trailing newline. When drift is detected, appends a warning line
+ * pointing at the upgrade hint.
+ *
+ * The CLI and orchestrator rows are rendered separately even though
+ * today they always show the same number — both ship from the same
+ * `@ai-sdlc/orchestrator` package.json. The shape is intentionally
+ * future-proofed: when the CLI is split into a thinner veneer with
+ * its own version it will start to differ from the orchestrator
+ * runtime, and operators are then trained to read both rows. Until
+ * then a duplicate value is the honest answer.
+ */
+export function formatVersionBlock(versions) {
+    const lines = [
+        `ai-sdlc CLI:       ${versions.cli}`,
+        `orchestrator:      ${versions.orchestrator}`,
+        `plugin:            ${versions.plugin ?? '(not detected)'}`,
+    ];
+    if (versions.drift) {
+        lines.push('', 'WARN  versions out of sync — components disagree.', '      Run `npm install -g @ai-sdlc/orchestrator@latest` (or pnpm equivalent) to align.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Return the upgrade hint shown by unknown-subcommand handler and by
+ * version drift warnings. Centralised so tests can assert one string.
+ */
+export function upgradeHint(versions) {
+    if (versions.drift) {
+        return `Detected version drift (cli=${versions.cli}, orchestrator=${versions.orchestrator}${versions.plugin ? `, plugin=${versions.plugin}` : ''}). Run \`npm install -g @ai-sdlc/orchestrator@latest\` to align.`;
+    }
+    return `Run \`ai-sdlc --version\` to confirm you are on the latest @ai-sdlc/orchestrator (currently ${versions.orchestrator}).`;
+}
+//# sourceMappingURL=versions.js.map

package/dist/code-area-classifier.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Classify a code area as frontend-bearing or not (RFC-0008 C3).
+ *
+ * `hasFrontendComponents` is the branch predicate in the §A.5 defect-risk
+ * blend: frontend-bearing areas blend code-quality signals with design-
+ * quality signals; pure-code areas use only code signals.
+ *
+ * Classification order:
+ *   1. If the state store has a recent `code_area_metrics` row for the
+ *      area, trust that explicitly — operators can correct the default
+ *      by writing the metric.
+ *   2. Otherwise, apply a path-string heuristic: common frontend
+ *      directory/extension markers.
+ *
+ * The state-store path matters because this runs in the hot admission
+ * loop — we don't want to ship a filesystem crawl on every issue score.
+ */
+import type { StateStore } from './state/store.js';
+export declare function checkHasFrontendComponents(codeArea: string, store?: StateStore): boolean;
+export declare function matchesFrontendHeuristic(codeArea: string): boolean;
+//# sourceMappingURL=code-area-classifier.d.ts.map

package/dist/code-area-classifier.js

@@ -0,0 +1,48 @@
+/**
+ * Classify a code area as frontend-bearing or not (RFC-0008 C3).
+ *
+ * `hasFrontendComponents` is the branch predicate in the §A.5 defect-risk
+ * blend: frontend-bearing areas blend code-quality signals with design-
+ * quality signals; pure-code areas use only code signals.
+ *
+ * Classification order:
+ *   1. If the state store has a recent `code_area_metrics` row for the
+ *      area, trust that explicitly — operators can correct the default
+ *      by writing the metric.
+ *   2. Otherwise, apply a path-string heuristic: common frontend
+ *      directory/extension markers.
+ *
+ * The state-store path matters because this runs in the hot admission
+ * loop — we don't want to ship a filesystem crawl on every issue score.
+ */
+const FRONTEND_PATH_MARKERS = [
+    'components/',
+    'ui/',
+    'frontend/',
+    'web/',
+    'webapp/',
+    'src/app/', // Next.js app-dir convention
+    'pages/',
+    'routes/',
+    'views/',
+];
+const FRONTEND_EXTENSIONS = ['.tsx', '.jsx', '.vue', '.svelte', '.astro'];
+export function checkHasFrontendComponents(codeArea, store) {
+    const authoritative = store?.getCodeAreaMetrics(codeArea);
+    if (authoritative)
+        return authoritative.hasFrontendComponents ?? false;
+    return matchesFrontendHeuristic(codeArea);
+}
+export function matchesFrontendHeuristic(codeArea) {
+    const lower = codeArea.toLowerCase();
+    for (const marker of FRONTEND_PATH_MARKERS) {
+        if (lower.includes(marker))
+            return true;
+    }
+    for (const ext of FRONTEND_EXTENSIONS) {
+        if (lower.endsWith(ext))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=code-area-classifier.js.map

package/dist/config.d.ts

@@ -5,9 +5,17 @@
  * Unlike the dogfood config loader, this version does NOT import builder
  * functions — it performs pure YAML loading and validation only.
  */
-import { type Pipeline, type AgentRole, type QualityGate, type AutonomyPolicy, type AdapterBinding, type AdapterRegistry } from '@ai-sdlc/reference';
+import { type Pipeline, type AgentRole, type QualityGate, type AutonomyPolicy, type AdapterBinding, type DesignSystemBinding, type DesignIntentDocument, type AdapterRegistry } from '@ai-sdlc/reference';
 export interface AiSdlcConfig {
+    /** Default pipeline (first Pipeline resource loaded; preserved for backward compat). */
     pipeline?: Pipeline;
+    /**
+     * All Pipeline resources found in the config directory. The dual-workflow setup
+     * (RFC-0010 §11): one pipeline for the public GitHub-issue path (API-key billed),
+     * another for the internal backlog path (subscription-billed). cli-watch picks
+     * by name based on the issue ID prefix.
+     */
+    pipelines?: Pipeline[];
     agentRole?: AgentRole;
     qualityGate?: QualityGate;
     autonomyPolicy?: AutonomyPolicy;
@@ -15,13 +23,37 @@ export interface AiSdlcConfig {
     adapterBinding?: AdapterBinding;
     /** All AdapterBinding resources found in the config directory. */
     adapterBindings?: AdapterBinding[];
+    /** All DesignSystemBinding resources found in the config directory (RFC-0006). */
+    designSystemBindings?: DesignSystemBinding[];
+    /** All DesignIntentDocument resources found in the config directory (RFC-0008). */
+    designIntentDocuments?: DesignIntentDocument[];
     adapterRegistry?: AdapterRegistry;
+    /**
+     * Per-file load issues collected during a non-fatal load. Each entry
+     * is `{ file, error }` for a YAML file that failed to parse or
+     * validate. Non-resource YAMLs (no `apiVersion`/`kind`) and DID→DSB
+     * cross-reference failures are NOT recorded here — the former are
+     * silently skipped, the latter throw outright.
+     */
+    warnings?: ConfigLoadWarning[];
+}
+export interface ConfigLoadWarning {
+    file: string;
+    error: string;
 }
 /**
  * Load all YAML files from the given directory, validate each against
  * the AI-SDLC JSON Schema, and return typed resources keyed by kind.
  */
 export declare function loadConfig(configDir: string): AiSdlcConfig;
+/**
+ * Validate that every DesignIntentDocument's `spec.designSystemRef.name`
+ * resolves to a loaded DesignSystemBinding. Namespace match is required
+ * only when both resources declare a namespace (RFC-0008 §4.5).
+ *
+ * Unidirectional: DID → DSB. DesignSystemBinding surface is not modified.
+ */
+export declare function validateDesignIntentDocumentReferences(config: AiSdlcConfig): void;
 /**
  * Async variant of loadConfig that also scans for local adapter plugins.
  */

package/dist/config.js

@@ -9,9 +9,8 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { validateResource, createAdapterRegistry, scanLocalAdapters, } from '@ai-sdlc/reference';
-/** Resource kinds that allow only a single instance. */
+/** Resource kinds that allow only a single instance. Multi-instance kinds are excluded. */
 const KIND_KEY = {
-    Pipeline: 'pipeline',
     AgentRole: 'agentRole',
     QualityGate: 'qualityGate',
     AutonomyPolicy: 'autonomyPolicy',
@@ -27,21 +26,54 @@ export function loadConfig(configDir) {
     }
     const files = readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
     const config = {};
+    const warnings = [];
     for (const file of files) {
-        // Skip non-resource YAML files (e.g. manifest.yaml)
-        if (file === 'manifest.yaml')
+        let doc;
+        try {
+            const raw = readFileSync(resolve(dir, file), 'utf-8');
+            doc = parseYaml(raw);
+        }
+        catch (err) {
+            // Malformed YAML — record and continue. One bad file should not
+            // poison the rest of the config (forward-looking YAMLs in active
+            // adoption are common).
+            warnings.push({ file, error: `parse error: ${err.message}` });
+            continue;
+        }
+        // Skip non-resource YAML files (review-exemplars.yaml, manifest.yaml, etc.)
+        // AI-SDLC resources always have an apiVersion field.
+        if (!doc || typeof doc !== 'object' || !('apiVersion' in doc) || !('kind' in doc)) {
             continue;
-        const raw = readFileSync(resolve(dir, file), 'utf-8');
-        const doc = parseYaml(raw);
+        }
         const result = validateResource(doc);
         if (!result.valid) {
-            const msgs = (result.errors ?? []).map((e) => `  ${e.path}: ${e.message}`).join('\n');
-            throw new Error(`Validation failed for ${file}:\n${msgs}`);
+            const msgs = (result.errors ?? []).map((e) => `${e.path}: ${e.message}`).join('; ');
+            // Forward-looking schemas are common during incremental adoption
+            // (RFC-0008 §A.4 readers landing in phases). Record + skip rather
+            // than throw — callers see the warning, the rest of the config
+            // (the parts that DO validate) continues to drive admission.
+            warnings.push({ file, error: `validation failed: ${msgs}` });
+            continue;
         }
         const resource = result.data;
         if (resource.kind === 'AdapterBinding') {
             (config.adapterBindings ??= []).push(resource);
         }
+        else if (resource.kind === 'DesignSystemBinding') {
+            (config.designSystemBindings ??= []).push(resource);
+        }
+        else if (resource.kind === 'DesignIntentDocument') {
+            (config.designIntentDocuments ??= []).push(resource);
+        }
+        else if (resource.kind === 'Pipeline') {
+            (config.pipelines ??= []).push(resource);
+            // Backward-compat: `config.pipeline` (singular) = the canonical one.
+            // Prefer the file literally named `pipeline.yaml` (the default workflow).
+            // Fall back to the first loaded otherwise.
+            if (file === 'pipeline.yaml' || file === 'pipeline.yml' || !config.pipeline) {
+                config.pipeline = resource;
+            }
+        }
         else {
             const key = KIND_KEY[resource.kind];
             if (key) {
@@ -50,12 +82,50 @@ export function loadConfig(configDir) {
             }
         }
     }
+    if (warnings.length > 0) {
+        config.warnings = warnings;
+    }
     // Backward compat: set adapterBinding to the first binding
     if (config.adapterBindings?.length) {
         config.adapterBinding = config.adapterBindings[0];
     }
+    // RFC-0008: validate DID → DSB cross-references
+    if (config.designIntentDocuments?.length) {
+        validateDesignIntentDocumentReferences(config);
+    }
     return config;
 }
+/**
+ * Validate that every DesignIntentDocument's `spec.designSystemRef.name`
+ * resolves to a loaded DesignSystemBinding. Namespace match is required
+ * only when both resources declare a namespace (RFC-0008 §4.5).
+ *
+ * Unidirectional: DID → DSB. DesignSystemBinding surface is not modified.
+ */
+export function validateDesignIntentDocumentReferences(config) {
+    const dids = config.designIntentDocuments ?? [];
+    const dsbs = config.designSystemBindings ?? [];
+    const unresolved = [];
+    for (const did of dids) {
+        const targetName = did.spec.designSystemRef.name;
+        const targetNamespace = did.spec.designSystemRef.namespace;
+        const match = dsbs.find((dsb) => {
+            if (dsb.metadata.name !== targetName)
+                return false;
+            if (targetNamespace && dsb.metadata.namespace && dsb.metadata.namespace !== targetNamespace) {
+                return false;
+            }
+            return true;
+        });
+        if (!match) {
+            const nsSuffix = targetNamespace ? `/${targetNamespace}` : '';
+            unresolved.push(`  DesignIntentDocument "${did.metadata.name}" references "${targetName}${nsSuffix}" which does not resolve to any loaded DesignSystemBinding`);
+        }
+    }
+    if (unresolved.length > 0) {
+        throw new Error(`DID → DesignSystemBinding reference validation failed:\n${unresolved.join('\n')}`);
+    }
+}
 /**
  * Async variant of loadConfig that also scans for local adapter plugins.
  */

package/dist/database/adapters/external.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ExternalAdapter per RFC §15.2. Operator-declared shell hooks for proprietary or
+ * custom branching mechanisms. Pipeline-load REQUIRES `acknowledgeUntrusted: true`
+ * because shell hooks execute with full credential scope.
+ */
+import { type DatabaseBranchAdapter, type DatabaseBranchCapabilities, type DatabaseBranchHandle, type DatabaseAdapterName, type ResolvedDatabaseBranchPool, type ValidationResult } from '../types.js';
+export interface ExternalAdapterDeps {
+    exec?: (cmd: string, args: string[]) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare class ExternalAdapter implements DatabaseBranchAdapter {
+    private readonly deps;
+    readonly name: DatabaseAdapterName;
+    readonly capabilities: DatabaseBranchCapabilities;
+    constructor(deps?: ExternalAdapterDeps);
+    validate(pool: ResolvedDatabaseBranchPool): Promise<ValidationResult>;
+    allocate(pool: ResolvedDatabaseBranchPool, branchKey: string): Promise<DatabaseBranchHandle>;
+    reclaim(handle: DatabaseBranchHandle): Promise<void>;
+    list(_pool: ResolvedDatabaseBranchPool): Promise<DatabaseBranchHandle[]>;
+    isAvailable(pool: ResolvedDatabaseBranchPool): Promise<boolean>;
+}
+//# sourceMappingURL=external.d.ts.map