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

package/scripts/harnessforce-hook.cjs

@@ -0,0 +1,23 @@
+// 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(
+			// biome-ignore lint/style/useTemplate: 古いNode.jsがES5として解析できる形を保つ。templateリテラルはES2015である。
+			JSON.stringify({
+				systemMessage: "Harnessforce hooks require Node.js 18 or later",
+			}) + "\n"
+		);
+	}
+}

package/skills/propose-improvements/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: propose-improvements
+description: From the analysis results of /harnessforce:tune, make suggested improvements for human interventions, repeatable loops, MCP servers, and usage (context compaction, cache reuse, model choice), record them with harnessforce tune record, and then show them. Use it only for targets that /harnessforce:tune marks as "a suggestion can be made". Does not modify files.
+---
+
+# Make improvement suggestions from the analysis results
+
+For each target marked "a suggestion can be made" in the "Targets for suggestions" printed by `summarize.mjs` of `/harnessforce:tune`, make a suggestion. Make each suggestion in a form the user can apply as it is, and record it before showing it.
+
+## Do not modify anything
+
+- Do not modify the user's files, settings, repository, or managed settings. Do not use the Edit or Write tools, `git apply`, `git commit`, creating a branch, or `gh pr create`. The diff and the Pull Request draft are only shown.
+- The only thing written is the record that `harnessforce tune record` writes to `~/.harnessforce/tune/`. Do not create temporary files either.
+
+## Conditions for making a suggestion
+
+The result of `summarize.mjs` is authoritative. Make no suggestion for a target marked "Not enough data" or "not measured, so no suggestion is made". The conditions are as follows.
+
+| Target | Minimum condition for a suggestion |
+| --- | --- |
+| All | The analyzed range has at least 10 sessions |
+| Human interventions | That `intervention.kind` appears in at least 3 sessions and at least 10 times in total |
+| Repeatable loops | That `loop.kind` appears at least 3 times in total |
+| MCP servers | At least 10 sessions have `configured` |
+| `frequent_compaction` and `low_cache_reuse` of usage | At least 3 sessions match that `usage.kind` |
+| `model_choice` of usage | At least 10 sessions have `models`, and in the total of `models` over the analyzed range, one `message.model` value accounts for at least 90% of the total `output_tokens` |
+
+- Do not use a value that was not measured (`not_measured`) as evidence. Do not treat "not measured" as 0.
+- The change type of a usage suggestion is limited to `claude_md`, `rule`, `skill`, `agent`, and `command` (for example, split up a bloated CLAUDE.md, or move exploration to a subagent and specify that agent's `model`). Do not use another change type such as the `model` in settings. `harnessforce tune record` rejects other change types. A change to `claude_md` is not detected when applied, so it does not appear in the before and after of the previous suggestion either.
+- Usage values (`usage`) stay on this device and are not sent to Harnessforce. You may use them as evidence for a suggestion.
+- Do not make a suggestion about the harness configuration itself (differences in results between skills, rules, agents, commands, hooks, MCP servers, and model versions).
+- If you investigate and find no change the user can apply as it is, make no suggestion for that target and say why in one line.
+
+## Gather evidence
+
+- Read only the parts you need of the record at the `transcript_path` of the target's evidence sessions. For human interventions, read the prompts of that kind and the agent response just before them. For loops, read the steps of one cycle (fetching the Issue, fixing, testing, pushing, creating the Pull Request, and so on) and the points where a person intervened. For MCP servers, read the calls and failures. For usage, read the instructions and the course of events before compaction for `frequent_compaction`, the responses before and after where the cache was not reused for `low_cache_reuse`, and the exploration and routine work done by the main agent for `model_choice`.
+- When you make a suggestion for the same target as a suggestion that "Before and after the previous suggestion" shows as "Did not move in the improving direction", cite that before and after as evidence and do not repeat the same diff as last time.
+- Read the current definition of the target (settings, skill, rule, agent, command, hook, `.mcp.json`, `mcpServers` in `~/.claude.json`, CLAUDE.md) and make the diff against the current content.
+
+## Format
+
+Give each suggestion the following.
+
+| Item | Content |
+| --- | --- |
+| Target category | One of `intervention.kind=<kind>`, `loop.kind=<kind>`, `mcp_server=<identifier>`, `usage.kind=<kind>`. The `<kind>` of `usage.kind` is one of `frequent_compaction`, `low_cache_reuse`, `model_choice` |
+| Evidence | The period, the counts, the times of the matching sessions, and excerpts of the records. Excerpts are shown on this device only |
+| Change type | One of `permissions`, `hook`, `skill`, `rule`, `agent`, `command`, `loop_prompt`, `mcp_config`, `claude_md` |
+| Apply to | The user scope, the repository scope, or managed settings, and the file path |
+| Change | A unified diff that can be applied as it is. For the repository scope, a Pull Request draft made of the branch name, the title, the body, and the diff. For managed settings, the diff that an Owner or Admin pastes |
+| Expected effect | Which category value decreases, and which existing metric (CI failure rate, rework rate, cost per completed Issue) changes |
+| How to measure | The ComponentVersion that changes when applied (kind and identifier), and the metric used for comparison |
+
+The change type and the component that changes when applied correspond as follows.
+
+| Change type | Component `kind` | Component identifier (`id`) | Expected content |
+| --- | --- | --- | --- |
+| `permissions` | `permissions` | `permissions` | The whole `permissions` value of the settings after applying (`value`) |
+| `hook` | `hook` | The event name of the hook | The value of that event under `hooks` in the settings after applying (`value`) |
+| `skill` | `skill` | The directory name of the skill | The whole content of `SKILL.md` after applying (`content`) |
+| `rule` | `rule` | `CLAUDE.md` or `rules/<path>` | The whole content of the file after applying (`content`) |
+| `agent` | `agent` | The path from `agents/` without `.md`, with `/` replaced by `:` | The whole content of the file after applying (`content`) |
+| `command` | `command` | The path from `commands/` without `.md`, with `/` replaced by `:` | The whole content of the file after applying (`content`) |
+| `loop_prompt` | `command` or `skill`, following the format of the file written | Same as `command` or `skill` above | The whole content of the file after applying (`content`) |
+| `mcp_config` | `mcp_server` (a diff that deletes the server has no component) | The server name | The definition of the server after applying (`value`). For deletion, the whole content of the file after applying (`content`) |
+| `claude_md` | None | None | The whole content of CLAUDE.md after applying (`content`) |
+
+The component `source` is the scope it applies to (`user`, `repository`, `local`, `managed`). A server in `.mcp.json` is `repository`, the top-level `mcpServers` of `~/.claude.json` is `user`, and the one under its `projects` is `local`.
+
+## Suggestions to reduce permissions
+
+- A suggestion to reduce answers to permission prompts takes the tools that asked for confirmation and the breakdown of their permissions as evidence. Allow only the smallest range of tools and commands that appeared in the evidence (for example `Bash(pnpm test:*)`, `Bash(git status)`, `mcp__github__get_issue`).
+- Do not suggest a rule that allows all commands. Do not include in any suggestion a permission for a whole tool or all commands such as `Bash`, `Bash(*)`, `Bash(:*)`, or `*`, nor `"defaultMode": "bypassPermissions"` or `--dangerously-skip-permissions`.
+
+## Suggestions for loops
+
+- A suggestion for a repeatable loop is a prompt in the form of a command or a skill (`loop_prompt`), and it must include stopping conditions. The stopping conditions are both the maximum number of repetitions and the points where a person checks (for example before creating a Pull Request, or when the same failure happens twice in a row).
+- In the prompt, replace each point where a person intervened in the evidence sessions with either a stopping condition or a step the agent does by itself.
+
+## Record, then show
+
+Before showing a suggestion, run `harnessforce tune record` for each suggestion and pass one UTF-8 JSON object on stdin. Pass the input with a heredoc and do not write it to a file. Use a delimiter word that does not appear in the input.
+
+```sh
+harnessforce tune record <<'HF_TUNE_RECORD_7f3c'
+{"category": "...", "change_type": "...", "scope": "...", "path": "...", "evidence_session_ids": ["..."], "body": "..."}
+HF_TUNE_RECORD_7f3c
+```
+
+| Item | Required | Content |
+| --- | --- | --- |
+| `category` | yes | The target category |
+| `change_type` | yes | The change type |
+| `scope` | yes | One of `user`, `repository`, `local`, `managed` |
+| `path` | yes | The absolute path of the file the change writes |
+| `project_root` | required when `scope` is `repository` or `local` | The absolute path of the root of the repository it applies to. Do not pass it otherwise |
+| `component` | required for a change that has a component in the table above | `kind`, `source`, `id` |
+| `content` | required when the `kind` of `component` is `rule`, `skill`, `agent`, or `command`, and when there is no component | The whole content of the file at `path` after applying |
+| `value` | required when the `kind` of `component` is `hook`, `permissions`, or `mcp_server` | The settings value (JSON) of that component after applying |
+| `evidence_session_ids` | yes | The session IDs of the evidence sessions (at least 1). Use only those shown in the evidence sessions |
+| `body` | yes | The body of the suggestion (markdown): the evidence, the change, the expected effect, and how to measure |
+
+- Show only the suggestions for which `harnessforce tune record` ended with exit code 0. Do not show a suggestion that ended with a non-zero code, and tell the user the message on stderr.
+- Record the same suggestion with the same input. With the same `category`, `change_type`, `path`, and content after applying, it counts as one no matter how many times it is recorded.
+- When showing, present the target category, the evidence, the change type, where to apply, the change, the expected effect, and how to measure, in this order.

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

@@ -0,0 +1,474 @@
+// `/harnessforce:tune`が使う。`harnessforce tune --json`を実行し、分析結果と、提案を作る条件の判定を表示する。
+// 判定はimprovement-loop.md「作る条件」に従う。harnessforceの文言（stderr）と終了コードはそのまま渡す。
+// Node.js 18で依存なしに動かすため、plainなESMで書く。
+import { spawnSync } from "node:child_process";
+
+const USAGE = "Usage: /harnessforce:tune [--all] [--no-send]";
+const HF_MISSING =
+	"`harnessforce` was not found. Install the CLI with `/harnessforce:setup`";
+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)}s`);
+
+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 = ["    Evidence sessions (newest first):"];
+	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(`      and ${sorted.length - MAX_EVIDENCE} more`);
+	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
+		? "none"
+		: [
+				...shares.main.map((m) => `main ${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
+		? "no value"
+		: 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 = [
+		"Before and after the previous suggestion (Before/after difference (does not show causation). The starting point is the time the application was detected):",
+	];
+	for (const f of followups) {
+		lines.push(
+			`- ${f.category} (${f.change_type} ${f.path}) starting point ${f.origin}`,
+			`    Before ${f.before.from} to ${f.before.to}: ${f.before.sessions} session(s), ${valueText(f.before.value)}`,
+			`    After ${f.after.from} to ${f.after.to}: ${f.after.sessions} session(s), ${valueText(f.after.value)}`,
+		);
+		if (f.no_comparison_data) lines.push("    No comparison data");
+		if (f.before_outside_range)
+			lines.push(
+				"    Part of the earlier period is outside the analysis range",
+			);
+		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(
+				"    Did not move in the improving direction. Use this as the basis when making a suggestion for the same target",
+			);
+	}
+	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}: not measured, so no suggestion is made`);
+			continue;
+		}
+		const hits = withUsage.filter((s) => s.usage.kinds.includes(kind));
+		if (hits.length < USAGE_MIN_SESSIONS) {
+			lines.push(
+				`- ${category}: Not enough data: needs at least ${USAGE_MIN_SESSIONS} matching sessions (${USAGE_MIN_SESSIONS - hits.length} more session(s) needed)`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: a suggestion can be made (${hits.length} session(s))`,
+			...evidenceLines(
+				hits.map((session) => ({
+					session,
+					count:
+						kind === "frequent_compaction"
+							? session.usage.compactions_auto
+							: Number(session.usage.cache_reuse_ratio.toFixed(3)),
+				})),
+				kind === "frequent_compaction"
+					? " auto-compaction(s)"
+					: " (cache reuse ratio)",
+			),
+		);
+	}
+	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}: not measured, so no suggestion is made`);
+		return lines;
+	}
+	if (withModels.length < MODEL_CHOICE_MIN_SESSIONS) {
+		lines.push(
+			`- ${category}: Not enough data: needs at least ${MODEL_CHOICE_MIN_SESSIONS} sessions with models (${MODEL_CHOICE_MIN_SESSIONS - withModels.length} more session(s) needed)`,
+		);
+		return lines;
+	}
+	const top = topMainModel(withModels);
+	if (top === undefined || top.share < MODEL_CHOICE_MIN_SHARE) {
+		lines.push(
+			`- ${category}: not suggested: no single model accounts for ${MODEL_CHOICE_MIN_SHARE * 100}% or more of the main output_tokens${top ? ` (largest: ${top.model} ${percent(top.share)})` : ""}`,
+		);
+		return lines;
+	}
+	lines.push(
+		`- ${category}: a suggestion can be made (${withModels.length} session(s), ${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 = [
+		`Sessions analyzed: ${output.session_count} (analyzer ${output.analyzer_version}, parser ${output.parser_version})`,
+		"",
+		"Human interventions (count, sessions with interventions, median wait time):",
+	];
+	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}: not measured`
+				: `  ${kind}: ${result.total} time(s), ${result.hits.length} session(s), ${secondsText(result.median)}`,
+		);
+
+	lines.push(
+		"",
+		"Repeatable loops (count, interventions during them, median duration):",
+	);
+	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}: not measured`);
+			continue;
+		}
+		const count = result.measured.reduce(
+			(sum, { value }) => sum + value.interventions,
+			0,
+		);
+		lines.push(
+			`  ${kind}: ${result.total} time(s), ${count} intervention(s), ${secondsText(result.median)}`,
+		);
+	}
+
+	lines.push("", "MCP servers (sessions where configured, calls, failures):");
+	const servers = mcpServers(sessions);
+	if (servers.length === 0) lines.push("  (no MCP servers in the records)");
+	for (const s of servers)
+		lines.push(
+			`  ${s.server}: configured in ${s.configured.length} session(s), ${s.calls === undefined ? "calls: not measured" : `${s.calls} call(s)`}, ${s.failures === undefined ? "failures: not measured" : `${s.failures} failure(s)`}`,
+		);
+
+	const withUsage = sessions.filter((s) => s.usage);
+	lines.push("", "Usage (matching sessions):");
+	for (const kind of SESSION_USAGE_KINDS)
+		lines.push(
+			withUsage.length === 0
+				? `  ${kind}: not measured`
+				: `  ${kind}: ${withUsage.filter((s) => s.usage.kinds.includes(kind)).length} session(s)`,
+		);
+	lines.push(
+		`  model (share of output_tokens): ${sharesText(modelShares(withUsage))}`,
+	);
+
+	lines.push("", ...renderFollowups(output.followups));
+	if (!output.sufficient) {
+		lines.push(
+			`Not enough data, so no suggestions are made: ${output.session_count} session(s) analyzed. Suggestions need at least ${MINIMUM_SESSIONS} (${MINIMUM_SESSIONS - output.session_count} more needed)`,
+		);
+		return lines;
+	}
+
+	lines.push("Targets for suggestions:");
+	for (const { kind, result } of interventions) {
+		const category = `intervention.kind=${kind}`;
+		if (result === undefined) {
+			lines.push(`- ${category}: not measured, so no suggestion is made`);
+			continue;
+		}
+		const lacking = missing([
+			[INTERVENTION_MIN_SESSIONS - result.hits.length, " session(s)"],
+			[INTERVENTION_MIN_COUNT - result.total, " time(s)"],
+		]);
+		if (lacking) {
+			lines.push(
+				`- ${category}: Not enough data: needs at least ${INTERVENTION_MIN_SESSIONS} sessions and at least ${INTERVENTION_MIN_COUNT} times in total (${lacking} more needed)`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: a suggestion can be made (${result.hits.length} session(s), ${result.total} time(s))`,
+			...evidenceLines(result.hits, " time(s)"),
+		);
+	}
+	for (const { kind, result } of loops) {
+		const category = `loop.kind=${kind}`;
+		if (result === undefined) {
+			lines.push(`- ${category}: not measured, so no suggestion is made`);
+			continue;
+		}
+		if (result.total < LOOP_MIN_OCCURRENCES) {
+			lines.push(
+				`- ${category}: Not enough data: needs at least ${LOOP_MIN_OCCURRENCES} times in total (${LOOP_MIN_OCCURRENCES - result.total} more needed)`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: a suggestion can be made (${result.total} time(s) in total)`,
+			...evidenceLines(result.hits, " time(s)"),
+		);
+	}
+	// 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}: not measured, so no suggestion is made`);
+			continue;
+		}
+		if (s.configured.length < MCP_MIN_CONFIGURED_SESSIONS) {
+			lines.push(
+				`- ${category}: Not enough data: needs at least ${MCP_MIN_CONFIGURED_SESSIONS} sessions where it was configured (${MCP_MIN_CONFIGURED_SESSIONS - s.configured.length} more needed)`,
+			);
+			continue;
+		}
+		lines.push(
+			`- ${category}: a suggestion can be made (configured in ${s.configured.length} session(s))`,
+			...evidenceLines(
+				s.configured.map(({ session, element }) => ({
+					session,
+					count: element.calls ?? 0,
+				})),
+				" call(s)",
+			),
+		);
+	}
+	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,29 @@
+---
+name: record-run
+description: For work on a Harnessforce Issue (an identifier such as ENG-42), use the tools of the Harnessforce MCP server to register this session as a Run and to close the Run when the work ends. Use it when you start work on an Issue and when you finish the work.
+---
+
+# Record work on a Harnessforce Issue
+
+Use the tools of the Harnessforce MCP server to link the work to the Issue. The first time you use a tool, you are asked to log in in the browser and choose a Workspace.
+
+## At the start of the work
+
+1. Pass the value of `harnessforce session_id: <session_id>` in the context as `session_id`, and register the Run with `start_run`. The Harnessforce plugin adds this line to the context at session start. If there are several, use the last one added. The input is the Issue identifier (`issue_identifier`), `agent` (`claude_code`), and `session_id`. If you know the repository, branch, and commit you are working on, pass them too. Keep the returned `run_id` until the end. If the line is missing from the context, follow "When the session ID is missing" below.
+2. Check the Issue with `get_issue`.
+
+## When the session ID changes
+
+- If the value of the last `harnessforce session_id:` in the context differs from the value you passed to the previous `start_run` (for example after forking the conversation or running `/clear`), call `start_run` once more with the new value before continuing, and use the returned `run_id` for later `complete_run` calls.
+
+## At the end of the work
+
+- Call `complete_run` with the `run_id`.
+
+## When the session ID is missing
+
+- If the context has no `harnessforce session_id:` line, do not guess and pass a session ID, and do not call `start_run` or `complete_run`. `get_issue` does not depend on the Run, so continue with it. Tell the user once: "The Harnessforce hook is not running, so the Run cannot be recorded. Run `/harnessforce:setup`".
+
+## What is not recorded
+
+- Harnessforce does not record a Plan, a Decision, or a Definition of Done, and the Harnessforce tools do not create or edit Issues. Issues are GitHub Issues. Harnessforce shows the sessions, Pull Requests, and CI results linked to an Issue without any record from you.