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: 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.tsindex 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.jsindex 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 bridgeconst 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.jsindex 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.jsindex 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));elseconsole.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.tsindex 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 bridgeconst 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.tsindex 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): Promiawait 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.mjsindex 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.jsindex 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 filesfor (const file of requiredFiles) {