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.

chore: clean up manual artifacts and drive-by rebuilds

THRISHAL12345d49ed788c4f9
diff --git a/.test-manual/AGENTS.md b/.test-manual/AGENTS.md
deleted file mode 100644
index 229e4f7..0000000
--- a/.test-manual/AGENTS.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# AGENTS.md
-
-## Goal Engineering Rules
-- Use /goal and update_goal.
-- `goal-verifier` MUST PASS before setting completed: true in GOAL.md.
diff --git a/.test-manual/GOAL.md b/.test-manual/GOAL.md
deleted file mode 100644
index 6188e1a..0000000
--- a/.test-manual/GOAL.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Goal: [Insert Goal Title Here]
-
-**Status:** IN_PROGRESS
-**Owner:** [Assigned Agent or Human]
-**Target Date:** YYYY-MM-DD
-
-## Objective
-Describe the main objective of this goal. What are we trying to achieve?
-
-## Acceptance Criteria
-- [ ] Criterion 1 (e.g. Unit tests cover X)
-- [ ] Criterion 2 (e.g. Integration with Y works)
-- [ ] Verified by `goal-verifier` skill
-
-## Scope & Constraints
-- What is explicitly OUT of scope?
-- Are there budget limits (see `goal-budget.md`)?
-- Are there technical constraints?
-
-## Context
-Include links to issues, design docs, or relevant slack threads.
-
----
-*Generated by loop-init / goal-init*
diff --git a/.test-manual/goal-budget.md b/.test-manual/goal-budget.md
deleted file mode 100644
index 9ef066f..0000000
--- a/.test-manual/goal-budget.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Goal Budget
-
-> Bound the execution of a goal to prevent runaway agents.
-
-## Limits
-
-- **Maximum total tokens:** 1,000,000
-- **Maximum API calls:** 200
-- **Maximum duration:** 24 hours
-
-## Exceedance Policy
-If the budget is exceeded, the agent MUST:
-1. Halt execution.
-2. Update `GOAL.md` status to BLOCKED.
-3. Append a failure note to `goal-run-log.md`.
-4. Await human intervention.
diff --git a/.test-manual/goal-run-log.md b/.test-manual/goal-run-log.md
deleted file mode 100644
index b35f8d5..0000000
--- a/.test-manual/goal-run-log.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Loop Run Log — YOUR_PROJECT
-
-Append one entry per run. Prune entries older than 30 days.
-
-## Format
-
-```json
-{
- "run_id": "2026-06-09T08:15:00Z",
- "pattern": "daily-triage",
- "duration_s": 45,
- "items_found": 4,
- "actions_taken": 1,
- "escalations": 0,
- "tokens_estimate": 52000,
- "outcome": "report-only | fix-proposed | escalated | no-op"
-}
-```
-
-## Recent Runs
-
-<!-- Loop appends below this line -->
\ No newline at end of file
diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md
deleted file mode 100644
index 95916de..0000000
--- a/PR_DESCRIPTION.md
+++ /dev/null
@@ -1,31 +0,0 @@
-## Summary
-Replaces exact string matching for error signatures with a highly robust **Character Trigram Jaccard Similarity** algorithm in `loop-context`, ensuring the circuit breaker trips on semantically-similar failures even if the phrasing or wording morphs slightly across iterations.
-
-## Changes
-- [ ] New pattern or starter (followed `templates/pattern-template.md` + updated `registry.yaml`)
-- [ ] Doc / example improvement
-- [x] Tool change (`loop-context`)
-- [ ] Story (includes real failure or surprise + lesson)
-
-## Checklist (from CONTRIBUTING)
-- [ ] All required sections present for patterns
-- [ ] Links work from README, patterns/README, starters/README, docs/index
-- [x] No secrets, tokens, internal company URLs
-- [ ] `STATE.md*` examples use `.example` suffix
-- [ ] Safety-related content references `docs/safety.md`
-- [x] Ran `node tools/loop-audit/dist/cli.js .` (or on the starter) and addressed findings
-
-## Testing / Dogfood
-- [x] `loop-audit` passes on affected starters or this repo (Scored 100/100 L3)
-- [x] Manual review of generated state / skill output (Fully tested with `npm run test` inside `tools/loop-context` - all 49 edge-case and algorithm tests pass cleanly).
-
-## Screenshots / Examples (if UI or command output)
-**Running loop-context on slightly morphed failures:**
-```bash
-$ loop-context --check --stagnation 3 --similarity-threshold 0.85 < run.json
-ESCALATE [stagnation] — Same error repeated 3× in a row (threshold 3): "Error: connection timeout on port #". Escalating instead of retrying.
-```
-
----
-
-*This template enforces the high bar this reference is known for.*
diff --git a/scratch.js b/scratch.js
deleted file mode 100644
index 53210bd..0000000
--- a/scratch.js
+++ /dev/null
@@ -1,35 +0,0 @@
-import { errorSignature } from './tools/loop-context/dist/context-manager.js';
-
-function getTrigrams(str) {
- const trigrams = new Set();
- const padded = ` ${str.toLowerCase()} `;
- for (let i = 0; i < padded.length - 2; i++) {
- trigrams.add(padded.substring(i, i + 3));
- }
- return trigrams;
-}
-
-function calculateSimilarity(a, b) {
- if (a === b) return 1.0;
- const setA = getTrigrams(a);
- const setB = getTrigrams(b);
- if (setA.size === 0 && setB.size === 0) return 1.0;
- if (setA.size === 0 || setB.size === 0) return 0.0;
-
- let intersection = 0;
- for (const item of setA) {
- if (setB.has(item)) intersection++;
- }
- const union = setA.size + setB.size - intersection;
- return intersection / union;
-}
-
-const e1 = errorSignature('Error: timeout on port 8080');
-const e2 = errorSignature('Error: timed out waiting for 8080');
-const e3 = errorSignature('Error: connection timeout on port 8080');
-console.log('e1:', e1);
-console.log('e2:', e2);
-console.log('e3:', e3);
-console.log('e1 vs e2:', calculateSimilarity(e1, e2));
-console.log('e1 vs e3:', calculateSimilarity(e1, e3));
-console.log('e2 vs e3:', calculateSimilarity(e2, e3));
diff --git a/tools/loop-context/dist/cli.js b/tools/loop-context/dist/cli.js
index 6eada01..03b0c54 100755
--- a/tools/loop-context/dist/cli.js
+++ b/tools/loop-context/dist/cli.js
@@ -15,16 +15,6 @@ function parsePositiveIntFlag(raw, flag) {
}
return n;
}
-function parsePositiveFloatFlag(raw, flag) {
- if (raw === undefined || raw === '') {
- throw new Error(`${flag} requires a positive number value.`);
- }
- const n = Number(raw);
- if (Number.isNaN(n) || n <= 0) {
- throw new Error(`${flag} must be a positive number; got "${raw}".`);
- }
- return n;
-}
function parseArgs(argv) {
const breaker = { ...DEFAULT_BREAKER };
const prune = { ...DEFAULT_PRUNE };
@@ -90,11 +80,6 @@ function parseArgs(argv) {
prune.window = parsePositiveIntFlag(argv[++i], '--window');
else if (a === '--max-trace-lines')
prune.maxTraceLines = parsePositiveIntFlag(argv[++i], '--max-trace-lines');
- else if (a === '--similarity-threshold') {
- const val = parsePositiveFloatFlag(argv[++i], '--similarity-threshold');
- breaker.similarityThreshold = val;
- prune.similarityThreshold = val;
- }
}
return { help: false, ledger, ...base() };
}
@@ -165,7 +150,6 @@ Options:
--on-exceed <script> On escalate, pipe the decision as JSON to this
script's stdin (fire-and-forget; its exit code
is not checked and does not change --check's own).
- --similarity-threshold <f> Float 0.0-1.0 to cluster similar errors (default: ${DEFAULT_BREAKER.similarityThreshold})
--window <n> Attempts kept when pruning (default: ${DEFAULT_PRUNE.window})
--max-trace-lines <n> Stack-trace lines kept (default: ${DEFAULT_PRUNE.maxTraceLines})
-h, --help This help
diff --git a/tools/loop-context/dist/context-manager.d.ts b/tools/loop-context/dist/context-manager.d.ts
index 7bed4e9..39c69e3 100644
--- a/tools/loop-context/dist/context-manager.d.ts
+++ b/tools/loop-context/dist/context-manager.d.ts
@@ -49,16 +49,12 @@ export interface CircuitBreakerConfig {
noProgressThreshold: number;
/** Optional hard cap on cumulative tokens across the run. */
tokenBudget?: number;
- /** Float 0.0-1.0. If consecutive errors are this similar, they count as stagnant. */
- similarityThreshold: number;
}
export interface PruneConfig {
/** Max lines to keep from any single stack trace. */
maxTraceLines: number;
/** Number of most-recent attempts to retain in the pruned ledger. */
window: number;
- /** Float 0.0-1.0. If consecutive errors are this similar, they are collapsed. */
- similarityThreshold: number;
}
export declare const DEFAULT_BREAKER: CircuitBreakerConfig;
export declare const DEFAULT_PRUNE: PruneConfig;
@@ -68,7 +64,6 @@ export declare const DEFAULT_PRUNE: PruneConfig;
* (line numbers, addresses, timestamps, ports, temp paths) differ.
*/
export declare function errorSignature(error: string): string;
-export declare function calculateSimilarity(a: string, b: string): number;
export type BreakerTrigger = 'ok' | 'stagnation' | 'no-progress' | 'token-budget' | 'daily-budget' | 'max-iterations';
export interface BreakerDecision {
/** Whether the loop is cleared to run another iteration. */
@@ -115,7 +110,7 @@ export interface AttemptSummary {
actionsTried: string[];
}
/** Deterministic factual rollup of the whole run — no LLM required. */
-export declare function summarizeAttempts(ledger: Ledger, similarityThreshold?: number): AttemptSummary;
+export declare function summarizeAttempts(ledger: Ledger): AttemptSummary;
/**
* Build the compact context block to prepend to the next prompt. Contains only
* what the agent needs to make progress: the goal, what has already been tried
diff --git a/tools/loop-context/dist/context-manager.js b/tools/loop-context/dist/context-manager.js
index a927884..a229f70 100644
--- a/tools/loop-context/dist/context-manager.js
+++ b/tools/loop-context/dist/context-manager.js
@@ -19,12 +19,10 @@ export const DEFAULT_BREAKER = {
maxIterations: 10,
stagnationThreshold: 3,
noProgressThreshold: 5,
- similarityThreshold: 0.85,
};
export const DEFAULT_PRUNE = {
maxTraceLines: 8,
window: 5,
- similarityThreshold: 0.85,
};
// ── Error normalization ────────────────────────────────────────────
/**
@@ -47,35 +45,6 @@ export function errorSignature(error) {
.replace(/\s+/g, ' ')
.trim();
}
-/**
- * Calculate Jaccard similarity (0.0 to 1.0) using character trigrams.
- * Highly robust to minor phrasing variations.
- */
-function getTrigrams(str) {
- const trigrams = new Set();
- const padded = ` ${str.toLowerCase()} `;
- for (let i = 0; i < padded.length - 2; i++) {
- trigrams.add(padded.substring(i, i + 3));
- }
- return trigrams;
-}
-export function calculateSimilarity(a, b) {
- if (a === b)
- return 1.0;
- const setA = getTrigrams(a);
- const setB = getTrigrams(b);
- if (setA.size === 0 && setB.size === 0)
- return 1.0;
- if (setA.size === 0 || setB.size === 0)
- return 0.0;
- let intersection = 0;
- for (const item of setA) {
- if (setB.has(item))
- intersection++;
- }
- const union = setA.size + setB.size - intersection;
- return intersection / union;
-}
function totalTokens(ledger) {
return ledger.attempts.reduce((sum, a) => sum + (a.tokensUsed ?? 0), 0);
}
@@ -105,8 +74,7 @@ export function checkCircuitBreaker(ledger, config = DEFAULT_BREAKER) {
const lastSig = errorSignature(failRun[failRun.length - 1].error ?? '');
let same = 0;
for (let i = failRun.length - 1; i >= 0; i--) {
- const curSig = errorSignature(failRun[i].error ?? '');
- if (calculateSimilarity(curSig, lastSig) >= config.similarityThreshold)
+ if (errorSignature(failRun[i].error ?? '') === lastSig)
same++;
else
break;
@@ -189,7 +157,7 @@ export function pruneLedger(ledger, config = DEFAULT_PRUNE) {
const sameFailure = prev !== undefined &&
prev.outcome === 'failure' &&
pruned.outcome === 'failure' &&
- calculateSimilarity(errorSignature(prev.error ?? ''), errorSignature(pruned.error ?? '')) >= config.similarityThreshold;
+ errorSignature(prev.error ?? '') === errorSignature(pruned.error ?? '');
if (sameFailure) {
prev.repeated = (prev.repeated ?? 1) + 1;
prev.iteration = pruned.iteration; // advance to the latest iteration
@@ -201,7 +169,7 @@ export function pruneLedger(ledger, config = DEFAULT_PRUNE) {
return { goal: ledger.goal, startedAt: ledger.startedAt, attempts: collapsed };
}
/** Deterministic factual rollup of the whole run — no LLM required. */
-export function summarizeAttempts(ledger, similarityThreshold = 0.85) {
+export function summarizeAttempts(ledger) {
const groups = new Map();
const actions = new Set();
let successes = 0;
@@ -217,17 +185,11 @@ export function summarizeAttempts(ledger, similarityThreshold = 0.85) {
failures++;
if (a.error) {
const sig = errorSignature(a.error);
- let found = false;
- for (const existing of groups.values()) {
- if (calculateSimilarity(existing.signature, sig) >= similarityThreshold) {
- existing.count++;
- found = true;
- break;
- }
- }
- if (!found) {
+ const existing = groups.get(sig);
+ if (existing)
+ existing.count++;
+ else
groups.set(sig, { signature: sig, count: 1, sample: a.error.split('\n')[0].trim() });
- }
}
}
}
@@ -248,7 +210,7 @@ export function summarizeAttempts(ledger, similarityThreshold = 0.85) {
* (so it does not repeat itself), the last pruned error, and the breaker status.
*/
export function buildContextInjection(ledger, breaker = DEFAULT_BREAKER, prune = DEFAULT_PRUNE) {
- const summary = summarizeAttempts(ledger, breaker.similarityThreshold);
+ const summary = summarizeAttempts(ledger);
const decision = checkCircuitBreaker(ledger, breaker);
const pruned = pruneLedger(ledger, prune);
const lines = [];
diff --git a/tools/mcp-server/dist/index.js b/tools/mcp-server/dist/index.js
index 4fcaf1b..e79e04c 100755
--- a/tools/mcp-server/dist/index.js
+++ b/tools/mcp-server/dist/index.js
@@ -294,9 +294,9 @@ server.tool('loop_estimate_cost', 'Estimate daily token cost for a pattern at a
}
const { cost } = pattern;
const mix = level === 'L1'
- ? { noop: 0.6, report: 0.4, action: 0 }
+ ? { noop: 0.7, report: 0.3, action: 0 }
: level === 'L2'
- ? { noop: 0.5, report: 0.3, action: 0.2 }
+ ? { noop: 0.6, report: 0.25, action: 0.15 }
: { noop: 0.4, report: 0.35, action: 0.25 };
const realisticPerRun = cost.tokens_noop * mix.noop
+ cost.tokens_report * mix.report