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

package/build/SubagentDrivenDevelopment/Services/DeliveryService.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { Service } from "../../Foundation/Service.js";
+import { validateAuthor } from "../Policies/InputValidation.js";
+import { requiredDeliveryReviewers } from "../Policies/RequiredReviewers.js";
+export class DeliveryService 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;
+    }
+    finish(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;
+            if (ledger.tickets.length === 0) {
+                throw new Error("Cannot finish; the feature must contain at least one ticket.");
+            }
+            const tickets = this.ticketRepository.readTickets(feature.workspace);
+            const missing = ledger.tickets
+                .filter((progress) => progress.status !== "closed")
+                .map((progress) => progress.id);
+            if (missing.length > 0) {
+                throw new Error(`Cannot finish; every feature ticket must be closed: ${missing.join(", ")}.`);
+            }
+            if (tickets.length !== ledger.tickets.length) {
+                throw new Error("Cannot finish; one or more feature ticket documents are missing.");
+            }
+            if (delivery.adjudication?.status === "pending") {
+                throw new Error(`Cannot finish; delivery correction is paused for adjudication (${delivery.adjudication.reason}).`);
+            }
+            const identity = this.gitEvidence.deliveryIdentity(feature, ledger, tickets);
+            const checkBlockers = this.checkPolicy.deliveryCheckBlockers(delivery, identity);
+            if (checkBlockers.length > 0) {
+                throw new Error(`Cannot finish; final delivery checks are not current and passing:\n${checkBlockers.join("\n")}`);
+            }
+            const reviewers = requiredDeliveryReviewers(ledger, delivery);
+            const assignments = delivery.reviewAssignments ?? [];
+            const reviewBlockers = [];
+            if (assignments.length !== reviewers.length) {
+                reviewBlockers.push("Aggregate review assignment batch is incomplete.");
+            }
+            for (const required of reviewers) {
+                const matching = assignments.filter((assignment) => assignment.agent === required.agent &&
+                    assignment.objective === required.details &&
+                    assignment.scope === "delivery");
+                if (matching.length !== 1) {
+                    reviewBlockers.push(`Required aggregate reviewer '${required.agent}' has no unique current assignment.`);
+                    continue;
+                }
+                const assignment = matching[0];
+                if (assignment.status !== "submitted" || assignment.result !== "passed") {
+                    reviewBlockers.push(`Required aggregate review '${required.agent}' is ${assignment.status === "pending" ? "pending" : (assignment.result ?? "incomplete")}.`);
+                    continue;
+                }
+                const blocker = this.reviewPolicy.reviewAssignmentBlocker(feature, delivery, assignment, identity);
+                if (blocker)
+                    reviewBlockers.push(blocker);
+            }
+            if (reviewBlockers.length > 0) {
+                throw new Error(`Cannot finish; aggregate required reviews are not current and passing:\n${reviewBlockers.join("\n")}`);
+            }
+            const findingBlockers = this.findingPolicy.deliveryFindingBlockers(feature, ledger, delivery, identity);
+            if (findingBlockers.length > 0) {
+                throw new Error(`Cannot finish; unresolved delivery blockers remain:\n${findingBlockers.join("\n")}`);
+            }
+            if (ledger.retrospectiveRequired && !options.report) {
+                throw new Error("A retrospective report is required by the feature's stored creation policy.");
+            }
+            let retrospective;
+            if (options.report) {
+                const report = isAbsolute(options.report)
+                    ? resolve(options.report)
+                    : resolve(feature.workspace, options.report);
+                this.reportEvidence.assertReportPath(feature, report, true);
+                const content = readFileSync(report);
+                if (content.length === 0 || !content.toString("utf8").trim()) {
+                    throw new Error("Retrospective report must not be empty.");
+                }
+                retrospective = {
+                    report,
+                    reportSha256: createHash("sha256").update(content).digest("hex"),
+                };
+            }
+            if (delivery.finished) {
+                const same = delivery.finished.report === retrospective?.report &&
+                    delivery.finished.reportSha256 === retrospective?.reportSha256;
+                if (!same) {
+                    throw new Error("Full-spec delivery is already finished with different retrospective evidence.");
+                }
+                return {
+                    scope: "delivery",
+                    finished: true,
+                    idempotent: true,
+                    retrospectiveRequired: ledger.retrospectiveRequired,
+                    ...(retrospective ? { retrospective } : {}),
+                    ...identity,
+                };
+            }
+            const confirmed = this.gitEvidence.deliveryIdentity(feature, ledger, this.ticketRepository.readTickets(feature.workspace));
+            if (confirmed.snapshot !== identity.snapshot ||
+                this.checkPolicy.deliveryCheckBlockers(delivery, confirmed).length > 0) {
+                throw new Error("Aggregate content or check evidence changed while finishing; resume and revalidate delivery.");
+            }
+            delivery.execution = "complete";
+            delivery.finished = {
+                at: new Date().toISOString(),
+                author: options.author.trim(),
+                ...retrospective,
+            };
+            delivery.status = "complete";
+            delivery.history.push({
+                at: delivery.finished.at,
+                author: delivery.finished.author,
+                action: "delivery-finished",
+            });
+            this.workspaceTransaction.writeLedger(feature, ledger);
+            return {
+                scope: "delivery",
+                finished: true,
+                retrospectiveRequired: ledger.retrospectiveRequired,
+                ...(retrospective ? { retrospective } : {}),
+                ...identity,
+            };
+        });
+    }
+    next(options) {
+        const status = this.featureInspectionService.status(options);
+        return {
+            feature: status.feature,
+            spec: status.spec,
+            snapshots: status.snapshots,
+            findings: status.findings,
+            requirementsDecisions: status.requirementsDecisions,
+            actions: status.actions,
+            pendingAssignments: status.pendingAssignments,
+            blockers: status.blockers,
+            delivery: status.delivery,
+        };
+    }
+}

package/build/SubagentDrivenDevelopment/Services/DeliverySubmissionService.js

@@ -0,0 +1,273 @@
+import { Service } from "../../Foundation/Service.js";
+import { validateAuthor } from "../Policies/InputValidation.js";
+export class DeliverySubmissionService extends Service {
+    gitEvidence;
+    reportEvidence;
+    ticketRepository;
+    ledgerRepository;
+    workspaceTransaction;
+    checkPolicy;
+    reviewPolicy;
+    featureInspectionService;
+    constructor(app, gitEvidence, reportEvidence, ticketRepository, ledgerRepository, workspaceTransaction, checkPolicy, reviewPolicy, featureInspectionService) {
+        super(app);
+        this.gitEvidence = gitEvidence;
+        this.reportEvidence = reportEvidence;
+        this.ticketRepository = ticketRepository;
+        this.ledgerRepository = ledgerRepository;
+        this.workspaceTransaction = workspaceTransaction;
+        this.checkPolicy = checkPolicy;
+        this.reviewPolicy = reviewPolicy;
+        this.featureInspectionService = featureInspectionService;
+    }
+    submitDeliveryImplementation(options) {
+        if (options.assignment !== undefined ||
+            options.result !== undefined ||
+            options.noFindings ||
+            options.findings !== undefined) {
+            throw new Error("Review assignment, result, and findings options require role review.");
+        }
+        if (options.unavailable && !options.details?.trim()) {
+            throw new Error("--details is required when the delivery implementation report is unavailable.");
+        }
+        if (options.unavailable && options.report !== undefined) {
+            throw new Error("--report cannot be combined with --unavailable.");
+        }
+        if (!options.unavailable && options.details !== undefined) {
+            throw new Error("--details is only valid with --unavailable.");
+        }
+        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;
+            const assignment = delivery.assignment;
+            if (!assignment || assignment.action !== "correct" || assignment.role !== "implementation") {
+                throw new Error("No matching delivery correction implementation assignment is pending.");
+            }
+            if (delivery.owner !== options.author.trim() ||
+                assignment.controller !== options.author.trim()) {
+                throw new Error("Only the current delivery controller may submit this implementation report.");
+            }
+            const attempt = delivery.correctionAttempts?.find((candidate) => candidate.number === assignment.attempt);
+            if (!attempt || attempt.assignmentId !== assignment.id) {
+                throw new Error("Delivery correction assignment has no matching persisted attempt.");
+            }
+            const identity = this.gitEvidence.deliveryIdentity(feature, ledger, this.ticketRepository.readTickets(feature.workspace));
+            if (options.unavailable) {
+                const details = options.details.trim();
+                if (assignment.status === "unavailable" && assignment.unavailableDetails === details) {
+                    return {
+                        scope: "delivery",
+                        execution: delivery.execution,
+                        assignment,
+                        unavailable: true,
+                        idempotent: true,
+                        ...identity,
+                    };
+                }
+                if (!["pending", "unavailable"].includes(assignment.status)) {
+                    throw new Error("The delivery implementation assignment is no longer awaiting a report.");
+                }
+                assignment.status = "unavailable";
+                assignment.unavailableDetails = details;
+                this.workspaceTransaction.writeLedger(feature, ledger);
+                return {
+                    scope: "delivery",
+                    execution: delivery.execution,
+                    assignment,
+                    unavailable: true,
+                    ...identity,
+                };
+            }
+            if (!options.report)
+                throw new Error("Delivery implementation submission requires --report.");
+            if (assignment.status === "submitted") {
+                const digest = this.reportEvidence.readReportDigest(feature, this.reportEvidence.submissionReportPath(feature, assignment, options.report));
+                if (digest !== assignment.reportSha256) {
+                    throw new Error("The registered delivery implementation report changed after submission.");
+                }
+                return {
+                    scope: "delivery",
+                    execution: delivery.execution,
+                    assignment,
+                    report: assignment.report,
+                    reportSha256: digest,
+                    idempotent: true,
+                    ...identity,
+                };
+            }
+            if (!["pending", "unavailable"].includes(assignment.status)) {
+                throw new Error("The delivery implementation assignment is not awaiting a report.");
+            }
+            const report = this.reportEvidence.submissionReportPath(feature, assignment, options.report);
+            const reportSha256 = this.reportEvidence.readReportDigest(feature, report);
+            assignment.status = "submitted";
+            assignment.reportSha256 = reportSha256;
+            assignment.submittedAt = new Date().toISOString();
+            assignment.submittedBy = options.author.trim();
+            delete assignment.unavailableDetails;
+            attempt.assignment = assignment;
+            delivery.execution = "reviewing";
+            delivery.history.push({
+                at: assignment.submittedAt,
+                author: options.author.trim(),
+                action: `correction-report-submitted:${assignment.id}`,
+            });
+            this.workspaceTransaction.writeLedger(feature, ledger);
+            return {
+                scope: "delivery",
+                execution: delivery.execution,
+                assignment,
+                report: assignment.report,
+                reportSha256,
+                ...identity,
+            };
+        });
+    }
+    submitDeliveryReview(options) {
+        if (options.role !== "review") {
+            throw new Error("Delivery implementation submissions require an active corrective assignment.");
+        }
+        if (!options.assignment?.trim())
+            throw new Error("Review submission requires --assignment.");
+        if (!options.report)
+            throw new Error("Review submission requires --report.");
+        if (!options.result)
+            throw new Error("Review submission requires explicit --result.");
+        if (!["passed", "failed", "unavailable"].includes(options.result)) {
+            throw new Error(`Invalid review result: ${options.result}.`);
+        }
+        const findingIds = options.findingIds?.map((id) => id.trim());
+        if (options.noFindings === true && findingIds !== undefined) {
+            throw new Error("--findings and --no-findings cannot be combined.");
+        }
+        if (findingIds !== undefined &&
+            (findingIds.length === 0 ||
+                findingIds.some((id) => !/^F-\d{4,}$/.test(id)) ||
+                new Set(findingIds).size !== findingIds.length)) {
+            throw new Error("--findings must contain unique canonical finding IDs.");
+        }
+        if (options.noFindings !== true && findingIds === undefined) {
+            throw new Error("Review submission requires either --findings or exclusive --no-findings.");
+        }
+        if (options.result === "passed" && options.details !== undefined) {
+            throw new Error("--details is only valid for failed or unavailable review results.");
+        }
+        if (options.result !== "passed" && !options.details?.trim()) {
+            throw new Error("--details is required for failed or unavailable reviews.");
+        }
+        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;
+            if (!delivery.owner || delivery.owner !== options.author.trim()) {
+                throw new Error("Only the current delivery controller may submit aggregate review.");
+            }
+            const assignment = delivery.reviewAssignments?.find((candidate) => candidate.id === options.assignment);
+            if (!assignment || assignment.scope !== "delivery") {
+                throw new Error(`No delivery review assignment matches ID ${options.assignment}.`);
+            }
+            const identity = this.gitEvidence.deliveryIdentity(feature, ledger, this.ticketRepository.readTickets(feature.workspace));
+            const blockers = this.checkPolicy.deliveryCheckBlockers(delivery, identity);
+            if (blockers.length > 0)
+                throw new Error(blockers.join("\n"));
+            const snapshotBlocker = this.reviewPolicy.reviewSnapshotBlocker(feature, delivery, assignment, identity);
+            if (snapshotBlocker)
+                throw new Error(snapshotBlocker);
+            const report = this.reportEvidence.submissionReportPath(feature, assignment, options.report);
+            const reportSha256 = this.reportEvidence.readReportDigest(feature, report);
+            const reported = (delivery.findings ?? [])
+                .filter((finding) => finding.provenance.some((source) => source.report === assignment.report && source.snapshot === assignment.snapshot))
+                .map((finding) => finding.id);
+            if (options.noFindings === true && reported.length > 0) {
+                throw new Error(`Review report has registered findings and cannot declare --no-findings: ${reported.join(", ")}.`);
+            }
+            if (findingIds !== undefined) {
+                const missing = reported.filter((id) => !findingIds.includes(id));
+                const unknown = findingIds.filter((id) => !reported.includes(id));
+                if (missing.length > 0 || unknown.length > 0) {
+                    throw new Error(`--findings must exactly list canonical findings registered from this delivery report and snapshot; missing=${missing.join(",") || "none"}; invalid provenance=${unknown.join(",") || "none"}.`);
+                }
+            }
+            if (assignment.status === "submitted") {
+                if (assignment.result === options.result &&
+                    assignment.noFindings === (options.noFindings === true ? true : undefined) &&
+                    JSON.stringify(assignment.findingIds) === JSON.stringify(findingIds) &&
+                    assignment.submittedBy === options.author.trim() &&
+                    assignment.details === options.details?.trim() &&
+                    assignment.reportSha256 === reportSha256) {
+                    return {
+                        scope: "delivery",
+                        execution: delivery.execution,
+                        assignment,
+                        report: assignment.report,
+                        reportSha256,
+                        idempotent: true,
+                        ...identity,
+                    };
+                }
+                throw new Error("The delivery review assignment already has a different submitted result.");
+            }
+            if (assignment.status !== "pending") {
+                throw new Error("The delivery review assignment is not awaiting a report.");
+            }
+            if (JSON.stringify(this.gitEvidence.changedPaths(delivery.baseSha)) !==
+                JSON.stringify(assignment.inventory)) {
+                throw new Error("Aggregate review inventory changed while submitting the report.");
+            }
+            assignment.status = "submitted";
+            assignment.result = options.result;
+            if (options.noFindings === true)
+                assignment.noFindings = true;
+            else
+                delete assignment.noFindings;
+            if (findingIds !== undefined)
+                assignment.findingIds = findingIds;
+            else
+                delete assignment.findingIds;
+            assignment.reportSha256 = reportSha256;
+            assignment.submittedAt = new Date().toISOString();
+            assignment.submittedBy = options.author.trim();
+            if (options.details?.trim())
+                assignment.details = options.details.trim();
+            const unresolvedBlocking = (assignment.findingIds ?? []).some((id) => delivery.findings?.some((finding) => finding.id === id &&
+                finding.blocking &&
+                finding.status !== "fixed" &&
+                finding.status !== "dismissed"));
+            if (assignment.result !== "passed" || unresolvedBlocking) {
+                delivery.execution = "changes-requested";
+            }
+            delivery.history.push({
+                at: new Date().toISOString(),
+                author: options.author.trim(),
+                action: `aggregate-review-submitted:${assignment.id}:${assignment.result}`,
+            });
+            if (delivery.reviewAssignments?.every((item) => item.status === "submitted")) {
+                for (const finding of delivery.findings ?? []) {
+                    if (!finding.blocking ||
+                        !finding.relatedTicket ||
+                        finding.status === "fixed" ||
+                        finding.status === "dismissed") {
+                        continue;
+                    }
+                    const ticket = ledger.tickets.find((item) => item.id === finding.relatedTicket);
+                    if (!ticket)
+                        throw new Error(`Related ticket not found: ${finding.relatedTicket}.`);
+                    ticket.status = "open";
+                    delete ticket.blocker;
+                }
+            }
+            this.workspaceTransaction.writeLedger(feature, ledger);
+            return {
+                scope: "delivery",
+                execution: delivery.execution,
+                assignment,
+                report: assignment.report,
+                reportSha256,
+                ...identity,
+            };
+        });
+    }
+}

package/build/SubagentDrivenDevelopment/Services/FeatureCreationService.js

@@ -0,0 +1,138 @@
+import { mkdirSync, mkdtempSync, realpathSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { templateCatalog } from "../../Assets/Templates/Catalog.js";
+import { Service } from "../../Foundation/Service.js";
+import { assertRealDirectory, lstatIfPresent, isPathInside, } from "../Persistence/FileSystem.js";
+import { validateCreateOptions, featureSlug, } from "../Policies/InputValidation.js";
+import { resolveRenderContext } from "../../TemplateRendering/Computed/ResolveRenderContext.js";
+import { renderText } from "../../TemplateRendering/Rendering/RenderText.js";
+const templates = fileURLToPath(new URL("../../Assets/Templates/", import.meta.url));
+export class FeatureCreationService extends Service {
+    featureWorkspace;
+    pathSafety;
+    workspaceTransaction;
+    gitEvidence;
+    constructor(app, featureWorkspace, pathSafety, workspaceTransaction, gitEvidence) {
+        super(app);
+        this.featureWorkspace = featureWorkspace;
+        this.pathSafety = pathSafety;
+        this.workspaceTransaction = workspaceTransaction;
+        this.gitEvidence = gitEvidence;
+    }
+    create(options) {
+        this.assertApplicationBooted();
+        validateCreateOptions(options);
+        const root = realpathSync(this.app.workspaceRoot);
+        if (!statSync(root).isDirectory())
+            throw new Error("Workspace root must be a directory.");
+        const scratch = join(root, ".scratch");
+        if (this.pathSafety.isIgnored(root, ".scratch/.sdd-create.lock")) {
+            throw new Error("Feature destination is ignored: .scratch");
+        }
+        const scratchEntry = lstatIfPresent(scratch);
+        if (scratchEntry) {
+            assertRealDirectory(scratch, ".scratch");
+        }
+        else {
+            try {
+                mkdirSync(scratch);
+            }
+            catch (error) {
+                if (typeof error !== "object" ||
+                    error === null ||
+                    !("code" in error) ||
+                    error.code !== "EEXIST") {
+                    throw error;
+                }
+                assertRealDirectory(scratch, ".scratch");
+            }
+        }
+        if (!isPathInside(root, realpathSync(scratch))) {
+            throw new Error(".scratch must remain inside this checkout.");
+        }
+        const release = this.workspaceTransaction.acquireCreationLock(scratch);
+        try {
+            this.featureWorkspace.rejectAbandonedStaging(scratch);
+            const id = this.featureWorkspace.nextFeatureId(scratch);
+            const feature = `${id}-${featureSlug(options.title)}`;
+            const workspace = join(scratch, feature);
+            if (lstatIfPresent(workspace)) {
+                throw new Error(`Feature workspace already exists: ${feature}`);
+            }
+            const relativeBase = `.scratch/${feature}`;
+            const targets = [
+                `${relativeBase}/spec.md`,
+                `${relativeBase}/sdd.json`,
+                `${relativeBase}/tickets`,
+                `${relativeBase}/reports`,
+            ];
+            if (options.withDesign)
+                targets.push(`${relativeBase}/design.md`);
+            for (const target of targets) {
+                if (this.pathSafety.isIgnored(root, target)) {
+                    throw new Error(`Feature destination is ignored: ${target}`);
+                }
+            }
+            const staging = mkdtempSync(join(scratch, ".sdd-create-"));
+            try {
+                mkdirSync(join(staging, "tickets"));
+                mkdirSync(join(staging, "reports"));
+                const context = resolveRenderContext(this.app, {
+                    variables: {
+                        title: options.title.trim(),
+                        author: options.author.trim(),
+                    },
+                });
+                const spec = renderText(readFileSync(join(templates, templateCatalog.sdd.spec), "utf8"), context);
+                const design = options.withDesign
+                    ? renderText(readFileSync(join(templates, templateCatalog.sdd.design), "utf8"), context)
+                    : undefined;
+                const ledger = {
+                    schemaVersion: 3,
+                    featureId: id,
+                    title: options.title.trim(),
+                    createdBy: options.author.trim(),
+                    createdAt: new Date().toISOString(),
+                    retrospectiveRequired: options.requireRetrospective ?? false,
+                    reviewPolicy: {
+                        version: 1,
+                        ticket: ["sdd-reviewer"],
+                        delivery: ["sdd-reviewer"],
+                    },
+                    tickets: [],
+                    delivery: {
+                        status: "active",
+                        execution: "unstarted",
+                        history: [],
+                        baseSha: this.gitEvidence.headSha(),
+                    },
+                };
+                writeFileSync(join(staging, "spec.md"), spec, { flag: "wx" });
+                if (design !== undefined) {
+                    writeFileSync(join(staging, "design.md"), design, { flag: "wx" });
+                }
+                writeFileSync(join(staging, "sdd.json"), `${JSON.stringify(ledger, null, 2)}\n`, {
+                    flag: "wx",
+                });
+                if (lstatIfPresent(workspace)) {
+                    throw new Error(`Feature workspace already exists: ${feature}`);
+                }
+                renameSync(staging, workspace);
+            }
+            catch (error) {
+                rmSync(staging, { recursive: true, force: true });
+                throw new Error(`Feature creation failed before publishing ${feature}; no complete workspace was created: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return {
+                feature,
+                workspace,
+                spec: join(workspace, "spec.md"),
+                ledger: join(workspace, "sdd.json"),
+            };
+        }
+        finally {
+            release();
+        }
+    }
+}