@use-the-fork/spindle 0.1.0 → 0.2.0

package/build/SubagentDrivenDevelopment/Services/TicketWorktreeService.js

@@ -0,0 +1,317 @@
+import { randomUUID } from "node:crypto";
+import { accessSync, constants, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { Service } from "../../Foundation/Service.js";
+import { isPathInside, lstatIfPresent } from "../Persistence/FileSystem.js";
+import { Records } from "../../Support/Records.js";
+export class TicketWorktreeService extends Service {
+    git;
+    gitEvidence;
+    constructor(app, git, gitEvidence) {
+        super(app);
+        this.git = git;
+        this.gitEvidence = gitEvidence;
+    }
+    create(feature, progress, directory, requiredAncestors, allowPendingRecords = false) {
+        for (const variable of [
+            "GIT_DIR",
+            "GIT_WORK_TREE",
+            "GIT_COMMON_DIR",
+            "GIT_INDEX_FILE",
+            "GIT_OBJECT_DIRECTORY",
+            "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+            "GIT_NAMESPACE",
+        ]) {
+            if (process.env[variable])
+                throw new Error(`Unset ${variable} before ticket dispatch.`);
+        }
+        if (!directory || !isAbsolute(directory)) {
+            throw new Error("--workspace must be an absolute existing external directory.");
+        }
+        const root = realpathSync(this.app.workspaceRoot);
+        const entry = lstatIfPresent(directory);
+        if (!entry?.isDirectory() || entry.isSymbolicLink()) {
+            throw new Error("--workspace must be an existing real directory.");
+        }
+        const parent = realpathSync(directory);
+        accessSync(parent, constants.W_OK | constants.X_OK);
+        const common = realpathSync(this.run(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+        const statePath = join(common, "spindle-feature-start", `${feature.feature}.json`);
+        const stateEntry = lstatIfPresent(statePath);
+        if (!stateEntry?.isFile() || stateEntry.isSymbolicLink()) {
+            throw new Error(`Feature startup state is missing or unsafe: ${statePath}.`);
+        }
+        const state = JSON.parse(readFileSync(statePath, "utf8"));
+        if (!Records.isRecord(state) ||
+            state.version !== 1 ||
+            state.phase !== "created" ||
+            state.feature !== feature.feature ||
+            state.featureBranch !== `features/${feature.feature}` ||
+            state.featureWorkspace !== root ||
+            typeof state.originalWorkspace !== "string" ||
+            !isAbsolute(state.originalWorkspace)) {
+            throw new Error("Feature startup state does not identify this canonical feature worktree.");
+        }
+        const original = realpathSync(state.originalWorkspace);
+        if (realpathSync(this.run(original, ["rev-parse", "--show-toplevel"])) !== original ||
+            realpathSync(this.run(original, ["rev-parse", "--path-format=absolute", "--git-common-dir"])) !== common) {
+            throw new Error("Recorded original checkout no longer matches the feature repository.");
+        }
+        if (isPathInside(original, parent) ||
+            isPathInside(root, parent) ||
+            isPathInside(common, parent)) {
+            throw new Error("--workspace must be outside the original and feature checkouts and Git directory.");
+        }
+        const branch = `tickets/${feature.feature}/${progress.id}`;
+        const workspace = join(parent, `${feature.feature}-${progress.id}`);
+        if (this.run(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== state.featureBranch) {
+            throw new Error("Ticket worktrees must start from the canonical feature branch.");
+        }
+        const currentSha = this.run(root, ["rev-parse", "--verify", "HEAD"]);
+        const lockPath = `.scratch/${feature.feature}/.sdd-tickets.lock`;
+        if (allowPendingRecords) {
+            if (this.gitEvidence.cleanDispatchBaseline(feature, true) !== currentSha) {
+                throw new Error("Feature HEAD changed during ticket dispatch.");
+            }
+        }
+        else {
+            const status = this.run(root, [
+                "status",
+                "--porcelain=v1",
+                "--untracked-files=all",
+                "--ignore-submodules=none",
+                "--",
+                ".",
+                `:(exclude,literal)${lockPath}`,
+            ]);
+            if (status) {
+                throw new Error(`Commit canonical workflow records and resolve other changes before ticket dispatch:\n${status}`);
+            }
+        }
+        const hook = this.run(root, ["rev-parse", "--git-path", "hooks/post-checkout"]);
+        let activeHook = false;
+        try {
+            accessSync(isAbsolute(hook) ? hook : join(root, hook), constants.X_OK);
+            activeHook = true;
+        }
+        catch (error) {
+            if (typeof error !== "object" ||
+                error === null ||
+                !("code" in error) ||
+                (error.code !== "ENOENT" && error.code !== "EACCES")) {
+                throw error;
+            }
+        }
+        if (activeHook) {
+            throw new Error("Active Git post-checkout hook requires manual handling before ticket dispatch.");
+        }
+        const journals = join(common, "spindle-ticket-start");
+        try {
+            mkdirSync(journals, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!lstatIfPresent(journals)?.isDirectory())
+                throw error;
+        }
+        if (!lstatSync(journals).isDirectory() || lstatSync(journals).isSymbolicLink()) {
+            throw new Error("Ticket startup state directory must be a real directory.");
+        }
+        const journal = join(journals, `${feature.feature}-${progress.id}.json`);
+        if (!progress.owner)
+            throw new Error("Ticket startup requires a recorded controller.");
+        let stateRecord;
+        const journalEntry = lstatIfPresent(journal);
+        if (journalEntry) {
+            if (!journalEntry.isFile() || journalEntry.isSymbolicLink()) {
+                throw new Error(`Ticket startup journal is not a regular file: ${journal}.`);
+            }
+            const saved = JSON.parse(readFileSync(journal, "utf8"));
+            if (!Records.isRecord(saved) ||
+                saved.version !== 2 ||
+                typeof saved.id !== "string" ||
+                saved.feature !== feature.feature ||
+                saved.ticket !== progress.id ||
+                saved.owner !== progress.owner ||
+                saved.featureWorkspace !== root ||
+                saved.workspace !== workspace ||
+                saved.branch !== branch ||
+                typeof saved.baseSha !== "string" ||
+                !/^[0-9a-f]{40,64}$/i.test(saved.baseSha) ||
+                (saved.directory !== undefined && !Records.isRecord(saved.directory))) {
+                throw new Error(`Ticket startup journal does not match the current assignment: ${journal}.`);
+            }
+            const directoryState = saved.directory;
+            let directoryIdentity;
+            if (directoryState !== undefined) {
+                if (!Records.isRecord(directoryState) ||
+                    typeof directoryState.device !== "number" ||
+                    typeof directoryState.inode !== "number") {
+                    throw new Error(`Ticket startup journal contains invalid directory identity: ${journal}.`);
+                }
+                directoryIdentity = { device: directoryState.device, inode: directoryState.inode };
+            }
+            stateRecord = {
+                version: 2,
+                id: saved.id,
+                feature: feature.feature,
+                ticket: progress.id,
+                owner: progress.owner,
+                featureWorkspace: root,
+                workspace,
+                branch,
+                baseSha: saved.baseSha,
+                ...(directoryIdentity ? { directory: directoryIdentity } : {}),
+            };
+        }
+        else {
+            if (lstatIfPresent(workspace)) {
+                throw new Error(`Ticket worktree destination already exists: ${workspace}.`);
+            }
+            if (this.branchExists(root, branch))
+                throw new Error(`Ticket branch already exists: ${branch}.`);
+            if (requiredAncestors.some((ancestor) => !this.isAncestor(root, ancestor, currentSha))) {
+                throw new Error("Feature branch does not contain every validated prerequisite.");
+            }
+            stateRecord = {
+                version: 2,
+                id: randomUUID(),
+                feature: feature.feature,
+                ticket: progress.id,
+                owner: progress.owner,
+                featureWorkspace: root,
+                workspace,
+                branch,
+                baseSha: currentSha,
+            };
+            try {
+                this.writeState(journal, stateRecord, true);
+            }
+            catch (error) {
+                throw new Error(`Ticket startup state could not be created; inspect ${journal}. ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (!this.isAncestor(root, stateRecord.baseSha, currentSha) ||
+            requiredAncestors.some((ancestor) => !this.isAncestor(root, ancestor, stateRecord.baseSha))) {
+            throw new Error("Ticket startup baseline does not include the current prerequisite integrations; preserve the recorded worktree and inspect it before continuing.");
+        }
+        try {
+            const registered = this.run(root, ["worktree", "list", "--porcelain", "-z"])
+                .split("\0")
+                .includes(`worktree ${workspace}`);
+            if (!registered) {
+                if (this.branchExists(root, branch)) {
+                    throw new Error(`Ticket branch exists without its recorded worktree: ${branch}.`);
+                }
+                let directoryEntry = lstatIfPresent(workspace);
+                if (!directoryEntry) {
+                    if (stateRecord.directory)
+                        throw new Error("Recorded ticket directory is missing.");
+                    mkdirSync(workspace);
+                    directoryEntry = lstatSync(workspace);
+                    stateRecord.directory = { device: directoryEntry.dev, inode: directoryEntry.ino };
+                    this.writeState(journal, stateRecord);
+                }
+                if (!directoryEntry.isDirectory() ||
+                    directoryEntry.isSymbolicLink() ||
+                    !stateRecord.directory ||
+                    directoryEntry.dev !== stateRecord.directory.device ||
+                    directoryEntry.ino !== stateRecord.directory.inode) {
+                    throw new Error(`Ticket worktree directory ownership cannot be verified: ${workspace}.`);
+                }
+            }
+            if (this.run(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== state.featureBranch ||
+                this.run(root, ["rev-parse", "--verify", "HEAD"]) !== currentSha) {
+                throw new Error("Feature branch advanced during ticket worktree creation.");
+            }
+            if (!registered) {
+                this.run(root, ["worktree", "add", "-b", branch, workspace, stateRecord.baseSha]);
+            }
+            const directoryEntry = lstatSync(workspace);
+            if (!stateRecord.directory ||
+                !directoryEntry.isDirectory() ||
+                directoryEntry.isSymbolicLink() ||
+                directoryEntry.dev !== stateRecord.directory.device ||
+                directoryEntry.ino !== stateRecord.directory.inode ||
+                realpathSync(workspace) !== workspace ||
+                realpathSync(this.run(workspace, ["rev-parse", "--show-toplevel"])) !== workspace ||
+                realpathSync(this.run(workspace, ["rev-parse", "--path-format=absolute", "--git-common-dir"])) !== common ||
+                this.run(workspace, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== branch ||
+                this.run(workspace, ["rev-parse", "--verify", "HEAD"]) !== stateRecord.baseSha ||
+                this.run(workspace, ["status", "--porcelain=v1", "--untracked-files=all"]) !== "") {
+                throw new Error("Created ticket worktree failed verification.");
+            }
+            const finalStatus = allowPendingRecords
+                ? this.gitEvidence.cleanDispatchBaseline(feature, true) === currentSha
+                : this.run(root, [
+                    "status",
+                    "--porcelain=v1",
+                    "--untracked-files=all",
+                    "--ignore-submodules=none",
+                    "--",
+                    ".",
+                    `:(exclude,literal)${lockPath}`,
+                ]) === "";
+            if (this.run(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== state.featureBranch ||
+                this.run(root, ["rev-parse", "--verify", "HEAD"]) !== currentSha ||
+                !finalStatus) {
+                throw new Error("Feature branch or checkout changed during ticket worktree creation.");
+            }
+            return { workspace, branch, baseSha: stateRecord.baseSha, journal };
+        }
+        catch (error) {
+            throw new Error(`Ticket worktree startup stopped; preserve and inspect ${journal}, ${branch}, and ${workspace}. ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    branchExists(root, branch) {
+        const result = this.git.run(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
+            cwd: root,
+            encoding: "utf8",
+        });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0 && result.status !== 1) {
+            throw new Error(`Cannot check ticket branch: ${result.stderr.trim()}`);
+        }
+        return result.status === 0;
+    }
+    isAncestor(root, ancestor, descendant) {
+        const result = this.git.run(["merge-base", "--is-ancestor", ancestor, descendant], {
+            cwd: root,
+            encoding: "utf8",
+        });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0 && result.status !== 1) {
+            throw new Error(`Cannot verify ticket startup ancestry: ${result.stderr.trim()}`);
+        }
+        return result.status === 0;
+    }
+    writeState(path, state, create = false) {
+        const target = create ? path : `${path}.${randomUUID()}.tmp`;
+        const fd = openSync(target, "wx", 0o600);
+        try {
+            writeFileSync(fd, `${JSON.stringify(state, null, 2)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (!create)
+            renameSync(target, path);
+        const directory = openSync(join(path, ".."), "r");
+        try {
+            fsyncSync(directory);
+        }
+        finally {
+            closeSync(directory);
+        }
+    }
+    run(root, args) {
+        const result = this.git.run(args, { cwd: root, encoding: "utf8" });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0)
+            throw new Error(`git ${args[0]} failed: ${result.stderr.trim()}`);
+        return result.stdout.trim();
+    }
+}

package/build/SubagentDrivenDevelopment/Services/WorkflowRecordsCommitter.js

@@ -0,0 +1,336 @@
+import { createHash, randomUUID } from "node:crypto";
+import { accessSync, closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { Service } from "../../Foundation/Service.js";
+import { lstatIfPresent } from "../Persistence/FileSystem.js";
+import { Records } from "../../Support/Records.js";
+export class WorkflowRecordsCommitter extends Service {
+    git;
+    constructor(app, git) {
+        super(app);
+        this.git = git;
+    }
+    commit(feature, confirmed) {
+        for (const variable of [
+            "GIT_DIR",
+            "GIT_WORK_TREE",
+            "GIT_COMMON_DIR",
+            "GIT_INDEX_FILE",
+            "GIT_OBJECT_DIRECTORY",
+            "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+            "GIT_NAMESPACE",
+        ]) {
+            if (process.env[variable]) {
+                throw new Error(`Unset ${variable} before committing workflow records.`);
+            }
+        }
+        const root = realpathSync(this.app.workspaceRoot);
+        if (realpathSync(feature.workspace) !== realpathSync(join(root, ".scratch", feature.feature))) {
+            throw new Error("Canonical workflow records do not belong to this feature worktree.");
+        }
+        const branch = this.run(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]).trim();
+        if (branch !== `features/${feature.feature}`) {
+            throw new Error(`Canonical workflow records can only be committed on features/${feature.feature}; current branch is ${branch}.`);
+        }
+        this.assertNoGitOperation(root);
+        this.assertNoHooks(root);
+        const lock = `.scratch/${feature.feature}/.sdd-tickets.lock`;
+        const staged = this.paths(root, ["diff", "--cached", "--name-only", "--no-renames", "-z"]);
+        const unstaged = this.paths(root, ["diff", "--name-only", "--no-renames", "-z"]);
+        const untracked = this.paths(root, ["ls-files", "--others", "--exclude-standard", "-z"]);
+        const changed = [...new Set([...staged, ...unstaged, ...untracked])]
+            .filter((path) => path !== lock)
+            .sort();
+        const common = realpathSync(this.run(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+        const directory = join(common, "spindle-record-commit");
+        const journal = join(directory, `${feature.feature}.json`);
+        const journalEntry = lstatIfPresent(journal);
+        let state;
+        if (journalEntry) {
+            const directoryEntry = lstatSync(directory);
+            if (!directoryEntry.isDirectory() || directoryEntry.isSymbolicLink()) {
+                throw new Error("Canonical record journal directory must be a real directory.");
+            }
+            if (!journalEntry.isFile() || journalEntry.isSymbolicLink()) {
+                throw new Error(`Canonical record journal is not a regular file: ${journal}.`);
+            }
+            const saved = JSON.parse(readFileSync(journal, "utf8"));
+            if (!Records.isRecord(saved) ||
+                saved.version !== 1 ||
+                saved.feature !== feature.feature ||
+                saved.workspace !== root ||
+                saved.branch !== branch ||
+                typeof saved.parent !== "string" ||
+                !/^[0-9a-f]{40,64}$/i.test(saved.parent) ||
+                !Array.isArray(saved.paths) ||
+                saved.paths.length === 0 ||
+                !saved.paths.every((path) => typeof path === "string" && this.isCanonicalRecord(feature, path)) ||
+                typeof saved.digest !== "string" ||
+                !/^[0-9a-f]{64}$/i.test(saved.digest) ||
+                (saved.tree !== undefined &&
+                    (typeof saved.tree !== "string" || !/^[0-9a-f]{40,64}$/i.test(saved.tree)))) {
+                throw new Error(`Canonical record journal does not match this worktree: ${journal}.`);
+            }
+            const paths = saved.paths.map((path) => {
+                if (typeof path !== "string")
+                    throw new Error("Invalid canonical record path.");
+                return path;
+            });
+            if (JSON.stringify([...new Set(paths)].sort()) !== JSON.stringify(paths)) {
+                throw new Error(`Canonical record journal has invalid paths: ${journal}.`);
+            }
+            state = {
+                version: 1,
+                feature: feature.feature,
+                workspace: root,
+                branch,
+                parent: saved.parent,
+                paths,
+                digest: saved.digest,
+                ...(typeof saved.tree === "string" ? { tree: saved.tree } : {}),
+            };
+        }
+        else {
+            if (staged.length > 0) {
+                throw new Error(`Staged data was preserved; inspect and commit or unstage it before continuing: ${staged.join(", ")}`);
+            }
+            if (changed.length === 0)
+                return undefined;
+            const invalid = changed.filter((path) => !this.isCanonicalRecord(feature, path));
+            if (invalid.length > 0) {
+                throw new Error(`Unrelated or non-canonical changes were preserved; resolve them before continuing:\n${invalid.join("\n")}`);
+            }
+            if (!confirmed) {
+                throw new Error(`Inspect these canonical records, then retry with --confirm-records; nothing was staged or committed:\n${changed.join("\n")}`);
+            }
+            state = {
+                version: 1,
+                feature: feature.feature,
+                workspace: root,
+                branch,
+                parent: this.run(root, ["rev-parse", "--verify", "HEAD"]),
+                paths: changed,
+                digest: this.digest(root, changed),
+            };
+            try {
+                mkdirSync(directory, { mode: 0o700 });
+            }
+            catch (error) {
+                if (!lstatIfPresent(directory)?.isDirectory())
+                    throw error;
+            }
+            const entry = lstatSync(directory);
+            if (!entry.isDirectory() || entry.isSymbolicLink()) {
+                throw new Error("Canonical record journal directory must be a real directory.");
+            }
+            this.writeState(journal, state, true);
+        }
+        if (!confirmed) {
+            throw new Error(`Inspect the journalled records and retry with --confirm-records: ${journal}.`);
+        }
+        try {
+            const head = this.run(root, ["rev-parse", "--verify", "HEAD"]);
+            if (head !== state.parent) {
+                this.assertCommitted(root, state, head);
+                if (changed.length > 0 || this.digest(root, state.paths) !== state.digest) {
+                    throw new Error("Committed records or the worktree changed during recovery.");
+                }
+                this.removeState(journal);
+                return head;
+            }
+            if (JSON.stringify(changed) !== JSON.stringify(state.paths) ||
+                this.digest(root, state.paths) !== state.digest ||
+                staged.some((path) => unstaged.includes(path))) {
+                throw new Error("Journalled records or staged data changed during recovery.");
+            }
+            this.run(root, ["add", "-A", "--", ...state.paths.map((path) => `:(literal)${path}`)]);
+            const selected = this.paths(root, [
+                "diff",
+                "--cached",
+                "--name-only",
+                "--no-renames",
+                "-z",
+            ]).sort();
+            if (JSON.stringify(selected) !== JSON.stringify(state.paths)) {
+                throw new Error(`Staged records changed during batching; preserve and inspect the index. Expected ${state.paths.join(", ")}, found ${selected.join(", ")}.`);
+            }
+            const remaining = [
+                ...this.paths(root, ["diff", "--name-only", "-z"]),
+                ...this.paths(root, ["ls-files", "--others", "--exclude-standard", "-z"]),
+            ].filter((path) => path !== lock);
+            if (remaining.length > 0 || this.digest(root, state.paths) !== state.digest) {
+                throw new Error(`Feature records changed during batching; preserve the index and worktree: ${remaining.join(", ")}`);
+            }
+            const tree = this.run(root, ["write-tree"]);
+            if (state.tree && state.tree !== tree) {
+                throw new Error("Journalled record index changed during recovery.");
+            }
+            if (!state.tree) {
+                state.tree = tree;
+                this.writeState(journal, state);
+            }
+            if (this.run(root, ["rev-parse", "--verify", "HEAD"]) !== state.parent) {
+                throw new Error("Feature branch advanced during canonical record batching.");
+            }
+            this.assertNoGitOperation(root);
+            this.assertNoHooks(root);
+            this.run(root, ["commit", "-m", `spindle: record ${feature.feature} workflow`]);
+            const committedHead = this.run(root, ["rev-parse", "--verify", "HEAD"]);
+            this.assertCommitted(root, state, committedHead);
+            const after = [
+                ...this.paths(root, ["diff", "--name-only", "-z"]),
+                ...this.paths(root, ["diff", "--cached", "--name-only", "-z"]),
+                ...this.paths(root, ["ls-files", "--others", "--exclude-standard", "-z"]),
+            ].filter((path) => path !== lock);
+            if (after.length > 0 || this.digest(root, state.paths) !== state.digest) {
+                throw new Error(`Canonical records were committed, but additional changes remain; preserve and inspect them: ${after.join(", ")}`);
+            }
+            this.removeState(journal);
+            return committedHead;
+        }
+        catch (error) {
+            throw new Error(`Canonical record batching stopped; preserve ${journal}, the index, and the worktree. ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    digest(root, paths) {
+        const entries = paths.map((path) => {
+            const entry = lstatIfPresent(join(root, path));
+            if (!entry)
+                return [path, "deleted"];
+            if (!entry.isFile() || entry.isSymbolicLink()) {
+                throw new Error(`Canonical record is not a regular file: ${path}.`);
+            }
+            return [
+                path,
+                entry.mode & 0o111 ? "100755" : "100644",
+                createHash("sha256")
+                    .update(readFileSync(join(root, path)))
+                    .digest("hex"),
+            ];
+        });
+        return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+    }
+    assertCommitted(root, state, head) {
+        const ancestry = this.run(root, ["rev-list", "--parents", "-n", "1", head]).split(/\s+/);
+        const committed = this.paths(root, [
+            "diff",
+            "--name-only",
+            "-z",
+            "--no-renames",
+            state.parent,
+            head,
+        ]).sort();
+        if (!state.tree ||
+            head === state.parent ||
+            ancestry.length !== 2 ||
+            ancestry[1] !== state.parent ||
+            this.run(root, ["show", "-s", "--format=%T", head]) !== state.tree ||
+            this.run(root, ["show", "-s", "--format=%s", head]) !==
+                `spindle: record ${state.feature} workflow` ||
+            JSON.stringify(committed) !== JSON.stringify(state.paths)) {
+            throw new Error("Canonical record commit failed verification; preserve and inspect Git state.");
+        }
+    }
+    assertNoGitOperation(root) {
+        if (this.paths(root, ["ls-files", "--unmerged", "-z"]).length > 0) {
+            throw new Error("Resolve unmerged index entries before committing workflow records.");
+        }
+        for (const operation of [
+            "MERGE_HEAD",
+            "CHERRY_PICK_HEAD",
+            "REVERT_HEAD",
+            "REBASE_HEAD",
+            "rebase-merge",
+            "rebase-apply",
+            "sequencer",
+        ]) {
+            const path = resolve(root, this.run(root, ["rev-parse", "--git-path", operation]));
+            if (lstatIfPresent(path)) {
+                throw new Error(`Complete the existing Git operation (${operation}) before committing records.`);
+            }
+        }
+    }
+    assertNoHooks(root) {
+        for (const hook of ["pre-commit", "prepare-commit-msg", "commit-msg", "post-commit"]) {
+            const path = resolve(root, this.run(root, ["rev-parse", "--git-path", `hooks/${hook}`]));
+            try {
+                accessSync(path, constants.X_OK);
+            }
+            catch (error) {
+                if (typeof error === "object" &&
+                    error !== null &&
+                    "code" in error &&
+                    (error.code === "ENOENT" || error.code === "EACCES")) {
+                    continue;
+                }
+                throw error;
+            }
+            throw new Error(`Active Git hook ${path} requires manual handling before committing records.`);
+        }
+    }
+    writeState(path, state, create = false) {
+        const target = create ? path : `${path}.${randomUUID()}.tmp`;
+        const fd = openSync(target, "wx", 0o600);
+        try {
+            writeFileSync(fd, `${JSON.stringify(state, null, 2)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (!create)
+            renameSync(target, path);
+        this.syncDirectory(join(path, ".."));
+    }
+    removeState(path) {
+        unlinkSync(path);
+        this.syncDirectory(join(path, ".."));
+    }
+    syncDirectory(path) {
+        const fd = openSync(path, "r");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    isCanonicalRecord(feature, path) {
+        const prefix = `.scratch/${feature.feature}/`;
+        if (!path.startsWith(prefix))
+            return false;
+        const relative = path.slice(prefix.length);
+        return (relative === "spec.md" ||
+            relative === "design.md" ||
+            relative === "sdd.json" ||
+            /^tickets\/T-\d{4,}\.md$/.test(relative) ||
+            /^reports\/[^/]+\.md$/.test(relative));
+    }
+    paths(root, args) {
+        const result = this.git.run(args, {
+            cwd: root,
+            encoding: "utf8",
+            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.trim()}`);
+        }
+        const output = result.stdout;
+        return output ? output.split("\0").filter(Boolean) : [];
+    }
+    run(root, args) {
+        const result = this.git.run(args, {
+            cwd: root,
+            encoding: "utf8",
+            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.trim()}`);
+        }
+        return result.stdout.trim();
+    }
+}