@use-the-fork/spindle 0.0.2 → 0.2.0

package/build/SubagentDrivenDevelopment/Persistence/ProgressSchema.js

@@ -1,7 +1,7 @@
 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 { isCheckRequirement, isCheckRecord, isSafeCoveragePath, } from "./CheckSchema.js";
 import { isReviewFinding, isRequirementsDecision, } from "./FindingSchema.js";
 import { isReviewAssignment, isSpecialistReviewRequirement, } from "./ReviewSchema.js";
 import { Records } from "../../Support/Records.js";
@@ -41,9 +41,7 @@ export function isDeliveryProgress(value) {
                 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.checks, "invalidations"))) &&
         (!Object.hasOwn(value, "findings") ||
             (Array.isArray(value.findings) && value.findings.every(isReviewFinding))) &&
         (!Object.hasOwn(value, "correctionAttempts") ||
@@ -82,6 +80,17 @@ export function isIntegrationRecord(value) {
     return (isRecord(value) &&
         typeof value.commitSha === "string" &&
         /^[0-9a-f]{40,64}$/i.test(value.commitSha) &&
+        (!Object.hasOwn(value, "mergeSha") ||
+            (typeof value.mergeSha === "string" && /^[0-9a-f]{40,64}$/i.test(value.mergeSha))) &&
+        (!Object.hasOwn(value, "postMerge") ||
+            (isRecord(value.postMerge) &&
+                Object.keys(value.postMerge).every((key) => ["status", "mergeSha", "checks"].includes(key)) &&
+                (value.postMerge.status === "pending" || value.postMerge.status === "passed") &&
+                typeof value.mergeSha === "string" &&
+                value.postMerge.mergeSha === value.mergeSha &&
+                (!Object.hasOwn(value.postMerge, "checks") ||
+                    isPostMergeChecks(value.postMerge.checks, value.mergeSha, value.postMerge.status)) &&
+                (value.postMerge.status !== "passed" || Object.hasOwn(value.postMerge, "checks")))) &&
         typeof value.integratedAt === "string" &&
         Number.isFinite(Date.parse(value.integratedAt)) &&
         typeof value.integratedBy === "string" &&
@@ -93,3 +102,44 @@ export function isIntegrationRecord(value) {
         typeof value.contentDigest === "string" &&
         /^[0-9a-f]{64}$/i.test(value.contentDigest));
 }
+function isPostMergeChecks(value, mergeSha, status) {
+    if (!isRecord(value) ||
+        !Object.keys(value).every((key) => ["required", "records"].includes(key)) ||
+        !Array.isArray(value.required) ||
+        value.required.length === 0 ||
+        !value.required.every(isCheckRequirement) ||
+        value.required.some((item) => item.command !== item.command.trim() ||
+            !Object.keys(item).every((key) => ["command", "addedAt", "addedBy"].includes(key))) ||
+        value.required.some((item) => item.removedAt !== undefined ||
+            item.removedBy !== undefined ||
+            item.removalDetails !== undefined) ||
+        new Set(value.required.map((item) => item.command)).size !== value.required.length ||
+        !Array.isArray(value.records) ||
+        !value.records.every(isCheckRecord) ||
+        value.records.some((record) => record.headSha !== mergeSha ||
+            !Object.keys(record).every((key) => [
+                "command",
+                "result",
+                "author",
+                "snapshot",
+                "codeSnapshot",
+                "requirementsSnapshot",
+                "headSha",
+                "recordedAt",
+                "details",
+            ].includes(key)) ||
+            record.coveredPaths !== undefined ||
+            record.coverageSnapshot !== undefined))
+        return false;
+    const required = value.required;
+    if (value.records.some((record) => !required.some((item) => item.command === record.command)))
+        return false;
+    if (status === "pending")
+        return true;
+    const records = value.records;
+    const latest = value.required.map((item) => [...records].reverse().find((record) => record.command === item.command));
+    return latest.every((record) => record?.result === "passed" &&
+        record.snapshot === latest[0]?.snapshot &&
+        record.codeSnapshot === latest[0]?.codeSnapshot &&
+        record.requirementsSnapshot === latest[0]?.requirementsSnapshot);
+}

package/build/SubagentDrivenDevelopment/Persistence/ReviewSchema.js

@@ -23,6 +23,10 @@ export function isReviewAssignment(value) {
         !/^[0-9a-f]{64}$/i.test(value.requirementsSnapshot) ||
         typeof value.headSha !== "string" ||
         !/^[0-9a-f]{40,64}$/i.test(value.headSha) ||
+        (Object.hasOwn(value, "workspace") &&
+            (typeof value.workspace !== "string" || !isAbsolute(value.workspace))) ||
+        (Object.hasOwn(value, "branch") &&
+            (typeof value.branch !== "string" || !value.branch.trim())) ||
         !Array.isArray(value.inventory) ||
         !value.inventory.every((path) => typeof path === "string" && path.length > 0) ||
         new Set(value.inventory).size !== value.inventory.length ||

package/build/SubagentDrivenDevelopment/Policies/AssignmentPolicy.js

@@ -21,9 +21,6 @@ export class AssignmentPolicy extends Service {
         return undefined;
     }
     resumeBlocker(feature, progress) {
-        if (progress.execution === "claimed" && (!progress.owner || !progress.baseSha)) {
-            return "Claim has no recorded owner or baseline; implementation is unavailable.";
-        }
         if (progress.execution === "implementing" && !progress.assignment) {
             return "Implementation is marked in progress without a recorded assignment.";
         }

package/build/SubagentDrivenDevelopment/Policies/CheckPolicy.js

@@ -19,18 +19,21 @@ export class CheckPolicy extends Service {
             const records = checks.records.filter((record) => record.command === requirement.command);
             const preservedIntegrationEvidence = this.gitEvidence.integrationPreservesEvidence(progress, identity);
             const current = records.filter((record) => {
-                if (record.snapshot === identity.snapshot &&
+                if ((!progress.worktree || record.headSha === identity.headSha) &&
+                    record.snapshot === identity.snapshot &&
                     record.codeSnapshot === identity.codeSnapshot &&
                     record.requirementsSnapshot === identity.requirementsSnapshot) {
                     return true;
                 }
-                if (preservedIntegrationEvidence &&
+                if (!progress.worktree &&
+                    preservedIntegrationEvidence &&
                     record.snapshot === progress.acceptedEvidence?.snapshot &&
                     record.codeSnapshot === progress.acceptedEvidence?.codeSnapshot &&
                     record.requirementsSnapshot === progress.acceptedEvidence?.requirementsSnapshot) {
                     return true;
                 }
-                if (!record.coveredPaths ||
+                if ((progress.worktree && record.headSha !== identity.headSha) ||
+                    !record.coveredPaths ||
                     !record.coverageSnapshot ||
                     record.requirementsSnapshot !== identity.requirementsSnapshot) {
                     return false;

package/build/SubagentDrivenDevelopment/Policies/ReadinessPolicy.js

@@ -5,17 +5,27 @@ export class ReadinessPolicy extends Service {
         super(app);
         this.ticketRepository = ticketRepository;
     }
-    evaluate(tickets) {
-        this.ticketRepository.validateDependencyGraph(tickets);
+    static unmetDependencies(ticket, tickets, ledger) {
         const byId = new Map(tickets.map((item) => [item.id, item]));
+        const progressById = new Map(ledger.tickets.map((item) => [item.id, item]));
+        return ticket.blocked_by.filter((id) => {
+            const dependencyTicket = byId.get(id);
+            const progress = progressById.get(id);
+            return (!dependencyTicket ||
+                dependencyTicket.status !== "closed" ||
+                !!dependencyTicket.blocker ||
+                progress?.status !== "closed" ||
+                progress.execution !== "integrated" ||
+                progress.integration?.postMerge?.status !== "passed");
+        });
+    }
+    evaluate(tickets, ledger) {
+        this.ticketRepository.validateDependencyGraph(tickets);
         const eligible = tickets.filter((item) => item.status === "open" && !item.blocker);
         const ready = [];
         const unready = [];
         for (const item of eligible) {
-            const pending = item.blocked_by.filter((id) => {
-                const dependencyTicket = byId.get(id);
-                return (!dependencyTicket || dependencyTicket.status !== "closed" || !!dependencyTicket.blocker);
-            });
+            const pending = ReadinessPolicy.unmetDependencies(item, tickets, ledger);
             if (pending.length === 0)
                 ready.push(item.id);
             else

package/build/SubagentDrivenDevelopment/Policies/ReviewPolicy.js

@@ -33,7 +33,16 @@ export class ReviewPolicy extends Service {
         return undefined;
     }
     reviewSnapshotBlocker(feature, progress, assignment, identity) {
+        if ("id" in progress && progress.worktree) {
+            try {
+                this.gitEvidence.assertTicketCodeCommitted(progress);
+            }
+            catch (error) {
+                return `Ticket review workspace is invalid: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
         const integratedEvidence = assignment.scope !== "delivery" &&
+            !("worktree" in progress && progress.worktree) &&
             this.gitEvidence.integrationPreservesEvidence(progress, identity) &&
             assignment.snapshot === progress.acceptedEvidence?.snapshot &&
             assignment.codeSnapshot === progress.acceptedEvidence?.codeSnapshot &&
@@ -42,14 +51,19 @@ export class ReviewPolicy extends Service {
         if (!integratedEvidence &&
             (assignment.snapshot !== identity.snapshot ||
                 assignment.codeSnapshot !== identity.codeSnapshot ||
-                assignment.requirementsSnapshot !== identity.requirementsSnapshot)) {
+                assignment.requirementsSnapshot !== identity.requirementsSnapshot ||
+                ("worktree" in progress &&
+                    !!progress.worktree &&
+                    (assignment.headSha !== identity.headSha ||
+                        assignment.workspace !== progress.worktree.workspace ||
+                        assignment.branch !== progress.worktree.branch)))) {
             return `Review assignment ${assignment.id} is stale for the current ticket snapshot.`;
         }
         if (!progress.baseSha)
             return "Review assignment has no recorded Git baseline.";
         let inventory;
         try {
-            inventory = this.gitEvidence.changedPaths(progress.baseSha);
+            inventory = this.gitEvidence.changedPaths(progress.baseSha, "id" in progress ? this.gitEvidence.ticketWorkspace(progress) : undefined);
         }
         catch (error) {
             return `Review inventory cannot be revalidated: ${error instanceof Error ? error.message : String(error)}`;

package/build/SubagentDrivenDevelopment/Policies/WorkflowPolicy.js

@@ -7,10 +7,7 @@ export class WorkflowPolicy extends Service {
         if (progress.adjudication?.status === "pending")
             return "adjudicate";
         if (progress.execution === "unstarted")
-            return "claim";
-        if (progress.execution === "claimed") {
-            return progress.owner && progress.baseSha ? "implement" : "resolve-claim-blocker";
-        }
+            return "implement";
         if (progress.execution === "implementing") {
             if (!progress.assignment)
                 return "resolve-assignment-blocker";
@@ -38,7 +35,7 @@ export class WorkflowPolicy extends Service {
                 if (reviews.some((assignment) => assignment.result !== "passed")) {
                     return "resolve-review-result";
                 }
-                return "accept";
+                return "integrate";
             }
             return blocker ? "restore-implementation-report" : "review";
         }
@@ -52,10 +49,13 @@ export class WorkflowPolicy extends Service {
                 ? "correct"
                 : "controller-correction-decision";
         }
-        if (progress.execution === "accepted")
-            return blocker ? "resolve-check-blocker" : "integrate";
-        if (progress.execution === "integrated")
+        if (progress.execution === "integrated") {
+            if (progress.integration?.postMerge?.status !== "passed")
+                return "post-merge-checks";
+            if (progress.status !== "closed")
+                return "verify-ticket-closure";
             return blocker ? "resolve-check-blocker" : "complete";
+        }
         return "resolve-blocker";
     }
     requireProgress(ledger, ticket) {

package/build/SubagentDrivenDevelopment/Services/AssignmentService.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import matter from "gray-matter";
 import { Service } from "../../Foundation/Service.js";
 import { lstatIfPresent } from "../Persistence/FileSystem.js";
@@ -13,9 +14,12 @@ export class AssignmentService extends Service {
     assignmentPolicy;
     checkPolicy;
     reviewPolicy;
+    readinessPolicy;
     workflowPolicy;
     featureInspectionService;
-    constructor(app, gitEvidence, reportEvidence, ticketRepository, ledgerRepository, workspaceTransaction, assignmentPolicy, checkPolicy, reviewPolicy, workflowPolicy, featureInspectionService) {
+    ticketWorktreeService;
+    workflowRecordsCommitter;
+    constructor(app, gitEvidence, reportEvidence, ticketRepository, ledgerRepository, workspaceTransaction, assignmentPolicy, checkPolicy, reviewPolicy, readinessPolicy, workflowPolicy, featureInspectionService, ticketWorktreeService, workflowRecordsCommitter) {
         super(app);
         this.gitEvidence = gitEvidence;
         this.reportEvidence = reportEvidence;
@@ -25,10 +29,13 @@ export class AssignmentService extends Service {
         this.assignmentPolicy = assignmentPolicy;
         this.checkPolicy = checkPolicy;
         this.reviewPolicy = reviewPolicy;
+        this.readinessPolicy = readinessPolicy;
         this.workflowPolicy = workflowPolicy;
         this.featureInspectionService = featureInspectionService;
+        this.ticketWorktreeService = ticketWorktreeService;
+        this.workflowRecordsCommitter = workflowRecordsCommitter;
     }
-    claim(options) {
+    implement(options) {
         validateTicketId(options.ticket);
         validateAuthor(options.author);
         const feature = this.featureInspectionService.resolveFeature(options.spec);
@@ -38,84 +45,98 @@ export class AssignmentService extends Service {
             this.ticketRepository.validateDependencyGraph(tickets);
             const ticket = this.ticketRepository.requireTicket(tickets, options.ticket);
             const progress = this.workflowPolicy.requireProgress(ledger, options.ticket);
-            if (progress.execution !== "unstarted") {
-                throw new Error(`Ticket ${options.ticket} is already owned or has progressed to ${progress.execution}.`);
-            }
-            if (ticket.status !== "open" || ticket.blocker) {
-                throw new Error(`Ticket ${options.ticket} is not open and unblocked.`);
-            }
-            const ticketsById = new Map(tickets.map((item) => [item.id, item]));
-            const unmet = ticket.blocked_by.filter((dependency) => {
-                const dependencyTicket = ticketsById.get(dependency);
-                return (!dependencyTicket || dependencyTicket.status !== "closed" || !!dependencyTicket.blocker);
-            });
-            if (unmet.length > 0) {
-                throw new Error(`Ticket ${options.ticket} has open dependencies: ${unmet.join(", ")}.`);
-            }
-            const baseSha = this.gitEvidence.cleanGitBaseline(feature);
-            progress.execution = "claimed";
-            progress.status = "in-progress";
-            progress.owner = options.author.trim();
-            progress.baseSha = baseSha;
-            ledger.delivery.baseSha ??= baseSha;
-            const identity = this.gitEvidence.contentIdentity(feature, ticket, baseSha, progress.checks);
-            const afterTicket = matter.stringify(this.ticketRepository.appendAudit(ticket.body, options.author, `Claimed from clean Git baseline ${baseSha}.`), this.ticketRepository.metadata(ticket));
-            this.workspaceTransaction.writeWorkflowState(feature, ticket, afterTicket, ledger);
-            return {
-                ticket: options.ticket,
-                execution: "claimed",
-                owner: options.author.trim(),
-                baseSha,
-                ...identity,
-            };
-        });
-    }
-    implement(options) {
-        validateTicketId(options.ticket);
-        validateAuthor(options.author);
-        const feature = this.featureInspectionService.resolveFeature(options.spec);
-        return this.workspaceTransaction.run(feature.workspace, () => {
-            const ledger = this.ledgerRepository.readLedger(feature);
-            const ticket = this.ticketRepository.requireTicket(this.ticketRepository.readTickets(feature.workspace), options.ticket);
-            const progress = this.workflowPolicy.requireProgress(ledger, options.ticket);
-            const identity = this.gitEvidence.contentIdentity(feature, ticket, progress.baseSha, progress.checks);
             if (progress.execution === "implementing" && progress.assignment) {
                 if (progress.owner !== options.author.trim()) {
                     throw new Error("Controller ownership changed; resume and confirm the handoff first.");
                 }
+                if (!progress.worktree ||
+                    !options.workspace ||
+                    !isAbsolute(options.workspace) ||
+                    join(realpathSync(options.workspace), `${feature.feature}-${options.ticket}`) !==
+                        progress.worktree.workspace) {
+                    throw new Error("Resume implementation using the originally assigned --workspace directory.");
+                }
                 return {
                     ticket: options.ticket,
                     execution: "implementing",
                     assignment: progress.assignment,
-                    ...identity,
+                    ...this.gitEvidence.contentIdentity(feature, ticket, progress.baseSha, progress.checks),
                 };
             }
-            if (progress.execution !== "claimed" || !progress.baseSha || !progress.owner) {
-                throw new Error(`Ticket ${options.ticket} must be claimed before implementation dispatch.`);
+            if (progress.execution !== "unstarted") {
+                throw new Error(`Ticket ${options.ticket} is already owned or has progressed to ${progress.execution}.`);
+            }
+            if (ticket.status !== "open" || ticket.blocker) {
+                throw new Error(`Ticket ${options.ticket} is not open and unblocked.`);
+            }
+            const readiness = this.readinessPolicy.evaluate(tickets, ledger);
+            if (!readiness.ready.includes(options.ticket)) {
+                const unready = readiness.unready.find((item) => item.ticket === options.ticket);
+                const dependencies = unready?.blockedBy ?? ticket.blocked_by;
+                throw new Error(dependencies.length > 0
+                    ? `Ticket ${options.ticket} has open dependencies: ${dependencies.join(", ")}.`
+                    : `Ticket ${options.ticket} is not ready for implementation.`);
             }
-            if (progress.owner !== options.author.trim()) {
-                throw new Error("Only the recorded controller may dispatch implementation.");
+            if (!options.workspace || !isAbsolute(options.workspace)) {
+                throw new Error("--workspace must be an absolute existing external directory.");
             }
             const report = join(feature.workspace, "reports", `${options.ticket}-implementation.md`);
             this.reportEvidence.assertReportPath(feature, report, false);
             if (lstatIfPresent(report)) {
                 throw new Error(`Assigned report already exists and was preserved: ${report}.`);
             }
+            const pendingPostMerge = ledger.tickets.some((candidate) => (candidate.integration ?? candidate.integrationHistory?.at(-1))?.postMerge?.status ===
+                "pending");
+            if (!pendingPostMerge) {
+                this.workflowRecordsCommitter.commit(feature, options.confirmRecords === true);
+            }
+            const baseSha = this.gitEvidence.cleanDispatchBaseline(feature, pendingPostMerge);
+            progress.status = "in-progress";
+            progress.owner = options.author.trim();
+            progress.baseSha = baseSha;
+            ledger.delivery.baseSha ??= baseSha;
+            const requiredAncestors = ticket.blocked_by.map((id) => {
+                const dependency = this.workflowPolicy.requireProgress(ledger, id);
+                const mergeSha = dependency.integration?.mergeSha;
+                if (!mergeSha || dependency.integration?.postMerge?.status !== "passed") {
+                    throw new Error(`Ticket ${id} is not integrated and post-merge validated.`);
+                }
+                return mergeSha;
+            });
+            const worktree = this.ticketWorktreeService.create(feature, progress, options.workspace, requiredAncestors, pendingPostMerge);
             const assignment = {
                 id: randomUUID(),
                 role: "implementation",
                 action: "implement",
                 controller: options.author.trim(),
                 report,
+                workspace: worktree.workspace,
+                branch: worktree.branch,
                 requestedAt: new Date().toISOString(),
                 status: "pending",
                 handoffs: [],
             };
             progress.execution = "implementing";
             progress.assignment = assignment;
+            progress.baseSha = worktree.baseSha;
+            progress.worktree = {
+                workspace: worktree.workspace,
+                branch: worktree.branch,
+                baseSha: worktree.baseSha,
+            };
             const afterTicket = matter.stringify(this.ticketRepository.appendAudit(ticket.body, options.author, `Implementation assignment ${assignment.id} recorded; role=implementation; report=${report}. No agent was launched.`), this.ticketRepository.metadata(ticket));
-            this.workspaceTransaction.writeWorkflowState(feature, ticket, afterTicket, ledger);
-            return { ticket: options.ticket, execution: "implementing", assignment, ...identity };
+            try {
+                this.workspaceTransaction.writeWorkflowState(feature, ticket, afterTicket, ledger);
+            }
+            catch (error) {
+                throw new Error(`Assignment recording failed; preserve and inspect ${worktree.journal}. ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return {
+                ticket: options.ticket,
+                execution: "implementing",
+                assignment,
+                ...this.gitEvidence.contentIdentity(feature, ticket, progress.baseSha, progress.checks),
+            };
         });
     }
     resume(options) {
@@ -135,6 +156,7 @@ export class AssignmentService extends Service {
             const ledger = this.ledgerRepository.readLedger(feature);
             const ticket = this.ticketRepository.requireTicket(this.ticketRepository.readTickets(feature.workspace), options.ticket);
             const progress = this.workflowPolicy.requireProgress(ledger, options.ticket);
+            this.gitEvidence.ticketWorkspace(progress);
             let handoffRecorded = false;
             if (progress.owner && progress.owner !== options.author.trim()) {
                 if (!options.confirmHandoff) {