@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/orchestration/phase-runner.js

@@ -0,0 +1,347 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+import { AgentWorktree } from '../agents/worktree.js';
+import { parseCompletionReport, } from '../agents/completion-report.js';
+import { verifyEngineerClaims } from '../agents/wrfc-reporting.js';
+import { runWrfcGateChecks } from '../agents/wrfc-gate-runtime.js';
+import { getWrfcTransportRetryDelayMs, getWrfcTransportRetryLimit } from '../agents/wrfc-config.js';
+import { isTransportFailureMessage } from '../types/errors.js';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+import { excludeUntouchedLaunchResidue } from './dirty-guard.js';
+import { classifyBookkeepingFailure } from './bookkeeping.js';
+import { mergeWorkItemUsage } from './types.js';
+function templateForPhase(phase) {
+    return phase.kind === 'review' || phase.kind === 'gate' ? 'general' : 'engineer';
+}
+function buildPhaseTask(item, phase, priorReports) {
+    const priorContext = priorReports.length > 0
+        ? `\n\nPrior phase reports for this work item:\n${priorReports.map((r) => `- ${r.phaseId}: ${r.report.summary}`).join('\n')}`
+        : '';
+    if (phase.kind === 'review' || phase.kind === 'gate') {
+        return `Assess the following work item's changes against its constraints and report findings. Do not modify files.\n\nWork item: ${item.title}\n${item.task}${priorContext}`;
+    }
+    if (phase.kind === 'fix') {
+        return `Address the following findings for this work item.\n\nWork item: ${item.title}\n${item.task}${priorContext}`;
+    }
+    return `${item.task}${priorContext}`;
+}
+function genericReport(summary) {
+    return { version: 1, archetype: 'generic', summary, result: summary };
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+function awaitAgentTermination(runtimeBus, agentManager, agentId) {
+    return new Promise((resolve) => {
+        const unsubscribe = runtimeBus.onDomain('agents', (envelope) => {
+            const event = envelope.payload;
+            if (event.agentId !== agentId)
+                return;
+            if (event.type !== 'AGENT_COMPLETED' && event.type !== 'AGENT_FAILED' && event.type !== 'AGENT_CANCELLED')
+                return;
+            unsubscribe();
+            const status = event.type === 'AGENT_COMPLETED' ? 'completed' : event.type === 'AGENT_CANCELLED' ? 'cancelled' : 'failed';
+            resolve({ status, record: agentManager.getStatus(agentId) });
+        });
+    });
+}
+function usageFromRecord(record, priceUsage) {
+    const u = record?.usage;
+    const base = {
+        inputTokens: u?.inputTokens ?? 0,
+        outputTokens: u?.outputTokens ?? 0,
+        cacheReadTokens: u?.cacheReadTokens ?? 0,
+        cacheWriteTokens: u?.cacheWriteTokens ?? 0,
+        reasoningTokens: u?.reasoningTokens,
+        llmCallCount: u?.llmCallCount ?? 0,
+        turnCount: u?.turnCount ?? 0,
+        toolCallCount: record?.toolCallCount ?? 0,
+    };
+    let costUsd = null;
+    let costState = 'unpriced';
+    if (u && priceUsage) {
+        try {
+            const priced = priceUsage(record?.model, { ...base, costUsd: null, costState: 'unpriced' });
+            if (priced !== null) {
+                costUsd = priced;
+                costState = 'priced';
+            }
+        }
+        catch {
+            // stays unpriced — never fabricate a cost from a throwing pricer.
+        }
+    }
+    return { ...base, costUsd, costState };
+}
+/**
+ * Combines a new phase's usage into a work item's running total. Single-source
+ * cost (never independently re-priced here). Thin alias over the canonical
+ * {@link mergeWorkItemUsage} (types.ts) so the phase-runner, the engine, and
+ * the fleet rollup adapters all fold usage through exactly one implementation.
+ */
+export function mergeUsage(a, b) {
+    return mergeWorkItemUsage(a, b);
+}
+/** Quality gates (global-config-driven, reused VERBATIM) + phase-required-gate assertion + phantom guard + reviewer constraint findings. */
+async function evaluateGate(workstream, phase, report, deps) {
+    const results = [...await runWrfcGateChecks({
+            configManager: deps.configManager,
+            projectRoot: deps.projectRoot,
+            runtimeBus: deps.runtimeBus,
+            sessionId: deps.sessionId,
+            chainId: workstream.id,
+            // Worktree mode (BIG-3 item 5): run the configured quality gates INSIDE the
+            // item's isolated worktree, the same way the phantom-work guard above
+            // verifies claims against that worktree path. BIG-1 fixed only the phantom
+            // check; without this, gates (typecheck/lint/test) would run against the
+            // shared projectRoot and never see the item's isolated changes. Absent
+            // (shared mode) ⇒ runWrfcGateChecks defaults cwd to projectRoot — unchanged.
+            ...(deps.itemWorktree ? { cwd: deps.itemWorktree.path } : {}),
+        })];
+    const ranNames = new Set(results.map((r) => r.gate));
+    const missingRequired = phase.gate.gates.filter((name) => !ranNames.has(name));
+    for (const name of missingRequired) {
+        results.push({ gate: name, passed: false, output: 'required gate is not configured/enabled', durationMs: 0 });
+    }
+    if (report.archetype === 'engineer' && !deps.skipClaimVerification) {
+        // Worktree mode: the agent's files landed in the item's OWN worktree, not
+        // the shared projectRoot — verify claims (existence + `git diff`) against
+        // that worktree path, or every real change would be falsely flagged as
+        // phantom work (nothing to find at projectRoot).
+        const verification = verifyEngineerClaims(report, deps.itemWorktree?.path ?? deps.projectRoot);
+        if (verification.kind === 'unverified' || verification.kind === 'unverifiable_no_claims') {
+            results.push({ gate: 'phantom-work-guard', passed: false, output: verification.summary, durationMs: 0 });
+        }
+    }
+    let constraintFindings;
+    let unsatisfiedConstraintIds;
+    if (report.archetype === 'reviewer') {
+        const reviewer = report;
+        constraintFindings = reviewer.constraintFindings ?? [];
+        const unsatisfied = constraintFindings.filter((f) => !f.satisfied);
+        unsatisfiedConstraintIds = unsatisfied.map((f) => f.constraintId);
+        if (!reviewer.passed || unsatisfied.length > 0) {
+            results.push({
+                gate: 'reviewer-verdict',
+                passed: false,
+                output: unsatisfied.length > 0
+                    ? `${unsatisfied.length} unsatisfied constraint(s): ${unsatisfied.map((f) => f.constraintId).join(', ')}`
+                    : 'reviewer did not pass',
+                durationMs: 0,
+            });
+        }
+    }
+    return {
+        passed: results.every((r) => r.passed),
+        results,
+        constraintFindings,
+        unsatisfiedConstraintIds,
+    };
+}
+/**
+ * Runs the POST-gate scoped-commit + merge for a passed phase and reports its
+ * outcome HONESTLY rather than swallowing failures. The gate has already
+ * decided the phase passed; this step only records the changes, so its result
+ * is bookkeeping: a failure surfaces to the engine as a warning on a passed
+ * item (or, for the narrow negating set — workspace corruption, see
+ * bookkeeping.ts — as an item failure), never as a silent no-op that lets the
+ * fleet imply a commit happened when it did not (DEBT-4 item 1).
+ */
+async function commitPhaseWork(item, phase, agentId, worktree, deps) {
+    if (phase.gate.scope === 'off') {
+        return { commit: { status: 'skipped', reason: 'commit disabled for this phase (gate scope: off)' } };
+    }
+    let paths = phase.gate.scope === 'scoped' ? item.touchedPaths : undefined;
+    let exclusion;
+    // Worktree mode: the item commits onto its own branch INSIDE its dedicated
+    // worktree, which the engine created fresh (and therefore clean) at claim.
+    // The launch-dirty snapshot is taken against the SHARED projectRoot, so it
+    // has nothing to say about a just-created worktree — a fresh worktree starts
+    // clean, so its launch-dirty residue is trivially empty. Skip the residue
+    // exclusion entirely and commit straight onto the item branch; NO merge to
+    // base (the sequential integration lane owns that at item termination).
+    if (deps.itemWorktree) {
+        try {
+            const result = await deps.itemWorktree.commit(`orchestration: ${item.title} — ${phase.kind} phase`, paths);
+            const ignoredNote = result.skippedIgnored.length > 0
+                ? `${result.skippedIgnored.length} ignored path${result.skippedIgnored.length === 1 ? '' : 's'} skipped`
+                : undefined;
+            if (result.hash === null) {
+                return { commit: { status: 'skipped', reason: ignoredNote ? `nothing to stage (${ignoredNote})` : 'nothing to stage' } };
+            }
+            return { commit: { status: 'committed', hash: result.hash, ...(ignoredNote ? { reason: ignoredNote } : {}) } };
+        }
+        catch (error) {
+            const reason = summarizeError(error);
+            const negating = classifyBookkeepingFailure(error) === 'negating';
+            logger.warn('orchestration phase-runner: worktree scoped commit did not complete', {
+                itemId: item.id, phaseId: phase.id, worktreePath: deps.itemWorktree.path, error: reason, negating,
+            });
+            return { commit: { status: 'failed', reason, negating } };
+        }
+    }
+    if (paths && paths.length > 0 && deps.launchDirtySnapshot) {
+        const launchSnapshot = deps.launchDirtySnapshot;
+        if (launchSnapshot.size > 0) {
+            const { included, excluded } = excludeUntouchedLaunchResidue(deps.projectRoot, paths, launchSnapshot);
+            if (excluded.length > 0) {
+                exclusion = { excludedPaths: excluded, skipped: included.length === 0 };
+                if (included.length === 0) {
+                    // Every candidate path is untouched launch-dirty residue — an
+                    // honest "nothing this phase did needs committing", not a silent
+                    // no-op AND not a fallback to sweeping the whole working tree.
+                    logger.info('orchestration phase-runner: scoped commit skipped — every candidate path is untouched launch-dirty residue', {
+                        itemId: item.id,
+                        phaseId: phase.id,
+                        excludedPaths: excluded,
+                    });
+                    return { exclusion, commit: { status: 'skipped', reason: 'every candidate path was untouched launch-dirty residue' } };
+                }
+                logger.info('orchestration phase-runner: excluded untouched launch-dirty residue from scoped commit', {
+                    itemId: item.id,
+                    phaseId: phase.id,
+                    excludedPaths: excluded,
+                });
+                paths = [...included];
+            }
+        }
+    }
+    try {
+        const result = await worktree.commitWorkingTree(`orchestration: ${item.title} — ${phase.kind} phase`, paths);
+        await worktree.merge(agentId);
+        const ignoredNote = result.skippedIgnored.length > 0
+            ? `${result.skippedIgnored.length} ignored path${result.skippedIgnored.length === 1 ? '' : 's'} skipped`
+            : undefined;
+        if (result.hash === null) {
+            // A null hash is "nothing was staged" — an honest skip, not a landed commit.
+            return { exclusion, commit: { status: 'skipped', reason: ignoredNote ? `nothing to stage (${ignoredNote})` : 'nothing to stage' } };
+        }
+        return {
+            exclusion,
+            commit: { status: 'committed', hash: result.hash, ...(ignoredNote ? { reason: ignoredNote } : {}) },
+        };
+    }
+    catch (error) {
+        const reason = summarizeError(error);
+        const negating = classifyBookkeepingFailure(error) === 'negating';
+        // Non-fatal by default: the gate already passed, so the engine treats this
+        // as a warning on a passed item. Only a NEGATING failure (workspace
+        // corruption — bookkeeping.ts) flips the item to failed.
+        logger.warn('orchestration phase-runner: scoped commit/merge did not complete', {
+            itemId: item.id, phaseId: phase.id, error: reason, negating,
+        });
+        return { exclusion, commit: { status: 'failed', reason, negating } };
+    }
+}
+/** Runs one WorkItem through one Phase to completion (or cancellation/failure). Recurses (bounded by transportRetryLimit) on a transport-classified spawn failure. */
+export async function runPhase(workstream, item, phase, priorReports, deps) {
+    const startedAt = Date.now();
+    const createWorktree = deps.createWorktree ?? (() => new AgentWorktree(deps.projectRoot));
+    const worktree = createWorktree();
+    const record = deps.agentManager.spawn({
+        mode: 'spawn',
+        task: buildPhaseTask(item, phase, priorReports),
+        template: templateForPhase(phase),
+        dangerously_disable_wrfc: true,
+        // Worktree mode: run the agent's tools with their working directory set to
+        // the item's isolated worktree, so its file edits land there instead of the
+        // shared projectRoot. Omitted (undefined) in shared mode ⇒ agent uses the
+        // orchestrator's default working directory exactly as before.
+        ...(deps.itemWorktree ? { workingDirectory: deps.itemWorktree.path } : {}),
+    });
+    record.workItemId = item.id;
+    item.agentId = record.id;
+    item.allAgentIds.push(record.id);
+    item.branch ??= `agent/${item.id}`;
+    const signal = deps.cancellation.start(item.id);
+    deps.agentManager.registerCancellationSignal(record.id, signal);
+    let outcome;
+    try {
+        outcome = await awaitAgentTermination(deps.runtimeBus, deps.agentManager, record.id);
+    }
+    finally {
+        deps.agentManager.releaseCancellationSignal(record.id);
+        deps.cancellation.release(item.id);
+    }
+    const usage = usageFromRecord(outcome.record, deps.priceUsage);
+    if (outcome.status === 'cancelled') {
+        await worktree.cleanup(record.id).catch(() => undefined);
+        return {
+            agentStatus: 'cancelled',
+            result: {
+                itemId: item.id,
+                phaseId: phase.id,
+                agentId: record.id,
+                report: genericReport('cancelled by operator'),
+                gate: { passed: false, results: [] },
+                startedAt,
+                completedAt: Date.now(),
+                usage,
+            },
+        };
+    }
+    if (outcome.status === 'failed') {
+        const transportFailure = isTransportFailureMessage(outcome.record?.error ?? '');
+        const retryLimit = getWrfcTransportRetryLimit(deps.configManager);
+        if (transportFailure && item.transportRetryCount < retryLimit) {
+            item.transportRetryCount += 1;
+            await worktree.cleanup(record.id).catch(() => undefined);
+            await sleep(getWrfcTransportRetryDelayMs(deps.configManager));
+            return runPhase(workstream, item, phase, priorReports, deps);
+        }
+        await worktree.cleanup(record.id).catch(() => undefined);
+        return {
+            agentStatus: 'failed',
+            result: {
+                itemId: item.id,
+                phaseId: phase.id,
+                agentId: record.id,
+                report: genericReport(outcome.record?.error ?? 'agent failed'),
+                gate: { passed: false, results: [] },
+                startedAt,
+                completedAt: Date.now(),
+                usage,
+            },
+        };
+    }
+    const report = parseCompletionReport(outcome.record?.fullOutput ?? '') ?? genericReport(outcome.record?.fullOutput ?? '');
+    if (report.archetype === 'engineer') {
+        const engineerReport = report;
+        for (const path of [...engineerReport.filesCreated, ...engineerReport.filesModified, ...engineerReport.filesDeleted]) {
+            if (!item.touchedPaths.includes(path))
+                item.touchedPaths.push(path);
+        }
+    }
+    const gate = await evaluateGate(workstream, phase, report, deps);
+    let commitExclusion;
+    let commit;
+    if (gate.passed) {
+        const committed = await commitPhaseWork(item, phase, record.id, worktree, deps);
+        commitExclusion = committed.exclusion;
+        commit = committed.commit;
+    }
+    // In worktree mode the item worktree persists across phases (the engine's
+    // integration lane owns its teardown), so only the shared-mode transient
+    // worktree gets cleaned up here.
+    if (!deps.itemWorktree) {
+        await worktree.cleanup(record.id).catch(() => undefined);
+    }
+    return {
+        agentStatus: 'completed',
+        result: {
+            itemId: item.id,
+            phaseId: phase.id,
+            agentId: record.id,
+            report,
+            gate,
+            startedAt,
+            completedAt: Date.now(),
+            usage,
+            ...(commitExclusion ? { commitExclusion } : {}),
+            ...(commit ? { commit } : {}),
+        },
+    };
+}

package/dist/platform/orchestration/proposal-workstream.d.ts

@@ -0,0 +1,56 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Proposal → workstream assembly (BIG-3 item 1) — the final stage of the
+ * WRFC→orchestration migration. `fromPlanProposal()` maps an APPROVED
+ * PlanProposal (platform/core/plan-proposal.ts, produced by the BIG-2 planner
+ * decomposition pipeline) into a `CreateWorkstreamInput` the engine can run
+ * directly, so `/workstream launch` executes the REAL multi-item plan instead
+ * of flattening it through the `fromChainSpec` compat path.
+ *
+ * The mapping, one honest step at a time:
+ *  - ONE work item per proposal work item. The proposal item's `title` becomes
+ *    the work item's title and its `brief` becomes the work item's `task` — the
+ *    prompt/context the phase agents actually run against (the phase-runner
+ *    prepends "Work item: <title>" to review/fix prompts, so both survive into
+ *    the agent's context). The proposal item's id is preserved so provenance,
+ *    dependencies, and fleet nodes all line up 1:1.
+ *  - Every item runs the SAME standard role-phase pipeline — engineer→review,
+ *    the exact `engineerReviewPhases` template `fromChainSpec` uses
+ *    (controller-compat.ts). The only per-assembly parameter is phase
+ *    `capacity`: it defaults to the item count so independent items run
+ *    concurrently (bounded only by their dependencies), where a single compat
+ *    chain stays at capacity 1. Callers may cap concurrency via `opts.capacity`.
+ *  - Inter-item dependencies carry over verbatim: `workItem.dependsOn` (already
+ *    resolved to item ids by assemblePlanProposal) becomes the engine work
+ *    item's `dependsOn`, which the scheduler gates the claim path on (an item
+ *    is not claimable until every dependency reaches 'passed'; see the
+ *    'blocked-dependency' state and applyDependencyGates).
+ *  - Workstream-level provenance records where the plan came from
+ *    (decomposedBy, proposalId, strategy, agent cost/elapsed).
+ *
+ * ASSERT-AT-ASSEMBLY (BIG-3 item 2): even though `assemblePlanProposal` already
+ * rejects dangling dependencies and cycles, this function re-checks both and
+ * THROWS on violation rather than quietly building a broken workstream — a
+ * dangling dependency would gate an item on nothing, and a cycle would deadlock
+ * every item in it forever in 'blocked-dependency'. Belt-and-braces, because a
+ * caller could hand us a hand-built or mutated proposal that never went through
+ * the assembler.
+ */
+import type { ConfigManager } from '../config/manager.js';
+import type { PlanProposal } from '../core/plan-proposal.js';
+import type { CreateWorkstreamInput } from './engine.js';
+export interface FromPlanProposalOptions {
+    /**
+     * Per-phase capacity for the engineer/review phases. Defaults to the number
+     * of work items, so all independent items can run concurrently (dependencies
+     * still gate the rest). Set a lower value to cap concurrency; clamped to at
+     * least 1.
+     */
+    readonly capacity?: number | undefined;
+}
+/**
+ * Assemble a `CreateWorkstreamInput` from an approved multi-item PlanProposal.
+ * See the module doc for the full mapping and the assembly-time assertions.
+ */
+export declare function fromPlanProposal(proposal: PlanProposal, configManager: Pick<ConfigManager, 'get' | 'getCategory'>, opts?: FromPlanProposalOptions): CreateWorkstreamInput;
+//# sourceMappingURL=proposal-workstream.d.ts.map

package/dist/platform/orchestration/proposal-workstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-workstream.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/proposal-workstream.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AA8CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,aAAa,CAAC,EACzD,IAAI,GAAE,uBAA4B,GACjC,qBAAqB,CA8BvB"}

package/dist/platform/orchestration/proposal-workstream.js

@@ -0,0 +1,76 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+import { getWrfcCommitScope } from '../agents/wrfc-config.js';
+import { engineerReviewPhases } from './controller-compat.js';
+/** Throws if any item's `dependsOn` references an unknown item, or if the dependency graph contains a cycle. */
+function assertAcyclicAndResolved(proposal) {
+    const ids = new Set(proposal.workItems.map((wi) => wi.id));
+    const byId = new Map(proposal.workItems.map((wi) => [wi.id, wi]));
+    for (const wi of proposal.workItems) {
+        for (const dep of wi.dependsOn) {
+            if (!ids.has(dep)) {
+                throw new Error(`fromPlanProposal: work item "${wi.title}" (${wi.id}) depends on unknown item id "${dep}" — the proposal is not internally consistent`);
+            }
+        }
+    }
+    // Iterative DFS cycle detection over ids (white/grey/black).
+    const state = new Map();
+    const onCycle = (id) => {
+        const title = byId.get(id)?.title ?? id;
+        throw new Error(`fromPlanProposal: dependency cycle detected involving work item "${title}" (${id}) — cannot assemble a workstream that would deadlock`);
+    };
+    const visit = (start) => {
+        const stack = [{ id: start, deps: byId.get(start)?.dependsOn ?? [], i: 0 }];
+        state.set(start, 'visiting');
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            if (frame.i >= frame.deps.length) {
+                state.set(frame.id, 'done');
+                stack.pop();
+                continue;
+            }
+            const next = frame.deps[frame.i++];
+            const seen = state.get(next);
+            if (seen === 'visiting')
+                onCycle(next);
+            if (seen === 'done')
+                continue;
+            state.set(next, 'visiting');
+            stack.push({ id: next, deps: byId.get(next)?.dependsOn ?? [], i: 0 });
+        }
+    };
+    for (const wi of proposal.workItems) {
+        if (!state.has(wi.id))
+            visit(wi.id);
+    }
+}
+/**
+ * Assemble a `CreateWorkstreamInput` from an approved multi-item PlanProposal.
+ * See the module doc for the full mapping and the assembly-time assertions.
+ */
+export function fromPlanProposal(proposal, configManager, opts = {}) {
+    assertAcyclicAndResolved(proposal);
+    const commitScope = getWrfcCommitScope(configManager);
+    const capacity = Math.max(1, opts.capacity ?? proposal.workItems.length);
+    const items = proposal.workItems.map((wi) => ({
+        id: wi.id,
+        title: wi.title,
+        // The brief IS the actionable prompt context; the engineer phase runs it
+        // verbatim as the item's task, and review/fix phases see it alongside the
+        // title (buildPhaseTask, phase-runner.ts).
+        task: wi.brief,
+        ...(wi.dependsOn.length > 0 ? { dependsOn: [...wi.dependsOn] } : {}),
+    }));
+    const provenance = {
+        ...(proposal.decomposedBy ? { decomposedBy: proposal.decomposedBy } : {}),
+        proposalId: proposal.id,
+        strategy: proposal.strategy,
+        ...(proposal.agentCostUsd !== undefined ? { agentCostUsd: proposal.agentCostUsd } : {}),
+        ...(proposal.elapsedMs !== undefined ? { elapsedMs: proposal.elapsedMs } : {}),
+    };
+    return {
+        title: proposal.task,
+        phases: engineerReviewPhases(commitScope, capacity),
+        items,
+        provenance,
+    };
+}

package/dist/platform/orchestration/scheduler.d.ts

@@ -0,0 +1,64 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Scheduler (Wave 4, wo701) — pure capacity-matching helpers, no side
+ * effects. The hard departure from WrfcController's pairwise
+ * engineer<->reviewer binding (startReview:883/startFix:1042): each tick,
+ * for every phase in ordinal order, free capacity slots (capacity minus
+ * in-flight) are filled from whichever waiting items are queued for that
+ * phase — an item advances the instant ITS gate passes, claimed by
+ * whatever slot happens to be free, never bound to a specific sibling item.
+ */
+import type { Phase, WorkItem, Workstream } from './types.js';
+export declare function sortedPhases(workstream: Workstream): Phase[];
+export declare function firstPhase(workstream: Workstream): Phase | undefined;
+/**
+ * The next phase in ORDINARY forward progression. Deliberately skips
+ * 'fix'-kind phases: a dynamically-inserted fix phase sits at an ordinal
+ * after its review (see engine.ts findOrInsertFixPhase) but is reachable
+ * ONLY via the explicit review-failure re-route, never as "what comes next"
+ * for an item whose review already passed — otherwise a later item that
+ * never needed fixing would wrongly detour through it.
+ */
+export declare function nextPhaseAfter(workstream: Workstream, ordinal: number): Phase | undefined;
+export declare function phaseById(workstream: Workstream, phaseId: string): Phase | undefined;
+/** The nearest preceding review-kind phase — the return target after a dynamically-inserted fix phase's gate passes. Purely structural (survives serialization with zero extra bookkeeping). */
+export declare function reviewPhaseBefore(workstream: Workstream, phase: Phase): Phase | undefined;
+export interface PhaseClaim {
+    readonly item: WorkItem;
+    readonly phase: Phase;
+}
+/**
+ * Whether an item's inter-item dependencies (BIG-3 item 2) are all satisfied,
+ * and — when not — WHY, split into dependencies still in flight vs. ones that
+ * have terminally failed. Pure (no side effects): the engine's per-tick
+ * dependency pre-pass (applyDependencyGates, engine.ts) calls this and applies
+ * the state/blockedReason transition. Missing dependency ids (no item in the
+ * workstream matches) are ignored here — assembly (fromPlanProposal) already
+ * asserts referential integrity, so a dangling id at runtime is treated as
+ * "not blocking" rather than an eternal block.
+ */
+export interface DependencyStatus {
+    /** True when every dependency has reached 'passed' (or there are none). */
+    readonly ready: boolean;
+    /** Titles of dependencies still pending/in flight (neither passed nor failed). */
+    readonly waiting: string[];
+    /** Titles of dependencies that have terminally FAILED — a recoverable block, not a terminal one for the dependent. */
+    readonly failed: string[];
+}
+export declare function dependencyStatus(workstream: Workstream, item: WorkItem): DependencyStatus;
+/**
+ * Which (item, phase) pairs have free capacity to claim RIGHT NOW. Pure —
+ * no side effects, no budget check (the caller applies budget.checkBudget
+ * before actually claiming, since budget is a *decision*, not a capacity
+ * fact this function should own).
+ *
+ * 'blocked-budget' items are deliberately included in the waiting set, not
+ * just 'pending'/'awaiting-capacity': a budget block is a recoverable
+ * decision (see BudgetCeiling/WorkItemState docs, types.ts), never a
+ * capacity fact, so a previously-blocked item must be reconsidered on every
+ * tick the instant a slot is free — the caller's budget.checkBudget call
+ * re-decides it fresh each time, honestly re-blocking it if the ceiling
+ * still refuses.
+ */
+export declare function computeClaims(workstream: Workstream): PhaseClaim[];
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/platform/orchestration/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/scheduler.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE9D,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,KAAK,EAAE,CAE5D;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,KAAK,GAAG,SAAS,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEzF;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEpF;AAED,gMAAgM;AAChM,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAEzF;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,sHAAsH;IACtH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,GAAG,gBAAgB,CAWzF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,EAAE,CAiBlE"}

package/dist/platform/orchestration/scheduler.js

@@ -0,0 +1,73 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export function sortedPhases(workstream) {
+    return [...workstream.phases].sort((a, b) => a.ordinal - b.ordinal);
+}
+export function firstPhase(workstream) {
+    return sortedPhases(workstream)[0];
+}
+/**
+ * The next phase in ORDINARY forward progression. Deliberately skips
+ * 'fix'-kind phases: a dynamically-inserted fix phase sits at an ordinal
+ * after its review (see engine.ts findOrInsertFixPhase) but is reachable
+ * ONLY via the explicit review-failure re-route, never as "what comes next"
+ * for an item whose review already passed — otherwise a later item that
+ * never needed fixing would wrongly detour through it.
+ */
+export function nextPhaseAfter(workstream, ordinal) {
+    return sortedPhases(workstream).find((p) => p.ordinal > ordinal && p.kind !== 'fix');
+}
+export function phaseById(workstream, phaseId) {
+    return workstream.phases.find((p) => p.id === phaseId);
+}
+/** The nearest preceding review-kind phase — the return target after a dynamically-inserted fix phase's gate passes. Purely structural (survives serialization with zero extra bookkeeping). */
+export function reviewPhaseBefore(workstream, phase) {
+    return sortedPhases(workstream).filter((p) => p.ordinal < phase.ordinal && p.kind === 'review').pop();
+}
+export function dependencyStatus(workstream, item) {
+    const waiting = [];
+    const failed = [];
+    for (const depId of item.dependsOn) {
+        const dep = workstream.items.find((i) => i.id === depId);
+        if (!dep)
+            continue; // dangling id — assembly guarantees this can't happen; ignore rather than block forever
+        if (dep.state === 'passed')
+            continue;
+        if (dep.state === 'failed')
+            failed.push(dep.title);
+        else
+            waiting.push(dep.title);
+    }
+    return { ready: waiting.length === 0 && failed.length === 0, waiting, failed };
+}
+/**
+ * Which (item, phase) pairs have free capacity to claim RIGHT NOW. Pure —
+ * no side effects, no budget check (the caller applies budget.checkBudget
+ * before actually claiming, since budget is a *decision*, not a capacity
+ * fact this function should own).
+ *
+ * 'blocked-budget' items are deliberately included in the waiting set, not
+ * just 'pending'/'awaiting-capacity': a budget block is a recoverable
+ * decision (see BudgetCeiling/WorkItemState docs, types.ts), never a
+ * capacity fact, so a previously-blocked item must be reconsidered on every
+ * tick the instant a slot is free — the caller's budget.checkBudget call
+ * re-decides it fresh each time, honestly re-blocking it if the ceiling
+ * still refuses.
+ */
+export function computeClaims(workstream) {
+    const claims = [];
+    for (const phase of sortedPhases(workstream)) {
+        const inFlight = workstream.items.filter((item) => item.currentPhaseId === phase.id && item.state === 'in-phase').length;
+        let free = phase.capacity - inFlight;
+        if (free <= 0)
+            continue;
+        const waiting = workstream.items.filter((item) => item.currentPhaseId === phase.id
+            && (item.state === 'pending' || item.state === 'awaiting-capacity' || item.state === 'blocked-budget'));
+        for (const item of waiting) {
+            if (free <= 0)
+                break;
+            claims.push({ item, phase });
+            free -= 1;
+        }
+    }
+    return claims;
+}