Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
fix(loop-audit,loop-sandbox): correct gate.yaml auto-fix schema and Windows spawn ENOENT (#382)
JonyT Agentic5bd6c18244a2
diff --git a/tools/loop-audit/dist/autofixer.js b/tools/loop-audit/dist/autofixer.jsindex 24f5efa..6cafa8d 100644--- a/tools/loop-audit/dist/autofixer.js+++ b/tools/loop-audit/dist/autofixer.js@@ -147,13 +147,25 @@ const AGENTS_MD_TEMPLATE = `# AGENTS.md — Project Conventions- Never auto-merge changes.- Ensure all loops isolate their work in worktrees.`;-const GATE_YAML_TEMPLATE = `# gate.yaml - Explicit human approval gates--gates:- - name: "Auto-merge to main"- description: "Never auto-merge changes to the main branch."- required_approvers:- - "human"+const GATE_YAML_TEMPLATE = `# Machine-readable twin of docs/safety.md, enforced by \`loop-gate check\`.+# See templates/gate.yaml.template in loop-engineering for the full reference.+version: 1++denylist:+ - ".env"+ - ".env.*"+ - "**/secrets/**"+ - "**/credentials/**"+ - "**/*_key*"+ - "**/*_secret*"++# Escalate instead of auto-merging when a change touches more than this many files.+maxFiles: 10++# --action auto-merge only proceeds if every changed path matches one of these.+autoMergeAllowlist:+ - "docs/**"+ - "**/*.md"`;export async function autoFixProject(target, result) {const root = path.resolve(target);diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.jsonindex df389a6..b4d6402 100644--- a/tools/loop-audit/package.json+++ b/tools/loop-audit/package.json@@ -12,7 +12,7 @@],"scripts": {"build": "tsc",- "test": "npm run build && node --test test/auditor.test.mjs",+ "test": "npm run build && node --test test/*.test.mjs","prepublishOnly": "npm test","start": "node dist/cli.js","audit": "npm run build && node dist/cli.js",diff --git a/tools/loop-audit/src/autofixer.ts b/tools/loop-audit/src/autofixer.tsindex 9ade06d..48f45e0 100644--- a/tools/loop-audit/src/autofixer.ts+++ b/tools/loop-audit/src/autofixer.ts@@ -156,13 +156,25 @@ const AGENTS_MD_TEMPLATE = `# AGENTS.md — Project Conventions- Ensure all loops isolate their work in worktrees.`;-const GATE_YAML_TEMPLATE = `# gate.yaml - Explicit human approval gates--gates:- - name: "Auto-merge to main"- description: "Never auto-merge changes to the main branch."- required_approvers:- - "human"+const GATE_YAML_TEMPLATE = `# Machine-readable twin of docs/safety.md, enforced by \`loop-gate check\`.+# See templates/gate.yaml.template in loop-engineering for the full reference.+version: 1++denylist:+ - ".env"+ - ".env.*"+ - "**/secrets/**"+ - "**/credentials/**"+ - "**/*_key*"+ - "**/*_secret*"++# Escalate instead of auto-merging when a change touches more than this many files.+maxFiles: 10++# --action auto-merge only proceeds if every changed path matches one of these.+autoMergeAllowlist:+ - "docs/**"+ - "**/*.md"`;export async function autoFixProject(target: string, result: AuditResult): Promise<void> {diff --git a/tools/loop-audit/test/autofixer.test.mjs b/tools/loop-audit/test/autofixer.test.mjsnew file mode 100644index 0000000..862f7b9--- /dev/null+++ b/tools/loop-audit/test/autofixer.test.mjs@@ -0,0 +1,52 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdtemp, readFile, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { autoFixProject } from '../dist/autofixer.js';++/** Signals with every fixable gap closed except gate.yaml, so autoFixProject+ * writes only that file (and never shells out to loop-init). */+function signalsMissingOnlyGateYaml() {+ return {+ stateFile: { present: true, paths: ['STATE.md'] },+ loopConfig: { present: true },+ skills: { count: 0, loopSkills: [] },+ verifier: { present: false },+ triage: { present: false },+ agentsMd: { present: true },+ patterns: { documented: false },+ safety: { loopMdMentionsSafety: false, safetyDocPresent: true },+ starters: { used: false },+ github: { present: false, workflows: false },+ mcp: { present: false },+ worktreeEvidence: { present: false },+ registry: { present: false },+ constraints: { present: true, hasConstraintsSkill: false },+ cost: { budgetDoc: true, runLog: true, loopMdBudget: false, budgetSkill: false },+ governance: { toolScope: false, stallDetection: false, escalation: false, gateYaml: false },+ loopActivity: { present: false, evidence: [] },+ harness: { stack: true, lock: false, sessions: false, emit: false, host: false },+ memory: { tiers: true, budget: false },+ fleet: { registry: false, inbox: false },+ };+}++test('autoFixProject writes a gate.yaml that loop-gate can actually load', async () => {+ const root = await mkdtemp(path.join(tmpdir(), 'loop-audit-autofix-'));+ try {+ await autoFixProject(root, { score: 0, level: 'L0', signals: signalsMissingOnlyGateYaml() });++ const written = await readFile(path.join(root, 'gate.yaml'), 'utf8');++ // This is the schema tools/loop-gate/src/gate.ts's loadGateConfig actually+ // requires -- { version: 1, denylist: string[], ... } -- not the+ // { gates: [...] } shape this template used to emit, which loop-gate+ // rejects outright.+ assert.match(written, /version:\s*1/);+ assert.match(written, /denylist:/);+ assert.doesNotMatch(written, /^gates:/m);+ } finally {+ await rm(root, { recursive: true, force: true }).catch(() => {});+ }+});diff --git a/tools/loop-sandbox/README.md b/tools/loop-sandbox/README.mdindex 104f69f..beab86c 100644--- a/tools/loop-sandbox/README.md+++ b/tools/loop-sandbox/README.md@@ -49,7 +49,7 @@ loop-sandbox <command> [options]| Option | Description ||--------|-------------|-| `--shell` | Spawns the command using `shell: true` (for bash -c, etc.) |+| `--shell` | Forces `shell: true` (for `bash -c`, etc.). On Windows, npm-installed `.cmd` shims (`npx`, `tsc`, ...) that fail with `ENOENT` are automatically retried through a shell, so this is rarely needed there. || `--base <branch>` | The base branch for the worktree (defaults to current HEAD) |### Examplesdiff --git a/tools/loop-sandbox/dist/cli.js b/tools/loop-sandbox/dist/cli.jsindex 5721526..c80c100 100644--- a/tools/loop-sandbox/dist/cli.js+++ b/tools/loop-sandbox/dist/cli.js@@ -95,7 +95,10 @@ Usage:loop-sandbox review List isolated patches ready for human review.Options for 'run':- --shell Run the command inside a shell environment (shell: true)+ --shell Force the command to run inside a shell environment+ (needed for shell built-ins like "bash -c"; on Windows,+ npm-installed .cmd shims like npx/tsc retry through a shell+ automatically on ENOENT, so this is rarely needed there)--base The base branch to branch the worktree from (default: current HEAD)Examples:diff --git a/tools/loop-sandbox/dist/sandbox.js b/tools/loop-sandbox/dist/sandbox.jsindex 73d60a6..e007dbf 100644--- a/tools/loop-sandbox/dist/sandbox.js+++ b/tools/loop-sandbox/dist/sandbox.js@@ -78,14 +78,42 @@ export async function runInSandbox(root, command, args, options = {}) {try {// 3. Execute the user's commandtry {- const child = spawn(command, args, {- cwd: worktreeAbsPath,- stdio: 'inherit',- shell: options.shell ?? false- });exitCode = await new Promise((resolve) => {- child.on('close', (code) => resolve(code));- child.on('error', () => resolve(1));+ // On Windows, a failed spawn (ENOENT) still emits a 'close' event a+ // few ms after 'error' with a synthetic exit code. Once the ENOENT+ // retry below fires, this flag makes the first (non-shell) attempt's+ // now-stale 'close'/'error' events no-ops instead of letting them win+ // the resolve() race against the retry's real, later result.+ let supersededByRetry = false;+ const attempt = (useShell) => {+ const child = spawn(command, args, {+ cwd: worktreeAbsPath,+ stdio: 'inherit',+ shell: useShell+ });+ child.on('close', (code) => {+ if (!useShell && supersededByRetry)+ return;+ resolve(code);+ });+ child.on('error', (err) => {+ if (!useShell && supersededByRetry)+ return;+ // On Windows, npm-installed CLIs (npx, tsc, ...) are .cmd/.bat+ // shims that spawn can't exec directly, and fail with ENOENT --+ // retry once through a shell. Forcing shell: true unconditionally+ // instead would break commands whose args rely on exact argv+ // quoting (e.g. `node -e "..."`), so only fall back on the+ // specific error this class of command actually produces.+ if (!useShell && !options.shell && process.platform === 'win32' && err.code === 'ENOENT') {+ supersededByRetry = true;+ attempt(true);+ return;+ }+ resolve(1);+ });+ };+ attempt(options.shell ?? false);});}catch (err) {diff --git a/tools/loop-sandbox/src/cli.ts b/tools/loop-sandbox/src/cli.tsindex de04871..72f0d9e 100644--- a/tools/loop-sandbox/src/cli.ts+++ b/tools/loop-sandbox/src/cli.ts@@ -106,7 +106,10 @@ Usage:loop-sandbox review List isolated patches ready for human review.Options for 'run':- --shell Run the command inside a shell environment (shell: true)+ --shell Force the command to run inside a shell environment+ (needed for shell built-ins like "bash -c"; on Windows,+ npm-installed .cmd shims like npx/tsc retry through a shell+ automatically on ENOENT, so this is rarely needed there)--base The base branch to branch the worktree from (default: current HEAD)Examples:diff --git a/tools/loop-sandbox/src/sandbox.ts b/tools/loop-sandbox/src/sandbox.tsindex 16e02a9..5c074a4 100644--- a/tools/loop-sandbox/src/sandbox.ts+++ b/tools/loop-sandbox/src/sandbox.ts@@ -104,15 +104,42 @@ export async function runInSandbox(root: string, command: string, args: string[]try {// 3. Execute the user's commandtry {- const child = spawn(command, args, {- cwd: worktreeAbsPath,- stdio: 'inherit',- shell: options.shell ?? false- });-exitCode = await new Promise<number | null>((resolve) => {- child.on('close', (code) => resolve(code));- child.on('error', () => resolve(1));+ // On Windows, a failed spawn (ENOENT) still emits a 'close' event a+ // few ms after 'error' with a synthetic exit code. Once the ENOENT+ // retry below fires, this flag makes the first (non-shell) attempt's+ // now-stale 'close'/'error' events no-ops instead of letting them win+ // the resolve() race against the retry's real, later result.+ let supersededByRetry = false;++ const attempt = (useShell: boolean) => {+ const child = spawn(command, args, {+ cwd: worktreeAbsPath,+ stdio: 'inherit',+ shell: useShell+ });++ child.on('close', (code) => {+ if (!useShell && supersededByRetry) return;+ resolve(code);+ });+ child.on('error', (err: NodeJS.ErrnoException) => {+ if (!useShell && supersededByRetry) return;+ // On Windows, npm-installed CLIs (npx, tsc, ...) are .cmd/.bat+ // shims that spawn can't exec directly, and fail with ENOENT --+ // retry once through a shell. Forcing shell: true unconditionally+ // instead would break commands whose args rely on exact argv+ // quoting (e.g. `node -e "..."`), so only fall back on the+ // specific error this class of command actually produces.+ if (!useShell && !options.shell && process.platform === 'win32' && err.code === 'ENOENT') {+ supersededByRetry = true;+ attempt(true);+ return;+ }+ resolve(1);+ });+ };+ attempt(options.shell ?? false);});} catch (err) {console.error(`❌ Execution failed inside sandbox:`, err);