Skip to content

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.

feat(loop-sync): make --auto-fix actually fix things (#523)

JonyT Agenticb5054c886055
diff --git a/tools/loop-sync/README.md b/tools/loop-sync/README.md
index 1794137..d0f924f 100644
--- a/tools/loop-sync/README.md
+++ b/tools/loop-sync/README.md
@@ -31,8 +31,8 @@ loop-sync [target-dir] [options]
| Option | Description |
|--------|-------------|
-| `-a, --auto-fix` | Attempt to auto-fix issues (experimental) |
-| `-d, --dry-run` | Show what would be done without making changes |
+| `-a, --auto-fix` | Scaffold missing STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md with minimal defaults, and add a missing STATE.md reference to LOOP.md. LOOP.md and AGENTS.md are never fabricated — run `loop-init` for those. |
+| `-d, --dry-run` | With `--auto-fix`, report what would be scaffolded/changed without writing anything |
| `-v, --verbose` | Show detailed information |
| `--json` | Output JSON format |
| `-h, --help` | Show help |
@@ -48,6 +48,12 @@ loop-sync ./my-project -v
# JSON output for scripting
loop-sync ./my-project --json
+
+# Preview what --auto-fix would scaffold/change, without writing anything
+loop-sync ./my-project --auto-fix --dry-run
+
+# Scaffold the safely-fixable files and fix the LOOP.md/STATE.md reference
+loop-sync ./my-project --auto-fix
```
## What it checks
diff --git a/tools/loop-sync/dist/cli.js b/tools/loop-sync/dist/cli.js
index 4525d89..315acc5 100644
--- a/tools/loop-sync/dist/cli.js
+++ b/tools/loop-sync/dist/cli.js
@@ -38,8 +38,13 @@ Usage:
loop-sync [target-dir] [options]
Options:
- -a, --auto-fix Attempt to auto-fix issues (experimental)
- -d, --dry-run Show what would be done without making changes
+ -a, --auto-fix Scaffold missing STATE.md, gate.yaml, loop-budget.md, and
+ loop-run-log.md with minimal defaults, and add a missing
+ STATE.md reference to LOOP.md. LOOP.md and AGENTS.md are
+ never fabricated -- their content is pattern-specific,
+ so a missing one still just suggests loop-init.
+ -d, --dry-run With --auto-fix, report what would be scaffolded/changed
+ without writing anything
-v, --verbose Show detailed information
--json Output JSON format
-h, --help Show this help
@@ -48,6 +53,8 @@ Examples:
loop-sync .
loop-sync ./my-project -v
loop-sync ./my-project --json
+ loop-sync ./my-project --auto-fix --dry-run
+ loop-sync ./my-project --auto-fix
The tool checks:
- STATE.md ↔ LOOP.md consistency
diff --git a/tools/loop-sync/dist/sync.js b/tools/loop-sync/dist/sync.js
index 7c99b4c..d9900da 100644
--- a/tools/loop-sync/dist/sync.js
+++ b/tools/loop-sync/dist/sync.js
@@ -7,7 +7,7 @@
* 3. Missing required files
* 4. Configuration drift from starters
*/
-import { readFile, access } from 'node:fs/promises';
+import { readFile, writeFile, access, mkdir } from 'node:fs/promises';
import { readdir, stat } from 'node:fs/promises';
import path from 'node:path';
/**
@@ -110,6 +110,131 @@ function compareMarkdownFiles(file1Content, file2Content, threshold = 0.5) {
const similarity = allHeadings.size === 0 ? 1 : matchingHeadings / allHeadings.size;
return { similarity, differences };
}
+/**
+ * Required files whose content is pattern-agnostic enough to scaffold a
+ * correct, minimal default without knowing which of loop-init's patterns
+ * (daily-triage, pr-babysitter, ci-sweeper, ...) the project actually uses.
+ * STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md all have exactly
+ * this shape upstream (see templates/*.template) -- LOOP.md and AGENTS.md
+ * don't, since their content *is* the pattern-specific goal and workflow, so
+ * auto-fix intentionally leaves those two as report-only rather than
+ * fabricating wrong content.
+ *
+ * These are inlined rather than read from templates/*.template because
+ * loop-sync ships as a standalone npm package (files: ["dist"]) that runs
+ * against arbitrary target directories -- a path relative to this package's
+ * own install location wouldn't resolve once installed outside this
+ * monorepo checkout.
+ */
+const AUTO_FIXABLE_FILES = new Set(['STATE.md', 'gate.yaml', 'loop-budget.md', 'loop-run-log.md']);
+function projectNameFrom(targetDir) {
+ return path.basename(path.resolve(targetDir)) || 'this project';
+}
+function scaffoldContent(file, projectName) {
+ switch (file) {
+ case 'STATE.md':
+ return `# Loop State — ${projectName}
+
+Last run: (set by loop on each run)
+
+## High Priority (loop is acting or waiting on human)
+
+<!-- Format:
+- [ ] ID — one-line description
+ Loop action: what the loop did last
+ Human decision: (if any)
+-->
+
+## Watch List
+
+<!-- Items to monitor but not act on yet -->
+
+## Recent Noise (ignored this run)
+
+<!-- Brief list — helps tune triage skill -->
+
+---
+Run log: (timestamp) | findings | actions | escalations
+`;
+ case 'gate.yaml':
+ return `# Machine-readable twin of your project's safety policy. Adjust denylist
+# and autoMergeAllowlist for your project's own sensitive paths.
+version: 1
+
+denylist:
+ - ".env"
+ - ".env.*"
+ - "**/secrets/**"
+ - "**/credentials/**"
+ - "**/*_key*"
+ - "**/*_secret*"
+ - ".terraform/**"
+ - "k8s/production/**"
+ - "**/migrations/**"
+ - "auth/**"
+ - "payments/**"
+ - "billing/**"
+
+# 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"
+`;
+ case 'loop-budget.md':
+ return `# Loop Budget — ${projectName}
+
+## Daily limits
+
+| Loop | Max runs/day | Max tokens/day | Max sub-agent spawns/run |
+|------|--------------|----------------|--------------------------|
+| Daily Triage | 2 | 100k | 0 (L1) / 2 (L2) |
+| PR Babysitter | 288 | 2M | 3 |
+| CI Sweeper | 96 | 1M | 3 |
+| Dependency Sweeper | 4 | 500k | 3 |
+| Post-Merge Cleanup | 1 | 200k | 2 |
+
+## On budget exceed
+
+1. Pause all schedulers (\`scheduler_delete\` or disable automations)
+2. Append event to \`loop-run-log.md\`
+3. Notify human (Slack / issue / STATE.md High Priority)
+
+## Kill switch
+
+- Command or issue label: \`loop-pause-all\`
+- Resume only after human clears the flag in STATE.md
+`;
+ case 'loop-run-log.md':
+ return `# Loop Run Log — ${projectName}
+
+Append one entry per run. Prune entries older than 30 days.
+
+## Format
+
+\`\`\`json
+{
+ "run_id": "2026-06-09T08:15:00Z",
+ "pattern": "daily-triage",
+ "duration_s": 45,
+ "items_found": 4,
+ "actions_taken": 1,
+ "escalations": 0,
+ "tokens_estimate": 52000,
+ "outcome": "report-only | fix-proposed | escalated | no-op"
+}
+\`\`\`
+
+## Recent Runs
+
+<!-- Loop appends below this line -->
+`;
+ default:
+ throw new Error(`No auto-fix scaffold defined for ${file}.`);
+ }
+}
/**
* Scan skills directory for version information
*/
@@ -165,12 +290,31 @@ export async function runSync(options) {
for (const file of requiredFiles) {
const filePath = path.join(targetDir, file);
if (!await fileExists(filePath)) {
+ const fixable = AUTO_FIXABLE_FILES.has(file);
+ if (autoFix && fixable) {
+ if (!dryRun) {
+ await mkdir(path.dirname(filePath), { recursive: true });
+ await writeFile(filePath, scaffoldContent(file, projectNameFrom(targetDir)));
+ }
+ issues.push({
+ type: 'missing',
+ file,
+ message: dryRun
+ ? `${file} is missing — would scaffold a minimal default (--dry-run, no changes made)`
+ : `${file} was missing — scaffolded a minimal default`,
+ severity: 'info',
+ suggestion: 'Review the generated content and adjust it for your project.',
+ });
+ continue;
+ }
issues.push({
type: 'missing',
file,
message: `${file} is missing`,
severity: 'error',
- suggestion: `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,
+ suggestion: fixable
+ ? `Run with --auto-fix to scaffold a minimal default, or 'npx @cobusgreyling/loop-init . --pattern daily-triage' for pattern-specific content`
+ : `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,
});
}
}
@@ -187,13 +331,30 @@ export async function runSync(options) {
const stateFiles = extractStateFiles(loopContent);
// Check if STATE.md is referenced in LOOP.md
if (!stateFiles.includes('STATE.md')) {
- issues.push({
- type: 'inconsistent',
- file: 'LOOP.md',
- message: 'LOOP.md does not reference STATE.md',
- severity: 'warning',
- suggestion: 'Add STATE.md to the state files list in LOOP.md',
- });
+ if (autoFix) {
+ if (!dryRun) {
+ const separator = /\n\n$/.test(loopContent) ? '' : loopContent.endsWith('\n') ? '\n' : '\n\n';
+ await writeFile(loopPath, `${loopContent}${separator}Update STATE.md after each run.\n`);
+ }
+ issues.push({
+ type: 'inconsistent',
+ file: 'LOOP.md',
+ message: dryRun
+ ? 'LOOP.md does not reference STATE.md — would append a reference (--dry-run, no changes made)'
+ : 'LOOP.md did not reference STATE.md — appended a reference',
+ severity: 'info',
+ suggestion: 'Review the appended line and reword it if you prefer.',
+ });
+ }
+ else {
+ issues.push({
+ type: 'inconsistent',
+ file: 'LOOP.md',
+ message: 'LOOP.md does not reference STATE.md',
+ severity: 'warning',
+ suggestion: 'Add STATE.md to the state files list in LOOP.md, or run with --auto-fix',
+ });
+ }
}
// Compare structural similarity
const { similarity, differences } = compareMarkdownFiles(stateContent, loopContent, 0.5);
diff --git a/tools/loop-sync/src/cli.ts b/tools/loop-sync/src/cli.ts
index da1e490..731a889 100644
--- a/tools/loop-sync/src/cli.ts
+++ b/tools/loop-sync/src/cli.ts
@@ -38,8 +38,13 @@ Usage:
loop-sync [target-dir] [options]
Options:
- -a, --auto-fix Attempt to auto-fix issues (experimental)
- -d, --dry-run Show what would be done without making changes
+ -a, --auto-fix Scaffold missing STATE.md, gate.yaml, loop-budget.md, and
+ loop-run-log.md with minimal defaults, and add a missing
+ STATE.md reference to LOOP.md. LOOP.md and AGENTS.md are
+ never fabricated -- their content is pattern-specific,
+ so a missing one still just suggests loop-init.
+ -d, --dry-run With --auto-fix, report what would be scaffolded/changed
+ without writing anything
-v, --verbose Show detailed information
--json Output JSON format
-h, --help Show this help
@@ -48,6 +53,8 @@ Examples:
loop-sync .
loop-sync ./my-project -v
loop-sync ./my-project --json
+ loop-sync ./my-project --auto-fix --dry-run
+ loop-sync ./my-project --auto-fix
The tool checks:
- STATE.md ↔ LOOP.md consistency
diff --git a/tools/loop-sync/src/sync.ts b/tools/loop-sync/src/sync.ts
index 942f54d..f0567f6 100644
--- a/tools/loop-sync/src/sync.ts
+++ b/tools/loop-sync/src/sync.ts
@@ -156,6 +156,134 @@ function compareMarkdownFiles(
return { similarity, differences };
}
+/**
+ * Required files whose content is pattern-agnostic enough to scaffold a
+ * correct, minimal default without knowing which of loop-init's patterns
+ * (daily-triage, pr-babysitter, ci-sweeper, ...) the project actually uses.
+ * STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md all have exactly
+ * this shape upstream (see templates/*.template) -- LOOP.md and AGENTS.md
+ * don't, since their content *is* the pattern-specific goal and workflow, so
+ * auto-fix intentionally leaves those two as report-only rather than
+ * fabricating wrong content.
+ *
+ * These are inlined rather than read from templates/*.template because
+ * loop-sync ships as a standalone npm package (files: ["dist"]) that runs
+ * against arbitrary target directories -- a path relative to this package's
+ * own install location wouldn't resolve once installed outside this
+ * monorepo checkout.
+ */
+const AUTO_FIXABLE_FILES = new Set(['STATE.md', 'gate.yaml', 'loop-budget.md', 'loop-run-log.md']);
+
+function projectNameFrom(targetDir: string): string {
+ return path.basename(path.resolve(targetDir)) || 'this project';
+}
+
+function scaffoldContent(file: string, projectName: string): string {
+ switch (file) {
+ case 'STATE.md':
+ return `# Loop State — ${projectName}
+
+Last run: (set by loop on each run)
+
+## High Priority (loop is acting or waiting on human)
+
+<!-- Format:
+- [ ] ID — one-line description
+ Loop action: what the loop did last
+ Human decision: (if any)
+-->
+
+## Watch List
+
+<!-- Items to monitor but not act on yet -->
+
+## Recent Noise (ignored this run)
+
+<!-- Brief list — helps tune triage skill -->
+
+---
+Run log: (timestamp) | findings | actions | escalations
+`;
+ case 'gate.yaml':
+ return `# Machine-readable twin of your project's safety policy. Adjust denylist
+# and autoMergeAllowlist for your project's own sensitive paths.
+version: 1
+
+denylist:
+ - ".env"
+ - ".env.*"
+ - "**/secrets/**"
+ - "**/credentials/**"
+ - "**/*_key*"
+ - "**/*_secret*"
+ - ".terraform/**"
+ - "k8s/production/**"
+ - "**/migrations/**"
+ - "auth/**"
+ - "payments/**"
+ - "billing/**"
+
+# 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"
+`;
+ case 'loop-budget.md':
+ return `# Loop Budget — ${projectName}
+
+## Daily limits
+
+| Loop | Max runs/day | Max tokens/day | Max sub-agent spawns/run |
+|------|--------------|----------------|--------------------------|
+| Daily Triage | 2 | 100k | 0 (L1) / 2 (L2) |
+| PR Babysitter | 288 | 2M | 3 |
+| CI Sweeper | 96 | 1M | 3 |
+| Dependency Sweeper | 4 | 500k | 3 |
+| Post-Merge Cleanup | 1 | 200k | 2 |
+
+## On budget exceed
+
+1. Pause all schedulers (\`scheduler_delete\` or disable automations)
+2. Append event to \`loop-run-log.md\`
+3. Notify human (Slack / issue / STATE.md High Priority)
+
+## Kill switch
+
+- Command or issue label: \`loop-pause-all\`
+- Resume only after human clears the flag in STATE.md
+`;
+ case 'loop-run-log.md':
+ return `# Loop Run Log — ${projectName}
+
+Append one entry per run. Prune entries older than 30 days.
+
+## Format
+
+\`\`\`json
+{
+ "run_id": "2026-06-09T08:15:00Z",
+ "pattern": "daily-triage",
+ "duration_s": 45,
+ "items_found": 4,
+ "actions_taken": 1,
+ "escalations": 0,
+ "tokens_estimate": 52000,
+ "outcome": "report-only | fix-proposed | escalated | no-op"
+}
+\`\`\`
+
+## Recent Runs
+
+<!-- Loop appends below this line -->
+`;
+ default:
+ throw new Error(`No auto-fix scaffold defined for ${file}.`);
+ }
+}
+
/**
* Scan skills directory for version information
*/
@@ -202,7 +330,7 @@ export async function runSync(options: SyncOptions): Promise<DriftReport> {
const { targetDir, autoFix, dryRun, verbose } = options;
const issues: DriftIssue[] = [];
const suggestions: string[] = [];
-
+
// Define required files
const requiredFiles = [
'STATE.md',
@@ -212,17 +340,36 @@ export async function runSync(options: SyncOptions): Promise<DriftReport> {
'loop-budget.md',
'loop-run-log.md',
];
-
+
// Check for missing required files
for (const file of requiredFiles) {
const filePath = path.join(targetDir, file);
if (!await fileExists(filePath)) {
+ const fixable = AUTO_FIXABLE_FILES.has(file);
+ if (autoFix && fixable) {
+ if (!dryRun) {
+ await mkdir(path.dirname(filePath), { recursive: true });
+ await writeFile(filePath, scaffoldContent(file, projectNameFrom(targetDir)));
+ }
+ issues.push({
+ type: 'missing',
+ file,
+ message: dryRun
+ ? `${file} is missing — would scaffold a minimal default (--dry-run, no changes made)`
+ : `${file} was missing — scaffolded a minimal default`,
+ severity: 'info',
+ suggestion: 'Review the generated content and adjust it for your project.',
+ });
+ continue;
+ }
issues.push({
type: 'missing',
file,
message: `${file} is missing`,
severity: 'error',
- suggestion: `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,
+ suggestion: fixable
+ ? `Run with --auto-fix to scaffold a minimal default, or 'npx @cobusgreyling/loop-init . --pattern daily-triage' for pattern-specific content`
+ : `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,
});
}
}
@@ -244,13 +391,29 @@ export async function runSync(options: SyncOptions): Promise<DriftReport> {
// Check if STATE.md is referenced in LOOP.md
if (!stateFiles.includes('STATE.md')) {
- issues.push({
- type: 'inconsistent',
- file: 'LOOP.md',
- message: 'LOOP.md does not reference STATE.md',
- severity: 'warning',
- suggestion: 'Add STATE.md to the state files list in LOOP.md',
- });
+ if (autoFix) {
+ if (!dryRun) {
+ const separator = /\n\n$/.test(loopContent) ? '' : loopContent.endsWith('\n') ? '\n' : '\n\n';
+ await writeFile(loopPath, `${loopContent}${separator}Update STATE.md after each run.\n`);
+ }
+ issues.push({
+ type: 'inconsistent',
+ file: 'LOOP.md',
+ message: dryRun
+ ? 'LOOP.md does not reference STATE.md — would append a reference (--dry-run, no changes made)'
+ : 'LOOP.md did not reference STATE.md — appended a reference',
+ severity: 'info',
+ suggestion: 'Review the appended line and reword it if you prefer.',
+ });
+ } else {
+ issues.push({
+ type: 'inconsistent',
+ file: 'LOOP.md',
+ message: 'LOOP.md does not reference STATE.md',
+ severity: 'warning',
+ suggestion: 'Add STATE.md to the state files list in LOOP.md, or run with --auto-fix',
+ });
+ }
}
// Compare structural similarity
diff --git a/tools/loop-sync/test/sync.test.mjs b/tools/loop-sync/test/sync.test.mjs
index 1690da1..b649b5a 100644
--- a/tools/loop-sync/test/sync.test.mjs
+++ b/tools/loop-sync/test/sync.test.mjs
@@ -1,7 +1,7 @@
import { test, describe, beforeEach, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import path from 'node:path';
-import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { mkdir, writeFile, rm, readFile, access } from 'node:fs/promises';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { runSync, formatReport, extractFrontmatter } from '../dist/sync.js';
@@ -83,6 +83,67 @@ describe('runSync', () => {
});
});
+describe('runSync auto-fix', () => {
+ const fixDir = path.join(process.cwd(), '.test-tmp-autofix');
+
+ beforeEach(() => mkdir(fixDir, { recursive: true }));
+ afterEach(() => rm(fixDir, { recursive: true, force: true }));
+
+ test('scaffolds STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md when missing', async () => {
+ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });
+
+ for (const file of ['STATE.md', 'gate.yaml', 'loop-budget.md', 'loop-run-log.md']) {
+ const content = await readFile(path.join(fixDir, file), 'utf8');
+ assert.ok(content.length > 0, `${file} should have been scaffolded with content`);
+ const issue = report.issues.find((i) => i.file === file);
+ assert.equal(issue.severity, 'info');
+ assert.match(issue.message, /scaffolded/i);
+ }
+ // loop-run-log.md must keep the marker append-run-log.mjs depends on.
+ const runLog = await readFile(path.join(fixDir, 'loop-run-log.md'), 'utf8');
+ assert.match(runLog, /<!-- Loop appends below this line -->/);
+ });
+
+ test('does not fabricate LOOP.md or AGENTS.md -- still reported as missing', async () => {
+ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });
+
+ assert.equal(await fileExists(path.join(fixDir, 'LOOP.md')), false);
+ assert.equal(await fileExists(path.join(fixDir, 'AGENTS.md')), false);
+ const loopIssue = report.issues.find((i) => i.file === 'LOOP.md');
+ assert.equal(loopIssue.severity, 'error');
+ assert.match(loopIssue.suggestion, /loop-init/);
+ });
+
+ test('--dry-run with --auto-fix reports without writing anything', async () => {
+ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: true, verbose: false });
+
+ assert.equal(await fileExists(path.join(fixDir, 'STATE.md')), false);
+ const issue = report.issues.find((i) => i.file === 'STATE.md');
+ assert.match(issue.message, /would scaffold/i);
+ assert.match(issue.message, /dry-run/i);
+ });
+
+ test('appends a STATE.md reference to LOOP.md when missing', async () => {
+ await writeFile(path.join(fixDir, 'STATE.md'), '# Loop State\n');
+ await writeFile(
+ path.join(fixDir, 'LOOP.md'),
+ `# Loop Configuration\n\n## Patterns\n- daily-triage\n`,
+ );
+
+ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });
+
+ const loopContent = await readFile(path.join(fixDir, 'LOOP.md'), 'utf8');
+ assert.match(loopContent, /Update STATE\.md after each run\./);
+ const issue = report.issues.find((i) => i.file === 'LOOP.md' && i.type === 'inconsistent');
+ assert.equal(issue.severity, 'info');
+ assert.match(issue.message, /appended a reference/i);
+ });
+});
+
+function fileExists(p) {
+ return access(p).then(() => true, () => false);
+}
+
describe('formatReport', () => {
test('formats healthy report', () => {
const formatted = formatReport({