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
import { readdir, readFile, stat } from 'node:fs/promises';
import path from 'node:path';
import { execSync } from 'node:child_process';
import { Finding, BaseAuditResult, fileExists } from '@cobusgreyling/readiness-core';
import { PROOF_FILE, readProof, type ProofSignals } from './proof.js';
export interface LoopSignals {
stateFile: { present: boolean; paths: string[] };
loopConfig: { present: boolean; path?: string };
skills: { count: number; loopSkills: string[] };
verifier: { present: boolean };
triage: { present: boolean };
agentsMd: { present: boolean };
patterns: { documented: boolean };
safety: { loopMdMentionsSafety: boolean; safetyDocPresent: boolean };
starters: { used: boolean };
github: { present: boolean; workflows: boolean };
mcp: { present: boolean };
worktreeEvidence: { present: boolean };
registry: { present: boolean };
cost: {
budgetDoc: boolean;
runLog: boolean;
loopMdBudget: boolean;
budgetSkill: boolean;
};
governance: {
toolScope: boolean;
stallDetection: boolean;
escalation: boolean;
gateYaml: boolean;
};
constraints: { present: boolean; hasConstraintsSkill: boolean };
loopActivity: { present: boolean; evidence: string[] };
/** harness-foundry runtime signals (LE → Foundry funnel). */
harness: {
stack: boolean;
lock: boolean;
sessions: boolean;
emit: boolean;
host: boolean;
};
/** memory-engineering setup (memory-tiers.md, memory-budget.md) */
memory: {
tiers: boolean;
budget: boolean;
};
/** fleet-engineering setup (fleet-registry.md, fleet-inbox.md) */
fleet: {
registry: boolean;
inbox: boolean;
};
/** Guardrails loop-drill showed firing (loop-drill.json). Optional so older callers still type-check. */
proof?: ProofSignals;
}
export type { Finding };
export type { ProofSignals };
export interface AuditResult extends BaseAuditResult<'L0' | 'L1' | 'L2' | 'L3', LoopSignals> {}
const STATE_FILES = [
'STATE.md',
'pr-babysitter-state.md',
'ci-sweeper-state.md',
'post-merge-state.md',
'dependency-sweeper-state.md',
'changelog-drafter-state.md',
'issue-triage-state.md',
];
/** Score contribution for each readiness signal (see computeScore). */
const SCORE_WEIGHTS = {
base: 7,
stateFile: 18,
triage: 14,
loopConfig: 9,
agentsMd: 9,
skillsTwoPlus: 14,
skillsOne: 7,
verifier: 14,
safetyLoopMd: 4,
safetyDoc: 4,
github: 6,
githubWorkflows: 4,
mcp: 3,
worktree: 3,
registry: 2,
budgetDoc: 3,
runLog: 3,
loopMdBudget: 2,
budgetSkill: 2,
toolScope: 3,
stallDetection: 3,
escalation: 3,
gateYaml: 3,
constraintsFile: 4,
constraintsSkill: 2,
loopActivity: 14,
/** Harness Runtime (harness-foundry) — stack, lock, sessions, emit, host */
harnessStack: 4,
harnessLock: 1,
harnessSessions: 2,
harnessEmit: 1,
harnessHost: 1,
/** Memory Engineering (memory-tiers.md, memory-budget.md) */
memoryTiers: 4,
memoryBudget: 2,
/** Fleet Engineering (fleet-registry.md, fleet-inbox.md) */
fleetRegistry: 4,
fleetInbox: 2,
} as const;
const LEVEL_THRESHOLDS = {
L1: 38,
L2: 58,
L3: 78,
} as const;
const LOOP_SKILL_NAMES = [
'loop-triage',
'minimal-fix',
'loop-verifier',
'pr-review-triage',
'ci-triage',
'post-merge-scan',
'dependency-triage',
'rebase-and-clean',
'changelog-scan',
'loop-constraints',
'draft-release-notes',
'issue-triage',
];
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,
];
const SKILL_DIRS = ['.grok/skills', '.claude/skills', '.codex/skills', 'skills'];
/**
* A signal file counts only when it has content. Empty and whitespace-only
* files, and JSON that is just {} or [], are placeholders: `touch` is not setup.
*/
export async function hasContent(p: string): Promise<boolean> {
let text: string;
try {
const info = await stat(p);
if (!info.isFile()) return false;
if (info.size > 64 * 1024) return true;
text = await readFile(p, 'utf8');
} catch {
return false;
}
const trimmed = text.replace(/^/, '').trim();
if (!trimmed) return false;
if (p.toLowerCase().endsWith('.json')) {
try {
const value = JSON.parse(trimmed);
if (value !== null && typeof value === 'object' && Object.keys(value).length === 0) return false;
} catch {
// Not valid JSON, but still content; other checks judge the format.
}
}
return true;
}
/**
* Frontmatter with a name and a description: what Claude Code, Codex and Grok
* need before they will load a skill or subagent. Without it the file is
* never invoked, whatever it is called.
*/
export function hasSkillFrontmatter(text: string): boolean {
const m = text.replace(/^/, '').match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
if (!m) return false;
return /^name:[ \t]*\S/m.test(m[1]) && /^description:[ \t]*\S/m.test(m[1]);
}
async function isLoadableSkill(p: string): Promise<boolean> {
try {
return hasSkillFrontmatter(await readFile(p, 'utf8'));
} catch {
return false;
}
}
/**
* A gate.yaml loop-gate can load declares `version: 1` and a denylist. This is
* a shape check, not a parse; loop-drill's record proves the policy works.
*/
export function looksLikeGatePolicy(text: string): boolean {
return /^version:[ \t]*1[ \t]*(?:#.*)?$/m.test(text) && /^denylist:/m.test(text);
}
async function anyFileWithContent(dir: string, depth: number, accept: (name: string) => boolean): Promise<boolean> {
let entries;
try {
entries = await readdir(dir, { withFileTypes: true });
} catch {
return false;
}
for (const e of entries) {
const p = path.join(dir, e.name);
if (e.isFile() && accept(e.name) && (await hasContent(p))) return true;
if (e.isDirectory() && depth > 0 && (await anyFileWithContent(p, depth - 1, accept))) return true;
}
return false;
}
interface SkillScan {
names: string[];
/** Skill and agent files that exist but could never be loaded. */
hollow: string[];
}
async function findSkills(root: string): Promise<SkillScan> {
const found = new Set<string>();
const hollow: string[] = [];
// A skill is a directory with a loadable SKILL.md. A bare directory, or a
// SKILL.md with no frontmatter, used to count just for its name.
for (const dir of SKILL_DIRS) {
let entries;
try {
entries = await readdir(path.join(root, dir), { withFileTypes: true });
} catch {
continue;
}
for (const e of entries) {
if (!e.isDirectory()) continue;
const rel = `${dir}/${e.name}/SKILL.md`;
if (await isLoadableSkill(path.join(root, rel))) found.add(e.name);
else hollow.push(rel);
}
}
// Claude Code agents and Codex subagents can host the verifier role
for (const dir of ['.claude/agents', '.codex/agents']) {
let entries;
try {
entries = await readdir(path.join(root, dir), { withFileTypes: true });
} catch {
continue;
}
for (const e of entries) {
if (!e.isFile()) continue;
const base = e.name.replace(/\.(md|toml)$/i, '');
if (!(base.includes('verifier') || base === 'loop-verifier')) continue;
const rel = `${dir}/${e.name}`;
const abs = path.join(root, rel);
const loadable = /\.md$/i.test(e.name) ? await isLoadableSkill(abs) : await hasContent(abs);
if (loadable) found.add('loop-verifier');
else hollow.push(rel);
}
}
// Opencode named agents in opencode.json (or the starter example before rename)
for (const configName of ['opencode.json', 'opencode.json.example']) {
const configPath = path.join(root, configName);
if (!(await fileExists(configPath))) continue;
try {
const raw = await readFile(configPath, 'utf8');
const parsed = JSON.parse(raw) as { agent?: Record<string, { name?: string }> };
const agents = parsed.agent ?? {};
for (const [key, def] of Object.entries(agents)) {
const name = (def?.name ?? key).toLowerCase();
if (name.includes('verifier') || key.toLowerCase().includes('verifier')) {
found.add('loop-verifier');
break;
}
}
} catch {
// ignore invalid JSON
}
}
return { names: [...found], hollow };
}
/**
* L3 means unattended actions behind gates, so the gate has to be shown to
* fire, not just to exist: loop-drill must have drilled the current gate.yaml
* in both directions, and no recorded guardrail may be failing.
*/
export function guardrailsProven(proof: ProofSignals | undefined): boolean {
return !!proof && proof.proven.includes('gate') && proof.failed.length === 0;
}
/** Activity older than this does not count toward Loop Ready. */
export const ACTIVITY_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
function parseLastRunTimestamp(text: string): Date | null {
const m = text.match(
/Last run:\s*([0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9:.]+(?:Z|[+-][0-9:]+)?)?)/i,
);
if (!m) return null;
const raw = /T|\s/.test(m[1]) ? m[1].replace(' ', 'T') : `${m[1]}T00:00:00Z`;
const d = new Date(raw);
return Number.isNaN(d.getTime()) ? null : d;
}
function isFreshTimestamp(d: Date, now = Date.now()): boolean {
const age = now - d.getTime();
return age <= ACTIVITY_MAX_AGE_MS && age >= -60_000;
}
async function detectLoopActivity(root: string): Promise<{ present: boolean; evidence: string[] }> {
const evidence: string[] = [];
const now = Date.now();
// 1. Fresh "Last run" timestamps in state files (not the mere presence of the words)
for (const sf of STATE_FILES) {
try {
const p = path.join(root, sf);
if (!(await fileExists(p))) continue;
const txt = await readFile(p, 'utf8');
const when = parseLastRunTimestamp(txt);
if (when && isFreshTimestamp(when, now)) evidence.push(`state:${sf}:fresh`);
} catch {}
}
// 2. Dated JSON rows in the run log (file presence alone is not a run)
try {
const logPath = path.join(root, 'loop-run-log.md');
if (await fileExists(logPath)) {
const txt = await readFile(logPath, 'utf8');
for (const line of txt.split('\n')) {
const trimmed = line.trim();
if (!trimmed.startsWith('{')) continue;
try {
const row = JSON.parse(trimmed) as { run_id?: string };
if (!row.run_id) continue;
const when = new Date(row.run_id);
if (!Number.isNaN(when.getTime()) && isFreshTimestamp(when, now)) {
evidence.push('log:loop-run-log.md:fresh');
break;
}
} catch {
// ignore invalid JSON lines
}
}
}
} catch {}
// 3. Git history on state / run-log files in the last 14 days — not arbitrary "triage" commit messages
try {
const log = execSync(
'git log --since=14.days --oneline -- STATE.md loop-run-log.md "*state.md" "*-state.md"',
{
cwd: root,
encoding: 'utf8',
stdio: ['ignore', 'pipe', 'ignore'],
timeout: 1500,
},
);
const first = log.trim().split('\n')[0] || '';
if (first) evidence.push(`git:${first.slice(0, 60)}`);
} catch {
// git not available or not a repo — ignore gracefully
}
return { present: evidence.length > 0, evidence: Array.from(new Set(evidence)).slice(0, 4) };
}
export function computeScore(signals: LoopSignals): { score: number; level: 'L0' | 'L1' | 'L2' | 'L3'; assessment: string } {
const w = SCORE_WEIGHTS;
let score: number = w.base;
if (signals.stateFile.present) score += w.stateFile;
if (signals.triage.present) score += w.triage;
if (signals.loopConfig.present) score += w.loopConfig;
if (signals.agentsMd.present) score += w.agentsMd;
if (signals.skills.count >= 2) score += w.skillsTwoPlus;
else if (signals.skills.count === 1) score += w.skillsOne;
if (signals.verifier.present) score += w.verifier;
if (signals.safety.loopMdMentionsSafety) score += w.safetyLoopMd;
if (signals.safety.safetyDocPresent) score += w.safetyDoc;
if (signals.github.present) score += w.github;
if (signals.github.workflows) score += w.githubWorkflows;
if (signals.mcp.present) score += w.mcp;
if (signals.worktreeEvidence.present) score += w.worktree;
if (signals.registry.present) score += w.registry;
if (signals.cost.budgetDoc) score += w.budgetDoc;
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.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;
if (signals.harness.stack) score += w.harnessStack;
if (signals.harness.lock) score += w.harnessLock;
if (signals.harness.sessions) score += w.harnessSessions;
if (signals.harness.emit) score += w.harnessEmit;
if (signals.harness.host) score += w.harnessHost;
if (signals.memory.tiers) score += w.memoryTiers;
if (signals.memory.budget) score += w.memoryBudget;
if (signals.fleet.registry) score += w.fleetRegistry;
if (signals.fleet.inbox) score += w.fleetInbox;
score = Math.min(100, Math.max(0, score));
const costReady =
signals.cost.budgetDoc &&
signals.cost.runLog &&
signals.cost.loopMdBudget;
const hasRealActivity = signals.loopActivity.present;
const proven = guardrailsProven(signals.proof);
const l3Ready = costReady && hasRealActivity && proven;
let level: 'L0' | 'L1' | 'L2' | 'L3' = 'L0';
if (score >= LEVEL_THRESHOLDS.L3 && signals.verifier.present && signals.stateFile.present && l3Ready) level = 'L3';
else if (score >= LEVEL_THRESHOLDS.L2 && signals.triage.present) level = 'L2';
else if (score >= LEVEL_THRESHOLDS.L1 && signals.stateFile.present) level = 'L1';
else level = 'L0';
const assessment =
score >= 82 && l3Ready
? 'Strong loop readiness — good candidate for L3 with explicit gates.'
: score >= 82 && !costReady
? 'Strong signals but missing cost observability (loop-budget.md, loop-run-log.md, LOOP.md budget) — add before L3.'
: score >= 82 && !hasRealActivity
? 'Strong structure but no proven loop runs yet — run one L1 cycle and commit state before L3.'
: score >= 82 && !proven
? 'Strong structure but guardrails are unproven — run loop-drill --record and commit loop-drill.json before L3.'
: score >= 62
? 'Good foundation — add missing verifier + safety docs for L3.'
: score >= 42
? 'Early loop setup — focus on L1 state + triage before enabling actions.'
: 'Not loop-ready — start with a starter from this repo (minimal-loop or pr-babysitter).';
return { score, level, assessment };
}
export async function auditProject(target: string): Promise<AuditResult> {
const root = path.resolve(target);
const findings: Finding[] = [];
const recommendations: string[] = [];
// Every file signal goes through here, so an empty file never scores and is
// reported instead of silently counted.
const placeholders: string[] = [];
const present = async (rel: string): Promise<boolean> => {
const p = path.join(root, rel);
if (await hasContent(p)) return true;
if (await fileExists(p)) placeholders.push(rel);
return false;
};
const statePaths: string[] = [];
for (const f of STATE_FILES) {
if (await present(f)) statePaths.push(f);
}
const loopMd = await present('LOOP.md');
const agentsMd = (await present('AGENTS.md')) || (await present('CLAUDE.md'));
const skillScan = await findSkills(root);
const skillNames = skillScan.names;
const proof = await readProof(root);
const loopSkills = skillNames.filter((s) => LOOP_SKILL_NAMES.includes(s));
// A verifier loop-drill caught approving seeded defects is Verifier Theater:
// it earns nothing, whatever its file is called.
const verifierFound = skillNames.includes('loop-verifier');
const verifier = verifierFound && !proof.failed.includes('verifier');
const triage = skillNames.includes('loop-triage') ||
skillNames.includes('pr-review-triage') ||
skillNames.includes('ci-triage') ||
skillNames.includes('dependency-triage') ||
skillNames.includes('post-merge-scan') ||
skillNames.includes('changelog-scan') ||
skillNames.includes('issue-triage');
let loopMdContent = '';
if (loopMd) {
loopMdContent = await readFile(path.join(root, 'LOOP.md'), 'utf8');
}
// New expanded signals. A .github/ of empty files is not a dogfooding setup.
const githubDir = await anyFileWithContent(path.join(root, '.github'), 3, () => true);
const hasWorkflows = await anyFileWithContent(path.join(root, '.github', 'workflows'), 0, (n) =>
/\.ya?ml$/i.test(n),
);
// Proper safety doc detection
let safetyDocPresent = false;
for (const f of SAFETY_FILES) {
if (await present(f)) { safetyDocPresent = true; break; }
}
let mcpConfig = false;
for (const f of MCP_FILES) {
if (await present(f)) { mcpConfig = true; break; }
}
const mcpPresent = mcpConfig || /MCP|mcp server|plugins & connectors/i.test(loopMdContent);
// Light evidence of worktree usage (common in patterns/starters/LOOP)
let worktreeEvidence = false;
const candidateMd = [
'LOOP.md',
'patterns/pr-babysitter.md',
'starters/minimal-loop/LOOP.md',
'starters/minimal-loop-claude/LOOP.md',
'starters/minimal-loop-codex/LOOP.md',
'docs/operating-loops.md',
];
for (const c of candidateMd) {
try {
const p = path.join(root, c);
if (await fileExists(p)) {
const txt = await readFile(p, 'utf8');
if (WORKTREE_HINTS.some(h => txt.toLowerCase().includes(h))) { worktreeEvidence = true; break; }
}
} catch {}
}
const registryPresent = await present('patterns/registry.yaml');
const budgetDoc = await present('loop-budget.md');
const runLog = await present('loop-run-log.md');
const loopMdBudget = BUDGET_HINTS.some((re) => re.test(loopMdContent));
// findSkills only lists skills with a loadable SKILL.md.
const budgetSkill = skillNames.includes('loop-budget');
const loopActivity = await detectLoopActivity(root);
const constraintsFile = await present('loop-constraints.md');
const constraintsSkill = skillNames.includes('loop-constraints');
// 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 stallClaimed =
skillNames.includes('loop-context') ||
skillNames.includes('loop-guard') ||
ledgerPresent ||
STALL_HINTS.some((re) => re.test(governanceCorpus));
const stallDetection = stallClaimed && !proof.failed.includes('breaker');
const escalation = ESCALATION_HINTS.some((re) => re.test(governanceCorpus));
// gate.yaml must look like a policy, and must not be one loop-drill found
// broken: failing, or impossible to drill at all (loop-gate refused it).
let gatePolicy = false;
if (await present('gate.yaml')) {
gatePolicy = looksLikeGatePolicy(await readFile(path.join(root, 'gate.yaml'), 'utf8'));
}
const gateYaml = gatePolicy && !proof.failed.includes('gate') && !proof.untested.includes('gate');
// Harness Runtime (harness-foundry) — versioned stack, sessions/traces, outerloop emit, host bridge
const foundryStackPath = path.join(root, '.foundry', 'stack.yaml');
const harnessStack = await present('.foundry/stack.yaml');
const harnessLock = (await present('.foundry/stack.lock')) || (await present('.foundry/stack.lock.yaml'));
let harnessSessions = false;
const sessionsDir = path.join(root, '.foundry', 'sessions');
if (await fileExists(sessionsDir)) {
try {
const entries = await readdir(sessionsDir, { withFileTypes: true });
harnessSessions = entries.some(
(e) => e.isDirectory() || (e.isFile() && e.name !== '.gitkeep'),
);
} catch {
harnessSessions = false;
}
}
let harnessEmit = false;
if (harnessStack) {
try {
const stackTxt = await readFile(foundryStackPath, 'utf8');
if (/emit\/outerloop-evidence|outerloop/i.test(stackTxt)) harnessEmit = true;
} catch {}
}
if (!harnessEmit && (await present('.foundry/hooks/outerloop.yaml'))) {
harnessEmit = true;
}
const harnessHost =
(await fileExists(path.join(root, '.foundry', 'host', 'cursor'))) ||
(await fileExists(path.join(root, '.foundry', 'host', 'claude-code'))) ||
(await present('.cursor/rules/foundry.mdc')) ||
(await present('.claude/foundry.md')) ||
/foundry host integrate|harness-foundry/i.test(loopMdContent);
const harness = {
stack: harnessStack,
lock: harnessLock,
sessions: harnessSessions,
emit: harnessEmit,
host: harnessHost,
};
// Memory Engineering (memory-tiers.md, memory-budget.md)
const memoryTiers = await present('memory-tiers.md');
const memoryBudget = await present('memory-budget.md');
const memory = { tiers: memoryTiers, budget: memoryBudget };
// Fleet Engineering (fleet-registry.md, fleet-inbox.md)
const fleetRegistry = await present('fleet-registry.md');
const fleetInbox = await present('fleet-inbox.md');
const fleet = { registry: fleetRegistry, inbox: fleetInbox };
const signals: LoopSignals = {
stateFile: { present: statePaths.length > 0, paths: statePaths },
loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },
skills: { count: loopSkills.length, loopSkills },
verifier: { present: verifier },
triage: { present: triage },
agentsMd: { present: agentsMd },
patterns: { documented: loopMd },
safety: { loopMdMentionsSafety: /gate|denylist|auto-merge|safety/i.test(loopMdContent), safetyDocPresent },
starters: { used: loopSkills.includes('loop-triage') },
github: { present: githubDir, workflows: hasWorkflows },
mcp: { present: mcpPresent },
constraints: { present: constraintsFile, hasConstraintsSkill: constraintsSkill },
worktreeEvidence: { present: worktreeEvidence },
registry: { present: registryPresent },
cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },
governance: { toolScope, stallDetection, escalation, gateYaml },
loopActivity,
harness,
memory,
fleet,
proof,
};
const thinLoopWorkflow = await present('.github/workflows/thin-loop.yml');
if (placeholders.length > 0 || skillScan.hollow.length > 0) {
const hollow = [...new Set([...placeholders, ...skillScan.hollow])];
findings.push({
level: 'warn',
message: `Not counted — empty, or a skill/agent without name + description frontmatter: ${hollow.join(', ')}.`,
});
recommendations.push('Fill in or delete placeholder files; a skill needs a SKILL.md with name and description frontmatter to load');
}
if (!signals.stateFile.present) {
if (thinLoopWorkflow) {
findings.push({
level: 'warn',
message: 'No STATE.md — acceptable for a thin loop if GitHub issues/PRs are the spine. Add STATE.md when findings must persist across runs.',
});
} else {
findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });
recommendations.push('Copy starters/minimal-loop/STATE.md.example (or -claude / -codex variant) to STATE.md — or scaffold starters/thin-loop if the tracker is the state');
}
} else {
findings.push({ level: 'ok', message: `State file(s): ${statePaths.join(', ')}` });
for (const sf of statePaths) {
try {
const txt = await readFile(path.join(root, sf), 'utf8');
const when = parseLastRunTimestamp(txt);
if (when && !isFreshTimestamp(when)) {
findings.push({
level: 'warn',
message: `${sf} Last run is older than 14 days — files on disk are not loop activity.`,
});
recommendations.push(`Run the loop and commit ${sf} (or append loop-run-log.md) so Loop Ready can see a fresh timestamp`);
}
} catch {}
}
}
if (!signals.triage.present) {
findings.push({ level: 'warn', message: 'No triage skill detected.' });
recommendations.push('Install loop-triage from starters/minimal-loop, minimal-loop-claude, or minimal-loop-codex');
} else {
findings.push({ level: 'ok', message: 'Triage skill present.' });
}
if (verifierFound && !verifier) {
findings.push({
level: 'fail',
message: `Verifier present but loop-drill's canary caught it approving seeded defects (Verifier Theater) — not counted: ${proof.failures.filter((id) => id.startsWith('verifier')).join(', ')}.`,
});
recommendations.push('Make the verifier reject the seeded defects, then rerun: npx @cobusgreyling/loop-drill . --only verifier --verifier-cmd "<cmd>" --record');
} else if (!signals.verifier.present) {
findings.push({ level: 'warn', message: 'No loop-verifier skill — maker/checker split incomplete.' });
recommendations.push('Add verifier: .grok/skills/loop-verifier, .claude/agents/loop-verifier.md, .codex/agents/verifier.toml, or a verifier agent in opencode.json');
} else {
findings.push({ level: 'ok', message: 'Verifier skill present.' });
}
if (!signals.loopConfig.present) {
findings.push({ level: 'warn', message: 'No LOOP.md documenting cadence, limits, and gates.' });
recommendations.push('Copy starters/minimal-loop/LOOP.md and customize');
}
if (!signals.agentsMd.present) {
findings.push({ level: 'warn', message: 'No AGENTS.md / CLAUDE.md for project conventions.' });
recommendations.push('Add AGENTS.md with build/test commands and review norms');
}
if (!signals.safety.loopMdMentionsSafety) {
findings.push({ level: 'warn', message: 'LOOP.md does not mention safety gates or auto-merge policy.' });
recommendations.push('Document human gates per docs/safety.md in LOOP.md');
}
if (!signals.safety.safetyDocPresent) {
findings.push({ level: 'warn', message: 'No safety.md or docs/safety.md found.' });
recommendations.push('Copy or create docs/safety.md (denylists, auto-merge policy, MCP scopes)');
} else {
findings.push({ level: 'ok', message: 'Safety documentation present.' });
}
if (!signals.constraints.present) {
findings.push({ level: 'warn', message: 'No loop-constraints.md — structured constraints file missing.' });
recommendations.push('Create loop-constraints.md with denylist paths, push/merge rules, and human gates (see templates/loop-constraints.md)');
} else {
findings.push({ level: 'ok', message: 'loop-constraints.md present.' });
}
if (signals.constraints.present && !signals.constraints.hasConstraintsSkill) {
findings.push({ level: 'warn', message: 'loop-constraints.md exists but no loop-constraints skill — rules not enforced at runtime.' });
recommendations.push('Add loop-constraints skill via loop-init or templates/SKILL.md.loop-constraints');
}
if (!signals.github.present) {
findings.push({ level: 'warn', message: 'No .github/ directory (templates, workflows for dogfooding).' });
recommendations.push('Add .github/ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, and workflows (see this repo for examples)');
} else if (!signals.github.workflows) {
findings.push({ level: 'warn', message: '.github/ exists but no workflows/ (CI dogfood opportunity).' });
recommendations.push('Add GitHub Actions that run loop-audit and validate patterns (dogfood the reference)');
} else {
findings.push({ level: 'ok', message: '.github/ with workflows present (strong dogfooding signal).' });
}
if (!signals.mcp.present) {
findings.push({ level: 'warn', message: 'No MCP / connector config or mentions detected.' });
recommendations.push('Document MCP usage (or note "MCP not required for this pattern") in LOOP.md or skills');
}
if (!signals.worktreeEvidence.present) {
findings.push({ level: 'warn', message: 'Little evidence of worktree usage in docs or state.' });
recommendations.push('Add worktree isolation notes to LOOP.md or pattern docs (see primitives and starters)');
}
if (!signals.registry.present) {
findings.push({ level: 'warn', message: 'No patterns/registry.yaml (machine-readable index for future tools).' });
recommendations.push('Add patterns/registry.yaml following the existing format');
}
if (!signals.cost.budgetDoc) {
findings.push({ level: 'warn', message: 'No loop-budget.md — token caps and kill switch undocumented.' });
recommendations.push('Scaffold with loop-init or copy templates/loop-budget.md.template');
} else {
findings.push({ level: 'ok', message: 'loop-budget.md present.' });
}
if (!signals.cost.runLog) {
findings.push({ level: 'warn', message: 'No loop-run-log.md — run history not persisted.' });
recommendations.push('Copy templates/loop-run-log.md.template to loop-run-log.md');
} else {
findings.push({ level: 'ok', message: 'loop-run-log.md present.' });
}
if (!signals.cost.loopMdBudget) {
findings.push({ level: 'warn', message: 'LOOP.md does not mention budget, token caps, or kill switch.' });
recommendations.push('Add a Budget section to LOOP.md (see starters/*/LOOP.md)');
}
if (!signals.cost.budgetSkill) {
findings.push({ level: 'warn', message: 'No loop-budget skill — budget checks are not automated at runtime.' });
recommendations.push('Add loop-budget skill via loop-init or templates/SKILL.md.loop-budget');
} 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).' });
}
// An empty gate.yaml is already listed as a placeholder; only judge one with content.
const gateHasContent = (await fileExists(path.join(root, 'gate.yaml'))) && !placeholders.includes('gate.yaml');
if (gatePolicy && proof.failed.includes('gate')) {
findings.push({
level: 'fail',
message: `gate.yaml present but loop-drill shows it does not hold — not counted: ${proof.failures.filter((id) => id.startsWith('gate')).join(', ')}.`,
});
recommendations.push('Fix gate.yaml so the failing drills pass, then rerun: npx @cobusgreyling/loop-drill . --record');
} else if (gatePolicy && proof.untested.includes('gate')) {
findings.push({
level: 'fail',
message: `gate.yaml present but loop-drill could not drill it — not counted${proof.skipReasons.gate ? `: ${proof.skipReasons.gate}` : '.'}`,
});
recommendations.push('Give gate.yaml a non-empty denylist that loop-gate accepts (see templates/gate.yaml.template), then rerun loop-drill --record');
} else if (gateHasContent && !gatePolicy) {
findings.push({
level: 'fail',
message: 'gate.yaml is not a gate policy (needs `version: 1` and a `denylist:`) — loop-gate would refuse to load it. Not counted.',
});
recommendations.push('Replace gate.yaml with templates/gate.yaml.template and customize the denylist');
} else 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).' });
}
// Proof that guardrails fire, from loop-drill --record.
if (proof.error) {
findings.push({ level: 'warn', message: `${PROOF_FILE} is unreadable (${proof.error}) — no guardrail counts as proven.` });
recommendations.push(`Regenerate it: npx @cobusgreyling/loop-drill . --record`);
} else if (!proof.present) {
findings.push({
level: 'warn',
message: `No ${PROOF_FILE} — guardrails are present but unproven. Nothing shows the gate blocks a sensitive path or the verifier rejects a bad change.`,
});
recommendations.push(`Prove the guardrails fire, then commit the record: npx @cobusgreyling/loop-drill . --record`);
} else {
if (proof.proven.length > 0) {
findings.push({ level: 'ok', message: `Guardrails proven by loop-drill: ${proof.proven.join(', ')}.` });
}
const failedElsewhere = proof.failed.filter((g) => g !== 'gate' && g !== 'verifier');
if (failedElsewhere.length > 0) {
findings.push({
level: 'fail',
message: `loop-drill shows guardrails failing to fire: ${failedElsewhere.join(', ')} (${proof.failures.filter((id) => failedElsewhere.some((g) => id.startsWith(g))).join(', ')}).`,
});
recommendations.push('Fix the failing guardrails, then rerun: npx @cobusgreyling/loop-drill . --record');
}
if (proof.stale.length > 0) {
findings.push({
level: 'warn',
message: `${PROOF_FILE} is out of date for: ${proof.stale.join(', ')} (gate.yaml changed since it was drilled, or a canary is over 30 days old) — not counted.`,
});
recommendations.push(`Re-record: npx @cobusgreyling/loop-drill . --record (add --only for canaries you ran before)`);
}
}
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.');
} else {
findings.push({ level: 'ok', message: `Loop activity detected — real usage signals present (${signals.loopActivity.evidence.length} sources).` });
}
if (!signals.harness.stack) {
findings.push({
level: 'warn',
message: 'No harness-foundry stack (.foundry/stack.yaml) — loop is designed but not versioned as a composable harness runtime.',
});
recommendations.push(
'Scaffold a harness: npx @cobusgreyling/loop-init . --with-foundry (or npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage)',
);
} else {
findings.push({ level: 'ok', message: 'Harness stack present (.foundry/stack.yaml).' });
if (!signals.harness.emit) {
findings.push({
level: 'warn',
message: 'Harness stack has no outerloop emit path (emit/outerloop-evidence or .foundry/hooks/outerloop.yaml).',
});
recommendations.push('Add emit/outerloop-evidence to the reliability layer, or enable .foundry/hooks/outerloop.yaml');
} else {
findings.push({ level: 'ok', message: 'Harness emit path to outerloop present.' });
}
if (!signals.harness.sessions) {
findings.push({
level: 'warn',
message: 'No harness sessions yet — run foundry once to produce traces.',
});
recommendations.push(
'npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring" then re-audit',
);
} else {
findings.push({ level: 'ok', message: 'Harness session/trace evidence present.' });
}
}
if (!signals.memory.tiers) {
findings.push({
level: 'warn',
message: 'No memory-tiers.md — memory engineering tiers are not defined.',
});
recommendations.push('Scaffold memory tiers: npx @cobusgreyling/loop-init . --with-memory');
} else {
findings.push({ level: 'ok', message: 'Memory tiers defined (memory-tiers.md).' });
if (!signals.memory.budget) {
findings.push({
level: 'warn',
message: 'Memory tiers defined but no memory-budget.md — recall budget is missing.',
});
recommendations.push('Add memory-budget.md to cap retrieval costs.');
} else {
findings.push({ level: 'ok', message: 'Memory budget defined.' });
}
}
if (!signals.fleet.registry) {
findings.push({
level: 'warn',
message: 'No fleet-registry.md — multi-agent populations and roles are not defined.',
});
recommendations.push('Scaffold a fleet: npx @cobusgreyling/loop-init . --with-fleet');
} else {
findings.push({ level: 'ok', message: 'Fleet registry defined (fleet-registry.md).' });
if (!signals.fleet.inbox) {
findings.push({
level: 'warn',
message: 'Fleet registry defined but no fleet-inbox.md — agents cannot cross-communicate.',
});
recommendations.push('Add fleet-inbox.md to enable cross-loop tasks.');
} else {
findings.push({ level: 'ok', message: 'Fleet inbox defined.' });
}
}
const { score, level, assessment } = computeScore(signals);
// Companion funnels stay available via --with-foundry / --with-memory / --with-fleet
// but are not pushed to the top of week-one recommendations.
const costReady =
signals.cost.budgetDoc &&
signals.cost.runLog &&
signals.cost.loopMdBudget;
if (score >= 78 && signals.verifier.present && signals.stateFile.present && !costReady) {
findings.push({
level: 'warn',
message: 'Score qualifies for L3 but cost observability is incomplete — capped at L2 until budget + run log + LOOP.md budget exist.',
});
}
if (score >= 78 && signals.verifier.present && signals.stateFile.present && costReady && !signals.loopActivity.present) {
findings.push({
level: 'warn',
message: 'Score qualifies for L3 but no proven loop activity yet — capped at L2 until you run and commit at least one loop cycle.',
});
}
if (
score >= 78 &&
signals.verifier.present &&
signals.stateFile.present &&
costReady &&
signals.loopActivity.present &&
!guardrailsProven(proof)
) {
findings.push({
level: 'warn',
message: `Score qualifies for L3 but the guardrails are unproven — capped at L2 until ${PROOF_FILE} shows the current gate.yaml passing its drills and no guardrail failing.`,
});
}
return {
target: root,
score,
level,
assessment,
signals,
findings,
recommendations,
};
}