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.

fix: sync gate.yaml across tools and resolve autofix discrepancy (#367)

THRISHAL DOMAf1eee8b4b6a9
diff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.ts
index 1362635..81972b4 100644
--- a/tools/loop-audit/dist/auditor.d.ts
+++ b/tools/loop-audit/dist/auditor.d.ts
@@ -54,6 +54,7 @@ export interface LoopSignals {
toolScope: boolean;
stallDetection: boolean;
escalation: boolean;
+ gateYaml: boolean;
};
constraints: {
present: boolean;
diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.js
index d5b755a..e3fd9a8 100644
--- a/tools/loop-audit/dist/auditor.js
+++ b/tools/loop-audit/dist/auditor.js
@@ -13,7 +13,7 @@ const STATE_FILES = [
];
/** Score contribution for each readiness signal (see computeScore). */
const SCORE_WEIGHTS = {
- base: 10,
+ base: 7,
stateFile: 18,
triage: 14,
loopConfig: 9,
@@ -35,6 +35,7 @@ const SCORE_WEIGHTS = {
toolScope: 3,
stallDetection: 3,
escalation: 3,
+ gateYaml: 3,
constraintsFile: 4,
constraintsSkill: 2,
loopActivity: 6,
@@ -256,6 +257,8 @@ export function computeScore(signals) {
score += w.stallDetection;
if (signals.governance.escalation)
score += w.escalation;
+ if (signals.governance.gateYaml)
+ score += w.gateYaml;
if (signals.constraints.present)
score += w.constraintsFile;
if (signals.constraints.hasConstraintsSkill)
@@ -452,6 +455,7 @@ export async function auditProject(target) {
ledgerPresent ||
STALL_HINTS.some((re) => re.test(governanceCorpus));
const escalation = ESCALATION_HINTS.some((re) => re.test(governanceCorpus));
+ const gateYaml = await fileExists(path.join(root, 'gate.yaml'));
// Harness Runtime (harness-foundry) — versioned stack, sessions/traces, outerloop emit, host bridge
const foundryStackPath = path.join(root, '.foundry', 'stack.yaml');
const harnessStack = await fileExists(foundryStackPath);
@@ -512,7 +516,7 @@ export async function auditProject(target) {
worktreeEvidence: { present: worktreeEvidence },
registry: { present: registryPresent },
cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },
- governance: { toolScope, stallDetection, escalation },
+ governance: { toolScope, stallDetection, escalation, gateYaml },
loopActivity,
harness,
memory,
@@ -623,6 +627,16 @@ export async function auditProject(target) {
else {
findings.push({ level: 'ok', message: 'Tool/MCP scope constrained (least-privilege signal present).' });
}
+ if (!signals.governance.gateYaml) {
+ findings.push({
+ level: 'warn',
+ message: 'No gate.yaml — explicit human approval gates are not defined for loop-sync.',
+ });
+ recommendations.push('Add gate.yaml to define explicit human approval gates.');
+ }
+ else {
+ findings.push({ level: 'ok', message: 'gate.yaml present (human gates defined).' });
+ }
if (!signals.governance.stallDetection) {
findings.push({ level: 'warn', message: 'No stall / no-progress detection — a stuck loop can repeat the same failing action instead of escalating.' });
recommendations.push('Add loop-context (circuit breaker) or a max-attempts / no-progress rule in LOOP.md that escalates instead of looping');
diff --git a/tools/loop-audit/dist/autofixer.js b/tools/loop-audit/dist/autofixer.js
index 56dc981..24f5efa 100644
--- a/tools/loop-audit/dist/autofixer.js
+++ b/tools/loop-audit/dist/autofixer.js
@@ -1,5 +1,6 @@
import { writeFile, mkdir } from 'node:fs/promises';
import path from 'node:path';
+import { execSync } from 'node:child_process';
import { fileExists } from '@cobusgreyling/readiness-core';
const STATE_MD_TEMPLATE = `# Loop State — YOUR_PROJECT
@@ -146,6 +147,14 @@ 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"
+`;
export async function autoFixProject(target, result) {
const root = path.resolve(target);
let fixesApplied = 0;
@@ -183,6 +192,26 @@ export async function autoFixProject(target, result) {
if (!result.signals.agentsMd.present) {
await safeWriteFile('AGENTS.md', AGENTS_MD_TEMPLATE, 'Project conventions');
}
+ if (!result.signals.governance.gateYaml) {
+ await safeWriteFile('gate.yaml', GATE_YAML_TEMPLATE, 'Explicit human approval gates');
+ }
+ const shellFix = (cmd, label) => {
+ console.log(`\n⚙️ Applying ${label}...`);
+ try {
+ execSync(cmd, { stdio: 'inherit', cwd: root });
+ console.log(`✅ Applied ${label}`);
+ fixesApplied++;
+ }
+ catch (err) {
+ console.error(`❌ Failed to apply ${label}:`, err instanceof Error ? err.message : String(err));
+ }
+ };
+ if (!result.signals.memory.tiers) {
+ shellFix('npx @cobusgreyling/loop-init . --with-memory', 'Memory engineering');
+ }
+ if (!result.signals.harness.stack) {
+ shellFix('npx @cobusgreyling/loop-init . --with-foundry', 'Harness foundry');
+ }
if (fixesApplied > 0) {
console.log(`\n✨ Applied ${fixesApplied} automatic fixes. Run loop-audit again to see your new score!`);
}
diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.js
index d7f8d12..a0735c8 100644
--- a/tools/loop-audit/dist/cli.js
+++ b/tools/loop-audit/dist/cli.js
@@ -2,11 +2,13 @@
import { auditProject } from './auditor.js';
import { printContributorCta } from './contributor-cta.js';
import { formatBadge, formatHuman, formatJson, formatMarkdown } from './reporter.js';
+import { autoFixProject } from './autofixer.js';
const args = process.argv.slice(2);
const target = args.find((a) => !a.startsWith('-')) || '.';
const json = args.includes('--json');
const md = args.includes('--md');
const suggest = args.includes('--suggest') || args.includes('--fix');
+const autoFix = args.includes('--auto-fix');
const badge = args.includes('--badge');
const help = args.includes('--help') || args.includes('-h');
if (help) {
@@ -19,6 +21,7 @@ Options:
--json JSON output (for CI / scripting)
--md Markdown report
--suggest Show copy-from-template commands for missing pieces (recommended on first runs)
+ --auto-fix Auto-heal missing repository structure (STATE, LOOP, budgets, etc.)
--badge Markdown README badge (Loop Ready level + score)
--help, -h This help
@@ -58,7 +61,10 @@ try {
console.log(formatMarkdown(result));
else
console.log(formatHuman(result));
- if (suggest) {
+ if (autoFix) {
+ await autoFixProject(target, result);
+ }
+ else if (suggest) {
console.log('\n=== Suggested actions (copy & customize) ===');
console.log('From the root of this repo (or after cloning the reference):');
console.log('');
diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.ts
index fccee5c..4cdb256 100644
--- a/tools/loop-audit/src/auditor.ts
+++ b/tools/loop-audit/src/auditor.ts
@@ -27,6 +27,7 @@ export interface LoopSignals {
toolScope: boolean;
stallDetection: boolean;
escalation: boolean;
+ gateYaml: boolean;
};
constraints: { present: boolean; hasConstraintsSkill: boolean };
loopActivity: { present: boolean; evidence: string[] };
@@ -61,7 +62,7 @@ const STATE_FILES = [
/** Score contribution for each readiness signal (see computeScore). */
const SCORE_WEIGHTS = {
- base: 10,
+ base: 7,
stateFile: 18,
triage: 14,
loopConfig: 9,
@@ -83,6 +84,7 @@ const SCORE_WEIGHTS = {
toolScope: 3,
stallDetection: 3,
escalation: 3,
+ gateYaml: 3,
constraintsFile: 4,
constraintsSkill: 2,
loopActivity: 6,
@@ -290,6 +292,7 @@ export function computeScore(signals: LoopSignals): { score: number; level: 'L0'
if (signals.governance.toolScope) score += w.toolScope;
if (signals.governance.stallDetection) score += w.stallDetection;
if (signals.governance.escalation) score += w.escalation;
+ if (signals.governance.gateYaml) score += w.gateYaml;
if (signals.constraints.present) score += w.constraintsFile;
if (signals.constraints.hasConstraintsSkill) score += w.constraintsSkill;
if (signals.loopActivity.present) score += w.loopActivity;
@@ -485,6 +488,7 @@ export async function auditProject(target: string): Promise<AuditResult> {
STALL_HINTS.some((re) => re.test(governanceCorpus));
const escalation = ESCALATION_HINTS.some((re) => re.test(governanceCorpus));
+ const gateYaml = await fileExists(path.join(root, 'gate.yaml'));
// Harness Runtime (harness-foundry) — versioned stack, sessions/traces, outerloop emit, host bridge
const foundryStackPath = path.join(root, '.foundry', 'stack.yaml');
@@ -553,7 +557,7 @@ export async function auditProject(target: string): Promise<AuditResult> {
worktreeEvidence: { present: worktreeEvidence },
registry: { present: registryPresent },
cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },
- governance: { toolScope, stallDetection, escalation },
+ governance: { toolScope, stallDetection, escalation, gateYaml },
loopActivity,
harness,
memory,
@@ -672,6 +676,16 @@ export async function auditProject(target: string): Promise<AuditResult> {
findings.push({ level: 'ok', message: 'Tool/MCP scope constrained (least-privilege signal present).' });
}
+ if (!signals.governance.gateYaml) {
+ findings.push({
+ level: 'warn',
+ message: 'No gate.yaml — explicit human approval gates are not defined for loop-sync.',
+ });
+ recommendations.push('Add gate.yaml to define explicit human approval gates.');
+ } else {
+ findings.push({ level: 'ok', message: 'gate.yaml present (human gates defined).' });
+ }
+
if (!signals.governance.stallDetection) {
findings.push({ level: 'warn', message: 'No stall / no-progress detection — a stuck loop can repeat the same failing action instead of escalating.' });
recommendations.push('Add loop-context (circuit breaker) or a max-attempts / no-progress rule in LOOP.md that escalates instead of looping');
diff --git a/tools/loop-audit/src/autofixer.ts b/tools/loop-audit/src/autofixer.ts
index 5a1b8ad..9ade06d 100644
--- a/tools/loop-audit/src/autofixer.ts
+++ b/tools/loop-audit/src/autofixer.ts
@@ -1,5 +1,6 @@
import { writeFile, mkdir } from 'node:fs/promises';
import path from 'node:path';
+import { execSync } from 'node:child_process';
import { fileExists } from '@cobusgreyling/readiness-core';
import { AuditResult } from './auditor.js';
@@ -155,6 +156,15 @@ 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"
+`;
+
export async function autoFixProject(target: string, result: AuditResult): Promise<void> {
const root = path.resolve(target);
let fixesApplied = 0;
@@ -201,6 +211,29 @@ export async function autoFixProject(target: string, result: AuditResult): Promi
await safeWriteFile('AGENTS.md', AGENTS_MD_TEMPLATE, 'Project conventions');
}
+ if (!result.signals.governance.gateYaml) {
+ await safeWriteFile('gate.yaml', GATE_YAML_TEMPLATE, 'Explicit human approval gates');
+ }
+
+ const shellFix = (cmd: string, label: string) => {
+ console.log(`\n⚙️ Applying ${label}...`);
+ try {
+ execSync(cmd, { stdio: 'inherit', cwd: root });
+ console.log(`✅ Applied ${label}`);
+ fixesApplied++;
+ } catch (err) {
+ console.error(`❌ Failed to apply ${label}:`, err instanceof Error ? err.message : String(err));
+ }
+ };
+
+ if (!result.signals.memory.tiers) {
+ shellFix('npx @cobusgreyling/loop-init . --with-memory', 'Memory engineering');
+ }
+
+ if (!result.signals.harness.stack) {
+ shellFix('npx @cobusgreyling/loop-init . --with-foundry', 'Harness foundry');
+ }
+
if (fixesApplied > 0) {
console.log(`\n✨ Applied ${fixesApplied} automatic fixes. Run loop-audit again to see your new score!`);
} else {
diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjs
index 972178d..1f5920f 100644
--- a/tools/loop-audit/test/auditor.test.mjs
+++ b/tools/loop-audit/test/auditor.test.mjs
@@ -24,7 +24,7 @@ function emptySignals() {
registry: { present: false },
constraints: { present: false, hasConstraintsSkill: false },
cost: { budgetDoc: false, runLog: false, loopMdBudget: false, budgetSkill: false },
- governance: { toolScope: false, stallDetection: false, escalation: false },
+ governance: { toolScope: false, stallDetection: false, escalation: false, gateYaml: false },
loopActivity: { present: false, evidence: [] },
harness: { stack: false, lock: false, sessions: false, emit: false, host: false },
memory: { tiers: false, budget: false },
@@ -198,6 +198,15 @@ test('formatBadge: includes level and score', () => {
assert.match(badge, /loop-engineering/);
});
+test('computeScore: gateYaml adds points', () => {
+ const base = emptySignals();
+ const { score: without } = computeScore(base);
+ const withGate = emptySignals();
+ withGate.governance.gateYaml = true;
+ const { score: withScore } = computeScore(withGate);
+ assert.equal(withScore - without, 3);
+});
+
test('computeScore: harness signals add points', () => {
const base = emptySignals();
const { score: without } = computeScore(base);
diff --git a/tools/loop-sync/dist/sync.js b/tools/loop-sync/dist/sync.js
index 74bfa31..3389ab7 100644
--- a/tools/loop-sync/dist/sync.js
+++ b/tools/loop-sync/dist/sync.js
@@ -156,6 +156,9 @@ export async function runSync(options) {
'STATE.md',
'LOOP.md',
'AGENTS.md',
+ 'gate.yaml',
+ 'loop-budget.md',
+ 'loop-run-log.md',
];
// Check for missing required files
for (const file of requiredFiles) {