goal-audit）¶

作成日: 2026-06-25 出典 / きっかけ: GitHub cobusgreyling/loop-engineering 同梱の npm CLI をグローバルインストールし、dist/ のソースを直読みしてまとめたもの関連: loop_engineering_入門（概念編はこちら） agentic_reference_architecture_評価ループ

0. 要点（3行）¶

4本のCLIは「ループを書く前後を支える足場・採点・見積もりツール」。実行エンジンではなく、Markdown ファイル（雛形）を撒く・点数化する・電卓を叩くだけの薄いユーティリティ。
依存ゼロに近い（loop-cost が yaml を持つのみ）。全部 Node.js 標準 API（fs / path / child_process）で書かれた ESM。中身は数百行で、読めば全部分かる。
本質は「規約（convention）の検査機」。特定のファイル名（STATE.md・LOOP.md・loop-budget.md）とスキル名（loop-triage・loop-verifier）が在るか／無いかを見て点数を付ける。つまりツールが偉いのではなく、ファイル命名規約こそが製品。

インストール済み: /opt/homebrew/lib/node_modules/@cobusgreyling/{loop-init,loop-audit,loop-cost,goal-audit}（npm install -g 済み、loop-init/loop-audit/loop-cost/goal-audit で起動可）

1. 全体像 — 4本の役割分担¶

                 ┌──────────────────────────────────────────────┐
ループを作る前 →  │ loop-init   雛形を撒く（scaffold）            │ 書き込み系
                 └──────────────────────────────────────────────┘
                 ┌──────────────────────────────────────────────┐
作る前/運用中  →  │ loop-cost   1日のトークン消費を見積もる（電卓）│ 読み取り専用
                 └──────────────────────────────────────────────┘
                 ┌──────────────────────────────────────────────┐
作った後/CI    →  │ loop-audit  「ループ準備度」を100点満点で採点 │ 読み取り専用
                 └──────────────────────────────────────────────┘
                 ┌──────────────────────────────────────────────┐
別系統（ゴール）→  │ goal-audit  「ゴール準備度」を採点（G0–G3）   │ 読み取り専用
                 └──────────────────────────────────────────────┘

ツール	バージョン	種別	一言で	bin エントリ	依存
loop-init	1.2.1	書き込み	パターン別の雛形（skills/STATE.md/LOOP.md/予算ファイル）を撒く	`dist/cli.js`	なし
loop-audit	1.4.1	読み取り	ループ準備度を採点し L0–L3 を判定。`--suggest` で不足分の補い方を提示	`dist/cli.js`	なし
loop-cost	1.0.2	読み取り	周期×パターンから1日のトークン消費を試算	`dist/cli.js`	`yaml`
goal-audit	1.0.2	読み取り	「完了まで走らせる」ゴール志向の準備度を採点（G0–G3）	`dist/cli.js`	なし

全て package.json が "type": "module"（ESM）、TypeScript を dist/*.js にコンパイル済みで配布。ソースは公開コンパイル後JSがそのまま読める（難読化なし）。

2. 共通アーキテクチャ — 「規約検査機」という設計思想¶

4本に共通する設計をまず掴むと、各ツールが一気に分かる。

2-1. 「ファイルが在るか」を見るだけ¶

全ツールの心臓は、この10行程度の fileExists ヘルパー。

async function fileExists(p) {
  try { await stat(p); return true; }
  catch { return false; }
}

監査ツール（audit系）は、決め打ちのファイル名リストを fileExists で順に当て、ヒット数を点数に変換しているだけ。たとえば loop-audit が探す状態ファイル名:

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',
];

スキルは .grok/skills/ .claude/skills/ .codex/skills/ skills/ の4箇所を見て、ディレクトリ名が既知のスキル名（loop-triage・loop-verifier 等）と一致するかで判定する。

示唆: このツール群の「価値」は CLI のロジックではなく、「ループ対応プロジェクトとはこういうファイル構成だ」という規約そのもの。CLI はその規約に従っているかを機械的に照合する物差し。あなたが自前で同じ規約を採用すれば、CLI 無しでも同じ恩恵（再現性・監査可能性）が得られる。

2-2. registry（パターン台帳）が単一の真実¶

7つのパターンの諸元（周期・コスト・スキル・人間ゲート）は loop-cost/registry.json に集約されている。loop-cost はこれを読んで計算し、loop-init はこれに対応する雛形を撒く。パターンの定義が1ファイルに正規化されている点が、複数ツールの整合を保つ肝。

3. loop-init — 雛形を撒くツール（書き込み系）¶

3-1. 何をするか¶

--pattern（7種）と --tool（grok / claude / codex）の組み合わせで、対応するスターターキットを丸ごとコピーし、足りない観測ファイル（予算・実行ログ）を生成する。

3-2. 使い方¶

# 基本形（カレントに daily-triage を Claude Code 向けで撒く）
loop-init . --pattern daily-triage --tool claude

# 撒く前に「何が起きるか」だけ見る（破壊しない・推奨）
loop-init . --pattern pr-babysitter --tool claude --dry-run

# 短縮形
loop-init . -p ci-sweeper -t codex

オプション: -p/--pattern・-t/--tool（既定 grok）・--dry-run・-h/--help。引数解釈は手書きの for ループ（parseArgs）で、- で始まらない引数を target ディレクトリとみなす。

3-3. 実際に撒かれるもの（dry-run 実測）¶

loop-init . --pattern daily-triage --tool claude --dry-run の出力（抜粋）:

  would copy: …/minimal-loop-claude/.claude/skills/loop-triage → ./.claude/skills/loop-triage
  would copy: …/minimal-loop-claude/.claude/agents/loop-verifier.md → ./.claude/agents/loop-verifier.md
  would copy: …/minimal-loop-claude/STATE.md.example → ./STATE.md
  would copy: …/minimal-loop-claude/LOOP.md → ./LOOP.md
  would write: ./loop-budget.md
  would copy: …/templates/loop-run-log.md.template → ./loop-run-log.md
  would copy: …/templates/SKILL.md.loop-budget → ./.claude/skills/loop-budget/SKILL.md

=== Next steps ===
  npx @cobusgreyling/loop-audit . --suggest
  npx @cobusgreyling/loop-cost --pattern daily-triage
  First loop command (claude):
  /loop 1d $loop-triage — update STATE.md. Report-only week one.

つまり生成物は (1) triage スキル、(2) verifier エージェント、(3) STATE.md、(4) LOOP.md、(5) loop-budget.md、(6) loop-run-log.md、(7) loop-budget スキル、(8) AGENTS.md。これがそのまま loop_engineering_入門の「5部品＋メモリ」の物理ファイル版になっている。

3-4. プログラム内部の要点¶

ツール別の置き場マッピング: verifier の出力先がツールで変わる。Grok は .grok/skills/loop-verifier/SKILL.md、Claude は .claude/agents/loop-verifier.md、Codex は .codex/agents/verifier.toml。Codex だけは Markdown を読み込んで TOML に組み立て直して書く（[system_prompt] content="""..."""）。ツール間の規約差をここで吸収している。
L2 パターンだけ追加部品: PATTERNS_NEEDING_FIX（pr-babysitter / ci-sweeper / dependency-sweeper / post-merge-cleanup）には minimal-fix スキルを追加し、L2_PATTERNS（ci-sweeper / dependency-sweeper）には verifier も足す。自動修正する系のパターンほど maker/checker 部品を厚くする設計。
予算ファイルを動的生成: buildLoopBudgetMd(pattern) が registry のコスト上限を埋め込んだ loop-budget.md を文字列生成する。daily-triage なら「Max 2 runs/day・10万トークン/日・kill switch: loop-pause-all」のような表を吐く。
既存ファイルは上書きしない: 各コピー前に exists() を確認し、在れば skip。冪等（idempotent）に作ってあるので再実行しても壊れない。
bundled → monorepo フォールバック: 雛形は通常パッケージ同梱の starters/ から取るが、無ければ monorepo の ../../starters を探す（リポジトリ内からの実行も想定）。

グローバルインストール済みパッケージにも starters/（8種）と templates/（8ファイル）が同梱されていることを実測で確認。CLI 単体で完結する。

4. loop-cost — トークン消費の電卓（読み取り専用）¶

4-1. 何をするか¶

registry のパターン諸元（1回あたりの no-op / report / action トークン）と周期から、1日の消費トークンを no-op・full・action・現実ブレンドの4シナリオで試算し、予算上限超過を警告する。

4-2. 使い方¶

loop-cost --pattern daily-triage --level L1          # 既定
loop-cost --pattern ci-sweeper --cadence 15m --level L2
loop-cost --pattern daily-triage --json              # 機械可読
loop-cost --list                                     # パターンID一覧
loop-cost --pattern pr-babysitter --conservative     # 範囲は遅い方を採用

4-3. 実測サンプル¶

loop-cost --pattern ci-sweeper --cadence 15m --level L2:

Loop Cost Estimate — CI Sweeper (ci-sweeper)
Cadence: 15m  →  96 runs/day
Level: L2  ·  Registry tier: very-high
Suggested daily cap: 1.0M tokens

Daily token estimates:
  Early-exit / no-op:  480k  (5k/run)
  Full triage:         4.8M  (50k/run)
  Action every run:    19.2M  (200k/run)
  Realistic blend:     1.8M  (L2: 85% early-exit, 10% triage, 5% implementer+verifier)

Warnings:
  ! Early-exit triage is required — empty watchlist should exit in <5k tokens.
  ! Worst case (action every run) exceeds suggested cap (1.0M/day).
  ! Realistic estimate exceeds suggested daily cap — slow cadence or tighten scope.
  ! High cadence (96 runs/day) — verify early-exit is working.

4-4. プログラム内部の要点（計算式）¶

中核は2つの関数。ここが一番「中身がある」ツール。

(1) 周期→1日の実行回数（cadenceToRunsPerDay）:

const INTERVAL_MS = { m: 60_000, h: 3_600_000, d: 86_400_000 };
// "15m" → 96回/日、"1d" → 1回/日
// "5m-15m" のような範囲は、既定で速い方(=多い回数)、--conservative で遅い方

86_400_000 ms ÷ 周期ms を floor。範囲指定（- 区切り）は Math.max（既定＝最悪ケース寄り）か Math.min（conservative）。

(2) レベル別の現実ブレンド（realisticMix）: L1/L2/L3 で「no-op:report:action の割合」を変える。early_exit_required パターンはさらに no-op 比率を上げる。

レベル	early-exit有	early-exit無
L1	90% no-op / 10% triage	60% no-op / 40% triage
L2	85% / 10% / 5% action	50% / 30% / 20% action
L3	—	40% / 35% / 25% action

(3) 警告ロジック（estimateCost）: action × 回数 > suggested_daily_cap や 現実ブレンド > cap、96回/日以上 で警告を積む。予算超過を「設計時に」気づかせるのが狙い。

registry の数値例（daily-triage）: no-op 5k / report 50k / action 200k トークン、上限10万/日。この数字は Cobus の経験則ベースの目安であり、自分のモデル・タスクでの実測に置き換えるべき値（断定値ではない）。

5. loop-audit — ループ準備度の採点（読み取り専用）¶

5-1. 何をするか¶

対象ディレクトリを走査し、5部品＋メモリ＋安全＋コスト観測の有無を点数化（0–100）。L0〜L3 を判定し、不足分の「埋め方コマンド」を提示する。v1.4 から「実際に回した形跡」も見るようになった。

5-2. 使い方¶

loop-audit .                 # 人間向けレポート
loop-audit . --suggest       # 不足分の補い方（初回推奨）
loop-audit . --json          # CI/スクリプト用
loop-audit . --md            # Markdown レポート

終了コード: score ≥ 40 で 0、< 40 で 2。→ CI のゲートに使える（準備不足ならビルドを止める）。

5-3. 採点ロジック（`computeScore`）¶

基礎点10点から、以下を加点（抜粋・実装の配点そのまま）:

信号	点	何を見るか
state ファイル	+18	`STATE.md` 等が在る
triage スキル	+14	`loop-triage` 等が在る
verifier スキル	+14	maker/checker の checker 役（`loop-verifier`）
スキル2個以上	+14（1個なら+7）	ループ用スキルの数
LOOP.md	+9	周期・上限・ゲートの設定ファイル
AGENTS.md / CLAUDE.md	+9	プロジェクト規約
safety（LOOP内言及/専用doc）	+4 / +4	人間ゲート・denylist
GitHub（dir / workflows）	+6 / +4	dogfooding 形跡
MCP / worktree / registry	+3 / +3 / +2	コネクタ・隔離・台帳
コスト観測（予算/実行ログ/LOOP予算/予算スキル）	+3/+3/+2/+2	トークン管理
loop活動の実形跡	+6	← v1.4 の目玉

5-4. レベル判定 — 「ファイルが在る」だけでは L3 にしない¶

L3: score≥78 かつ verifier有 かつ state有 かつ l3Ready
L2: score≥58 かつ triage有
L1: score≥38 かつ state有
L0: それ未満

肝は l3Ready = costReady && hasRealActivity。

costReady: 予算doc・実行ログ・LOOP内予算が3つ揃うこと
hasRealActivity: 後述の「実際に回した形跡」が在ること

→ 構造だけ整えても（＝ファイルを置いただけでは）L3 に上がれず L2 で頭打ち。「実際に1サイクル回して state をコミットせよ」と促す。「形だけの自動化」を点数で拒否する思想が実装に埋め込まれている。

5-5. 「実際に回した形跡」の検出（`detectLoopActivity`）— v1.4 の核心¶

5つの動的シグナルを探す:

state ファイル内の Last run / 日付行（2026-06-25 形式）/ triage 語
実行ログ成果物（loop-run-log / run-log / loop.log 等のファイル名）
.github/workflows/ に triage/changelog/loop/audit を含む YAML
git log --oneline -25 を execSync で実行し、loop/STATE.md/changelog 等のコミットを探す（タイムアウト1.5秒、リポジトリでなければ静かにスキップ）
LOOP.md 内の last run / cadence / scheduled 言及

→ 静的なファイル存在チェックだけでなく、git 履歴という「動かした証拠」まで見る点が、ただのリンターと一線を画す。

5-6. `--suggest` の中身（`auditProject`）¶

不足している信号ごとに「埋め方の1行コマンド」を recommendations に積む。例: state が無ければ Copy starters/minimal-loop/STATE.md.example to STATE.md、verifier が無ければ Add verifier: .claude/agents/loop-verifier.md 等。監査と是正手順がセット。

6. goal-audit — ゴール準備度の採点（読み取り専用）¶

6-1. loop-audit との違い¶

loop-audit が「定期的に回るループ」の準備度を見るのに対し、goal-audit は「完了まで走らせる単発ゴール（Grok Build の /goal 等）」の準備度を見る姉妹ツール。loop_engineering_入門でいう派生概念「Goal Engineering（run-until-done）」に対応。

6-2. 使い方・判定¶

goal-audit .            # G0–G3 を判定
goal-audit . --suggest
goal-audit . --json

判定は素朴な閾値: G3≥80 / G2≥60 / G1≥40 / G0（loop-audit のような l3Ready ゲートは無い）。終了コードは score≥40 で 0、未満で 2。

6-3. 採点ロジックの違い（`auditProject`）¶

loop-audit が STATE.md（繰り返しの記憶）を最重視するのに対し、goal-audit は別の軸を見る:

信号	点	loop-audit との差
`GOAL.md`	+15(+5)	← ゴールの定義文書。これが核
ゴールスキル（goal-verifier / goal-scoper / goal-completion-check）	+10+α	スキル名が loop 系と別
verifier	+20	「実装者が自己採点する」のを防ぐ最重要部品として最大配点
テストハーネス	+15	`package.json`/`pyproject.toml`/`tests/` 等を検出
CI	+10	`.github/workflows`/`.gitlab-ci.yml`/`Jenkinsfile`
AGENTS.md（goal 言及）	+10(+5)
予算doc / 実行ログ / 安全doc	+10 / +5 / +5

設計の含意: 単発ゴールは「いつ終わったか」を客観判定する必要があるので、テスト・CI・verifier に重い配点。「done conditions are subjective（テストが無いと完了条件が主観的）」という findings が象徴的。一方ループは「次回に記憶を渡す」ことが肝なので state を最重視。目的が違えば測る物差しも変えるという、地味だが正しい設計判断。

6.5. STATE.md の構造とライフサイクル（記憶の物理ファイル）¶

6.5-1. 一言で¶

STATE.md は「ループの記憶（外付けの脳）」。チャットは閉じれば消えるが、ループは次の run が必要なので、毎回の終わりに「何を見て・何をして・何を人間に投げたか」を書き出し、次の run の始めに読み直す。これが無いとループは毎回ゼロから始まる健忘症になる。loop_engineering_入門の「ループはメモリ・検証・境界を持つプロセス」の、メモリそのもの。

6.5-2. read / write サイクル¶

[run N 開始]
   ① 読む : 前回の STATE.md を読み「もう知っていること」を把握
   ② triage: 新しい発見と突き合わせ、既知・重複を除外
   ③ 行動 or エスカレーション
   ④ 書く : 結果を STATE.md に上書き（Last run 更新・Run log 追記）
[run N 終了] → 次回 run N+1 は更新済み STATE.md を ① で読む

参照する主体は3者:

誰が	いつ	何のために
ループ本体（triage スキル）	毎 run の最初と最後	記憶を読み、結果を書き戻す。`loop-triage` スキルは出力に必ず `### 4. State Updates` を出す規約
人間	任意	`High Priority` を見れば自分の判断待ち事項が1ファイルで分かる
loop-audit	監査時	存在で +18点。中の `Last run`・日付行を読み「本当に回した形跡」を判定

6.5-3. 何が書かれているか（汎用 `STATE.md.template` 実物）¶

# Loop State — {{PROJECT_NAME}}
Last run: (set by loop on each run)        ← 最終実行時刻。activity検出の鍵

## High Priority (loop is acting or waiting on human)
- [ ] ID — 一行説明
  Loop action: ループが前回やったこと
  Human decision: （あれば）人間の判断
## Watch List                              ← 監視中だが今は動かない
## Recent Noise (ignored this run)          ← 見たが無視（triage精度調整用）
---
Run log: (timestamp) | findings | actions | escalations

4ゾーン構成: High Priority（動作中／判断待ち）／ Watch List（監視のみ）／ Recent Noise（無視記録＝triage チューニング）／ Run log（実行台帳）。

6.5-4. パターン別に構造が変わる¶

state ファイル名・中身はパターン固有（STATE_FILES リスト）。

pr-babysitter-state.md: Watched PRs（Status / Attempts: 0/3 / Last action）/ Escalated / Resolved (last 7d)。Attempts: n/3 カウンタが無限修正ループを止める。
ci-sweeper-state.md: Active Failures / Watch (flakes / infra) / Resolved。フレーキー/インフラ起因を別枠に隔離。

6.5-5. STATE.md × hook（Claude Code）— 独自の上積み¶

注: loop-engineering リポジトリ自体は hook 連携を前提にしない（スキル＋スケジューラでモデルに STATE.md を書かせる設計）。以下は Claude Code の hook と組み合わせる独自アイデアでリポジトリ外の発想。

狙い: STATE.md の弱点は「更新がLLMの善意頼み」で、忘れ・サボり・context圧縮で記憶が虫食いになること。hook はハーネスが実行する＝モデルの気分に左右されないので、STATE.md を「モデルが守るべき規約」から「ハーネスが強制する不変条件」へ格上げできる。

hook イベント	STATE.md への作用	解決する問題
SessionStart	STATE.md を読んで context 注入	「読み忘れ」を消す
Stop / SubagentStop	`Run log` に1行追記（JST timestamp・findings・actions）	「書き忘れ」を消す。loop-audit の activity 検出が必ず通る
PostToolUse（git commit 検知）	`Last run` を現在時刻（JST）に更新	実行形跡を機械的に残す
PreToolUse（gate）	STATE/loop-budget を読み、予算超過や `loop-pause-all` フラグでツール実行を deny	kill switch・人間ゲートを決定論的に強制

既に「読む半分」は実装済み: MEMORY.md が SessionStart で context 注入されている＝「SessionStart hook で記憶ファイルを読ませる」パターンそのもの。STATE.md はこのループ版＋書き込み半分。
一番おいしいのは PreToolUse 予算ゲート: 既存の gitleaks-precommit.sh（PreToolUse でコミットをブロック）・block-secret-file-reads.sh と同型で、「予算超過でツールを止める」に転用できる。loop_engineering_入門の L3 昇格条件「denylist・kill switch」を口約束でなくコードで担保できる。

7. まとめ — どう使い分けるか早見表¶

やりたいこと	コマンド	種別
新しくループを始める雛形を撒く	`loop-init . -p <pattern> -t claude`	書き込み
撒く前に影響範囲だけ確認	`loop-init . -p <pattern> --dry-run`	安全
ループのコストが心配	`loop-cost --pattern <id> --cadence <周期> --level <L1-3>`	読み取り
既存プロジェクトのループ成熟度を測る	`loop-audit . --suggest`	読み取り
CI でループ準備不足を弾く	`loop-audit . --json`（exit 2 を拾う）	読み取り
単発「完了まで走る」ゴールの準備度	`goal-audit . --suggest`	読み取り

結論: この4本は「魔法のオーケストレーター」ではなく、規約に沿ったファイルが在るかを照合する物差し＋雛形撒き＋電卓。だが価値はそこにある——(1) STATE.md/LOOP.md/loop-budget.md という命名規約、(2) 「形だけでは L3 に上げない（実行形跡を git まで見る）」という昇格の厳しさ、(3) コストを設計時に試算させる規律。あなたの ~/temporal-workflows や ~/research-orchestrator に、この命名規約と「予算・実行ログ・verifier を必須にする」発想を移植すれば、CLI 自体を常用しなくても運用の堅牢性は上がる。ツールを使うより、ツールが体現している規約を盗むのが正解。

参考リンク¶

GitHub リポジトリ本体: https://github.com/cobusgreyling/loop-engineering
npm: @cobusgreyling/loop-init / loop-audit / loop-cost / goal-audit
概念編ノート: loop_engineering_入門
インストール先（ローカル実測）: /opt/homebrew/lib/node_modules/@cobusgreyling/

作成: 2026-06-25 ／最終更新: 2026-06-25

Loop Engineering CLI ツール群 調査資料（loop-init / loop-audit / loop-cost / goal-audit）¶