@tea-agent/loop-agent 0.24.10 → 0.25.0

package/dist/worker/feature/scaffold.js

@@ -0,0 +1,798 @@
+import { access, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import YAML from "yaml";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+export const FEATURE_SCAFFOLD_TEMPLATES = [
+    "backend-only",
+    "frontend-only",
+    "fe-with-api",
+];
+export const FEATURE_ID_PATTERN = /^F-\d{4}-\d{3,}$/;
+export class ScaffoldError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ScaffoldError";
+        this.code = code;
+        this.details = details;
+    }
+}
+const DEFAULT_FORBIDDEN = ["config/prod/**", ".env", ".env.*", "secrets/**"];
+/**
+ * Deterministic Feature Packet scaffold.
+ * No model calls, no `.harness` I/O, no LoopAgentClient.
+ */
+export async function scaffoldFeaturePacket(request) {
+    const repoRoot = path.resolve(request.repoRoot);
+    await assertRepoRoot(repoRoot);
+    const inputs = await resolveInputs(request);
+    const plans = inputs.map((input) => renderWritePlan(input, repoRoot));
+    // Preflight: target existence + path containment + validate each plan in staging.
+    for (const plan of plans) {
+        const targetAbs = path.join(repoRoot, plan.featureDirRel);
+        await assertTargetAbsent(targetAbs, plan.featureId);
+        await assertFeatureDirContainment(repoRoot, targetAbs);
+    }
+    // Validate all plans in isolated temp dirs first (zero repo write until commit).
+    for (const plan of plans) {
+        await preflightValidatePlan(plan);
+    }
+    if (request.dryRun) {
+        return {
+            schemaVersion: 1,
+            ok: true,
+            dryRun: true,
+            features: plans.map((plan) => toFeatureResult(plan, repoRoot)),
+            writtenPaths: [],
+        };
+    }
+    const committed = [];
+    try {
+        for (const plan of plans) {
+            const written = await commitPlan(plan, repoRoot, request.faultInjector);
+            committed.push(written);
+            if (committed.length === 1 && plans.length > 1) {
+                await request.faultInjector?.("after-first-commit", plan.featureId);
+            }
+        }
+    }
+    catch (error) {
+        // Roll back any directories committed in this batch.
+        for (const abs of committed.reverse()) {
+            await rm(abs, { recursive: true, force: true }).catch(() => undefined);
+        }
+        // Leave no staging parents behind either.
+        await cleanupScaffoldStaging(repoRoot).catch(() => undefined);
+        if (error instanceof ScaffoldError)
+            throw error;
+        throw new ScaffoldError("write-failed", error instanceof Error ? error.message : String(error));
+    }
+    return {
+        schemaVersion: 1,
+        ok: true,
+        dryRun: false,
+        features: plans.map((plan) => toFeatureResult(plan, repoRoot)),
+        writtenPaths: committed.map((abs) => path.relative(repoRoot, abs).split(path.sep).join("/")),
+    };
+}
+async function resolveInputs(request) {
+    if (request.batchFile && request.feature) {
+        throw new ScaffoldError("invalid-args", "feature scaffold: --batch is mutually exclusive with single-feature flags");
+    }
+    if (request.batchFile) {
+        return loadBatchFile(request.batchFile);
+    }
+    if (!request.feature) {
+        throw new ScaffoldError("invalid-args", "feature scaffold requires either single-feature flags or --batch <file>");
+    }
+    return [normalizeFeatureInput(request.feature)];
+}
+async function loadBatchFile(batchFile) {
+    let rawText;
+    try {
+        rawText = await readFile(path.resolve(batchFile), "utf-8");
+    }
+    catch (error) {
+        throw new ScaffoldError("batch-parse-error", `cannot read batch file: ${batchFile}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        const trimmed = rawText.trim();
+        parsed = trimmed.startsWith("{") || trimmed.startsWith("[")
+            ? JSON.parse(trimmed)
+            : YAML.parse(rawText);
+    }
+    catch (error) {
+        throw new ScaffoldError("batch-parse-error", `batch file is not valid YAML/JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ScaffoldError("batch-parse-error", "batch file must be an object with features[]");
+    }
+    const features = parsed.features;
+    if (!Array.isArray(features) || features.length === 0) {
+        throw new ScaffoldError("batch-parse-error", "batch file features[] must be a non-empty array");
+    }
+    const inputs = features.map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new ScaffoldError("batch-parse-error", `features[${index}] must be an object`);
+        }
+        const row = entry;
+        const featureId = String(row.feature_id ?? "");
+        const title = String(row.title ?? "");
+        const template = row.template;
+        const verifyCommands = asStringArray(row.verify_commands);
+        if (!featureId || !title || !template) {
+            throw new ScaffoldError("batch-parse-error", `features[${index}] requires feature_id, title, template`);
+        }
+        if (!verifyCommands.length) {
+            throw new ScaffoldError("batch-parse-error", `features[${index}] requires non-empty verify_commands`);
+        }
+        return normalizeFeatureInput({
+            featureId,
+            title,
+            template,
+            description: typeof row.description === "string" ? row.description : undefined,
+            bePaths: asStringArray(row.be_paths),
+            fePaths: asStringArray(row.fe_paths),
+            contractPath: typeof row.contract_path === "string" ? row.contract_path : undefined,
+            verifyCommands,
+            acceptance: Array.isArray(row.acceptance)
+                ? row.acceptance
+                : undefined,
+        });
+    });
+    const seen = new Set();
+    for (const input of inputs) {
+        if (seen.has(input.featureId)) {
+            throw new ScaffoldError("batch-conflict", `duplicate feature_id in batch: ${input.featureId}`);
+        }
+        seen.add(input.featureId);
+    }
+    return inputs;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.length > 0);
+}
+export function normalizeFeatureInput(input) {
+    if (!FEATURE_ID_PATTERN.test(input.featureId)) {
+        throw new ScaffoldError("invalid-feature-id", `feature-id must match ${FEATURE_ID_PATTERN}: got ${input.featureId}`);
+    }
+    if (!FEATURE_SCAFFOLD_TEMPLATES.includes(input.template)) {
+        throw new ScaffoldError("invalid-template", `template must be one of ${FEATURE_SCAFFOLD_TEMPLATES.join("|")}; got ${input.template}`);
+    }
+    if (!input.title.trim()) {
+        throw new ScaffoldError("invalid-args", "title is required");
+    }
+    if (!input.verifyCommands.length) {
+        throw new ScaffoldError("invalid-args", "at least one --verify-command is required (scaffold does not invent project test commands)");
+    }
+    const bePaths = (input.bePaths ?? []).map(normalizeRepoRelativePath);
+    const fePaths = (input.fePaths ?? []).map(normalizeRepoRelativePath);
+    const needsBe = input.template === "backend-only" || input.template === "fe-with-api";
+    const needsFe = input.template === "frontend-only" || input.template === "fe-with-api";
+    if (needsBe && bePaths.length === 0) {
+        throw new ScaffoldError("invalid-args", `template ${input.template} requires at least one --be-path`);
+    }
+    if (needsFe && fePaths.length === 0) {
+        throw new ScaffoldError("invalid-args", `template ${input.template} requires at least one --fe-path`);
+    }
+    if (input.template === "backend-only" && fePaths.length > 0) {
+        throw new ScaffoldError("invalid-args", "backend-only does not accept --fe-path");
+    }
+    if (input.template === "frontend-only" && bePaths.length > 0) {
+        throw new ScaffoldError("invalid-args", "frontend-only does not accept --be-path");
+    }
+    const contractPath = normalizeRepoRelativePath(input.contractPath ?? `docs/contracts/${input.featureId}/api.md`);
+    return {
+        featureId: input.featureId,
+        title: input.title.trim(),
+        template: input.template,
+        description: (input.description ?? input.title).trim(),
+        bePaths,
+        fePaths,
+        contractPath,
+        verifyCommands: input.verifyCommands.map((c) => c.trim()).filter(Boolean),
+        acceptance: input.acceptance,
+    };
+}
+/**
+ * Normalize a user-supplied path pattern to a portable repo-relative form.
+ * Rejects absolute paths, empty segments with `..`, and Windows drive roots.
+ */
+export function normalizeRepoRelativePath(raw) {
+    const trimmed = raw.trim().replace(/\\/g, "/");
+    if (!trimmed) {
+        throw new ScaffoldError("invalid-path", "path must be non-empty");
+    }
+    if (path.isAbsolute(trimmed) || /^[A-Za-z]:\//.test(trimmed) || trimmed.startsWith("/")) {
+        throw new ScaffoldError("invalid-path", `path must be repo-relative: ${raw}`);
+    }
+    const parts = trimmed.split("/").filter((p) => p.length > 0 && p !== ".");
+    if (parts.some((p) => p === "..")) {
+        throw new ScaffoldError("invalid-path", `path must not contain '..': ${raw}`);
+    }
+    return parts.join("/");
+}
+export function renderWritePlan(input, repoRoot) {
+    const normalized = normalizeFeatureInput(input);
+    const featureId = normalized.featureId;
+    const repoName = path.basename(repoRoot) || "repo";
+    const files = [];
+    files.push({
+        relativePath: "feature.yaml",
+        content: YAML.stringify({
+            schema_version: 1,
+            feature_id: featureId,
+            profile: "generic",
+        }),
+    });
+    files.push({
+        relativePath: "requirement.md",
+        content: [
+            `# ${normalized.title}`,
+            "",
+            normalized.description,
+            "",
+            `Feature ID: \`${featureId}\``,
+            `Template: \`${normalized.template}\``,
+            "",
+        ].join("\n"),
+    });
+    files.push({
+        relativePath: "design.md",
+        content: renderDesign(normalized),
+    });
+    const acceptanceItems = buildAcceptance(normalized);
+    files.push({
+        relativePath: "acceptance.yaml",
+        content: YAML.stringify({
+            schema_version: 1,
+            feature_id: featureId,
+            acceptance: acceptanceItems,
+        }),
+    });
+    const graphAndTasks = renderGraphAndTasks(normalized, repoName);
+    files.push({
+        relativePath: "tasks/task-graph.yaml",
+        content: YAML.stringify(graphAndTasks.graph),
+    });
+    for (const task of graphAndTasks.tasks) {
+        files.push({
+            relativePath: `tasks/${task.id}.yaml`,
+            content: YAML.stringify(task.spec),
+        });
+    }
+    return {
+        featureId,
+        template: normalized.template,
+        featureDirRel: `features/${featureId}`,
+        files,
+    };
+}
+function renderDesign(input) {
+    const lines = [
+        `# Design — ${input.title}`,
+        "",
+        "## Goals",
+        "",
+        input.description ?? input.title,
+        "",
+        "## Paths",
+        "",
+    ];
+    if (input.bePaths?.length) {
+        lines.push("- Backend allowed paths:");
+        for (const p of input.bePaths)
+            lines.push(`  - \`${p}\``);
+    }
+    if (input.fePaths?.length) {
+        lines.push("- Frontend allowed paths:");
+        for (const p of input.fePaths)
+            lines.push(`  - \`${p}\``);
+    }
+    if (input.template === "fe-with-api" && input.contractPath) {
+        lines.push(`- Contract path: \`${input.contractPath}\``);
+    }
+    lines.push("", "## Artifacts", "");
+    if (input.template === "backend-only") {
+        lines.push("- `BE-IMPL-001` produces `backend-impl`");
+    }
+    else if (input.template === "frontend-only") {
+        lines.push("- `FE-IMPL-001` produces `frontend-impl`");
+    }
+    else {
+        lines.push("- `CONTRACT-001` produces `api-contract`");
+        lines.push("- `BE-IMPL-001` / `FE-IMPL-001` consume `api-contract` (only formal consumers)");
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function buildAcceptance(input) {
+    if (input.acceptance?.length) {
+        return input.acceptance.map((item, index) => {
+            const taskRefs = defaultTaskRefs(input.template);
+            return {
+                id: item.id || `AC-${String(index + 1).padStart(3, "0")}`,
+                title: item.title,
+                priority: item.priority ?? "must",
+                type: item.type ?? "behavior",
+                given: item.given,
+                when: item.when,
+                then: item.then,
+                verification: {
+                    expected_task_refs: taskRefs,
+                },
+            };
+        });
+    }
+    const taskRefs = defaultTaskRefs(input.template);
+    return [
+        {
+            id: "AC-001",
+            title: input.title,
+            priority: "must",
+            type: "behavior",
+            given: "需求与路径边界已冻结",
+            when: "Feature Packet 内实现任务完成",
+            then: "验收目标达成且 verify.commands 通过",
+            verification: {
+                expected_task_refs: taskRefs,
+            },
+        },
+    ];
+}
+function defaultTaskRefs(template) {
+    if (template === "backend-only")
+        return ["BE-IMPL-001"];
+    if (template === "frontend-only")
+        return ["FE-IMPL-001"];
+    return ["CONTRACT-001", "BE-IMPL-001", "FE-IMPL-001"];
+}
+function renderGraphAndTasks(input, repoName) {
+    const featureId = input.featureId;
+    const acIds = (input.acceptance?.length
+        ? input.acceptance.map((a, i) => a.id || `AC-${String(i + 1).padStart(3, "0")}`)
+        : ["AC-001"]);
+    if (input.template === "backend-only") {
+        const bePath = primaryPath(input.bePaths);
+        const graph = {
+            schema_version: 1,
+            feature_id: featureId,
+            nodes: [
+                {
+                    id: "BE-IMPL-001",
+                    task: "BE-IMPL-001.yaml",
+                    type: "backend-feature",
+                    depends_on: [],
+                    produces: [
+                        {
+                            kind: "backend-impl",
+                            schemaId: "backend-impl-v1",
+                            path: bePath,
+                        },
+                    ],
+                },
+            ],
+            parallel_policy: {
+                max_parallel_tasks: 1,
+                disallow_same_file_parallel_writes: true,
+            },
+        };
+        const spec = baseTaskSpec({
+            id: "BE-IMPL-001",
+            featureId,
+            title: `${input.title} — 后端实现`,
+            description: input.description ?? input.title,
+            type: "backend-feature",
+            workflow: "agent-dag",
+            dependsOn: [],
+            acceptanceRefs: acIds,
+            allowedPaths: withProgressPaths(input.bePaths, featureId, "be"),
+            forbiddenPaths: [...DEFAULT_FORBIDDEN, "apps/**"],
+            verifyCommands: input.verifyCommands,
+            repoName,
+            goals: ["实现后端变更并满足验收"],
+        });
+        return { graph, tasks: [{ id: "BE-IMPL-001", spec }] };
+    }
+    if (input.template === "frontend-only") {
+        const fePath = primaryPath(input.fePaths);
+        const graph = {
+            schema_version: 1,
+            feature_id: featureId,
+            nodes: [
+                {
+                    id: "FE-IMPL-001",
+                    task: "FE-IMPL-001.yaml",
+                    type: "frontend-feature",
+                    depends_on: [],
+                    produces: [
+                        {
+                            kind: "frontend-impl",
+                            schemaId: "frontend-impl-v1",
+                            path: fePath,
+                        },
+                    ],
+                },
+            ],
+            parallel_policy: {
+                max_parallel_tasks: 1,
+                disallow_same_file_parallel_writes: true,
+            },
+        };
+        const spec = baseTaskSpec({
+            id: "FE-IMPL-001",
+            featureId,
+            title: `${input.title} — 前端实现`,
+            description: input.description ?? input.title,
+            type: "frontend-feature",
+            workflow: "frontend-implementation",
+            dependsOn: [],
+            acceptanceRefs: acIds,
+            allowedPaths: withProgressPaths(input.fePaths, featureId, "fe"),
+            forbiddenPaths: [...DEFAULT_FORBIDDEN, "services/**"],
+            verifyCommands: input.verifyCommands,
+            repoName,
+            goals: ["实现前端变更并满足验收"],
+            capabilities: ["interactive-ui"],
+        });
+        return { graph, tasks: [{ id: "FE-IMPL-001", spec }] };
+    }
+    // fe-with-api
+    const contractPath = input.contractPath;
+    const bePath = primaryPath(input.bePaths);
+    const fePath = primaryPath(input.fePaths);
+    const graph = {
+        schema_version: 1,
+        feature_id: featureId,
+        nodes: [
+            {
+                id: "CONTRACT-001",
+                task: "CONTRACT-001.yaml",
+                type: "architecture",
+                depends_on: [],
+                produces: [
+                    {
+                        kind: "api-contract",
+                        schemaId: "api-contract-v1",
+                        path: contractPath,
+                    },
+                ],
+            },
+            {
+                id: "BE-IMPL-001",
+                task: "BE-IMPL-001.yaml",
+                type: "backend-feature",
+                depends_on: ["CONTRACT-001"],
+                consumes: [
+                    {
+                        kind: "api-contract",
+                        schemaId: "api-contract-v1",
+                        producerTaskId: "CONTRACT-001",
+                    },
+                ],
+                produces: [
+                    {
+                        kind: "backend-impl",
+                        schemaId: "backend-impl-v1",
+                        path: bePath,
+                    },
+                ],
+            },
+            {
+                id: "FE-IMPL-001",
+                task: "FE-IMPL-001.yaml",
+                type: "frontend-feature",
+                depends_on: ["CONTRACT-001"],
+                consumes: [
+                    {
+                        kind: "api-contract",
+                        schemaId: "api-contract-v1",
+                        producerTaskId: "CONTRACT-001",
+                    },
+                ],
+                produces: [
+                    {
+                        kind: "frontend-impl",
+                        schemaId: "frontend-impl-v1",
+                        path: fePath,
+                    },
+                ],
+            },
+        ],
+        parallel_policy: {
+            max_parallel_tasks: 1,
+            disallow_same_file_parallel_writes: true,
+        },
+    };
+    const contractSpec = baseTaskSpec({
+        id: "CONTRACT-001",
+        featureId,
+        title: `${input.title} — API 契约`,
+        description: `冻结 ${contractPath}；正式 consumers 仅为 BE-IMPL-001 与 FE-IMPL-001。`,
+        type: "architecture",
+        workflow: "agent-dag",
+        dependsOn: [],
+        acceptanceRefs: acIds,
+        allowedPaths: withProgressPaths([contractPath], featureId, "contract"),
+        forbiddenPaths: [...DEFAULT_FORBIDDEN, "services/**", "apps/**"],
+        verifyCommands: input.verifyCommands,
+        repoName,
+        goals: ["冻结 API 契约文档", "声明正式 consumers 仅为 BE-IMPL / FE-IMPL"],
+        riskLevel: "low",
+        priority: "P1",
+    });
+    const beSpec = baseTaskSpec({
+        id: "BE-IMPL-001",
+        featureId,
+        title: `${input.title} — 后端实现`,
+        description: input.description ?? input.title,
+        type: "backend-feature",
+        workflow: "agent-dag",
+        dependsOn: ["CONTRACT-001"],
+        acceptanceRefs: acIds,
+        allowedPaths: withProgressPaths(input.bePaths, featureId, "be"),
+        forbiddenPaths: [...DEFAULT_FORBIDDEN, "apps/**"],
+        verifyCommands: input.verifyCommands,
+        repoName,
+        goals: ["按契约实现后端"],
+    });
+    const feSpec = baseTaskSpec({
+        id: "FE-IMPL-001",
+        featureId,
+        title: `${input.title} — 前端实现`,
+        description: input.description ?? input.title,
+        type: "frontend-feature",
+        workflow: "frontend-implementation",
+        dependsOn: ["CONTRACT-001"],
+        acceptanceRefs: acIds,
+        allowedPaths: withProgressPaths(input.fePaths, featureId, "fe"),
+        forbiddenPaths: [...DEFAULT_FORBIDDEN, "services/**"],
+        verifyCommands: input.verifyCommands,
+        repoName,
+        goals: ["按契约实现前端"],
+        capabilities: ["interactive-ui"],
+    });
+    return {
+        graph,
+        tasks: [
+            { id: "CONTRACT-001", spec: contractSpec },
+            { id: "BE-IMPL-001", spec: beSpec },
+            { id: "FE-IMPL-001", spec: feSpec },
+        ],
+    };
+}
+function primaryPath(paths) {
+    const first = paths[0];
+    // Strip trailing globs for produces.path readability.
+    return first.replace(/\/\*\*$/, "").replace(/\*$/, "") || first;
+}
+function withProgressPaths(paths, featureId, lane) {
+    return [
+        ...paths,
+        `docs/progress/${featureId}/${lane}/status.md`,
+        `docs/progress/${featureId}/${lane}/**`,
+    ];
+}
+function baseTaskSpec(input) {
+    return {
+        schema_version: 1,
+        id: input.id,
+        feature_id: input.featureId,
+        title: input.title,
+        description: input.description,
+        repo: {
+            name: input.repoName,
+            path_ref: ".",
+            default_branch: "main",
+        },
+        type: input.type,
+        priority: input.priority ?? "P2",
+        risk_level: input.riskLevel ?? "medium",
+        ...(input.capabilities ? { capabilities: input.capabilities } : {}),
+        depends_on: input.dependsOn,
+        source_docs: {
+            requirement: "../requirement.md",
+            acceptance: "../acceptance.yaml",
+            design: "../design.md",
+        },
+        acceptance_refs: input.acceptanceRefs,
+        scope: {
+            goals: input.goals,
+            non_goals: ["不扩展到模板外的 Task 节点（无 BE-TEST/FE-TEST/FINAL-VERIFY）"],
+            assumptions: ["verify.commands 由 scaffold 调用方显式提供"],
+            open_questions: [],
+        },
+        constraints: {
+            allowed_paths: input.allowedPaths,
+            forbidden_paths: input.forbiddenPaths,
+            hard_constraints: [
+                "不读取生产密钥",
+                "不绕过 scaffold 冻结的 depends/produces/consumes",
+            ],
+        },
+        execution: {
+            workflow: input.workflow,
+        },
+        verify: {
+            preset: "standard",
+            mode: "serial",
+            quota: "full",
+            commands: input.verifyCommands.map((command, index) => ({
+                id: `verify-${index + 1}`,
+                label: command,
+                command,
+                required: true,
+                timeout_ms: 300000,
+            })),
+        },
+        worker: {
+            execution_mode: "generate-validate-run",
+            max_attempts: 1,
+            timeout_ms: 7200000,
+            require_clean_worktree: true,
+            require_human_review: true,
+            create_worktree: false,
+        },
+        loop_agent: {
+            profile_policy: "mapped",
+            strict_models: true,
+            strict_governance: true,
+            max_concurrent: 1,
+        },
+        outputs: {
+            required: [
+                "dag_json",
+                "dag_validate_json",
+                "run_record",
+                "dag_report_json",
+                "shell_verification",
+                "closeout_or_failure_handoff",
+            ],
+        },
+        failure_policy: {
+            failed_run_promote: false,
+            generate_closeout_draft: true,
+            create_followup_task: true,
+        },
+    };
+}
+async function preflightValidatePlan(plan) {
+    const stageRoot = await mkdtemp(path.join(os.tmpdir(), "feature-scaffold-validate-"));
+    try {
+        const featureDir = path.join(stageRoot, plan.featureId);
+        await materializePlan(plan, featureDir);
+        const result = await validateFeatureTaskGraph(featureDir);
+        if (!result.ok) {
+            throw new ScaffoldError("validate-failed", `rendered packet failed validate-feature for ${plan.featureId}`, result.errors);
+        }
+        if (result.summary.profile !== "generic") {
+            throw new ScaffoldError("validate-failed", `scaffold must emit generic profile; got ${result.summary.profile}`);
+        }
+    }
+    finally {
+        await rm(stageRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function commitPlan(plan, repoRoot, faultInjector) {
+    const featuresRoot = path.join(repoRoot, "features");
+    await mkdir(featuresRoot, { recursive: true });
+    await assertFeatureDirContainment(repoRoot, path.join(featuresRoot, plan.featureId));
+    const stageParent = path.join(featuresRoot, `.scaffold-staging-${plan.featureId}`);
+    const stageDir = path.join(stageParent, plan.featureId);
+    const targetDir = path.join(featuresRoot, plan.featureId);
+    await rm(stageParent, { recursive: true, force: true }).catch(() => undefined);
+    try {
+        await mkdir(stageDir, { recursive: true });
+        // Reject symlink escape on features root after create.
+        await assertNoSymlinkEscape(repoRoot, stageDir);
+        await materializePlan(plan, stageDir);
+        await faultInjector?.("after-stage-materialize", plan.featureId);
+        // Re-validate staged packet (same FS as final) before rename.
+        const stagedValidation = await validateFeatureTaskGraph(stageDir);
+        if (!stagedValidation.ok) {
+            throw new ScaffoldError("validate-failed", `staged packet failed validate-feature for ${plan.featureId}`, stagedValidation.errors);
+        }
+        await assertTargetAbsent(targetDir, plan.featureId);
+        await faultInjector?.("before-rename", plan.featureId);
+        await rename(stageDir, targetDir);
+        await rm(stageParent, { recursive: true, force: true }).catch(() => undefined);
+        return targetDir;
+    }
+    catch (error) {
+        await rm(stageParent, { recursive: true, force: true }).catch(() => undefined);
+        if (error instanceof ScaffoldError)
+            throw error;
+        throw new ScaffoldError("write-failed", error instanceof Error ? error.message : String(error));
+    }
+}
+async function cleanupScaffoldStaging(repoRoot) {
+    const featuresRoot = path.join(repoRoot, "features");
+    try {
+        const entries = await readdir(featuresRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.startsWith(".scaffold-staging-")) {
+                await rm(path.join(featuresRoot, entry.name), {
+                    recursive: true,
+                    force: true,
+                });
+            }
+        }
+    }
+    catch {
+        // features/ may not exist after total rollback
+    }
+}
+async function materializePlan(plan, featureDirAbs) {
+    for (const file of plan.files) {
+        const abs = path.join(featureDirAbs, ...file.relativePath.split("/"));
+        await mkdir(path.dirname(abs), { recursive: true });
+        await writeFile(abs, file.content.endsWith("\n") ? file.content : `${file.content}\n`, "utf-8");
+    }
+}
+function toFeatureResult(plan, repoRoot) {
+    return {
+        featureId: plan.featureId,
+        template: plan.template,
+        featureDir: path.join(repoRoot, plan.featureDirRel),
+        files: plan.files.map((f) => f.relativePath).sort(),
+    };
+}
+async function assertRepoRoot(repoRoot) {
+    try {
+        const st = await lstat(repoRoot);
+        if (!st.isDirectory()) {
+            throw new ScaffoldError("repo-missing", `repo is not a directory: ${repoRoot}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof ScaffoldError)
+            throw error;
+        throw new ScaffoldError("repo-missing", `repo does not exist: ${repoRoot}`);
+    }
+}
+async function assertTargetAbsent(targetAbs, featureId) {
+    try {
+        await access(targetAbs);
+        throw new ScaffoldError("target-exists", `feature directory already exists (no --force): features/${featureId}`);
+    }
+    catch (error) {
+        if (error instanceof ScaffoldError)
+            throw error;
+        // ENOENT is success
+    }
+}
+async function assertFeatureDirContainment(repoRoot, targetAbs) {
+    // Resolve the repo root (handles macOS /var -> /private/var). The target may
+    // not exist yet, so re-base it on the real repo rather than realpath(target).
+    const resolvedRepo = path.resolve(repoRoot);
+    const realRepo = await realpath(resolvedRepo).catch(() => resolvedRepo);
+    const featuresRoot = path.join(realRepo, "features");
+    const resolvedTarget = path.resolve(targetAbs);
+    let normalizedTarget = resolvedTarget;
+    const relFromResolvedRepo = path.relative(resolvedRepo, resolvedTarget);
+    if (!relFromResolvedRepo.startsWith("..") && !path.isAbsolute(relFromResolvedRepo)) {
+        normalizedTarget = path.join(realRepo, relFromResolvedRepo);
+    }
+    const rel = path.relative(featuresRoot, normalizedTarget);
+    if (rel === "" ||
+        rel === "." ||
+        rel === ".." ||
+        rel.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(rel) ||
+        rel.split(path.sep).includes("..")) {
+        throw new ScaffoldError("invalid-path", `feature path escapes repo/features: ${targetAbs}`);
+    }
+}
+async function assertNoSymlinkEscape(repoRoot, candidate) {
+    const realRepo = await realpath(repoRoot);
+    const realCandidate = await realpath(candidate);
+    const rel = path.relative(realRepo, realCandidate);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new ScaffoldError("invalid-path", `staging path escapes repo via symlink: ${candidate}`);
+    }
+}