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

package/build/SubagentDrivenDevelopment/Services/DeliveryCorrectionService.js

@@ -0,0 +1,253 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Service } from "../../Foundation/Service.js";
+import { lstatIfPresent } from "../Persistence/FileSystem.js";
+import { validateAuthor } from "../Policies/InputValidation.js";
+export class DeliveryCorrectionService extends Service {
+    gitEvidence;
+    reportEvidence;
+    ticketRepository;
+    ledgerRepository;
+    workspaceTransaction;
+    featureInspectionService;
+    constructor(app, gitEvidence, reportEvidence, ticketRepository, ledgerRepository, workspaceTransaction, featureInspectionService) {
+        super(app);
+        this.gitEvidence = gitEvidence;
+        this.reportEvidence = reportEvidence;
+        this.ticketRepository = ticketRepository;
+        this.ledgerRepository = ledgerRepository;
+        this.workspaceTransaction = workspaceTransaction;
+        this.featureInspectionService = featureInspectionService;
+    }
+    deliveryCorrect(options) {
+        validateAuthor(options.author);
+        const findingIds = [...new Set((options.findings ?? []).map((finding) => finding.trim()))];
+        if (findingIds.some((finding) => !/^F-\d{4,}$/.test(finding))) {
+            throw new Error("--findings must contain canonical finding IDs.");
+        }
+        const objective = options.details.trim();
+        if (!objective)
+            throw new Error("--details must not be empty.");
+        if (options.decision !== undefined && !["continue", "pause"].includes(options.decision)) {
+            throw new Error("--decision must be 'continue' or 'pause'.");
+        }
+        if (options.decision !== "pause" && findingIds.length === 0 && !options.checkFailure?.trim()) {
+            throw new Error("correct requires actionable --findings or a non-mechanical --check-failure.");
+        }
+        if (options.decision === "pause") {
+            if (![
+                "no-progress",
+                "repeated-failure",
+                "recurring-blocker",
+                "requirements-disagreement",
+                "worker-blocked",
+            ].includes(options.reason ?? "")) {
+                throw new Error("--reason is required for a pause and must identify the adjudication category.");
+            }
+            if (options.assessment || options.assessmentResult) {
+                throw new Error("--assessment is only valid with --decision continue.");
+            }
+        }
+        else if (options.reason) {
+            throw new Error("--reason is only valid with --decision pause.");
+        }
+        if (options.decision === "continue" &&
+            (!options.assessment?.trim() || options.assessmentResult !== "productive")) {
+            throw new Error("--assessment and --assessment-result productive are required with --decision continue.");
+        }
+        if (options.assessmentResult && options.decision !== "continue") {
+            throw new Error("--assessment-result is only valid with --decision continue.");
+        }
+        const feature = this.featureInspectionService.resolveFeature(options.spec);
+        return this.workspaceTransaction.run(feature.workspace, () => {
+            const ledger = this.ledgerRepository.readLedger(feature);
+            const delivery = ledger.delivery;
+            if (delivery.owner !== options.author.trim()) {
+                throw new Error("Only the recorded delivery controller may dispatch a correction.");
+            }
+            const attempts = (delivery.correctionAttempts ??= []);
+            const identity = this.gitEvidence.deliveryIdentity(feature, ledger, this.ticketRepository.readTickets(feature.workspace));
+            const currentFailedCheck = (delivery.checks?.records ?? []).some((record) => record.snapshot === identity.snapshot &&
+                record.codeSnapshot === identity.codeSnapshot &&
+                record.requirementsSnapshot === identity.requirementsSnapshot &&
+                record.result === "failed");
+            if (options.decision === "pause") {
+                if (delivery.execution === "implementing" && delivery.assignment?.status !== "submitted") {
+                    throw new Error("A pending delivery implementation assignment must be resumed, not paused.");
+                }
+                if (attempts.length === 0 &&
+                    delivery.execution !== "changes-requested" &&
+                    !currentFailedCheck) {
+                    throw new Error("Adjudication pause requires a recorded failed correction, check, or review.");
+                }
+                const adjudication = {
+                    status: "pending",
+                    reason: options.reason,
+                    details: objective,
+                    recordedAt: new Date().toISOString(),
+                    recordedBy: options.author.trim(),
+                };
+                if (delivery.adjudication?.status === "pending" &&
+                    delivery.adjudication.reason === adjudication.reason &&
+                    delivery.adjudication.details === adjudication.details &&
+                    delivery.adjudication.recordedBy === adjudication.recordedBy) {
+                    return {
+                        scope: "delivery",
+                        execution: delivery.execution,
+                        adjudication: delivery.adjudication,
+                        paused: true,
+                        idempotent: true,
+                        ...identity,
+                    };
+                }
+                delivery.adjudication = adjudication;
+                delivery.execution = "changes-requested";
+                delivery.history.push({
+                    at: adjudication.recordedAt,
+                    author: adjudication.recordedBy,
+                    action: `correction-paused:${adjudication.reason}`,
+                });
+                this.workspaceTransaction.writeLedger(feature, ledger);
+                return {
+                    scope: "delivery",
+                    execution: delivery.execution,
+                    adjudication,
+                    paused: true,
+                    ...identity,
+                };
+            }
+            if (delivery.execution === "implementing" &&
+                delivery.assignment?.action === "correct" &&
+                delivery.assignment.status !== "submitted" &&
+                delivery.assignment.findingIds?.join(",") === findingIds.join(",") &&
+                delivery.assignment.checkFailure === options.checkFailure?.trim() &&
+                delivery.assignment.objective === objective) {
+                const current = attempts.find((attempt) => attempt.number === delivery.assignment?.attempt);
+                if (!current)
+                    throw new Error("Delivery correction assignment has no persisted attempt record.");
+                return {
+                    scope: "delivery",
+                    execution: "implementing",
+                    attempt: current,
+                    assignment: delivery.assignment,
+                    idempotent: true,
+                    ...identity,
+                };
+            }
+            if (delivery.adjudication?.status === "pending" && options.decision !== "continue") {
+                throw new Error(`Delivery correction is paused for adjudication (${delivery.adjudication.reason}).`);
+            }
+            if (delivery.execution !== "changes-requested" && !currentFailedCheck) {
+                throw new Error("Delivery must have a failed aggregate review or current failed check before correction.");
+            }
+            if (delivery.assignment?.action === "correct" && delivery.assignment.status !== "submitted") {
+                throw new Error("The current delivery correction assignment must be resumed, not replaced.");
+            }
+            if (attempts.length > 0 || delivery.adjudication?.status === "pending") {
+                if (options.decision !== "continue" || !options.assessment?.trim()) {
+                    throw new Error("A subsequent delivery correction requires --decision continue and --assessment.");
+                }
+                const previous = attempts.at(-1);
+                previous.progressAssessment = {
+                    decision: "continue",
+                    result: "productive",
+                    details: options.assessment.trim(),
+                    recordedAt: new Date().toISOString(),
+                    recordedBy: options.author.trim(),
+                };
+            }
+            else if (options.decision || options.assessment) {
+                throw new Error("The first delivery correction does not accept a continuation assessment.");
+            }
+            for (const id of findingIds) {
+                if (!delivery.findings?.some((finding) => finding.id === id && finding.status === "confirmed")) {
+                    throw new Error(`Delivery finding ${id} is not an actionable unresolved finding.`);
+                }
+            }
+            const checkFailure = options.checkFailure?.trim();
+            if (checkFailure) {
+                const record = (delivery.checks?.records ?? [])
+                    .filter((candidate) => candidate.command === checkFailure &&
+                    candidate.snapshot === identity.snapshot &&
+                    candidate.codeSnapshot === identity.codeSnapshot &&
+                    candidate.requirementsSnapshot === identity.requirementsSnapshot)
+                    .at(-1);
+                if (!record || record.result !== "failed") {
+                    throw new Error(`Delivery check failure '${checkFailure}' must be an explicitly recorded failed check for the current snapshot.`);
+                }
+            }
+            const number = attempts.length + 1;
+            const requestedAt = new Date().toISOString();
+            const assignment = {
+                id: randomUUID(),
+                role: "implementation",
+                action: "correct",
+                controller: options.author.trim(),
+                attempt: number,
+                findingIds,
+                ...(checkFailure ? { checkFailure } : {}),
+                objective,
+                report: join(feature.workspace, "reports", `final-round-${number}-fix.md`),
+                requestedAt,
+                status: "pending",
+                handoffs: [],
+            };
+            this.reportEvidence.assertReportPath(feature, assignment.report, false);
+            if (lstatIfPresent(assignment.report)) {
+                throw new Error(`Assigned report already exists and was preserved: ${assignment.report}.`);
+            }
+            const attempt = {
+                number,
+                findingIds,
+                ...(checkFailure ? { checkFailure } : {}),
+                objective,
+                startedAt: requestedAt,
+                startedBy: options.author.trim(),
+                assignmentId: assignment.id,
+                assignment,
+                ...(delivery.assignment ? { priorAssignment: delivery.assignment } : {}),
+                ...(checkFailure
+                    ? {
+                        checks: (delivery.checks?.records ?? []).filter((record) => record.snapshot === identity.snapshot &&
+                            record.codeSnapshot === identity.codeSnapshot &&
+                            record.requirementsSnapshot === identity.requirementsSnapshot),
+                    }
+                    : {}),
+            };
+            if (attempts.length > 0 || delivery.adjudication?.status === "pending") {
+                attempt.progressAssessment = {
+                    decision: "continue",
+                    result: "productive",
+                    details: options.assessment.trim(),
+                    recordedAt: new Date().toISOString(),
+                    recordedBy: options.author.trim(),
+                };
+            }
+            attempts.push(attempt);
+            delivery.assignment = assignment;
+            delivery.execution = "implementing";
+            if (delivery.adjudication?.status === "pending") {
+                delivery.adjudication.status = "resolved";
+                delivery.adjudication.resolution = {
+                    details: options.assessment.trim(),
+                    recordedAt: new Date().toISOString(),
+                    recordedBy: options.author.trim(),
+                };
+            }
+            delivery.history.push({
+                at: requestedAt,
+                author: options.author.trim(),
+                action: `correction-dispatched:${number}`,
+            });
+            this.workspaceTransaction.writeLedger(feature, ledger);
+            return {
+                scope: "delivery",
+                execution: "implementing",
+                attempt,
+                assignment,
+                ...(delivery.adjudication ? { adjudication: delivery.adjudication } : {}),
+                ...identity,
+            };
+        });
+    }
+}

package/build/SubagentDrivenDevelopment/Services/DeliveryFindingService.js

@@ -0,0 +1,302 @@
+import { isAbsolute, resolve } from "node:path";
+import { Service } from "../../Foundation/Service.js";
+import { validateTicketId } from "../Policies/InputValidation.js";
+import { validateAuthor } from "../Policies/InputValidation.js";
+import { requiredDeliveryReviewers } from "../Policies/RequiredReviewers.js";
+export class DeliveryFindingService extends Service {
+    gitEvidence;
+    reportEvidence;
+    ticketRepository;
+    ledgerRepository;
+    workspaceTransaction;
+    checkPolicy;
+    findingPolicy;
+    reviewPolicy;
+    featureInspectionService;
+    constructor(app, gitEvidence, reportEvidence, ticketRepository, ledgerRepository, workspaceTransaction, checkPolicy, findingPolicy, reviewPolicy, featureInspectionService) {
+        super(app);
+        this.gitEvidence = gitEvidence;
+        this.reportEvidence = reportEvidence;
+        this.ticketRepository = ticketRepository;
+        this.ledgerRepository = ledgerRepository;
+        this.workspaceTransaction = workspaceTransaction;
+        this.checkPolicy = checkPolicy;
+        this.findingPolicy = findingPolicy;
+        this.reviewPolicy = reviewPolicy;
+        this.featureInspectionService = featureInspectionService;
+    }
+    deliveryFindingCreate(options) {
+        validateAuthor(options.author);
+        if (!["high", "medium", "low"].includes(options.severity)) {
+            throw new Error(`Invalid finding severity: ${options.severity}.`);
+        }
+        if (options.blocking === options.nonBlocking) {
+            throw new Error("Choose exactly one of --blocking or --non-blocking.");
+        }
+        if (!options.summary.trim())
+            throw new Error("Finding summary must not be empty.");
+        if (!options.details.trim())
+            throw new Error("Finding details must not be empty.");
+        if (options.relatedTicket)
+            validateTicketId(options.relatedTicket);
+        if (options.link !== undefined && options.relatedTicket !== undefined) {
+            throw new Error("--related-ticket cannot be combined with --link.");
+        }
+        if (!/^[0-9a-f]{64}$/i.test(options.snapshot)) {
+            throw new Error("Finding snapshot must be a CLI-returned content snapshot.");
+        }
+        const feature = this.featureInspectionService.resolveFeature(options.spec);
+        return this.workspaceTransaction.run(feature.workspace, () => {
+            const ledger = this.ledgerRepository.readLedger(feature);
+            const delivery = ledger.delivery;
+            if (!delivery.owner || delivery.owner !== options.author.trim()) {
+                throw new Error("Only the current delivery controller may register findings.");
+            }
+            const report = options.source
+                ? isAbsolute(options.source)
+                    ? resolve(options.source)
+                    : resolve(feature.workspace, options.source)
+                : "";
+            const assignment = delivery.reviewAssignments?.find((candidate) => candidate.report === report &&
+                candidate.snapshot === options.snapshot &&
+                candidate.scope === "delivery");
+            if (!assignment) {
+                throw new Error("Finding source report and snapshot must match a frozen delivery review assignment.");
+            }
+            if (assignment.status === "submitted") {
+                throw new Error("Findings must be registered before submitting the delivery assignment.");
+            }
+            const identity = this.gitEvidence.deliveryIdentity(feature, ledger, this.ticketRepository.readTickets(feature.workspace));
+            if (options.relatedTicket) {
+                const relatedTicket = ledger.tickets.find((item) => item.id === options.relatedTicket);
+                if (!relatedTicket) {
+                    throw new Error(`Related ticket not found: ${options.relatedTicket}.`);
+                }
+            }
+            const stale = this.reviewPolicy.reviewSnapshotBlocker(feature, delivery, assignment, identity);
+            if (stale)
+                throw new Error(stale);
+            this.reportEvidence.readReportDigest(feature, report);
+            const source = {
+                report,
+                snapshot: options.snapshot,
+                author: options.author.trim(),
+                summary: options.summary.trim(),
+                details: options.details.trim(),
+            };
+            const findings = delivery.findings ?? [];
+            if (options.link !== undefined) {
+                const canonical = findings.find((finding) => finding.id === options.link);
+                if (!canonical)
+                    throw new Error(`Canonical delivery finding not found: ${options.link}.`);
+                const prior = canonical.provenance.find((item) => item.report === source.report && item.snapshot === source.snapshot);
+                if (prior) {
+                    if (prior.author !== source.author ||
+                        prior.summary !== source.summary ||
+                        prior.details !== source.details) {
+                        throw new Error("This report and snapshot are already linked with different details.");
+                    }
+                    return { scope: "delivery", finding: canonical, idempotent: true, ...identity };
+                }
+                canonical.provenance.push(source);
+                canonical.history.push({
+                    at: new Date().toISOString(),
+                    author: options.author.trim(),
+                    action: "observation-linked",
+                    details: `Linked observation from ${report} at snapshot ${options.snapshot}: ${source.summary} — ${source.details}`,
+                });
+                this.workspaceTransaction.writeLedger(feature, ledger);
+                return { scope: "delivery", finding: canonical, ...identity };
+            }
+            const duplicate = findings.find((finding) => finding.author === options.author.trim() &&
+                finding.relatedTicket === options.relatedTicket &&
+                finding.severity === options.severity &&
+                finding.blocking === (options.blocking === true) &&
+                finding.summary === options.summary.trim() &&
+                finding.details === options.details.trim() &&
+                finding.provenance.some((item) => item.report === source.report &&
+                    item.snapshot === source.snapshot &&
+                    item.author === source.author &&
+                    item.summary === source.summary &&
+                    item.details === source.details));
+            if (duplicate)
+                return { scope: "delivery", finding: duplicate, idempotent: true, ...identity };
+            const highest = findings.reduce((current, finding) => {
+                const match = /^F-(\d{4,})$/.exec(finding.id);
+                return match && BigInt(match[1]) > current ? BigInt(match[1]) : current;
+            }, 0n);
+            const at = new Date().toISOString();
+            const finding = {
+                id: `F-${String(highest + 1n).padStart(4, "0")}`,
+                ...(options.relatedTicket ? { relatedTicket: options.relatedTicket } : {}),
+                severity: options.severity,
+                blocking: options.blocking === true,
+                status: "open",
+                summary: options.summary.trim(),
+                details: options.details.trim(),
+                author: options.author.trim(),
+                createdAt: at,
+                provenance: [source],
+                history: [
+                    {
+                        at,
+                        author: options.author.trim(),
+                        action: "registered",
+                        details: `Registered from ${report} at snapshot ${options.snapshot}.`,
+                    },
+                ],
+            };
+            delivery.findings = findings;
+            findings.push(finding);
+            delivery.history.push({
+                at,
+                author: options.author.trim(),
+                action: `finding-registered:${finding.id}`,
+            });
+            this.workspaceTransaction.writeLedger(feature, ledger);
+            return { scope: "delivery", finding, snapshot: identity.snapshot, headSha: identity.headSha };
+        });
+    }
+    deliveryFindingUpdate(options) {
+        validateAuthor(options.author);
+        if (!/^F-\d{4,}$/.test(options.finding)) {
+            throw new Error(`Invalid finding ID: ${options.finding}.`);
+        }
+        if (!["open", "confirmed", "fixed", "dismissed", "deferred"].includes(options.status)) {
+            throw new Error(`Invalid finding status: ${options.status}.`);
+        }
+        if (["dismissed", "deferred"].includes(options.status) && !options.details?.trim()) {
+            throw new Error(`--details is required for a ${options.status} finding disposition.`);
+        }
+        if (options.status === "deferred" && !options.followUp?.trim()) {
+            throw new Error("--follow-up is required for a deferred delivery finding.");
+        }
+        if (options.status === "deferred" && !options.requirementsDecision?.trim()) {
+            throw new Error("--requirements-decision is required for a deferred delivery finding.");
+        }
+        if (options.status === "fixed" && !options.evidence?.trim()) {
+            throw new Error("--evidence is required to mark a finding fixed.");
+        }
+        if (options.status !== "deferred" &&
+            (options.followUp !== undefined || options.requirementsDecision !== undefined)) {
+            throw new Error("--follow-up and --requirements-decision are only valid for a deferred finding.");
+        }
+        if (options.status !== "fixed" && options.evidence !== undefined) {
+            throw new Error("--evidence is only valid for a fixed finding.");
+        }
+        const feature = this.featureInspectionService.resolveFeature(options.spec);
+        return this.workspaceTransaction.run(feature.workspace, () => {
+            const ledger = this.ledgerRepository.readLedger(feature);
+            const delivery = ledger.delivery;
+            if (delivery.owner !== options.author.trim()) {
+                throw new Error("Only the current delivery controller may record a finding ruling.");
+            }
+            const finding = delivery.findings?.find((candidate) => candidate.id === options.finding);
+            if (!finding)
+                throw new Error(`Delivery finding not found: ${options.finding}.`);
+            const identity = this.gitEvidence.deliveryIdentity(feature, ledger, this.ticketRepository.readTickets(feature.workspace));
+            const rulingDetails = options.details?.trim();
+            let requirementsDecision;
+            if (options.status === "deferred") {
+                requirementsDecision = delivery.requirementsDecisions?.find((decision) => decision.id === options.requirementsDecision &&
+                    decision.finding === finding.id &&
+                    decision.status === "approved" &&
+                    decision.requirementsSnapshot === identity.requirementsSnapshot);
+                if (!requirementsDecision) {
+                    throw new Error("--requirements-decision must identify an approved decision for this finding and current requirements.");
+                }
+                const requiredReviewers = requiredDeliveryReviewers(ledger, delivery);
+                const assignments = delivery.reviewAssignments ?? [];
+                for (const { agent } of requiredReviewers) {
+                    const matching = assignments.filter((assignment) => assignment.agent === agent &&
+                        assignment.snapshot === identity.snapshot &&
+                        assignment.requirementsSnapshot === identity.requirementsSnapshot);
+                    if (matching.length !== 1 ||
+                        matching[0].status !== "submitted" ||
+                        matching[0].result !== "passed" ||
+                        this.reviewPolicy.reviewAssignmentBlocker(feature, delivery, matching[0], identity)) {
+                        throw new Error(`A deferred delivery finding requires fresh passing aggregate review from '${agent}'.`);
+                    }
+                }
+            }
+            let verification;
+            if (options.status === "fixed") {
+                if (!/^[0-9a-f]{64}$/i.test(options.evidence)) {
+                    throw new Error("--evidence must be a CLI-returned content snapshot.");
+                }
+                if (options.evidence !== identity.snapshot) {
+                    throw new Error("Verification evidence must match the current delivery snapshot.");
+                }
+                if (finding.provenance.some((source) => source.snapshot === identity.snapshot)) {
+                    throw new Error("Verification evidence must reflect changed content since every finding observation.");
+                }
+                const checks = this.checkPolicy.deliveryCheckBlockers(delivery, identity);
+                const required = delivery.checks?.required.filter((check) => !check.removedAt) ?? [];
+                if (required.length === 0 || checks.length > 0) {
+                    throw new Error(`Verification evidence is insufficient:\n${checks.join("\n") || "No required delivery checks are declared."}`);
+                }
+                verification = {
+                    snapshot: identity.snapshot,
+                    checkCommands: required.map((check) => check.command),
+                    verifiedAt: new Date().toISOString(),
+                    verifiedBy: options.author.trim(),
+                };
+            }
+            const last = finding.history.at(-1);
+            if (finding.status === options.status &&
+                finding.rulingDetails === rulingDetails &&
+                last?.action === `status:${options.status}` &&
+                last.author === options.author.trim()) {
+                return { scope: "delivery", finding, idempotent: true, snapshot: identity.snapshot };
+            }
+            const current = this.gitEvidence.deliveryIdentity(feature, ledger, this.ticketRepository.readTickets(feature.workspace));
+            if (current.snapshot !== identity.snapshot) {
+                throw new Error("Delivery content changed while recording the finding ruling.");
+            }
+            const wasBlocking = finding.blocking && !["fixed", "dismissed"].includes(finding.status);
+            finding.status = options.status;
+            if (["dismissed", "deferred"].includes(options.status))
+                finding.rulingDetails = rulingDetails;
+            else
+                delete finding.rulingDetails;
+            if (options.status === "deferred") {
+                finding.followUp = options.followUp.trim();
+                finding.requirementsDecision = requirementsDecision.id;
+            }
+            else {
+                delete finding.followUp;
+                delete finding.requirementsDecision;
+            }
+            if (verification)
+                finding.verification = verification;
+            else
+                delete finding.verification;
+            const details = rulingDetails ?? (verification ? `Verified at ${verification.snapshot}.` : options.status);
+            finding.history.push({
+                at: new Date().toISOString(),
+                author: options.author.trim(),
+                action: `status:${options.status}`,
+                details,
+            });
+            delivery.history.push({
+                at: new Date().toISOString(),
+                author: options.author.trim(),
+                action: `finding-${options.status}:${finding.id}`,
+            });
+            if (wasBlocking && ["fixed", "dismissed"].includes(options.status)) {
+                delivery.execution = "reviewing";
+            }
+            else if (finding.blocking && options.status === "deferred") {
+                delivery.execution =
+                    this.findingPolicy.deliveryFindingBlockers(feature, ledger, delivery, identity).length > 0
+                        ? "changes-requested"
+                        : "reviewing";
+            }
+            else if (finding.blocking && !["fixed", "dismissed"].includes(options.status)) {
+                delivery.execution = "changes-requested";
+            }
+            this.workspaceTransaction.writeLedger(feature, ledger);
+            return { scope: "delivery", finding, snapshot: identity.snapshot };
+        });
+    }
+}