@cobusgreyling/loop-init 1.3.2 → 1.4.0

package/README.md

@@ -4,6 +4,8 @@ Scaffold loop engineering starters into your project by pattern and tool.
 
 **npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok** works immediately.
 
+See [docs/loop-init-validation.md](../../docs/loop-init-validation.md) for a validated pattern × --tool matrix.
+
 ## Install & Run
 
 ```bash
@@ -31,6 +33,17 @@ After scaffolding, always run `npx @cobusgreyling/loop-audit . --suggest` and ac
 
 L2 patterns (`ci-sweeper`, `dependency-sweeper`) also copy `minimal-fix` and `loop-verifier` templates when missing from the starter.
 
+Fix-capable patterns (`pr-babysitter`, `ci-sweeper`, `dependency-sweeper`, `post-merge-cleanup`) also get a **circuit breaker**:
+
+- `loop-guard` skill — logs each attempt to `loop-ledger.json` and runs [`loop-context`](../loop-context) `--check` before retrying
+- `loop-ledger.json` — seeded with the pattern's goal, its `pattern`/`level`, and an empty `attempts` array
+
+The ledger's `pattern`/`level` let `loop-guard` size the breaker's `--token-budget` from [`loop-cost`](../loop-cost)'s realistic per-run estimate instead of a hand-typed number. The breaker escalates (same error N× in a row, too many consecutive failures, token budget, or iteration cap) instead of looping in vain. Report-only patterns skip it.
+
+Patterns that act on human-authored, often underspecified input (`issue-triage`) also get an **intake** skill:
+
+- `loop-intake` skill — when a work item is too vague to verify "done", it asks one question at a time, pushes for exact values, and writes an open question + `needs-human` escalation instead of guessing. Clarifying up front keeps the loop from burning fix attempts on a goal that was never well defined.
+
 Every scaffold also creates:
 
 - `loop-budget.md` — pattern-specific daily caps and kill switch

package/dist/cli.js

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process';
 import { cp, mkdir, readFile, writeFile, access } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { printContributorCta } from './contributor-cta.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const MONOREPO_STARTERS = path.resolve(PACKAGE_ROOT, '../../starters');
@@ -29,6 +30,12 @@ const PATTERNS_NEEDING_FIX = new Set([
     'dependency-sweeper',
     'post-merge-cleanup',
 ]);
+/**
+ * Patterns that act on human-authored, often underspecified input (issues).
+ * They get the loop-intake skill so the loop clarifies a vague item or escalates
+ * it instead of guessing and burning fix attempts.
+ */
+const PATTERNS_NEEDING_INTAKE = new Set(['issue-triage']);
 const STATE_FILES = {
     'daily-triage': 'STATE.md',
     'pr-babysitter': 'pr-babysitter-state.md',
@@ -142,6 +149,62 @@ async function copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun)
         await copyTemplateVerifier(templatesRoot, targetDir, tool, dryRun);
     }
 }
+/** Per-pattern goal seeded into loop-ledger.json for the circuit breaker. */
+const LEDGER_GOAL = {
+    'daily-triage': 'Keep the repo healthy and STATE.md current',
+    'pr-babysitter': 'Get the watched PR review-ready and green',
+    'ci-sweeper': 'Get failing CI back to green',
+    'dependency-sweeper': 'Land safe dependency updates',
+    'post-merge-cleanup': 'Clean up regressions from recent merges',
+    'changelog-drafter': 'Draft accurate release notes',
+    'issue-triage': 'Triage the open issue queue',
+};
+/**
+ * Readiness level seeded into loop-ledger.json so the loop-guard skill can
+ * resolve a realistic per-run token budget from `loop-cost --json` instead of a
+ * hand-typed number. Fix-capable loops draft changes with a verifier (a human
+ * still merges), so L2 is the right default; tune it in the ledger if a loop
+ * runs unattended (L3) or report-only (L1).
+ */
+const LEDGER_LEVEL = {
+    'daily-triage': 'L1',
+    'pr-babysitter': 'L2',
+    'ci-sweeper': 'L2',
+    'dependency-sweeper': 'L2',
+    'post-merge-cleanup': 'L2',
+    'changelog-drafter': 'L1',
+    'issue-triage': 'L1',
+};
+/**
+ * Fix-capable loops retry actions, so they need a circuit breaker: scaffold the
+ * loop-guard skill plus a seeded loop-ledger.json wired to `loop-context`.
+ * Report-only patterns (daily-triage, issue-triage, changelog-drafter) don't
+ * retry fixes, so they skip this to keep the scaffold minimal.
+ */
+async function scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun) {
+    if (!PATTERNS_NEEDING_FIX.has(pattern))
+        return;
+    await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-guard', targetDir, tool, 'loop-guard', dryRun);
+    const ledgerPath = path.join(targetDir, 'loop-ledger.json');
+    if (await exists(ledgerPath))
+        return;
+    const seed = `${JSON.stringify({ goal: LEDGER_GOAL[pattern], pattern, level: LEDGER_LEVEL[pattern], attempts: [] }, null, 2)}\n`;
+    if (dryRun) {
+        console.log(`  would write: ${ledgerPath}`);
+        return;
+    }
+    await writeFile(ledgerPath, seed);
+    console.log('  created: loop-ledger.json (circuit breaker)');
+}
+/**
+ * Scaffold the loop-intake skill for patterns that receive ambiguous human
+ * input, so the loop sharpens the goal (or escalates) before acting on it.
+ */
+async function scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun) {
+    if (!PATTERNS_NEEDING_INTAKE.has(pattern))
+        return;
+    await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-intake', targetDir, tool, 'loop-intake', dryRun);
+}
 function formatTokenCap(n) {
     if (n >= 1_000_000)
         return `${n / 1_000_000}M`;
@@ -442,7 +505,9 @@ Examples:
         await copyFile(loopMd, path.join(targetDir, 'LOOP.md'), dryRun);
     }
     await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);
+    await scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun);
     await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);
+    await scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun);
     await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);
     if (tool !== 'opencode' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {
         const agentsTemplate = `# AGENTS.md
@@ -475,12 +540,21 @@ npm run lint
             console.log(`  npx @cobusgreyling/loop-audit ${auditArg} --suggest`);
         }
     }
+    if (PATTERNS_NEEDING_FIX.has(pattern)) {
+        console.log('');
+        console.log('Circuit breaker wired (loop-guard skill + loop-ledger.json):');
+        console.log('  npx @cobusgreyling/loop-context --check --ledger loop-ledger.json');
+    }
+    if (PATTERNS_NEEDING_INTAKE.has(pattern)) {
+        console.log('');
+        console.log('Intake wired (loop-intake skill): clarify a vague item or escalate before acting.');
+    }
     console.log('');
     console.log(`First loop (${tool}):`);
     console.log(`  ${firstLoopCommand(pattern, tool)}`);
     console.log('');
     console.log(`Estimate cost: npx @cobusgreyling/loop-cost --pattern ${pattern} --level L1`);
-    console.log('');
+    printContributorCta();
 }
 async function readDirNames(dir) {
     const { readdir } = await import('node:fs/promises');

package/dist/contributor-cta.d.ts

@@ -0,0 +1,2 @@
+export declare const CONTRIBUTOR_QUICKSTART_URL = "https://github.com/cobusgreyling/loop-engineering/discussions/123";
+export declare function printContributorCta(): void;

package/dist/contributor-cta.js

@@ -0,0 +1,6 @@
+export const CONTRIBUTOR_QUICKSTART_URL = 'https://github.com/cobusgreyling/loop-engineering/discussions/123';
+export function printContributorCta() {
+    console.log('');
+    console.log('Contribute (~15 min tasks):');
+    console.log(`  ${CONTRIBUTOR_QUICKSTART_URL}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cobusgreyling/loop-init",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Scaffold loop engineering patterns and starters into any project. Supports Grok, Claude Code, Codex, Opencode and more. npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode",
   "type": "module",
   "bin": {

package/templates/SKILL.md.loop-guard

@@ -0,0 +1,92 @@
+---
+name: loop-guard
+description: >
+  Circuit breaker for fix-capable loops. Before each iteration, append the last
+  attempt to loop-ledger.json and run loop-context --check; if it escalates,
+  stop and hand the human a clean summary instead of looping in vain.
+user_invocable: true
+---
+
+# Loop Guard (Circuit Breaker)
+
+You keep a fix loop from burning tokens on a problem it cannot solve. You wrap
+every iteration of an action skill (`minimal-fix`, `ci-triage`, `dependency-triage`, …)
+with a deterministic circuit-breaker check powered by
+[`loop-context`](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-context).
+
+The breaker needs no LLM call, so it is cheap enough to run on every iteration.
+
+## The ledger
+
+`loop-ledger.json` records the loop's goal, its pattern/level, and one entry per
+attempt:
+
+```json
+{ "goal": "Get failing CI green", "pattern": "ci-sweeper", "level": "L2", "attempts": [] }
+```
+
+`pattern` and `level` are seeded by `loop-init`; the breaker ignores them but the
+budget step below reads them to size `--token-budget` from real cost data.
+
+After every iteration, append what you just tried:
+
+```json
+{ "iteration": 3, "action": "patch flaky auth test", "outcome": "failure",
+  "error": "AssertionError: expected 200 got 500", "tokensUsed": 1800 }
+```
+
+`outcome` is `success | failure | noop`. Always include `error` on failures —
+that is how the breaker detects a repeated (stagnant) failure.
+
+## Size the token budget from the pattern
+
+Don't hand-type a token cap — `loop-context` can derive it directly from the
+pattern's realistic per-run cost
+([`loop-cost`](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-cost)
+computes this from `patterns/registry.yaml`) so the breaker trips on genuine
+cost blowup, not a made-up number. Substitute the ledger's own `pattern`/`level`
+(here: `ci-sweeper` / `L2`):
+
+```bash
+npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \
+  --budget-from-pattern ci-sweeper --budget-level L2
+```
+
+## Before each iteration
+
+1. Append the previous attempt to `loop-ledger.json`.
+2. Run the breaker with the resolved budget:
+   ```bash
+   npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \
+     --budget-from-pattern ci-sweeper --budget-level L2
+   ```
+3. Act on the exit code:
+   - **0** → continue. Optionally trim the next prompt first:
+     `npx @cobusgreyling/loop-context --inject --ledger loop-ledger.json`
+   - **2** → **STOP.** The breaker tripped — same error N× in a row, too many
+     consecutive failures, the token budget, or the iteration cap. Do not retry.
+
+## On escalate (exit 2)
+
+1. Capture a clean, pruned summary for the human:
+   ```bash
+   npx @cobusgreyling/loop-context --inject --ledger loop-ledger.json > escalation.md
+   ```
+2. Write the escalation into STATE.md High Priority (or open an issue).
+3. Exit the loop. A human decides the next step.
+
+## Rules
+
+- Never widen thresholds just to keep looping — escalation is a feature, not a failure.
+- Never edit the ledger to hide a repeated error; the breaker exists to catch it.
+- Defaults: 3× same error, 5 consecutive failures, 10 iterations. Tune with
+  `--stagnation`, `--no-progress`, `--max-iterations`, or an explicit
+  `--token-budget` (wins over `--budget-from-pattern` if both are given).
+
+## Interaction with other skills
+
+- `minimal-fix` / `ci-triage` — record each attempt's outcome + error in the ledger.
+- `loop-verifier` — a verifier rejection is a `failure`; log it so repeats trip the breaker.
+- `loop-constraints` — honors "escalate after N attempts"; this skill makes it mechanical.
+- `loop-budget` — the per-run budget here comes from `--budget-from-pattern`;
+  loop-budget.md still governs the *daily* cap across runs.

package/templates/SKILL.md.loop-intake

@@ -0,0 +1,71 @@
+---
+name: loop-intake
+description: >
+  Clarify an ambiguous goal or work item BEFORE the loop acts on it. Runs at the
+  front of a run when the assigned task is underspecified. Ask one question at a
+  time, push for exact values, and escalate instead of guessing.
+user_invocable: true
+---
+
+# Loop Intake - Clarify Before You Act
+
+Autonomous loops waste attempts (and budget) when they guess at a vague goal.
+This skill runs FIRST, before triage or any action skill, whenever the item the
+loop is about to work on is not specific enough to verify "done".
+
+## When to run
+
+Run intake when the goal or work item is missing any of:
+
+- a single, testable definition of done
+- the exact scope (which repo / branch / paths / tickets)
+- concrete values a fix would depend on (error text, thresholds, versions)
+
+If the goal is already specific and verifiable, skip intake and proceed.
+
+## How to clarify (one question at a time)
+
+1. Read the current state file and the item (issue, PR, request) in full. Do NOT
+   re-ask anything already answered there.
+2. Ask the SINGLE most decision-blocking question. Wait for the answer.
+3. Push for an exact value. "It should be fast" becomes "What p95 latency, in
+   ms?". "Add a limit" becomes "How many per minute?". Re-ask once if the answer
+   is still vague.
+4. Stop as soon as the goal is verifiable. Do not interrogate for its own sake.
+
+Ask in behavior terms, not implementation: what the system must do, what the user
+sees, which values matter. Not: which function, table, or endpoint.
+
+## When an answer stays vague
+
+Do not guess. Record it and move on:
+
+- Write the gap as an open question in the state file: `- [ ] OQ: <question>`.
+- Mark the item `needs-human` (escalate per the loop's handoff rule).
+- If NO blocking question can be resolved, escalate the whole item and stop.
+  Acting on a guess burns attempts the circuit breaker should not have to catch.
+
+## Output
+
+Append a short, sharpened goal to the state file (or the item):
+
+```
+Goal (clarified): <one testable sentence>
+Done when: <verifiable condition>
+Open questions: <N> (needs-human) - <list>
+```
+
+Hand back to triage or the action skill only if "Done when" is now verifiable.
+
+## Interaction with other skills
+
+- Runs BEFORE `loop-triage` / `issue-triage` and any action skill.
+- Feeds `loop-verifier`: the "Done when" line becomes the verifier's check.
+- Pairs with `loop-guard` (circuit breaker): intake prevents wasted attempts on a
+  goal that was never well defined; the breaker catches the ones that slip through.
+- Respects `loop-constraints`: never ask for, or act on, denylisted scope.
+
+## Default behavior
+
+Report-only in week one: propose the clarified goal and open questions, but let a
+human confirm before the loop acts on the sharpened goal.

package/templates/loop-constraints.md

@@ -18,6 +18,7 @@
 - Never disable tests to make CI green
 - Never refactor unrelated code — one fix per run
 - Max 3 fix attempts per item; escalate after
+- Enforce the attempt limit mechanically: log each try to `loop-ledger.json` and run `loop-context --check` before retrying (see the `loop-guard` skill)
 
 ## Communication
 - Always tell me what you're about to do before doing it