claude-attribution 1.2.4 → 1.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-attribution",
-	"version": "1.2.4",
+	"version": "1.2.7",
 	"description": "AI code attribution tracking for Claude Code sessions — checkpoint-based line diff approach",
 	"type": "module",
 	"bin": {

package/src/hooks/post-tool-use.ts

@@ -45,12 +45,21 @@ async function main() {
 	const { session_id, tool_name, tool_input } = payload;
 	const repoRoot = resolve(process.cwd());
 
-	// Log every tool call
-	const logEntry = {
+	// Log every tool call. For Skill invocations, also capture the skill name
+	// so metrics can show "/pr" instead of the generic "Skill ×1".
+	const logEntry: {
+		timestamp: string;
+		session: string;
+		tool: string;
+		skill?: string;
+	} = {
 		timestamp: new Date().toISOString(),
 		session: session_id,
 		tool: tool_name,
 	};
+	if (tool_name === "Skill" && typeof tool_input["skill"] === "string") {
+		logEntry.skill = tool_input["skill"];
+	}
 
 	try {
 		const logDir = join(repoRoot, ".claude", "logs");

package/src/metrics/collect.ts

@@ -29,8 +29,11 @@ const execFileAsync = promisify(execFile);
 export interface MetricsData {
 	repoRoot: string;
 	sessionId: string;
+	/** Notable non-file-op tools used (Bash, Read, Write, Edit etc. excluded). */
 	toolCounts: Map<string, number>;
 	agentCounts: Map<string, number>;
+	/** Slash command skills invoked (e.g. ["pr", "metrics"]). */
+	skillNames: string[];
 	transcript: TranscriptResult | null;
 	attributions: AttributionResult[];
 	lastSeenByFile: Map<string, FileAttribution>;
@@ -43,6 +46,44 @@ export interface MetricsData {
 	} | null;
 }
 
+/**
+ * Tools that are routine file/task operations — excluded from the metrics
+ * display because they add noise without conveying meaningful intent.
+ * Skill invocations are tracked separately by skill name.
+ */
+const BORING_TOOLS = new Set([
+	// File operations
+	"Read",
+	"Write",
+	"Edit",
+	"Glob",
+	"Grep",
+	"NotebookEdit",
+	"MultiEdit",
+	// Task/todo management
+	"TaskCreate",
+	"TaskUpdate",
+	"TaskGet",
+	"TaskList",
+	"TaskOutput",
+	"TaskStop",
+	// Planning & worktree lifecycle
+	"EnterPlanMode",
+	"ExitPlanMode",
+	"EnterWorktree",
+	"ExitWorktree",
+	// Cron
+	"CronCreate",
+	"CronDelete",
+	"CronList",
+	// Shell (too generic — any meaningful external calls are implicit in the PR)
+	"Bash",
+	// Skill is tracked by name in skillNames, not toolCounts
+	"Skill",
+	// Agent is tracked in agentCounts via agent-activity.jsonl
+	"Agent",
+]);
+
 async function readSessionStart(repoRoot: string): Promise<Date | null> {
 	const markerPath = join(
 		repoRoot,
@@ -201,7 +242,7 @@ export async function collectMetrics(
 				join(logDir, "tool-usage.jsonl"),
 				sessionId,
 				sessionStart ?? undefined,
-			) as Promise<{ tool?: string }[]>,
+			) as Promise<{ tool?: string; skill?: string }[]>,
 			readJsonlForSession(
 				join(logDir, "agent-activity.jsonl"),
 				sessionId,
@@ -212,10 +253,18 @@ export async function collectMetrics(
 			getMinimapTotals(root),
 		]);
 
-	// Tool counts
+	// Tool counts — skip boring file ops and infrastructure tools.
+	// Skill invocations are tracked separately by name.
 	const toolCounts = new Map<string, number>();
+	const skillNames: string[] = [];
 	for (const e of toolEntries) {
-		if (e.tool) toolCounts.set(e.tool, (toolCounts.get(e.tool) ?? 0) + 1);
+		if (!e.tool) continue;
+		if (e.tool === "Skill") {
+			if (e.skill) skillNames.push(e.skill);
+			continue;
+		}
+		if (BORING_TOOLS.has(e.tool)) continue;
+		toolCounts.set(e.tool, (toolCounts.get(e.tool) ?? 0) + 1);
 	}
 
 	// Agent counts (SubagentStart events only)
@@ -261,6 +310,7 @@ export async function collectMetrics(
 		sessionId,
 		toolCounts,
 		agentCounts,
+		skillNames,
 		transcript,
 		attributions,
 		lastSeenByFile,
@@ -269,11 +319,36 @@ export async function collectMetrics(
 	};
 }
 
+/** Format a session time summary. Returns empty string when no time data. */
+function formatSessionLine(transcript: TranscriptResult): string {
+	const parts: string[] = [];
+
+	parts.push(
+		`${transcript.humanPromptCount} prompt${transcript.humanPromptCount === 1 ? "" : "s"}`,
+	);
+
+	const {
+		activeMinutes: total,
+		aiMinutes: ai,
+		humanMinutes: human,
+	} = transcript;
+	if (total > 0) {
+		if (human > 0) {
+			parts.push(`${total}m total (${ai}m AI · ${human}m human)`);
+		} else {
+			parts.push(`${total}m`);
+		}
+	}
+
+	return parts.join(" · ");
+}
+
 export function renderMetrics(data: MetricsData): string {
 	const {
 		repoRoot,
 		toolCounts,
 		agentCounts,
+		skillNames,
 		transcript,
 		lastSeenByFile,
 		allTranscripts,
@@ -286,7 +361,7 @@ export function renderMetrics(data: MetricsData): string {
 	out("## Claude Code Metrics");
 	out();
 
-	// Headline: AI% + active time (most important stat, shown first)
+	// Headline: AI% (most important stat, shown first)
 	const allFileStats = [...lastSeenByFile.values()];
 	const hasAttribution = allFileStats.length > 0;
 	if (minimapTotals && minimapTotals.total > 0) {
@@ -304,30 +379,26 @@ export function renderMetrics(data: MetricsData): string {
 				minimapTotals.total > 0
 					? Math.round((prTotal / minimapTotals.total) * 100)
 					: 0;
-			const activePart =
-				transcript && transcript.activeMinutes > 0
-					? ` · Active: ${transcript.activeMinutes}m`
-					: "";
 			out(
-				`**This PR:** ${prTotal} lines changed (${codebasePct}% of codebase) · ${prPctAi}% Claude edits · ${prAi} AI lines${activePart}`,
+				`**This PR:** ${prTotal} lines changed (${codebasePct}% of codebase) · ${prPctAi}% Claude edits · ${prAi} AI lines`,
 			);
 		}
 		out();
 	} else if (hasAttribution) {
 		const { ai, total, pctAi } = aggregateTotals(allFileStats);
-		const activePart =
-			transcript && transcript.activeMinutes > 0
-				? ` · Active: ${transcript.activeMinutes}m`
-				: "";
-		out(
-			`**AI contribution: ~${pctAi}%** (${ai} of ${total} committed lines)${activePart}`,
-		);
-		out();
-	} else if (transcript && transcript.activeMinutes > 0) {
-		out(`**Active session time:** ${transcript.activeMinutes}m`);
+		out(`**AI contribution: ~${pctAi}%** (${ai} of ${total} committed lines)`);
 		out();
 	}
 
+	// Session: prompts + time breakdown
+	if (transcript) {
+		const sessionLine = formatSessionLine(transcript);
+		if (sessionLine) {
+			out(`**Session:** ${sessionLine}`);
+			out();
+		}
+	}
+
 	// Model usage table
 	if (transcript) {
 		out("| Model | Calls | Input | Output | Cache |");
@@ -344,8 +415,6 @@ export function renderMetrics(data: MetricsData): string {
 			`| **Total** | ${t.totalCalls} | ${kFormat(t.totalInputTokens)} | ${kFormat(t.totalOutputTokens)} | ${kFormat(totalCache)} |`,
 		);
 		out();
-		out(`**Human prompts (steering effort):** ${transcript.humanPromptCount}`);
-		out();
 	}
 
 	// Multi-session rollup (shown when multiple Claude sessions contributed)
@@ -362,6 +431,8 @@ export function renderMetrics(data: MetricsData): string {
 					t.totals.totalCacheCreationTokens +
 					t.totals.totalCacheReadTokens,
 				humanPromptCount: acc.humanPromptCount + t.humanPromptCount,
+				aiMinutes: acc.aiMinutes + t.aiMinutes,
+				humanMinutes: acc.humanMinutes + t.humanMinutes,
 				activeMinutes: acc.activeMinutes + t.activeMinutes,
 			}),
 			{
@@ -370,6 +441,8 @@ export function renderMetrics(data: MetricsData): string {
 				totalOutputTokens: 0,
 				totalCacheTokens: 0,
 				humanPromptCount: 0,
+				aiMinutes: 0,
+				humanMinutes: 0,
 				activeMinutes: 0,
 			},
 		);
@@ -379,24 +452,35 @@ export function renderMetrics(data: MetricsData): string {
 			`| ${agg.totalCalls} | ${kFormat(agg.totalInputTokens)} | ${kFormat(agg.totalOutputTokens)} | ${kFormat(agg.totalCacheTokens)} |`,
 		);
 		out();
-		out(`**Total human prompts:** ${agg.humanPromptCount}`);
-		if (agg.activeMinutes > 0) {
-			out(`**Total active session time:** ${agg.activeMinutes}m`);
+		const aggSessionLine = [
+			`${agg.humanPromptCount} prompt${agg.humanPromptCount === 1 ? "" : "s"}`,
+			...(agg.activeMinutes > 0
+				? agg.humanMinutes > 0
+					? [
+							`${agg.activeMinutes}m total (${agg.aiMinutes}m AI · ${agg.humanMinutes}m human)`,
+						]
+					: [`${agg.activeMinutes}m`]
+				: []),
+		].join(" · ");
+		if (aggSessionLine) {
+			out(`**Total session:** ${aggSessionLine}`);
 		}
 		out();
 	}
 
-	// <details> block — tools, agents, per-file breakdown
+	// <details> block — skills, agents, notable tools, per-file breakdown
 	const claudeFiles = [...lastSeenByFile.entries()].filter(
 		([, stats]) => stats.ai > 0 || stats.mixed > 0,
 	);
-	const hasTools = toolCounts.size > 0;
+	const hasSkills = skillNames.length > 0;
 	const hasAgents = agentCounts.size > 0;
+	const hasNotableTools = toolCounts.size > 0;
 	const hasFiles = claudeFiles.length > 0;
 
 	const summaryParts: string[] = [];
-	if (hasTools) summaryParts.push("Tools");
+	if (hasSkills) summaryParts.push("Skills");
 	if (hasAgents) summaryParts.push("Agents");
+	if (hasNotableTools) summaryParts.push("Tools");
 	if (hasFiles) summaryParts.push("Files");
 	if (summaryParts.length === 0) summaryParts.push("Details");
 
@@ -404,27 +488,36 @@ export function renderMetrics(data: MetricsData): string {
 	out(`<summary>${summaryParts.join(" · ")}</summary>`);
 	out();
 
-	if (hasTools) {
-		const toolLine = [...toolCounts.entries()]
-			.sort((a, b) => b[1] - a[1])
-			.map(([tool, count]) => `${tool} ×${count}`)
-			.join(", ");
-		out(`**Tools:** ${toolLine}`);
-		out();
-	} else {
-		out("_No tool usage logs found_");
+	if (hasSkills) {
+		// Deduplicate and show slash command names
+		const unique = [...new Set(skillNames)];
+		out(`**Skills:** ${unique.map((s) => `/${s}`).join(", ")}`);
 		out();
 	}
 
 	if (hasAgents) {
 		const agentLine = [...agentCounts.entries()]
 			.sort((a, b) => b[1] - a[1])
-			.map(([agent, count]) => `${agent} ×${count}`)
+			.map(([agent, count]) => (count > 1 ? `${agent} ×${count}` : agent))
 			.join(", ");
 		out(`**Agents:** ${agentLine}`);
 		out();
 	}
 
+	if (hasNotableTools) {
+		const toolLine = [...toolCounts.entries()]
+			.sort((a, b) => b[1] - a[1])
+			.map(([tool, count]) => (count > 1 ? `${tool} ×${count}` : tool))
+			.join(", ");
+		out(`**External tools:** ${toolLine}`);
+		out();
+	}
+
+	if (!hasSkills && !hasAgents && !hasNotableTools) {
+		out("_No tool usage logs found_");
+		out();
+	}
+
 	if (hasFiles) {
 		out("#### Files");
 		out();

package/src/metrics/transcript.ts

@@ -12,7 +12,7 @@
  *   ~/.claude/projects/<project-key>/<session-id>/subagents/<agent-id>.jsonl
  *
  * This module reads both main and subagent transcripts, merges them by model,
- * and returns aggregated token/model usage + human prompt count.
+ * and returns aggregated token/model usage + human prompt count + time breakdown.
  */
 import { readFile, readdir } from "fs/promises";
 import { existsSync } from "fs";
@@ -40,8 +40,12 @@ export interface TranscriptResult {
 		totalCacheReadTokens: number;
 	};
 	humanPromptCount: number;
-	/** Active session time in minutes (idle gaps >15 min are excluded). */
+	/** Total active session time in minutes (idle gaps >15 min excluded). */
 	activeMinutes: number;
+	/** Minutes Claude was actively processing (human→assistant gaps). */
+	aiMinutes: number;
+	/** Minutes the human was active between Claude responses (>30s gaps, <15m). */
+	humanMinutes: number;
 }
 
 interface TranscriptEntry {
@@ -58,6 +62,11 @@ interface TranscriptEntry {
 	};
 }
 
+interface TimedMessage {
+	type: string;
+	ts: number;
+}
+
 function modelShort(full: string): ModelUsage["modelShort"] {
 	if (/opus/i.test(full)) return "Opus";
 	if (/sonnet/i.test(full)) return "Sonnet";
@@ -82,12 +91,12 @@ function projectKey(repoRoot: string): string {
 async function parseTranscriptFile(filePath: string): Promise<{
 	entries: TranscriptEntry[];
 	humanCount: number;
-	timestamps: number[];
+	timedMessages: TimedMessage[];
 }> {
 	const raw = await readFile(filePath, "utf8");
 	const entries: TranscriptEntry[] = [];
 	let humanCount = 0;
-	const timestamps: number[] = [];
+	const timedMessages: TimedMessage[] = [];
 
 	for (const line of raw.split("\n")) {
 		const trimmed = line.trim();
@@ -96,34 +105,62 @@ async function parseTranscriptFile(filePath: string): Promise<{
 			const entry = JSON.parse(trimmed) as TranscriptEntry;
 			entries.push(entry);
 			if (entry.type === "human") humanCount++;
-			if (entry.timestamp) {
+			if (entry.type && entry.timestamp) {
 				const ms = new Date(entry.timestamp).getTime();
-				if (!isNaN(ms)) timestamps.push(ms);
+				if (!isNaN(ms)) timedMessages.push({ type: entry.type, ts: ms });
 			}
 		} catch {
 			// Skip malformed lines
 		}
 	}
 
-	return { entries, humanCount, timestamps };
+	return { entries, humanCount, timedMessages };
 }
 
 /**
- * Compute active session time in minutes from a sorted list of timestamps.
+ * Compute AI vs human time breakdown from a sequence of timed messages.
  *
- * Sums consecutive gaps only when the gap is under 15 minutes (900_000ms).
- * Gaps of 15+ minutes are treated as idle (away from keyboard, blocked on CI,
- * etc.) and excluded so they don't inflate the active time metric.
+ * - human→* gap: Claude is processing (AI time)
+ * - assistant→* gap <30s: automated tool result turnaround (AI time)
+ * - assistant→* gap 30s–15m: human reviewing/thinking (human time)
+ * - Any gap ≥15m: idle, excluded
  */
-function computeActiveMinutes(allTimestamps: number[]): number {
-	const sorted = [...allTimestamps].sort((a, b) => a - b);
-	let totalMs = 0;
-	const IDLE_THRESHOLD_MS = 900_000; // 15 minutes
+function computeTimeBreakdown(messages: TimedMessage[]): {
+	totalMinutes: number;
+	aiMinutes: number;
+	humanMinutes: number;
+} {
+	const sorted = [...messages].sort((a, b) => a.ts - b.ts);
+	const IDLE_MS = 900_000; // 15 min
+	const AUTO_MS = 30_000; // 30 sec — automated tool turnaround
+
+	let aiMs = 0;
+	let humanMs = 0;
+
 	for (let i = 1; i < sorted.length; i++) {
-		const gap = (sorted[i] ?? 0) - (sorted[i - 1] ?? 0);
-		if (gap < IDLE_THRESHOLD_MS) totalMs += gap;
+		const prev = sorted[i - 1]!;
+		const curr = sorted[i]!;
+		const gap = curr.ts - prev.ts;
+		if (gap >= IDLE_MS) continue; // idle gap, skip
+
+		if (prev.type === "human") {
+			// Claude is processing a message
+			aiMs += gap;
+		} else {
+			// Gap after an assistant message
+			if (gap < AUTO_MS) {
+				aiMs += gap; // automated tool result
+			} else {
+				humanMs += gap; // human reviewing / typing next message
+			}
+		}
 	}
-	return Math.round(totalMs / 60_000);
+
+	return {
+		aiMinutes: Math.round(aiMs / 60_000),
+		humanMinutes: Math.round(humanMs / 60_000),
+		totalMinutes: Math.round((aiMs + humanMs) / 60_000),
+	};
 }
 
 function aggregateEntries(entries: TranscriptEntry[]): Map<string, ModelUsage> {
@@ -164,8 +201,9 @@ function aggregateEntries(entries: TranscriptEntry[]): Map<string, ModelUsage> {
  * ~/.claude/projects/<key>/ directory structure. Aggregates token counts by model
  * (Opus / Sonnet / Haiku / Unknown) and counts human prompt turns.
  *
- * Human prompt count is used as a proxy for "steering effort" in the /metrics output
- * — it represents how many times the developer had to direct Claude.
+ * Time breakdown uses only the main transcript's message sequence (human vs
+ * assistant), since subagent messages are automated orchestration — not human
+ * interaction. Human→assistant gaps = AI time; assistant→human gaps >30s = human time.
  *
  * Returns null if the session transcript file doesn't exist (session not found).
  */
@@ -183,21 +221,17 @@ export async function parseTranscript(
 	const {
 		entries: mainEntries,
 		humanCount,
-		timestamps: mainTimestamps,
+		timedMessages,
 	} = await parseTranscriptFile(mainFile);
 	const combined = aggregateEntries(mainEntries);
-	const allTimestamps: number[] = [...mainTimestamps];
 
-	// Merge subagent transcripts
+	// Merge subagent transcripts (token counts only — exclude from time breakdown)
 	const subagentDir = join(transcriptDir, sessionId, "subagents");
 	if (existsSync(subagentDir)) {
 		for (const file of (await readdir(subagentDir)).filter((f) =>
 			f.endsWith(".jsonl"),
 		)) {
-			const { entries, timestamps } = await parseTranscriptFile(
-				join(subagentDir, file),
-			);
-			allTimestamps.push(...timestamps);
+			const { entries } = await parseTranscriptFile(join(subagentDir, file));
 			for (const [model, usage] of aggregateEntries(entries)) {
 				const existing = combined.get(model);
 				if (!existing) {
@@ -235,11 +269,16 @@ export async function parseTranscript(
 		},
 	);
 
+	const { totalMinutes, aiMinutes, humanMinutes } =
+		computeTimeBreakdown(timedMessages);
+
 	return {
 		sessionId,
 		byModel,
 		totals,
 		humanPromptCount: humanCount,
-		activeMinutes: computeActiveMinutes(allTimestamps),
+		activeMinutes: totalMinutes,
+		aiMinutes,
+		humanMinutes,
 	};
 }

package/src/setup/branch-protection.ts

@@ -0,0 +1,432 @@
+/**
+ * Branch protection utilities for claude-attribution install.
+ *
+ * Handles both classic branch protection rules and GitHub rulesets.
+ * After installing the workflow, detects what protection is active on the
+ * default branch and interactively offers to add our workflow job as a
+ * required status check.
+ *
+ * Design:
+ *   - Classic protection: PATCH .../required_status_checks (preserves existing)
+ *   - Rulesets: PUT .../rulesets/{id} with updated rules (preserves all other rules)
+ *   - Both present: numbered prompt so user chooses where to add
+ *   - Already configured: silent skip for that protection type
+ *   - Any failure: graceful fallback to informational note, never breaks install
+ */
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { writeFile, unlink, rmdir, mkdtemp } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { createInterface } from "readline";
+
+const execFileAsync = promisify(execFile);
+
+/** The GitHub Actions job name — must match `jobs.metrics.name` in the workflow template. */
+export const WORKFLOW_CHECK_NAME = "Claude Code Attribution Metrics";
+
+/** GitHub Actions app ID — used so the check shows "GitHub Actions" rather than "any source". */
+const GITHUB_ACTIONS_APP_ID = 15368;
+
+type Check = { context: string; app_id: number };
+
+interface ClassicStatus {
+	branch: string;
+	strict: boolean;
+	checks: Check[];
+	hasOurCheck: boolean;
+}
+
+interface RulesetStatus {
+	id: number;
+	name: string;
+	hasOurCheck: boolean;
+	/** Full raw ruleset object — re-submitted on PUT to preserve all fields. */
+	raw: RawRuleset;
+}
+
+interface RawRuleset {
+	name: string;
+	target?: string;
+	enforcement?: string;
+	conditions?: unknown;
+	bypass_actors?: unknown[];
+	rules?: RawRule[];
+}
+
+interface RawRule {
+	type: string;
+	parameters?: {
+		strict_required_status_checks_policy?: boolean;
+		required_status_checks?: Array<{
+			context: string;
+			integration_id?: number;
+		}>;
+		[key: string]: unknown;
+	};
+}
+
+// ─── GitHub API helpers ───────────────────────────────────────────────────────
+
+async function ghGet(path: string): Promise<unknown> {
+	try {
+		const { stdout } = (await execFileAsync("gh", [
+			"api",
+			path,
+		])) as unknown as { stdout: string };
+		return JSON.parse(stdout) as unknown;
+	} catch {
+		return null;
+	}
+}
+
+async function ghPut(path: string, body: unknown): Promise<void> {
+	const tmpDir = await mkdtemp(join(tmpdir(), "claude-attribution-api-"));
+	const tmpFile = join(tmpDir, "body.json");
+	try {
+		await writeFile(tmpFile, JSON.stringify(body), { flag: "wx" });
+		await execFileAsync("gh", [
+			"api",
+			path,
+			"--method",
+			"PUT",
+			"--input",
+			tmpFile,
+		]);
+	} finally {
+		await unlink(tmpFile).catch(() => {});
+		await rmdir(tmpDir).catch(() => {});
+	}
+}
+
+async function ghPatch(path: string, body: unknown): Promise<void> {
+	const tmpDir = await mkdtemp(join(tmpdir(), "claude-attribution-api-"));
+	const tmpFile = join(tmpDir, "body.json");
+	try {
+		await writeFile(tmpFile, JSON.stringify(body), { flag: "wx" });
+		await execFileAsync("gh", [
+			"api",
+			path,
+			"--method",
+			"PATCH",
+			"--input",
+			tmpFile,
+		]);
+	} finally {
+		await unlink(tmpFile).catch(() => {});
+		await rmdir(tmpDir).catch(() => {});
+	}
+}
+
+// ─── Detection ────────────────────────────────────────────────────────────────
+
+async function getClassicStatus(
+	slug: string,
+	branch: string,
+): Promise<ClassicStatus | null> {
+	const data = await ghGet(`repos/${slug}/branches/${branch}/protection`);
+	if (!data) return null;
+
+	const prot = data as {
+		required_status_checks?: {
+			strict: boolean;
+			contexts?: string[];
+			checks?: Check[];
+		};
+	};
+
+	const rsc = prot.required_status_checks;
+	if (!rsc) {
+		// Protection exists but no required status checks configured yet
+		return {
+			branch,
+			strict: false,
+			checks: [],
+			hasOurCheck: false,
+		};
+	}
+
+	const checks: Check[] =
+		rsc.checks && rsc.checks.length > 0
+			? rsc.checks
+			: (rsc.contexts ?? []).map((c) => ({ context: c, app_id: -1 }));
+
+	return {
+		branch,
+		strict: rsc.strict,
+		checks,
+		hasOurCheck: checks.some((c) => c.context === WORKFLOW_CHECK_NAME),
+	};
+}
+
+async function getRulesetStatuses(slug: string): Promise<RulesetStatus[]> {
+	const list = await ghGet(`repos/${slug}/rulesets`);
+	if (!Array.isArray(list) || list.length === 0) return [];
+
+	// Fetch full details for each ruleset in parallel (rules not in list response)
+	const results = await Promise.all(
+		(list as Array<{ id: number }>).map(async (rs) => {
+			const full = (await ghGet(
+				`repos/${slug}/rulesets/${rs.id}`,
+			)) as RawRuleset | null;
+			if (!full) return null;
+
+			const statusCheckRule = full.rules?.find(
+				(r) => r.type === "required_status_checks",
+			);
+			const hasOurCheck =
+				statusCheckRule?.parameters?.required_status_checks?.some(
+					(c) => c.context === WORKFLOW_CHECK_NAME,
+				) ?? false;
+
+			return {
+				id: rs.id,
+				name: full.name,
+				hasOurCheck,
+				raw: full,
+			} satisfies RulesetStatus;
+		}),
+	);
+
+	return results.filter((r): r is RulesetStatus => r !== null);
+}
+
+/** Extract "owner/repo" from SSH or HTTPS origin remote URL. */
+export function remoteUrlToSlug(url: string): string | null {
+	const m =
+		url.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/) ??
+		url.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+	return m?.[1] ?? null;
+}
+
+// ─── Modification ─────────────────────────────────────────────────────────────
+
+async function addToClassic(
+	classic: ClassicStatus,
+	slug: string,
+): Promise<void> {
+	await ghPatch(
+		`repos/${slug}/branches/${classic.branch}/protection/required_status_checks`,
+		{
+			strict: classic.strict,
+			checks: [
+				...classic.checks,
+				{ context: WORKFLOW_CHECK_NAME, app_id: GITHUB_ACTIONS_APP_ID },
+			],
+		},
+	);
+}
+
+async function addToRuleset(rs: RulesetStatus, slug: string): Promise<void> {
+	const rules = rs.raw.rules ?? [];
+	const existingRule = rules.find((r) => r.type === "required_status_checks");
+
+	let updatedRules: RawRule[];
+	if (existingRule) {
+		const existingChecks =
+			existingRule.parameters?.required_status_checks ?? [];
+		updatedRules = rules.map((r) =>
+			r.type === "required_status_checks"
+				? {
+						...r,
+						parameters: {
+							...r.parameters,
+							required_status_checks: [
+								...existingChecks,
+								{
+									context: WORKFLOW_CHECK_NAME,
+									integration_id: GITHUB_ACTIONS_APP_ID,
+								},
+							],
+						},
+					}
+				: r,
+		);
+	} else {
+		// No required_status_checks rule yet — add one
+		updatedRules = [
+			...rules,
+			{
+				type: "required_status_checks",
+				parameters: {
+					strict_required_status_checks_policy: false,
+					required_status_checks: [
+						{
+							context: WORKFLOW_CHECK_NAME,
+							integration_id: GITHUB_ACTIONS_APP_ID,
+						},
+					],
+				},
+			},
+		];
+	}
+
+	await ghPut(`repos/${slug}/rulesets/${rs.id}`, {
+		...rs.raw,
+		rules: updatedRules,
+	});
+}
+
+// ─── Prompts ──────────────────────────────────────────────────────────────────
+
+async function promptYesNo(question: string): Promise<boolean> {
+	if (!process.stdin.isTTY) return false;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim().toLowerCase() === "y");
+		});
+	});
+}
+
+async function promptChoice(
+	question: string,
+	options: string[],
+): Promise<number> {
+	if (!process.stdin.isTTY) return -1;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => {
+		const numbered = options.map((o, i) => `    [${i + 1}] ${o}`).join("\n");
+		rl.question(`${question}\n${numbered}\n  Choice [1]: `, (answer) => {
+			rl.close();
+			const n = parseInt(answer.trim() || "1", 10);
+			resolve(n >= 1 && n <= options.length ? n - 1 : -1);
+		});
+	});
+}
+
+function printNote(branch: string): void {
+	console.log(
+		`\n  ℹ️  To block merges when this workflow fails, add '${WORKFLOW_CHECK_NAME}'`,
+	);
+	console.log(
+		`      to required status checks for '${branch}' in Settings → Branches or Rules.`,
+	);
+}
+
+// ─── Main entry point ─────────────────────────────────────────────────────────
+
+/**
+ * Detect branch protection on the repo's default branch and offer to add
+ * the workflow job as a required status check. Called from install.ts after
+ * the workflow file is written. Never throws — all errors fall back to a note.
+ */
+export async function configureRequiredCheck(repoRoot: string): Promise<void> {
+	try {
+		const { stdout: remoteOut } = (await execFileAsync(
+			"git",
+			["remote", "get-url", "origin"],
+			{ cwd: repoRoot },
+		)) as unknown as { stdout: string };
+		const slug = remoteUrlToSlug(remoteOut.trim());
+		if (!slug) return;
+
+		const repoData = await ghGet(`repos/${slug}`);
+		const branch = (repoData as { default_branch?: string } | null)
+			?.default_branch;
+		if (!branch) return;
+
+		// Detect both protection types in parallel
+		const [classic, rulesets] = await Promise.all([
+			getClassicStatus(slug, branch),
+			getRulesetStatuses(slug),
+		]);
+
+		// Determine what needs to be added
+		const classicNeeded = classic !== null && !classic.hasOurCheck;
+		const rulesetsNeeded = rulesets.filter((rs) => !rs.hasOurCheck);
+
+		// Already fully configured
+		if (!classicNeeded && rulesetsNeeded.length === 0) {
+			if (classic?.hasOurCheck || rulesets.some((rs) => rs.hasOurCheck)) {
+				console.log(
+					`✓ '${WORKFLOW_CHECK_NAME}' already a required status check`,
+				);
+			}
+			return;
+		}
+
+		// Build the list of targets that need our check
+		const targets: Array<
+			| { kind: "classic"; classic: ClassicStatus }
+			| { kind: "ruleset"; rs: RulesetStatus }
+		> = [];
+		if (classicNeeded) targets.push({ kind: "classic", classic });
+		for (const rs of rulesetsNeeded) targets.push({ kind: "ruleset", rs });
+
+		let chosen: typeof targets;
+
+		if (targets.length === 1) {
+			// Single target — simple yes/no
+			const target = targets[0]!;
+			const label =
+				target.kind === "classic"
+					? `branch protection rule on '${branch}'`
+					: `ruleset '${target.rs.name}'`;
+			console.log(`\n  Branch protection is active on '${branch}'.`);
+			const yes = await promptYesNo(
+				`  Add '${WORKFLOW_CHECK_NAME}' to ${label}? [y/N] `,
+			);
+			if (!yes) {
+				printNote(branch);
+				return;
+			}
+			chosen = targets;
+		} else {
+			// Multiple targets — numbered choice
+			const options = [
+				...targets.map((t) =>
+					t.kind === "classic"
+						? `Branch protection rule on '${branch}'`
+						: `Ruleset: '${t.rs.name}'`,
+				),
+				"Both",
+				"Skip",
+			];
+			console.log(
+				`\n  Multiple branch protection rules active on '${branch}'.`,
+			);
+			console.log(
+				`  Where should '${WORKFLOW_CHECK_NAME}' be added as a required check?`,
+			);
+			const idx = await promptChoice("", options);
+			if (idx === -1 || idx === options.length - 1) {
+				// Skip
+				printNote(branch);
+				return;
+			}
+			if (idx === options.length - 2) {
+				// Both
+				chosen = targets;
+			} else {
+				chosen = [targets[idx]!];
+			}
+		}
+
+		// Apply changes
+		for (const target of chosen) {
+			if (target.kind === "classic") {
+				await addToClassic(target.classic, slug);
+				console.log(
+					`✓ Added '${WORKFLOW_CHECK_NAME}' to branch protection on '${branch}'`,
+				);
+			} else {
+				await addToRuleset(target.rs, slug);
+				console.log(
+					`✓ Added '${WORKFLOW_CHECK_NAME}' to ruleset '${target.rs.name}'`,
+				);
+			}
+		}
+	} catch {
+		console.log(
+			`\n  ℹ️  Could not configure required status checks automatically.`,
+		);
+		console.log(
+			`      To block merges on workflow failure, add '${WORKFLOW_CHECK_NAME}'`,
+		);
+		console.log(
+			`      to required status checks in your branch protection settings.`,
+		);
+	}
+}

package/src/setup/install.ts

@@ -19,6 +19,7 @@ import {
 	detectHookManager,
 	type HooksConfig,
 } from "./shared.ts";
+import { configureRequiredCheck } from "./branch-protection.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -174,7 +175,10 @@ async function main() {
 		`✓ Installed .github/workflows/claude-attribution-pr.yml — runner: ${runsOn}${detectedNote}`,
 	);
 
-	// 5. Record installed version for auto-upgrade tracking
+	// 5. Check branch protection and offer to add required status check
+	await configureRequiredCheck(targetRepo);
+
+	// 6. Record installed version for auto-upgrade tracking
 	const pkg = JSON.parse(
 		await readFile(join(ATTRIBUTION_ROOT, "package.json"), "utf8"),
 	) as { version: string };