@delegance/claude-autopilot 7.3.0 → 7.4.2

package/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.4.2 (2026-05-11)
+
+**v7.4.2 — risk-tiered codex pass policy in autopilot skill.**
+Docs-only PR. Codifies finding N2 from the v7.4.1 codex strategic
+review into `skills/autopilot/SKILL.md`.
+
+**New policy table** in the skill:
+
+| Spec risk | # of codex passes |
+|---|---|
+| **Low** (CLI UX, doc-only, scaffolding, CI tweaks) | 1 |
+| **Medium** (new exec modes, auth, billing, data-access, env vars, API contracts) | 2 |
+| **High** (sandboxing, multi-tenancy, auto-merge, repo-mutation, secrets, RPC/SECURITY DEFINER) | 3 + external review |
+
+**Convention:** spec docs declare `risk: low | medium | high` in
+frontmatter. Omitted defaults to **medium** (safer than defaulting
+to low).
+
+**v7.x examples** included in the skill text:
+* v7.1.7 (low) — 1 pass, 0 CRITICALs in practice.
+* v7.4.0 (low) — 1 pass, 2 CRITICALs caught pre-impl.
+* v7.0 Phase 6 (high) — 3 passes, would have shipped credential-
+  exfiltration vector C3 without all three.
+* v8.0 spec (high) — 2 passes done, needs 3rd before v8 alpha.
+
+No code change. Bumping to 7.4.2.
+
+## 7.4.1 (2026-05-11)
+
+**v7.4.1 — strategic pivot doc from codex 5.5 review.** Docs-only
+PR. Records the decision to pause v8 daemon implementation pending
+customer discovery, plus 8 other findings from the codex strategic
+review of full project state on 2026-05-11.
+
+**Key outcome:** "ship v8 daemon" is NOT the next milestone. The CLI
+chat-session loop is the validated asset; v8 is unvalidated. New
+priority order: (1) customer discovery sprint, (2) hosted beta
+readiness slice (operational), (3) org-tier revocation completion,
+(4) risk-tiered codex pass policy in the autopilot skill.
+
+**Process changes adopted:**
+
+* **Risk-tiered codex passes** (1 for low-risk CLI UX, 2 for new
+  exec/auth/billing/data-access modes, 3 for sandboxing /
+  multi-tenancy / repo-mutation).
+* **Strategic codex review every ~10 PRs** (separate from per-spec
+  passes — catches "ship more without validating demand" trap).
+* **Bounded benchmark suite gate** (4 repo shapes only, run
+  pre-release + after major workflow changes — already in v8 spec).
+
+**v8 IF customer discovery validates demand:** local-only alpha
+first (per W5 of codex review). NO hosted workers, NO billing, NO
+auto-merge until alpha demand is proven.
+
+Full doc at `docs/strategy/2026-05-11-codex-pivot.md`.
+
+## 7.4.0 (2026-05-11)
+
+**v7.4.0 — scaffold per-stack support (Python + FastAPI).** Closes
+the v7.1.6/v7.1.8 benchmark caveat ("n=1, Node 22 ESM only —
+Python/Rust/Go remain v8 follow-ups") and gates v8 spec
+stabilization criteria #2 (4-repo benchmark suite).
+
+* **Stack detection precedence** (codex C1): explicit `--stack` >
+  FastAPI > Python > Node > detected-but-unsupported > Node fallback.
+  FastAPI checked BEFORE Python so FastAPI specs that include
+  `pyproject.toml` aren't mis-classified.
+* **FastAPI scaffold completeness** (codex C2): generates a runnable
+  `src/<package>/main.py` with `app = FastAPI()`, `/health` route,
+  `run()` function, plus `tests/test_main.py` (otherwise the
+  `[project.scripts]` entry was dangling).
+* **Name normalization** (codex W1): PEP 503 distribution name +
+  valid Python identifier package name. `my-pkg-2` → distribution
+  `my-pkg-2`, package `my_pkg_2`. Hatchling explicit `packages`
+  config always present.
+* **Detected-but-unsupported** (codex W2): Go/Rust/Ruby specs →
+  exit 3 with diagnostic, NOT silent fallback to Node.
+* **Polyglot guard** (codex W3): specs listing both `package.json`
+  AND `pyproject.toml` without `--stack` → exit 3.
+* **Narrow dep extraction** (codex W6): 3 patterns only, no inferred
+  versions, dedup by PEP 503 normalized name. FastAPI auto-includes
+  `fastapi>=0.110` + `uvicorn[standard]>=0.27`.
+* **Module split**: `scaffold.ts` is now the dispatcher;
+  per-stack scaffolders live under
+  `src/cli/scaffold/{node,python,types}.ts`.
+* **New flags**: `--stack <node|python|fastapi>`, `--list-stacks`.
+* **Integration test** (codex N3): scaffolds FastAPI + creates
+  isolated venv (handles PEP 668) + `pip install -e .` + import-
+  app. Skipped cleanly when `python3` unavailable.
+
+1563 → 1597 CLI tests; tsc clean; build clean. PR #155 spec +
+#156 impl. Version 7.3.0 → 7.4.0.
+
 ## 7.3.0 (2026-05-10)
 
 **v7.3.0 — library export surface for v8 daemon.** Minor bump

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