@delegance/claude-autopilot 7.3.0 → 7.4.2

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.2",
   "type": "module",
   "publishConfig": {
     "tag": "next"

package/skills/autopilot/SKILL.md

@@ -25,6 +25,58 @@ The ONLY time you stop is if a step **fails and cannot be recovered**. Otherwise
 
 Brief status lines like `[autopilot] Step 3: Executing plan...` are fine. Full summaries, questions, or check-ins are not.
 
+## Codex pass policy (risk-tiered)
+
+> Adopted from the v7.4.1 strategic review (see
+> `docs/strategy/2026-05-11-codex-pivot.md`, codex finding N2).
+>
+> The v8 spec pass-2 finding 3 CRITICALs the original spec missed
+> (especially sandbox / credential exfiltration) was concrete evidence
+> that 1 codex pass is insufficient for security-sensitive architecture.
+> But running 3 passes on every CLI polish spec adds latency without
+> proportional value.
+
+**Tier the spec by risk; pass count follows.**
+
+| Spec risk | Triggers | # of codex passes |
+|---|---|---|
+| **Low** | CLI UX changes, doc-only PRs, scaffolding extensions, config polish, CI workflow tweaks | **1 pass** (this skill's existing pattern — codex on the committed spec) |
+| **Medium** | New execution modes, auth changes, billing flows, data-access patterns, new env vars, API contracts | **2 passes** (1 on the draft spec, 1 on the merged spec after edits) |
+| **High** | Sandboxing, multi-tenancy, auto-merge, anything that mutates user repos, new secrets-handling, RPC/SECURITY DEFINER changes | **3 passes** + external review (1 draft, 1 post-edit, 1 on the impl PR diff) |
+
+**How to apply.** Spec docs declare risk in their frontmatter:
+
+```markdown
+---
+title: <topic>
+risk: low | medium | high
+---
+```
+
+If the spec's `risk:` is omitted, default to **medium** (safer than
+defaulting to low; matches the v8 spec pattern where pass-1 was
+clearly insufficient).
+
+The brainstorming skill's per-step codex pass (approach selection,
+architecture, components, error handling, implementation prep) is
+ALWAYS run — it's how we get a draft spec good enough to merge.
+This tier policy applies to the **post-brainstorm** passes and to
+the codex PR review at Step 7 below.
+
+**Examples from v7.x:**
+
+* v7.1.7 (setup polish — CLAUDE.md scaffold + .gitignore + dedup): low.
+  1 pass on the committed spec. Caught zero CRITICALs in practice.
+* v7.4.0 (Python/FastAPI scaffold extension): low. 1 pass. Found
+  2 CRITICALs (FastAPI precedence, dangling entrypoint) — both
+  fixed pre-impl, no PR-pass surprises.
+* v7.0 Phase 6 (engine-off removal + middleware revocation): high.
+  3 passes (spec, post-edit, PR diff). Each pass surfaced new
+  trust-boundary issues; without all three the launch would have
+  shipped with the credential-exfiltration vector C3.
+* v8.0 spec (standalone daemon): high. 2 passes so far + needs a
+  3rd before any v8 alpha implementation.
+
 ## Pipeline
 
 Execute these steps in order. Do NOT pause between steps unless a step fails.