flywheel

フライホイールスキル

ループ内の位置： 運用ループの7番目（キャプチャ＋ラチェット）—昇格ラチェットがデータを供給するナレッジプールの健全性を監視します。 ナレッジフライホイールの健全性を監視します。

フライホイールモデル

Sessions → Transcripts → Forge → Pool → Promote → Knowledge
     ↑                                               │
     └───────────────────────────────────────────────┘
                    Future sessions find it

速度 = ナレッジが流れる速度です。摩擦 = フライホイールを遅らせるボトルネックです。

統合されたトリガー（ag-s43tg 第1波）：ratchet はここにルーティングされます

• ratchet → フライホイールゲートの追跡。 ブラウニアンラチェットのゲートを記録するよう求められた場合に使用します — 永続的なゲートを通じたRPIワークフローの進捗を追跡します （Progress = Chaos × Filter → Ratchet。マージ／クローズ／保存された進捗はラチェットを逆転できません）。
• ゲートの操作方法：.agents/ao/chain.jsonlのチェーンに対してao ratchet status / ao ratchet check <step> / ao ratchet record <step> --output "<artifact-path>"を実行します （ステップ：research、plan、implement、vibe、post-mortem）。
• ラチェットは進捗を追跡してロックしますが、ループ自体は実行しません — 作業を実行するには/crank （エピックループ）または/swarm（Ralphループ）と組み合わせてください。

実行手順

/flywheelを実行する場合：

ステップ 1：ナレッジプールを測定する

# Count top-level artifact files (avoid counting directories)
LEARNINGS=$(find .agents/learnings -maxdepth 1 -type f 2>/dev/null | wc -l)
PATTERNS=$(find .agents/patterns -maxdepth 1 -type f 2>/dev/null | wc -l)
RESEARCH=$(find .agents/research -maxdepth 1 -type f 2>/dev/null | wc -l)
RETROS=$(find .agents/retros -maxdepth 1 -type f 2>/dev/null | wc -l)
echo "Learnings: $LEARNINGS"
echo "Patterns: $PATTERNS"
echo "Research: $RESEARCH"
echo "Retros: $RETROS"

ステップ 2：最近のアクティビティを確認する

# Recent learnings (last 7 days)
find .agents/learnings -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l
# Recent research
find .agents/research -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l

ステップ 3：陳腐化を検出する

# Old artifacts (> 30 days without modification)
find .agents/ -name "*.md" -mtime +30 2>/dev/null | wc -l

ステップ 3.5：キャッシュの健全性を確認する

if command -v ao &>/dev/null; then
  # Get citation report (cache metrics)
  CITE_REPORT=$(ao metrics cite-report --json --days 30 2>/dev/null)
  if [ -n "$CITE_REPORT" ]; then
    HIT_RATE=$(echo "$CITE_REPORT" | jq -r '.hit_rate // "unknown"')
    UNCITED=$(echo "$CITE_REPORT" | jq -r '(.uncited_learnings // []) | length')
    STALE_90D=$(echo "$CITE_REPORT" | jq -r '.staleness["90d"] // 0')
    echo "Cache hit rate: $HIT_RATE"
    echo "Uncited learnings: $UNCITED"
    echo "Stale (90d uncited): $STALE_90D"
  fi
else
  # ao-free fallback: compute approximate metrics from files
  echo "Cache health (ao-free fallback):"
  echo "Active learnings (30d): $(find .agents/learnings/ -name '*.md' -mtime -30 2>/dev/null | wc -l | tr -d ' ')"
  echo "Forge candidates pending: $(ls .agents/forge/*.md 2>/dev/null | wc -l | tr -d ' ')"
  if [ -f .agents/ao/citations.jsonl ]; then
    echo "Total citations: $(wc -l < .agents/ao/citations.jsonl | tr -d ' ')"
    echo "Unique learnings cited: $(grep -o '"artifact_path":"[^"]*"' .agents/ao/citations.jsonl 2>/dev/null | sort -u | wc -l | tr -d ' ')"
  else
    echo "No citation data (citations.jsonl not found)"
  fi
  [ -f .agents/ao/outcomes.jsonl ] && echo "Session outcomes recorded: $(wc -l < .agents/ao/outcomes.jsonl | tr -d ' ')"
fi

ステップ 4：ao CLI のステータスを確認する

if command -v ao &>/dev/null; then
  ao metrics flywheel status 2>/dev/null || echo "ao metrics flywheel status unavailable"
  ao status 2>/dev/null || echo "ao status unavailable"
  ao maturity --scan 2>/dev/null || echo "ao maturity unavailable"
  ao anti-patterns 2>/dev/null || echo "ao anti-patterns unavailable"
  ao badge 2>/dev/null || echo "ao badge unavailable"

  # Knowledge maintenance
  ao dedup --merge 2>/dev/null || true
  ao contradict 2>/dev/null || true
  ao constraint review 2>/dev/null || true
  ao curate status 2>/dev/null || true
  ao metrics health 2>/dev/null || true
  ao metrics cite-report --days 30 2>/dev/null || true

  # Active pruning: archive stale, evict low-utility, and curate noisy uncited learnings
  ao maturity --expire --archive 2>/dev/null || true
  ao maturity --evict --archive 2>/dev/null || true
  ao maturity --curate --archive 2>/dev/null || true

  # Retrieval quality: use the representative live corpus when it exists
  if [ -d cli/cmd/ao/testdata/retrieval-bench-live ]; then
    ao eval bench --live --corpus cli/cmd/ao/testdata/retrieval-bench-live --json 2>/dev/null || true
  fi
else
  echo "ao CLI not available — using file-based metrics"
  echo "Pool depths:"
  for pool in learnings patterns forge knowledge research retros; do
    echo "  $pool: $(ls .agents/${pool}/*.md 2>/dev/null | wc -l | tr -d ' ')"
  done
  echo "  global patterns: $(ls ~/.claude/patterns/*.md 2>/dev/null | wc -l | tr -d ' ')"
  echo "See references/promotion-tiers.md for tier definitions"
fi

ステップ 4.5：メトリクスを処理する（スキルのテレメトリーから）

.agents/ao/skill-telemetry.jsonlが存在する場合、jqを使用してスキルごとの呼び出し回数、スキルごとの平均サイクル時間、ゲートの失敗率を抽出します。健全性レポート（ステップ 6）の## Process Metricsに含めてください。

ステップ 5：アーティファクトの整合性を検証する

相互参照の検証：ナレッジアーティファクトをスキャンし、内部参照の破損を確認します。 references/artifact-consistency.mdに記載された手順に従い、scripts/artifact-consistency.shを使用してください。 デフォルトの許可リストはreferences/artifact-consistency-allowlist.txtにあります。全件をそのまま監査するには--no-allowlistを使用してください。

健全性の指標：>90% = 健全、70-90% = 警告、<70% = 重大。

ステップ 6：健全性レポートを作成する

出力先： .agents/flywheel-status.md

# Knowledge Flywheel Health

**Date:** YYYY-MM-DD

## Pool Depths
| Pool | Count | Recent (7d) |
|------|-------|-------------|
| Learnings | <count> | <count> |
| Patterns | <count> | <count> |
| Research | <count> | <count> |
| Retros | <count> | <count> |

## Velocity (Last 7 Days)
- Sessions with extractions: <count>
- New learnings: <count>
- New patterns: <count>

## Artifact Consistency
- References scanned: <count>
- Broken references: <count>
- Consistency score: <percentage>%
- Status: <Healthy/Warning/Critical>

## Cache Health
- Hit rate: <percentage>%
- Uncited learnings: <count>
- Stale (90d uncited): <count>
- Status: <Healthy/Warning/Critical>

## Retrieval Quality
- Live corpus coverage: <percentage or unavailable>
- Live corpus learnings: <count or unavailable>
- Status: <Healthy/Warning/Critical>

## Health Status
<Healthy/Warning/Critical>

## Friction Points
- <issue 1>
- <issue 2>

## Recommendations
1. <recommendation>
2. <recommendation>

ステップ 7：ユーザーに報告する

ユーザーに以下を伝えます：

1. フライホイール全体の健全性
2. ナレッジプールの深さ
3. 最近のアクティビティ
4. 摩擦の要因
5. 推奨事項

健全性の指標

指標	健全	警告	重大
週あたりの学習数	3+	1-2	0
陳腐化したアーティファクト	<20%	20-50%	>50%
調査／計画比率	>0.5	0.2-0.5	<0.2
キャッシュヒット率	>80%	50-80%	<50%

ゴールデンシグナル

4つのゴールデンシグナル（常に表示）は、ナレッジが真に複利的に増えているのか、単にノイズが蓄積しているだけなのかを明らかにします。

ao flywheel status              # table output with golden signals
ao flywheel status --json       # machine-readable

4つのシグナル

#	シグナル	問い	主要指標
1	速度の傾向	σρ-δは増加していますか？	ベースライン速度の線形回帰の傾き（7日／30日）
2	引用パイプライン	引用は役に立っていますか？	報酬が0.6を超えるフィードバックの割合
3	調査の完了	調査内容は活用されていますか？	孤立した調査の割合（学習へのバックリンクなし）
4	再利用の集中度	プール全体が活用されていますか？	引用分布のジニ係数

判定としきい値

シグナル	健全	警告	重大
速度の傾向	複利的（傾き > +0.01）	停滞	減衰（傾き < -0.01）
引用パイプライン	強化中（高利用率が>60%）	不活性（30-60%）	低下中（<30%）
調査の完了	活用中（孤立が<=10%）	—	抱え込み（孤立が>=10%）
再利用の集中度	分散（ジニ係数<0.4、アクティブ>30%）	集中	休眠（ジニ係数>0.7またはアクティブ<10%）

全体判定： 健全が3つ以上 = 複利的、重大が3つ以上 = 減衰中、混在 = 蓄積中。

推奨アクション

判定	アクション
decaying	/compile サイクルを実行し、古くなった成果物をアーカイブして、ao lookup で引用を増やします
accumulating	孤立した調査内容（/research→/post-mortem --quick パイプライン）を確認し、/curate --mode=forge の収集品質を高めます
compounding	現在の頻度を維持します。傾向を追跡するため、ベースライン（ao metrics baseline）の記録を検討してください

キャッシュの削除

削除パイプライン全体（受動的な追跡 → 信頼度の低下 → 成熟度のスキャン → アーカイブ）については、references/cache-eviction.md をお読みください。

Hub の予算とフェーズ 4 の強化

~/.agents/learnings/ のフェーズ 4（soc-ytpq）ガバナンスは、すべて助言的なものであり、デフォルトでは何もブロックしません。詳細については、references/hub-budget.md をご覧ください。

• サイズ予算： 目標は ≤ 250 MB / ≤ 5,000 ファイルです。ao maturity --evict --target-size=250M で元に戻します（ユーティリティの低い順に処理し、lifecycle.IsEvictionEligible に従って正規ファイル／信頼度の高いファイルを保護します）。
• ボリュームゲート： 昇格数が --max-promotions=N（デフォルト 500。フォールバックとして AO_MAX_PROMOTIONS=N 環境変数を使用。≤0 で無効化）を超えると、ao harvest は警告を出します。警告のみです。2,638 件の昇格が発生した soc-ujls の処理により、ハードゲートでは正当な実行を誤ってブロックすることが明らかになっています。
• 出所： 昇格されたすべてのファイルは、フロントマターに source_rig: を含みます（書き込み元が空の場合は source_rig: unknown としてシリアライズされます）。harvest.Promote と pool.(*Pool).Promote はどちらも、~/.agents/pool/promoted-index.jsonl を使って同じ Hub 内のコンテンツ重複を検出します。
• 再肥大化のトリアージ： SkipGlobalHub のデフォルトが true であることを確認します（agentops-b3v / soc-ujls の修正）。次に、grep -h '^source_rig:' ~/.agents/learnings/*.md | sort | uniq -c | sort -rn を実行して、再発の原因となった書き込み元を特定します。rm を直接使わず、--target-size を使用してください。

主なルール

• 定期的に監視する - フライホイールには注意が必要です。ボトルネックに早めに対処してください
• フライホイールに知識を供給する - /post-mortem（または /post-mortem --quick）を実行してください
• 古くなった知識を整理する - 古い成果物をアーカイブしてください

例

ユーザーの発言： /flywheel — プールの深さを集計し、最近のアクティビティを確認し、成果物の整合性を検証して、.agents/flywheel-status.md に健全性レポートを書き込みます。 フックのトリガー： /post-mortem の後 — 現在のメトリクスと過去のメトリクスを比較し、速度の低下や摩擦点にフラグを立てます。

トラブルシューティング

問題	原因	解決策
すべてのプール数がゼロ	.agents/ ディレクトリが存在しないか、空です	/post-mortem（または --quick）を実行して、知識プールに初期データを追加します
速度が常にゼロ	最近の抽出（過去 7 日間）がありません	/post-mortem（または --quick）を実行して、学びを抽出し、インデックスを作成します
"ao CLI not available"	ao コマンドがインストールされていないか、PATH にありません	ao CLI をインストールするか、手動でプール数を数えるフォールバックを使用します
古くなった成果物が >50%	最後のセッションから長期間が経過しているか、リポジトリが非アクティブです	/provenance --stale を実行して、古い成果物を監査し、アーカイブします

参考ドキュメント

• references/artifact-consistency.md
• references/promotion-tiers.md
• references/hub-budget.md
• references/cache-eviction.md
• references/flywheel-cli.feature — 実行可能な仕様：ao flywheel CLI コマンドの動作。cmd テストにリンクされています（soc-jnfgi）