@warpgogol/forge 2.1.0 → 2.3.0

package/dist/os/adr/handlers/archive.js

@@ -0,0 +1,194 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+ADR archive handler — moves terminal-status ADR files into status-specific
+subdirectories under docs/adrs/archive/ and moves non-terminal files found
+in subdirectories back to the root.
+</purpose>
+<non-goals>
+  <item>Does not validate ADR content — use adr.validate for that.</item>
+  <item>Does not change ADR frontmatter — only moves files on disk.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0367: implement adr.archive command for terminal-status file archiving.</item>
+  <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
+  <item>RFC-0733: add pinned-files pre-check — skip pinned files with warning instead of moving them.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import path from "node:path";
+import { listAdrFiles, readAndParseAdr } from "../frontmatter-io.js";
+import { ADR_DIR } from "../types.js";
+import { loadPinnedManifest, isPinned, isIntraDirMove } from "../../core/handlers/pinned-check.js";
+export const ADR_TERMINAL_STATUSES = ["implemented", "rejected", "superseded"];
+export async function runAdrArchive(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const adrDirPath = path.join(workspaceRoot, ADR_DIR);
+    const dryRun = context.dryRun || input.flags["dry-run"] === true;
+    const statusFilter = input.flags["status"];
+    if (statusFilter && !ADR_TERMINAL_STATUSES.includes(statusFilter)) {
+        throw new Error(`Invalid --status "${statusFilter}". Must be one of: ${ADR_TERMINAL_STATUSES.join(", ")}`);
+    }
+    const files = await listAdrFiles(adrDirPath);
+    const moved = [];
+    const skipped = [];
+    // RFC-0733: Load pinned manifest once per invocation
+    let pinnedManifest = null;
+    try {
+        pinnedManifest = await loadPinnedManifest(workspaceRoot);
+    }
+    catch {
+        // Malformed manifest — skip pre-check
+    }
+    for (const fileName of files) {
+        const result = await readAndParseAdr(adrDirPath, fileName);
+        if (!result) {
+            skipped.push({
+                id: "UNKNOWN",
+                file: path.join(ADR_DIR, fileName),
+                reason: "unreadable frontmatter",
+            });
+            continue;
+        }
+        const fm = result.parsed.frontmatter;
+        const id = String(fm["id"] ?? "UNKNOWN");
+        const status = String(fm["status"] ?? "").trim();
+        const isTerminal = status === "implemented" || status === "rejected" || status === "superseded";
+        const isInArchive = fileName.includes("/");
+        const relFile = path.join(ADR_DIR, fileName);
+        const basename = path.basename(fileName);
+        if (statusFilter && status !== statusFilter) {
+            skipped.push({
+                id,
+                file: relFile,
+                reason: `status ${status} does not match --status ${statusFilter}`,
+            });
+            continue;
+        }
+        if (isTerminal && !isInArchive) {
+            const targetDir = path.join(adrDirPath, "archive", status);
+            const targetPath = path.join(targetDir, basename);
+            const targetRel = path.join(ADR_DIR, "archive", status, basename);
+            // RFC-0733: Check if file is pinned before moving
+            // Gap fix: exempt intra-directory moves (file stays within the same pinned dir)
+            if (pinnedManifest &&
+                isPinned(pinnedManifest, relFile) &&
+                !isIntraDirMove(pinnedManifest, relFile, targetRel)) {
+                skipped.push({ id, file: relFile, reason: "pinned (protected by .forge/pinned.yaml)" });
+                if (outputFormat === "pretty") {
+                    logger.warn(`  pinned: skipping ${relFile} (protected)`);
+                }
+                continue;
+            }
+            try {
+                await fs.access(targetPath);
+                skipped.push({ id, file: relFile, reason: "destination exists" });
+                continue;
+            }
+            catch {
+                // destination doesn't exist — proceed
+            }
+            if (!dryRun) {
+                await fs.mkdir(targetDir, { recursive: true });
+                try {
+                    await fs.rename(path.join(adrDirPath, fileName), targetPath);
+                }
+                catch (err) {
+                    if (err.code === "ENOENT") {
+                        skipped.push({ id, file: relFile, reason: "already moved by another process" });
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            moved.push({
+                id,
+                file: targetRel,
+                status,
+                from: relFile,
+                to: targetRel,
+                direction: "into-archive",
+            });
+        }
+        else if (!isTerminal && isInArchive) {
+            const targetPath = path.join(adrDirPath, basename);
+            const targetRel = path.join(ADR_DIR, basename);
+            // RFC-0733: Check if file is pinned before moving
+            // Gap fix: exempt intra-directory moves (file stays within the same pinned dir)
+            if (pinnedManifest &&
+                isPinned(pinnedManifest, relFile) &&
+                !isIntraDirMove(pinnedManifest, relFile, targetRel)) {
+                skipped.push({ id, file: relFile, reason: "pinned (protected by .forge/pinned.yaml)" });
+                if (outputFormat === "pretty") {
+                    logger.warn(`  pinned: skipping ${relFile} (protected)`);
+                }
+                continue;
+            }
+            try {
+                await fs.access(targetPath);
+                skipped.push({ id, file: relFile, reason: "destination exists" });
+                continue;
+            }
+            catch {
+                // destination doesn't exist — proceed
+            }
+            if (!dryRun) {
+                try {
+                    await fs.rename(path.join(adrDirPath, fileName), targetPath);
+                }
+                catch (err) {
+                    if (err.code === "ENOENT") {
+                        skipped.push({ id, file: relFile, reason: "already moved by another process" });
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            moved.push({
+                id,
+                file: targetRel,
+                status,
+                from: relFile,
+                to: targetRel,
+                direction: "out-of-archive",
+            });
+        }
+        else if (isTerminal && isInArchive) {
+            skipped.push({ id, file: relFile, reason: `already archived (${status})` });
+        }
+        else {
+            skipped.push({ id, file: relFile, reason: `status ${status} is non-terminal` });
+        }
+    }
+    if (outputFormat === "pretty") {
+        if (dryRun) {
+            logger.info(`[dry-run] adr.archive: would move ${moved.length} file(s), skip ${skipped.length}`);
+        }
+        else {
+            logger.success(`adr.archive: moved ${moved.length} file(s), skipped ${skipped.length}`);
+        }
+        for (const m of moved) {
+            logger.info(`  ${m.direction}: ${m.id} (${m.status}) ${m.from} → ${m.to}`);
+        }
+    }
+    return {
+        data: {
+            command: "adr.archive",
+            status: "ok",
+            moved,
+            skipped,
+            dryRun,
+        },
+        summary: dryRun
+            ? `[dry-run] Would move ${moved.length} file(s), skip ${skipped.length}`
+            : `Moved ${moved.length} file(s), skipped ${skipped.length}`,
+        nextSteps: [
+            {
+                action: "Run: pnpm exec werkstatt run adr.list --json to verify archive status",
+                kind: "optional",
+            },
+        ],
+    };
+}
+//# sourceMappingURL=archive.js.map

package/dist/os/adr/handlers/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../../os/adr/handlers/archive.ts"],"names":[],"mappings":"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"}

package/dist/os/adr/handlers/implement-stamp.d.ts

@@ -0,0 +1,4 @@
+import type { AdrImplementStampResult } from "../types.ts";
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+export declare function runAdrImplementStamp(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<AdrImplementStampResult>>;
+//# sourceMappingURL=implement-stamp.d.ts.map

package/dist/os/adr/handlers/implement-stamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implement-stamp.d.ts","sourceRoot":"","sources":["../../../../os/adr/handlers/implement-stamp.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAyC,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAClG,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AA0H/B,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAC,CAuJtD"}

package/dist/os/adr/handlers/implement-stamp.js

@@ -0,0 +1,258 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0727: adr.implement.stamp — the exclusive atomic path for
+accepted/proposed → implemented ADR transitions. Validates preconditions
+and atomically mutates ADR frontmatter.
+</purpose>
+<non-goals>
+  <item>Does not transition ADRs not in accepted or proposed status.</item>
+  <item>Does not add acceptance criteria or evidence checks — ADRs do not have these.</item>
+  <item>Does not call the GitHub API or require network access.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0727: initial implementation — mirrors rfc.implement.stamp for ADRs.</item>
+</CHANGE_SUMMARY>
+*/
+import { execFile } from "node:child_process";
+import { readFile, unlink, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { writeFileAtomic } from "../../../src/utils/fs-atomic.js";
+import { listAdrFiles, readAndParseAdr, adrFileMatchesId } from "../frontmatter-io.js";
+import { ADR_DIR } from "../types.js";
+// ─── Git helpers ─────────────────────────────────────────────────────────────
+function execGit(workspaceRoot, args) {
+    return new Promise((resolve) => {
+        execFile("git", args, { cwd: workspaceRoot, timeout: 10000 }, (err, stdout) => {
+            if (err) {
+                resolve("");
+                return;
+            }
+            resolve(stdout.trim());
+        });
+    });
+}
+async function isAdrFileClean(workspaceRoot, adrRelPath) {
+    const status = await execGit(workspaceRoot, ["status", "--porcelain", "--", adrRelPath]);
+    return status.length === 0;
+}
+async function commitReachableFromHead(workspaceRoot, commitSha) {
+    return new Promise((resolve) => {
+        execFile("git", ["merge-base", "--is-ancestor", commitSha, "HEAD"], { cwd: workspaceRoot, timeout: 10000 }, (err) => {
+            resolve(!err);
+        });
+    });
+}
+async function commitReferencesAdr(workspaceRoot, commitSha, adrId) {
+    const commitMsg = await execGit(workspaceRoot, ["log", "-1", "--format=%B", commitSha]);
+    if (commitMsg.includes(adrId))
+        return true;
+    const changedFiles = await execGit(workspaceRoot, [
+        "show",
+        "--name-only",
+        "--format=",
+        commitSha,
+    ]);
+    const slug = adrId.toLowerCase();
+    if (changedFiles.toLowerCase().includes(slug))
+        return true;
+    return false;
+}
+// ─── ADR-specific exclusive lock ─────────────────────────────────────────────
+function lockFilePath(workspaceRoot, adrId) {
+    const slug = adrId.toLowerCase();
+    return join(workspaceRoot, ".adr-locks", `${slug}.lock`);
+}
+async function acquireAdrLock(workspaceRoot, adrId) {
+    const lockPath = lockFilePath(workspaceRoot, adrId);
+    const lockDir = dirname(lockPath);
+    await mkdir(lockDir, { recursive: true });
+    const { open } = await import("node:fs/promises");
+    try {
+        const handle = await open(lockPath, "wx");
+        await handle.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }));
+        await handle.close();
+        return { acquired: true, lockPath };
+    }
+    catch {
+        return { acquired: false, lockPath };
+    }
+}
+async function releaseAdrLock(lockPath) {
+    try {
+        await unlink(lockPath);
+    }
+    catch {
+        // Lock file already removed — safe
+    }
+}
+// ─── Frontmatter mutation ────────────────────────────────────────────────────
+function mutateAdrFrontmatter(source, status, implementedAt, updatedAt) {
+    let content = source;
+    content = content.replace(/^status: \w+$/m, `status: ${status}`);
+    if (/^implementedAt:.*$/m.test(content)) {
+        content = content.replace(/^implementedAt:.*$/m, `implementedAt: ${implementedAt}`);
+    }
+    else {
+        content = content.replace(/^updatedAt: .*$/m, `updatedAt: ${updatedAt}\nimplementedAt: ${implementedAt}`);
+    }
+    content = content.replace(/^updatedAt: .*$/m, `updatedAt: ${updatedAt}`);
+    return content;
+}
+function toIsoDate(date) {
+    return date.toISOString().split("T")[0];
+}
+// ─── Main handler ────────────────────────────────────────────────────────────
+export async function runAdrImplementStamp(input, context) {
+    const { workspaceRoot, logger, outputFormat, dryRun } = context;
+    const adrDirPath = join(workspaceRoot, ADR_DIR);
+    const targetId = input.flags["id"];
+    const implementationCommit = input.flags["implementation-commit"];
+    // ── Flag validation ───────────────────────────────────────────────────────
+    if (!targetId) {
+        throw new Error("adr.implement.stamp requires --id flag (e.g. --id ADR-0003).");
+    }
+    if (!implementationCommit) {
+        throw new Error("adr.implement.stamp requires --implementation-commit flag (the SHA of the implementation commit).");
+    }
+    const violations = [];
+    const isDryRun = dryRun || input.flags["dry-run"] === true;
+    // ── Find the target ADR ───────────────────────────────────────────────────
+    const files = await listAdrFiles(adrDirPath);
+    const targetFile = files.find((f) => adrFileMatchesId(f, targetId));
+    if (!targetFile) {
+        violations.push({
+            rule: "ADR-IMP-01",
+            message: `ADR ${targetId} not found in ${ADR_DIR}.`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    const targetParsed = await readAndParseAdr(adrDirPath, targetFile);
+    if (!targetParsed) {
+        violations.push({
+            rule: "ADR-IMP-01",
+            message: `Could not parse target ADR ${targetId}.`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    const fm = targetParsed.parsed.frontmatter;
+    const currentStatus = String(fm["status"] ?? "");
+    // ── ADR-IMP-01: must be in accepted or proposed status ─────────────────────
+    if (currentStatus !== "accepted" && currentStatus !== "proposed") {
+        violations.push({
+            rule: "ADR-IMP-01",
+            message: `ADR ${targetId} has status "${currentStatus}" — only "accepted" or "proposed" ADRs can be stamped to "implemented".`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    // ── ADR-IMP-04: ADR file must be clean (no uncommitted edits to the target ADR) ──
+    const adrRelPath = join(ADR_DIR, targetFile);
+    const adrFileClean = await isAdrFileClean(workspaceRoot, adrRelPath);
+    if (!adrFileClean) {
+        violations.push({
+            rule: "ADR-IMP-04",
+            message: `ADR file ${adrRelPath} has uncommitted changes. Commit the ADR file before stamping.`,
+        });
+    }
+    // ── ADR-IMP-03: implementation commit validation ──────────────────────────
+    const reachable = await commitReachableFromHead(workspaceRoot, implementationCommit);
+    if (!reachable) {
+        violations.push({
+            rule: "ADR-IMP-03",
+            message: `Implementation commit ${implementationCommit} is not reachable from HEAD. The commit must be an ancestor of the current HEAD.`,
+        });
+    }
+    else {
+        const referencesAdr = await commitReferencesAdr(workspaceRoot, implementationCommit, targetId);
+        if (!referencesAdr) {
+            violations.push({
+                rule: "ADR-IMP-03",
+                message: `Implementation commit ${implementationCommit} does not reference ${targetId} in its message or changed files.`,
+            });
+        }
+    }
+    // If any violations found, return without mutation
+    if (violations.length > 0) {
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    // ── ADR-IMP-05: acquire ADR-specific exclusive lock ───────────────────────
+    const { acquired, lockPath } = await acquireAdrLock(workspaceRoot, targetId);
+    if (!acquired) {
+        violations.push({
+            rule: "ADR-IMP-05",
+            message: `A concurrent stamp operation is in progress for ${targetId}. Wait for it to complete and retry.`,
+        });
+        return stampFailResult(violations, isDryRun, outputFormat, logger);
+    }
+    try {
+        // ── Atomic mutation ──────────────────────────────────────────────────────
+        const adrFilePath = join(adrDirPath, targetFile);
+        const adrSource = await readFile(adrFilePath, "utf-8");
+        const today = toIsoDate(new Date());
+        const stampedAt = new Date().toISOString();
+        const mutatedSource = mutateAdrFrontmatter(adrSource, "implemented", today, today);
+        if (isDryRun) {
+            if (outputFormat === "pretty") {
+                logger.success(`[dry-run] ${targetId} would be stamped as implemented`);
+                logger.info(`  implementation commit: ${implementationCommit}`);
+                logger.info(`  stamped at: ${stampedAt}`);
+            }
+            return {
+                data: {
+                    command: "adr.implement.stamp",
+                    status: "pass",
+                    data: {
+                        adrId: targetId,
+                        implementationCommit,
+                        stampedAt,
+                    },
+                    violations: [],
+                },
+                exitCode: 0,
+                summary: `adr.implement.stamp: dry-run — ${targetId} would be stamped`,
+            };
+        }
+        await writeFileAtomic(adrFilePath, mutatedSource);
+        if (outputFormat === "pretty") {
+            logger.success(`${targetId} stamped as implemented`);
+            logger.info(`  implementation commit: ${implementationCommit}`);
+            logger.info(`  stamped at: ${stampedAt}`);
+        }
+        return {
+            data: {
+                command: "adr.implement.stamp",
+                status: "pass",
+                data: {
+                    adrId: targetId,
+                    implementationCommit,
+                    stampedAt,
+                },
+                violations: [],
+            },
+            exitCode: 0,
+            summary: `adr.implement.stamp: ${targetId} stamped as implemented`,
+        };
+    }
+    finally {
+        await releaseAdrLock(lockPath);
+    }
+}
+function stampFailResult(violations, isDryRun, outputFormat, logger) {
+    const prefix = isDryRun ? "[dry-run] " : "";
+    if (outputFormat === "pretty") {
+        for (const v of violations) {
+            logger.warn(`${prefix}${v.rule}: ${v.message}`);
+        }
+    }
+    return {
+        data: {
+            command: "adr.implement.stamp",
+            status: "fail",
+            violations,
+        },
+        exitCode: 1,
+        summary: `${prefix}adr.implement.stamp: ${violations.length} violation(s)`,
+    };
+}
+//# sourceMappingURL=implement-stamp.js.map

package/dist/os/adr/handlers/implement-stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"implement-stamp.js","sourceRoot":"","sources":["../../../../os/adr/handlers/implement-stamp.ts"],"names":[],"mappings":"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"}

package/dist/os/adr/handlers/list-create.d.ts

@@ -0,0 +1,5 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import type { AdrListResult, AdrCreateResult } from "../types.ts";
+export declare function runAdrList(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<AdrListResult>>;
+export declare function runAdrCreate(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<AdrCreateResult>>;
+//# sourceMappingURL=list-create.d.ts.map

package/dist/os/adr/handlers/list-create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-create.d.ts","sourceRoot":"","sources":["../../../../os/adr/handlers/list-create.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEV,aAAa,EACb,eAAe,EAGhB,MAAM,aAAa,CAAC;AAOrB,wBAAsB,UAAU,CAC9B,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC,CA0D5C;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC,CAyG9C"}

package/dist/os/adr/handlers/list-create.js

@@ -0,0 +1,165 @@
+/*
+<MODULE_CONTRACT>
+<purpose>ADR list and create handlers mirroring the RFC domain.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0366: create ADR list and create handlers mirroring the RFC domain.</item>
+  <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import path from "node:path";
+import { toKebabCase } from "../../../src/utils/string-utils.js";
+import { listAdrFiles, readAndParseAdr } from "../frontmatter-io.js";
+import { ADR_DIR, ADR_TEMPLATE_FILE, ADR_SCOPES, ADR_STATUSES } from "../types.js";
+function toIsoDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+export async function runAdrList(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const adrDirPath = path.join(workspaceRoot, ADR_DIR);
+    const filterStatus = input.flags["status"];
+    const filterScope = input.flags["scope"];
+    const filterDecider = input.flags["decider"];
+    const files = await listAdrFiles(adrDirPath);
+    const entries = [];
+    for (const fileName of files) {
+        const result = await readAndParseAdr(adrDirPath, fileName);
+        if (!result)
+            continue;
+        const fm = result.parsed.frontmatter;
+        const id = String(fm["id"] ?? "");
+        const status = String(fm["status"] ?? "");
+        const scope = String(fm["scope"] ?? "");
+        const decider = String(fm["decider"] ?? "");
+        if (filterStatus && status !== filterStatus)
+            continue;
+        if (filterScope && scope !== filterScope)
+            continue;
+        if (filterDecider && decider !== filterDecider)
+            continue;
+        entries.push({
+            id,
+            title: String(fm["title"] ?? ""),
+            status,
+            scope,
+            decider,
+            updatedAt: String(fm["updatedAt"] ?? ""),
+            file: path.join(ADR_DIR, fileName),
+        });
+    }
+    if (outputFormat === "pretty") {
+        if (entries.length === 0) {
+            logger.info("No ADRs found matching the given filters.");
+        }
+        else {
+            logger.section(`ADRs (${entries.length})`);
+            for (const entry of entries) {
+                logger.info(`${entry.id}  ${entry.status.padEnd(12)} ${entry.scope.padEnd(10)} ${entry.decider.padEnd(20)} ${entry.title}`);
+            }
+        }
+    }
+    return {
+        data: {
+            command: "adr.list",
+            status: "ok",
+            count: entries.length,
+            entries,
+        },
+        summary: `${entries.length} ADR(s) found`,
+    };
+}
+export async function runAdrCreate(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const adrDirPath = path.join(workspaceRoot, ADR_DIR);
+    const title = input.flags["title"];
+    if (!title) {
+        throw new Error('adr.create requires --title flag, e.g. --title="Use DuckDB for local analytics"');
+    }
+    const scope = input.flags["scope"] ?? "package";
+    const decider = input.flags["decider"] ?? "architecture";
+    const status = input.flags["status"] ?? "proposed";
+    const relatedRaw = input.flags["related"];
+    if (!ADR_SCOPES.includes(scope)) {
+        throw new Error(`Invalid scope: ${scope}. Must be one of: ${ADR_SCOPES.join(", ")}`);
+    }
+    if (!ADR_STATUSES.includes(status)) {
+        throw new Error(`Invalid status: ${status}. Must be one of: ${ADR_STATUSES.join(", ")}`);
+    }
+    const files = await listAdrFiles(adrDirPath);
+    let maxId = 0;
+    for (const f of files) {
+        const basename = path.basename(f);
+        const match = basename.match(/^adr-(\d{4})/);
+        if (match) {
+            const num = parseInt(match[1], 10);
+            if (num > maxId)
+                maxId = num;
+        }
+    }
+    const nextNum = maxId + 1;
+    const paddedNum = String(nextNum).padStart(4, "0");
+    const nextSlug = `adr-${paddedNum}`;
+    const nextId = `ADR-${paddedNum}`;
+    const templateRelPath = ADR_TEMPLATE_FILE;
+    const templatePath = path.join(workspaceRoot, templateRelPath);
+    let templateContent;
+    try {
+        templateContent = await fs.readFile(templatePath, "utf-8");
+    }
+    catch {
+        throw new Error(`ADR template not found at ${templateRelPath}. Ensure docs/adrs/ contains the template.`);
+    }
+    const today = toIsoDate(new Date());
+    const kebabTitle = toKebabCase(title);
+    const fileName = `${nextSlug}-${kebabTitle}.md`;
+    let content = templateContent;
+    content = content.replace(/^id: ADR-0000$/m, `id: ${nextId}`);
+    const escapedTitle = title.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    content = content.replace(/^title: ".*"$/m, `title: "${escapedTitle}"`);
+    content = content.replace(/^status: \w+$/m, `status: ${status}`);
+    content = content.replace(/^scope: \w+$/m, `scope: ${scope}`);
+    content = content.replace(/^decider: \w+$/m, `decider: ${decider}`);
+    content = content.replace(/^createdAt: YYYY-MM-DD$/m, `createdAt: ${today}`);
+    content = content.replace(/^updatedAt: YYYY-MM-DD$/m, `updatedAt: ${today}`);
+    content = content.replace(/^# ADR-0000: .+$/m, `# ${nextId}: ${title}`);
+    const relatedIds = relatedRaw
+        ? relatedRaw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+    if (relatedIds.length > 0) {
+        content = content.replace(/^related:\s*\n\s*- RFC-0001\s*$/m, `related:\n${relatedIds.map((id) => `  - ${id}`).join("\n")}`);
+    }
+    else {
+        content = content.replace(/^related:\s*\n\s*- RFC-0001\s*$/m, `related: []`);
+    }
+    try {
+        await fs.mkdir(adrDirPath, { recursive: true });
+    }
+    catch {
+        // ignore
+    }
+    const targetPath = path.join(adrDirPath, fileName);
+    await fs.writeFile(targetPath, content, "utf-8");
+    const relativeFile = path.join(ADR_DIR, fileName);
+    if (outputFormat === "pretty") {
+        logger.success(`Created ${nextId}: ${title}`);
+        logger.info(`File: ${relativeFile}`);
+        logger.info(`Status: ${status} (only the named decider may change status)`);
+    }
+    return {
+        data: {
+            command: "adr.create",
+            status: "ok",
+            file: relativeFile,
+            id: nextId,
+        },
+        summary: `Created ${nextId}: ${title}`,
+    };
+}
+//# sourceMappingURL=list-create.js.map