@use-the-fork/spindle 0.0.0-stage → 0.0.2

package/build/SubagentDrivenDevelopment/Policies/FindingPolicy.js

@@ -0,0 +1,53 @@
+import { Service } from "../../Foundation/Service.js";
+import { requiredDeliveryReviewers } from "./RequiredReviewers.js";
+export class FindingPolicy extends Service {
+    reviewPolicy;
+    constructor(app, reviewPolicy) {
+        super(app);
+        this.reviewPolicy = reviewPolicy;
+    }
+    findingBlockers(progress, identity) {
+        return (progress.findings ?? [])
+            .filter((finding) => finding.blocking &&
+            finding.status !== "fixed" &&
+            finding.status !== "dismissed" &&
+            !(finding.status === "deferred" &&
+                finding.requirementsDecision &&
+                progress.requirementsDecisions?.some((decision) => decision.id === finding.requirementsDecision &&
+                    decision.finding === finding.id &&
+                    decision.status === "approved" &&
+                    decision.requirementsSnapshot === identity.requirementsSnapshot) &&
+                (progress.reviewAssignments?.length ?? 0) > 0 &&
+                progress.reviewAssignments.every((assignment) => assignment.status === "submitted" &&
+                    assignment.result === "passed" &&
+                    assignment.snapshot === identity.snapshot &&
+                    assignment.requirementsSnapshot === identity.requirementsSnapshot)))
+            .map((finding) => `Finding ${finding.id} is unresolved and blocking acceptance (severity=${finding.severity}, status=${finding.status}).`);
+    }
+    deliveryFindingBlockers(feature, ledger, delivery, identity) {
+        return (delivery.findings ?? [])
+            .filter((finding) => {
+            if (!finding.blocking || ["fixed", "dismissed"].includes(finding.status))
+                return false;
+            if (finding.status !== "deferred" || !finding.requirementsDecision)
+                return true;
+            const decision = delivery.requirementsDecisions?.find((candidate) => candidate.id === finding.requirementsDecision &&
+                candidate.finding === finding.id &&
+                candidate.status === "approved" &&
+                candidate.requirementsSnapshot === identity.requirementsSnapshot);
+            if (!decision)
+                return true;
+            const required = requiredDeliveryReviewers(ledger, delivery);
+            return required.some(({ agent }) => {
+                const matching = (delivery.reviewAssignments ?? []).filter((assignment) => assignment.agent === agent &&
+                    assignment.status === "submitted" &&
+                    assignment.result === "passed" &&
+                    assignment.snapshot === identity.snapshot &&
+                    assignment.requirementsSnapshot === identity.requirementsSnapshot);
+                return (matching.length !== 1 ||
+                    !!this.reviewPolicy.reviewAssignmentBlocker(feature, delivery, matching[0], identity));
+            });
+        })
+            .map((finding) => `Delivery finding ${finding.id} remains ${finding.status}.`);
+    }
+}

package/build/SubagentDrivenDevelopment/Policies/InputValidation.js

@@ -0,0 +1,36 @@
+import { TICKET_ID, TICKET_CATEGORIES, TRACKER_STATUSES, } from "../Models/Workflow.js";
+export function validateAuthor(author) {
+    if (!author.trim())
+        throw new Error("Author must not be empty.");
+}
+export function validateTicketId(ticket) {
+    if (!TICKET_ID.test(ticket))
+        throw new Error(`Invalid ticket ID: ${ticket}.`);
+}
+export function validateCategory(category) {
+    if (!TICKET_CATEGORIES.includes(category)) {
+        throw new Error(`Invalid ticket category: ${category}.`);
+    }
+}
+export function validateTriageStatus(status) {
+    if (!TRACKER_STATUSES.includes(status)) {
+        throw new Error(`Invalid ticket status: ${status}.`);
+    }
+}
+export function validateCreateOptions({ title, author }) {
+    if (!title.trim())
+        throw new Error("Title must not be empty.");
+    if (!author.trim())
+        throw new Error("Author must not be empty.");
+}
+export function featureSlug(title) {
+    const slug = title
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+    if (!slug)
+        throw new Error("Title must contain at least one letter or number.");
+    return slug;
+}

package/build/SubagentDrivenDevelopment/Policies/ReadinessPolicy.js

@@ -0,0 +1,26 @@
+import { Service } from "../../Foundation/Service.js";
+export class ReadinessPolicy extends Service {
+    ticketRepository;
+    constructor(app, ticketRepository) {
+        super(app);
+        this.ticketRepository = ticketRepository;
+    }
+    evaluate(tickets) {
+        this.ticketRepository.validateDependencyGraph(tickets);
+        const byId = new Map(tickets.map((item) => [item.id, item]));
+        const eligible = tickets.filter((item) => item.status === "open" && !item.blocker);
+        const ready = [];
+        const unready = [];
+        for (const item of eligible) {
+            const pending = item.blocked_by.filter((id) => {
+                const dependencyTicket = byId.get(id);
+                return (!dependencyTicket || dependencyTicket.status !== "closed" || !!dependencyTicket.blocker);
+            });
+            if (pending.length === 0)
+                ready.push(item.id);
+            else
+                unready.push({ ticket: item.id, blockedBy: pending });
+        }
+        return { ready, unready };
+    }
+}

package/build/SubagentDrivenDevelopment/Policies/RequiredReviewers.js

@@ -0,0 +1,12 @@
+export function requiredReviewers(policy, requirements = []) {
+    return [
+        ...policy.map((agent) => ({ agent })),
+        ...requirements.map(({ agent, details }) => ({ agent, details })),
+    ];
+}
+export function requiredTicketReviewers(ledger, progress) {
+    return requiredReviewers(ledger.reviewPolicy.ticket, progress.reviewRequirements ?? []);
+}
+export function requiredDeliveryReviewers(ledger, progress) {
+    return requiredReviewers(ledger.reviewPolicy.delivery, progress.reviewRequirements ?? []);
+}

package/build/SubagentDrivenDevelopment/Policies/ReviewPolicy.js

@@ -0,0 +1,87 @@
+import { Service } from "../../Foundation/Service.js";
+export class ReviewPolicy extends Service {
+    gitEvidence;
+    reportEvidence;
+    constructor(app, gitEvidence, reportEvidence) {
+        super(app);
+        this.gitEvidence = gitEvidence;
+        this.reportEvidence = reportEvidence;
+    }
+    reviewAssignmentBlocker(feature, progress, assignment, identity) {
+        if (assignment.status !== "pending") {
+            try {
+                const currentDigest = this.reportEvidence.readReportDigest(feature, assignment.report);
+                if (currentDigest !== assignment.reportSha256) {
+                    return `The registered review report for assignment ${assignment.id} changed after submission.`;
+                }
+            }
+            catch {
+                return `The registered review report for assignment ${assignment.id} is missing or unavailable.`;
+            }
+        }
+        const snapshotBlocker = this.reviewSnapshotBlocker(feature, progress, assignment, identity);
+        if (snapshotBlocker)
+            return snapshotBlocker;
+        if (assignment.status === "pending")
+            return undefined;
+        if (assignment.result !== "passed") {
+            return `Review assignment ${assignment.id} is ${assignment.result}.${assignment.details ? ` Details: ${assignment.details}` : ""}`;
+        }
+        if (assignment.noFindings !== true && (assignment.findingIds?.length ?? 0) === 0) {
+            return `Review assignment ${assignment.id} has no explicit findings declaration.`;
+        }
+        return undefined;
+    }
+    reviewSnapshotBlocker(feature, progress, assignment, identity) {
+        const integratedEvidence = assignment.scope !== "delivery" &&
+            this.gitEvidence.integrationPreservesEvidence(progress, identity) &&
+            assignment.snapshot === progress.acceptedEvidence?.snapshot &&
+            assignment.codeSnapshot === progress.acceptedEvidence?.codeSnapshot &&
+            assignment.requirementsSnapshot === progress.acceptedEvidence?.requirementsSnapshot &&
+            JSON.stringify(assignment.inventory) === JSON.stringify(progress.acceptedEvidence?.files);
+        if (!integratedEvidence &&
+            (assignment.snapshot !== identity.snapshot ||
+                assignment.codeSnapshot !== identity.codeSnapshot ||
+                assignment.requirementsSnapshot !== identity.requirementsSnapshot)) {
+            return `Review assignment ${assignment.id} is stale for the current ticket snapshot.`;
+        }
+        if (!progress.baseSha)
+            return "Review assignment has no recorded Git baseline.";
+        let inventory;
+        try {
+            inventory = this.gitEvidence.changedPaths(progress.baseSha);
+        }
+        catch (error) {
+            return `Review inventory cannot be revalidated: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        if (JSON.stringify(inventory) !== JSON.stringify(assignment.inventory)) {
+            return `Review assignment ${assignment.id} no longer matches the frozen Git inventory.`;
+        }
+        if (assignment.status === "pending")
+            return undefined;
+        try {
+            const currentDigest = this.reportEvidence.readReportDigest(feature, assignment.report);
+            if (currentDigest !== assignment.reportSha256) {
+                return `The registered review report for assignment ${assignment.id} changed after submission.`;
+            }
+        }
+        catch {
+            return `The registered review report for assignment ${assignment.id} is missing or unavailable.`;
+        }
+        return undefined;
+    }
+    reviewReportIntegrityBlocker(feature, assignment) {
+        if (assignment.status !== "submitted" || !assignment.reportSha256) {
+            return "Review report was not submitted.";
+        }
+        try {
+            if (this.reportEvidence.readReportDigest(feature, assignment.report) !== assignment.reportSha256) {
+                return "Review report content changed after submission.";
+            }
+        }
+        catch {
+            return "Review report is missing or unavailable.";
+        }
+        return undefined;
+    }
+}

package/build/SubagentDrivenDevelopment/Policies/WorkflowPolicy.js

@@ -0,0 +1,85 @@
+import { Service } from "../../Foundation/Service.js";
+export class WorkflowPolicy extends Service {
+    constructor(app) {
+        super(app);
+    }
+    nextAction(progress, blocker) {
+        if (progress.adjudication?.status === "pending")
+            return "adjudicate";
+        if (progress.execution === "unstarted")
+            return "claim";
+        if (progress.execution === "claimed") {
+            return progress.owner && progress.baseSha ? "implement" : "resolve-claim-blocker";
+        }
+        if (progress.execution === "implementing") {
+            if (!progress.assignment)
+                return "resolve-assignment-blocker";
+            if (progress.assignment.status === "submitted") {
+                if (blocker?.startsWith("Required check "))
+                    return "record-current-checks";
+                return blocker ? "restore-implementation-report" : "review";
+            }
+            return "await-implementation-report";
+        }
+        if (progress.execution === "reviewing") {
+            if (blocker?.startsWith("Finding "))
+                return "resolve-findings";
+            if (blocker?.startsWith("Required check "))
+                return "record-current-checks";
+            const reviews = progress.reviewAssignments ?? [];
+            if (reviews.length > 0) {
+                if (blocker?.startsWith("The registered review report"))
+                    return "restore-review-report";
+                if (blocker)
+                    return "resolve-review-blocker";
+                if (reviews.some((assignment) => assignment.status === "pending")) {
+                    return "await-review-report";
+                }
+                if (reviews.some((assignment) => assignment.result !== "passed")) {
+                    return "resolve-review-result";
+                }
+                return "accept";
+            }
+            return blocker ? "restore-implementation-report" : "review";
+        }
+        if (progress.execution === "changes-requested") {
+            if ((progress.findings ?? []).some((finding) => finding.status === "confirmed")) {
+                return "correct";
+            }
+            if (blocker?.startsWith("Finding "))
+                return "adjudicate-findings";
+            return (progress.correctionAttempts?.length ?? 0) > 0
+                ? "correct"
+                : "controller-correction-decision";
+        }
+        if (progress.execution === "accepted")
+            return blocker ? "resolve-check-blocker" : "integrate";
+        if (progress.execution === "integrated")
+            return blocker ? "resolve-check-blocker" : "complete";
+        return "resolve-blocker";
+    }
+    requireProgress(ledger, ticket) {
+        const progress = ledger.tickets.find((item) => item.id === ticket);
+        if (!progress)
+            throw new Error(`Ticket ${ticket} has no ledger execution record.`);
+        return progress;
+    }
+    acceptedInventory(progress, ticketId) {
+        const corrective = progress.correctionAttempts?.at(-1)?.reviewAssignments ?? [];
+        const assignments = corrective.length > 0 ? corrective : (progress.reviewAssignments ?? []);
+        if (assignments.length === 0 ||
+            assignments.some((assignment) => assignment.status !== "submitted")) {
+            throw new Error(`Ticket ${ticketId} has no complete frozen review inventory.`);
+        }
+        const inventory = assignments[0].inventory;
+        if (assignments.some((assignment) => JSON.stringify(assignment.inventory) !== JSON.stringify(inventory))) {
+            throw new Error(`Ticket ${ticketId} review assignments disagree on the accepted inventory.`);
+        }
+        return [...inventory];
+    }
+    assertDeliveryOpen(delivery) {
+        if (delivery.finished) {
+            throw new Error("Delivery is finished; final checks cannot be changed.");
+        }
+    }
+}

package/build/SubagentDrivenDevelopment/Services/AssignmentService.js

@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import matter from "gray-matter";
+import { Service } from "../../Foundation/Service.js";
+import { lstatIfPresent } from "../Persistence/FileSystem.js";
+import { validateAuthor, validateTicketId, } from "../Policies/InputValidation.js";
+export class AssignmentService extends Service {
+    gitEvidence;
+    reportEvidence;
+    ticketRepository;
+    ledgerRepository;
+    workspaceTransaction;
+    assignmentPolicy;
+    checkPolicy;
+    reviewPolicy;
+    workflowPolicy;
+    featureInspectionService;
+    constructor(app, gitEvidence, reportEvidence, ticketRepository, ledgerRepository, workspaceTransaction, assignmentPolicy, checkPolicy, reviewPolicy, workflowPolicy, featureInspectionService) {
+        super(app);
+        this.gitEvidence = gitEvidence;
+        this.reportEvidence = reportEvidence;
+        this.ticketRepository = ticketRepository;
+        this.ledgerRepository = ledgerRepository;
+        this.workspaceTransaction = workspaceTransaction;
+        this.assignmentPolicy = assignmentPolicy;
+        this.checkPolicy = checkPolicy;
+        this.reviewPolicy = reviewPolicy;
+        this.workflowPolicy = workflowPolicy;
+        this.featureInspectionService = featureInspectionService;
+    }
+    claim(options) {
+        validateTicketId(options.ticket);
+        validateAuthor(options.author);
+        const feature = this.featureInspectionService.resolveFeature(options.spec);
+        return this.workspaceTransaction.run(feature.workspace, () => {
+            const ledger = this.ledgerRepository.readLedger(feature);
+            const tickets = this.ticketRepository.readTickets(feature.workspace);
+            this.ticketRepository.validateDependencyGraph(tickets);
+            const ticket = this.ticketRepository.requireTicket(tickets, options.ticket);
+            const progress = this.workflowPolicy.requireProgress(ledger, options.ticket);
+            if (progress.execution !== "unstarted") {
+                throw new Error(`Ticket ${options.ticket} is already owned or has progressed to ${progress.execution}.`);
+            }
+            if (ticket.status !== "open" || ticket.blocker) {
+                throw new Error(`Ticket ${options.ticket} is not open and unblocked.`);
+            }
+            const ticketsById = new Map(tickets.map((item) => [item.id, item]));
+            const unmet = ticket.blocked_by.filter((dependency) => {
+                const dependencyTicket = ticketsById.get(dependency);
+                return (!dependencyTicket || dependencyTicket.status !== "closed" || !!dependencyTicket.blocker);
+            });
+            if (unmet.length > 0) {
+                throw new Error(`Ticket ${options.ticket} has open dependencies: ${unmet.join(", ")}.`);
+            }
+            const baseSha = this.gitEvidence.cleanGitBaseline(feature);
+            progress.execution = "claimed";
+            progress.status = "in-progress";
+            progress.owner = options.author.trim();
+            progress.baseSha = baseSha;
+            ledger.delivery.baseSha ??= baseSha;
+            const identity = this.gitEvidence.contentIdentity(feature, ticket, baseSha, progress.checks);
+            const afterTicket = matter.stringify(this.ticketRepository.appendAudit(ticket.body, options.author, `Claimed from clean Git baseline ${baseSha}.`), this.ticketRepository.metadata(ticket));
+            this.workspaceTransaction.writeWorkflowState(feature, ticket, afterTicket, ledger);
+            return {
+                ticket: options.ticket,
+                execution: "claimed",
+                owner: options.author.trim(),
+                baseSha,
+                ...identity,
+            };
+        });
+    }
+    implement(options) {
+        validateTicketId(options.ticket);
+        validateAuthor(options.author);
+        const feature = this.featureInspectionService.resolveFeature(options.spec);
+        return this.workspaceTransaction.run(feature.workspace, () => {
+            const ledger = this.ledgerRepository.readLedger(feature);
+            const ticket = this.ticketRepository.requireTicket(this.ticketRepository.readTickets(feature.workspace), options.ticket);
+            const progress = this.workflowPolicy.requireProgress(ledger, options.ticket);
+            const identity = this.gitEvidence.contentIdentity(feature, ticket, progress.baseSha, progress.checks);
+            if (progress.execution === "implementing" && progress.assignment) {
+                if (progress.owner !== options.author.trim()) {
+                    throw new Error("Controller ownership changed; resume and confirm the handoff first.");
+                }
+                return {
+                    ticket: options.ticket,
+                    execution: "implementing",
+                    assignment: progress.assignment,
+                    ...identity,
+                };
+            }
+            if (progress.execution !== "claimed" || !progress.baseSha || !progress.owner) {
+                throw new Error(`Ticket ${options.ticket} must be claimed before implementation dispatch.`);
+            }
+            if (progress.owner !== options.author.trim()) {
+                throw new Error("Only the recorded controller may dispatch implementation.");
+            }
+            const report = join(feature.workspace, "reports", `${options.ticket}-implementation.md`);
+            this.reportEvidence.assertReportPath(feature, report, false);
+            if (lstatIfPresent(report)) {
+                throw new Error(`Assigned report already exists and was preserved: ${report}.`);
+            }
+            const assignment = {
+                id: randomUUID(),
+                role: "implementation",
+                action: "implement",
+                controller: options.author.trim(),
+                report,
+                requestedAt: new Date().toISOString(),
+                status: "pending",
+                handoffs: [],
+            };
+            progress.execution = "implementing";
+            progress.assignment = assignment;
+            const afterTicket = matter.stringify(this.ticketRepository.appendAudit(ticket.body, options.author, `Implementation assignment ${assignment.id} recorded; role=implementation; report=${report}. No agent was launched.`), this.ticketRepository.metadata(ticket));
+            this.workspaceTransaction.writeWorkflowState(feature, ticket, afterTicket, ledger);
+            return { ticket: options.ticket, execution: "implementing", assignment, ...identity };
+        });
+    }
+    resume(options) {
+        if (options.scope === "delivery") {
+            if (options.ticket)
+                throw new Error("--ticket and --scope delivery are mutually exclusive.");
+            return this.deliveryResume(options);
+        }
+        if (options.scope !== undefined)
+            throw new Error("--scope must be 'delivery'.");
+        if (!options.ticket)
+            throw new Error("resume requires --ticket or --scope delivery.");
+        validateTicketId(options.ticket);
+        validateAuthor(options.author);
+        const feature = this.featureInspectionService.resolveFeature(options.spec);
+        return this.workspaceTransaction.run(feature.workspace, () => {
+            const ledger = this.ledgerRepository.readLedger(feature);
+            const ticket = this.ticketRepository.requireTicket(this.ticketRepository.readTickets(feature.workspace), options.ticket);
+            const progress = this.workflowPolicy.requireProgress(ledger, options.ticket);
+            let handoffRecorded = false;
+            if (progress.owner && progress.owner !== options.author.trim()) {
+                if (!options.confirmHandoff) {
+                    throw new Error(`Ownership handoff from ${progress.owner} to ${options.author.trim()} requires --confirm-handoff after the previous controller has stopped editing.`);
+                }
+                const previousOwner = progress.owner;
+                progress.owner = options.author.trim();
+                if (progress.assignment) {
+                    progress.assignment.controller = options.author.trim();
+                    progress.assignment.handoffs.push({
+                        at: new Date().toISOString(),
+                        from: previousOwner,
+                        to: options.author.trim(),
+                        confirmedStopped: true,
+                    });
+                }
+                const afterTicket = matter.stringify(this.ticketRepository.appendAudit(ticket.body, options.author, `Controller handoff from ${previousOwner} to ${options.author.trim()} confirmed after the previous controller stopped editing.`), this.ticketRepository.metadata(ticket));
+                this.workspaceTransaction.writeWorkflowState(feature, ticket, afterTicket, ledger);
+                handoffRecorded = true;
+            }
+            const currentTicket = this.ticketRepository.requireTicket(this.ticketRepository.readTickets(feature.workspace), options.ticket);
+            const identity = this.gitEvidence.contentIdentity(feature, currentTicket, progress.baseSha, progress.checks);
+            const reviewAssignments = progress.assignment?.action === "correct"
+                ? ((progress.correctionAttempts ?? []).find((attempt) => attempt.assignmentId === progress.assignment?.id)?.reviewAssignments ?? [])
+                : progress.reviewAssignments;
+            const resumeProgress = reviewAssignments === undefined ? progress : { ...progress, reviewAssignments };
+            const reviewBlocker = (reviewAssignments ?? [])
+                .map((assignment) => this.reviewPolicy.reviewAssignmentBlocker(feature, progress, assignment, identity))
+                .find((reason) => reason !== undefined);
+            const blocker = this.assignmentPolicy.resumeBlocker(feature, progress) ??
+                reviewBlocker ??
+                this.checkPolicy.checkBlockers(feature, currentTicket, progress, identity)[0];
+            return {
+                ticket: options.ticket,
+                gate: progress.execution,
+                nextAction: this.workflowPolicy.nextAction(resumeProgress, blocker),
+                ...(progress.owner ? { owner: progress.owner } : {}),
+                ...(progress.assignment ? { assignment: progress.assignment } : {}),
+                correctionAttempts: progress.correctionAttempts ?? [],
+                ...(progress.adjudication ? { adjudication: progress.adjudication } : {}),
+                ...(reviewAssignments ? { reviewAssignments } : {}),
+                ...(handoffRecorded ? { handoffRecorded: true } : {}),
+                ...(blocker ? { blocker } : {}),
+                ...identity,
+            };
+        });
+    }
+    deliveryResume(options) {
+        validateAuthor(options.author);
+        const feature = this.featureInspectionService.resolveFeature(options.spec);
+        return this.workspaceTransaction.run(feature.workspace, () => {
+            const ledger = this.ledgerRepository.readLedger(feature);
+            const delivery = ledger.delivery;
+            let handoffRecorded = false;
+            if (delivery.owner && delivery.owner !== options.author.trim()) {
+                if (!options.confirmHandoff) {
+                    throw new Error(`Ownership handoff from ${delivery.owner} to ${options.author.trim()} requires --confirm-handoff after the previous controller has stopped editing.`);
+                }
+                const previousOwner = delivery.owner;
+                delivery.owner = options.author.trim();
+                if (delivery.assignment) {
+                    delivery.assignment.controller = options.author.trim();
+                    delivery.assignment.handoffs.push({
+                        at: new Date().toISOString(),
+                        from: previousOwner,
+                        to: options.author.trim(),
+                        confirmedStopped: true,
+                    });
+                }
+                delivery.history.push({
+                    at: new Date().toISOString(),
+                    author: options.author.trim(),
+                    action: `controller-handoff:${previousOwner}`,
+                });
+                this.workspaceTransaction.writeLedger(feature, ledger);
+                handoffRecorded = true;
+            }
+            const tickets = this.ticketRepository.readTickets(feature.workspace);
+            const identity = this.gitEvidence.deliveryIdentity(feature, ledger, tickets);
+            const completion = delivery.finished
+                ? this.featureInspectionService.deliveryStatus(feature, ledger, tickets)
+                : undefined;
+            const checkBlocker = this.checkPolicy.deliveryCheckBlockers(delivery, identity)[0];
+            let blocker = completion?.action === "completion-invalidated"
+                ? `Finished delivery completion is invalidated: ${completion.blockers.join(" ")}`
+                : delivery.adjudication?.status === "pending"
+                    ? `Delivery correction is paused for adjudication (${delivery.adjudication.reason}).`
+                    : checkBlocker;
+            let nextAction;
+            if (completion) {
+                nextAction = completion.action;
+            }
+            else if (delivery.adjudication?.status === "pending") {
+                nextAction = "adjudicate";
+            }
+            else if (delivery.assignment &&
+                ["pending", "unavailable"].includes(delivery.assignment.status)) {
+                nextAction = "await-implementation-report";
+            }
+            else if (delivery.reviewAssignments?.some((assignment) => assignment.status === "pending")) {
+                nextAction = "await-review-report";
+            }
+            else if (checkBlocker) {
+                nextAction = "record-final-checks";
+            }
+            else if (delivery.execution === "changes-requested") {
+                nextAction = "correct";
+            }
+            else if (delivery.execution === "reviewing") {
+                nextAction = "review-or-finish";
+            }
+            else {
+                nextAction = "review";
+            }
+            return {
+                scope: "delivery",
+                gate: delivery.execution,
+                nextAction,
+                ...(delivery.owner ? { owner: delivery.owner } : {}),
+                ...(delivery.assignment ? { assignment: delivery.assignment } : {}),
+                correctionAttempts: delivery.correctionAttempts ?? [],
+                ...(delivery.adjudication ? { adjudication: delivery.adjudication } : {}),
+                ...(delivery.reviewAssignments ? { reviewAssignments: delivery.reviewAssignments } : {}),
+                ...(handoffRecorded ? { handoffRecorded: true } : {}),
+                ...(blocker ? { blocker } : {}),
+                retrospectiveRequired: ledger.retrospectiveRequired,
+                finished: !!delivery.finished,
+                ...identity,
+            };
+        });
+    }
+}