@ai-sdlc/orchestrator 0.6.0 → 0.9.0

package/dist/database/connection-injection.js

@@ -0,0 +1,93 @@
+/**
+ * Connection-string injection per RFC §15.6. The agent sees the per-worktree branch
+ * via the same env-var name (`DATABASE_URL` etc.) the application expects. Adapters
+ * provide the rewritten string; this module derives optional component env vars
+ * (PGHOST, PGDATABASE, etc.) from it.
+ */
+/**
+ * Build the env-var overlay for a single (handle, pool) pair. The agent's process
+ * env is the orchestrator's env merged with this overlay.
+ *
+ * Component derivation supports postgres:// connection strings — for non-Postgres
+ * URLs (e.g., sqlite file paths), additionalEnvs is silently ignored.
+ */
+export function buildInjectionOverrides(handle, pool) {
+    const overrides = {};
+    overrides[pool.injection.targetEnv] = handle.connectionString;
+    if (pool.injection.additionalEnvs && pool.injection.additionalEnvs.length > 0) {
+        const components = parsePostgresUrl(handle.connectionString);
+        if (components) {
+            for (const envName of pool.injection.additionalEnvs) {
+                const mapped = mapEnvNameToComponent(envName, components);
+                if (mapped !== null)
+                    overrides[envName] = mapped;
+            }
+        }
+    }
+    return overrides;
+}
+export function parsePostgresUrl(url) {
+    // postgres://[user[:password]@]host[:port][/database][?...]
+    // Also handles postgresql:// scheme.
+    try {
+        const parsed = new URL(url);
+        if (!/^postgres(?:ql)?:$/.test(parsed.protocol))
+            return null;
+        return {
+            host: parsed.hostname,
+            port: parsed.port || '5432',
+            database: parsed.pathname.replace(/^\//, ''),
+            user: decodeURIComponent(parsed.username),
+            password: decodeURIComponent(parsed.password),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function mapEnvNameToComponent(name, c) {
+    const upper = name.toUpperCase();
+    switch (upper) {
+        case 'PGHOST':
+        case 'POSTGRES_HOST':
+        case 'DB_HOST':
+            return c.host;
+        case 'PGPORT':
+        case 'POSTGRES_PORT':
+        case 'DB_PORT':
+            return c.port;
+        case 'PGDATABASE':
+        case 'POSTGRES_DB':
+        case 'DB_NAME':
+            return c.database;
+        case 'PGUSER':
+        case 'POSTGRES_USER':
+        case 'DB_USER':
+            return c.user;
+        case 'PGPASSWORD':
+        case 'POSTGRES_PASSWORD':
+        case 'DB_PASSWORD':
+            return c.password;
+        default:
+            return null;
+    }
+}
+/**
+ * Mask a connection string for safe logging. Replaces the password segment with
+ * `****`. Per RFC §15.1 the connection string itself MUST NEVER appear in any
+ * observability output — this helper exists for adapter error messages where
+ * the URL form might leak.
+ */
+export function maskConnectionString(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.password) {
+            parsed.password = '****';
+        }
+        return parsed.toString();
+    }
+    catch {
+        return '<unparseable connection string>';
+    }
+}
+//# sourceMappingURL=connection-injection.js.map

package/dist/database/index.d.ts

@@ -0,0 +1,12 @@
+export * from './types.js';
+export { DatabaseAdapterRegistry, UnknownDatabaseAdapterError } from './registry.js';
+export { buildInjectionOverrides, parsePostgresUrl, maskConnectionString, type InjectedEnvOverrides, } from './connection-injection.js';
+export { enforceTopologyGuard, buildMigrationDivergedEvent, type KnownInFlightBranches, type MigrationDivergedEvent, } from './topology.js';
+export { SqliteCopyAdapter, type SqliteCopyAdapterDeps } from './adapters/sqlite-copy.js';
+export { NeonAdapter, type NeonAdapterDeps } from './adapters/neon.js';
+export { PgSnapshotRestoreAdapter, type PgSnapshotRestoreAdapterDeps, } from './adapters/pg-snapshot-restore.js';
+export { ExternalAdapter, type ExternalAdapterDeps } from './adapters/external.js';
+import { DatabaseAdapterRegistry } from './registry.js';
+/** Pre-populated registry with the four shipped v1 adapters. */
+export declare function createDefaultDatabaseAdapterRegistry(): DatabaseAdapterRegistry;
+//# sourceMappingURL=index.d.ts.map

package/dist/database/index.js

@@ -0,0 +1,23 @@
+export * from './types.js';
+export { DatabaseAdapterRegistry, UnknownDatabaseAdapterError } from './registry.js';
+export { buildInjectionOverrides, parsePostgresUrl, maskConnectionString, } from './connection-injection.js';
+export { enforceTopologyGuard, buildMigrationDivergedEvent, } from './topology.js';
+export { SqliteCopyAdapter } from './adapters/sqlite-copy.js';
+export { NeonAdapter } from './adapters/neon.js';
+export { PgSnapshotRestoreAdapter, } from './adapters/pg-snapshot-restore.js';
+export { ExternalAdapter } from './adapters/external.js';
+import { DatabaseAdapterRegistry } from './registry.js';
+import { SqliteCopyAdapter } from './adapters/sqlite-copy.js';
+import { NeonAdapter } from './adapters/neon.js';
+import { PgSnapshotRestoreAdapter } from './adapters/pg-snapshot-restore.js';
+import { ExternalAdapter } from './adapters/external.js';
+/** Pre-populated registry with the four shipped v1 adapters. */
+export function createDefaultDatabaseAdapterRegistry() {
+    const reg = new DatabaseAdapterRegistry();
+    reg.register(new SqliteCopyAdapter());
+    reg.register(new NeonAdapter());
+    reg.register(new PgSnapshotRestoreAdapter());
+    reg.register(new ExternalAdapter());
+    return reg;
+}
+//# sourceMappingURL=index.js.map

package/dist/database/registry.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseAdapterName, DatabaseBranchAdapter } from './types.js';
+export declare class UnknownDatabaseAdapterError extends Error {
+    readonly name: string;
+    constructor(name: string);
+}
+export declare class DatabaseAdapterRegistry {
+    private readonly adapters;
+    register(adapter: DatabaseBranchAdapter): void;
+    get(name: string): DatabaseBranchAdapter;
+    has(name: string): boolean;
+    list(): DatabaseAdapterName[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/database/registry.js

@@ -0,0 +1,27 @@
+export class UnknownDatabaseAdapterError extends Error {
+    name;
+    constructor(name) {
+        super(`Unknown DatabaseBranchAdapter: ${name}`);
+        this.name = name;
+        this.name = 'UnknownDatabaseAdapterError';
+    }
+}
+export class DatabaseAdapterRegistry {
+    adapters = new Map();
+    register(adapter) {
+        this.adapters.set(adapter.name, adapter);
+    }
+    get(name) {
+        const a = this.adapters.get(name);
+        if (!a)
+            throw new UnknownDatabaseAdapterError(name);
+        return a;
+    }
+    has(name) {
+        return this.adapters.has(name);
+    }
+    list() {
+        return Array.from(this.adapters.keys());
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/database/topology.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Branch topology guard per RFC §15.5.1 (Q15 resolution). Defaults `allowBranchFromBranch`
+ * to false, refusing to allocate a branch whose upstream is itself an in-flight feature
+ * branch. Eliminates MigrationDiverged for ~95% of pipelines that don't need stacked PRs.
+ */
+import { type ResolvedDatabaseBranchPool } from './types.js';
+export interface KnownInFlightBranches {
+    /** Branch names currently allocated as DatabaseBranch handles in this pool. */
+    inFlightBranchNames: Set<string>;
+    /** Stable upstream branch names the operator considers safe to branch from. */
+    stableUpstreams: Set<string>;
+}
+/**
+ * Validate a branchFrom request against the topology guard. Throws
+ * BranchTopologyForbiddenError if the upstream is an in-flight branch and
+ * `allowBranchFromBranch` is false.
+ */
+export declare function enforceTopologyGuard(pool: ResolvedDatabaseBranchPool, state: KnownInFlightBranches): void;
+/**
+ * MigrationDiverged event payload per RFC §15.5.1. Emitted by the orchestrator when a
+ * branch with active children is reclaimed (parent PR abandoned).
+ */
+export interface MigrationDivergedEvent {
+    type: 'MigrationDiverged';
+    reclaimedBranch: {
+        branchKey: string;
+        reason: 'pr-abandoned' | 'manual-reclaim' | 'ttl-expired';
+        issueId?: string;
+    };
+    divergentChildren: Array<{
+        branchKey: string;
+        issueId?: string;
+        lastActivity: string;
+    }>;
+    interpretation: string;
+    recommendation: string;
+}
+/**
+ * Build a MigrationDiverged event from the parent reclaim + a snapshot of children.
+ * The orchestrator emits this through its event stream; the operator triages per
+ * the runbook. NO auto-action.
+ */
+export declare function buildMigrationDivergedEvent(parent: {
+    branchKey: string;
+    reason: 'pr-abandoned' | 'manual-reclaim' | 'ttl-expired';
+    issueId?: string;
+}, children: Array<{
+    branchKey: string;
+    issueId?: string;
+    lastActivity: Date;
+}>): MigrationDivergedEvent;
+//# sourceMappingURL=topology.d.ts.map

package/dist/database/topology.js

@@ -0,0 +1,44 @@
+/**
+ * Branch topology guard per RFC §15.5.1 (Q15 resolution). Defaults `allowBranchFromBranch`
+ * to false, refusing to allocate a branch whose upstream is itself an in-flight feature
+ * branch. Eliminates MigrationDiverged for ~95% of pipelines that don't need stacked PRs.
+ */
+import { BranchTopologyForbiddenError } from './types.js';
+/**
+ * Validate a branchFrom request against the topology guard. Throws
+ * BranchTopologyForbiddenError if the upstream is an in-flight branch and
+ * `allowBranchFromBranch` is false.
+ */
+export function enforceTopologyGuard(pool, state) {
+    const branchFrom = pool.upstream.branchFrom;
+    if (!branchFrom)
+        return;
+    // Always allowed when the upstream is a declared stable branch.
+    if (state.stableUpstreams.has(branchFrom))
+        return;
+    if (state.inFlightBranchNames.has(branchFrom)) {
+        if (pool.allowBranchFromBranch !== true) {
+            throw new BranchTopologyForbiddenError(`DatabaseBranchPool '${pool.name}' attempted to branch from in-flight branch '${branchFrom}'; ` +
+                `set allowBranchFromBranch: true to opt in to chained branching (and accept MigrationDiverged risk).`, pool.name);
+        }
+    }
+}
+/**
+ * Build a MigrationDiverged event from the parent reclaim + a snapshot of children.
+ * The orchestrator emits this through its event stream; the operator triages per
+ * the runbook. NO auto-action.
+ */
+export function buildMigrationDivergedEvent(parent, children) {
+    return {
+        type: 'MigrationDiverged',
+        reclaimedBranch: parent,
+        divergentChildren: children.map((c) => ({
+            branchKey: c.branchKey,
+            issueId: c.issueId,
+            lastActivity: c.lastActivity.toISOString(),
+        })),
+        interpretation: 'child branches inherit a migration that no longer exists in any merged code. Their PRs may pass tests but break on merge to main.',
+        recommendation: 'operator triage: rebase children onto current upstream, accept divergence, or reclaim children. The orchestrator does NOT auto-rebase or auto-reclaim.',
+    };
+}
+//# sourceMappingURL=topology.js.map

package/dist/database/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * DatabaseBranchAdapter framework per RFC-0010 §15. Each adapter abstracts a database
+ * branching mechanism; the orchestrator allocates a branch per worktree, injects the
+ * branch's connection string into the agent's environment, and reclaims on PR merge.
+ */
+export type DatabaseAdapterName = 'sqlite-copy' | 'neon' | 'pg-snapshot-restore' | 'supabase' | 'external';
+export interface DatabaseBranchCapabilities {
+    branchCreationLatencyP50Ms: number;
+    maxBranches: number;
+    supportsMigrations: boolean;
+    supportsReadOnlyBranches: boolean;
+    supportsBranchFromBranch: boolean;
+    multiDatabase: boolean;
+    costModel: 'per-branch-storage' | 'per-snapshot' | 'free';
+}
+export interface DatabaseBranchHandle {
+    /** Stable key derived from the worktree branch name. */
+    branchKey: string;
+    /**
+     * Connection URL the agent will use. NEVER logged in cleartext per RFC §15.1
+     * (security review property — adapters MUST mask credentials in any error returned).
+     */
+    connectionString: string;
+    createdAt: Date;
+    /** Upstream branch the handle was derived from. */
+    upstream: string;
+    upstreamCommitId?: string;
+    /** Adapter-specific metadata (Neon: branch_id; pg-snapshot-restore: snapshot id). */
+    metadata: Record<string, string>;
+}
+export interface ResolvedDatabaseBranchPool {
+    name: string;
+    adapter: DatabaseAdapterName;
+    upstream: {
+        connectionStringEnv: string;
+        branchFrom?: string;
+    };
+    injection: {
+        targetEnv: string;
+        additionalEnvs?: string[];
+    };
+    lifecycle?: {
+        createOn?: 'worktree-allocation' | 'first-write-stage';
+        reclaimOn?: 'pr-merge' | 'worktree-reclaim' | 'manual';
+        maxConcurrent?: number;
+        branchTtl?: string;
+        abandonAfter?: string;
+        warmPoolSize?: number;
+    };
+    allowBranchFromBranch?: boolean;
+    migrations?: {
+        runOnBranchCreate?: boolean;
+        migrationCommand?: string;
+        migrationCwd?: string;
+    };
+    credentials?: Record<string, unknown>;
+}
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DatabaseBranchAdapter {
+    readonly name: DatabaseAdapterName;
+    readonly capabilities: DatabaseBranchCapabilities;
+    /** Pipeline-load validation; checks credentials + adapter-specific config. */
+    validate(pool: ResolvedDatabaseBranchPool): Promise<ValidationResult>;
+    /** Provision a new branch from the pool's upstream. */
+    allocate(pool: ResolvedDatabaseBranchPool, branchKey: string): Promise<DatabaseBranchHandle>;
+    /** Destroy a branch and free its quota slot. */
+    reclaim(handle: DatabaseBranchHandle): Promise<void>;
+    /** Enumerate currently active branches (for stale-branch sweep on startup). */
+    list(pool: ResolvedDatabaseBranchPool): Promise<DatabaseBranchHandle[]>;
+    /** Cheap liveness probe. */
+    isAvailable(pool: ResolvedDatabaseBranchPool): Promise<boolean>;
+}
+export declare class DatabaseBranchAdapterError extends Error {
+    readonly adapter: DatabaseAdapterName;
+    readonly branchKey?: string | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, adapter: DatabaseAdapterName, branchKey?: string | undefined, cause?: unknown | undefined);
+}
+export declare class BranchTopologyForbiddenError extends Error {
+    readonly poolName: string;
+    constructor(message: string, poolName: string);
+}
+export type DatabaseAccess = 'none' | 'read' | 'write' | 'migrate';
+//# sourceMappingURL=types.d.ts.map

package/dist/database/types.js

@@ -0,0 +1,26 @@
+/**
+ * DatabaseBranchAdapter framework per RFC-0010 §15. Each adapter abstracts a database
+ * branching mechanism; the orchestrator allocates a branch per worktree, injects the
+ * branch's connection string into the agent's environment, and reclaims on PR merge.
+ */
+export class DatabaseBranchAdapterError extends Error {
+    adapter;
+    branchKey;
+    cause;
+    constructor(message, adapter, branchKey, cause) {
+        super(message);
+        this.adapter = adapter;
+        this.branchKey = branchKey;
+        this.cause = cause;
+        this.name = 'DatabaseBranchAdapterError';
+    }
+}
+export class BranchTopologyForbiddenError extends Error {
+    poolName;
+    constructor(message, poolName) {
+        super(message);
+        this.poolName = poolName;
+        this.name = 'BranchTopologyForbiddenError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/design-authority.d.ts

@@ -0,0 +1,40 @@
+/**
+ * C5 — Design authority signal detection (RFC-0008 §A.5).
+ *
+ * Determines whether the issue's author or any commenter is listed as a
+ * `designAuthority` principal on the resolved DesignSystemBinding, and
+ * parses the explicit signal type from issue labels (preferred) or
+ * structured comment markers.
+ */
+import type { DesignSystemBinding } from '@ai-sdlc/reference';
+import type { DesignAuthoritySignalType } from './admission-score.js';
+export interface CheckDesignAuthorityInput {
+    /** GitHub login of the issue author. */
+    authorLogin?: string;
+    /** GitHub logins of anyone who commented on the issue. */
+    commenterLogins?: readonly string[];
+    /** Labels attached to the issue — used to parse the signal type. */
+    labels: readonly string[];
+}
+export interface DesignAuthoritySignalResult {
+    isDesignAuthority: boolean;
+    signalType: DesignAuthoritySignalType;
+}
+/**
+ * Determine whether the issue author or any commenter is a
+ * designAuthority principal, and resolve the signal type from labels.
+ * Returns `{ isDesignAuthority: false, signalType: 'unspecified' }`
+ * when no DSB is present.
+ */
+export declare function checkDesignAuthority(input: CheckDesignAuthorityInput, binding: DesignSystemBinding | undefined): DesignAuthoritySignalResult;
+/**
+ * Resolve the design-signal type from issue labels.
+ *
+ * Priority order mirrors the RFC's weighting (positive signals first),
+ * so an issue tagged with both a positive and a negative label resolves
+ * to the positive one. This is deliberate: design authorities shouldn't
+ * dual-tag in practice, but if they do, we don't want to default to the
+ * punitive path.
+ */
+export declare function parseDesignSignalType(labels: readonly string[]): DesignAuthoritySignalType;
+//# sourceMappingURL=design-authority.d.ts.map

package/dist/design-authority.js

@@ -0,0 +1,71 @@
+/**
+ * C5 — Design authority signal detection (RFC-0008 §A.5).
+ *
+ * Determines whether the issue's author or any commenter is listed as a
+ * `designAuthority` principal on the resolved DesignSystemBinding, and
+ * parses the explicit signal type from issue labels (preferred) or
+ * structured comment markers.
+ */
+/**
+ * Label-encoded design signal types. Short, stable slugs keep GitHub
+ * label names readable; the map below converts them to the
+ * `DesignAuthoritySignalType` used downstream.
+ */
+const LABEL_TO_SIGNAL = Object.freeze({
+    'design/advances-coherence': 'advances-design-coherence',
+    'design/fills-gap': 'fills-catalog-gap',
+    'design/fragments-catalog': 'fragments-component-catalog',
+    'design/misaligned-brand': 'misaligned-with-brand',
+});
+/**
+ * Determine whether the issue author or any commenter is a
+ * designAuthority principal, and resolve the signal type from labels.
+ * Returns `{ isDesignAuthority: false, signalType: 'unspecified' }`
+ * when no DSB is present.
+ */
+export function checkDesignAuthority(input, binding) {
+    const principals = binding?.spec.stewardship.designAuthority.principals ?? [];
+    const authorityParticipants = collectAuthorityParticipants(input, principals);
+    const isDesignAuthority = authorityParticipants.length > 0;
+    const signalType = parseDesignSignalType(input.labels);
+    return { isDesignAuthority, signalType };
+}
+function collectAuthorityParticipants(input, principals) {
+    if (principals.length === 0)
+        return [];
+    const principalSet = new Set(principals.map((p) => p.toLowerCase()));
+    const participants = [];
+    if (input.authorLogin && principalSet.has(input.authorLogin.toLowerCase())) {
+        participants.push(input.authorLogin);
+    }
+    for (const c of input.commenterLogins ?? []) {
+        if (principalSet.has(c.toLowerCase()))
+            participants.push(c);
+    }
+    return participants;
+}
+/**
+ * Resolve the design-signal type from issue labels.
+ *
+ * Priority order mirrors the RFC's weighting (positive signals first),
+ * so an issue tagged with both a positive and a negative label resolves
+ * to the positive one. This is deliberate: design authorities shouldn't
+ * dual-tag in practice, but if they do, we don't want to default to the
+ * punitive path.
+ */
+export function parseDesignSignalType(labels) {
+    const priority = [
+        'advances-design-coherence',
+        'fills-catalog-gap',
+        'fragments-component-catalog',
+        'misaligned-with-brand',
+    ];
+    const lowered = labels.map((l) => l.toLowerCase());
+    for (const target of priority) {
+        const label = Object.entries(LABEL_TO_SIGNAL).find(([, v]) => v === target)?.[0];
+        if (label && lowered.includes(label))
+            return target;
+    }
+    return 'unspecified';
+}
+//# sourceMappingURL=design-authority.js.map

package/dist/design-lookahead.d.ts

@@ -0,0 +1,64 @@
+/**
+ * C7 — Design Lookahead Notification (RFC-0008 §11 + Amendment 6).
+ *
+ * Fires a notification when a backlog item has:
+ *   1. Stayed in the top-10 of the prioritized backlog for ≥48h
+ *      (OQ-7 stability threshold against priority churn)
+ *   2. Design-system impact (any of: frontend code area, catalog gaps,
+ *      or `PRODUCT_HIGH_DESIGN_LOW` tension flag)
+ *   3. Not been notified within the last 7 days
+ *      (dedupe via `design_lookahead_notifications` table)
+ *
+ * The payload is the full `PillarBreakdown` plus gap and tension
+ * information — design reviewers need the structured context to decide
+ * whether to unblock, reprioritize, or flag the item.
+ */
+import type { StateStore } from './state/store.js';
+import type { PillarBreakdown, TensionFlag } from './pillar-breakdown.js';
+export interface DesignLookaheadConfig {
+    /** Min time an issue must have been in top-N to qualify. Default 48h. */
+    stabilityThresholdMs: number;
+    /** Min time since last notification before re-notifying. Default 7d. */
+    dedupeExpiryMs: number;
+    /** Cutoff for "top" (ignored when `items` is already pre-filtered). */
+    topN: number;
+}
+export declare const DEFAULT_LOOKAHEAD_CONFIG: DesignLookaheadConfig;
+export interface BacklogItem {
+    issueNumber: number;
+    /** Composite score that placed this item in top-N. */
+    composite: number;
+    /** Pillar breakdown from the admission composite. */
+    pillarBreakdown: PillarBreakdown;
+    /** When the item first entered the top-N (ISO timestamp). */
+    enteredTop10At?: string;
+    /** Whether the code area has frontend components (C3 classifier). */
+    hasFrontendComponents?: boolean;
+    /** Catalog gaps surfaced during enrichment (C2). */
+    catalogGaps?: string[];
+}
+export type DesignImpactReason = 'frontend-components' | 'catalog-gaps' | 'product-design-tension';
+export interface DesignLookaheadNotification {
+    type: 'DesignLookaheadNotification';
+    issueNumber: number;
+    notifiedAt: string;
+    /** Reasons this item was flagged (ordered as detected). */
+    reasons: DesignImpactReason[];
+    pillarBreakdown: PillarBreakdown;
+    catalogGaps: string[];
+    tensionFlags: TensionFlag[];
+}
+export declare function detectDesignImpactReasons(item: BacklogItem): DesignImpactReason[];
+export interface DesignLookaheadDetectorDeps {
+    stateStore: StateStore;
+    now?: () => number;
+    config?: Partial<DesignLookaheadConfig>;
+}
+/**
+ * Run one scheduler tick. `items` should already be the top-N backlog
+ * items in descending composite order; caller is responsible for
+ * tracking `enteredTop10At` across ticks. Returns the notifications
+ * to emit + persist for this tick.
+ */
+export declare function detectDesignLookaheadNotifications(items: readonly BacklogItem[], deps: DesignLookaheadDetectorDeps): DesignLookaheadNotification[];
+//# sourceMappingURL=design-lookahead.d.ts.map

package/dist/design-lookahead.js

@@ -0,0 +1,86 @@
+/**
+ * C7 — Design Lookahead Notification (RFC-0008 §11 + Amendment 6).
+ *
+ * Fires a notification when a backlog item has:
+ *   1. Stayed in the top-10 of the prioritized backlog for ≥48h
+ *      (OQ-7 stability threshold against priority churn)
+ *   2. Design-system impact (any of: frontend code area, catalog gaps,
+ *      or `PRODUCT_HIGH_DESIGN_LOW` tension flag)
+ *   3. Not been notified within the last 7 days
+ *      (dedupe via `design_lookahead_notifications` table)
+ *
+ * The payload is the full `PillarBreakdown` plus gap and tension
+ * information — design reviewers need the structured context to decide
+ * whether to unblock, reprioritize, or flag the item.
+ */
+// ── Thresholds ─────────────────────────────────────────────────────────
+const DEFAULT_STABILITY_MS = 48 * 60 * 60 * 1000;
+const DEFAULT_DEDUPE_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_TOP_N = 10;
+export const DEFAULT_LOOKAHEAD_CONFIG = {
+    stabilityThresholdMs: DEFAULT_STABILITY_MS,
+    dedupeExpiryMs: DEFAULT_DEDUPE_EXPIRY_MS,
+    topN: DEFAULT_TOP_N,
+};
+// ── Impact detection ───────────────────────────────────────────────────
+export function detectDesignImpactReasons(item) {
+    const reasons = [];
+    if (item.hasFrontendComponents)
+        reasons.push('frontend-components');
+    if ((item.catalogGaps ?? []).length > 0)
+        reasons.push('catalog-gaps');
+    if (item.pillarBreakdown.tensions.some((t) => t.type === 'PRODUCT_HIGH_DESIGN_LOW')) {
+        reasons.push('product-design-tension');
+    }
+    return reasons;
+}
+/**
+ * Run one scheduler tick. `items` should already be the top-N backlog
+ * items in descending composite order; caller is responsible for
+ * tracking `enteredTop10At` across ticks. Returns the notifications
+ * to emit + persist for this tick.
+ */
+export function detectDesignLookaheadNotifications(items, deps) {
+    const config = { ...DEFAULT_LOOKAHEAD_CONFIG, ...deps.config };
+    const nowMs = (deps.now ?? (() => Date.now()))();
+    const topItems = items.slice(0, config.topN);
+    const emissions = [];
+    for (const item of topItems) {
+        // 1. Stability check — must have been in top-N ≥ stabilityThresholdMs.
+        if (!item.enteredTop10At)
+            continue;
+        const enteredMs = Date.parse(item.enteredTop10At);
+        if (Number.isNaN(enteredMs))
+            continue;
+        if (nowMs - enteredMs < config.stabilityThresholdMs)
+            continue;
+        // 2. Design-system impact.
+        const reasons = detectDesignImpactReasons(item);
+        if (reasons.length === 0)
+            continue;
+        // 3. Dedupe via notification table.
+        const existing = deps.stateStore.getDesignLookaheadNotification(item.issueNumber);
+        if (existing?.lastNotifiedAt) {
+            const lastMs = Date.parse(existing.lastNotifiedAt);
+            if (!Number.isNaN(lastMs) && nowMs - lastMs < config.dedupeExpiryMs)
+                continue;
+        }
+        // 4. Emit + record.
+        const notification = {
+            type: 'DesignLookaheadNotification',
+            issueNumber: item.issueNumber,
+            notifiedAt: new Date(nowMs).toISOString(),
+            reasons,
+            pillarBreakdown: item.pillarBreakdown,
+            catalogGaps: item.catalogGaps ?? [],
+            tensionFlags: item.pillarBreakdown.tensions,
+        };
+        emissions.push(notification);
+        deps.stateStore.upsertDesignLookaheadNotification({
+            issueNumber: item.issueNumber,
+            pillarBreakdownJson: JSON.stringify(item.pillarBreakdown),
+        });
+    }
+    return emissions;
+}
+//# sourceMappingURL=design-lookahead.js.map