@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/design-system-stewardship.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stewardship enforcement for DesignSystemBinding resources (RFC-0006 §5.3).
+ *
+ * Validates that changes to authority-scoped fields are submitted by
+ * authorized principals. Changes to sharedAuthority fields require
+ * approval from both disciplines when requireBothDisciplines is true.
+ */
+import type { DesignSystemBinding } from '@ai-sdlc/reference';
+export interface StewardshipDecision {
+    allowed: boolean;
+    reason: string;
+    requiredApprovals?: string[];
+}
+/**
+ * Enforce stewardship constraints on a proposed change to a DesignSystemBinding.
+ *
+ * @param changedFields - The field paths being modified
+ * @param principal - The identity of the person/agent making the change
+ * @param binding - The DesignSystemBinding being modified
+ */
+export declare function enforceStewardship(changedFields: string[], principal: string, binding: DesignSystemBinding): StewardshipDecision;
+//# sourceMappingURL=design-system-stewardship.d.ts.map

package/dist/design-system-stewardship.js

@@ -0,0 +1,85 @@
+/**
+ * Stewardship enforcement for DesignSystemBinding resources (RFC-0006 §5.3).
+ *
+ * Validates that changes to authority-scoped fields are submitted by
+ * authorized principals. Changes to sharedAuthority fields require
+ * approval from both disciplines when requireBothDisciplines is true.
+ */
+/**
+ * Determine which authority scope a field belongs to.
+ */
+function findAuthorityScope(stewardship, field) {
+    if (stewardship.sharedAuthority?.scope?.includes(field))
+        return 'shared';
+    if (stewardship.designAuthority.scope.includes(field))
+        return 'design';
+    if (stewardship.engineeringAuthority.scope.includes(field))
+        return 'engineering';
+    return 'none';
+}
+/**
+ * Check if a principal is authorized for a given authority scope.
+ */
+function isAuthorized(stewardship, principal, scope) {
+    const authorityType = findAuthorityScope(stewardship, scope);
+    switch (authorityType) {
+        case 'design':
+            return stewardship.designAuthority.principals.includes(principal);
+        case 'engineering':
+            return stewardship.engineeringAuthority.principals.includes(principal);
+        case 'shared':
+            return (stewardship.designAuthority.principals.includes(principal) ||
+                stewardship.engineeringAuthority.principals.includes(principal) ||
+                (stewardship.sharedAuthority?.principals?.includes(principal) ?? false));
+        case 'none':
+            return true; // Unscoped fields are unrestricted
+    }
+}
+/**
+ * Enforce stewardship constraints on a proposed change to a DesignSystemBinding.
+ *
+ * @param changedFields - The field paths being modified
+ * @param principal - The identity of the person/agent making the change
+ * @param binding - The DesignSystemBinding being modified
+ */
+export function enforceStewardship(changedFields, principal, binding) {
+    const stewardship = binding.spec.stewardship;
+    const requireBoth = stewardship.changeApproval?.requireBothDisciplines ?? true;
+    for (const field of changedFields) {
+        const scope = findAuthorityScope(stewardship, field);
+        // Shared authority fields may require both disciplines
+        if (scope === 'shared' && requireBoth) {
+            const isDesign = stewardship.designAuthority.principals.includes(principal);
+            const isEngineering = stewardship.engineeringAuthority.principals.includes(principal);
+            const isShared = stewardship.sharedAuthority?.principals?.includes(principal) ?? false;
+            if (!isDesign && !isEngineering && !isShared) {
+                return {
+                    allowed: false,
+                    reason: `Principal "${principal}" is not authorized for shared-authority field "${field}"`,
+                };
+            }
+            // Identify which discipline still needs to approve
+            const needed = [];
+            if (!isDesign && !isShared)
+                needed.push('design');
+            if (!isEngineering && !isShared)
+                needed.push('engineering');
+            if (needed.length > 0) {
+                return {
+                    allowed: false,
+                    reason: `Shared-authority field "${field}" requires approval from both disciplines. Pending: ${needed.join(', ')}`,
+                    requiredApprovals: needed,
+                };
+            }
+        }
+        // Design/engineering scoped fields
+        if (!isAuthorized(stewardship, principal, field)) {
+            return {
+                allowed: false,
+                reason: `Principal "${principal}" is not authorized for ${scope}-authority field "${field}"`,
+            };
+        }
+    }
+    return { allowed: true, reason: 'All changed fields are within principal authority' };
+}
+//# sourceMappingURL=design-system-stewardship.js.map

package/dist/design-system-validation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Validates DesignSystemBinding inheritance constraints (RFC-0006 §5.6).
+ *
+ * Multi-brand inheritance uses the `extends` field. Validation enforces:
+ * - Child compliance thresholds >= parent thresholds
+ * - Child cannot remove parent disallowHardcoded categories
+ * - Inheritance depth limited to two levels (parent → child)
+ */
+import type { DesignSystemBinding } from '@ai-sdlc/reference';
+export interface InheritanceError {
+    field: string;
+    message: string;
+}
+export interface InheritanceValidationResult {
+    valid: boolean;
+    errors: InheritanceError[];
+}
+/**
+ * Resolve the parent binding from the collection by name.
+ */
+export declare function resolveParent(child: DesignSystemBinding, bindings: DesignSystemBinding[]): DesignSystemBinding | undefined;
+/**
+ * Validate that a child DesignSystemBinding conforms to its parent's constraints.
+ *
+ * Rules:
+ * 1. Child compliance.coverage.minimum >= parent compliance.coverage.minimum
+ * 2. Child compliance.coverage.target >= parent compliance.coverage.target (if both defined)
+ * 3. Child must not remove any parent disallowHardcoded categories
+ * 4. Two-level depth limit: parent must not itself have an `extends` field
+ */
+export declare function validateDesignSystemInheritance(child: DesignSystemBinding, parent: DesignSystemBinding): InheritanceValidationResult;
+/**
+ * Validate all DesignSystemBinding inheritance relationships in a collection.
+ * Returns errors for any invalid inheritance chains.
+ */
+export declare function validateAllInheritance(bindings: DesignSystemBinding[]): InheritanceValidationResult;
+//# sourceMappingURL=design-system-validation.d.ts.map

package/dist/design-system-validation.js

@@ -0,0 +1,88 @@
+/**
+ * Validates DesignSystemBinding inheritance constraints (RFC-0006 §5.6).
+ *
+ * Multi-brand inheritance uses the `extends` field. Validation enforces:
+ * - Child compliance thresholds >= parent thresholds
+ * - Child cannot remove parent disallowHardcoded categories
+ * - Inheritance depth limited to two levels (parent → child)
+ */
+/**
+ * Resolve the parent binding from the collection by name.
+ */
+export function resolveParent(child, bindings) {
+    if (!child.spec.extends)
+        return undefined;
+    return bindings.find((b) => b.metadata.name === child.spec.extends);
+}
+/**
+ * Validate that a child DesignSystemBinding conforms to its parent's constraints.
+ *
+ * Rules:
+ * 1. Child compliance.coverage.minimum >= parent compliance.coverage.minimum
+ * 2. Child compliance.coverage.target >= parent compliance.coverage.target (if both defined)
+ * 3. Child must not remove any parent disallowHardcoded categories
+ * 4. Two-level depth limit: parent must not itself have an `extends` field
+ */
+export function validateDesignSystemInheritance(child, parent) {
+    const errors = [];
+    // Depth limit: parent must not extend another binding
+    if (parent.spec.extends) {
+        errors.push({
+            field: 'extends',
+            message: `Inheritance depth exceeds two levels: "${child.metadata.name}" extends "${parent.metadata.name}" which extends "${parent.spec.extends}". Only parent → child is supported in v1alpha1.`,
+        });
+    }
+    // Coverage minimum: child >= parent
+    const parentMin = parent.spec.compliance.coverage.minimum;
+    const childMin = child.spec.compliance.coverage.minimum;
+    if (childMin < parentMin) {
+        errors.push({
+            field: 'compliance.coverage.minimum',
+            message: `Child minimum coverage (${childMin}) is less than parent minimum (${parentMin}). Child thresholds can only tighten, not loosen.`,
+        });
+    }
+    // Coverage target: child >= parent (if both defined)
+    const parentTarget = parent.spec.compliance.coverage.target;
+    const childTarget = child.spec.compliance.coverage.target;
+    if (parentTarget !== undefined && childTarget !== undefined && childTarget < parentTarget) {
+        errors.push({
+            field: 'compliance.coverage.target',
+            message: `Child target coverage (${childTarget}) is less than parent target (${parentTarget}). Child thresholds can only tighten, not loosen.`,
+        });
+    }
+    // disallowHardcoded: child must not remove parent categories
+    const parentCategories = new Set((parent.spec.compliance.disallowHardcoded ?? []).map((r) => r.category));
+    const childCategories = new Set((child.spec.compliance.disallowHardcoded ?? []).map((r) => r.category));
+    for (const category of parentCategories) {
+        if (!childCategories.has(category)) {
+            errors.push({
+                field: 'compliance.disallowHardcoded',
+                message: `Child removes parent disallowHardcoded category "${category}". Child bindings may add categories but must not remove parent categories.`,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate all DesignSystemBinding inheritance relationships in a collection.
+ * Returns errors for any invalid inheritance chains.
+ */
+export function validateAllInheritance(bindings) {
+    const allErrors = [];
+    for (const binding of bindings) {
+        if (!binding.spec.extends)
+            continue;
+        const parent = resolveParent(binding, bindings);
+        if (!parent) {
+            allErrors.push({
+                field: 'extends',
+                message: `Binding "${binding.metadata.name}" extends "${binding.spec.extends}" but no binding with that name exists.`,
+            });
+            continue;
+        }
+        const result = validateDesignSystemInheritance(binding, parent);
+        allErrors.push(...result.errors);
+    }
+    return { valid: allErrors.length === 0, errors: allErrors };
+}
+//# sourceMappingURL=design-system-validation.js.map

package/dist/dispatch/index.d.ts

@@ -0,0 +1,4 @@
+export { runWorkerPool, type WorkItem, type WorkerPoolDeps, type WorkerPoolEvent, type WorkerPoolResult, } from './worker-pool.js';
+export { withMergeGate, forceReleaseMergeGate, isBranchUpToDate, MergeGateLockTimeoutError, type MergeGateDeps, } from './merge-gate.js';
+export { decideRequeue, appendTriageHistory, type FailureEvent, type RequeueTrigger, type RequeueDecision, type RequeueDecisionInput, type TriageHistoryEntry, type FailureClassification, } from './requeue.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dispatch/index.js

@@ -0,0 +1,4 @@
+export { runWorkerPool, } from './worker-pool.js';
+export { withMergeGate, forceReleaseMergeGate, isBranchUpToDate, MergeGateLockTimeoutError, } from './merge-gate.js';
+export { decideRequeue, appendTriageHistory, } from './requeue.js';
+//# sourceMappingURL=index.js.map

package/dist/dispatch/merge-gate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * File-based merge gate per RFC-0010 §10. Single mutex (<pool>/.merge-gate.lock)
+ * serializes the merge-eligibility/rebase step across parallel agents. Stale-base
+ * detection + rebase-on-conflict per §10.2.
+ *
+ * Per project policy (feedback_never_merge_prs.md): the orchestrator MUST NOT execute
+ * `gh pr merge`. The merge gate ensures a PR is in known-mergeable state when the
+ * human reviewer hits merge — it does NOT perform the merge itself.
+ */
+export declare class MergeGateLockTimeoutError extends Error {
+    readonly lockPath: string;
+    constructor(lockPath: string);
+}
+export interface MergeGateDeps {
+    /** Override for tests. */
+    now?: () => number;
+}
+/**
+ * Acquire the merge gate, run `work`, release. The lock is a sentinel file; if it
+ * already exists, the caller polls until it's released or the timeout elapses.
+ *
+ * Caveat: this is a cooperative file lock, not a kernel lock. Crashes can leave a
+ * stale lock; the caller is expected to forcibly remove and retry as a recovery step.
+ */
+export declare function withMergeGate<T>(poolDir: string, work: () => Promise<T>, options?: {
+    timeoutMs?: number;
+}, deps?: MergeGateDeps): Promise<T>;
+/**
+ * Force-remove a stale merge gate lock. Operators run this manually when an agent
+ * crashed mid-merge-gate and the lock file is orphaned.
+ */
+export declare function forceReleaseMergeGate(poolDir: string): Promise<void>;
+/**
+ * Test helper: write a sentinel lock file in an unexpected state (used by tests
+ * verifying the timeout path).
+ */
+export declare function _testWriteSentinel(poolDir: string): Promise<void>;
+/**
+ * Stale-base detection per RFC §10.2. Compares a branch's base SHA to the current
+ * remote target's HEAD; returns true when the branch is up-to-date.
+ *
+ * The actual git logic is delegated to the caller via `headOfRemote` so this stays
+ * unit-testable without shelling out.
+ */
+export declare function isBranchUpToDate(branchBaseSha: string, targetBranch: string, headOfRemote: (target: string) => Promise<string>): Promise<boolean>;
+//# sourceMappingURL=merge-gate.d.ts.map

package/dist/dispatch/merge-gate.js

@@ -0,0 +1,90 @@
+/**
+ * File-based merge gate per RFC-0010 §10. Single mutex (<pool>/.merge-gate.lock)
+ * serializes the merge-eligibility/rebase step across parallel agents. Stale-base
+ * detection + rebase-on-conflict per §10.2.
+ *
+ * Per project policy (feedback_never_merge_prs.md): the orchestrator MUST NOT execute
+ * `gh pr merge`. The merge gate ensures a PR is in known-mergeable state when the
+ * human reviewer hits merge — it does NOT perform the merge itself.
+ */
+import { mkdir, open, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const POLL_INTERVAL_MS = 100;
+const DEFAULT_LOCK_TIMEOUT_MS = 5 * 60 * 1000;
+export class MergeGateLockTimeoutError extends Error {
+    lockPath;
+    constructor(lockPath) {
+        super(`Timed out waiting for merge gate lock at ${lockPath}`);
+        this.lockPath = lockPath;
+        this.name = 'MergeGateLockTimeoutError';
+    }
+}
+/**
+ * Acquire the merge gate, run `work`, release. The lock is a sentinel file; if it
+ * already exists, the caller polls until it's released or the timeout elapses.
+ *
+ * Caveat: this is a cooperative file lock, not a kernel lock. Crashes can leave a
+ * stale lock; the caller is expected to forcibly remove and retry as a recovery step.
+ */
+export async function withMergeGate(poolDir, work, options = {}, deps = {}) {
+    const lockPath = join(poolDir, '.merge-gate.lock');
+    const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    const now = deps.now ?? (() => Date.now());
+    const startedAt = now();
+    await mkdir(dirname(lockPath), { recursive: true });
+    // Acquire — exclusive create, polling until success or timeout.
+    for (;;) {
+        try {
+            const fh = await open(lockPath, 'wx');
+            await fh.write(`pid=${process.pid}\nat=${new Date().toISOString()}\n`);
+            await fh.close();
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (now() - startedAt > timeoutMs) {
+                throw new MergeGateLockTimeoutError(lockPath);
+            }
+            await sleep(POLL_INTERVAL_MS);
+        }
+    }
+    try {
+        return await work();
+    }
+    finally {
+        // Best-effort release; if removal fails (lock file already gone), continue.
+        await rm(lockPath, { force: true });
+    }
+}
+/**
+ * Force-remove a stale merge gate lock. Operators run this manually when an agent
+ * crashed mid-merge-gate and the lock file is orphaned.
+ */
+export async function forceReleaseMergeGate(poolDir) {
+    await rm(join(poolDir, '.merge-gate.lock'), { force: true });
+}
+/**
+ * Test helper: write a sentinel lock file in an unexpected state (used by tests
+ * verifying the timeout path).
+ */
+export async function _testWriteSentinel(poolDir) {
+    const path = join(poolDir, '.merge-gate.lock');
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, 'sentinel');
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Stale-base detection per RFC §10.2. Compares a branch's base SHA to the current
+ * remote target's HEAD; returns true when the branch is up-to-date.
+ *
+ * The actual git logic is delegated to the caller via `headOfRemote` so this stays
+ * unit-testable without shelling out.
+ */
+export async function isBranchUpToDate(branchBaseSha, targetBranch, headOfRemote) {
+    const head = await headOfRemote(targetBranch);
+    return branchBaseSha === head;
+}
+//# sourceMappingURL=merge-gate.js.map

package/dist/dispatch/requeue.d.ts

@@ -0,0 +1,57 @@
+/**
+ * PPA re-scoring on requeue per RFC-0010 §9.4 (Q3 resolution).
+ *
+ * Hybrid algorithm: re-score IF
+ *   - time since last triage > 24h, OR
+ *   - failure type signals difficulty miscalibration, OR
+ *   - operator-triggered requeue.
+ *
+ * Otherwise trust the original PPA composite. Failure-type taxonomy from §9.4.1
+ * encodes which events are transient (trust score) vs intrinsic (re-score).
+ */
+export type FailureEvent = 'MergeConflict' | 'RebaseConflict' | 'CIFailure' | 'HarnessUnavailable' | 'BranchQuotaExceeded' | 'PortCollision' | 'BudgetExceeded' | 'OffPeakDeferralExceeded' | 'AgentTimeout' | 'MaxRetriesExhausted' | 'MigrationConflict' | 'MigrationFailed' | 'EstimateVariance' | 'WorktreeOwnershipMismatch';
+export type RequeueTrigger = 'automatic' | 'operator';
+export interface FailureClassification {
+    /** Trust the score on first occurrence; never re-score. */
+    alwaysTransient: boolean;
+    /** Re-score after this many failures of this type within 24h. */
+    reScoreAfterCount: number;
+    /** Re-score on first occurrence regardless. */
+    alwaysReScore: boolean;
+}
+export interface TriageHistoryEntry {
+    timestamp: string;
+    trigger: 'original' | 'time-threshold' | 'failure-type' | 'operator-requeue';
+    triggerDetail?: string;
+    composite: number;
+    costUsd?: number;
+}
+export interface RequeueDecisionInput {
+    /** Most recent triage entry for the issue. */
+    lastTriage: TriageHistoryEntry;
+    /** History of failures observed for this issue (unsorted). */
+    failureHistory: Array<{
+        at: string;
+        event: FailureEvent;
+    }>;
+    /** The failure that triggered this requeue (the fresh one). */
+    triggeringFailure: FailureEvent;
+    /** Whether the operator pressed the requeue button. */
+    trigger: RequeueTrigger;
+    now?: () => Date;
+}
+export interface RequeueDecision {
+    reScore: boolean;
+    reason: 'time-threshold' | 'failure-type' | 'operator-requeue' | 'trust-score';
+    detail: string;
+}
+export declare function decideRequeue(input: RequeueDecisionInput): RequeueDecision;
+/**
+ * Append a triage event to the per-issue history file, returning whether this
+ * crosses the RetriageStorm threshold (>10 retriage events in 24h).
+ */
+export declare function appendTriageHistory(artifactsDir: string, issueId: string, entry: TriageHistoryEntry): Promise<{
+    stormDetected: boolean;
+    eventsInWindow: number;
+}>;
+//# sourceMappingURL=requeue.d.ts.map

package/dist/dispatch/requeue.js

@@ -0,0 +1,131 @@
+/**
+ * PPA re-scoring on requeue per RFC-0010 §9.4 (Q3 resolution).
+ *
+ * Hybrid algorithm: re-score IF
+ *   - time since last triage > 24h, OR
+ *   - failure type signals difficulty miscalibration, OR
+ *   - operator-triggered requeue.
+ *
+ * Otherwise trust the original PPA composite. Failure-type taxonomy from §9.4.1
+ * encodes which events are transient (trust score) vs intrinsic (re-score).
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const TAXONOMY = {
+    MergeConflict: { alwaysTransient: true, reScoreAfterCount: Infinity, alwaysReScore: false },
+    RebaseConflict: { alwaysTransient: true, reScoreAfterCount: Infinity, alwaysReScore: false },
+    CIFailure: { alwaysTransient: false, reScoreAfterCount: 3, alwaysReScore: false },
+    HarnessUnavailable: { alwaysTransient: true, reScoreAfterCount: Infinity, alwaysReScore: false },
+    BranchQuotaExceeded: { alwaysTransient: true, reScoreAfterCount: Infinity, alwaysReScore: false },
+    PortCollision: { alwaysTransient: true, reScoreAfterCount: Infinity, alwaysReScore: false },
+    BudgetExceeded: { alwaysTransient: false, reScoreAfterCount: 2, alwaysReScore: false },
+    OffPeakDeferralExceeded: {
+        alwaysTransient: true,
+        reScoreAfterCount: Infinity,
+        alwaysReScore: false,
+    },
+    AgentTimeout: { alwaysTransient: false, reScoreAfterCount: 2, alwaysReScore: false },
+    MaxRetriesExhausted: { alwaysTransient: false, reScoreAfterCount: 1, alwaysReScore: true },
+    MigrationConflict: { alwaysTransient: false, reScoreAfterCount: 1, alwaysReScore: true },
+    MigrationFailed: { alwaysTransient: false, reScoreAfterCount: 1, alwaysReScore: true },
+    EstimateVariance: { alwaysTransient: false, reScoreAfterCount: 1, alwaysReScore: true },
+    WorktreeOwnershipMismatch: {
+        alwaysTransient: true,
+        reScoreAfterCount: Infinity,
+        alwaysReScore: false,
+    },
+};
+const TIME_THRESHOLD_HOURS = 24;
+const FAILURE_HISTORY_WINDOW_HOURS = 24;
+const RETRIAGE_STORM_THRESHOLD = 10;
+export function decideRequeue(input) {
+    const now = (input.now ?? (() => new Date()))();
+    if (input.trigger === 'operator') {
+        return { reScore: true, reason: 'operator-requeue', detail: 'operator manually requeued' };
+    }
+    const lastTriage = new Date(input.lastTriage.timestamp);
+    const hoursSinceTriage = (now.getTime() - lastTriage.getTime()) / (60 * 60 * 1000);
+    if (hoursSinceTriage > TIME_THRESHOLD_HOURS) {
+        return {
+            reScore: true,
+            reason: 'time-threshold',
+            detail: `${hoursSinceTriage.toFixed(1)}h since last triage (>24h)`,
+        };
+    }
+    const taxonomy = TAXONOMY[input.triggeringFailure];
+    if (taxonomy.alwaysReScore) {
+        return {
+            reScore: true,
+            reason: 'failure-type',
+            detail: `${input.triggeringFailure} signals difficulty miscalibration`,
+        };
+    }
+    if (!taxonomy.alwaysTransient) {
+        const recent = input.failureHistory.filter((f) => {
+            if (f.event !== input.triggeringFailure)
+                return false;
+            const at = new Date(f.at);
+            const hours = (now.getTime() - at.getTime()) / (60 * 60 * 1000);
+            return hours <= FAILURE_HISTORY_WINDOW_HOURS;
+        });
+        // The triggering failure is not yet in the history — count includes it.
+        if (recent.length + 1 >= taxonomy.reScoreAfterCount) {
+            return {
+                reScore: true,
+                reason: 'failure-type',
+                detail: `${input.triggeringFailure} occurred ${recent.length + 1}× in 24h (threshold ${taxonomy.reScoreAfterCount})`,
+            };
+        }
+    }
+    return {
+        reScore: false,
+        reason: 'trust-score',
+        detail: taxonomy.alwaysTransient
+            ? `${input.triggeringFailure} is transient`
+            : `${input.triggeringFailure} below re-score threshold`,
+    };
+}
+/**
+ * Append a triage event to the per-issue history file, returning whether this
+ * crosses the RetriageStorm threshold (>10 retriage events in 24h).
+ */
+export async function appendTriageHistory(artifactsDir, issueId, entry) {
+    const path = join(artifactsDir, issueId, 'triage-history.jsonl');
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, JSON.stringify(entry) + '\n', 'utf8');
+    // Count retriage events in the last 24h (excludes 'original').
+    const eventsInWindow = await countRetriageInWindow(path, new Date());
+    return {
+        stormDetected: eventsInWindow > RETRIAGE_STORM_THRESHOLD,
+        eventsInWindow,
+    };
+}
+async function countRetriageInWindow(path, now) {
+    const { readFile } = await import('node:fs/promises');
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    const cutoff = now.getTime() - FAILURE_HISTORY_WINDOW_HOURS * 60 * 60 * 1000;
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e.trigger === 'original')
+                continue;
+            const at = new Date(e.timestamp).getTime();
+            if (at >= cutoff)
+                count++;
+        }
+        catch {
+            // Skip malformed lines.
+        }
+    }
+    return count;
+}
+//# sourceMappingURL=requeue.js.map

package/dist/dispatch/worker-pool.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bounded-concurrency worker pool per RFC-0010 §9. Accepts a stream of work items in
+ * PPA-priority order, dispatches up to `maxConcurrent` simultaneously, and surfaces
+ * structured admission/dispatch events.
+ */
+export interface WorkItem<T> {
+    /** Unique id (typically issue id). */
+    id: string;
+    /** PPA composite score; higher = higher priority. */
+    ppaScore: number;
+    /** The actual work to perform when admitted. */
+    payload: T;
+}
+export interface WorkerPoolDeps<T, R> {
+    /** Number of in-flight items allowed at once. */
+    maxConcurrent: number;
+    /** Execute a single work item; called by the pool with concurrency-bounded parallelism. */
+    execute: (item: WorkItem<T>) => Promise<R>;
+    /** Optional admission gate; return false to defer the item back into the queue. */
+    admit?: (item: WorkItem<T>) => Promise<boolean>;
+    /** Optional structured event sink. */
+    onEvent?: (event: WorkerPoolEvent<T>) => void;
+}
+export type WorkerPoolEvent<T> = {
+    type: 'queued';
+    item: WorkItem<T>;
+    queueSize: number;
+} | {
+    type: 'admission-deferred';
+    item: WorkItem<T>;
+} | {
+    type: 'started';
+    item: WorkItem<T>;
+    inFlight: number;
+} | {
+    type: 'completed';
+    item: WorkItem<T>;
+    durationMs: number;
+} | {
+    type: 'failed';
+    item: WorkItem<T>;
+    error: Error;
+};
+export interface WorkerPoolResult<T, R> {
+    succeeded: Array<{
+        item: WorkItem<T>;
+        result: R;
+    }>;
+    failed: Array<{
+        item: WorkItem<T>;
+        error: Error;
+    }>;
+    deferred: Array<WorkItem<T>>;
+}
+/**
+ * Process all items with bounded concurrency. Items are dispatched in PPA score order
+ * (descending). Items that the admission gate rejects are returned in `deferred` for
+ * the caller to requeue or escalate. Failed executions are returned in `failed`; the
+ * pool does NOT auto-retry — that's the caller's responsibility (see RFC §9.4).
+ */
+export declare function runWorkerPool<T, R>(items: WorkItem<T>[], deps: WorkerPoolDeps<T, R>): Promise<WorkerPoolResult<T, R>>;
+//# sourceMappingURL=worker-pool.d.ts.map