@delegance/claude-autopilot 7.3.0 → 7.4.0

package/dist/src/cli/help-text.js

@@ -28,7 +28,7 @@ export const HELP_GROUPS = [
         verbs: [
             { verb: 'init', summary: 'Scaffold guardrail.config.yaml + auto-detect migrate stack (writes .autopilot/stack.md)' },
             { verb: 'setup', summary: 'Auto-detect stack, write config, install pre-push hook' },
-            { verb: 'scaffold', summary: 'Scaffold project skeleton from a spec markdown (--from-spec <path>)' },
+            { verb: 'scaffold', summary: 'Scaffold project skeleton from a spec markdown (--from-spec <path> [--stack node|python|fastapi])' },
             { verb: 'autopilot', summary: 'Multi-phase orchestrator — run scan → spec → plan → implement under one runId (v6.2.0)' },
             { verb: 'brainstorm', summary: 'Pipeline entry point (Claude Code skill — see /brainstorm)' },
             { verb: 'spec', summary: 'Spec-writing pointer (Claude Code skill — see /brainstorm)' },

package/dist/src/cli/index.js

@@ -197,7 +197,7 @@ These are aliases for the flat subcommands; they still work without the 'advance
 // `run resume` form is handled BEFORE the default `run` -> review dispatch
 // kicks in (see disambiguation block just below).
 const SUBCOMMANDS = ['init', 'run', 'runs', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'deploy', 'brainstorm', 'spec', 'plan', 'implement', 'review', 'validate', 'autopilot', 'internal', 'help', '--help', '-h'];
-const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path', 'adapter', 'ref', 'sha', 'spec', 'context', 'mode', 'phases', 'budget'];
+const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path', 'adapter', 'ref', 'sha', 'spec', 'context', 'mode', 'phases', 'budget', 'stack'];
 // Bare invocation — no subcommand, no flags → show welcome guide
 if (args.length === 0) {
     const hasKey = !!(process.env.ANTHROPIC_API_KEY || process.env.GEMINI_API_KEY ||
@@ -933,14 +933,31 @@ switch (subcommand) {
     }
     case 'scaffold': {
         // v7.2.0 — `claude-autopilot scaffold --from-spec <path>`
+        // v7.4.0 — `--stack <node|python|fastapi>` + `--list-stacks`.
+        if (boolFlag('list-stacks')) {
+            const { printStackList } = await import("./scaffold.js");
+            printStackList();
+            process.exit(0);
+        }
         const fromSpec = flag('from-spec');
         const dryRun = boolFlag('dry-run');
+        const stackArg = flag('stack');
+        if (stackArg && !['node', 'python', 'fastapi'].includes(stackArg)) {
+            console.error(`\x1b[31m[claude-autopilot] --stack "${stackArg}" not recognized — supported: node, python, fastapi\x1b[0m`);
+            console.error(`  See: claude-autopilot scaffold --list-stacks`);
+            process.exit(3);
+        }
         if (!fromSpec) {
             console.error(`\x1b[31m[claude-autopilot] scaffold requires --from-spec <path>\x1b[0m`);
             console.error(`  Example: claude-autopilot scaffold --from-spec docs/specs/foo.md`);
+            console.error(`  Stacks:  claude-autopilot scaffold --list-stacks`);
             process.exit(1);
         }
-        await runScaffold({ specPath: fromSpec, dryRun });
+        await runScaffold({
+            specPath: fromSpec,
+            dryRun,
+            ...(stackArg ? { stack: stackArg } : {}),
+        });
         process.exit(0);
         break;
     }

package/dist/src/cli/scaffold/node.d.ts

@@ -0,0 +1,20 @@
+import type { ParsedFiles, ScaffoldResult, ScaffoldRunContext } from './types.ts';
+/**
+ * Build a minimal starter package.json. Caller passes in any explicit
+ * hints (parsed from spec); we layer Node 22 ESM defaults on top.
+ *
+ * Note: signature unchanged from v7.2.0 — re-exported through ../scaffold.ts
+ * so consumers that imported from the public scaffold module keep working.
+ */
+export declare function buildStarterPackageJson(projectName: string, hints: ParsedFiles['packageHints']): Record<string, unknown>;
+/**
+ * Node ESM scaffolder. Materializes directories + placeholder files,
+ * writes package.json (when listed in spec) and tsconfig.json (when listed),
+ * choosing JS vs TS tsconfig flavor based on which extension dominates the
+ * other listed paths.
+ *
+ * Behavior is intentionally byte-identical to v7.2.0 — the existing
+ * tests/scaffold.test.ts is the regression bar.
+ */
+export declare function scaffoldNode(ctx: ScaffoldRunContext): Promise<ScaffoldResult>;
+//# sourceMappingURL=node.d.ts.map

package/dist/src/cli/scaffold/node.js

@@ -0,0 +1,162 @@
+// v7.4.0 — Node ESM scaffolder, extracted from src/cli/scaffold.ts (was the
+// monolithic v7.2.0 implementation). Pure module split: the buildStarterPackageJson
+// + scaffoldNode functions here are byte-identical-in-behavior to v7.2.0; the
+// existing 11 scaffold tests are the regression bar.
+//
+// Why split: v7.4.0 adds Python + FastAPI per-stack scaffolders (see ./python.ts).
+// Keeping each stack in its own module makes the v7.5+ plan (Go, Rust, Ruby) a
+// drop-in pattern: add a new file, register it in the dispatcher inside
+// ../scaffold.ts.
+import * as fs from 'node:fs';
+import * as fsAsync from 'node:fs/promises';
+import * as path from 'node:path';
+const PASS = '\x1b[32m✓\x1b[0m';
+const SKIP = '\x1b[2m·\x1b[0m';
+const DIM = (t) => `\x1b[2m${t}\x1b[0m`;
+/**
+ * Build a minimal starter package.json. Caller passes in any explicit
+ * hints (parsed from spec); we layer Node 22 ESM defaults on top.
+ *
+ * Note: signature unchanged from v7.2.0 — re-exported through ../scaffold.ts
+ * so consumers that imported from the public scaffold module keep working.
+ */
+export function buildStarterPackageJson(projectName, hints) {
+    const pkg = {
+        name: projectName,
+        version: '0.1.0',
+        private: true,
+        type: hints.type ?? 'module',
+        engines: { node: '>=22' },
+        scripts: {
+            test: 'node --test tests/*.test.js',
+            ...hints.scripts,
+        },
+    };
+    if (hints.bin)
+        pkg.bin = hints.bin;
+    if (hints.dependencies)
+        pkg.dependencies = hints.dependencies;
+    if (hints.devDependencies)
+        pkg.devDependencies = hints.devDependencies;
+    return pkg;
+}
+const STARTER_TSCONFIG_JS = {
+    compilerOptions: {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        allowJs: true,
+        checkJs: true,
+        noEmit: true,
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        types: ['node'],
+    },
+    include: ['bin/**/*', 'src/**/*', 'tests/**/*'],
+};
+const STARTER_TSCONFIG_TS = {
+    compilerOptions: {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        outDir: 'dist',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        types: ['node'],
+    },
+    include: ['bin/**/*', 'src/**/*', 'tests/**/*'],
+};
+/**
+ * Node ESM scaffolder. Materializes directories + placeholder files,
+ * writes package.json (when listed in spec) and tsconfig.json (when listed),
+ * choosing JS vs TS tsconfig flavor based on which extension dominates the
+ * other listed paths.
+ *
+ * Behavior is intentionally byte-identical to v7.2.0 — the existing
+ * tests/scaffold.test.ts is the regression bar.
+ */
+export async function scaffoldNode(ctx) {
+    const { cwd, parsed, dryRun } = ctx;
+    const projectName = path.basename(cwd);
+    const filesCreated = [];
+    const filesSkippedExisting = [];
+    const dirsCreated = [];
+    let packageJsonAction = 'skipped-exists';
+    let tsconfigAction = 'skipped-no-ts';
+    // 1) Create directories first.
+    const dirs = new Set();
+    for (const p of parsed.paths) {
+        const d = path.dirname(p);
+        if (d && d !== '.')
+            dirs.add(d);
+    }
+    for (const d of dirs) {
+        const abs = path.join(cwd, d);
+        if (fs.existsSync(abs))
+            continue;
+        if (!dryRun)
+            await fsAsync.mkdir(abs, { recursive: true });
+        dirsCreated.push(d);
+        console.log(`  ${PASS}  mkdir   ${DIM(d + '/')}`);
+    }
+    // 2) Create placeholder files (skip ones we'll handle specially).
+    const SPECIAL = new Set(['package.json', 'tsconfig.json']);
+    for (const p of parsed.paths) {
+        if (SPECIAL.has(p))
+            continue;
+        const abs = path.join(cwd, p);
+        if (fs.existsSync(abs)) {
+            filesSkippedExisting.push(p);
+            console.log(`  ${SKIP}  exists  ${DIM(p)}`);
+            continue;
+        }
+        if (!dryRun) {
+            await fsAsync.mkdir(path.dirname(abs), { recursive: true });
+            // Touch — empty file. Real content is the agent's job.
+            await fsAsync.writeFile(abs, '', 'utf8');
+        }
+        filesCreated.push(p);
+        console.log(`  ${PASS}  touch   ${DIM(p)}`);
+    }
+    // 3) package.json — only if the spec lists it.
+    if (parsed.paths.includes('package.json')) {
+        const pkgAbs = path.join(cwd, 'package.json');
+        if (fs.existsSync(pkgAbs)) {
+            packageJsonAction = 'skipped-exists';
+            console.log(`  ${SKIP}  exists  ${DIM('package.json (preserved)')}`);
+        }
+        else {
+            const pkg = buildStarterPackageJson(projectName, parsed.packageHints);
+            if (!dryRun) {
+                await fsAsync.writeFile(pkgAbs, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+            }
+            packageJsonAction = 'created';
+            console.log(`  ${PASS}  write   ${DIM('package.json (Node 22 ESM starter)')}`);
+        }
+    }
+    // 4) tsconfig.json — only if the spec lists it. JS-flavor when the
+    //    other paths are predominantly .js, TS-flavor for .ts.
+    if (parsed.paths.includes('tsconfig.json')) {
+        const tsAbs = path.join(cwd, 'tsconfig.json');
+        if (fs.existsSync(tsAbs)) {
+            tsconfigAction = 'skipped-exists';
+            console.log(`  ${SKIP}  exists  ${DIM('tsconfig.json (preserved)')}`);
+        }
+        else {
+            const otherPaths = parsed.paths.filter((p) => !SPECIAL.has(p));
+            const tsCount = otherPaths.filter((p) => /\.tsx?$/.test(p)).length;
+            const jsCount = otherPaths.filter((p) => /\.jsx?$/.test(p)).length;
+            const config = tsCount > jsCount ? STARTER_TSCONFIG_TS : STARTER_TSCONFIG_JS;
+            tsconfigAction = 'created';
+            if (!dryRun) {
+                await fsAsync.writeFile(tsAbs, JSON.stringify(config, null, 2) + '\n', 'utf8');
+            }
+            const flavor = config === STARTER_TSCONFIG_TS ? 'compiled TS to dist/' : 'JS w/ JSDoc + checkJs';
+            console.log(`  ${PASS}  write   ${DIM(`tsconfig.json (${flavor})`)}`);
+        }
+    }
+    return { filesCreated, dirsCreated, filesSkippedExisting, packageJsonAction, tsconfigAction };
+}
+//# sourceMappingURL=node.js.map

package/dist/src/cli/scaffold/python.d.ts

@@ -0,0 +1,71 @@
+import type { ScaffoldResult, ScaffoldRunContext } from './types.ts';
+/**
+ * PEP 503 distribution-name normalization, restricted to what we need
+ * here. Lowercase, runs of `[._-]+` collapse to a single `-`, leading +
+ * trailing `[._-]` stripped. Empty result falls back to 'app' (so the
+ * worst-case `cwd` of `___` still produces a buildable pyproject).
+ */
+export declare function normalizeDistributionName(raw: string): string;
+/**
+ * Convert a (PEP 503 normalized) distribution name into a valid Python
+ * identifier suitable for a top-level package directory:
+ *   - replace `-` and `.` with `_`
+ *   - prefix `_` if it starts with a digit (so `2cool` -> `_2cool`)
+ *
+ * Tests pin both transformations:
+ *   my-pkg-2 -> my_pkg_2
+ *   2cool    -> _2cool
+ */
+export declare function packageNameFromDistribution(distribution: string): string;
+/**
+ * Parse a dependency string (`fastapi`, `fastapi>=0.110`,
+ * `uvicorn[standard]`, `pyramid==2.0`) into its PEP 503 normalized
+ * "name" portion — used purely as a dedup key. We don't care about the
+ * version specifier when keying; first-occurrence wins (per spec
+ * "Dedupe by PEP 503 normalized name; first occurrence wins").
+ */
+export declare function dependencyNameKey(dep: string): string;
+/**
+ * Build the dependency list for the generated pyproject.toml. Honors
+ * the narrow contract from spec ("Dependency hint extraction (codex
+ * WARNING #6)"): values flow through verbatim, no version inference,
+ * deduped by PEP 503 normalized name. For FastAPI we ALSO seed
+ * `fastapi>=0.110` and `uvicorn[standard]>=0.27` if not already present.
+ */
+export declare function buildPythonDependencies(hintDeps: string[] | undefined, isFastapi: boolean): string[];
+/**
+ * Generate the pyproject.toml body. Caller supplies the resolved
+ * distribution name, package name, dependency list, and FastAPI flag
+ * (only difference: FastAPI adds a `[project.scripts]` block).
+ */
+export declare function buildPyproject(opts: {
+    distributionName: string;
+    packageName: string;
+    dependencies: string[];
+    isFastapi: boolean;
+}): string;
+/** FastAPI entrypoint — codex CRITICAL #2: must be runnable, not a stub. */
+export declare function buildFastapiMain(packageName: string): string;
+/** Smoke test for the FastAPI scaffold — also auto-included so pytest config isn't dead. */
+export declare function buildFastapiTest(packageName: string): string;
+/**
+ * The Python scaffolder. Materializes:
+ *   - src/<package_name>/__init__.py (empty)
+ *   - tests/ directory
+ *   - pyproject.toml (PEP 621 + hatchling)
+ *   - README.md (only if missing)
+ *
+ * For FastAPI specs it also writes:
+ *   - src/<package_name>/main.py (runnable FastAPI app)
+ *   - tests/test_main.py (smoke test)
+ *
+ * Files explicitly listed in the spec's `## Files` get touched as empty
+ * placeholders if they don't already exist (matches the v7.2.0 Node
+ * behavior). The special files above are written with content even when
+ * not listed in `## Files` — without them the generated pyproject.toml
+ * is invalid (missing package dir) or has dead config (no tests).
+ */
+export declare function scaffoldPython(ctx: ScaffoldRunContext, opts: {
+    isFastapi: boolean;
+}): Promise<ScaffoldResult>;
+//# sourceMappingURL=python.d.ts.map

package/dist/src/cli/scaffold/python.js

@@ -0,0 +1,338 @@
+// v7.4.0 — Python + FastAPI scaffolder.
+//
+// Two scaffold flavors share most of this module:
+//   - bare Python (pyproject.toml / requirements.txt detected)
+//   - FastAPI (Python + a main.py + a `fastapi` mention in the spec)
+//
+// FastAPI auto-includes `fastapi>=0.110` and `uvicorn[standard]>=0.27` in
+// dependencies (deduped by PEP 503 normalized name) and emits a runnable
+// `src/<package>/main.py` + `tests/test_main.py` so the generated
+// `[project.scripts]` entrypoint actually resolves on `pip install -e .`
+// — not a dangling stub. This was codex CRITICAL #2 on the v7.4.0 spec.
+//
+// All naming follows the deterministic algorithm described in the spec
+// ("Name normalization (codex WARNING #1)"):
+//   - distribution_name = PEP 503 normalize(basename(cwd))
+//   - package_name = distribution_name with `-`/`.` -> `_`,
+//                    prefix `_` if it would start with a digit.
+import * as fs from 'node:fs';
+import * as fsAsync from 'node:fs/promises';
+import * as path from 'node:path';
+const PASS = '\x1b[32m✓\x1b[0m';
+const SKIP = '\x1b[2m·\x1b[0m';
+const DIM = (t) => `\x1b[2m${t}\x1b[0m`;
+/**
+ * PEP 503 distribution-name normalization, restricted to what we need
+ * here. Lowercase, runs of `[._-]+` collapse to a single `-`, leading +
+ * trailing `[._-]` stripped. Empty result falls back to 'app' (so the
+ * worst-case `cwd` of `___` still produces a buildable pyproject).
+ */
+export function normalizeDistributionName(raw) {
+    const lower = raw.toLowerCase();
+    const collapsed = lower.replace(/[._-]+/g, '-');
+    const stripped = collapsed.replace(/^[-]+/, '').replace(/[-]+$/, '');
+    return stripped.length > 0 ? stripped : 'app';
+}
+/**
+ * Convert a (PEP 503 normalized) distribution name into a valid Python
+ * identifier suitable for a top-level package directory:
+ *   - replace `-` and `.` with `_`
+ *   - prefix `_` if it starts with a digit (so `2cool` -> `_2cool`)
+ *
+ * Tests pin both transformations:
+ *   my-pkg-2 -> my_pkg_2
+ *   2cool    -> _2cool
+ */
+export function packageNameFromDistribution(distribution) {
+    const replaced = distribution.replace(/[-.]/g, '_');
+    return /^[0-9]/.test(replaced) ? `_${replaced}` : replaced;
+}
+/**
+ * Parse a dependency string (`fastapi`, `fastapi>=0.110`,
+ * `uvicorn[standard]`, `pyramid==2.0`) into its PEP 503 normalized
+ * "name" portion — used purely as a dedup key. We don't care about the
+ * version specifier when keying; first-occurrence wins (per spec
+ * "Dedupe by PEP 503 normalized name; first occurrence wins").
+ */
+export function dependencyNameKey(dep) {
+    // Strip extras + version specifier. Match the leading
+    // identifier (PEP 508 names are `[A-Za-z0-9._-]+`).
+    const m = /^[A-Za-z0-9._-]+/.exec(dep.trim());
+    if (!m)
+        return dep.trim().toLowerCase();
+    return normalizeDistributionName(m[0]);
+}
+/**
+ * Build the dependency list for the generated pyproject.toml. Honors
+ * the narrow contract from spec ("Dependency hint extraction (codex
+ * WARNING #6)"): values flow through verbatim, no version inference,
+ * deduped by PEP 503 normalized name. For FastAPI we ALSO seed
+ * `fastapi>=0.110` and `uvicorn[standard]>=0.27` if not already present.
+ */
+export function buildPythonDependencies(hintDeps, isFastapi) {
+    const out = [];
+    const seen = new Set();
+    const push = (raw) => {
+        const key = dependencyNameKey(raw);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(raw);
+    };
+    for (const d of hintDeps ?? [])
+        push(d);
+    if (isFastapi) {
+        // Only auto-add when not already supplied. If the spec listed
+        // `fastapi==0.115`, we keep that pin and don't override it with our
+        // default lower bound.
+        push('fastapi>=0.110');
+        push('uvicorn[standard]>=0.27');
+    }
+    return out;
+}
+/**
+ * Format a TOML string array, one entry per line. Used for the
+ * `dependencies = [...]` block in pyproject.toml. Strings are quoted
+ * with double quotes; we escape backslashes + double quotes.
+ */
+function tomlStringArray(values) {
+    if (values.length === 0)
+        return '[]';
+    const lines = values.map(v => `    "${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+    return `[\n${lines.join(',\n')},\n]`;
+}
+/**
+ * Generate the pyproject.toml body. Caller supplies the resolved
+ * distribution name, package name, dependency list, and FastAPI flag
+ * (only difference: FastAPI adds a `[project.scripts]` block).
+ */
+export function buildPyproject(opts) {
+    const { distributionName, packageName, dependencies, isFastapi } = opts;
+    const lines = [];
+    lines.push('[project]');
+    lines.push(`name = "${distributionName}"`);
+    lines.push('version = "0.1.0"');
+    lines.push('requires-python = ">=3.11"');
+    lines.push(`dependencies = ${tomlStringArray(dependencies)}`);
+    lines.push('');
+    if (isFastapi) {
+        lines.push('[project.scripts]');
+        lines.push(`${distributionName}-server = "${packageName}.main:run"`);
+        lines.push('');
+    }
+    lines.push('[build-system]');
+    lines.push('requires = ["hatchling"]');
+    lines.push('build-backend = "hatchling.build"');
+    lines.push('');
+    // codex W1 — explicit packages list, no auto-discovery.
+    lines.push('[tool.hatch.build.targets.wheel]');
+    lines.push(`packages = ["src/${packageName}"]`);
+    lines.push('');
+    lines.push('[tool.pytest.ini_options]');
+    lines.push('testpaths = ["tests"]');
+    lines.push('');
+    return lines.join('\n');
+}
+/** FastAPI entrypoint — codex CRITICAL #2: must be runnable, not a stub. */
+export function buildFastapiMain(packageName) {
+    return `"""FastAPI entrypoint — auto-scaffolded by claude-autopilot.
+Override the prose docstring + add real routes; keep \`app\` and
+\`run()\` exported so the [project.scripts] entry stays valid.
+"""
+from fastapi import FastAPI
+import uvicorn
+
+app = FastAPI()
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+def run() -> None:
+    uvicorn.run("${packageName}.main:app", host="0.0.0.0", port=8000)
+`;
+}
+/** Smoke test for the FastAPI scaffold — also auto-included so pytest config isn't dead. */
+export function buildFastapiTest(packageName) {
+    return `from fastapi.testclient import TestClient
+from ${packageName}.main import app
+
+client = TestClient(app)
+
+
+def test_health() -> None:
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+`;
+}
+/** Generic Python README placeholder. Never overwrites an existing README. */
+function buildReadme(distributionName, isFastapi) {
+    const stackLabel = isFastapi ? 'FastAPI' : 'Python';
+    return `# ${distributionName}
+
+${stackLabel} project scaffolded by \`claude-autopilot scaffold --from-spec\`.
+
+## Install
+
+\`\`\`bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+\`\`\`
+
+## Test
+
+\`\`\`bash
+pytest
+\`\`\`
+`;
+}
+/**
+ * The Python scaffolder. Materializes:
+ *   - src/<package_name>/__init__.py (empty)
+ *   - tests/ directory
+ *   - pyproject.toml (PEP 621 + hatchling)
+ *   - README.md (only if missing)
+ *
+ * For FastAPI specs it also writes:
+ *   - src/<package_name>/main.py (runnable FastAPI app)
+ *   - tests/test_main.py (smoke test)
+ *
+ * Files explicitly listed in the spec's `## Files` get touched as empty
+ * placeholders if they don't already exist (matches the v7.2.0 Node
+ * behavior). The special files above are written with content even when
+ * not listed in `## Files` — without them the generated pyproject.toml
+ * is invalid (missing package dir) or has dead config (no tests).
+ */
+export async function scaffoldPython(ctx, opts) {
+    const { cwd, parsed, dryRun } = ctx;
+    const { isFastapi } = opts;
+    const distributionName = normalizeDistributionName(path.basename(cwd));
+    const packageName = packageNameFromDistribution(distributionName);
+    const filesCreated = [];
+    const filesSkippedExisting = [];
+    const dirsCreated = [];
+    // We treat these as "managed" — we generate them with content, not
+    // empty placeholders, so the spec's bullet-list entries for them
+    // don't get touched first.
+    const MANAGED_FILES = new Set([
+        'pyproject.toml',
+        'requirements.txt', // we don't generate this, but if listed we leave it
+        `src/${packageName}/__init__.py`,
+        `src/${packageName}/main.py`,
+        'tests/test_main.py',
+        'README.md',
+    ]);
+    // 1) Create directories. Always include the package + tests dirs;
+    //    plus any dirs implied by spec paths.
+    const dirs = new Set([`src/${packageName}`, 'tests']);
+    for (const p of parsed.paths) {
+        const d = path.dirname(p);
+        if (d && d !== '.')
+            dirs.add(d);
+    }
+    for (const d of dirs) {
+        const abs = path.join(cwd, d);
+        if (fs.existsSync(abs))
+            continue;
+        if (!dryRun)
+            await fsAsync.mkdir(abs, { recursive: true });
+        dirsCreated.push(d);
+        console.log(`  ${PASS}  mkdir   ${DIM(d + '/')}`);
+    }
+    // 2) Touch placeholder files for any spec paths we don't manage.
+    for (const p of parsed.paths) {
+        if (MANAGED_FILES.has(p))
+            continue;
+        const abs = path.join(cwd, p);
+        if (fs.existsSync(abs)) {
+            filesSkippedExisting.push(p);
+            console.log(`  ${SKIP}  exists  ${DIM(p)}`);
+            continue;
+        }
+        if (!dryRun) {
+            await fsAsync.mkdir(path.dirname(abs), { recursive: true });
+            await fsAsync.writeFile(abs, '', 'utf8');
+        }
+        filesCreated.push(p);
+        console.log(`  ${PASS}  touch   ${DIM(p)}`);
+    }
+    // 3) src/<package_name>/__init__.py
+    const initRel = `src/${packageName}/__init__.py`;
+    const initAbs = path.join(cwd, initRel);
+    if (fs.existsSync(initAbs)) {
+        filesSkippedExisting.push(initRel);
+        console.log(`  ${SKIP}  exists  ${DIM(initRel)}`);
+    }
+    else {
+        if (!dryRun)
+            await fsAsync.writeFile(initAbs, '', 'utf8');
+        filesCreated.push(initRel);
+        console.log(`  ${PASS}  touch   ${DIM(initRel)}`);
+    }
+    // 4) FastAPI-only: main.py + tests/test_main.py
+    if (isFastapi) {
+        const mainRel = `src/${packageName}/main.py`;
+        const mainAbs = path.join(cwd, mainRel);
+        if (fs.existsSync(mainAbs)) {
+            filesSkippedExisting.push(mainRel);
+            console.log(`  ${SKIP}  exists  ${DIM(mainRel)}`);
+        }
+        else {
+            if (!dryRun)
+                await fsAsync.writeFile(mainAbs, buildFastapiMain(packageName), 'utf8');
+            filesCreated.push(mainRel);
+            console.log(`  ${PASS}  write   ${DIM(`${mainRel} (FastAPI app + /health + run())`)}`);
+        }
+        const testRel = 'tests/test_main.py';
+        const testAbs = path.join(cwd, testRel);
+        if (fs.existsSync(testAbs)) {
+            filesSkippedExisting.push(testRel);
+            console.log(`  ${SKIP}  exists  ${DIM(testRel)}`);
+        }
+        else {
+            if (!dryRun)
+                await fsAsync.writeFile(testAbs, buildFastapiTest(packageName), 'utf8');
+            filesCreated.push(testRel);
+            console.log(`  ${PASS}  write   ${DIM(`${testRel} (smoke test for /health)`)}`);
+        }
+    }
+    // 5) pyproject.toml
+    const pyprojectAbs = path.join(cwd, 'pyproject.toml');
+    if (fs.existsSync(pyprojectAbs)) {
+        filesSkippedExisting.push('pyproject.toml');
+        console.log(`  ${SKIP}  exists  ${DIM('pyproject.toml (preserved)')}`);
+    }
+    else {
+        const dependencies = buildPythonDependencies(parsed.packageHints.pythonDeps, isFastapi);
+        const body = buildPyproject({ distributionName, packageName, dependencies, isFastapi });
+        if (!dryRun)
+            await fsAsync.writeFile(pyprojectAbs, body, 'utf8');
+        filesCreated.push('pyproject.toml');
+        const flavor = isFastapi ? 'PEP 621 + hatchling + FastAPI deps' : 'PEP 621 + hatchling';
+        console.log(`  ${PASS}  write   ${DIM(`pyproject.toml (${flavor})`)}`);
+    }
+    // 6) README.md — codex NOTE #1 (always create, never overwrite).
+    const readmeAbs = path.join(cwd, 'README.md');
+    if (fs.existsSync(readmeAbs)) {
+        filesSkippedExisting.push('README.md');
+        console.log(`  ${SKIP}  exists  ${DIM('README.md (preserved)')}`);
+    }
+    else {
+        if (!dryRun)
+            await fsAsync.writeFile(readmeAbs, buildReadme(distributionName, isFastapi), 'utf8');
+        filesCreated.push('README.md');
+        console.log(`  ${PASS}  write   ${DIM('README.md')}`);
+    }
+    return {
+        filesCreated,
+        dirsCreated,
+        filesSkippedExisting,
+        // Node-shape fields — we never touch package.json / tsconfig in Python.
+        packageJsonAction: 'skipped-exists',
+        tsconfigAction: 'skipped-no-ts',
+    };
+}
+//# sourceMappingURL=python.js.map

package/dist/src/cli/scaffold/types.d.ts

@@ -0,0 +1,68 @@
+/** Supported `--stack` values. v7.5+ will add 'go', 'rust', 'ruby'. */
+export type Stack = 'node' | 'python' | 'fastapi';
+/**
+ * Stacks we can DETECT but cannot scaffold yet. Detection still warns +
+ * exits 3 so the operator gets a clear "v7.5" diagnostic instead of a
+ * silent fallback to Node, which would generate a wrong-language skeleton.
+ */
+export type UnsupportedStack = 'go' | 'rust' | 'ruby';
+export interface ParsedFiles {
+    /** Raw paths extracted from the `## Files` section bullets. */
+    paths: string[];
+    /** Loosely-parsed package.json hints found anywhere in the section. */
+    packageHints: {
+        bin?: Record<string, string>;
+        type?: 'module' | 'commonjs';
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        scripts?: Record<string, string>;
+        /**
+         * Best-effort stack hint from prose ("uses fastapi", "Python 3.12",
+         * "Node 22 ESM"). Used as a tie-breaker when path heuristics are
+         * ambiguous between Python and FastAPI.
+         */
+        stackHint?: 'node' | 'python' | 'fastapi';
+        /**
+         * Extra Python dependency strings extracted via the narrow contract
+         * documented in the spec ("Dependency hint extraction"):
+         *   - explicit `dependencies: [...]` block in spec prose
+         *   - backticked package names with extras (`uvicorn[standard]`)
+         *   - phrase `depends on <name>`
+         *
+         * Stored verbatim — never version-inferred. Deduped by
+         * PEP 503 normalized name in the Python scaffolder.
+         */
+        pythonDeps?: string[];
+    };
+}
+export interface ScaffoldOptions {
+    cwd?: string;
+    specPath: string;
+    /** When true, log what would happen but don't write anything. */
+    dryRun?: boolean;
+    /**
+     * Explicit stack override. When provided, skips path-based detection
+     * (but still validates the value: unknown → exit 3). v7.4.0 ships
+     * 'node' | 'python' | 'fastapi'.
+     */
+    stack?: Stack;
+}
+export interface ScaffoldResult {
+    filesCreated: string[];
+    dirsCreated: string[];
+    filesSkippedExisting: string[];
+    /** Node-only metadata; Python scaffolder leaves these as 'skipped-no-ts' / 'skipped-exists'. */
+    packageJsonAction: 'created' | 'merged' | 'skipped-exists';
+    tsconfigAction: 'created' | 'skipped-exists' | 'skipped-no-ts';
+    /** v7.4.0 — which stack was used. Useful for tests and for the CLI banner. */
+    stack?: Stack;
+    /** Names of files explicitly skipped because of `--stack` filtering (codex W5). */
+    ignoredOtherStackFiles?: string[];
+}
+/** Per-stack scaffolders share this small context. */
+export interface ScaffoldRunContext {
+    cwd: string;
+    parsed: ParsedFiles;
+    dryRun: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/cli/scaffold/types.js

@@ -0,0 +1,6 @@
+// v7.4.0 — shared types for per-stack scaffolders. Lives in its own file
+// (rather than ../scaffold.ts) so that node.ts and python.ts can both import
+// from it without creating a circular dependency back to the public entry
+// module.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/cli/scaffold.d.ts

@@ -1,39 +1,53 @@
-export interface ScaffoldOptions {
-    cwd?: string;
-    specPath: string;
-    /** When true, log what would happen but don't write anything. */
-    dryRun?: boolean;
-}
-export interface ScaffoldResult {
-    filesCreated: string[];
-    dirsCreated: string[];
-    filesSkippedExisting: string[];
-    packageJsonAction: 'created' | 'merged' | 'skipped-exists';
-    tsconfigAction: 'created' | 'skipped-exists' | 'skipped-no-ts';
-}
-interface ParsedFiles {
-    /** Raw paths extracted from the `## Files` section bullets. */
-    paths: string[];
-    /** Loosely-parsed package.json hints found anywhere in the section. */
-    packageHints: {
-        bin?: Record<string, string>;
-        type?: 'module' | 'commonjs';
-        dependencies?: Record<string, string>;
-        devDependencies?: Record<string, string>;
-        scripts?: Record<string, string>;
-    };
-}
+import { buildStarterPackageJson } from './scaffold/node.ts';
+import type { ParsedFiles, ScaffoldOptions, ScaffoldResult, Stack, UnsupportedStack } from './scaffold/types.ts';
+export { buildStarterPackageJson };
+export type { ScaffoldOptions, ScaffoldResult, ParsedFiles, Stack };
+/** Valid `--stack` argument values. v7.5+ adds 'go', 'rust', 'ruby'. */
+export declare const SUPPORTED_STACKS: readonly Stack[];
+/** Stacks we DETECT-but-don't-support yet. Mapped to spec exit-3 messages. */
+export declare const UNSUPPORTED_STACK_FILES: Record<UnsupportedStack, string>;
 /**
  * Parse the `## Files` (or `## files`) section of a spec markdown file.
  * Tolerant: missing section returns `null`; malformed bullets are skipped
  * silently. Returns extracted file paths + best-effort package-hint blob.
+ *
+ * v7.4.0 also extracts:
+ *   - `stackHint` — first prose mention of `fastapi` / `python` / `node`
+ *     (case-insensitive). Used as a tie-breaker when path heuristics are
+ *     ambiguous between Python and FastAPI.
+ *   - `pythonDeps` — narrow extraction per spec ("Dependency hint
+ *     extraction"): explicit `dependencies: [...]` block, backticked
+ *     package names with extras, and the phrase `depends on <name>`.
  */
 export declare function parseSpecFiles(markdown: string): ParsedFiles | null;
 /**
- * Build a minimal starter package.json. Caller passes in any explicit
- * hints (parsed from spec); we layer Node 22 ESM defaults on top.
+ * Result of stack detection. `kind` is one of:
+ *   - 'resolved'    — `stack` is set; proceed.
+ *   - 'unsupported' — detected an unsupported stack file (Go/Rust/Ruby).
+ *                     Caller exits 3 with `message`.
+ *   - 'polyglot'    — both Node + Python markers present without --stack.
+ *                     Caller exits 3 with `message`.
  */
-export declare function buildStarterPackageJson(projectName: string, hints: ParsedFiles['packageHints']): Record<string, unknown>;
+export type StackDetection = {
+    kind: 'resolved';
+    stack: Stack;
+} | {
+    kind: 'unsupported';
+    stack: UnsupportedStack;
+    message: string;
+} | {
+    kind: 'polyglot';
+    message: string;
+};
+/**
+ * Apply the precedence ladder documented at the top of this file. Pure
+ * function — no I/O — so it's directly unit-testable.
+ */
+export declare function detectStack(parsed: ParsedFiles, explicit?: Stack): StackDetection;
+/**
+ * Print the `--list-stacks` output (codex NOTE #2). Three sections:
+ * Supported, Auto-detected, Recognized-but-unsupported.
+ */
+export declare function printStackList(): void;
 export declare function runScaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
-export {};
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/src/cli/scaffold.js

@@ -1,60 +1,64 @@
-// v7.2.0 — `claude-autopilot scaffold --from-spec <path>`
+// v7.4.0 — `claude-autopilot scaffold --from-spec <path>` (per-stack).
 //
-// Closes the biggest remaining day-1 friction the v7.1.6 blank-repo
-// benchmark identified: even with auto-scaffolded CLAUDE.md and .gitignore
-// (v7.1.7), a fresh repo still needs a hand-written package.json, tsconfig,
-// and directory skeleton before any feature work happens. This verb reads
-// a spec markdown file's `## Files` section and creates the listed
-// directories + a starter package.json + tsconfig.json.
+// History:
+//   v7.2.0 — initial verb, Node ESM only.
+//   v7.4.0 — split per-stack scaffolders into ./scaffold/{node,python}.ts.
+//            This file remains the public entry point + stack detector +
+//            dispatcher; src/index.ts continues to re-export `runScaffold`,
+//            `parseSpecFiles`, `buildStarterPackageJson`, plus the
+//            `ScaffoldOptions` / `ScaffoldResult` types from here so library
+//            consumers don't break.
 //
-// Scope intentionally small:
-//   - Node ESM only (one-shot ship; per-stack expansion is v8 work).
-//   - Touches files, never overwrites (operator opted into autopilot, not
-//     into us nuking their package.json).
-//   - Inspects spec for `scripts:` / `dependencies:` / `devDependencies:`
-//     hints in plain prose; uses heuristics rather than a strict schema.
+// Stack detection lives in `detectStack()`. Per the spec ("Stack detection"
+// section), precedence is:
+//   1. explicit --stack flag (validated; unknown -> exit 3)
+//   2. FastAPI (path + 'fastapi' mention) — checked BEFORE generic Python so
+//      a FastAPI spec listing pyproject.toml isn't mis-classified
+//   3. Python (pyproject.toml or requirements.txt)
+//   4. Node (package.json)
+//   5. Detected-but-unsupported (go.mod / Cargo.toml / Gemfile) -> exit 3
+//   6. Fallback: Node ESM (preserves v7.2.0 default for ambiguous specs)
 //
-// Spec format expectations (matches v7.1.6 benchmark spec shape):
-//
-//   ## Files
-//
-//   * `package.json` — `type: module`, `bin: { foo: bin/foo.js }`,
-//     `dependencies: { @anthropic-ai/sdk: ^0.91 }`, ...
-//   * `bin/foo.js` — argv parser + main loop.
-//   * `src/baz.js` — pure function.
-//   * `tests/foo.test.js` — node:test cases.
-//   * `README.md` — usage + install.
-//
-// Heuristics:
-//   - Backtick-quoted paths in `## Files` bullets become directories
-//     (parent of the path) and empty placeholder files (the path itself).
-//   - JSON-ish tokens in the bullet description (`type: module`,
-//     `dependencies: { foo: ^1 }`) get parsed loosely and merged into
-//     a starter package.json.
-//   - tsconfig is a Node 22 ESM default with `allowJs+checkJs+noEmit`
-//     when the spec lists `.js` files (matches v7.1.6 benchmark project),
-//     or compiled NodeNext when it lists `.ts`.
-//
-// What this DELIBERATELY does NOT do:
-//   - Run `npm install`. The user can decide which package manager.
-//   - Pick a test runner if the spec doesn't say. Echoes `npm test`.
-//   - Generate the CLAUDE.md (that's v7.1.7's job).
+// Polyglot guard: package.json AND pyproject.toml together without --stack
+// -> exit 3 with "polyglot spec — pass --stack to disambiguate".
 //
 // Exit codes:
-//   0 — scaffolded (or all targets already existed; idempotent)
-//   1 — spec file missing or not readable
-//   2 — spec missing a `## Files` section
+//   0 — scaffolded
+//   1 — spec file missing
+//   2 — spec missing `## Files` section
+//   3 (NEW v7.4.0) — `--stack` value not recognized, detected-but-unsupported
+//                    stack (Go/Rust/Ruby), or polyglot spec without --stack
 import * as fs from 'node:fs';
 import * as fsAsync from 'node:fs/promises';
 import * as path from 'node:path';
-const PASS = '\x1b[32m✓\x1b[0m';
-const SKIP = '\x1b[2m·\x1b[0m';
+import { scaffoldNode, buildStarterPackageJson } from "./scaffold/node.js";
+import { scaffoldPython } from "./scaffold/python.js";
 const BOLD = (t) => `\x1b[1m${t}\x1b[0m`;
 const DIM = (t) => `\x1b[2m${t}\x1b[0m`;
+// Re-export types + the legacy buildStarterPackageJson so `src/index.ts` and
+// the existing tests/scaffold.test.ts (which imports from this module) keep
+// compiling without changes.
+export { buildStarterPackageJson };
+/** Valid `--stack` argument values. v7.5+ adds 'go', 'rust', 'ruby'. */
+export const SUPPORTED_STACKS = ['node', 'python', 'fastapi'];
+/** Stacks we DETECT-but-don't-support yet. Mapped to spec exit-3 messages. */
+export const UNSUPPORTED_STACK_FILES = {
+    go: 'go.mod',
+    rust: 'Cargo.toml',
+    ruby: 'Gemfile',
+};
 /**
  * Parse the `## Files` (or `## files`) section of a spec markdown file.
  * Tolerant: missing section returns `null`; malformed bullets are skipped
  * silently. Returns extracted file paths + best-effort package-hint blob.
+ *
+ * v7.4.0 also extracts:
+ *   - `stackHint` — first prose mention of `fastapi` / `python` / `node`
+ *     (case-insensitive). Used as a tie-breaker when path heuristics are
+ *     ambiguous between Python and FastAPI.
+ *   - `pythonDeps` — narrow extraction per spec ("Dependency hint
+ *     extraction"): explicit `dependencies: [...]` block, backticked
+ *     package names with extras, and the phrase `depends on <name>`.
  */
 export function parseSpecFiles(markdown) {
     const filesSectionRe = /^##\s+files\s*$/im;
@@ -78,12 +82,20 @@ export function parseSpecFiles(markdown) {
             continue;
         const raw = captured.trim();
         // Skip prose-y entries by requiring path-shape: contains `/` or
-        // ends in known ext, OR is a known root-level file.
-        if (/[/.](?:js|ts|tsx|jsx|md|json|yaml|yml|sh|py|rs|go|rb|sql)$/i.test(raw) ||
+        // ends in known ext, OR is a known root-level file. v7.4.0 adds
+        // `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `Gemfile`,
+        // `go.mod` to the root-file allowlist so the stack detector can see
+        // them.
+        if (/[/.](?:js|ts|tsx|jsx|md|json|yaml|yml|sh|py|rs|go|rb|sql|toml)$/i.test(raw) ||
             raw === 'package.json' ||
             raw === 'tsconfig.json' ||
             raw === 'README.md' ||
-            raw === '.gitignore') {
+            raw === '.gitignore' ||
+            raw === 'pyproject.toml' ||
+            raw === 'requirements.txt' ||
+            raw === 'Cargo.toml' ||
+            raw === 'Gemfile' ||
+            raw === 'go.mod') {
             paths.push(raw);
         }
     }
@@ -104,12 +116,14 @@ export function parseSpecFiles(markdown) {
         if (Object.keys(entries).length > 0)
             packageHints.bin = entries;
     }
-    // dependencies: { foo: ^1 }
-    const depMatch = /dependencies\s*:\s*\{\s*([^}]+)\s*\}/i.exec(sectionBody);
-    const depBody = depMatch?.[1];
-    if (depBody) {
+    // dependencies: { foo: ^1 }   — Node-shape (object form).
+    // Skip if it looks like an array (Python-shape `dependencies: [...]`)
+    // — that's handled below as a Python dep block.
+    const depObjMatch = /dependencies\s*:\s*\{\s*([^}]+)\s*\}/i.exec(sectionBody);
+    const depObjBody = depObjMatch?.[1];
+    if (depObjBody) {
         const entries = {};
-        for (const part of depBody.split(',')) {
+        for (const part of depObjBody.split(',')) {
             const [name, version] = part.split(':').map((s) => s.trim().replace(/['"`]/g, ''));
             if (name && version)
                 entries[name] = version;
@@ -133,60 +147,133 @@ export function parseSpecFiles(markdown) {
         if (Object.keys(entries).length > 0)
             packageHints.scripts = entries;
     }
+    // v7.4.0 — Python dep extraction (narrow contract, codex W6).
+    // Pattern 1: explicit `dependencies: [foo, bar, baz]` array form.
+    // We deliberately accept the Python-style array AFTER the Node-style
+    // object check above so a Node spec with `dependencies: { foo: ^1 }`
+    // still flows into packageHints.dependencies.
+    const pythonDeps = [];
+    const depArrayMatch = /dependencies\s*:\s*\[\s*([^\]]+)\s*\]/i.exec(sectionBody);
+    const depArrayBody = depArrayMatch?.[1];
+    if (depArrayBody) {
+        for (const raw of depArrayBody.split(',')) {
+            const cleaned = raw.trim().replace(/^[`'"]/, '').replace(/[`'"]$/, '');
+            if (cleaned)
+                pythonDeps.push(cleaned);
+        }
+    }
+    // Pattern 2: backticked package names with extras. We look for
+    // backticks containing `name[extra]` (with or without a version
+    // suffix). This is intentionally narrow — `foo` alone in backticks
+    // could be anything (filename, prose), so we require the `[extra]`
+    // shape to fire this pattern.
+    const extrasRe = /`([A-Za-z][A-Za-z0-9._-]*\[[^\]`]+\][^`]*)`/g;
+    let em;
+    while ((em = extrasRe.exec(sectionBody)) !== null) {
+        const value = em[1]?.trim();
+        if (value)
+            pythonDeps.push(value);
+    }
+    // Pattern 3: phrase `depends on <name>`. We capture the next
+    // identifier-shaped token (PEP 508 names: letters / digits / `._-`).
+    const dependsOnRe = /depends\s+on\s+`?([A-Za-z][A-Za-z0-9._-]*(?:\[[^\]]+\])?(?:[<>=!~][^\s`]+)?)`?/gi;
+    let dm;
+    while ((dm = dependsOnRe.exec(sectionBody)) !== null) {
+        const name = dm[1]?.trim();
+        if (name)
+            pythonDeps.push(name);
+    }
+    if (pythonDeps.length > 0)
+        packageHints.pythonDeps = pythonDeps;
+    // v7.4.0 — stack hint extraction. First-match wins, FastAPI checked
+    // before generic Python (codex C1) so prose like "FastAPI app on
+    // Python 3.12" classifies as fastapi, not python.
+    if (/\bfastapi\b/i.test(sectionBody)) {
+        packageHints.stackHint = 'fastapi';
+    }
+    else if (/\bpython\b/i.test(sectionBody)) {
+        packageHints.stackHint = 'python';
+    }
+    else if (/\bnode(?:\.js)?\s+\d+\b/i.test(sectionBody)) {
+        packageHints.stackHint = 'node';
+    }
     return { paths, packageHints };
 }
 /**
- * Build a minimal starter package.json. Caller passes in any explicit
- * hints (parsed from spec); we layer Node 22 ESM defaults on top.
+ * Apply the precedence ladder documented at the top of this file. Pure
+ * function — no I/O — so it's directly unit-testable.
+ */
+export function detectStack(parsed, explicit) {
+    // Step 1: explicit override always wins.
+    if (explicit)
+        return { kind: 'resolved', stack: explicit };
+    const paths = parsed.paths;
+    const has = (name) => paths.includes(name);
+    const hasMainPy = paths.some(p => p === 'main.py' ||
+        p === 'app/main.py' ||
+        /^src\/[^/]+\/main\.py$/.test(p));
+    const hasFastapiMention = parsed.packageHints.stackHint === 'fastapi';
+    const hasPythonMarker = has('pyproject.toml') || has('requirements.txt');
+    const hasNodeMarker = has('package.json');
+    // Polyglot guard (codex W3) — Node + Python without --stack.
+    if (hasNodeMarker && hasPythonMarker) {
+        return {
+            kind: 'polyglot',
+            message: 'polyglot spec — pass --stack to disambiguate',
+        };
+    }
+    // Step 2: FastAPI (BEFORE generic Python — codex C1).
+    if (hasMainPy && hasFastapiMention) {
+        return { kind: 'resolved', stack: 'fastapi' };
+    }
+    // Edge: spec lists pyproject.toml AND mentions FastAPI in prose but
+    // doesn't list main.py — still classify as FastAPI; we generate
+    // main.py ourselves anyway.
+    if (hasPythonMarker && hasFastapiMention) {
+        return { kind: 'resolved', stack: 'fastapi' };
+    }
+    // Step 3: Python.
+    if (hasPythonMarker)
+        return { kind: 'resolved', stack: 'python' };
+    // Step 4: Node.
+    if (hasNodeMarker)
+        return { kind: 'resolved', stack: 'node' };
+    // Step 5: detected-but-unsupported (codex W2).
+    for (const [stack, file] of Object.entries(UNSUPPORTED_STACK_FILES)) {
+        if (has(file)) {
+            return {
+                kind: 'unsupported',
+                stack,
+                message: `${stack} detected but not supported until v7.5`,
+            };
+        }
+    }
+    // Step 6: fallback — Node ESM (preserves v7.2.0 default for ambiguous
+    // specs that listed only paths with no root-marker file).
+    return { kind: 'resolved', stack: 'node' };
+}
+/**
+ * Print the `--list-stacks` output (codex NOTE #2). Three sections:
+ * Supported, Auto-detected, Recognized-but-unsupported.
  */
-export function buildStarterPackageJson(projectName, hints) {
-    const pkg = {
-        name: projectName,
-        version: '0.1.0',
-        private: true,
-        type: hints.type ?? 'module',
-        engines: { node: '>=22' },
-        scripts: {
-            test: 'node --test tests/*.test.js',
-            ...hints.scripts,
-        },
-    };
-    if (hints.bin)
-        pkg.bin = hints.bin;
-    if (hints.dependencies)
-        pkg.dependencies = hints.dependencies;
-    if (hints.devDependencies)
-        pkg.devDependencies = hints.devDependencies;
-    return pkg;
+export function printStackList() {
+    console.log('');
+    console.log(BOLD('Supported (--stack accepts these):'));
+    console.log('  node     Node 22 ESM (package.json + tsconfig.json)');
+    console.log('  python   Python 3.11+ (pyproject.toml + hatchling + pytest)');
+    console.log('  fastapi  Python + FastAPI (auto-includes fastapi + uvicorn[standard])');
+    console.log('');
+    console.log(BOLD('Auto-detected from `## Files`:'));
+    console.log('  node     when `package.json` is listed');
+    console.log('  python   when `pyproject.toml` or `requirements.txt` is listed');
+    console.log('  fastapi  when `main.py` is listed AND a bullet mentions `fastapi`');
+    console.log('');
+    console.log(BOLD('Recognized-but-unsupported (exit 3):'));
+    console.log('  go       v7.5  (would detect via go.mod)');
+    console.log('  rust     v7.5  (would detect via Cargo.toml)');
+    console.log('  ruby     v7.5+ (would detect via Gemfile)');
+    console.log('');
 }
-const STARTER_TSCONFIG_JS = {
-    compilerOptions: {
-        target: 'ES2022',
-        module: 'NodeNext',
-        moduleResolution: 'NodeNext',
-        allowJs: true,
-        checkJs: true,
-        noEmit: true,
-        strict: true,
-        esModuleInterop: true,
-        skipLibCheck: true,
-        types: ['node'],
-    },
-    include: ['bin/**/*', 'src/**/*', 'tests/**/*'],
-};
-const STARTER_TSCONFIG_TS = {
-    compilerOptions: {
-        target: 'ES2022',
-        module: 'NodeNext',
-        moduleResolution: 'NodeNext',
-        outDir: 'dist',
-        strict: true,
-        esModuleInterop: true,
-        skipLibCheck: true,
-        types: ['node'],
-    },
-    include: ['bin/**/*', 'src/**/*', 'tests/**/*'],
-};
 export async function runScaffold(opts) {
     const cwd = opts.cwd ?? process.cwd();
     const specAbs = path.isAbsolute(opts.specPath) ? opts.specPath : path.join(cwd, opts.specPath);
@@ -200,88 +287,72 @@ export async function runScaffold(opts) {
         process.stderr.write(`[scaffold] spec missing a "## Files" section: ${specAbs}\n`);
         process.exit(2);
     }
-    console.log(`\n${BOLD('[scaffold]')} ${DIM(specAbs)}\n`);
-    const projectName = path.basename(cwd);
-    const filesCreated = [];
-    const filesSkippedExisting = [];
-    const dirsCreated = [];
-    let packageJsonAction = 'skipped-exists';
-    let tsconfigAction = 'skipped-no-ts';
-    // 1) Create directories first.
-    const dirs = new Set();
-    for (const p of parsed.paths) {
-        const d = path.dirname(p);
-        if (d && d !== '.')
-            dirs.add(d);
+    // Validate explicit --stack value. The CLI dispatch in src/cli/index.ts
+    // also validates, but doing it here too means library consumers calling
+    // `runScaffold({ stack: 'python' })` get the same guard.
+    if (opts.stack && !SUPPORTED_STACKS.includes(opts.stack)) {
+        process.stderr.write(`[scaffold] --stack "${opts.stack}" not recognized — supported: ${SUPPORTED_STACKS.join(', ')}\n`);
+        process.exit(3);
     }
-    for (const d of dirs) {
-        const abs = path.join(cwd, d);
-        if (fs.existsSync(abs))
-            continue;
-        if (!opts.dryRun)
-            await fsAsync.mkdir(abs, { recursive: true });
-        dirsCreated.push(d);
-        console.log(`  ${PASS}  mkdir   ${DIM(d + '/')}`);
+    const detection = detectStack(parsed, opts.stack);
+    if (detection.kind === 'unsupported') {
+        process.stderr.write(`[scaffold] ${detection.message}\n`);
+        process.exit(3);
     }
-    // 2) Create placeholder files (skip ones we'll handle specially).
-    const SPECIAL = new Set(['package.json', 'tsconfig.json']);
-    for (const p of parsed.paths) {
-        if (SPECIAL.has(p))
-            continue;
-        const abs = path.join(cwd, p);
-        if (fs.existsSync(abs)) {
-            filesSkippedExisting.push(p);
-            console.log(`  ${SKIP}  exists  ${DIM(p)}`);
-            continue;
-        }
-        if (!opts.dryRun) {
-            await fsAsync.mkdir(path.dirname(abs), { recursive: true });
-            // Touch — empty file. Real content is the agent's job.
-            await fsAsync.writeFile(abs, '', 'utf8');
-        }
-        filesCreated.push(p);
-        console.log(`  ${PASS}  touch   ${DIM(p)}`);
+    if (detection.kind === 'polyglot') {
+        process.stderr.write(`[scaffold] ${detection.message}\n`);
+        process.exit(3);
     }
-    // 3) package.json — only if the spec lists it.
-    if (parsed.paths.includes('package.json')) {
-        const pkgAbs = path.join(cwd, 'package.json');
-        if (fs.existsSync(pkgAbs)) {
-            packageJsonAction = 'skipped-exists';
-            console.log(`  ${SKIP}  exists  ${DIM('package.json (preserved)')}`);
-        }
-        else {
-            const pkg = buildStarterPackageJson(projectName, parsed.packageHints);
-            if (!opts.dryRun) {
-                await fsAsync.writeFile(pkgAbs, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
-            }
-            packageJsonAction = 'created';
-            console.log(`  ${PASS}  write   ${DIM('package.json (Node 22 ESM starter)')}`);
+    const stack = detection.stack;
+    console.log(`\n${BOLD('[scaffold]')} ${DIM(specAbs)} ${DIM(`(stack: ${stack})`)}\n`);
+    // codex W5 — when --stack <python|fastapi> is explicit and the spec
+    // ALSO lists Node files, warn + filter them out so the Python
+    // scaffolder doesn't try to touch them.
+    let ignoredOtherStackFiles;
+    let parsedForStack = parsed;
+    if (opts.stack && (stack === 'python' || stack === 'fastapi')) {
+        const NODE_FILES = new Set(['package.json', 'tsconfig.json']);
+        const ignored = parsed.paths.filter(p => NODE_FILES.has(p));
+        if (ignored.length > 0) {
+            ignoredOtherStackFiles = ignored;
+            console.log(`  ${DIM(`! ignoring Node files (--stack ${stack}): ${ignored.join(', ')}`)}`);
+            parsedForStack = {
+                ...parsed,
+                paths: parsed.paths.filter(p => !NODE_FILES.has(p)),
+            };
         }
     }
-    // 4) tsconfig.json — only if the spec lists it. JS-flavor when the
-    //    other paths are predominantly .js, TS-flavor for .ts.
-    if (parsed.paths.includes('tsconfig.json')) {
-        const tsAbs = path.join(cwd, 'tsconfig.json');
-        if (fs.existsSync(tsAbs)) {
-            tsconfigAction = 'skipped-exists';
-            console.log(`  ${SKIP}  exists  ${DIM('tsconfig.json (preserved)')}`);
-        }
-        else {
-            const otherPaths = parsed.paths.filter((p) => !SPECIAL.has(p));
-            const tsCount = otherPaths.filter((p) => /\.tsx?$/.test(p)).length;
-            const jsCount = otherPaths.filter((p) => /\.jsx?$/.test(p)).length;
-            const config = tsCount > jsCount ? STARTER_TSCONFIG_TS : STARTER_TSCONFIG_JS;
-            tsconfigAction = 'created';
-            if (!opts.dryRun) {
-                await fsAsync.writeFile(tsAbs, JSON.stringify(config, null, 2) + '\n', 'utf8');
-            }
-            const flavor = config === STARTER_TSCONFIG_TS ? 'compiled TS to dist/' : 'JS w/ JSDoc + checkJs';
-            console.log(`  ${PASS}  write   ${DIM(`tsconfig.json (${flavor})`)}`);
+    else if (opts.stack === 'node') {
+        // Symmetric: when --stack node is forced and the spec also lists
+        // Python markers, drop them so we don't touch them as placeholders.
+        const PYTHON_FILES = new Set(['pyproject.toml', 'requirements.txt']);
+        const ignored = parsed.paths.filter(p => PYTHON_FILES.has(p));
+        if (ignored.length > 0) {
+            ignoredOtherStackFiles = ignored;
+            console.log(`  ${DIM(`! ignoring Python files (--stack node): ${ignored.join(', ')}`)}`);
+            parsedForStack = {
+                ...parsed,
+                paths: parsed.paths.filter(p => !PYTHON_FILES.has(p)),
+            };
         }
     }
-    console.log(`\n${BOLD('Done.')} ${DIM(`${dirsCreated.length} dirs, ${filesCreated.length} files created, ${filesSkippedExisting.length} skipped.`)}\n`);
+    const ctx = { cwd, parsed: parsedForStack, dryRun: !!opts.dryRun };
+    let result;
+    if (stack === 'python') {
+        result = await scaffoldPython(ctx, { isFastapi: false });
+    }
+    else if (stack === 'fastapi') {
+        result = await scaffoldPython(ctx, { isFastapi: true });
+    }
+    else {
+        result = await scaffoldNode(ctx);
+    }
+    result.stack = stack;
+    if (ignoredOtherStackFiles)
+        result.ignoredOtherStackFiles = ignoredOtherStackFiles;
+    console.log(`\n${BOLD('Done.')} ${DIM(`${result.dirsCreated.length} dirs, ${result.filesCreated.length} files created, ${result.filesSkippedExisting.length} skipped.`)}\n`);
     if (opts.dryRun)
         console.log(DIM(`(--dry-run: no files were written)\n`));
-    return { filesCreated, dirsCreated, filesSkippedExisting, packageJsonAction, tsconfigAction };
+    return result;
 }
 //# sourceMappingURL=scaffold.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "type": "module",
   "publishConfig": {
     "tag": "next"