@cobusgreyling/loop-cost 1.0.0

package/README.md

@@ -0,0 +1,44 @@
+# loop-cost
+
+Estimate daily token spend for [loop engineering](https://github.com/cobusgreyling/loop-engineering) patterns by cadence and readiness level (L1–L3).
+
+Uses cost metadata from `patterns/registry.yaml`.
+
+## Install & Run
+
+```bash
+npx @cobusgreyling/loop-cost --pattern ci-sweeper --cadence 15m --level L2
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --json
+npx @cobusgreyling/loop-cost --list
+```
+
+**From this repo:**
+
+```bash
+cd tools/loop-cost
+npm install
+npm test
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--pattern` | Pattern id (see `--list`) |
+| `--cadence` | Override cadence (e.g. `15m`, `1d`) |
+| `--level` | `L1`, `L2`, or `L3` (default `L1`) |
+| `--conservative` | Use slower cadence from ranges |
+| `--json` | Machine-readable output |
+
+## Scenarios
+
+Each estimate includes:
+
+- **Early-exit / no-op** — empty watchlist, minimal tokens
+- **Full triage** — every run does a full scan
+- **Action every run** — implementer + verifier every time (worst case)
+- **Realistic blend** — level-based mix (documented in output)
+
+Pair with `loop-budget.md` (scaffolded by `loop-init`) and `loop-audit` cost observability checks.
+
+See [docs/operating-loops.md](../../docs/operating-loops.md).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { readFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'yaml';
+import { estimateCost, formatEstimateHuman, } from './estimator.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+function parseArgs(argv) {
+    let pattern = 'daily-triage';
+    let cadence;
+    let level = 'L1';
+    let conservative = false;
+    let json = false;
+    let list = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--pattern' || a === '-p')
+            pattern = argv[++i];
+        else if (a === '--cadence' || a === '-c')
+            cadence = argv[++i];
+        else if (a === '--level' || a === '-l')
+            level = argv[++i];
+        else if (a === '--conservative')
+            conservative = true;
+        else if (a === '--json')
+            json = true;
+        else if (a === '--list')
+            list = true;
+        else if (a === '--help' || a === '-h')
+            return { help: true };
+    }
+    return { help: false, pattern, cadence, level, conservative, json, list };
+}
+async function loadRegistry() {
+    const candidates = [
+        path.join(PACKAGE_ROOT, 'registry.json'),
+        path.resolve(PACKAGE_ROOT, '../../patterns/registry.yaml'),
+    ];
+    for (const p of candidates) {
+        try {
+            await access(p);
+            const raw = await readFile(p, 'utf8');
+            if (p.endsWith('.json'))
+                return JSON.parse(raw);
+            return yaml.parse(raw);
+        }
+        catch {
+            /* try next */
+        }
+    }
+    throw new Error('Pattern registry not found. Run from loop-engineering repo or install @cobusgreyling/loop-cost.');
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        console.log(`loop-cost — estimate daily token spend for loop patterns
+
+Usage:
+  loop-cost --pattern <id> [options]
+
+Options:
+  -p, --pattern <id>     Pattern id (default: daily-triage)
+  -c, --cadence <spec>   Override cadence (e.g. 15m, 1d, 5m-15m)
+  -l, --level <L1|L2|L3> Readiness level (default: L1)
+  --conservative         Use slower cadence from ranges (e.g. 15m not 5m)
+  --json                 Machine-readable output
+  --list                 List pattern ids
+  -h, --help             This help
+
+Examples:
+  loop-cost --pattern ci-sweeper --cadence 15m --level L2
+  loop-cost --pattern daily-triage --level L1 --json
+  loop-cost --list
+`);
+        process.exit(0);
+    }
+    const registry = await loadRegistry();
+    if (args.list) {
+        for (const p of registry.patterns) {
+            console.log(`${p.id}\t${p.token_cost}\t${p.cadence}`);
+        }
+        return;
+    }
+    const pattern = registry.patterns.find((p) => p.id === args.pattern);
+    if (!pattern) {
+        console.error(`Unknown pattern: ${args.pattern}. Use --list for ids.`);
+        process.exit(1);
+    }
+    if (!pattern.cost) {
+        console.error(`Pattern ${args.pattern} has no cost block in registry.`);
+        process.exit(1);
+    }
+    const result = estimateCost({
+        pattern,
+        cadence: args.cadence,
+        level: args.level,
+        conservative: args.conservative,
+    });
+    if (args.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatEstimateHuman(result));
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error('loop-cost failed:', msg);
+    process.exit(1);
+});

package/dist/estimator.d.ts

@@ -0,0 +1,64 @@
+export type ReadinessLevel = 'L1' | 'L2' | 'L3';
+export interface PatternCost {
+    tokens_noop: number;
+    tokens_report: number;
+    tokens_action: number;
+    suggested_daily_cap: number;
+    early_exit_required: boolean;
+}
+export interface RegistryPattern {
+    id: string;
+    name: string;
+    cadence: string;
+    token_cost: string;
+    cost: PatternCost;
+}
+export interface RegistryDoc {
+    patterns: RegistryPattern[];
+}
+export interface EstimateInput {
+    pattern: RegistryPattern;
+    cadence?: string;
+    level: ReadinessLevel;
+    conservative?: boolean;
+}
+export interface EstimateResult {
+    patternId: string;
+    patternName: string;
+    cadence: string;
+    level: ReadinessLevel;
+    runsPerDay: number;
+    tokenCostTier: string;
+    suggestedDailyCap: number;
+    earlyExitRequired: boolean;
+    scenarios: {
+        noop: {
+            tokensPerRun: number;
+            tokensPerDay: number;
+        };
+        report: {
+            tokensPerRun: number;
+            tokensPerDay: number;
+        };
+        action: {
+            tokensPerRun: number;
+            tokensPerDay: number;
+        };
+        realistic: {
+            tokensPerRun: number;
+            tokensPerDay: number;
+            assumptions: string;
+        };
+    };
+    warnings: string[];
+}
+export declare function parseInterval(token: string): number;
+/** Runs per day for a single interval like 15m or 1d. */
+export declare function runsPerDayForInterval(interval: string): number;
+/**
+ * Parse pattern cadence (e.g. 5m-15m, 1d-2h) into runs/day.
+ * conservative=true picks the slower cadence in a range.
+ */
+export declare function cadenceToRunsPerDay(cadence: string, conservative?: boolean): number;
+export declare function estimateCost(input: EstimateInput): EstimateResult;
+export declare function formatEstimateHuman(r: EstimateResult): string;

package/dist/estimator.js

@@ -0,0 +1,135 @@
+const INTERVAL_MS = {
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+export function parseInterval(token) {
+    const m = token.match(/^(\d+)([mhd])$/);
+    if (!m)
+        throw new Error(`Invalid cadence interval: ${token}`);
+    const unit = m[2];
+    return Number(m[1]) * INTERVAL_MS[unit];
+}
+/** Runs per day for a single interval like 15m or 1d. */
+export function runsPerDayForInterval(interval) {
+    const ms = parseInterval(interval);
+    return Math.floor(86_400_000 / ms);
+}
+/**
+ * Parse pattern cadence (e.g. 5m-15m, 1d-2h) into runs/day.
+ * conservative=true picks the slower cadence in a range.
+ */
+export function cadenceToRunsPerDay(cadence, conservative = false) {
+    const parts = cadence.split('-').map((p) => p.trim());
+    if (parts.length === 1)
+        return runsPerDayForInterval(parts[0]);
+    const runs = parts.map(runsPerDayForInterval);
+    return conservative ? Math.min(...runs) : Math.max(...runs);
+}
+function realisticMix(level, earlyExitRequired) {
+    if (level === 'L1') {
+        return {
+            noop: earlyExitRequired ? 0.9 : 0.6,
+            report: earlyExitRequired ? 0.1 : 0.4,
+            action: 0,
+            assumptions: earlyExitRequired
+                ? 'L1: 90% early-exit, 10% full triage'
+                : 'L1: 60% no-op, 40% full triage',
+        };
+    }
+    if (level === 'L2') {
+        return {
+            noop: earlyExitRequired ? 0.85 : 0.5,
+            report: earlyExitRequired ? 0.1 : 0.3,
+            action: earlyExitRequired ? 0.05 : 0.2,
+            assumptions: earlyExitRequired
+                ? 'L2: 85% early-exit, 10% triage, 5% implementer+verifier'
+                : 'L2: 50% no-op, 30% triage, 20% action',
+        };
+    }
+    return {
+        noop: 0.4,
+        report: 0.35,
+        action: 0.25,
+        assumptions: 'L3: 40% no-op, 35% triage, 25% action (unattended — monitor closely)',
+    };
+}
+function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${Math.round(n / 1_000)}k`;
+    return String(n);
+}
+export function estimateCost(input) {
+    const cadence = input.cadence ?? input.pattern.cadence;
+    const runsPerDay = cadenceToRunsPerDay(cadence, input.conservative);
+    const { cost, token_cost: tokenCostTier } = input.pattern;
+    const mix = realisticMix(input.level, cost.early_exit_required);
+    const noopDay = cost.tokens_noop * runsPerDay;
+    const reportDay = cost.tokens_report * runsPerDay;
+    const actionDay = cost.tokens_action * runsPerDay;
+    const realisticPerRun = cost.tokens_noop * mix.noop +
+        cost.tokens_report * mix.report +
+        cost.tokens_action * mix.action;
+    const realisticDay = Math.round(realisticPerRun * runsPerDay);
+    const warnings = [];
+    if (cost.early_exit_required) {
+        warnings.push('Early-exit triage is required — empty watchlist should exit in <5k tokens.');
+    }
+    if (actionDay > cost.suggested_daily_cap) {
+        warnings.push(`Worst case (action every run) exceeds suggested cap (${formatTokens(cost.suggested_daily_cap)}/day).`);
+    }
+    if (realisticDay > cost.suggested_daily_cap) {
+        warnings.push(`Realistic estimate exceeds suggested daily cap — slow cadence or tighten scope.`);
+    }
+    if (runsPerDay >= 96) {
+        warnings.push(`High cadence (${runsPerDay} runs/day) — verify early-exit is working.`);
+    }
+    return {
+        patternId: input.pattern.id,
+        patternName: input.pattern.name,
+        cadence,
+        level: input.level,
+        runsPerDay,
+        tokenCostTier,
+        suggestedDailyCap: cost.suggested_daily_cap,
+        earlyExitRequired: cost.early_exit_required,
+        scenarios: {
+            noop: { tokensPerRun: cost.tokens_noop, tokensPerDay: noopDay },
+            report: { tokensPerRun: cost.tokens_report, tokensPerDay: reportDay },
+            action: { tokensPerRun: cost.tokens_action, tokensPerDay: actionDay },
+            realistic: {
+                tokensPerRun: Math.round(realisticPerRun),
+                tokensPerDay: realisticDay,
+                assumptions: mix.assumptions,
+            },
+        },
+        warnings,
+    };
+}
+export function formatEstimateHuman(r) {
+    const lines = [];
+    lines.push('');
+    lines.push(`Loop Cost Estimate — ${r.patternName} (${r.patternId})`);
+    lines.push('═'.repeat(50));
+    lines.push(`Cadence: ${r.cadence}  →  ${r.runsPerDay} runs/day`);
+    lines.push(`Level: ${r.level}  ·  Registry tier: ${r.tokenCostTier}`);
+    lines.push(`Suggested daily cap: ${formatTokens(r.suggestedDailyCap)} tokens`);
+    lines.push('');
+    lines.push('Daily token estimates:');
+    lines.push(`  Early-exit / no-op:  ${formatTokens(r.scenarios.noop.tokensPerDay)}  (${formatTokens(r.scenarios.noop.tokensPerRun)}/run)`);
+    lines.push(`  Full triage:         ${formatTokens(r.scenarios.report.tokensPerDay)}  (${formatTokens(r.scenarios.report.tokensPerRun)}/run)`);
+    lines.push(`  Action every run:    ${formatTokens(r.scenarios.action.tokensPerDay)}  (${formatTokens(r.scenarios.action.tokensPerRun)}/run)`);
+    lines.push(`  Realistic blend:     ${formatTokens(r.scenarios.realistic.tokensPerDay)}  (${r.scenarios.realistic.assumptions})`);
+    if (r.warnings.length) {
+        lines.push('');
+        lines.push('Warnings:');
+        for (const w of r.warnings)
+            lines.push(`  ! ${w}`);
+    }
+    lines.push('');
+    lines.push('Docs: docs/operating-loops.md · Scaffold: npx @cobusgreyling/loop-init');
+    lines.push('');
+    return lines.join('\n');
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cobusgreyling/loop-cost",
+  "version": "1.0.0",
+  "description": "Estimate daily token spend for loop engineering patterns by cadence and readiness level.",
+  "type": "module",
+  "bin": {
+    "loop-cost": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "registry.json",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle": "node scripts/bundle-registry.mjs",
+    "build": "npm run bundle && tsc",
+    "test": "npm run build && node --test test/estimator.test.mjs",
+    "prepublishOnly": "npm test",
+    "start": "node dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "loop-engineering",
+    "ai-agents",
+    "token-budget",
+    "cost-estimate"
+  ],
+  "author": "Cobus Greyling",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cobusgreyling/loop-engineering.git",
+    "directory": "tools/loop-cost"
+  },
+  "homepage": "https://cobusgreyling.github.io/loop-engineering/",
+  "bugs": {
+    "url": "https://github.com/cobusgreyling/loop-engineering/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/registry.json

@@ -0,0 +1,294 @@
+{
+  "patterns": [
+    {
+      "id": "pr-babysitter",
+      "name": "PR Babysitter",
+      "file": "pr-babysitter.md",
+      "goal": "Shepherd PRs through review, CI, rebase, and merge",
+      "cadence": "5m-15m",
+      "risk": "medium",
+      "tools": [
+        "grok",
+        "claude-code",
+        "codex",
+        "github-actions"
+      ],
+      "skills": [
+        "pr-review-triage",
+        "minimal-fix",
+        "rebase-and-clean"
+      ],
+      "state": "pr-babysitter-state.md",
+      "phases": [
+        "discover",
+        "triage",
+        "fix",
+        "verify",
+        "notify"
+      ],
+      "human_gates": [
+        "security",
+        "payments",
+        "auth",
+        "max-fix-attempts"
+      ],
+      "starter": "starters/pr-babysitter",
+      "week_one_mode": "L1",
+      "token_cost": "high",
+      "cost": {
+        "tokens_noop": 3000,
+        "tokens_report": 80000,
+        "tokens_action": 250000,
+        "suggested_daily_cap": 2000000,
+        "early_exit_required": true
+      }
+    },
+    {
+      "id": "daily-triage",
+      "name": "Daily Triage",
+      "file": "daily-triage.md",
+      "goal": "Prioritized morning scan of CI, issues, commits, and chat",
+      "cadence": "1d-2h",
+      "risk": "low",
+      "tools": [
+        "grok",
+        "claude-code",
+        "codex",
+        "github-actions"
+      ],
+      "skills": [
+        "loop-triage",
+        "minimal-fix"
+      ],
+      "state": "STATE.md",
+      "phases": [
+        "report",
+        "act-small-wins",
+        "escalate"
+      ],
+      "human_gates": [
+        "design-decisions",
+        "multi-file-refactors"
+      ],
+      "starter": "starters/minimal-loop",
+      "week_one_mode": "L1",
+      "token_cost": "low",
+      "cost": {
+        "tokens_noop": 5000,
+        "tokens_report": 50000,
+        "tokens_action": 200000,
+        "suggested_daily_cap": 100000,
+        "early_exit_required": false
+      }
+    },
+    {
+      "id": "ci-sweeper",
+      "name": "CI Sweeper",
+      "file": "ci-sweeper.md",
+      "goal": "React to failing CI with minimal fixes and escalation",
+      "cadence": "5m-15m",
+      "risk": "medium",
+      "tools": [
+        "grok",
+        "claude-code",
+        "codex",
+        "github-actions"
+      ],
+      "skills": [
+        "ci-triage",
+        "minimal-fix"
+      ],
+      "state": "ci-sweeper-state.md",
+      "phases": [
+        "detect",
+        "classify",
+        "fix",
+        "verify",
+        "escalate"
+      ],
+      "human_gates": [
+        "infra-failures",
+        "max-attempts",
+        "security-tests"
+      ],
+      "starter": "starters/ci-sweeper",
+      "week_one_mode": "L2",
+      "token_cost": "very-high",
+      "cost": {
+        "tokens_noop": 5000,
+        "tokens_report": 50000,
+        "tokens_action": 200000,
+        "suggested_daily_cap": 1000000,
+        "early_exit_required": true
+      }
+    },
+    {
+      "id": "post-merge-cleanup",
+      "name": "Post-Merge Cleanup",
+      "file": "post-merge-cleanup.md",
+      "goal": "Follow-up tech debt and cleanup after merges to main",
+      "cadence": "1d-6h",
+      "risk": "low",
+      "tools": [
+        "grok",
+        "claude-code",
+        "codex",
+        "github-actions"
+      ],
+      "skills": [
+        "post-merge-scan",
+        "minimal-fix"
+      ],
+      "state": "post-merge-state.md",
+      "phases": [
+        "scan-merges",
+        "prioritize",
+        "fix-small",
+        "ticket-large"
+      ],
+      "human_gates": [
+        "architectural-debt",
+        "feature-flags",
+        "large-diffs"
+      ],
+      "starter": "starters/post-merge-cleanup",
+      "week_one_mode": "L1",
+      "token_cost": "low",
+      "cost": {
+        "tokens_noop": 5000,
+        "tokens_report": 40000,
+        "tokens_action": 150000,
+        "suggested_daily_cap": 200000,
+        "early_exit_required": false
+      }
+    },
+    {
+      "id": "dependency-sweeper",
+      "name": "Dependency Sweeper",
+      "file": "dependency-sweeper.md",
+      "goal": "Discover, safely apply, and verify dependency + vulnerability updates with human gates on risky changes",
+      "cadence": "6h-1d",
+      "risk": "medium",
+      "tools": [
+        "grok",
+        "claude-code",
+        "codex",
+        "github-actions"
+      ],
+      "skills": [
+        "dependency-triage",
+        "minimal-fix",
+        "loop-verifier"
+      ],
+      "state": "dependency-sweeper-state.md",
+      "phases": [
+        "scan",
+        "triage-risk",
+        "patch-safe",
+        "verify-worktree",
+        "escalate-risky"
+      ],
+      "human_gates": [
+        "major-bumps",
+        "high-sev-cve",
+        "denylisted-packages",
+        "max-attempts"
+      ],
+      "starter": "starters/dependency-sweeper",
+      "week_one_mode": "L2",
+      "token_cost": "medium",
+      "cost": {
+        "tokens_noop": 5000,
+        "tokens_report": 60000,
+        "tokens_action": 300000,
+        "suggested_daily_cap": 500000,
+        "early_exit_required": true
+      }
+    },
+    {
+      "id": "changelog-drafter",
+      "name": "Changelog Drafter",
+      "file": "changelog-drafter.md",
+      "goal": "Scan merged PRs and commits, draft categorized high-quality release notes or CHANGELOG entries for human review",
+      "cadence": "1d",
+      "risk": "low",
+      "tools": [
+        "grok",
+        "claude-code",
+        "codex",
+        "github-actions"
+      ],
+      "skills": [
+        "changelog-scan",
+        "draft-release-notes",
+        "loop-verifier"
+      ],
+      "state": "changelog-drafter-state.md",
+      "phases": [
+        "scan-merges",
+        "categorize",
+        "draft",
+        "review",
+        "publish"
+      ],
+      "human_gates": [
+        "breaking-changes",
+        "security",
+        "major-features",
+        "marketing-sensitive"
+      ],
+      "starter": "starters/changelog-drafter",
+      "week_one_mode": "L1",
+      "token_cost": "low",
+      "cost": {
+        "tokens_noop": 5000,
+        "tokens_report": 35000,
+        "tokens_action": 80000,
+        "suggested_daily_cap": 100000,
+        "early_exit_required": false
+      }
+    },
+    {
+      "id": "issue-triage",
+      "name": "Issue Triage",
+      "file": "issue-triage.md",
+      "goal": "Discover, deduplicate, prioritize and label incoming issues/discussions so the team always has a clean actionable queue. Excellent low-risk companion to Daily Triage.",
+      "cadence": "2h-1d",
+      "risk": "low",
+      "tools": [
+        "grok",
+        "claude-code",
+        "codex",
+        "github-actions"
+      ],
+      "skills": [
+        "issue-triage",
+        "loop-verifier"
+      ],
+      "state": "issue-triage-state.md",
+      "phases": [
+        "discover",
+        "dedupe",
+        "score",
+        "propose-labels",
+        "human-review"
+      ],
+      "human_gates": [
+        "security",
+        "p0-p1",
+        "ambiguous-duplicates",
+        "stale-closures"
+      ],
+      "starter": "starters/minimal-loop",
+      "week_one_mode": "L1",
+      "token_cost": "low",
+      "cost": {
+        "tokens_noop": 3000,
+        "tokens_report": 30000,
+        "tokens_action": 60000,
+        "suggested_daily_cap": 80000,
+        "early_exit_required": false
+      }
+    }
+  ]
+}