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

package/build/SubagentDrivenDevelopment/Evidence/GitEvidence.js

@@ -0,0 +1,449 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, readlinkSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import matter from "gray-matter";
+import { Service } from "../../Foundation/Service.js";
+import { isSafeCoveragePath } from "../Persistence/CheckSchema.js";
+import { lstatIfPresent, isPathInside } from "../Persistence/FileSystem.js";
+export class GitEvidence extends Service {
+    git;
+    ledgerRepository;
+    constructor(app, git, ledgerRepository) {
+        super(app);
+        this.git = git;
+        this.ledgerRepository = ledgerRepository;
+    }
+    allGitChangePaths() {
+        const paths = new Set();
+        for (const args of [
+            ["diff", "--name-only", "-z", "--no-renames", "HEAD", "--", "."],
+            ["diff", "--cached", "--name-only", "-z", "--no-renames", "HEAD", "--", "."],
+            ["ls-files", "--others", "--exclude-standard", "-z"],
+        ]) {
+            for (const path of this.gitBuffer(args).toString("utf8").split("\0")) {
+                if (path)
+                    paths.add(path);
+            }
+        }
+        return [...paths].sort();
+    }
+    deliveryRecordPaths(feature, ledger = this.ledgerRepository.readLedger(feature)) {
+        const lockPath = `.scratch/${feature.feature}/.sdd-tickets.lock`;
+        const allowed = this.workflowDeliveryRecordPaths(feature, ledger);
+        return this.allGitChangePaths().filter((path) => path !== lockPath && allowed.has(path));
+    }
+    workflowDeliveryRecordPaths(feature, ledger) {
+        const root = realpathSync(this.app.workspaceRoot);
+        const featurePrefix = `.scratch/${feature.feature}/`;
+        const paths = new Set([
+            relative(root, feature.spec),
+            relative(root, feature.ledger),
+            ...ledger.tickets.map((ticket) => `${featurePrefix}tickets/${ticket.id}.md`),
+        ]);
+        const reports = join(feature.workspace, "reports");
+        const addReport = (report) => {
+            if (!report)
+                return;
+            const path = isAbsolute(report) ? resolve(report) : resolve(feature.workspace, report);
+            if (isPathInside(reports, path) && /^[^/]+\.md$/.test(relative(reports, path))) {
+                paths.add(relative(root, path));
+            }
+        };
+        for (const ticket of ledger.tickets) {
+            addReport(ticket.assignment?.report);
+            for (const assignment of [
+                ...(ticket.reviewAssignments ?? []),
+                ...(ticket.reviewHistory ?? []),
+            ]) {
+                addReport(assignment.report);
+            }
+            for (const attempt of ticket.correctionAttempts ?? []) {
+                addReport(attempt.assignment.report);
+                addReport(attempt.priorAssignment?.report);
+                for (const assignment of attempt.reviewAssignments ?? [])
+                    addReport(assignment.report);
+            }
+            for (const finding of ticket.findings ?? []) {
+                for (const provenance of finding.provenance)
+                    addReport(provenance.report);
+            }
+        }
+        return paths;
+    }
+    worktreeContentDigest(paths) {
+        const records = paths.map((path) => {
+            const location = join(this.app.workspaceRoot, path);
+            const entry = lstatIfPresent(location);
+            if (!entry)
+                return [path, "deleted", ""];
+            if (entry.isSymbolicLink()) {
+                return [path, "120000", readlinkSync(location)];
+            }
+            if (!entry.isFile()) {
+                throw new Error(`Accepted path '${path}' is not a regular file or symlink.`);
+            }
+            const mode = entry.mode & 0o111 ? "100755" : "100644";
+            return [path, mode, readFileSync(location).toString("base64")];
+        });
+        return createHash("sha256").update(JSON.stringify(records)).digest("hex");
+    }
+    gitTreeContentDigest(commitSha, paths) {
+        const records = paths.map((path) => {
+            const entries = this.gitBuffer(["ls-tree", "-z", commitSha, "--", `:(literal)${path}`])
+                .toString("utf8")
+                .split("\0")
+                .filter(Boolean);
+            const exact = entries
+                .map((entry) => {
+                const [metadata, treePath] = entry.split("\t", 2);
+                const [mode, type, object] = (metadata ?? "").split(" ");
+                return treePath === path && mode && type === "blob" && object
+                    ? { mode, object }
+                    : undefined;
+            })
+                .find((entry) => entry !== undefined);
+            if (!exact)
+                return [path, "deleted", ""];
+            const content = this.gitBuffer(["cat-file", "blob", exact.object]).toString("base64");
+            return [path, exact.mode, content];
+        });
+        return createHash("sha256").update(JSON.stringify(records)).digest("hex");
+    }
+    gitIndexContentDigest(paths) {
+        const records = paths.map((path) => {
+            const entries = this.gitBuffer(["ls-files", "--stage", "-z", "--", `:(literal)${path}`])
+                .toString("utf8")
+                .split("\0")
+                .filter(Boolean);
+            if (entries.length !== 1)
+                return [path, "invalid-index-entry", ""];
+            const separator = entries[0].indexOf("\t");
+            if (separator < 0 || entries[0].slice(separator + 1) !== path) {
+                return [path, "invalid-index-entry", ""];
+            }
+            const [mode, object, stage] = entries[0].slice(0, separator).split(" ");
+            if (stage !== "0" ||
+                !object ||
+                (mode !== "100644" && mode !== "100755" && mode !== "120000")) {
+                return [path, "invalid-index-entry", ""];
+            }
+            const content = this.gitBuffer(["cat-file", "blob", object]).toString("base64");
+            return [path, mode, content];
+        });
+        return createHash("sha256").update(JSON.stringify(records)).digest("hex");
+    }
+    cleanGitBaseline(feature) {
+        const root = realpathSync(this.app.workspaceRoot);
+        const changes = this.gitChangeSummary(feature);
+        if (changes) {
+            const deliveryRecords = this.deliveryRecordPaths(feature);
+            if (deliveryRecords.length > 0) {
+                throw new Error(`Cannot claim while uncommitted delivery records remain; the caller must commit them first:\n${deliveryRecords.join("\n")}`);
+            }
+            throw new Error(`Cannot claim from a dirty checkout; commit or otherwise resolve staged, unstaged, and untracked changes first:\n${changes}`);
+        }
+        const revision = this.git.run(["rev-parse", "--verify", "HEAD"], {
+            cwd: root,
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        if (revision.error)
+            throw revision.error;
+        if (revision.status !== 0 || !/^[0-9a-f]{40,64}\n?$/i.test(revision.stdout)) {
+            throw new Error(`Unable to record the clean checkout's starting commit: ${revision.stderr.trim()}`);
+        }
+        return revision.stdout.trim();
+    }
+    contentIdentity(feature, ticket, baseSha = this.headSha(), checks, coveredPaths) {
+        const root = realpathSync(this.app.workspaceRoot);
+        const headSha = this.headSha();
+        const changedPaths = this.changedPaths(baseSha);
+        const paths = new Set(coveredPaths ?? changedPaths);
+        if (coveredPaths) {
+            for (const path of paths) {
+                if (!isSafeCoveragePath(path) || !isPathInside(root, resolve(root, path))) {
+                    throw new Error(`Unsafe path in content identity scope: ${path}.`);
+                }
+            }
+        }
+        const code = createHash("sha256");
+        code.update("spindle-code-snapshot-v2\0");
+        const field = (tag, value) => {
+            const tagBytes = Buffer.from(tag);
+            const valueBytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            const tagLength = Buffer.alloc(4);
+            tagLength.writeUInt32BE(tagBytes.length);
+            const valueLength = Buffer.alloc(8);
+            valueLength.writeBigUInt64BE(BigInt(valueBytes.length));
+            code.update(tagLength);
+            code.update(tagBytes);
+            code.update(valueLength);
+            code.update(valueBytes);
+        };
+        for (const path of [...paths].sort()) {
+            field("record", "path");
+            field("path", path);
+            field("index-stage", this.gitBuffer(["ls-files", "--stage", "-z", "--", `:(literal)${path}`]));
+            const indexed = this.git.run(["show", `:${path}`], {
+                cwd: root,
+                encoding: "buffer",
+                env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+            });
+            if (indexed.error)
+                throw indexed.error;
+            field("index-state", indexed.status === 0 ? "present" : "absent");
+            if (indexed.status === 0)
+                field("index-content", indexed.stdout);
+            const pathOnDisk = join(root, path);
+            const entry = lstatIfPresent(pathOnDisk);
+            if (!entry) {
+                field("worktree-state", "deleted");
+            }
+            else {
+                field("worktree-mode", String(entry.mode & 0o777));
+                if (entry.isSymbolicLink()) {
+                    field("worktree-type", "symlink");
+                    field("worktree-target", readlinkSync(pathOnDisk));
+                }
+                else if (entry.isFile()) {
+                    field("worktree-type", "file");
+                    field("worktree-content", readFileSync(pathOnDisk));
+                }
+                else if (entry.isDirectory()) {
+                    throw new Error(`Cannot compute code identity for nested repository or worktree '${path}'; directory worktrees are unsupported.`);
+                }
+                else {
+                    throw new Error(`Cannot compute code identity for unsupported non-file worktree path '${path}'.`);
+                }
+            }
+        }
+        const codeSnapshot = code.digest("hex");
+        const requirementParts = [
+            readFileSync(feature.spec, "utf8"),
+            this.ticketRequirements(ticket.raw),
+            checks?.required ?? [],
+        ];
+        const requirementsSnapshot = createHash("sha256")
+            .update(JSON.stringify(requirementParts))
+            .digest("hex");
+        const snapshot = createHash("sha256")
+            .update(JSON.stringify([codeSnapshot, requirementsSnapshot]))
+            .digest("hex");
+        return { snapshot, codeSnapshot, requirementsSnapshot, headSha };
+    }
+    deliveryIdentity(feature, ledger, tickets) {
+        if (tickets.length === 0)
+            throw new Error("Aggregate evidence requires at least one ticket.");
+        const delivery = ledger.delivery;
+        delivery.baseSha ??= ledger.tickets.find((progress) => progress.baseSha)?.baseSha;
+        if (!delivery.baseSha) {
+            throw new Error("Aggregate evidence requires the first ticket's recorded Git baseline.");
+        }
+        const codeIdentity = this.contentIdentity(feature, tickets[0], delivery.baseSha);
+        const requirementsSnapshot = createHash("sha256")
+            .update(JSON.stringify([
+            readFileSync(feature.spec, "utf8"),
+            tickets.map((ticket) => [
+                ticket.id,
+                ticket.title,
+                ticket.reporter,
+                ticket.category,
+                ticket.status,
+                ticket.blocked_by,
+                ticket.blocker,
+                this.ticketRequirements(ticket.raw),
+            ]),
+            (delivery.checks?.required ?? []).filter((requirement) => !requirement.removedAt),
+        ]))
+            .digest("hex");
+        const snapshot = createHash("sha256")
+            .update(JSON.stringify([codeIdentity.codeSnapshot, requirementsSnapshot]))
+            .digest("hex");
+        return {
+            snapshot,
+            codeSnapshot: codeIdentity.codeSnapshot,
+            requirementsSnapshot,
+            headSha: codeIdentity.headSha,
+        };
+    }
+    changedPaths(baseSha) {
+        const paths = new Set();
+        for (const args of [
+            ["diff", "--name-only", "-z", baseSha, "--", "."],
+            ["diff", "--cached", "--name-only", "-z", baseSha, "--", "."],
+            ["ls-files", "--others", "--exclude-standard", "-z"],
+        ]) {
+            const output = this.gitBuffer(args).toString("utf8");
+            for (const path of output.split("\0")) {
+                if (path && path !== ".scratch" && !path.startsWith(".scratch/"))
+                    paths.add(path);
+            }
+        }
+        this.assertStableSubmodules(baseSha, paths);
+        return [...paths].sort();
+    }
+    assertStableSubmodules(baseSha, changedPaths) {
+        const gitlinks = new Map();
+        for (const record of this.gitBuffer(["ls-files", "--stage", "-z"])
+            .toString("utf8")
+            .split("\0")) {
+            const [metadata, path] = record.split("\t", 2);
+            if (!metadata || !path || path === ".scratch" || path.startsWith(".scratch/"))
+                continue;
+            const [mode, sha, stage] = metadata.split(" ");
+            if (mode === "160000" && sha && stage === "0")
+                gitlinks.set(path, sha);
+        }
+        const knownPaths = new Set(gitlinks.keys());
+        for (const record of this.gitBuffer(["ls-tree", "-r", "-z", baseSha])
+            .toString("utf8")
+            .split("\0")) {
+            const [metadata, path] = record.split("\t", 2);
+            if (metadata?.startsWith("160000 commit ") &&
+                path &&
+                path !== ".scratch" &&
+                !path.startsWith(".scratch/")) {
+                knownPaths.add(path);
+            }
+        }
+        for (const path of knownPaths) {
+            const entry = lstatIfPresent(join(this.app.workspaceRoot, path));
+            if (!entry) {
+                throw new Error(`Cannot compute code identity for submodule '${path}'; its worktree is missing or uninitialized.`);
+            }
+            if (!entry.isDirectory()) {
+                throw new Error(`Cannot compute code identity for submodule '${path}'; its worktree state is unsupported.`);
+            }
+            if (changedPaths.has(path)) {
+                throw new Error(`Cannot compute code identity for changed submodule '${path}'; submodule changes are unsupported.`);
+            }
+            if (!gitlinks.has(path))
+                continue;
+            let revision;
+            try {
+                revision = this.gitBuffer(["-C", path, "rev-parse", "--verify", "HEAD"])
+                    .toString("utf8")
+                    .trim();
+            }
+            catch {
+                throw new Error(`Cannot compute code identity for submodule '${path}'; its worktree is missing or uninitialized.`);
+            }
+            const status = this.gitBuffer([
+                "-C",
+                path,
+                "status",
+                "--porcelain",
+                "--untracked-files=all",
+                "--ignore-submodules=none",
+            ]).toString("utf8");
+            if (revision !== gitlinks.get(path) || status.length > 0) {
+                throw new Error(`Cannot compute code identity for changed submodule '${path}'; submodule changes are unsupported.`);
+            }
+        }
+    }
+    ticketRequirements(raw) {
+        const body = matter(raw).content;
+        const sections = new Map();
+        const headings = [...body.matchAll(/^##[ \t]+(.+?)[ \t]*\r?$/gm)];
+        for (let index = 0; index < headings.length; index++) {
+            const heading = headings[index];
+            const title = heading[1].trim().toLowerCase();
+            const start = heading.index + heading[0].length;
+            const end = headings[index + 1]?.index ?? body.length;
+            if (title === "requirements" || title === "acceptance criteria") {
+                sections.set(title, body.slice(start, end).trim());
+            }
+            if (title === "comments") {
+                const decisions = body
+                    .slice(start, end)
+                    .split(/\n[ \t]*\n/)
+                    .filter((entry) => !entry.startsWith("[SDD-SCOPE-RULING ") && /\brequirements? decision\b/i.test(entry))
+                    .map((entry) => entry.trim());
+                sections.set("requirements decisions", decisions.join("\n\n"));
+            }
+        }
+        return JSON.stringify([...sections.entries()].sort(([left], [right]) => left.localeCompare(right)));
+    }
+    headSha() {
+        const revision = this.git.run(["rev-parse", "--verify", "HEAD"], {
+            cwd: realpathSync(this.app.workspaceRoot),
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        if (revision.error)
+            throw revision.error;
+        if (revision.status !== 0 || !/^[0-9a-f]{40,64}\n?$/i.test(revision.stdout)) {
+            throw new Error(`Unable to identify current Git revision: ${revision.stderr.trim()}`);
+        }
+        return revision.stdout.trim();
+    }
+    gitBuffer(args) {
+        const result = this.git.run(args, {
+            cwd: realpathSync(this.app.workspaceRoot),
+            encoding: "buffer",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0) {
+            throw new Error(`git ${args[0]} failed: ${result.stderr.toString("utf8").trim()}`);
+        }
+        return result.stdout;
+    }
+    gitChangeSummary(feature) {
+        const root = realpathSync(this.app.workspaceRoot);
+        const relativeLock = relative(root, join(feature.workspace, ".sdd-tickets.lock"));
+        const status = this.git.run([
+            "--no-pager",
+            "-c",
+            "color.ui=false",
+            "status",
+            "--porcelain=v1",
+            "--untracked-files=all",
+            "--",
+            ".",
+            `:(exclude)${relativeLock}`,
+        ], {
+            cwd: root,
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        });
+        if (status.error)
+            throw status.error;
+        if (status.status !== 0) {
+            throw new Error(`git status failed while checking claim readiness: ${status.stderr.trim()}`);
+        }
+        return status.stdout.trim();
+    }
+    integrationPreservesEvidence(progress, identity) {
+        if (!("id" in progress))
+            return false;
+        const accepted = progress.acceptedEvidence;
+        if (progress.execution !== "integrated" ||
+            !progress.integration ||
+            !accepted ||
+            !progress.baseSha ||
+            identity.requirementsSnapshot !== accepted.requirementsSnapshot) {
+            return false;
+        }
+        try {
+            return (progress.integration.contentDigest === accepted.contentDigest &&
+                JSON.stringify(progress.integration.files) === JSON.stringify(accepted.files) &&
+                JSON.stringify(this.changedPaths(progress.baseSha)) === JSON.stringify(accepted.files) &&
+                this.worktreeContentDigest(accepted.files) === accepted.contentDigest);
+        }
+        catch {
+            return false;
+        }
+    }
+    assertSafeIntegrationChanges(feature, acceptedFiles, ledger) {
+        const allowed = new Set(acceptedFiles);
+        for (const path of this.workflowDeliveryRecordPaths(feature, ledger))
+            allowed.add(path);
+        const lockPath = `.scratch/${feature.feature}/.sdd-tickets.lock`;
+        const unrelated = this.allGitChangePaths().filter((path) => path !== lockPath && !allowed.has(path));
+        if (unrelated.length > 0) {
+            throw new Error(`Unsafe unrelated pending changes prevent integration: ${JSON.stringify(unrelated)}.`);
+        }
+    }
+}

package/build/SubagentDrivenDevelopment/Evidence/ReportEvidence.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { Service } from "../../Foundation/Service.js";
+import { lstatIfPresent, isPathInside } from "../Persistence/FileSystem.js";
+export class ReportEvidence extends Service {
+    pathSafety;
+    constructor(app, pathSafety) {
+        super(app);
+        this.pathSafety = pathSafety;
+    }
+    assertReportPath(feature, path, mustExist) {
+        const reports = join(feature.workspace, "reports");
+        const directory = lstatIfPresent(reports);
+        if (!directory?.isDirectory() || directory.isSymbolicLink()) {
+            throw new Error("Feature reports path must be a real directory.");
+        }
+        if (!isPathInside(reports, path) || !/^[^/]+\.md$/.test(path.slice(reports.length + 1))) {
+            throw new Error("Implementation report must be a Markdown file inside feature reports/.");
+        }
+        const root = realpathSync(this.app.workspaceRoot);
+        if (!isPathInside(root, path) || !isPathInside(root, realpathSync(reports))) {
+            throw new Error("Implementation report must remain inside this checkout.");
+        }
+        const relativePath = relative(root, path);
+        if (this.pathSafety.isIgnored(root, relativePath)) {
+            throw new Error(`Implementation report path is ignored: ${relativePath}`);
+        }
+        const entry = lstatIfPresent(path);
+        if (mustExist && !entry)
+            throw Object.assign(new Error("Report does not exist."), { code: "ENOENT" });
+        if (entry && (!entry.isFile() || entry.isSymbolicLink())) {
+            throw new Error(`Implementation report must be a regular file: ${path}.`);
+        }
+        if (entry && !isPathInside(reports, realpathSync(path))) {
+            throw new Error("Implementation report must remain inside feature reports/.");
+        }
+    }
+    submissionReportPath(feature, assignment, supplied) {
+        const path = supplied
+            ? isAbsolute(supplied)
+                ? resolve(supplied)
+                : resolve(feature.workspace, supplied)
+            : assignment.report;
+        if (path !== assignment.report) {
+            throw new Error(`Report target does not match the assigned destination ${assignment.report}.`);
+        }
+        this.assertReportPath(feature, path, false);
+        return path;
+    }
+    readReportDigest(feature, report) {
+        this.assertReportPath(feature, report, true);
+        return createHash("sha256").update(readFileSync(report)).digest("hex");
+    }
+    assertAcceptedReportsCurrent(feature, progress) {
+        const implementationReports = [
+            progress.assignment,
+            ...(progress.correctionAttempts ?? []).flatMap((attempt) => [attempt.assignment]),
+        ].filter((assignment) => !!assignment);
+        for (const assignment of implementationReports) {
+            if (assignment.status !== "submitted" || !assignment.reportSha256) {
+                throw new Error(`Implementation report for ${assignment.id} is not current and submitted.`);
+            }
+            if (this.readReportDigest(feature, assignment.report) !== assignment.reportSha256) {
+                throw new Error(`Implementation report for ${assignment.id} changed after submission.`);
+            }
+        }
+        const reviewReports = [
+            ...(progress.reviewAssignments ?? []),
+            ...(progress.correctionAttempts ?? []).flatMap((attempt) => attempt.reviewAssignments ?? []),
+        ];
+        for (const assignment of reviewReports) {
+            if (assignment.status !== "submitted" ||
+                !assignment.reportSha256 ||
+                this.readReportDigest(feature, assignment.report) !== assignment.reportSha256) {
+                throw new Error(`Review report for ${assignment.id} is not current and submitted.`);
+            }
+        }
+    }
+}

package/build/SubagentDrivenDevelopment/Models/Assignments.js

@@ -0,0 +1 @@
+export {};

package/build/SubagentDrivenDevelopment/Models/Evidence.js

@@ -0,0 +1 @@
+export {};

package/build/SubagentDrivenDevelopment/Models/Findings.js

@@ -0,0 +1 @@
+export {};

package/build/SubagentDrivenDevelopment/Models/Options.js

@@ -0,0 +1 @@
+export {};

package/build/SubagentDrivenDevelopment/Models/Workflow.js

@@ -0,0 +1,16 @@
+export const FEATURE_DIRECTORY = /^(\d{4,})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+export const HISTORICAL_DATE_DIRECTORY = /^\d{4}-\d{2}-\d{2}-/;
+export const TICKET_ID = /^T-(\d{4,})$/;
+export const TICKET_CATEGORIES = ["bug", "enhancement"];
+export const TRACKER_STATUSES = ["open", "in-progress", "closed"];
+export const EXECUTION_STATES = [
+    "unstarted",
+    "claimed",
+    "implementing",
+    "reviewing",
+    "changes-requested",
+    "accepted",
+    "integrated",
+    "complete",
+    "blocked",
+];