@drawcall/create 0.1.3 → 0.2.0

package/dist/scaffold.js

@@ -2,36 +2,100 @@ import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+import { Context, Effect, Layer } from "effect";
+import { classifyHarnessOutput } from "./classify.js";
 import { GITHUB_SKILLS, GITIGNORE_ENTRIES, PACKAGE_SKILLS, PACKAGES } from "./constants.js";
-import { assertExitCode } from "./subprocess.js";
+import { FsFailure, StageFailure } from "./errors.js";
+import { Shell } from "./shell.js";
 export function generateProjectName() {
     return `dc-${randomBytes(3).toString("hex")}`;
 }
-export async function initGitRepo(cwd, runner) {
-    await assertExitCode(runner({ command: "git", args: ["init"], cwd }), "failed to initialise git repository");
-}
-export async function commitAll(cwd, runner, message) {
-    await assertExitCode(runner({ command: "git", args: ["add", "-A"], cwd }), "failed to stage changes");
-    // A build turn often commits its own work mid-turn (the harness runs git itself). When it does,
-    // the staged tree is already clean here and an --allow-empty commit would mint a second, empty
-    // "feat: build turn N" — so commit count drifts above turn count. Only commit when something is
-    // actually staged; otherwise the turn's own commit already records this turn's completion.
-    if (await isTreeClean(cwd, runner))
-        return;
-    await assertExitCode(runner({ command: "git", args: ["commit", "-m", message], cwd }), "failed to commit changes");
-}
-// True when `git add -A` left nothing staged (a clean index against HEAD). `git diff --cached
-// --quiet` exits 0 when there are no staged changes and 1 when there are, which is exactly the
-// signal we want — so we read its exit code rather than asserting it.
-async function isTreeClean(cwd, runner) {
-    const { exitCode } = await runner({
-        command: "git",
-        args: ["diff", "--cached", "--quiet"],
-        cwd
+// Our harness names don't all match the `skills` CLI's agent ids.
+const SKILLS_AGENT = {
+    opencode: "opencode",
+    codex: "codex",
+    claude: "claude-code",
+    pi: "pi",
+    gemini: "gemini-cli",
+    grok: "universal",
+    forge: "universal"
+};
+export class Scaffold extends Context.Tag("Scaffold")() {
+}
+const fail = (label, output, exitCode, timedOut) => new StageFailure({
+    stage: "scaffold",
+    reason: classifyHarnessOutput(output, exitCode, timedOut),
+    detail: `${label}: ${output.slice(-400)}`
+});
+const live = (shell) => {
+    const fsOp = (op, path, run) => Effect.tryPromise({
+        try: run,
+        catch: (e) => new FsFailure({ op, path, detail: String(e) })
     });
-    return exitCode === 0;
+    const step = (cwd, label, command, args) => shell
+        .run({ command, args, cwd })
+        .pipe(Effect.flatMap((r) => r.exitCode === 0
+        ? Effect.void
+        : Effect.fail(fail(label, r.output, r.exitCode, r.timedOut))));
+    return {
+        run: (cwd, harness) => Effect.gen(function* () {
+            yield* fsOp("seed", cwd, () => seedProjectFiles(cwd));
+            // The curated set installs together; their peer ranges drift, and modern npm aborts on the
+            // first mismatch — so install as-specified and let the pinned versions stand.
+            yield* step(cwd, "npm install", "npm", ["install", "--legacy-peer-deps", ...PACKAGES]);
+            yield* fsOp("shims", cwd, () => ensureLocalCliShims(cwd));
+            // Dependencies first: PACKAGE_SKILLS install from their package directory under node_modules,
+            // which only exists once dependencies are installed.
+            const agent = SKILLS_AGENT[harness];
+            for (const skill of GITHUB_SKILLS) {
+                yield* step(cwd, `skills add ${skill}`, "npx", [
+                    "--yes",
+                    "skills",
+                    "add",
+                    skill,
+                    "-y",
+                    "--agent",
+                    agent
+                ]);
+            }
+            for (const pkg of PACKAGE_SKILLS) {
+                // Absolute path so the source is unambiguous (a bare "node_modules/@x/y" reads as a GitHub
+                // owner/repo slug).
+                yield* step(cwd, `skills add ${pkg}`, "npx", [
+                    "--yes",
+                    "skills",
+                    "add",
+                    join(cwd, "node_modules", pkg),
+                    "-y",
+                    "--agent",
+                    agent
+                ]);
+            }
+        })
+    };
+};
+export const ScaffoldLive = Layer.effect(Scaffold, Effect.map(Shell, (shell) => live(shell)));
+// --- file seeding ----------------------------------------------------------
+async function seedProjectFiles(cwd) {
+    await ensureProjectGitignore(cwd);
+    await ensureNpmrc(cwd);
+    for (const directoryName of ["src", "public"]) {
+        const directory = join(cwd, directoryName);
+        await mkdir(directory, { recursive: true });
+        const placeholder = join(directory, ".gitkeep");
+        if (!existsSync(placeholder))
+            await writeFile(placeholder, "");
+    }
+    await initNpmProject(cwd);
+}
+function toPackageName(name) {
+    const normalized = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._~-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized || "drawcall-project";
 }
-export async function initNpmProject(cwd, _runner) {
+async function initNpmProject(cwd) {
     const packageJsonPath = join(cwd, "package.json");
     if (existsSync(packageJsonPath))
         return;
@@ -39,146 +103,47 @@ export async function initNpmProject(cwd, _runner) {
         name: toPackageName(basename(cwd)),
         version: "1.0.0",
         private: true,
-        // Seed runnable scripts so every project is launchable from turn 1 (Vite is the pinned
-        // bundler). Build turns serve via `npm run dev` and bundle via `npm run build`; without
-        // these, weaker harnesses ship a project with no documented way to run the game.
         type: "module",
-        scripts: {
-            dev: "vite",
-            build: "vite build",
-            preview: "vite preview"
-        }
+        scripts: { dev: "vite", build: "vite build", preview: "vite preview" }
     }, null, 2)}\n`);
 }
-function toPackageName(name) {
-    const normalized = name
-        .toLowerCase()
-        .replace(/[^a-z0-9._~-]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    return normalized || "drawcall-project";
-}
-export async function ensureProjectGitignore(cwd) {
+async function ensureProjectGitignore(cwd) {
     const gitignorePath = join(cwd, ".gitignore");
     const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
     const existingEntries = new Set(existing
         .split(/\r?\n/)
         .map((line) => line.trim())
         .filter((line) => line && !line.startsWith("#")));
-    const missingEntries = GITIGNORE_ENTRIES.filter((entry) => !existingEntries.has(entry));
-    if (missingEntries.length === 0)
+    const missing = GITIGNORE_ENTRIES.filter((entry) => !existingEntries.has(entry));
+    if (missing.length === 0)
         return;
-    const prefix = existing.trimEnd();
-    const nextContent = [prefix, ...missingEntries].filter(Boolean).join("\n") + "\n";
-    await writeFile(gitignorePath, nextContent);
+    const next = [existing.trimEnd(), ...missing].filter(Boolean).join("\n") + "\n";
+    await writeFile(gitignorePath, next);
 }
-// The curated package set pins a recent `three`, but some Drawcall packages declare peer ranges
-// that lag a minor or two (e.g. @drawcall/flipbook peers an older three). The scaffold's own
-// install passes `--legacy-peer-deps`, but later installs — a harness running `npm install`, or
-// `market install` applying a template — run plain and would abort on the first peer mismatch.
-// A persisted `.npmrc` makes the whole project tolerant so those installs don't veto a pinned
-// version over a peer-range lag.
-export async function ensureNpmrc(cwd) {
+async function ensureNpmrc(cwd) {
     const npmrcPath = join(cwd, ".npmrc");
     const existing = existsSync(npmrcPath) ? await readFile(npmrcPath, "utf8") : "";
     if (/^\s*legacy-peer-deps\s*=/m.test(existing))
         return;
-    const prefix = existing.trimEnd();
-    const nextContent = [prefix, "legacy-peer-deps=true"].filter(Boolean).join("\n") + "\n";
-    await writeFile(npmrcPath, nextContent);
+    const next = [existing.trimEnd(), "legacy-peer-deps=true"].filter(Boolean).join("\n") + "\n";
+    await writeFile(npmrcPath, next);
 }
-export async function ensureBaseProjectDirectories(cwd) {
-    for (const directoryName of ["src", "public"]) {
-        const directory = join(cwd, directoryName);
-        await mkdir(directory, { recursive: true });
-        const placeholder = join(directory, ".gitkeep");
-        if (!existsSync(placeholder))
-            await writeFile(placeholder, "");
-    }
-}
-// Our harness names don't all match the `skills` CLI's agent ids.
-const SKILLS_AGENT = {
-    opencode: "opencode",
-    codex: "codex",
-    claude: "claude-code",
-    pi: "pi",
-    gemini: "gemini-cli",
-    // The skills CLI has no dedicated grok agent; "universal" installs to .agents/skills, which
-    // grok discovers. Verify skill discovery in grok's e2e run and adjust if it misses them.
-    grok: "universal",
-    // Likewise no dedicated forge agent; "universal" (.agents/skills) is the portable target.
-    // Verify forge actually discovers the installed skills in its e2e run and adjust if it misses.
-    forge: "universal"
-};
-// Must run after installDependencies: the PACKAGE_SKILLS are installed from their package directory
-// under node_modules, which only exists once dependencies are installed.
-export async function installSkills(cwd, harness, runner) {
-    const agent = SKILLS_AGENT[harness];
-    const addSkill = (source, label) => assertExitCode(runner({
-        command: "npx",
-        args: ["--yes", "skills", "add", source, "-y", "--agent", agent],
-        cwd
-    }), `failed to install skill ${label}`);
-    for (const skill of GITHUB_SKILLS) {
-        await addSkill(skill, skill);
-    }
-    // Install the private-repo skills from their already-installed npm package (see PACKAGE_SKILLS).
-    // An absolute path is unambiguous — a bare "node_modules/@drawcall/acta" would be read as an
-    // owner/repo GitHub slug.
-    for (const pkg of PACKAGE_SKILLS) {
-        await addSkill(join(cwd, "node_modules", pkg), pkg);
-    }
-}
-export async function installDependencies(cwd, runner) {
-    // This is a fixed, curated set of packages we install together; their peer ranges drift
-    // independently (e.g. a runtime that pins an older `three` minor), and modern npm aborts the
-    // whole install on the first peer mismatch. We don't want a generated project to fail to
-    // scaffold over a peer-range lag in one package, so we install the set as-specified and let
-    // the pinned versions stand rather than letting peer resolution veto them.
-    await assertExitCode(runner({ command: "npm", args: ["install", "--legacy-peer-deps", ...PACKAGES], cwd }), "failed to install dependencies");
-    await ensureLocalCliShims(cwd);
-}
-// Called after the template stage: an applied starter may already ship a README, so this only
-// creates a minimal state-record when none exists. The fixed goal lives in GOAL.md; the plan
-// lives in PLAN.md.
-export async function ensureStateReadme(cwd) {
-    const readmePath = join(cwd, "README.md");
-    if (existsSync(readmePath))
-        return;
-    await writeFile(readmePath, `# Project State
-
-This is the state-record: what the product actually is right now. The fixed goal
-lives in GOAL.md; the plan toward it lives in PLAN.md once planning has run.
-
-## Verified State
-
-- Nothing verified yet — the project was just scaffolded.
-
-## Next Step
-
-- Survey the fitting installed skills, packages, and Market assets, then plan and build the first real slice toward the full goal without shrinking it into a prototype.
-
-## Proof Log
-
-- No proof-run has been recorded yet.
-`);
-}
-// --- Installed-package shims -------------------------------------------------
-// The @drawcall/acta and @drawcall/market packages ship CLIs/install logic that
-// assume a different layout than a freshly-generated project. These helpers
-// patch the installed copies in node_modules so their bins resolve locally.
-export async function ensureLocalCliShims(cwd) {
+// --- installed-package shims ----------------------------------------------
+// @drawcall/acta and @drawcall/market ship CLIs/install logic assuming a different layout than a
+// freshly generated project. Patch the installed copies so their bins resolve locally.
+async function ensureLocalCliShims(cwd) {
     await ensureActaCliShim(cwd);
     await ensureMarketCliShim(cwd);
 }
-export async function ensureMarketCliShim(cwd) {
+async function ensureMarketCliShim(cwd) {
     const packageRoot = join(cwd, "node_modules", "@drawcall", "market");
     await rewriteMarketInstallRoot(join(packageRoot, "dist", "install.js"));
     await rewriteMarketInstallRoot(join(packageRoot, "src", "install.ts"));
 }
-export async function ensureActaCliShim(cwd) {
+async function ensureActaCliShim(cwd) {
     const packageRoot = join(cwd, "node_modules", "@drawcall", "acta");
-    const devShim = join(packageRoot, "src", "cli", "dev.ts");
     const sourceCli = join(packageRoot, "src", "cli", "index.js");
+    const devShim = join(packageRoot, "src", "cli", "dev.ts");
     const distCli = join(packageRoot, "dist", "cli", "index.js");
     const packageJsonPath = join(packageRoot, "package.json");
     const binShim = join(cwd, "node_modules", ".bin", "acta");
@@ -190,33 +155,23 @@ export async function ensureActaCliShim(cwd) {
         await writeFile(devShim, "#!/usr/bin/env node\nimport '../../dist/cli/index.js';\n");
         await chmod(devShim, 0o755);
     }
-    await rewriteActaPackageBin(packageJsonPath);
-    await rewriteActaPackageEntrypoint(packageJsonPath);
+    await rewriteActaPackageJson(packageJsonPath);
     await mkdir(dirname(binShim), { recursive: true });
     await rm(binShim, { force: true });
     await writeFile(binShim, "#!/usr/bin/env node\nimport '../@drawcall/acta/dist/cli/index.js';\n");
     await chmod(binShim, 0o755);
 }
-async function rewriteActaPackageBin(packageJsonPath) {
+async function rewriteActaPackageJson(packageJsonPath) {
     if (!existsSync(packageJsonPath))
         return;
     const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
     const existingBin = packageJson.bin && typeof packageJson.bin === "object" ? packageJson.bin : {};
     packageJson.bin = { ...existingBin, acta: "dist/cli/index.js" };
-    await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
-}
-async function rewriteActaPackageEntrypoint(packageJsonPath) {
-    if (!existsSync(packageJsonPath))
-        return;
-    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
     packageJson.main = "dist/index.js";
     packageJson.types = "dist/index.d.ts";
     packageJson.exports = {
         ...(packageJson.exports ?? {}),
-        ".": {
-            types: "./dist/index.d.ts",
-            import: "./dist/index.js"
-        }
+        ".": { types: "./dist/index.d.ts", import: "./dist/index.js" }
     };
     await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
 }
@@ -241,7 +196,6 @@ async function rewriteMarketInstallRoot(filePath) {
 
 async function downloadAssets`;
     const patched = source.replace(/export async function findInstallRoot[\s\S]*?\n}\n\n?async function downloadAssets/, replacement);
-    if (patched !== source) {
+    if (patched !== source)
         await writeFile(filePath, patched);
-    }
 }

package/dist/shell.d.ts

@@ -0,0 +1,22 @@
+import { Context, Effect, Layer } from "effect";
+import { Logger } from "./logger.js";
+export interface CommandSpec {
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    readonly cwd: string;
+    readonly timeoutMs?: number;
+}
+export interface CommandResult {
+    readonly exitCode: number;
+    readonly output: string;
+    readonly timedOut: boolean;
+}
+export interface ShellService {
+    readonly run: (spec: CommandSpec) => Effect.Effect<CommandResult>;
+    readonly exists: (command: string) => Effect.Effect<boolean>;
+}
+declare const Shell_base: Context.TagClass<Shell, "Shell", ShellService>;
+export declare class Shell extends Shell_base {
+}
+export declare const ShellLive: (env?: NodeJS.ProcessEnv) => Layer.Layer<Shell, never, Logger>;
+export {};

package/dist/shell.js

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { delimiter, dirname, join, resolve } from "node:path";
+import which from "which";
+import { Context, Effect, Layer } from "effect";
+import { TIMEOUT_EXIT_CODE, TIMEOUT_KILL_GRACE_MS } from "./constants.js";
+import { Logger } from "./logger.js";
+export class Shell extends Context.Tag("Shell")() {
+}
+// Prepend the project's local bin and fence git's directory walk to the project's parent, so a
+// harness spawned in the project resolves project-local CLIs and never escapes upward to a parent
+// repo. (Kept verbatim from the original runner — this is hard-won and not Effect-specific.)
+function buildSubprocessEnv(cwd, baseEnv = process.env) {
+    const projectParent = dirname(resolve(cwd));
+    const localBin = join(resolve(cwd), "node_modules", ".bin");
+    return {
+        ...baseEnv,
+        PATH: baseEnv.PATH ? `${localBin}${delimiter}${baseEnv.PATH}` : localBin,
+        GIT_CEILING_DIRECTORIES: baseEnv.GIT_CEILING_DIRECTORIES
+            ? `${projectParent}${delimiter}${baseEnv.GIT_CEILING_DIRECTORIES}`
+            : projectParent
+    };
+}
+// Signals never reach a detached child group directly, so tear the whole tree down explicitly. On
+// win32 there are no process groups; taskkill /T removes the tree.
+function killTree(child, detached, signal) {
+    const pid = child.pid;
+    if (!pid)
+        return;
+    if (process.platform === "win32") {
+        spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" }).unref();
+        return;
+    }
+    try {
+        process.kill(detached ? -pid : pid, signal);
+    }
+    catch {
+        /* already exited between the timeout firing and this kill */
+    }
+}
+const live = (env, logger) => ({
+    exists: (command) => Effect.promise(async () => {
+        const resolved = await which(command, {
+            nothrow: true,
+            path: env.PATH,
+            pathExt: env.PATHEXT
+        });
+        return resolved !== null;
+    }),
+    run: ({ command, args, cwd, timeoutMs }) => 
+    // Effect.async so an outer interruption (Ctrl-C, an enclosing timeout) runs the returned
+    // finalizer and kills the child tree — the heavy harness process can never outlive its fiber.
+    Effect.async((resume) => {
+        const startedAt = Date.now();
+        const detached = process.platform !== "win32";
+        const captured = [];
+        // The Logger is synchronous (it appends to the hidden log); runSync bridges it into node's
+        // event callbacks below, where we cannot await.
+        const log = (text) => Effect.runSync(logger.write(text));
+        log(`\n$ ${[command, ...args].join(" ")}`);
+        const child = spawn(command, [...args], {
+            cwd,
+            detached,
+            env: buildSubprocessEnv(cwd, env),
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        // Read both streams a line at a time so a timestamp only ever prefixes a whole line, and keep
+        // every line for classification.
+        for (const stream of [child.stdout, child.stderr]) {
+            if (!stream)
+                continue;
+            createInterface({ input: stream }).on("line", (line) => {
+                captured.push(line);
+                Effect.runSync(logger.captured(line));
+            });
+        }
+        let timedOut = false;
+        let killTimer;
+        const timeout = timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                log(`[create] ${command} timed out after ${Math.ceil(timeoutMs / 1000)}s`);
+                killTree(child, detached, "SIGTERM");
+                killTimer = setTimeout(() => killTree(child, detached, "SIGKILL"), TIMEOUT_KILL_GRACE_MS);
+            }, timeoutMs);
+        const cleanup = () => {
+            if (timeout)
+                clearTimeout(timeout);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
+        child.once("error", (error) => {
+            cleanup();
+            // spawn failed (command not found, etc.): surface as a non-zero exit with the error text so
+            // the caller can classify it like any other failure.
+            captured.push(String(error.message ?? error));
+            resume(Effect.succeed({ exitCode: 127, output: captured.join("\n"), timedOut }));
+        });
+        child.once("exit", (code, signal) => {
+            cleanup();
+            const exitCode = timedOut ? TIMEOUT_EXIT_CODE : signal ? 1 : (code ?? 1);
+            const elapsed = Math.round((Date.now() - startedAt) / 1000);
+            const failure = !timedOut && exitCode !== 0 ? ` — exit ${exitCode}` : "";
+            log(`[create] ${command} done in ${elapsed}s${failure}`);
+            resume(Effect.succeed({ exitCode, output: captured.join("\n"), timedOut }));
+        });
+        return Effect.sync(() => {
+            cleanup();
+            killTree(child, detached, "SIGKILL");
+        });
+    })
+});
+export const ShellLive = (env = process.env) => Layer.effect(Shell, Effect.map(Logger, (logger) => live(env, logger)));

package/dist/stages.d.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import { type HarnessName, type PipelineStage } from "./constants.js";
+import { type RunFailure } from "./errors.js";
+import { Git, type RunMeta } from "./git.js";
+import { Harness } from "./harness.js";
+import { Scaffold } from "./scaffold.js";
+export interface RunContext {
+    readonly cwd: string;
+    readonly prompt: string;
+    readonly harness: HarnessName;
+    readonly harnessArgs?: ReadonlyArray<string>;
+    readonly timeoutMs?: number;
+    readonly skipTemplate?: boolean;
+}
+type StageEnv = Harness | Scaffold | Git;
+export declare const runStage: (stage: Exclude<PipelineStage, "build">, ctx: RunContext, runMeta: RunMeta | undefined) => Effect.Effect<void, RunFailure, StageEnv>;
+export declare const buildTurn: (ctx: RunContext, turnNumber: number) => Effect.Effect<void, RunFailure, StageEnv>;
+export {};

package/dist/stages.js

@@ -0,0 +1,120 @@
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Effect } from "effect";
+import { classifyHarnessOutput } from "./classify.js";
+import { GOAL_FILE, PLAN_FILE, README_FILE } from "./constants.js";
+import { FsFailure, StageFailure } from "./errors.js";
+import { Git } from "./git.js";
+import { Harness } from "./harness.js";
+import { Scaffold } from "./scaffold.js";
+import { buildBuildPrompt, buildGoalPrompt, buildPlanPrompt, buildSurveyAssetsPrompt, buildSurveyTechnologyPrompt, buildTemplatePrompt } from "./prompts.js";
+// Run one harness turn for a stage, turning a non-zero exit / timeout into a classified, explainable
+// StageFailure. A clean exit is success — the stage's own assertions (did GOAL.md appear?) catch the
+// "ran fine but produced nothing" case separately.
+const turn = (stage, prompt, ctx) => Effect.flatMap(Harness, (harness) => harness
+    .runTurn({
+    harness: ctx.harness,
+    prompt,
+    cwd: ctx.cwd,
+    harnessArgs: ctx.harnessArgs,
+    timeoutMs: ctx.timeoutMs
+})
+    .pipe(Effect.flatMap((r) => r.exitCode === 0
+    ? Effect.void
+    : Effect.fail(new StageFailure({
+        stage,
+        reason: classifyHarnessOutput(r.output, r.exitCode, r.timedOut),
+        detail: r.output.slice(-400)
+    })))));
+const assertProduced = (ctx, file, stage) => existsSync(join(ctx.cwd, file))
+    ? Effect.void
+    : Effect.fail(new StageFailure({
+        stage,
+        reason: { _tag: "Local", op: `${stage} output`, detail: `did not create ${file}` },
+        detail: `harness finished without creating ${file}`
+    }));
+// Templates may ship their own README; only seed the minimal state-record when none exists.
+const ensureStateReadme = (cwd) => {
+    const path = join(cwd, README_FILE);
+    if (existsSync(path))
+        return Effect.void;
+    return Effect.tryPromise({
+        try: () => writeFile(path, `# Project State
+
+This is the state-record: what the product actually is right now. The fixed goal
+lives in GOAL.md; the plan toward it lives in PLAN.md once planning has run.
+
+## Verified State
+
+- Nothing verified yet — the project was just scaffolded.
+
+## Next Step
+
+- Survey the fitting installed skills, packages, and Market assets, then plan and build the first real slice toward the full goal without shrinking it into a prototype.
+`),
+        catch: (e) => new FsFailure({ op: "write", path, detail: String(e) })
+    });
+};
+const checkpoint = (cwd, stage) => Effect.flatMap(Git, (git) => git.checkpoint(cwd, stage));
+// --- the stages ------------------------------------------------------------
+const scaffold = (ctx, runMeta) => Effect.gen(function* () {
+    const git = yield* Git;
+    const scaffolder = yield* Scaffold;
+    yield* git.init(ctx.cwd);
+    yield* scaffolder.run(ctx.cwd, ctx.harness);
+    yield* git.checkpoint(ctx.cwd, "scaffold", runMeta);
+});
+const template = (ctx) => Effect.gen(function* () {
+    // A skip-template run starts from a bare scaffold; otherwise apply a fitting Market starter.
+    if (!ctx.skipTemplate)
+        yield* turn("template", buildTemplatePrompt(ctx.prompt), ctx);
+    yield* ensureStateReadme(ctx.cwd);
+    yield* checkpoint(ctx.cwd, "template");
+});
+// opencode contends over one per-project session when several instances share a dir, so its surveys
+// run serially; every other harness runs the two concurrently.
+const surveys = (ctx) => Effect.gen(function* () {
+    const both = [
+        turn("surveys", buildSurveyAssetsPrompt(ctx.prompt), ctx),
+        turn("surveys", buildSurveyTechnologyPrompt(ctx.prompt), ctx)
+    ];
+    yield* Effect.all(both, { concurrency: ctx.harness === "opencode" ? 1 : "unbounded" });
+    yield* checkpoint(ctx.cwd, "surveys");
+});
+const goal = (ctx) => Effect.gen(function* () {
+    yield* turn("goal", buildGoalPrompt(ctx.prompt), ctx);
+    yield* assertProduced(ctx, GOAL_FILE, "goal");
+    yield* checkpoint(ctx.cwd, "goal");
+});
+const plan = (ctx) => Effect.gen(function* () {
+    yield* turn("plan", buildPlanPrompt(ctx.prompt), ctx);
+    yield* assertProduced(ctx, PLAN_FILE, "plan");
+    yield* checkpoint(ctx.cwd, "plan");
+});
+// One build turn. The harness re-reads GOAL/PLAN/README and continues the plan; when the plan is
+// genuinely consumed it deletes PLAN.md, which is our "done" signal. The checkpoint is --allow-empty,
+// so a turn that committed real work and a turn that did nothing both leave a marker — and the
+// supervisor tells them apart by the tree hash, not by whether a commit appeared.
+const build = (ctx, turnNumber) => Effect.gen(function* () {
+    yield* turn("build", buildBuildPrompt(ctx.prompt, turnNumber), ctx);
+    const done = !existsSync(join(ctx.cwd, PLAN_FILE));
+    yield* checkpoint(ctx.cwd, done ? "done" : "build");
+});
+// Dispatch a non-build stage. Build is driven directly by the supervisor (it owns the turn number
+// and budget), so it is intentionally excluded from this signature.
+export const runStage = (stage, ctx, runMeta) => {
+    switch (stage) {
+        case "scaffold":
+            return scaffold(ctx, runMeta);
+        case "template":
+            return template(ctx);
+        case "surveys":
+            return surveys(ctx);
+        case "goal":
+            return goal(ctx);
+        case "plan":
+            return plan(ctx);
+    }
+};
+export const buildTurn = (ctx, turnNumber) => build(ctx, turnNumber);