@drawcall/create 0.1.2 → 0.2.0

package/dist/classify.d.ts

@@ -0,0 +1,27 @@
+export type FailureReason = {
+    readonly _tag: "SessionLimit";
+    readonly resetAt?: string;
+} | {
+    readonly _tag: "RateLimited";
+    readonly retryAfter?: string;
+} | {
+    readonly _tag: "Overloaded";
+} | {
+    readonly _tag: "Auth";
+    readonly hint: string;
+} | {
+    readonly _tag: "Network";
+    readonly detail: string;
+} | {
+    readonly _tag: "Timeout";
+    readonly afterMs: number;
+} | {
+    readonly _tag: "Local";
+    readonly op: string;
+    readonly detail: string;
+} | {
+    readonly _tag: "Unknown";
+    readonly exitCode: number;
+};
+export declare function classifyHarnessOutput(output: string, exitCode: number, timedOut?: boolean): FailureReason;
+export declare function humanReason(reason: FailureReason): string;

package/dist/classify.js

@@ -0,0 +1,68 @@
+// Ordered table of known signals. The first pattern that matches the captured output wins, so the
+// most specific causes (a session limit is a *kind* of rate limit) come first. Adding a newly-seen
+// failure message is a one-line addition here — and a fixture in classify.test.ts captured from the
+// real run that surprised us, so the incident becomes the regression test.
+const SIGNALS = [
+    // "You've hit your session limit · resets 2:10pm (America/New_York)" — Claude subscription cap.
+    // The reset clock is the whole point of surfacing this, so capture the rest of the line after
+    // "resets" verbatim (time + timezone) rather than trying to parse it into a Date we'd mis-zone.
+    {
+        test: /session limit\b[^\n]*?\bresets?\b\s+([^\n]+)/i,
+        reason: (m) => ({ _tag: "SessionLimit", resetAt: m[1]?.trim() })
+    },
+    { test: /\bsession limit\b/i, reason: () => ({ _tag: "SessionLimit" }) },
+    {
+        test: /\b(usage limit|rate.?limit(?:ed)?|too many requests|\b429\b|rate_limit_error)\b/i,
+        reason: () => ({ _tag: "RateLimited" })
+    },
+    {
+        test: /\b(overloaded(_error)?|529|service unavailable|503|internal server error|\b500\b|bad gateway|502)\b/i,
+        reason: () => ({ _tag: "Overloaded" })
+    },
+    {
+        // Auth/login problems — including a harness configured for a provider whose key is missing. The
+        // captured hint is the actionable bit (e.g. "run claude login", "unable to authenticate").
+        test: /(please run\s+\/?login|not (?:logged in|authenticated)|unable to authenticate|authentication (?:parameter|failed|required|error)|missing (?:api[ _-]?key|credentials)|invalid x-api-key|oauth token (?:has )?expired|unauthorized|\b401\b)/i,
+        reason: (m) => ({ _tag: "Auth", hint: m[0] })
+    },
+    {
+        test: /\b(econnreset|enotfound|etimedout|eai_again|socket hang up|network (?:error|timeout)|fetch failed|connection (?:refused|reset))\b/i,
+        reason: (m) => ({ _tag: "Network", detail: m[0] })
+    }
+];
+export function classifyHarnessOutput(output, exitCode, timedOut = false) {
+    if (timedOut)
+        return { _tag: "Timeout", afterMs: 0 };
+    for (const signal of SIGNALS) {
+        const match = output.match(signal.test);
+        if (match)
+            return signal.reason(match);
+    }
+    return { _tag: "Unknown", exitCode };
+}
+// A single human-readable sentence for the reason, harness-agnostic (the caller prepends "Claude"/the
+// stage). This is what makes "✕ build 1 failed" become "✕ session limit reached (resets 2:10pm …)".
+export function humanReason(reason) {
+    switch (reason._tag) {
+        case "SessionLimit":
+            return reason.resetAt
+                ? `session limit reached (resets ${reason.resetAt})`
+                : "session limit reached";
+        case "RateLimited":
+            return reason.retryAfter ? `rate limited (retry after ${reason.retryAfter})` : "rate limited";
+        case "Overloaded":
+            return "provider overloaded";
+        case "Auth":
+            return `not authenticated (${reason.hint})`;
+        case "Network":
+            return `network error (${reason.detail})`;
+        case "Timeout":
+            return reason.afterMs > 0
+                ? `timed out after ${Math.round(reason.afterMs / 1000)}s`
+                : "timed out";
+        case "Local":
+            return `${reason.op} failed (${reason.detail})`;
+        case "Unknown":
+            return `failed with exit code ${reason.exitCode}`;
+    }
+}

package/dist/cli.js

@@ -1,18 +1,61 @@
 #!/usr/bin/env node
+import { existsSync, mkdirSync } from "node:fs";
 import { createRequire } from "node:module";
-import { Command } from "commander";
-import { CliError } from "./constants.js";
-import { createCreateCommand } from "./command.js";
+import { join, resolve } from "node:path";
+import { Effect, Layer } from "effect";
+import { formatResult, parseRunOptions } from "./command.js";
+import { CliError, SESSION_LOG_FILE } from "./constants.js";
+import { GitLive } from "./git.js";
+import { HarnessLive } from "./harness.js";
+import { LoggerLive } from "./logger.js";
+import { ScaffoldLive, generateProjectName } from "./scaffold.js";
+import { ShellLive } from "./shell.js";
+import { run } from "./supervisor.js";
 const packageJson = createRequire(import.meta.url)("../package.json");
-const program = createCreateCommand(new Command(), {
-    version: packageJson.version
-});
+// Compute (and, for a new run, create) the project directory up front — synchronously, before the
+// Effect program — because the log layer is built from this path. A new run mints dc-xxxxxx (or
+// --name / --here); a resume points at an existing project.
+function prepareDir(options) {
+    const base = resolve(options.cwd ?? process.cwd());
+    if (options.resume)
+        return base;
+    if (options.here)
+        return base;
+    const dir = join(base, options.projectName ?? generateProjectName());
+    if (existsSync(dir))
+        throw new CliError(`project directory already exists: ${dir}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+// The live wiring: Logger ← (the hidden log file) ← Shell ← {Git, Harness, Scaffold}. The supervisor
+// needs Git/Harness/Scaffold/Logger; Shell is an internal dependency of the domain services.
+function liveLayer(logFile) {
+    const logger = LoggerLive(logFile);
+    const shell = Layer.provide(ShellLive(process.env), logger);
+    const domain = Layer.provide(Layer.mergeAll(GitLive, HarnessLive, ScaffoldLive), shell);
+    return Layer.merge(domain, logger);
+}
+async function main() {
+    const options = parseRunOptions(process.argv.slice(2), packageJson.version);
+    // Validate before creating anything, so a missing prompt never leaves an empty dc-xxxx behind.
+    if (!options.resume && !options.prompt) {
+        throw new CliError('a prompt is required, e.g. drawcall-create "build a rocket league clone"');
+    }
+    const dir = prepareDir(options);
+    console.log(`${options.resume ? "Resuming" : "Creating"} ${dir}`);
+    const formatted = await Effect.runPromise(run({ ...options, cwd: dir }).pipe(Effect.provide(liveLayer(join(dir, SESSION_LOG_FILE))), Effect.map(formatResult), 
+    // A PreflightError can't be resumed or retried past — surface its message and fail.
+    Effect.catchTag("PreflightError", (e) => Effect.succeed({ text: `\n✕ ${e.message}`, exitCode: 1 }))));
+    (formatted.exitCode === 0 ? console.log : console.error)(formatted.text);
+    process.exitCode = formatted.exitCode;
+}
 try {
-    await program.parseAsync(process.argv);
+    await main();
 }
 catch (error) {
-    if (!(error instanceof CliError))
-        throw error;
-    console.error(`error ${error.message}`);
-    process.exit(error.exitCode);
+    if (error instanceof CliError) {
+        console.error(`error ${error.message}`);
+        process.exit(error.exitCode);
+    }
+    throw error;
 }

package/dist/command.d.ts

@@ -1,18 +1,16 @@
-import { Command } from "commander";
-import { type HarnessName, type Stage } from "./constants.js";
-import { createProject } from "./create.js";
-import { superviseBuild } from "./supervisor.js";
-export declare function createCreateCommand(command?: Command, options?: {
-    version?: string;
-    createProject?: typeof createProject;
-    superviseBuild?: typeof superviseBuild;
-}): Command;
+import { type HarnessName } from "./constants.js";
+import type { RunOptions, RunResult } from "./supervisor.js";
 export declare function splitHarnessArgs(args: string[]): {
     promptParts: string[];
     harnessArgs: string[];
 };
-export declare function parsePromptParts(promptParts: string[]): string;
+export declare function parsePromptParts(promptParts: string[]): string | undefined;
 export declare function parseHarnessName(value: string | undefined): HarnessName | undefined;
-export declare function parseStage(value: string | undefined): Stage | undefined;
 export declare function parsePositiveInteger(value: string | undefined, optionName: string): number | undefined;
 export declare function parseHarnessTimeoutMs(value: string | undefined): number | undefined;
+export declare function parseRunOptions(argv: string[], version?: string): RunOptions;
+export interface FormattedResult {
+    readonly text: string;
+    readonly exitCode: number;
+}
+export declare function formatResult(result: RunResult): FormattedResult;

package/dist/command.js

@@ -1,146 +1,139 @@
 import { Command } from "commander";
-import { CliError, DEFAULT_HARNESS_TIMEOUT_MS, HARNESS_NAMES, MAX_BUILD_TURNS, STAGES } from "./constants.js";
-import { createProject } from "./create.js";
-import { superviseBuild } from "./supervisor.js";
-import { formatDuration } from "./progress-log.js";
-const CLI_OPTION_NAMES = [
-    "--stage",
+import { humanReason } from "./classify.js";
+import { CliError, HARNESS_NAMES, MAX_BUILD_TURNS } from "./constants.js";
+const OPTION_NAMES = [
+    "--resume",
     "--harness",
     "--harness-timeout-minutes",
     "--max-turns",
     "--name",
-    "--skip-template",
-    "--supervise"
+    "--here",
+    "--skip-template"
 ];
-export function createCreateCommand(command = new Command(), options = {}) {
-    const create = options.createProject ?? createProject;
-    const supervise = options.superviseBuild ?? superviseBuild;
-    command
-        .name("drawcall-create")
-        .description("Create a project with an installed local harness")
-        .argument("[args...]", "what should be created; use -- to pass following args to the harness (omit with --supervise)")
-        .option("--stage <name>", `which stage to run (${STAGES.join(", ")})`)
-        .option("--harness <name>", `harness to use (${HARNESS_NAMES.join(", ")})`)
-        .option("--harness-timeout-minutes <count>", `timeout for each harness invocation in minutes (default: ${DEFAULT_HARNESS_TIMEOUT_MS / 60_000})`)
-        .option("--max-turns <count>", `maximum build turns (default: ${MAX_BUILD_TURNS})`)
-        .option("--name <name>", "project directory name (default: a generated dc-xxxxxx name)")
-        .option("--skip-template", "during a full run, skip starter template search and build from scratch")
-        .option("--supervise", "run only the build loop, crash-safe: each turn is a separate child process, the tree is reset to the last good commit before every turn, and a killed turn resumes automatically")
-        .passThroughOptions()
-        .version(options.version ?? "0.0.0")
-        .action(async (args = [], commandOptions) => {
-        const { promptParts, harnessArgs } = splitHarnessArgs(args);
-        if (commandOptions.supervise === true) {
-            const result = await supervise({
-                harness: parseHarnessName(commandOptions.harness),
-                harnessArgs,
-                harnessTimeoutMinutes: parsePositiveInteger(commandOptions.harnessTimeoutMinutes, "--harness-timeout-minutes"),
-                maxTurns: parsePositiveInteger(commandOptions.maxTurns, "--max-turns")
-            });
-            console.log(formatSupervised(result));
-            process.exitCode = result.stop === "stuck" ? 1 : 0;
-            return;
-        }
-        const prompt = parsePromptParts(promptParts);
-        const result = await create(prompt, {
-            stage: parseStage(commandOptions.stage),
-            harness: parseHarnessName(commandOptions.harness),
-            harnessTimeoutMs: parseHarnessTimeoutMs(commandOptions.harnessTimeoutMinutes),
-            harnessArgs,
-            maxTurns: parsePositiveInteger(commandOptions.maxTurns, "--max-turns"),
-            projectName: commandOptions.name,
-            skipTemplate: commandOptions.skipTemplate === true
-        });
-        const ok = result.exitCode === 0;
-        const write = ok ? console.log : console.error;
-        write(ok ? formatSuccess(result) : formatFailure(result));
-        process.exitCode = result.exitCode;
-    });
-    return command;
-}
+// Split off harness pass-through args after `--`; the rest is the prompt.
 export function splitHarnessArgs(args) {
-    const separatorIndex = args.indexOf("--");
-    if (separatorIndex === -1)
+    const i = args.indexOf("--");
+    if (i === -1)
         return { promptParts: args, harnessArgs: [] };
-    return {
-        promptParts: args.slice(0, separatorIndex),
-        harnessArgs: args.slice(separatorIndex + 1)
-    };
+    return { promptParts: args.slice(0, i), harnessArgs: args.slice(i + 1) };
 }
 export function parsePromptParts(promptParts) {
-    // passThroughOptions() turns options placed after the prompt into prompt words; reject them
-    // instead of silently sending them to the harness.
-    const misplaced = promptParts.find((part) => CLI_OPTION_NAMES.includes(part));
+    const misplaced = promptParts.find((part) => OPTION_NAMES.includes(part));
     if (misplaced) {
-        const valuePlaceholder = misplaced === "--skip-template" ? "" : " <value>";
-        throw new CliError(`${misplaced} must come before the prompt, e.g. drawcall-create ${misplaced}${valuePlaceholder} "<prompt>"`);
+        const placeholder = misplaced === "--skip-template" || misplaced === "--here" || misplaced === "--resume"
+            ? ""
+            : " <value>";
+        throw new CliError(`${misplaced} must come before the prompt, e.g. drawcall-create ${misplaced}${placeholder} "<prompt>"`);
     }
     const prompt = promptParts.join(" ").trim();
-    if (!prompt)
-        throw new CliError("prompt is required");
-    return prompt;
+    return prompt.length > 0 ? prompt : undefined;
+}
+function isHarnessName(value) {
+    return HARNESS_NAMES.includes(value);
 }
 export function parseHarnessName(value) {
     if (!value)
         return undefined;
-    if (HARNESS_NAMES.includes(value))
+    if (isHarnessName(value))
         return value;
     throw new CliError(`unsupported harness "${value}". Supported: ${HARNESS_NAMES.join(", ")}`);
 }
-export function parseStage(value) {
-    if (!value)
-        return undefined;
-    if (STAGES.includes(value))
-        return value;
-    throw new CliError(`unsupported stage "${value}". Supported: ${STAGES.join(", ")}`);
-}
 export function parsePositiveInteger(value, optionName) {
     if (value === undefined)
         return undefined;
-    if (!/^[1-9]\d*$/.test(value)) {
+    if (!/^[1-9]\d*$/.test(value))
         throw new CliError(`${optionName} must be a positive integer`);
-    }
     return Number(value);
 }
 export function parseHarnessTimeoutMs(value) {
     const minutes = parsePositiveInteger(value, "--harness-timeout-minutes");
     return minutes === undefined ? undefined : minutes * 60_000;
 }
-function formatSupervised(result) {
-    const reason = {
-        "plan-consumed": "Plan consumed — build complete",
-        "budget-exhausted": "Reached the build-turn budget; PLAN.md still records remaining work",
-        stuck: "Stopped: no forward progress across consecutive turns"
-    };
-    return ["", reason[result.stop], `Turns ${result.turns}`, `Path  ${result.projectDir}`].join("\n");
+// Parse argv into RunOptions. Pure (no IO); throws CliError on bad input.
+export function parseRunOptions(argv, version = "0.0.0") {
+    let result;
+    const command = new Command();
+    command
+        .name("drawcall-create")
+        .description("Create a project with an installed local harness — supervised and resumable")
+        .argument("[args...]", "what to create; use -- to pass following args to the harness")
+        .option("--resume", "resume the run in the given (or current) directory")
+        .option("--harness <name>", `harness to use (${HARNESS_NAMES.join(", ")})`)
+        .option("--harness-timeout-minutes <count>", "timeout for each harness turn, in minutes")
+        .option("--max-turns <count>", `maximum build turns (default: ${MAX_BUILD_TURNS})`)
+        .option("--name <name>", "project directory name (default: a generated dc-xxxxxx name)")
+        .option("--here", "scaffold into the current directory instead of a new subfolder")
+        .option("--skip-template", "build from scratch, skipping the starter-template search")
+        .passThroughOptions()
+        .helpOption("-h, --help")
+        .version(version)
+        .action((args = [], opts) => {
+        const { promptParts, harnessArgs } = splitHarnessArgs(args);
+        result = {
+            prompt: parsePromptParts(promptParts),
+            resume: opts.resume === true,
+            // For --resume the path is the project dir; otherwise it is the parent the new dir goes in.
+            cwd: process.cwd(),
+            projectName: opts.name,
+            here: opts.here === true,
+            harness: parseHarnessName(opts.harness),
+            harnessArgs,
+            harnessTimeoutMs: parseHarnessTimeoutMs(opts.harnessTimeoutMinutes),
+            maxTurns: parsePositiveInteger(opts.maxTurns, "--max-turns"),
+            skipTemplate: opts.skipTemplate === true
+        };
+    });
+    command.parse(argv, { from: "user" });
+    if (!result)
+        throw new CliError("nothing to do");
+    return result;
 }
-function formatSuccess(result) {
-    const lines = [
-        "",
-        `Project ready in ${formatDuration(result.durationMs)}`,
-        `Path  ${result.projectDir}`,
-        `Log   drawcall-create.log`
-    ];
-    const turns = formatTurns(result);
-    if (turns)
-        lines.splice(3, 0, `Turns ${turns}`);
-    return lines.join("\n");
+export function formatResult(result) {
+    switch (result.outcome) {
+        case "done":
+            return {
+                exitCode: 0,
+                text: ["", "✓ Project ready", `Path  ${result.projectDir}`].join("\n")
+            };
+        case "budget-exhausted":
+            return {
+                exitCode: 0,
+                text: [
+                    "",
+                    `Reached the ${result.buildTurns}-turn build budget; PLAN.md still records remaining work.`,
+                    `Path    ${result.projectDir}`,
+                    `Resume  npx @drawcall/create --resume ${result.projectDir}`
+                ].join("\n")
+            };
+        case "stuck":
+            return { exitCode: 1, text: formatStuck(result) };
+    }
 }
-function formatFailure(result) {
+// The "why did it stop" report: how many no-progress attempts, the distinct reasons with counts, and
+// the one-command resume. This is what turns a bare "✕ failed" into something a user can act on.
+function formatStuck(result) {
     const lines = [
         "",
-        `Stopped after ${formatDuration(result.durationMs)}`,
-        `Exit code  ${result.exitCode}`,
-        `Path       ${result.projectDir}`,
-        `Log        drawcall-create.log`
+        `✕ Stopped after ${result.staleAttempts} attempt${result.staleAttempts === 1 ? "" : "s"} with no forward progress.`
     ];
-    const turns = formatTurns(result);
-    if (turns)
-        lines.splice(3, 0, `Turns      ${turns}`);
+    if (result.errors.length > 0) {
+        lines.push("  Errors seen:");
+        for (const [reason, count] of tally(result.errors)) {
+            lines.push(`    ${count}× ${reason}`);
+        }
+    }
+    else {
+        lines.push("  The last turns ran without error but produced no changes.");
+    }
+    lines.push(`  Your work is committed in ${result.projectDir}.`);
+    lines.push(`  Resume:  npx @drawcall/create --resume ${result.projectDir}`);
     return lines.join("\n");
 }
-function formatTurns(result) {
-    if (result.maxTurns === 0)
-        return undefined;
-    return `${result.turns}/${result.maxTurns}`;
+function tally(errors) {
+    const counts = new Map();
+    for (const reason of errors) {
+        const text = humanReason(reason);
+        counts.set(text, (counts.get(text) ?? 0) + 1);
+    }
+    return [...counts.entries()];
 }

package/dist/constants.d.ts

@@ -3,7 +3,8 @@ export type HarnessName = (typeof HARNESS_NAMES)[number];
 export declare const STAGES: readonly ["scaffold", "template", "survey-assets", "survey-technology", "goal", "plan", "build", "full"];
 export type Stage = (typeof STAGES)[number];
 export declare const PARALLEL_STAGES: readonly ["survey-assets", "survey-technology"];
-export declare const SKILLS: readonly ["drawcall-ai/vitexec", "drawcall-ai/uikitml", "drawcall-ai/acta", "drawcall-ai/market", "drawcall-ai/speech", "drawcall-ai/flipbook", "drawcall-ai/skills"];
+export declare const PACKAGE_SKILLS: readonly ["@drawcall/acta", "@drawcall/market", "vitexec", "@drawcall/uikitml", "@drawcall/flipbook"];
+export declare const GITHUB_SKILLS: readonly ["drawcall-ai/speech", "drawcall-ai/skills"];
 export declare const PACKAGES: readonly ["vitexec@latest", "@drawcall/uikitml@latest", "@drawcall/acta@latest", "@drawcall/market@latest", "@drawcall/flipbook@latest", "@pmndrs/uikit@latest", "@pmndrs/pointer-events@latest", "@pmndrs/viverse@latest", "navcat@^0.4.1", "three@^0.184.0", "vite@^8.0.16", "typescript@^6.0.3", "elics@^3.4.2", "postprocessing@^6.39.1"];
 export declare const PACKAGE_NAMES: readonly ["vitexec", "@drawcall/uikitml", "@drawcall/acta", "@drawcall/market", "@drawcall/flipbook", "@pmndrs/uikit", "@pmndrs/pointer-events", "@pmndrs/viverse", "navcat", "three", "vite", "typescript", "elics"];
 export declare const MAX_BUILD_TURNS = 10;
@@ -17,8 +18,13 @@ export declare const SURVEY_DIR = "surveys";
 export declare const ASSET_SURVEY_FILE = "surveys/ASSETS.md";
 export declare const TECH_SURVEY_FILE = "surveys/TECHNOLOGY.md";
 export declare const PROOF_DIR = "proof";
-export declare const SESSION_LOG_FILE = "drawcall-create.log";
-export declare const GITIGNORE_ENTRIES: readonly ["node_modules/", "dist/", "build/", "coverage/", ".env", ".env.*", ".DS_Store", "surveys/", "proof/", "drawcall-create.log"];
+export declare const SESSION_LOG_FILE = ".drawcall-create.log";
+export declare const PIPELINE_STAGES: readonly ["scaffold", "template", "surveys", "goal", "plan", "build"];
+export type PipelineStage = (typeof PIPELINE_STAGES)[number];
+export declare const CHECKPOINT_SUBJECT: (stage: string) => string;
+export declare const STAGE_TRAILER = "Create-Stage";
+export declare const RUN_TRAILER = "Create-Run";
+export declare const GITIGNORE_ENTRIES: readonly ["node_modules/", "dist/", "build/", "coverage/", ".env", ".env.*", ".DS_Store", "surveys/", "proof/", ".drawcall-create.log"];
 /** Error whose message is shown to the user and whose code becomes the process exit code. */
 export declare class CliError extends Error {
     readonly exitCode: number;

package/dist/constants.js

@@ -21,15 +21,21 @@ export const STAGES = [
 // applied state (they write disjoint gitignored scratch files and don't depend on each other) and
 // share a barrier before the goal stage.
 export const PARALLEL_STAGES = ["survey-assets", "survey-technology"];
-export const SKILLS = [
-    "drawcall-ai/vitexec",
-    "drawcall-ai/uikitml",
-    "drawcall-ai/acta",
-    "drawcall-ai/market",
-    "drawcall-ai/speech",
-    "drawcall-ai/flipbook",
-    "drawcall-ai/skills"
+// Skills installed from their already-installed npm package directory under node_modules. Each such
+// package ships its SKILL.md inside the published tarball (skills/<name>/SKILL.md), so once
+// dependencies are installed `skills add <node_modules/pkg>` discovers it with no network, no auth,
+// and in lockstep with the installed package version. This is the preferred source: the skill can
+// never drift from the package it documents. Only skills whose package we install belong here.
+export const PACKAGE_SKILLS = [
+    "@drawcall/acta",
+    "@drawcall/market",
+    "vitexec",
+    "@drawcall/uikitml",
+    "@drawcall/flipbook"
 ];
+// Skills with no installable package of their own — cloned from their public GitHub repo. `speech`
+// has no runtime package in PACKAGES; `drawcall-ai/skills` is a multi-skill monorepo, not one package.
+export const GITHUB_SKILLS = ["drawcall-ai/speech", "drawcall-ai/skills"];
 export const PACKAGES = [
     "vitexec@latest",
     "@drawcall/uikitml@latest",
@@ -78,7 +84,30 @@ export const TECH_SURVEY_FILE = `${SURVEY_DIR}/TECHNOLOGY.md`;
 // Build turns drop proof files here; gitignored scratch (the durable record of what was proven
 // lives in README.md), so generated repos don't fill with committed binaries.
 export const PROOF_DIR = "proof";
-export const SESSION_LOG_FILE = "drawcall-create.log";
+// The single on-disk artifact of a run besides the project itself: a hidden, gitignored log. It is
+// also the project's human-readable record; all *machine* state (resume point, run metadata) lives
+// in git history via commit trailers, so the directory gains exactly one hidden file.
+export const SESSION_LOG_FILE = ".drawcall-create.log";
+// The pipeline as an ordered ledger of stages. Each completed stage ends with one create-owned git
+// commit carrying a `Create-Stage: <stage>` trailer; resume reads the newest such trailer to learn
+// where to continue (see resume.ts). "done" is the terminal marker the final build commit carries.
+export const PIPELINE_STAGES = [
+    "scaffold",
+    "template",
+    "surveys",
+    "goal",
+    "plan",
+    "build"
+];
+// The subject and trailer keys on create's own checkpoint commits. The subject names the stage
+// plainly (these are checkpoints, not conventional-commit "chore"s), and the trailers are the
+// machine-readable resume ledger.
+export const CHECKPOINT_SUBJECT = (stage) => `create: ${stage}`;
+export const STAGE_TRAILER = "Create-Stage";
+// Run metadata (prompt + config) rides on the scaffold commit as a one-line JSON trailer, so the
+// whole run — resume point and how to reproduce it — is reconstructable from git history alone and
+// survives a clone. JSON keeps a multi-line prompt on a single trailer line.
+export const RUN_TRAILER = "Create-Run";
 export const GITIGNORE_ENTRIES = [
     "node_modules/",
     "dist/",

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+import { type FailureReason } from "./classify.js";
+import type { PipelineStage } from "./constants.js";
+declare const StageFailure_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "StageFailure";
+} & Readonly<A>;
+export declare class StageFailure extends StageFailure_base<{
+    readonly stage: PipelineStage;
+    readonly reason: FailureReason;
+    readonly detail: string;
+}> {
+    get explain(): string;
+}
+declare const GitFailure_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "GitFailure";
+} & Readonly<A>;
+export declare class GitFailure extends GitFailure_base<{
+    readonly op: string;
+    readonly detail: string;
+}> {
+}
+declare const FsFailure_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FsFailure";
+} & Readonly<A>;
+export declare class FsFailure extends FsFailure_base<{
+    readonly op: string;
+    readonly path: string;
+    readonly detail: string;
+}> {
+}
+declare const PreflightError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PreflightError";
+} & Readonly<A>;
+export declare class PreflightError extends PreflightError_base<{
+    readonly message: string;
+}> {
+}
+export type RunFailure = StageFailure | GitFailure | FsFailure;
+export declare function reasonOf(failure: RunFailure): FailureReason;
+export {};

package/dist/errors.js

@@ -0,0 +1,32 @@
+import { Data } from "effect";
+import { humanReason } from "./classify.js";
+// A stage attempt (a harness turn or a mechanical scaffold step) failed. The `reason` is the
+// classified, explainable cause; `detail` is a short raw tail kept for the log. This is the common
+// case — almost every failure is one of these.
+export class StageFailure extends Data.TaggedError("StageFailure") {
+    get explain() {
+        return `${this.stage}: ${humanReason(this.reason)}`;
+    }
+}
+// A git operation the pipeline depends on failed unexpectedly (commit, reset, read). Kept distinct
+// from StageFailure so the report can say "git commit failed" rather than mislabel it a harness blip.
+export class GitFailure extends Data.TaggedError("GitFailure") {
+}
+// A filesystem operation failed unexpectedly (seed a file, read a record).
+export class FsFailure extends Data.TaggedError("FsFailure") {
+}
+// A condition that cannot be resumed or retried past: bad CLI input, no harness on PATH, git missing,
+// or "this directory is not a resumable run". These fail the whole command immediately, before the
+// supervisor loop — retrying them from disk state would change nothing.
+export class PreflightError extends Data.TaggedError("PreflightError") {
+}
+export function reasonOf(failure) {
+    switch (failure._tag) {
+        case "StageFailure":
+            return failure.reason;
+        case "GitFailure":
+            return { _tag: "Local", op: `git ${failure.op}`, detail: failure.detail };
+        case "FsFailure":
+            return { _tag: "Local", op: `${failure.op} ${failure.path}`, detail: failure.detail };
+    }
+}

package/dist/git.d.ts

@@ -0,0 +1,27 @@
+import { Context, Effect, Layer } from "effect";
+import { type HarnessName, type PipelineStage } from "./constants.js";
+import { GitFailure } from "./errors.js";
+import { Shell } from "./shell.js";
+export interface RunMeta {
+    readonly prompt: string;
+    readonly harness?: HarnessName;
+    readonly harnessArgs?: ReadonlyArray<string>;
+    readonly harnessTimeoutMs?: number;
+    readonly maxTurns?: number;
+    readonly skipTemplate?: boolean;
+}
+export type StageMarker = PipelineStage | "done";
+export interface GitService {
+    readonly init: (cwd: string) => Effect.Effect<void, GitFailure>;
+    readonly resetClean: (cwd: string) => Effect.Effect<void, GitFailure>;
+    readonly treeHash: (cwd: string) => Effect.Effect<string>;
+    readonly checkpoint: (cwd: string, stage: StageMarker, run?: RunMeta) => Effect.Effect<void, GitFailure>;
+    readonly latestStage: (cwd: string) => Effect.Effect<StageMarker | undefined>;
+    readonly countStage: (cwd: string, stage: StageMarker) => Effect.Effect<number>;
+    readonly readRunMeta: (cwd: string) => Effect.Effect<RunMeta | undefined>;
+}
+declare const Git_base: Context.TagClass<Git, "Git", GitService>;
+export declare class Git extends Git_base {
+}
+export declare const GitLive: Layer.Layer<Git, never, Shell>;
+export {};