@harnessforce/claude-code-plugin 0.0.0-stage → 0.1.0

package/scripts/harnessforce-hook.cjs

@@ -0,0 +1,22 @@
+// hookのentry。18未満のNode.jsでも構文解析できるよう、ES5とCommonJSだけで書く（correlation.md「実行環境」）。
+// 本体は組み込みのfetchを使うため、Node.js 18以上でだけ読み込む。
+"use strict";
+
+var major = Number(process.versions.node.split(".")[0]);
+
+if (major >= 18) {
+	require("./harnessforce-hook-main.cjs");
+} else {
+	process.stderr.write(
+		"harnessforce: session registration skipped (unsupported node)\n"
+	);
+	// 利用者に届く表示。文言はagent-coreのUNSUPPORTED_NODE_WARNINGと同じ値で、testで一致を確かめる。
+	// 繰り返し表示しないよう、session開始のhookだけが出す。
+	if (process.argv[2] === "session-start") {
+		process.stdout.write(
+			JSON.stringify({
+				systemMessage: "Harnessforceのhookには18以上のNode.jsが必要です",
+			}) + "\n"
+		);
+	}
+}

package/skills/propose-improvements/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: propose-improvements
+description: /harnessforce:tuneの分析結果から、人の介入、ループにできる繰り返し、MCP server、使い方（contextの圧縮、cacheの再利用、modelの使い分け）の改善の提案を作り、harnessforce tune recordで記録してから表示する。/harnessforce:tuneが「提案を作れます」と判定した対象にだけ使う。ファイルは書き換えない。
+---
+
+# 分析結果から改善の提案を作る
+
+`/harnessforce:tune`の`summarize.mjs`が出した「提案の対象」のうち、「提案を作れます」の対象ごとに提案を作る。提案は利用者がそのまま適用できる形にし、記録してから表示する。
+
+## 書き換えない
+
+- 利用者のファイル、設定、repository、managed settingsを書き換えない。Edit、Writeのtool、`git apply`、`git commit`、branchの作成、`gh pr create`を使わない。差分とPull Requestの下書きは表示するだけである。
+- 書き込むのは、`harnessforce tune record`が`~/.harnessforce/tune/`へ書く記録だけである。一時fileも作らない。
+
+## 作る条件
+
+`summarize.mjs`の判定が正である。「データ不足」と「未計測のため提案しません」の対象には提案を作らない。判定の条件は次のとおりである。
+
+| 対象 | 提案を作る最小の条件 |
+| --- | --- |
+| すべて | 分析した範囲に10 session以上ある |
+| 人の介入 | その`intervention.kind`が、3 session以上で合計10回以上ある |
+| ループにできる繰り返し | その`loop.kind`が、合計3回以上ある |
+| MCP server | `configured`のsessionが10以上ある |
+| 使い方の`frequent_compaction`、`low_cache_reuse` | その`usage.kind`に当たるsessionが3以上ある |
+| 使い方の`model_choice` | `models`を持つsessionが10以上あり、分析した範囲の`models`の合計で、1つの`message.model`の値が`output_tokens`の合計の90%以上を占める |
+
+- 未計測（`not_measured`）の値を根拠にしない。未計測を0として扱わない。
+- 使い方の提案の変更の種類は、`claude_md`、`rule`、`skill`、`agent`、`command`に限る（例: 肥大したCLAUDE.mdを分ける、探索をsubagentへ移してそのagentの`model`を指定する）。settingsの`model`など、他の変更の種類にしない。`harnessforce tune record`は他の変更の種類を拒否する。`claude_md`の変更は適用を検出しないため、前回の提案の前後にも現れない。
+- 使い方の値（`usage`）は端末だけの値であり、Harnessforceへ送られない。提案の根拠には使ってよい。
+- ハーネスの構成（skill、rule、agent、command、hook、MCP server、modelのversionごとの成果の差）を対象にした提案は作らない。
+- 調べても、利用者がそのまま適用できる変更が見つからなければ、その対象の提案を作らず、理由を1行で伝える。
+
+## 根拠を集める
+
+- 対象の「根拠のsession」の`transcript_path`の記録を、提案に必要な部分だけ読む。人の介入なら、その種類のpromptと、直前のagentの応答を読む。ループなら、一巡の手順（Issueの取得、修正、test、push、Pull Requestの作成など）と、人が介入した時点を読む。MCP serverなら、呼び出しと失敗を読む。使い方なら、`frequent_compaction`は圧縮の前の指示と経緯、`low_cache_reuse`はcacheが再利用されなかった応答の前後、`model_choice`は本体が行っていた探索や定型の作業を読む。
+- 「前回の提案の前後」で「良くなった向きへ動いていません」と示された提案と同じ対象の提案を作るときは、その前後を根拠に示し、前回と同じ差分を繰り返さない。
+- 適用先の現在の定義（settings、skill、rule、agent、command、hook、`.mcp.json`、`~/.claude.json`の`mcpServers`、CLAUDE.md）を読み、差分を現在の内容に対して作る。
+
+## 形式
+
+提案ごとに次を持たせる。
+
+| 項目 | 内容 |
+| --- | --- |
+| 対象のカテゴリ | `intervention.kind=<kind>`、`loop.kind=<kind>`、`mcp_server=<識別子>`、`usage.kind=<kind>`のいずれか。`usage.kind`の`<kind>`は`frequent_compaction`、`low_cache_reuse`、`model_choice`のいずれか |
+| 根拠 | 期間、回数、該当したsessionの時刻と、記録の抜粋。抜粋は端末にだけ表示する |
+| 変更の種類 | `permissions`、`hook`、`skill`、`rule`、`agent`、`command`、`loop_prompt`、`mcp_config`、`claude_md`のいずれか |
+| 適用先 | 利用者のscope、repositoryのscope、managed settingsのいずれかと、ファイルのpath |
+| 変更 | そのまま適用できるunified diff。repositoryのscopeなら、branch名、title、本文、diffからなるPull Requestの下書き。managed settingsなら、Owner/Adminが貼り付ける差分 |
+| 期待する効果 | どのカテゴリの値が減るか、どの既存の指標（CIの失敗率、手戻り率、完了Issueあたりのcost）が変わるか |
+| 測り方 | 適用で変わるComponentVersion（種類と識別子）と、比較に使う指標 |
+
+変更の種類と、適用で変わるcomponentの対応は次のとおりである。
+
+| 変更の種類 | componentの`kind` | componentの識別子（`id`） | 期待する内容 |
+| --- | --- | --- | --- |
+| `permissions` | `permissions` | `permissions` | 適用後のsettingsの`permissions`の値全体（`value`） |
+| `hook` | `hook` | hookのevent名 | 適用後のsettingsの`hooks`のそのeventの値（`value`） |
+| `skill` | `skill` | skillのdirectory名 | 適用後の`SKILL.md`の内容全体（`content`） |
+| `rule` | `rule` | `CLAUDE.md`か`rules/<path>` | 適用後のfileの内容全体（`content`） |
+| `agent` | `agent` | `agents/`からのpathの`.md`を除き`/`を`:`にした名前 | 適用後のfileの内容全体（`content`） |
+| `command` | `command` | `commands/`からのpathの`.md`を除き`/`を`:`にした名前 | 適用後のfileの内容全体（`content`） |
+| `loop_prompt` | 書くfileの形式に従い`command`か`skill` | 上の`command`か`skill`と同じ | 適用後のfileの内容全体（`content`） |
+| `mcp_config` | `mcp_server`（serverを削除する差分ではcomponentを持たない） | server名 | 適用後のserverの定義（`value`）。削除では適用後のfileの内容全体（`content`） |
+| `claude_md` | 無し | 無し | 適用後のCLAUDE.mdの内容全体（`content`） |
+
+componentの`source`は適用先のscope（`user`、`repository`、`local`、`managed`）とする。`.mcp.json`のserverは`repository`、`~/.claude.json`の最上位の`mcpServers`は`user`、その`projects`の下は`local`である。
+
+## 許可を減らす提案
+
+- 権限の確認への応答を減らす提案は、確認を求められたtoolと、その許可の内訳を根拠にする。許可するのは、根拠に現れたtoolとcommandの最小の範囲だけとする（例: `Bash(pnpm test:*)`、`Bash(git status)`、`mcp__github__get_issue`）。
+- すべてのコマンドを許可する規則を提案しない。`Bash`、`Bash(*)`、`Bash(:*)`、`*`のような、tool全体やすべてのcommandへの許可、`"defaultMode": "bypassPermissions"`、`--dangerously-skip-permissions`は、どの提案にも含めない。
+
+## ループの提案
+
+- ループにできる繰り返しの提案は、commandかskillの形式のprompt（`loop_prompt`）とし、止める条件を必ず含める。止める条件は、最大の繰り返し回数と、人が確認する時点（例: Pull Requestの作成前、同じ失敗が2回続いたとき）の両方とする。
+- promptは、根拠のsessionで人が介入していた時点を、止める条件か、agentが自分で行う手順のどちらかに置き換える。
+
+## 記録してから表示する
+
+提案を表示する前に、提案ごとに`harnessforce tune record`を実行し、stdinへUTF-8のJSONのobjectを1つ渡す。入力はheredocで渡し、fileに書かない。区切りの語は、入力に現れない語にする。
+
+```sh
+harnessforce tune record <<'HF_TUNE_RECORD_7f3c'
+{"category": "...", "change_type": "...", "scope": "...", "path": "...", "evidence_session_ids": ["..."], "body": "..."}
+HF_TUNE_RECORD_7f3c
+```
+
+| 項目 | 必須 | 内容 |
+| --- | --- | --- |
+| `category` | ✓ | 対象のカテゴリ |
+| `change_type` | ✓ | 変更の種類 |
+| `scope` | ✓ | `user`、`repository`、`local`、`managed`のいずれか |
+| `path` | ✓ | 変更が書くfileの絶対path |
+| `project_root` | `scope`が`repository`か`local`なら必須 | 適用先のrepositoryのrootの絶対path。それ以外では渡さない |
+| `component` | 上の対応表でcomponentを持つ変更なら必須 | `kind`、`source`、`id` |
+| `content` | `component`の`kind`が`rule`、`skill`、`agent`、`command`の場合と、componentを持たない場合に必須 | 適用後の`path`のfileの内容全体 |
+| `value` | `component`の`kind`が`hook`、`permissions`、`mcp_server`の場合に必須 | 適用後のそのcomponentのsettingsの値（JSON） |
+| `evidence_session_ids` | ✓ | 根拠のsessionのsession ID（1件以上）。「根拠のsession」に表示されたものだけを使う |
+| `body` | ✓ | 提案の本文（markdown）。根拠、変更、期待する効果、測り方 |
+
+- `harnessforce tune record`が終了コード0で終わった提案だけを表示する。0以外で終わった提案は表示せず、stderrの文言を伝える。
+- 同じ提案は同じ入力で記録する。同じ`category`、`change_type`、`path`、適用後の内容なら、何回記録しても1件として数えられる。
+- 表示では、対象のカテゴリ、根拠、変更の種類、適用先、変更、期待する効果、測り方を、この順に示す。

package/skills/propose-improvements/scripts/summarize.mjs

@@ -0,0 +1,472 @@
+// `/harnessforce:tune`が使う。`harnessforce tune --json`を実行し、分析結果と、提案を作る条件の判定を表示する。
+// 判定はimprovement-loop.md「作る条件」に従う。harnessforceの文言（stderr）と終了コードはそのまま渡す。
+// Node.js 18で依存なしに動かすため、plainなESMで書く。
+import { spawnSync } from "node:child_process";
+
+const USAGE = "使い方: /harnessforce:tune [--all] [--no-send]";
+const HF_MISSING =
+	"`harnessforce`が見つかりません。`/harnessforce:setup`でCLIを導入してください";
+const ALLOWED_FLAGS = new Set(["--all", "--no-send"]);
+
+const MINIMUM_SESSIONS = 10;
+const INTERVENTION_MIN_SESSIONS = 3;
+const INTERVENTION_MIN_COUNT = 10;
+const LOOP_MIN_OCCURRENCES = 3;
+const MCP_MIN_CONFIGURED_SESSIONS = 10;
+const MAX_EVIDENCE = 20;
+const USAGE_MIN_SESSIONS = 3;
+const MODEL_CHOICE_MIN_SESSIONS = 10;
+const MODEL_CHOICE_MIN_SHARE = 0.9;
+// 使い方のうち、sessionごとに判定する種類。model_choiceは分析した範囲の合計で判定する。
+const SESSION_USAGE_KINDS = ["frequent_compaction", "low_cache_reuse"];
+// improvement-loop.md「前回の提案の前後」の「良くなった向き」。model_choiceは向きを持たない。
+const IMPROVES_BY = {
+	"intervention.kind": "decrease",
+	"loop.kind": "decrease",
+	mcp_server: "decrease",
+	"usage.kind=frequent_compaction": "decrease",
+	"usage.kind=low_cache_reuse": "increase",
+};
+
+const INTERVENTION_KINDS = [
+	"approval",
+	"continue",
+	"ci_relay",
+	"review_relay",
+	"answer",
+	"other",
+];
+const LOOP_KINDS = [
+	"issue_to_pr",
+	"ci_fix",
+	"review_response",
+	"test_fix",
+	"lint_fix",
+	"dependency_update",
+];
+
+const median = (values) => {
+	if (values.length === 0) return null;
+	const sorted = [...values].sort((a, b) => a - b);
+	const middle = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 1
+		? sorted[middle]
+		: (sorted[middle - 1] + sorted[middle]) / 2;
+};
+
+const secondsText = (value) => (value === null ? "—" : `${value.toFixed(1)}秒`);
+
+const newestFirst = (a, b) =>
+	a.session.started_at < b.session.started_at
+		? 1
+		: a.session.started_at > b.session.started_at
+			? -1
+			: a.session.session_id.localeCompare(b.session.session_id);
+
+// 計測したsessionだけを合計する。1つも無ければundefined（未計測）とし、0と区別する。
+function measure(sessions, pick, countField, medianField) {
+	const measured = sessions
+		.map((session) => ({ session, value: pick(session.report) }))
+		.filter(({ value }) => value?.measurement === "measured");
+	if (measured.length === 0) return undefined;
+	const hits = measured.filter(({ value }) => value[countField] > 0);
+	return {
+		total: measured.reduce((sum, { value }) => sum + value[countField], 0),
+		median: median(
+			measured
+				.map(({ value }) => value[medianField])
+				.filter((m) => typeof m === "number"),
+		),
+		hits: hits.map(({ session, value }) => ({
+			session,
+			count: value[countField],
+		})),
+		measured,
+	};
+}
+
+function mcpServers(sessions) {
+	const byServer = new Map();
+	for (const session of sessions)
+		for (const element of session.report.mcp_servers ?? []) {
+			const entries = byServer.get(element.server) ?? [];
+			entries.push({ session, element });
+			byServer.set(element.server, entries);
+		}
+	return [...byServer.entries()]
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([server, entries]) => {
+			const configured = entries.filter(({ element }) => element.configured);
+			const sum = (field, measurement) => {
+				const measured = entries.filter(
+					({ element }) => element[measurement] === "measured",
+				);
+				return measured.length === 0
+					? undefined
+					: measured.reduce((total, { element }) => total + element[field], 0);
+			};
+			return {
+				server,
+				configured,
+				calls: sum("calls", "measurement"),
+				failures: sum("failures", "failures_measurement"),
+			};
+		});
+}
+
+function evidenceLines(hits, unit) {
+	const sorted = [...hits].sort(newestFirst);
+	const lines = ["    根拠のsession（新しい順）:"];
+	for (const { session, count } of sorted.slice(0, MAX_EVIDENCE))
+		lines.push(
+			`      ${session.session_id} ${session.started_at} ${session.repository ?? "-"} sendable=${session.sendable} ${count}${unit} ${session.transcript_path}`,
+		);
+	if (sorted.length > MAX_EVIDENCE)
+		lines.push(`      ほか${sorted.length - MAX_EVIDENCE}件`);
+	return lines;
+}
+
+const missing = (parts) =>
+	parts
+		.filter(([amount]) => amount > 0)
+		.map(([amount, unit]) => `${amount}${unit}`)
+		.join("、");
+
+const percent = (share) => `${(share * 100).toFixed(1)}%`;
+
+// `models`（本体）と`subagent_models`の合計を分母にした、modelごとのoutput_tokensの割合。
+// どちらかがnullのsessionは除く。分母が0ならnull。
+function modelShares(sessions) {
+	const counted = sessions.filter(
+		(s) =>
+			s.usage && s.usage.models !== null && s.usage.subagent_models !== null,
+	);
+	const totals = (field) => {
+		const byModel = new Map();
+		for (const s of counted)
+			for (const m of s.usage[field])
+				byModel.set(m.model, (byModel.get(m.model) ?? 0) + m.output_tokens);
+		return byModel;
+	};
+	const main = totals("models");
+	const subagent = totals("subagent_models");
+	const denominator = [...main.values(), ...subagent.values()].reduce(
+		(total, v) => total + v,
+		0,
+	);
+	if (denominator === 0) return null;
+	const shares = (byModel) =>
+		[...byModel]
+			// harnessforce tune の表示（UTF-16 の code unit 順）と並びを揃える。
+			.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+			.map(([model, tokens]) => ({ model, share: tokens / denominator }));
+	return { main: shares(main), subagent: shares(subagent) };
+}
+
+const sharesText = (shares) =>
+	shares === null
+		? "なし"
+		: [
+				...shares.main.map((m) => `本体 ${m.model} ${percent(m.share)}`),
+				...shares.subagent.map(
+					(m) => `subagent ${m.model} ${percent(m.share)}`,
+				),
+			].join("、");
+
+// 「作る条件」の`model_choice`: 分析した範囲の`models`の合計で、output_tokensが最も多いmodelとその割合。
+function topMainModel(sessions) {
+	const byModel = new Map();
+	for (const s of sessions)
+		for (const m of s.usage.models)
+			byModel.set(m.model, (byModel.get(m.model) ?? 0) + m.output_tokens);
+	const total = [...byModel.values()].reduce((sum, v) => sum + v, 0);
+	const [model, tokens] = [...byModel].sort(
+		([a, x], [b, y]) => y - x || a.localeCompare(b),
+	)[0] ?? [undefined, 0];
+	return model === undefined || total === 0
+		? undefined
+		: { model, tokens, share: tokens / total };
+}
+
+const valueText = (value) =>
+	value === null
+		? "値なし"
+		: typeof value === "number"
+			? String(Number(value.toFixed(3)))
+			: sharesText(value);
+
+function improvesBy(category) {
+	return IMPROVES_BY[category] ?? IMPROVES_BY[category.split("=")[0]];
+}
+
+// improvement-loop.md「前回の提案の前後」
+function renderFollowups(followups) {
+	if (!Array.isArray(followups) || followups.length === 0) return [];
+	const lines = [
+		"前回の提案の前後（前後の差（因果を示しません）。起点は適用を検出した時刻です）:",
+	];
+	for (const f of followups) {
+		lines.push(
+			`- ${f.category}（${f.change_type} ${f.path}）起点 ${f.origin}`,
+			`    前 ${f.before.from}〜${f.before.to}: ${f.before.sessions} session、${valueText(f.before.value)}`,
+			`    後 ${f.after.from}〜${f.after.to}: ${f.after.sessions} session、${valueText(f.after.value)}`,
+		);
+		if (f.no_comparison_data) lines.push("    比較データなし");
+		if (f.before_outside_range)
+			lines.push("    前の期間の一部が分析の範囲の外です");
+		const direction = improvesBy(f.category);
+		const isImproved =
+			direction === "decrease"
+				? f.after.value < f.before.value
+				: f.after.value > f.before.value;
+		if (direction !== undefined && !f.no_comparison_data && !isImproved)
+			lines.push(
+				"    良くなった向きへ動いていません。同じ対象の提案を作るときの根拠にします",
+			);
+	}
+	lines.push("");
+	return lines;
+}
+
+function usageTargets(sessions) {
+	const lines = [];
+	// usage を出力しない古い harnessforce の出力では、使い方を未計測として扱い提案を作らない。
+	const withUsage = sessions.filter((s) => s.usage);
+	for (const kind of SESSION_USAGE_KINDS) {
+		const category = `usage.kind=${kind}`;
+		if (withUsage.length === 0) {
+			lines.push(`- ${category}: 未計測のため提案しません`);
+			continue;
+		}
+		const hits = withUsage.filter((s) => s.usage.kinds.includes(kind));
+		if (hits.length < USAGE_MIN_SESSIONS) {
+			lines.push(
+				`- ${category}: データ不足: 当たるsessionが${USAGE_MIN_SESSIONS}以上必要です（あと${USAGE_MIN_SESSIONS - hits.length} session）`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: 提案を作れます（${hits.length} session）`,
+			...evidenceLines(
+				hits.map((session) => ({
+					session,
+					count:
+						kind === "frequent_compaction"
+							? session.usage.compactions_auto
+							: Number(session.usage.cache_reuse_ratio.toFixed(3)),
+				})),
+				kind === "frequent_compaction"
+					? "回の自動圧縮"
+					: "（cacheの再利用の割合）",
+			),
+		);
+	}
+	const category = "usage.kind=model_choice";
+	const withModels = withUsage.filter(
+		(s) => Array.isArray(s.usage.models) && s.usage.models.length > 0,
+	);
+	if (withUsage.length === 0) {
+		lines.push(`- ${category}: 未計測のため提案しません`);
+		return lines;
+	}
+	if (withModels.length < MODEL_CHOICE_MIN_SESSIONS) {
+		lines.push(
+			`- ${category}: データ不足: modelsを持つsessionが${MODEL_CHOICE_MIN_SESSIONS}以上必要です（あと${MODEL_CHOICE_MIN_SESSIONS - withModels.length} session）`,
+		);
+		return lines;
+	}
+	const top = topMainModel(withModels);
+	if (top === undefined || top.share < MODEL_CHOICE_MIN_SHARE) {
+		lines.push(
+			`- ${category}: 提案しません: 1つのmodelが本体のoutput_tokensの${MODEL_CHOICE_MIN_SHARE * 100}%以上を占めていません${top ? `（最大 ${top.model} ${percent(top.share)}）` : ""}`,
+		);
+		return lines;
+	}
+	lines.push(
+		`- ${category}: 提案を作れます（${withModels.length} session、${top.model} ${percent(top.share)}）`,
+		...evidenceLines(
+			withModels.map((session) => ({
+				session,
+				count:
+					session.usage.models.find((m) => m.model === top.model)
+						?.output_tokens ?? 0,
+			})),
+			` output_tokens（${top.model}）`,
+		),
+	);
+	return lines;
+}
+
+function render(output) {
+	const { sessions } = output;
+	const lines = [
+		`分析したsession: ${output.session_count}件（analyzer ${output.analyzer_version}、parser ${output.parser_version}）`,
+		"",
+		"人の介入（回数、介入のあったsession数、待ち時間の中央値）:",
+	];
+	const interventions = INTERVENTION_KINDS.map((kind) => ({
+		kind,
+		result: measure(
+			sessions,
+			(r) => r.interventions?.[kind],
+			"count",
+			"wait_seconds_median",
+		),
+	}));
+	for (const { kind, result } of interventions)
+		lines.push(
+			result === undefined
+				? `  ${kind}: 未計測`
+				: `  ${kind}: ${result.total}回、${result.hits.length} session、${secondsText(result.median)}`,
+		);
+
+	lines.push(
+		"",
+		"ループにできる繰り返し（回数、その間の介入、所要時間の中央値）:",
+	);
+	const loops = LOOP_KINDS.map((kind) => ({
+		kind,
+		result: measure(
+			sessions,
+			(r) => r.loops?.[kind],
+			"occurrences",
+			"duration_seconds_median",
+		),
+	}));
+	for (const { kind, result } of loops) {
+		if (result === undefined) {
+			lines.push(`  ${kind}: 未計測`);
+			continue;
+		}
+		const count = result.measured.reduce(
+			(sum, { value }) => sum + value.interventions,
+			0,
+		);
+		lines.push(
+			`  ${kind}: ${result.total}回、介入${count}回、${secondsText(result.median)}`,
+		);
+	}
+
+	lines.push("", "MCP server（設定されていたsession数、呼び出し、失敗）:");
+	const servers = mcpServers(sessions);
+	if (servers.length === 0) lines.push("  （記録にMCP serverがありません）");
+	for (const s of servers)
+		lines.push(
+			`  ${s.server}: 設定されていたsession ${s.configured.length}件、${s.calls === undefined ? "呼び出し: 未計測" : `呼び出し${s.calls}回`}、${s.failures === undefined ? "失敗: 未計測" : `失敗${s.failures}回`}`,
+		);
+
+	const withUsage = sessions.filter((s) => s.usage);
+	lines.push("", "使い方（当たるsession）:");
+	for (const kind of SESSION_USAGE_KINDS)
+		lines.push(
+			withUsage.length === 0
+				? `  ${kind}: 未計測`
+				: `  ${kind}: ${withUsage.filter((s) => s.usage.kinds.includes(kind)).length} session`,
+		);
+	lines.push(
+		`  model（output_tokensの割合）: ${sharesText(modelShares(withUsage))}`,
+	);
+
+	lines.push("", ...renderFollowups(output.followups));
+	if (!output.sufficient) {
+		lines.push(
+			`データ不足のため提案を作りません: 分析したsessionは${output.session_count}件です。提案には${MINIMUM_SESSIONS}件以上が必要です（あと${MINIMUM_SESSIONS - output.session_count}件）`,
+		);
+		return lines;
+	}
+
+	lines.push("提案の対象:");
+	for (const { kind, result } of interventions) {
+		const category = `intervention.kind=${kind}`;
+		if (result === undefined) {
+			lines.push(`- ${category}: 未計測のため提案しません`);
+			continue;
+		}
+		const lacking = missing([
+			[INTERVENTION_MIN_SESSIONS - result.hits.length, " session"],
+			[INTERVENTION_MIN_COUNT - result.total, "回"],
+		]);
+		if (lacking) {
+			lines.push(
+				`- ${category}: データ不足: ${INTERVENTION_MIN_SESSIONS} session以上で合計${INTERVENTION_MIN_COUNT}回以上が必要です（あと${lacking}）`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: 提案を作れます（${result.hits.length} session、${result.total}回）`,
+			...evidenceLines(result.hits, "回"),
+		);
+	}
+	for (const { kind, result } of loops) {
+		const category = `loop.kind=${kind}`;
+		if (result === undefined) {
+			lines.push(`- ${category}: 未計測のため提案しません`);
+			continue;
+		}
+		if (result.total < LOOP_MIN_OCCURRENCES) {
+			lines.push(
+				`- ${category}: データ不足: 合計${LOOP_MIN_OCCURRENCES}回以上が必要です（あと${LOOP_MIN_OCCURRENCES - result.total}回）`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: 提案を作れます（合計${result.total}回）`,
+			...evidenceLines(result.hits, "回"),
+		);
+	}
+	// unlistedは構成に無いserverをまとめたものであり、設定されていたsessionを持たないため対象にしない。
+	for (const s of servers.filter((server) => server.server !== "unlisted")) {
+		const category = `mcp_server=${s.server}`;
+		if (s.calls === undefined && s.failures === undefined) {
+			lines.push(`- ${category}: 未計測のため提案しません`);
+			continue;
+		}
+		if (s.configured.length < MCP_MIN_CONFIGURED_SESSIONS) {
+			lines.push(
+				`- ${category}: データ不足: 設定されていたsessionが${MCP_MIN_CONFIGURED_SESSIONS}件以上必要です（あと${MCP_MIN_CONFIGURED_SESSIONS - s.configured.length}件）`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: 提案を作れます（設定されていたsession ${s.configured.length}件）`,
+			...evidenceLines(
+				s.configured.map(({ session, element }) => ({
+					session,
+					count: element.calls ?? 0,
+				})),
+				"回の呼び出し",
+			),
+		);
+	}
+	lines.push(...usageTargets(sessions));
+	return lines;
+}
+
+function run(args) {
+	if (!args.every((arg) => ALLOWED_FLAGS.has(arg))) {
+		process.stderr.write(`${USAGE}\n`);
+		return 2;
+	}
+	// Windowsのnpmのharnessforceは.cmdであり、shellを通さないと起動できない。引数は上で許した値だけである。
+	const hf = spawnSync("harnessforce", ["tune", "--json", ...new Set(args)], {
+		stdio: ["ignore", "pipe", "inherit"],
+		encoding: "utf8",
+		maxBuffer: 256 * 1024 * 1024,
+		shell: process.platform === "win32",
+	});
+	if (hf.error?.code === "ENOENT") {
+		process.stderr.write(`${HF_MISSING}\n`);
+		return 1;
+	}
+	const code = hf.status ?? 1;
+	let output;
+	try {
+		output = JSON.parse(hf.stdout);
+	} catch {
+		return code;
+	}
+	process.stdout.write(`${render(output).join("\n")}\n`);
+	return code;
+}
+
+process.exitCode = run(process.argv.slice(2));

package/skills/record-run/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: record-run
+description: HarnessforceのIssue（ENG-42のような識別子）に取り組む作業で、HarnessforceのMCP serverのtoolを使い、このsessionをRunとして登録し、Plan、Decision、Definition of Doneの充足を記録する。Issueに取り組み始めるとき、Issueを指定されずに変更をcommitする作業を始めるとき、方針を変えるとき、作業を終えるときに使う。
+---
+
+# HarnessforceのIssueの作業を記録する
+
+HarnessforceのMCP serverのtoolで、作業をIssueに結び付けて記録する。toolを初めて使うときは、ブラウザでのログインとWorkspaceの選択を求められる。
+
+## 作業の開始時
+
+利用者がIssueを示していなければ、先に下の「Issueを指定されていない場合」に従う。
+
+1. contextにある`harnessforce session_id: <session_id>`の値を`session_id`として渡し、`start_run`でRunを登録する。この行はHarnessforceのpluginがsessionの開始時にcontextへ加える。複数あれば、最後に加えられたものを使う。入力は、Issueの識別子（`issue_identifier`）、`agent`（`claude_code`）、`session_id`とする。作業しているrepository、branch、commitが分かれば併せて渡す。返された`run_id`を終了時まで控えておく。contextにこの行が無い場合は、下の「session IDが無い場合」に従う。
+2. `get_issue`で、Issue、Plan、Definition of Doneを確認する。nativeのIssueなら、下の「nativeのIssueの状態」に従う。Planは状態（現行か`proposed`か）で区別されている。
+3. 現行のPlanも`proposed`のPlanも無ければ、作業の方針を`record_plan`で記録する。本文はmarkdownで書く。
+
+## 作業の途中
+
+- 方針を変えたとき、または選択肢から選んだときは、`record_decision`で記録する。題（`title`）、決めたこと（`decision`）、理由（`rationale`）を必ず書き、検討した選択肢があれば`alternatives`に書く。
+
+## session IDが変わったとき
+
+- contextの最後の`harnessforce session_id:`の値が、直前の`start_run`に渡した値と異なる（会話をforkしたとき、`/clear`したときなど）場合は、作業を続ける前に新しい値で`start_run`をもう1度呼び、返された`run_id`を以後の`complete_run`に使う。
+
+## 作業の終了時
+
+- `complete_run`に`run_id`と、`get_issue`が返したDefinition of Doneの項目ごとの充足（`item_id`と、満たしたなら`met`、満たしていないなら`unmet`）を渡す。Definition of Doneの項目が無い場合は、項目を渡さない。
+
+## Issueを指定されていない場合
+
+利用者がIssueを示さずに作業を始めたら、Issueを作るかを利用者に尋ねる。Issueを作るのは、利用者が承諾した後だけとする。
+
+1. 次のすべてに当たる場合だけ尋ねる。
+   - 利用者がIssueの識別子を示していない。現在のbranch名が`ENG-42`、`eng-42-login`、`gh-45-fix`のような識別子を含み、`get_issue`でそのIssueを解決できたら（`gh-<番号>`は、そのrepositoryの`<owner>/<repo>#<番号>`として渡す）、そのIssueを示されたものとして「作業の開始時」に進み、尋ねない。`not_found`なら識別子が無い場合と同じに扱う。
+   - 作業が変更をcommitするものである。調べもの、質問への回答、計画だけの会話では尋ねない。
+   - contextに`harnessforce session_id:`の行がある。
+   - contextの最後の`harnessforce session_id:`の値ごとに、同じ値で尋ねるのは1回だけとする。利用者が断ったら、同じ値の間は再び尋ねない。forkや`/clear`で値が変わったら、改めて尋ねてよい。
+2. 既存のIssueを先に示す。作業の要約から、Issueのtitleに現れそうな語を最大3つ選び、語ごとに`list_issues`を、`q`を`-status:done,canceled {語}`、`sort`を`updated`として1回ずつ呼ぶ。自由文は複数の語ではそのすべてを含むIssueにだけ一致するため、語を分けて呼ぶ。結果を合わせて重複を除き、更新の新しい順に最大5件を候補として示す。利用者が候補を選んだら、Issueを作らずにそのIssueで「作業の開始時」に進む。
+3. 候補に当たるものが無ければ、作る案を示す。
+   - title: 作業の要約。80文字以内。
+   - 説明: 目的と完了の条件の箇条書き。
+   - Project: `list_projects`を`q`を`status:active`として呼び、1件ならそれを、2件以上なら利用者に選ばせる。0件ならIssueを作らず、その旨を伝える。
+   - titleと説明には、promptの本文、file path、command、secretを写さない。titleは一覧とURLに現れ、説明より広く読まれる。
+   - 外部のIssue管理ツールを使うチームには、「Harnessforceにだけ作られ、外部のツールには書き戻されません」と伝える。
+4. 利用者が案を承諾した場合だけ、`create_issue`でIssueを作り、返されたidentifierで「作業の開始時」の`start_run`を呼ぶ。利用者が案を直したら、直した値で作る。承諾は会話の中の利用者の明示の返答とする。非対話の実行や利用者のいない自動の実行では、返答を得られないため作らない。
+5. 作れない場合と失敗した場合:
+   - `create_issue`か、候補を選んだ後の`start_run`が`forbidden`（Viewerのtoken、閲覧のみのWorkspaceの`workspace_read_only`を含む）を返したら、作れない理由をそのまま伝え、同じsession IDでは再び尋ねない。
+   - `create_issue`を再試行しない。再試行するとIssueが2件作られうる。timeoutなどで結果が分からなければ、`list_issues`で案のtitleを自由文に検索し、titleが完全に一致し、作成時刻が呼び出しの後のIssueが見つかればそれを使う。見つからなければ、作れなかったことを伝える。
+   - `create_issue`が成功して`start_run`だけが失敗したら、作ったIssueのidentifierを伝え、Issueを作り直さない。
+6. `create_project`、`create_milestone`、`create_cycle`、`create_objective`を自らの判断で呼ばない。目標日、所属、Priority、Assigneeも自ら変えない。これらは計画の変更であり、利用者が会話の中で明示に指示した場合だけ、指示どおりに呼ぶ。
+
+## nativeのIssueの状態
+
+- nativeのIssue（`get_issue`の`external`が`null`のIssue）で、作業を始めた時点の状態が`backlog`か`unstarted`なら、`start_run`の後に「状態を『進行中』にしますか」と尋ね、承諾した場合だけ`update_issue`で状態を`started`に変える。`update_issue`には、`get_issue`が返したIssueの`version`（`definition_of_done.version`ではない）と、変えない他の属性の現在の値を併せて渡す。
+- 作業を終える時点で、利用者が仕事の完了を示していれば、`complete_run`の後に「状態を『完了』にしますか」と尋ね、承諾した場合だけ状態を`done`に変える。Pull Requestを開いただけで、mergeされていない場合は尋ねない。
+- 外部由来のIssueの状態は変えない。状態の正本は外部のツールである。GitHub IssuesのIssueでは、利用者がPull Requestの本文を書く際の文面として`Closes #<番号>`を提案してよい。agentがPull RequestとIssueを自ら結び付ける操作の代わりにはしない。
+- `update_issue`が`conflict`を返したら、`get_issue`で読み直して伝え、1回だけ尋ね直す。再び`conflict`なら、そのことを伝えて終える。
+
+## session IDが無い場合
+
+- contextに`harnessforce session_id:`の行が無ければ、session IDを推測して渡さず、`start_run`と`complete_run`を呼ばない。`get_issue`、`record_plan`、`record_decision`はRunに依らないため続ける。利用者には「Harnessforceのhookが動いていないため、Runを記録できません。`/harnessforce:setup`を実行してください」と1回だけ伝える。
+
+## 記録の扱い
+
+- agentが記録したPlan、Decision、充足は`proposed`として保存され、人が承認するまで確定しない。記録したことを、確定したこととして利用者へ伝えない。