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

package/build/SubagentDrivenDevelopment/Persistence/LedgerRepository.js

@@ -0,0 +1,322 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { blueprintCatalog } from "../../BlueprintManagement/Catalog/BlueprintCatalog.js";
+import { Service } from "../../Foundation/Service.js";
+import { FEATURE_DIRECTORY, EXECUTION_STATES, TICKET_CATEGORIES, TRACKER_STATUSES, } from "../Models/Workflow.js";
+import { isImplementationAssignment, isCorrectionAttempt, isCorrectionAdjudication, hasMatchingCorrectionAttempt, } from "./AssignmentSchema.js";
+import { isCheckRequirement, isCheckRecord, isCheckGateInvalidation, } from "./CheckSchema.js";
+import { isReviewFinding, isRequirementsDecision, } from "./FindingSchema.js";
+import { isDeliveryProgress, isAcceptedEvidence, isIntegrationRecord, } from "./ProgressSchema.js";
+import { isReviewAssignment, isSpecialistReviewRequirement, } from "./ReviewSchema.js";
+import { Records } from "../../Support/Records.js";
+const isRecord = Records.isRecord;
+export class LedgerRepository extends Service {
+    constructor(app) {
+        super(app);
+    }
+    readLedger(feature) {
+        return this.validateLedger(JSON.parse(readFileSync(feature.ledger, "utf8")), feature.feature);
+    }
+    validateLedger(value, feature) {
+        this.assertLedger(value, feature);
+        return value;
+    }
+    assertLedger(value, feature) {
+        if (!isRecord(value))
+            throw new Error("Feature ledger must contain a JSON object.");
+        const id = FEATURE_DIRECTORY.exec(feature)?.[1];
+        if (value.schemaVersion !== 3) {
+            throw new Error(`Unsupported feature ledger schema version: ${String(value.schemaVersion)}.`);
+        }
+        if (typeof value.featureId !== "string" || value.featureId !== id) {
+            throw new Error("Feature ledger ID does not match its workspace directory.");
+        }
+        if (typeof value.title !== "string" || !value.title.trim()) {
+            throw new Error("Feature ledger title must be a non-empty string.");
+        }
+        if (typeof value.createdBy !== "string" || !value.createdBy.trim()) {
+            throw new Error("Feature ledger author must be a non-empty string.");
+        }
+        if (typeof value.createdAt !== "string" || !Number.isFinite(Date.parse(value.createdAt))) {
+            throw new Error("Feature ledger creation time must be a valid timestamp.");
+        }
+        if (typeof value.retrospectiveRequired !== "boolean") {
+            throw new Error("Feature ledger retrospective policy must be a boolean.");
+        }
+        if (!isRecord(value.reviewPolicy))
+            throw new Error("Feature review policy must be an object.");
+        if (typeof value.reviewPolicy.version !== "number" ||
+            !Number.isSafeInteger(value.reviewPolicy.version) ||
+            value.reviewPolicy.version < 1) {
+            throw new Error("Feature review policy version must be a positive integer.");
+        }
+        for (const role of ["ticket", "delivery"]) {
+            const reviewers = value.reviewPolicy[role];
+            if (!Array.isArray(reviewers) ||
+                reviewers.length === 0 ||
+                !reviewers.every((reviewer) => typeof reviewer === "string" && reviewer.trim())) {
+                throw new Error(`Feature ${role} review requirements must be a non-empty string list.`);
+            }
+        }
+        if (!Array.isArray(value.tickets) ||
+            !value.tickets.every((ticket) => isRecord(ticket) &&
+                typeof ticket.id === "string" &&
+                /^T-\d{4,}$/.test(ticket.id) &&
+                typeof ticket.execution === "string" &&
+                EXECUTION_STATES.includes(ticket.execution) &&
+                typeof ticket.title === "string" &&
+                !!ticket.title.trim() &&
+                typeof ticket.reporter === "string" &&
+                !!ticket.reporter.trim() &&
+                typeof ticket.category === "string" &&
+                TICKET_CATEGORIES.includes(ticket.category) &&
+                typeof ticket.status === "string" &&
+                TRACKER_STATUSES.includes(ticket.status) &&
+                Array.isArray(ticket.blockedBy) &&
+                ticket.blockedBy.every((dependency) => typeof dependency === "string") &&
+                (!Object.hasOwn(ticket, "blocker") ||
+                    (typeof ticket.blocker === "string" && !!ticket.blocker.trim())) &&
+                ((!Object.hasOwn(ticket, "owner") && !Object.hasOwn(ticket, "baseSha")) ||
+                    (typeof ticket.owner === "string" &&
+                        !!ticket.owner.trim() &&
+                        typeof ticket.baseSha === "string" &&
+                        /^[0-9a-f]{40,64}$/i.test(ticket.baseSha))) &&
+                (!Object.hasOwn(ticket, "acceptedEvidence") ||
+                    isAcceptedEvidence(ticket.acceptedEvidence)) &&
+                (!Object.hasOwn(ticket, "integration") ||
+                    (ticket.execution === "integrated" &&
+                        isIntegrationRecord(ticket.integration) &&
+                        isAcceptedEvidence(ticket.acceptedEvidence) &&
+                        JSON.stringify(ticket.integration.files) ===
+                            JSON.stringify(ticket.acceptedEvidence.files) &&
+                        ticket.integration.contentDigest === ticket.acceptedEvidence.contentDigest)) &&
+                (!Object.hasOwn(ticket, "reviewRequirements") ||
+                    (Array.isArray(ticket.reviewRequirements) &&
+                        ticket.reviewRequirements.every(isSpecialistReviewRequirement) &&
+                        new Set(ticket.reviewRequirements.map((requirement) => requirement.agent)).size ===
+                            ticket.reviewRequirements.length)) &&
+                (!Object.hasOwn(ticket, "checks") ||
+                    (isRecord(ticket.checks) &&
+                        Array.isArray(ticket.checks.required) &&
+                        ticket.checks.required.every(isCheckRequirement) &&
+                        Array.isArray(ticket.checks.records) &&
+                        ticket.checks.records.every(isCheckRecord) &&
+                        (!Object.hasOwn(ticket.checks, "invalidations") ||
+                            (Array.isArray(ticket.checks.invalidations) &&
+                                ticket.checks.invalidations.every(isCheckGateInvalidation))))) &&
+                (!Object.hasOwn(ticket, "assignment") ||
+                    (isImplementationAssignment(ticket.assignment) &&
+                        ticket.assignment.report ===
+                            join(this.app.workspaceRoot, ".scratch", feature, "reports", ticket.assignment.action === "implement"
+                                ? `${ticket.id}-implementation.md`
+                                : `${ticket.id}-round-${ticket.assignment.attempt}-fix.md`))) &&
+                (!Object.hasOwn(ticket, "correctionAttempts") ||
+                    (Array.isArray(ticket.correctionAttempts) &&
+                        ticket.correctionAttempts.every(isCorrectionAttempt) &&
+                        ticket.correctionAttempts.every((attempt, index) => attempt.number === index + 1) &&
+                        ticket.correctionAttempts.every((attempt) => attempt.assignment.report ===
+                            join(this.app.workspaceRoot, ".scratch", feature, "reports", `${ticket.id}-round-${attempt.number}-fix.md`) &&
+                            (!attempt.priorAssignment ||
+                                attempt.priorAssignment.report ===
+                                    join(this.app.workspaceRoot, ".scratch", feature, "reports", attempt.priorAssignment.action === "implement"
+                                        ? `${ticket.id}-implementation.md`
+                                        : `${ticket.id}-round-${attempt.priorAssignment.attempt}-fix.md`)) &&
+                            (attempt.reviewAssignments ?? []).every((assignment) => assignment.report ===
+                                join(this.app.workspaceRoot, ".scratch", feature, "reports", assignment.scope === "initial"
+                                    ? `${ticket.id}-review-${assignment.id}.md`
+                                    : `${ticket.id}-round-${assignment.attempt}-review-${assignment.id}.md`))) &&
+                        hasMatchingCorrectionAttempt(ticket))) &&
+                (!Object.hasOwn(ticket, "adjudication") ||
+                    isCorrectionAdjudication(ticket.adjudication)) &&
+                (!Object.hasOwn(ticket, "reviewAssignments") ||
+                    (Array.isArray(ticket.reviewAssignments) &&
+                        ticket.reviewAssignments.every((assignment) => isReviewAssignment(assignment) &&
+                            blueprintCatalog.agents[assignment.agent]?.canReview === true &&
+                            assignment.report ===
+                                join(this.app.workspaceRoot, ".scratch", feature, "reports", assignment.scope === "initial"
+                                    ? `${ticket.id}-review-${assignment.id}.md`
+                                    : `${ticket.id}-round-${assignment.attempt}-review-${assignment.id}.md`)))) &&
+                (!Object.hasOwn(ticket, "reviewHistory") ||
+                    (Array.isArray(ticket.reviewHistory) &&
+                        ticket.reviewHistory.every((assignment) => isReviewAssignment(assignment) &&
+                            blueprintCatalog.agents[assignment.agent]?.canReview === true &&
+                            assignment.report ===
+                                join(this.app.workspaceRoot, ".scratch", feature, "reports", assignment.scope === "initial"
+                                    ? `${ticket.id}-review-${assignment.id}.md`
+                                    : `${ticket.id}-round-${assignment.attempt}-review-${assignment.id}.md`)))) &&
+                (!Object.hasOwn(ticket, "requirementsDecisions") ||
+                    (Array.isArray(ticket.requirementsDecisions) &&
+                        ticket.requirementsDecisions.every(isRequirementsDecision))) &&
+                (!Object.hasOwn(ticket, "findings") ||
+                    (Array.isArray(ticket.findings) && ticket.findings.every(isReviewFinding))))) {
+            throw new Error("Feature ticket records must contain a ticket ID and a valid execution state.");
+        }
+        if (new Set(value.tickets.map((ticket) => ticket.id)).size !==
+            value.tickets.length) {
+            throw new Error("Feature ledger ticket IDs must be unique.");
+        }
+        for (const ticket of value.tickets) {
+            for (const requirement of ticket.reviewRequirements ?? []) {
+                if (blueprintCatalog.agents[requirement.agent]?.canReview !== true) {
+                    throw new Error(`Required specialist agent '${requirement.agent}' is not explicitly marked review-eligible.`);
+                }
+                if (value.reviewPolicy.ticket.includes(requirement.agent)) {
+                    throw new Error(`Specialist reviewer '${requirement.agent}' duplicates the pinned ticket review policy.`);
+                }
+            }
+            const findingIds = ticket.findings?.map((finding) => finding.id) ?? [];
+            if (new Set(findingIds).size !== findingIds.length) {
+                throw new Error(`Finding IDs must be unique within ticket ${ticket.id}.`);
+            }
+            const decisionIds = ticket.requirementsDecisions?.map((decision) => decision.id) ?? [];
+            if (new Set(decisionIds).size !== decisionIds.length) {
+                throw new Error(`Requirements decision IDs must be unique within ticket ${ticket.id}.`);
+            }
+            for (const finding of ticket.findings ?? []) {
+                if (finding.requirementsDecision &&
+                    !ticket.requirementsDecisions?.some((decision) => decision.id === finding.requirementsDecision &&
+                        decision.finding === finding.id &&
+                        decision.status === "approved")) {
+                    throw new Error(`Finding ${finding.id} references an invalid requirements decision.`);
+                }
+            }
+            for (const assignment of [
+                ...(ticket.reviewHistory ?? []),
+                ...(ticket.reviewAssignments ?? []),
+            ]) {
+                const reported = (ticket.findings ?? []).filter((finding) => finding.provenance.some((source) => source.report === assignment.report && source.snapshot === assignment.snapshot));
+                if (assignment.noFindings === true && reported.length > 0) {
+                    throw new Error(`Review assignment ${assignment.id} declares no findings despite registered provenance.`);
+                }
+                for (const id of assignment.findingIds ?? []) {
+                    const finding = (ticket.findings ?? []).find((candidate) => candidate.id === id);
+                    if (!finding ||
+                        !finding.provenance.some((source) => source.report === assignment.report && source.snapshot === assignment.snapshot)) {
+                        throw new Error(`Review assignment ${assignment.id} references finding ${id} without matching provenance.`);
+                    }
+                }
+                if (assignment.status === "submitted" &&
+                    assignment.findingIds &&
+                    (reported.length !== assignment.findingIds.length ||
+                        reported.some((finding) => !assignment.findingIds.includes(finding.id)))) {
+                    throw new Error(`Review assignment ${assignment.id} does not list the complete canonical findings set.`);
+                }
+            }
+        }
+        const reviewAssignmentIds = value.tickets.flatMap((ticket) => isRecord(ticket)
+            ? [
+                ...(Array.isArray(ticket.reviewHistory) ? ticket.reviewHistory : []),
+                ...(Array.isArray(ticket.reviewAssignments) ? ticket.reviewAssignments : []),
+            ].map((assignment) => (isRecord(assignment) ? assignment.id : undefined))
+            : []);
+        if (reviewAssignmentIds.some((assignmentId) => typeof assignmentId !== "string") ||
+            new Set(reviewAssignmentIds).size !== reviewAssignmentIds.length) {
+            throw new Error("Feature review assignment IDs must be unique.");
+        }
+        if (!isRecord(value.delivery))
+            throw new Error("Feature delivery progress must be an object.");
+        if (typeof value.delivery.execution !== "string" ||
+            !EXECUTION_STATES.includes(value.delivery.execution)) {
+            throw new Error("Feature delivery execution state is invalid.");
+        }
+        if (!["active", "complete"].includes(String(value.delivery.status))) {
+            throw new Error("Feature tracking status is invalid.");
+        }
+        if (!Array.isArray(value.delivery.history) ||
+            !value.delivery.history.every((entry) => isRecord(entry) &&
+                typeof entry.at === "string" &&
+                Number.isFinite(Date.parse(entry.at)) &&
+                typeof entry.author === "string" &&
+                entry.author.trim() &&
+                typeof entry.action === "string" &&
+                entry.action.trim())) {
+            throw new Error("Feature delivery history records must contain a valid timestamp, author, and action.");
+        }
+        const delivery = value.delivery;
+        if ((Object.hasOwn(delivery, "baseSha") &&
+            (typeof delivery.baseSha !== "string" || !/^[0-9a-f]{40,64}$/i.test(delivery.baseSha))) ||
+            (Object.hasOwn(delivery, "owner") &&
+                (typeof delivery.owner !== "string" || !delivery.owner.trim())) ||
+            (Object.hasOwn(delivery, "reviewRequirements") &&
+                (!Array.isArray(delivery.reviewRequirements) ||
+                    !delivery.reviewRequirements.every(isSpecialistReviewRequirement) ||
+                    new Set(delivery.reviewRequirements.map((item) => item.agent)).size !==
+                        delivery.reviewRequirements.length)) ||
+            (Object.hasOwn(delivery, "reviewAssignments") &&
+                (!Array.isArray(delivery.reviewAssignments) ||
+                    !delivery.reviewAssignments.every((assignment) => isReviewAssignment(assignment) &&
+                        assignment.scope === "delivery" &&
+                        blueprintCatalog.agents[assignment.agent]?.canReview === true &&
+                        assignment.report ===
+                            join(this.app.workspaceRoot, ".scratch", feature, "reports", assignment.attempt
+                                ? `final-round-${assignment.attempt}-review-${assignment.id}.md`
+                                : `final-review-${assignment.id}.md`)))) ||
+            (Object.hasOwn(delivery, "reviewHistory") &&
+                (!Array.isArray(delivery.reviewHistory) ||
+                    !delivery.reviewHistory.every((assignment) => isReviewAssignment(assignment) &&
+                        assignment.scope === "delivery" &&
+                        blueprintCatalog.agents[assignment.agent]?.canReview === true))) ||
+            (Object.hasOwn(delivery, "requirementsDecisions") &&
+                (!Array.isArray(delivery.requirementsDecisions) ||
+                    !delivery.requirementsDecisions.every(isRequirementsDecision) ||
+                    new Set(delivery.requirementsDecisions.map((decision) => decision.id)).size !==
+                        delivery.requirementsDecisions.length)) ||
+            (Object.hasOwn(delivery, "findings") &&
+                (!Array.isArray(delivery.findings) || !delivery.findings.every(isReviewFinding))) ||
+            (Object.hasOwn(delivery, "assignment") &&
+                (!isImplementationAssignment(delivery.assignment) ||
+                    delivery.assignment.action !== "correct" ||
+                    !Number.isSafeInteger(delivery.assignment.attempt) ||
+                    delivery.assignment.report !==
+                        join(this.app.workspaceRoot, ".scratch", feature, "reports", `final-round-${delivery.assignment.attempt}-fix.md`))) ||
+            (Object.hasOwn(delivery, "checks") &&
+                (!isRecord(delivery.checks) ||
+                    !Array.isArray(delivery.checks.required) ||
+                    !delivery.checks.required.every(isCheckRequirement) ||
+                    !Array.isArray(delivery.checks.records) ||
+                    !delivery.checks.records.every(isCheckRecord))) ||
+            (Object.hasOwn(delivery, "correctionAttempts") &&
+                (!Array.isArray(delivery.correctionAttempts) ||
+                    !delivery.correctionAttempts.every(isCorrectionAttempt) ||
+                    delivery.correctionAttempts.some((attempt, index) => attempt.number !== index + 1 ||
+                        attempt.assignment.action !== "correct" ||
+                        attempt.assignment.report !==
+                            join(this.app.workspaceRoot, ".scratch", feature, "reports", `final-round-${attempt.number}-fix.md`) ||
+                        (attempt.reviewAssignments ?? []).some((assignment) => assignment.scope !== "delivery" ||
+                            assignment.attempt !== attempt.number ||
+                            assignment.report !==
+                                join(this.app.workspaceRoot, ".scratch", feature, "reports", `final-round-${attempt.number}-review-${assignment.id}.md`))) ||
+                    !hasMatchingCorrectionAttempt(delivery))) ||
+            (Object.hasOwn(delivery, "adjudication") && !isCorrectionAdjudication(delivery.adjudication))) {
+            throw new Error("Feature delivery evidence or assignment records are invalid.");
+        }
+        if (!isDeliveryProgress(delivery)) {
+            throw new Error("Feature delivery progress does not match the delivery ledger schema.");
+        }
+        const deliveryFindingIds = delivery.findings?.map((finding) => finding.id) ?? [];
+        if (new Set(deliveryFindingIds).size !== deliveryFindingIds.length) {
+            throw new Error("Delivery finding IDs must be unique.");
+        }
+        const ticketIds = new Set(value.tickets.map((ticket) => ticket.id));
+        for (const finding of delivery.findings ?? []) {
+            if (finding.relatedTicket && !ticketIds.has(finding.relatedTicket)) {
+                throw new Error(`Delivery finding ${finding.id} references missing ticket ${finding.relatedTicket}.`);
+            }
+            if (finding.requirementsDecision &&
+                !delivery.requirementsDecisions?.some((decision) => decision.id === finding.requirementsDecision &&
+                    decision.finding === finding.id &&
+                    decision.status === "approved")) {
+                throw new Error(`Delivery finding ${finding.id} references an invalid requirements decision.`);
+            }
+        }
+        const allReviewAssignmentIds = [
+            ...reviewAssignmentIds,
+            ...(Array.isArray(delivery.reviewHistory) ? delivery.reviewHistory : []).map((assignment) => isRecord(assignment) ? assignment.id : undefined),
+            ...(Array.isArray(delivery.reviewAssignments) ? delivery.reviewAssignments : []).map((assignment) => (isRecord(assignment) ? assignment.id : undefined)),
+        ];
+        if (allReviewAssignmentIds.some((assignmentId) => typeof assignmentId !== "string") ||
+            new Set(allReviewAssignmentIds).size !== allReviewAssignmentIds.length) {
+            throw new Error("Feature review assignment IDs must be unique.");
+        }
+    }
+}

package/build/SubagentDrivenDevelopment/Persistence/PathSafety.js

@@ -0,0 +1,62 @@
+import { realpathSync } from "node:fs";
+import { join, relative } from "node:path";
+import { Service } from "../../Foundation/Service.js";
+import { lstatIfPresent, isPathInside } from "./FileSystem.js";
+export class PathSafety extends Service {
+    git;
+    constructor(app, git) {
+        super(app);
+        this.git = git;
+    }
+    assertTicketPath(workspace, path) {
+        const ticketsDirectory = join(workspace, "tickets");
+        const directoryEntry = lstatIfPresent(ticketsDirectory);
+        if (!directoryEntry?.isDirectory() || directoryEntry.isSymbolicLink()) {
+            throw new Error("Feature tickets path must be a real directory.");
+        }
+        if (!isPathInside(ticketsDirectory, path) ||
+            !/^T-\d{4,}\.md$/.test(path.slice(ticketsDirectory.length + 1))) {
+            throw new Error("Ticket path must be a numbered Markdown file inside tickets/.");
+        }
+        const entry = lstatIfPresent(path);
+        if (entry && !entry.isFile())
+            throw new Error(`Ticket path must be a regular file: ${path}.`);
+        if (entry && !isPathInside(ticketsDirectory, realpathSync(path))) {
+            throw new Error("Ticket file must remain inside the feature tickets directory.");
+        }
+        const root = realpathSync(this.app.workspaceRoot);
+        const relativePath = relative(root, path);
+        if (this.isIgnored(root, relativePath))
+            throw new Error(`Ticket path is ignored: ${relativePath}`);
+    }
+    isIgnored(root, relativePath) {
+        const result = this.git.run([
+            "--no-pager",
+            "-c",
+            "color.ui=false",
+            "check-ignore",
+            "--quiet",
+            "--no-index",
+            "--",
+            relativePath,
+        ], {
+            cwd: root,
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0 && result.status !== 1) {
+            throw new Error(`git check-ignore failed: ${result.stderr.trim()}`);
+        }
+        return result.status === 0;
+    }
+    assertReadyReadable(workspace) {
+        if (lstatIfPresent(join(workspace, ".sdd-write-recovery.json"))) {
+            throw new Error("Pending ticket recovery journal; run a mutating ticket command to recover.");
+        }
+        if (lstatIfPresent(join(workspace, ".sdd-tickets.lock"))) {
+            throw new Error("Ticket updates are in progress; retry ready after the lock is released.");
+        }
+    }
+}

package/build/SubagentDrivenDevelopment/Persistence/ProgressSchema.js

@@ -0,0 +1,95 @@
+import { isAbsolute } from "node:path";
+import { EXECUTION_STATES } from "../Models/Workflow.js";
+import { isImplementationAssignment, isCorrectionAttempt, isCorrectionAdjudication, } from "./AssignmentSchema.js";
+import { isCheckRequirement, isCheckRecord, isCheckGateInvalidation, isSafeCoveragePath, } from "./CheckSchema.js";
+import { isReviewFinding, isRequirementsDecision, } from "./FindingSchema.js";
+import { isReviewAssignment, isSpecialistReviewRequirement, } from "./ReviewSchema.js";
+import { Records } from "../../Support/Records.js";
+const isRecord = Records.isRecord;
+export function isDeliveryProgress(value) {
+    return (isRecord(value) &&
+        (!Object.hasOwn(value, "status") || ["active", "complete"].includes(String(value.status))) &&
+        typeof value.execution === "string" &&
+        EXECUTION_STATES.some((state) => state === value.execution) &&
+        Array.isArray(value.history) &&
+        value.history.every((entry) => isRecord(entry) &&
+            typeof entry.at === "string" &&
+            Number.isFinite(Date.parse(entry.at)) &&
+            typeof entry.author === "string" &&
+            !!entry.author.trim() &&
+            typeof entry.action === "string" &&
+            !!entry.action.trim()) &&
+        (!Object.hasOwn(value, "baseSha") ||
+            (typeof value.baseSha === "string" && /^[0-9a-f]{40,64}$/i.test(value.baseSha))) &&
+        (!Object.hasOwn(value, "owner") || (typeof value.owner === "string" && !!value.owner.trim())) &&
+        (!Object.hasOwn(value, "reviewRequirements") ||
+            (Array.isArray(value.reviewRequirements) &&
+                value.reviewRequirements.every(isSpecialistReviewRequirement))) &&
+        (!Object.hasOwn(value, "reviewAssignments") ||
+            (Array.isArray(value.reviewAssignments) &&
+                value.reviewAssignments.every(isReviewAssignment))) &&
+        (!Object.hasOwn(value, "reviewHistory") ||
+            (Array.isArray(value.reviewHistory) && value.reviewHistory.every(isReviewAssignment))) &&
+        (!Object.hasOwn(value, "assignment") ||
+            (isImplementationAssignment(value.assignment) && value.assignment.action === "correct")) &&
+        (!Object.hasOwn(value, "requirementsDecisions") ||
+            (Array.isArray(value.requirementsDecisions) &&
+                value.requirementsDecisions.every(isRequirementsDecision))) &&
+        (!Object.hasOwn(value, "checks") ||
+            (isRecord(value.checks) &&
+                Array.isArray(value.checks.required) &&
+                value.checks.required.every(isCheckRequirement) &&
+                Array.isArray(value.checks.records) &&
+                value.checks.records.every(isCheckRecord) &&
+                (!Object.hasOwn(value.checks, "invalidations") ||
+                    (Array.isArray(value.checks.invalidations) &&
+                        value.checks.invalidations.every(isCheckGateInvalidation))))) &&
+        (!Object.hasOwn(value, "findings") ||
+            (Array.isArray(value.findings) && value.findings.every(isReviewFinding))) &&
+        (!Object.hasOwn(value, "correctionAttempts") ||
+            (Array.isArray(value.correctionAttempts) &&
+                value.correctionAttempts.every(isCorrectionAttempt))) &&
+        (!Object.hasOwn(value, "adjudication") || isCorrectionAdjudication(value.adjudication)) &&
+        (!Object.hasOwn(value, "acceptedEvidence") || isAcceptedEvidence(value.acceptedEvidence)) &&
+        (!Object.hasOwn(value, "finished") ||
+            (isRecord(value.finished) &&
+                typeof value.finished.at === "string" &&
+                Number.isFinite(Date.parse(value.finished.at)) &&
+                typeof value.finished.author === "string" &&
+                !!value.finished.author.trim() &&
+                (!Object.hasOwn(value.finished, "report") ||
+                    (typeof value.finished.report === "string" && isAbsolute(value.finished.report))) &&
+                (!Object.hasOwn(value.finished, "reportSha256") ||
+                    (typeof value.finished.reportSha256 === "string" &&
+                        /^[0-9a-f]{64}$/i.test(value.finished.reportSha256))))));
+}
+export function isAcceptedEvidence(value) {
+    return (isRecord(value) &&
+        typeof value.snapshot === "string" &&
+        /^[0-9a-f]{64}$/i.test(value.snapshot) &&
+        typeof value.codeSnapshot === "string" &&
+        /^[0-9a-f]{64}$/i.test(value.codeSnapshot) &&
+        typeof value.requirementsSnapshot === "string" &&
+        /^[0-9a-f]{64}$/i.test(value.requirementsSnapshot) &&
+        Array.isArray(value.files) &&
+        value.files.length > 0 &&
+        value.files.every((path) => typeof path === "string" && isSafeCoveragePath(path)) &&
+        new Set(value.files).size === value.files.length &&
+        typeof value.contentDigest === "string" &&
+        /^[0-9a-f]{64}$/i.test(value.contentDigest));
+}
+export function isIntegrationRecord(value) {
+    return (isRecord(value) &&
+        typeof value.commitSha === "string" &&
+        /^[0-9a-f]{40,64}$/i.test(value.commitSha) &&
+        typeof value.integratedAt === "string" &&
+        Number.isFinite(Date.parse(value.integratedAt)) &&
+        typeof value.integratedBy === "string" &&
+        !!value.integratedBy.trim() &&
+        Array.isArray(value.files) &&
+        value.files.length > 0 &&
+        value.files.every((path) => typeof path === "string" && isSafeCoveragePath(path)) &&
+        new Set(value.files).size === value.files.length &&
+        typeof value.contentDigest === "string" &&
+        /^[0-9a-f]{64}$/i.test(value.contentDigest));
+}

package/build/SubagentDrivenDevelopment/Persistence/ReadinessReader.js

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { Service } from "../../Foundation/Service.js";
+export class ReadinessReader extends Service {
+    ticketRepository;
+    ledgerRepository;
+    pathSafety;
+    constructor(app, ticketRepository, ledgerRepository, pathSafety) {
+        super(app);
+        this.ticketRepository = ticketRepository;
+        this.ledgerRepository = ledgerRepository;
+        this.pathSafety = pathSafety;
+    }
+    read(feature) {
+        let ledger;
+        let tickets;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            this.pathSafety.assertReadyReadable(feature.workspace);
+            const ledgerRaw = readFileSync(feature.ledger, "utf8");
+            this.ledgerRepository.validateLedger(JSON.parse(ledgerRaw), feature.feature);
+            const observedTickets = this.ticketRepository.readTickets(feature.workspace);
+            this.pathSafety.assertReadyReadable(feature.workspace);
+            const confirmedLedgerRaw = readFileSync(feature.ledger, "utf8");
+            const confirmedLedger = this.ledgerRepository.validateLedger(JSON.parse(confirmedLedgerRaw), feature.feature);
+            const confirmedTickets = this.ticketRepository.readTickets(feature.workspace);
+            this.pathSafety.assertReadyReadable(feature.workspace);
+            const observedTicketContents = new Map(observedTickets.map((ticket) => [ticket.id, ticket.raw]));
+            const ticketsMatch = observedTicketContents.size === confirmedTickets.length &&
+                confirmedTickets.every((ticket) => observedTicketContents.get(ticket.id) === ticket.raw);
+            if (ledgerRaw === confirmedLedgerRaw && ticketsMatch) {
+                ledger = confirmedLedger;
+                tickets = confirmedTickets;
+                break;
+            }
+        }
+        if (!ledger || !tickets) {
+            throw new Error("Ticket data changed while reading the ready queue; retry ready.");
+        }
+        return { ledger, tickets };
+    }
+}

package/build/SubagentDrivenDevelopment/Persistence/ReviewSchema.js

@@ -0,0 +1,68 @@
+import { isAbsolute } from "node:path";
+import { Records } from "../../Support/Records.js";
+const isRecord = Records.isRecord;
+export function isReviewAssignment(value) {
+    if (!isRecord(value) ||
+        typeof value.id !== "string" ||
+        !value.id.trim() ||
+        typeof value.agent !== "string" ||
+        !value.agent.trim() ||
+        value.role !== "review" ||
+        !["initial", "corrective", "delivery"].includes(String(value.scope)) ||
+        (value.scope === "corrective" &&
+            (!Number.isSafeInteger(value.attempt) || Number(value.attempt) < 1)) ||
+        (value.scope === "initial" && Object.hasOwn(value, "attempt")) ||
+        (value.scope === "delivery" &&
+            Object.hasOwn(value, "attempt") &&
+            (!Number.isSafeInteger(value.attempt) || Number(value.attempt) < 1)) ||
+        typeof value.snapshot !== "string" ||
+        !/^[0-9a-f]{64}$/i.test(value.snapshot) ||
+        typeof value.codeSnapshot !== "string" ||
+        !/^[0-9a-f]{64}$/i.test(value.codeSnapshot) ||
+        typeof value.requirementsSnapshot !== "string" ||
+        !/^[0-9a-f]{64}$/i.test(value.requirementsSnapshot) ||
+        typeof value.headSha !== "string" ||
+        !/^[0-9a-f]{40,64}$/i.test(value.headSha) ||
+        !Array.isArray(value.inventory) ||
+        !value.inventory.every((path) => typeof path === "string" && path.length > 0) ||
+        new Set(value.inventory).size !== value.inventory.length ||
+        (Object.hasOwn(value, "objective") &&
+            (typeof value.objective !== "string" || !value.objective.trim())) ||
+        (Object.hasOwn(value, "details") &&
+            (typeof value.details !== "string" || !value.details.trim())) ||
+        typeof value.report !== "string" ||
+        !isAbsolute(value.report) ||
+        typeof value.requestedAt !== "string" ||
+        !Number.isFinite(Date.parse(value.requestedAt)) ||
+        !["pending", "submitted"].includes(String(value.status))) {
+        return false;
+    }
+    if (value.status === "pending")
+        return true;
+    return (["passed", "failed", "unavailable"].includes(String(value.result)) &&
+        (value.noFindings === true
+            ? value.findingIds === undefined
+            : value.noFindings === undefined &&
+                Array.isArray(value.findingIds) &&
+                value.findingIds.length > 0 &&
+                value.findingIds.every((id) => typeof id === "string" && /^F-\d{4,}$/.test(id)) &&
+                new Set(value.findingIds).size === value.findingIds.length) &&
+        typeof value.reportSha256 === "string" &&
+        /^[0-9a-f]{64}$/i.test(value.reportSha256) &&
+        typeof value.submittedAt === "string" &&
+        Number.isFinite(Date.parse(value.submittedAt)) &&
+        typeof value.submittedBy === "string" &&
+        !!value.submittedBy.trim() &&
+        (value.result === "passed" || (typeof value.details === "string" && !!value.details.trim())));
+}
+export function isSpecialistReviewRequirement(value) {
+    return (isRecord(value) &&
+        typeof value.agent === "string" &&
+        !!value.agent.trim() &&
+        typeof value.details === "string" &&
+        !!value.details.trim() &&
+        typeof value.author === "string" &&
+        !!value.author.trim() &&
+        typeof value.requestedAt === "string" &&
+        Number.isFinite(Date.parse(value.requestedAt)));
+}