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
feat(loop-audit): score least-privilege, stall detection, and escalation signals (#233)
JonyT Agenticea1d4ce3ba67
diff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.mdindex a198c9a..7af369f 100644--- a/tools/loop-audit/README.md+++ b/tools/loop-audit/README.md@@ -70,6 +70,9 @@ npm publish --access public| loop-run-log.md | Append-only run history || LOOP.md budget section | Cadence limits documented in config || loop-budget skill | Runtime budget guard |+| Least-privilege tool scope | `allowed-tools` in SKILL.md, or documented tool/MCP scopes (agents get only what their role needs) |+| Stall / no-progress detection | loop-context circuit breaker, a ledger, or a documented max-attempts / no-progress rule |+| Human-escalation path | LOOP.md / safety docs define when to stop and hand off to a human || **loopActivity (v1.4)** | **Dynamic proof**: "Last run" timestamps in state, loop-related git commits, scheduled workflows, run logs |L3 requires verifier + state + cost observability (budget + run log + LOOP.md budget) **and** proven loop activity (not just files on disk).diff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.tsindex 2d81924..24e462e 100644--- a/tools/loop-audit/dist/auditor.d.ts+++ b/tools/loop-audit/dist/auditor.d.ts@@ -49,6 +49,11 @@ export interface LoopSignals {loopMdBudget: boolean;budgetSkill: boolean;};+ governance: {+ toolScope: boolean;+ stallDetection: boolean;+ escalation: boolean;+ };constraints: {present: boolean;hasConstraintsSkill: boolean;diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.jsindex cee4ef2..4b90013 100644--- a/tools/loop-audit/dist/auditor.js+++ b/tools/loop-audit/dist/auditor.js@@ -31,6 +31,9 @@ const SCORE_WEIGHTS = {runLog: 3,loopMdBudget: 2,budgetSkill: 2,+ toolScope: 3,+ stallDetection: 3,+ escalation: 3,constraintsFile: 4,constraintsSkill: 2,loopActivity: 6,@@ -58,6 +61,36 @@ const SAFETY_FILES = ['safety.md', 'docs/safety.md', 'SECURITY.md'];const MCP_FILES = ['.mcp.json', 'mcp.json', '.mcp/config.json'];const WORKTREE_HINTS = ['worktree', 'worktrees', 'git worktree'];const BUDGET_HINTS = [/budget/i, /max tokens/i, /token cap/i, /kill switch/i, /loop-pause-all/i];+// Governance signals (multi-agent safety rubric): least-privilege tool scope,+// stall / no-progress detection, and an explicit human-escalation path.+const TOOL_SCOPE_HINTS = [+ /least[- ]privilege/i,+ /tool scope/i,+ /scoped tools?/i,+ /allow-?list/i,+ /read-only tools?/i,+ /permission scope/i,+];+const STALL_HINTS = [+ /loop-context/i,+ /circuit breaker/i,+ /max attempts/i,+ /no[- ]progress/i,+ /\bstall(ed|s|ing)?\b/i,+ /\bstuck\b/i,+ /same error/i,+];+const ESCALATION_HINTS = [+ /escalat/i,+ /hand[- ]?off/i,+ /human[- ]in[- ]the[- ]loop/i,+ /\bHITL\b/i,+ /human review/i,+ /needs? human/i,+ /stop and ask/i,+ /exit code 2/i,+ /\bexit 2\b/i,+];async function fileExists(p) {try {await stat(p);@@ -233,6 +266,12 @@ export function computeScore(signals) {score += w.loopMdBudget;if (signals.cost.budgetSkill)score += w.budgetSkill;+ if (signals.governance.toolScope)+ score += w.toolScope;+ if (signals.governance.stallDetection)+ score += w.stallDetection;+ if (signals.governance.escalation)+ score += w.escalation;if (signals.constraints.present)score += w.constraintsFile;if (signals.constraints.hasConstraintsSkill)@@ -364,6 +403,60 @@ export async function auditProject(target) {break;}}+ // Governance corpus: docs where scope / stall / escalation rules are written.+ let governanceCorpus = loopMdContent;+ for (const f of ['docs/safety.md', 'safety.md', 'SECURITY.md', 'loop-constraints.md']) {+ const p = path.join(root, f);+ if (await fileExists(p)) {+ try {+ governanceCorpus += '\n' + (await readFile(p, 'utf8'));+ }+ catch { }+ }+ }+ // allowed-tools frontmatter in any SKILL.md is a concrete least-privilege signal.+ let skillDeclaresTools = false;+ const skillScanDirs = [+ path.join(root, '.grok', 'skills'),+ path.join(root, '.claude', 'skills'),+ path.join(root, '.codex', 'skills'),+ path.join(root, 'skills'),+ ];+ for (const dir of skillScanDirs) {+ if (skillDeclaresTools)+ break;+ if (!(await fileExists(dir)))+ continue;+ try {+ const entries = await readdir(dir, { withFileTypes: true });+ for (const e of entries) {+ if (!e.isDirectory())+ continue;+ const sp = path.join(dir, e.name, 'SKILL.md');+ if (await fileExists(sp)) {+ const txt = await readFile(sp, 'utf8');+ if (/allowed-tools\s*:/i.test(txt)) {+ skillDeclaresTools = true;+ break;+ }+ }+ }+ }+ catch { }+ }+ const toolScope = skillDeclaresTools || TOOL_SCOPE_HINTS.some((re) => re.test(governanceCorpus));+ // loop-context is this repo's circuit breaker; its ledger is direct proof of stall handling.+ let ledgerPresent = false;+ try {+ const rootEntries = await readdir(root, { withFileTypes: true });+ ledgerPresent = rootEntries.some((e) => e.isFile() && /ledger/i.test(e.name));+ }+ catch { }+ const stallDetection = skillNames.includes('loop-context') ||+ skillNames.includes('loop-guard') ||+ ledgerPresent ||+ STALL_HINTS.some((re) => re.test(governanceCorpus));+ const escalation = ESCALATION_HINTS.some((re) => re.test(governanceCorpus));const signals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -380,6 +473,7 @@ export async function auditProject(target) {worktreeEvidence: { present: worktreeEvidence },registry: { present: registryPresent },cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },+ governance: { toolScope, stallDetection, escalation },loopActivity,};if (!signals.stateFile.present) {@@ -481,6 +575,27 @@ export async function auditProject(target) {else {findings.push({ level: 'ok', message: 'loop-budget skill present.' });}+ if (!signals.governance.toolScope) {+ findings.push({ level: 'warn', message: 'No least-privilege tool scope — skills/agents may hold broader tool or MCP access than their role needs.' });+ recommendations.push('Declare allowed-tools in SKILL.md frontmatter, or document tool/MCP scopes in docs/safety.md (least privilege per role)');+ }+ else {+ findings.push({ level: 'ok', message: 'Tool/MCP scope constrained (least-privilege signal present).' });+ }+ 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');+ }+ else {+ findings.push({ level: 'ok', message: 'Stall / no-progress detection present (circuit breaker or documented rule).' });+ }+ if (!signals.governance.escalation) {+ findings.push({ level: 'warn', message: 'No explicit human-escalation path — the loop has no defined hand-off when stuck or out of scope.' });+ recommendations.push('Document an escalation path in LOOP.md (when to stop and hand to a human; e.g. loop-context exit code 2)');+ }+ else {+ findings.push({ level: 'ok', message: 'Human-escalation path documented.' });+ }if (!signals.loopActivity.present) {findings.push({ level: 'warn', message: 'No evidence of actual loop runs detected (no "Last run" entries in state, loop-related git activity, or scheduled workflows yet).' });recommendations.push('Run one loop (report-only), update + commit STATE.md (or pattern state). This turns structure into proven usage.');diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.jsindex 5f9d4c0..a50a2bd 100644--- a/tools/loop-audit/dist/cli.js+++ b/tools/loop-audit/dist/cli.js@@ -10,7 +10,7 @@ const suggest = args.includes('--suggest') || args.includes('--fix');const badge = args.includes('--badge');const help = args.includes('--help') || args.includes('-h');if (help) {- console.log(`loop-audit — Loop Readiness Score CLI (v1.4+)+ console.log(`loop-audit — Loop Readiness Score CLI (v1.6+)Usage:loop-audit [path] [options]@@ -22,6 +22,9 @@ Options:--badge Markdown README badge (Loop Ready level + score)--help, -h This help+New in v1.6:+ • Governance signals: least-privilege tool scope, stall / no-progress detection, human-escalation path+New in v1.4:• Dynamic "loop activity" detection (git history, "Last run" in STATE, scheduled workflows)• Higher L3 bar requires proven usage, not just filesdiff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.jsonindex c2b2404..d7a8ece 100644--- a/tools/loop-audit/package.json+++ b/tools/loop-audit/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop-audit",- "version": "1.5.3",+ "version": "1.6.0","description": "Loop engineering readiness auditor. Compute Loop Readiness Score (L0-L3), detect activity, and get actionable suggestions. npx @cobusgreyling/loop-audit . --suggest","type": "module","bin": {diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.tsindex 708d22d..72b4d3e 100644--- a/tools/loop-audit/src/auditor.ts+++ b/tools/loop-audit/src/auditor.ts@@ -22,6 +22,11 @@ export interface LoopSignals {loopMdBudget: boolean;budgetSkill: boolean;};+ governance: {+ toolScope: boolean;+ stallDetection: boolean;+ escalation: boolean;+ };constraints: { present: boolean; hasConstraintsSkill: boolean };loopActivity: { present: boolean; evidence: string[] };}@@ -72,6 +77,9 @@ const SCORE_WEIGHTS = {runLog: 3,loopMdBudget: 2,budgetSkill: 2,+ toolScope: 3,+ stallDetection: 3,+ escalation: 3,constraintsFile: 4,constraintsSkill: 2,loopActivity: 6,@@ -103,6 +111,37 @@ const MCP_FILES = ['.mcp.json', 'mcp.json', '.mcp/config.json'];const WORKTREE_HINTS = ['worktree', 'worktrees', 'git worktree'];const BUDGET_HINTS = [/budget/i, /max tokens/i, /token cap/i, /kill switch/i, /loop-pause-all/i];+// Governance signals (multi-agent safety rubric): least-privilege tool scope,+// stall / no-progress detection, and an explicit human-escalation path.+const TOOL_SCOPE_HINTS = [+ /least[- ]privilege/i,+ /tool scope/i,+ /scoped tools?/i,+ /allow-?list/i,+ /read-only tools?/i,+ /permission scope/i,+];+const STALL_HINTS = [+ /loop-context/i,+ /circuit breaker/i,+ /max attempts/i,+ /no[- ]progress/i,+ /\bstall(ed|s|ing)?\b/i,+ /\bstuck\b/i,+ /same error/i,+];+const ESCALATION_HINTS = [+ /escalat/i,+ /hand[- ]?off/i,+ /human[- ]in[- ]the[- ]loop/i,+ /\bHITL\b/i,+ /human review/i,+ /needs? human/i,+ /stop and ask/i,+ /exit code 2/i,+ /\bexit 2\b/i,+];+async function fileExists(p: string): Promise<boolean> {try {await stat(p);@@ -259,6 +298,9 @@ export function computeScore(signals: LoopSignals): { score: number; level: 'L0'if (signals.cost.runLog) score += w.runLog;if (signals.cost.loopMdBudget) score += w.loopMdBudget;if (signals.cost.budgetSkill) score += w.budgetSkill;+ if (signals.governance.toolScope) score += w.toolScope;+ if (signals.governance.stallDetection) score += w.stallDetection;+ if (signals.governance.escalation) score += w.escalation;if (signals.constraints.present) score += w.constraintsFile;if (signals.constraints.hasConstraintsSkill) score += w.constraintsSkill;if (signals.loopActivity.present) score += w.loopActivity;@@ -397,6 +439,60 @@ export async function auditProject(target: string): Promise<AuditResult> {}}+ // Governance corpus: docs where scope / stall / escalation rules are written.+ let governanceCorpus = loopMdContent;+ for (const f of ['docs/safety.md', 'safety.md', 'SECURITY.md', 'loop-constraints.md']) {+ const p = path.join(root, f);+ if (await fileExists(p)) {+ try {+ governanceCorpus += '\n' + (await readFile(p, 'utf8'));+ } catch {}+ }+ }++ // allowed-tools frontmatter in any SKILL.md is a concrete least-privilege signal.+ let skillDeclaresTools = false;+ const skillScanDirs = [+ path.join(root, '.grok', 'skills'),+ path.join(root, '.claude', 'skills'),+ path.join(root, '.codex', 'skills'),+ path.join(root, 'skills'),+ ];+ for (const dir of skillScanDirs) {+ if (skillDeclaresTools) break;+ if (!(await fileExists(dir))) continue;+ try {+ const entries = await readdir(dir, { withFileTypes: true });+ for (const e of entries) {+ if (!e.isDirectory()) continue;+ const sp = path.join(dir, e.name, 'SKILL.md');+ if (await fileExists(sp)) {+ const txt = await readFile(sp, 'utf8');+ if (/allowed-tools\s*:/i.test(txt)) {+ skillDeclaresTools = true;+ break;+ }+ }+ }+ } catch {}+ }++ const toolScope = skillDeclaresTools || TOOL_SCOPE_HINTS.some((re) => re.test(governanceCorpus));++ // loop-context is this repo's circuit breaker; its ledger is direct proof of stall handling.+ let ledgerPresent = false;+ try {+ const rootEntries = await readdir(root, { withFileTypes: true });+ ledgerPresent = rootEntries.some((e) => e.isFile() && /ledger/i.test(e.name));+ } catch {}+ const stallDetection =+ skillNames.includes('loop-context') ||+ skillNames.includes('loop-guard') ||+ ledgerPresent ||+ STALL_HINTS.some((re) => re.test(governanceCorpus));++ const escalation = ESCALATION_HINTS.some((re) => re.test(governanceCorpus));+const signals: LoopSignals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -413,6 +509,7 @@ export async function auditProject(target: string): Promise<AuditResult> {worktreeEvidence: { present: worktreeEvidence },registry: { present: registryPresent },cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },+ governance: { toolScope, stallDetection, escalation },loopActivity,};@@ -522,6 +619,27 @@ export async function auditProject(target: string): Promise<AuditResult> {findings.push({ level: 'ok', message: 'loop-budget skill present.' });}+ if (!signals.governance.toolScope) {+ findings.push({ level: 'warn', message: 'No least-privilege tool scope — skills/agents may hold broader tool or MCP access than their role needs.' });+ recommendations.push('Declare allowed-tools in SKILL.md frontmatter, or document tool/MCP scopes in docs/safety.md (least privilege per role)');+ } else {+ findings.push({ level: 'ok', message: 'Tool/MCP scope constrained (least-privilege signal present).' });+ }++ 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');+ } else {+ findings.push({ level: 'ok', message: 'Stall / no-progress detection present (circuit breaker or documented rule).' });+ }++ if (!signals.governance.escalation) {+ findings.push({ level: 'warn', message: 'No explicit human-escalation path — the loop has no defined hand-off when stuck or out of scope.' });+ recommendations.push('Document an escalation path in LOOP.md (when to stop and hand to a human; e.g. loop-context exit code 2)');+ } else {+ findings.push({ level: 'ok', message: 'Human-escalation path documented.' });+ }+if (!signals.loopActivity.present) {findings.push({ level: 'warn', message: 'No evidence of actual loop runs detected (no "Last run" entries in state, loop-related git activity, or scheduled workflows yet).' });recommendations.push('Run one loop (report-only), update + commit STATE.md (or pattern state). This turns structure into proven usage.');diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.tsindex 6d64c8a..1ae39fd 100644--- a/tools/loop-audit/src/cli.ts+++ b/tools/loop-audit/src/cli.ts@@ -12,7 +12,7 @@ const badge = args.includes('--badge');const help = args.includes('--help') || args.includes('-h');if (help) {- console.log(`loop-audit — Loop Readiness Score CLI (v1.4+)+ console.log(`loop-audit — Loop Readiness Score CLI (v1.6+)Usage:loop-audit [path] [options]@@ -24,6 +24,9 @@ Options:--badge Markdown README badge (Loop Ready level + score)--help, -h This help+New in v1.6:+ • Governance signals: least-privilege tool scope, stall / no-progress detection, human-escalation path+New in v1.4:• Dynamic "loop activity" detection (git history, "Last run" in STATE, scheduled workflows)• Higher L3 bar requires proven usage, not just filesdiff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjsindex 44adc6f..af64144 100644--- a/tools/loop-audit/test/auditor.test.mjs+++ b/tools/loop-audit/test/auditor.test.mjs@@ -24,6 +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 },loopActivity: { present: false, evidence: [] },};}@@ -138,6 +139,48 @@ test('auditProject: minimal L1 layout', async () => {}});+test('computeScore: governance signals add points', () => {+ const base = emptySignals();+ const { score: without } = computeScore(base);+ const withGov = emptySignals();+ withGov.governance = { toolScope: true, stallDetection: true, escalation: true };+ const { score: withScore } = computeScore(withGov);+ assert.equal(withScore - without, 9);+});++test('auditProject: governance signals detected from docs and skill frontmatter', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-gov-'));+ try {+ await writeFile(+ path.join(dir, 'LOOP.md'),+ '# Loop\nTool scope: least-privilege per role.\nUses loop-context circuit breaker with max attempts; on no-progress, escalate to a human (exit code 2).\n',+ );+ await mkdir(path.join(dir, '.claude', 'skills', 'loop-triage'), { recursive: true });+ await writeFile(+ path.join(dir, '.claude', 'skills', 'loop-triage', 'SKILL.md'),+ '---\nname: loop-triage\ndescription: triage\nallowed-tools: Read, Grep\n---\n# Triage\n',+ );+ const result = await auditProject(dir);+ assert.ok(result.signals.governance.toolScope);+ assert.ok(result.signals.governance.stallDetection);+ assert.ok(result.signals.governance.escalation);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('auditProject: governance signals absent in bare project', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-nogov-'));+ try {+ const result = await auditProject(dir);+ assert.equal(result.signals.governance.toolScope, false);+ assert.equal(result.signals.governance.stallDetection, false);+ assert.equal(result.signals.governance.escalation, false);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});+test('formatBadge: includes level and score', () => {const badge = formatBadge({target: '/tmp',