@ai-sdlc/orchestrator 0.5.0 → 0.9.0

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

package/dist/dispatch/worker-pool.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+/**
+ * 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 async function runWorkerPool(items, deps) {
+    if (deps.maxConcurrent < 1) {
+        throw new Error(`maxConcurrent must be >= 1 (got ${deps.maxConcurrent})`);
+    }
+    const sorted = [...items].sort((a, b) => b.ppaScore - a.ppaScore);
+    const result = { succeeded: [], failed: [], deferred: [] };
+    const onEvent = deps.onEvent ?? (() => { });
+    for (const item of sorted) {
+        onEvent({ type: 'queued', item, queueSize: sorted.length });
+    }
+    let inFlight = 0;
+    const queue = [...sorted];
+    // Spawn N workers that pull from the shared queue until empty.
+    const worker = async () => {
+        for (;;) {
+            const item = queue.shift();
+            if (!item)
+                return;
+            inFlight++;
+            try {
+                if (deps.admit) {
+                    const admitted = await deps.admit(item);
+                    if (!admitted) {
+                        onEvent({ type: 'admission-deferred', item });
+                        result.deferred.push(item);
+                        continue;
+                    }
+                }
+                const start = Date.now();
+                onEvent({ type: 'started', item, inFlight });
+                const r = await deps.execute(item);
+                onEvent({ type: 'completed', item, durationMs: Date.now() - start });
+                result.succeeded.push({ item, result: r });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                onEvent({ type: 'failed', item, error });
+                result.failed.push({ item, error });
+            }
+            finally {
+                inFlight--;
+            }
+        }
+    };
+    const workers = Array.from({ length: Math.min(deps.maxConcurrent, sorted.length) }, () => worker());
+    await Promise.all(workers);
+    return result;
+}
+//# sourceMappingURL=worker-pool.js.map

package/dist/execute.d.ts

@@ -76,9 +76,49 @@ export interface ExecuteOptions {
     stateStore?: StateStore;
     /** Priority score from PPA scoring (set by watch loop or caller). */
     priorityScore?: PriorityScore;
+    /**
+     * Override the Pipeline resource selected for this execution. When set, takes
+     * precedence over the on-disk `config.pipeline` loaded from `.ai-sdlc/`. The
+     * watch loop uses this to pass the dispatcher-selected pipeline (e.g., the
+     * backlog pipeline for AISDLC-* issues) instead of letting executePipeline
+     * fall back to the canonical pipeline.yaml.
+     */
+    pipelineOverride?: import('@ai-sdlc/reference').Pipeline;
 }
 /**
  * Execute the full AI-SDLC pipeline for a given issue ID.
  */
 export declare function executePipeline(issueId: string, options?: ExecuteOptions): Promise<PipelineResult>;
+/**
+ * Capture the current branch name (or commit SHA in detached-HEAD state) so the
+ * pipeline can restore the user's worktree after the run. Returns null on git
+ * failure — callers treat null as "don't try to restore".
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function captureCurrentBranch(workDir: string): Promise<string | null>;
+/**
+ * Restore the user's original HEAD if the pipeline switched branches AND the
+ * working tree is clean. If the working tree has uncommitted changes (from a
+ * partial pipeline run), log a warning and leave HEAD where it is — better to
+ * preserve the pipeline's state than to clobber whatever the user has.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function restoreOriginalBranch(workDir: string, originalHead: string | null, log: {
+    info: (msg: string) => void;
+} | undefined): Promise<void>;
+/**
+ * Push a branch to origin, rebasing onto the remote tip if it has advanced.
+ * Pre-AISDLC-68-rerun the pipeline did a plain `git push` and rejected with
+ * non-fast-forward when the remote branch had drifted (e.g. a previous run's
+ * commits or a manual edit). The fix: try push; on non-fast-forward, fetch +
+ * rebase HEAD onto origin/<branch>, retry once. Rebase conflicts surface as
+ * the original error so the operator can resolve manually.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function pushBranchWithRebase(workDir: string, branchName: string, log: {
+    info: (msg: string) => void;
+} | undefined): Promise<void>;
 //# sourceMappingURL=execute.d.ts.map