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-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.md
index 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.ts
index 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.js
index 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.js
index 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 files
diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.json
index 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.ts
index 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.ts
index 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 files
diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjs
index 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',