pi-dev-team 0.2.0

package/extensions/dev-team/lib/config.ts

@@ -0,0 +1,236 @@
+/**
+ * dev-team configuration.
+ *
+ * Merged, later wins:
+ *   1. built-in defaults
+ *   2. ~/.pi/agent/dev-team.json          (user)
+ *   3. <project>/.pi/dev-team.json        (project, committed)
+ *   4. <project>/.pi/dev-team.local.json  (project, personal, git-ignored)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readSmallFile } from "./safe-read.ts";
+
+export type Tier = "opus" | "sonnet" | "haiku" | "fable" | string;
+
+export interface HookConfig {
+	/** Master switch for the Python hook bridge. */
+	enabled: boolean;
+	/** Hook script basenames (without .py) to skip. Replaces the default list when set. */
+	disabled: string[];
+	/** Hook script basenames to force-enable even if in the default disabled list. */
+	enable: string[];
+	/** Append advisory hook output (exit 0 stdout) to the tool result the model sees. */
+	outputToModel: boolean;
+	/** Per-hook timeout in seconds (fail-open on timeout). */
+	timeoutSec: number;
+}
+
+export const GITHUB_STYLE_MODES = ["block", "warn", "off"] as const;
+export type GitHubStyleMode = (typeof GITHUB_STYLE_MODES)[number];
+
+export interface DevTeamConfig {
+	/** Agent model tier -> "provider/model-id" or "inherit" (use the dispatching session's model). */
+	models: Record<Tier, string>;
+	/** Agent `effort` -> pi thinking level. */
+	thinking: Record<string, string>;
+	/** Maximum concurrently running subagent processes (across all calls). */
+	maxParallelAgents: number;
+	/** Maximum nesting depth of subagents (a subagent dispatching a subagent is depth 2). */
+	maxSubagentDepth: number;
+	/** Wall-clock limit per subagent in seconds (0 = none). */
+	subagentTimeoutSec: number;
+	hooks: HookConfig;
+	/** Run hooks/post_format.py after write/edit (what /setup's formatter hook did). */
+	autoFormat: boolean;
+	/** Pull request and issue text that breaks the GitHub style rules: block the gh call once ("block"), only note it ("warn"), or skip the check and the style guide ("off"). */
+	githubStyle: GitHubStyleMode;
+	/** How dev-team skills are advertised in the system prompt. */
+	skillIndex: "compact" | "full" | "off";
+	/** Max description characters per skill in the compact index. */
+	skillIndexChars: number;
+	/** Put the `claude` -> `pi` CLI shim on PATH for scripts that call `claude -p`. */
+	claudeShim: boolean;
+	/** Extra environment variables for tools, hooks, scripts and subagents (e.g. DEV_TEAM_MAX_PARALLEL_BUILDS). */
+	env: Record<string, string>;
+}
+
+/**
+ * Hooks off by default. See PORTING.md section 4.
+ * - replaced natively by the extension: cost_meter, subagent_skill_context
+ * - need Claude transcripts / Claude-only config: code_intelligence_*, phase_marker, session_learning_trigger,
+ *   mcp_json_repowise_nudge, version_check
+ * - only act inside the upstream monorepo: the rest
+ */
+export const DEFAULT_DISABLED_HOOKS = [
+	"cost_meter",
+	"subagent_skill_context",
+	"code_intelligence_nudge",
+	"code_intelligence_turn_mark",
+	"phase_marker",
+	"session_learning_trigger",
+	"mcp_json_repowise_nudge",
+	"version_check",
+	"contract_version_guard",
+	"pre_commit_knowledge_index",
+	"knowledge_index",
+	"skills_index",
+	"scan_bash_command_for_banned_scripts",
+	"scan_worktree_for_banned_scripts",
+	"eval_compliance_check",
+];
+
+export const DEFAULT_CONFIG: DevTeamConfig = {
+	models: { opus: "inherit", sonnet: "inherit", haiku: "inherit", fable: "inherit" },
+	thinking: { low: "low", medium: "medium", high: "high", xhigh: "xhigh", max: "max" },
+	maxParallelAgents: 6,
+	maxSubagentDepth: 2,
+	subagentTimeoutSec: 3600,
+	hooks: { enabled: true, disabled: DEFAULT_DISABLED_HOOKS, enable: [], outputToModel: true, timeoutSec: 60 },
+	autoFormat: false,
+	githubStyle: "block",
+	skillIndex: "compact",
+	skillIndexChars: 220,
+	claudeShim: true,
+	env: {},
+};
+
+/** Tier presets offered by `/dev-team models`. Values are provider/model ids from pi's catalog. */
+export const MODEL_PRESETS: Record<string, Record<string, string>> = {
+	"github-copilot": {
+		opus: "github-copilot/claude-opus-5.5",
+		sonnet: "github-copilot/claude-sonnet-5.5",
+		haiku: "github-copilot/claude-haiku-4.5",
+		fable: "github-copilot/claude-fable-5.1",
+	},
+	anthropic: {
+		opus: "anthropic/claude-opus-5-5",
+		sonnet: "anthropic/claude-sonnet-5-5",
+		haiku: "anthropic/claude-haiku-4-5",
+		fable: "anthropic/claude-fable-5-1",
+	},
+	inherit: { opus: "inherit", sonnet: "inherit", haiku: "inherit", fable: "inherit" },
+};
+
+export function userConfigPath(): string {
+	return path.join(getAgentDir(), "dev-team.json");
+}
+
+export function projectConfigPath(cwd: string, local = false): string {
+	return path.join(cwd, ".pi", local ? "dev-team.local.json" : "dev-team.json");
+}
+
+function readJson(file: string): Record<string, unknown> | undefined {
+	const text = readSmallFile(file);
+	if (text === undefined) return undefined;
+	try {
+		const parsed = JSON.parse(text);
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+	return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Deep merge for plain objects; arrays and scalars replace. */
+export function mergeConfig<T>(base: T, override: unknown): T {
+	if (!isPlainObject(override)) return base;
+	const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+	for (const [k, v] of Object.entries(override)) {
+		const cur = out[k];
+		out[k] = isPlainObject(cur) && isPlainObject(v) ? mergeConfig(cur, v) : v;
+	}
+	return out as T;
+}
+
+/**
+ * A project's config may set only these dev-team tuning settings, each to a plain number, word or
+ * flag. pi asks about trust only when a repo has pi-protected files (.pi/settings.json, .pi/extensions,
+ * ...), so a repo with just a .pi/dev-team.json is trusted without a prompt. Its env must therefore not
+ * reach PATH, NODE_OPTIONS or PYTHONPATH, any file path the port reads or runs (DEV_TEAM_PY_CACHE is
+ * executed by hooks/py.sh), a program choice, or a gate bypass (DEV_TEAM_AUTO_APPROVE,
+ * DEV_TEAM_GUARD_OVERRIDE, *_SKIP, a threshold whose 0 disables a guard). Those stay available in the
+ * user's own config and environment.
+ */
+export const PROJECT_ENV_SETTINGS: ReadonlySet<string> = new Set([
+	"DEV_TEAM_MAX_PARALLEL_BUILDS",
+	"DEV_TEAM_MAX_PARALLEL_REVIEW_AGENTS",
+	"DEV_TEAM_AUTO_REVIEW",
+	"DEV_TEAM_AUTO_REVIEW_THRESHOLD",
+	"DEV_TEAM_REPO_REVIEW_PERCENT_THRESHOLD",
+	"DEV_TEAM_REPO_REVIEW_MIN_ADDED_LINES",
+	"DEV_TEAM_REPO_REVIEW_MAX_ADDED_LINES",
+	"DEV_TEAM_REVIEW_CONTEXT_PACK",
+	"DEV_TEAM_WORKTREE_BASE_FRESH",
+	"DEV_TEAM_AUTOCOMPACT_NUDGE",
+	"DEV_TEAM_COST_METER",
+	"DEV_TEAM_TASK_METRICS",
+	"DEV_TEAM_REVIEW_VALUE",
+	"DEV_TEAM_TELEMETRY",
+]);
+const PLAIN_SETTING_VALUE = /^[A-Za-z0-9._-]{0,64}$/;
+
+export function isProjectEnvSettingAllowed(key: string, value: unknown): boolean {
+	return PROJECT_ENV_SETTINGS.has(key) && (typeof value === "string" || typeof value === "number" || typeof value === "boolean") && PLAIN_SETTING_VALUE.test(String(value));
+}
+
+/**
+ * A project config file as it may apply: env limited to PROJECT_ENV_SETTINGS (an env that is not an
+ * object is dropped whole), and no `hooks` at all, since hooks include the guards; hooks are set in the
+ * user's own config. `ignored` names everything left out, as `env.KEY`, `env` or `hooks`.
+ */
+export function filterProjectConfig(data: Record<string, unknown>): { data: Record<string, unknown>; ignored: string[] } {
+	const ignored: string[] = [];
+	const { env, hooks, ...rest } = data;
+	const out: Record<string, unknown> = rest;
+	if (hooks !== undefined) ignored.push("hooks");
+	if (env === undefined) return { data: out, ignored };
+	if (!isPlainObject(env)) return { data: out, ignored: [...ignored, "env"] };
+	const entries = Object.entries(env);
+	out.env = Object.fromEntries(entries.filter(([k, v]) => isProjectEnvSettingAllowed(k, v)));
+	for (const [k, v] of entries) if (!isProjectEnvSettingAllowed(k, v)) ignored.push(`env.${k}`);
+	return { data: out, ignored };
+}
+
+/**
+ * User config, then the project's .pi/dev-team.json and .pi/dev-team.local.json. Project files are
+ * filtered (filterProjectConfig), so callers pass `includeProject: ctx.isProjectTrusted()`.
+ */
+export function loadConfig(
+	cwd: string,
+	opts: { includeProject: boolean; userConfigFile?: string },
+): { config: DevTeamConfig; sources: string[]; ignoredProjectSettings: string[] } {
+	let config = DEFAULT_CONFIG;
+	const sources: string[] = [];
+	const ignoredProjectSettings: string[] = [];
+	const userFile = opts.userConfigFile ?? userConfigPath();
+	const projectFiles = opts.includeProject ? [projectConfigPath(cwd), projectConfigPath(cwd, true)] : [];
+	for (const file of [userFile, ...projectFiles]) {
+		const raw = readJson(file);
+		if (!raw) continue;
+		const { data, ignored } = file === userFile ? { data: raw, ignored: [] } : filterProjectConfig(raw);
+		if ("githubStyle" in data && !(GITHUB_STYLE_MODES as readonly unknown[]).includes(data.githubStyle)) delete data.githubStyle;
+		config = mergeConfig(config, data);
+		sources.push(file);
+		ignoredProjectSettings.push(...ignored);
+	}
+	return { config, sources, ignoredProjectSettings };
+}
+
+/** Read-modify-write one config file (used by /dev-team models). */
+export function updateConfigFile(file: string, patch: Record<string, unknown>): void {
+	const current = readJson(file) ?? {};
+	const next = mergeConfig(current, patch);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+}
+
+export function isHookEnabled(config: DevTeamConfig, hookName: string): boolean {
+	if (!config.hooks.enabled) return false;
+	if (config.hooks.enable.includes(hookName)) return true;
+	return !config.hooks.disabled.includes(hookName);
+}

package/extensions/dev-team/lib/gh-command.ts

@@ -0,0 +1,103 @@
+/**
+ * The title and body that `gh pr|issue create|edit|comment` commands in a bash command line send.
+ * Only literal values are returned: a value the shell computes is left undefined, so it is not checked.
+ */
+import * as path from "node:path";
+import { readBoundedFile } from "./safe-read.ts";
+import { type ShellSegment, type ShellWord, scanShell } from "./shell-scan.ts";
+
+export const GH_TEXT_KINDS = ["pr", "issue", "comment"] as const;
+export type GhTextKind = (typeof GH_TEXT_KINDS)[number];
+
+/** A body file is read up to this size: 100,000 characters of UTF-8 take at most 4 bytes each. */
+export const MAX_BODY_FILE_BYTES = 400_000;
+
+export interface GhText {
+	kind: GhTextKind;
+	title?: string;
+	body?: string;
+	/** The body file is larger than MAX_BODY_FILE_BYTES, so it was not read. */
+	bodyFileTooLarge?: boolean;
+}
+
+type BodyValue = Pick<GhText, "body" | "bodyFileTooLarge">;
+
+const TITLE_FLAGS = new Set(["--title", "-t"]);
+const BODY_FLAGS = new Set(["--body", "-b"]);
+const BODY_FILE_FLAGS = new Set(["--body-file", "-F"]);
+const GH_GROUPS = new Set(["pr", "issue"]);
+const GH_ACTIONS = new Set(["create", "edit", "comment"]);
+/** Words that can come before the command itself in a simple command. */
+const COMMAND_PREFIXES = new Set(["if", "then", "elif", "else", "do", "while", "until", "!", "{", "time", "env", "command", "exec", "nohup"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/** The body a `--body-file` value gives: a file relative to `cwd`, or stdin for `-`. */
+function bodyFromFile(value: ShellWord, stdin: string | undefined, cwd: string): BodyValue {
+	if (value.dynamic) return { body: undefined };
+	if (value.text === "-") return { body: stdin };
+	const result = readBoundedFile(path.resolve(cwd, value.text), MAX_BODY_FILE_BYTES);
+	if ("text" in result) return { body: result.text };
+	return result.skipped === "too-large" ? { body: undefined, bodyFileTooLarge: true } : { body: undefined };
+}
+
+/** Literal stdin from a `<<'EOF'` heredoc or a `<<<` here-string in the command's arguments. */
+function readStdin(args: ShellWord[]): string | undefined {
+	for (let argIndex = 0; argIndex < args.length; argIndex++) {
+		const arg = args[argIndex];
+		if (arg.redirect === "heredoc") return arg.dynamic ? undefined : arg.heredocBody;
+		if (arg.redirect === "here-string") {
+			const value = args[argIndex + 1];
+			return value && !value.dynamic ? `${value.text}\n` : undefined;
+		}
+	}
+	return undefined;
+}
+
+/** The kind and arguments when the segment is `[prefix ...] [NAME=value ...] gh pr|issue create|edit|comment ...`. */
+function locateGhCommand(segment: ShellSegment): { kind: GhTextKind; args: ShellWord[] } | undefined {
+	let commandIndex = 0;
+	const isPrefix = (word: ShellWord) => (!word.dynamic && COMMAND_PREFIXES.has(word.text)) || ASSIGNMENT.test(word.text);
+	while (commandIndex < segment.length && isPrefix(segment[commandIndex])) commandIndex++;
+	const [command, group, action] = segment.slice(commandIndex, commandIndex + 3);
+	if (!command || command.dynamic || path.basename(command.text) !== "gh") return undefined;
+	if (!group || !GH_GROUPS.has(group.text) || !action || !GH_ACTIONS.has(action.text)) return undefined;
+	const kind: GhTextKind = action.text === "comment" ? "comment" : group.text === "pr" ? "pr" : "issue";
+	return { kind, args: segment.slice(commandIndex + 3) };
+}
+
+/** Title and body from the flags. When a flag is given twice, the last one wins, as in gh. */
+function readTitleAndBody(kind: GhTextKind, args: ShellWord[], cwd: string): GhText {
+	const stdin = readStdin(args);
+	let titleValue: Pick<GhText, "title"> = {};
+	let bodyValue: BodyValue = {};
+	for (let argIndex = 0; argIndex < args.length; argIndex++) {
+		const arg = args[argIndex];
+		if (arg.redirect) {
+			if (arg.redirect === "here-string") argIndex++;
+			continue;
+		}
+		const inlineFlag = /^(--[a-z-]+)=([\s\S]*)$/.exec(arg.text);
+		const flag = inlineFlag ? inlineFlag[1] : arg.text;
+		if (!TITLE_FLAGS.has(flag) && !BODY_FLAGS.has(flag) && !BODY_FILE_FLAGS.has(flag)) continue;
+		const value: ShellWord | undefined = inlineFlag ? { text: inlineFlag[2], dynamic: arg.dynamic } : args[++argIndex];
+		if (!value || value.redirect) continue;
+		if (TITLE_FLAGS.has(flag)) titleValue = { title: value.dynamic ? undefined : value.text };
+		else if (BODY_FLAGS.has(flag)) bodyValue = { body: value.dynamic ? undefined : value.text };
+		else bodyValue = bodyFromFile(value, stdin, cwd);
+	}
+	return { kind, ...titleValue, ...bodyValue };
+}
+
+/**
+ * The title and body that each `gh pr|issue create|edit|comment` in a bash command sends. A value the
+ * shell computes ($VAR, `$(git log ...)`, an unquoted heredoc with $ in it) is left undefined and not
+ * checked. `$(cat <<'EOF' ...)`, `--body-file -` with a heredoc or here-string, and a body file
+ * (relative to `cwd`) are read.
+ */
+export function extractGhTexts(command: string, cwd: string): GhText[] {
+	if (!/\bgh\b/.test(command)) return [];
+	return scanShell(command).flatMap((segment) => {
+		const located = locateGhCommand(segment);
+		return located ? [readTitleAndBody(located.kind, located.args, cwd)] : [];
+	});
+}

package/extensions/dev-team/lib/github-style.ts

@@ -0,0 +1,307 @@
+/**
+ * Writing style for the pull requests, issues and comments that the team opens on GitHub. The rules
+ * join two sources: plain English after ASD-STE100 (AminBlg/SimpleEnglish: short sentences, active
+ * voice, no hedges, no filler) and a layout for a reader with little attention to spare
+ * (ayghri/i-have-adhd: the point first, short lists, one next step, details out of the way).
+ *
+ * `styleGuideFor` gives the rules for the system prompt of every session and subagent.
+ * `createStyleGate` checks the text each `gh pr|issue create|edit|comment` in a bash command sends
+ * (see gh-command.ts) and decides whether the extension blocks the call (once), adds a note, or lets
+ * it pass.
+ */
+import { createHash } from "node:crypto";
+import type { GitHubStyleMode } from "./config.ts";
+import { extractGhTexts, type GhText, type GhTextKind } from "./gh-command.ts";
+
+export type { GhText } from "./gh-command.ts";
+
+/** Visible words allowed, by kind. Code, URLs, HTML comments, tables, headings and <details> blocks do not count. */
+export const WORD_LIMITS: Readonly<Record<GhTextKind, number>> = { pr: 250, issue: 250, comment: 150 };
+/** Text longer than this is reported as too long and not checked further, so the check stays fast. */
+export const MAX_LINT_CHARS = 100_000;
+
+export const MAX_SENTENCE_WORDS = 25;
+export const MAX_LIST_ITEMS = 5;
+/** Matches the "<70 chars" title rule of the /pr skill. */
+export const MAX_TITLE_CHARS = 69;
+/** Blocked commands remembered for the block-once rule; the oldest is forgotten first. */
+export const MAX_REMEMBERED_BLOCKS = 200;
+
+export const FILLER_TERMS = [
+	"simply",
+	"seamless",
+	"seamlessly",
+	"robust",
+	"powerful",
+	"comprehensive",
+	"leverage",
+	"leverages",
+	"leveraged",
+	"leveraging",
+	"crucial",
+	"delve",
+	"in order to",
+	"it is worth noting",
+] as const;
+
+const EXAMPLE_SENTENCE_CHARS = 60;
+const EXAMPLE_BOLD_CHARS = 30;
+const MAX_BOLD_EXAMPLES = 3;
+const TAB_WIDTH = 4;
+
+export const GITHUB_STYLE_GUIDE = [
+	"GitHub text style (pull request and issue titles, bodies, comments). Readers skim, so:",
+	`- Title: at most ${MAX_TITLE_CHARS} characters, imperative ("Add rate limit to /login").`,
+	"- First line of the body: one sentence that says what changes and why (issue: what is wrong and its effect).",
+	`- Then short sections: Summary (at most 3 bullets), Test plan or Acceptance criteria. No more than ${MAX_LIST_ITEMS} items in a list or sub-list.`,
+	`- Plain English: at most ${MAX_SENTENCE_WORDS} words per sentence, active voice, simple tenses, one term for one thing. Use can/will/must, not should/may/might.`,
+	`- No em-dashes, no bold, no emoji, no filler (${FILLER_TERMS.join(", ")}). State the fact, not its importance.`,
+	"- End with one next step for the reader, for example \"Review: start at `src/auth.ts:42`.\"",
+	`- Keep the visible text at ${WORD_LIMITS.pr} words or fewer (comments: ${WORD_LIMITS.comment}). Code, URLs, HTML comments, tables, headings and <details> blocks do not count. Put long required content (evidence bundles, decisions, logs) at the end in one <details><summary>…</summary> block.`,
+	"- Keep every heading, section and marker that a skill template requires: shorten its content or move it into <details>, never drop or rename it.",
+	"- Never change code, identifiers, commands, paths, error text or numbers to fit these rules.",
+].join("\n");
+
+/** The rules for the system prompt, or undefined when the style is off. */
+export function styleGuideFor(mode: GitHubStyleMode): string | undefined {
+	return mode === "off" ? undefined : GITHUB_STYLE_GUIDE;
+}
+
+// ---------------------------------------------------------------- lint
+
+/**
+ * Marks where a block (code, table, <details>, comment) was removed, so the lists and paragraphs on
+ * either side stay apart. A blank line cannot do this: list items may have blank lines between them.
+ * The break keeps the block's indentation, so a block inside a list item stays part of that item.
+ */
+const BLOCK_BREAK = "\u0000";
+
+const isSpaceOrTab = (char: string | undefined) => char === " " || char === "\t";
+
+/**
+ * Remove every `open ... close` span (case-insensitive), in one pass. A span alone on its lines
+ * becomes a block break; a span inside a line becomes a space. An unclosed span runs to the end.
+ */
+function removeSpans(text: string, open: string, close: string): string {
+	const lower = text.toLowerCase();
+	let out = "";
+	let i = 0;
+	while (i < text.length) {
+		const openAt = lower.indexOf(open, i);
+		if (openAt < 0) break;
+		const closeAt = lower.indexOf(close, openAt + open.length);
+		const spanEnd = closeAt < 0 ? text.length : closeAt + close.length;
+		let lineStart = openAt;
+		while (isSpaceOrTab(text[lineStart - 1])) lineStart--;
+		let lineEnd = spanEnd;
+		while (isSpaceOrTab(text[lineEnd])) lineEnd++;
+		const aloneOnLine = (lineStart === 0 || text[lineStart - 1] === "\n") && (lineEnd === text.length || text[lineEnd] === "\n");
+		out += text.slice(i, openAt) + (aloneOnLine ? BLOCK_BREAK : " ");
+		i = spanEnd;
+	}
+	return out + text.slice(i);
+}
+
+const FENCE = /^[ \t]*(`{3,}|~{3,})/;
+const TABLE_ROW = /^[ \t]*\|/;
+const HEADING = /^[ \t]*#{1,6}(?:[ \t]|$)/;
+const LIST_MARKER = /^([ \t]*)(?:[-*+]|\d+[.)])[ \t]+(?:\[[ xX]\][ \t]+)?/;
+
+/** The body as the reader first sees it: no code, URLs, collapsed details, HTML comments or tables. */
+export function visibleText(body: string): string {
+	return visibleWithBreaks(body).replaceAll(BLOCK_BREAK, "");
+}
+
+/** visibleText, with a BLOCK_BREAK line where each block was removed. */
+function visibleWithBreaks(body: string): string {
+	// Code goes first, so a `<details>` or `<!--` quoted in code is not taken for HTML.
+	const withoutCode = removeFencedCode(body.replace(/\r\n?/g, "\n")).replace(/`[^`\n]*`/g, "");
+	return removeSpans(removeSpans(withoutCode, "<!--", "-->"), "<details", "</details>")
+		.split("\n")
+		.map((line) => (TABLE_ROW.test(line) ? indentOf(line) + BLOCK_BREAK : line))
+		.join("\n")
+		.replace(/https?:\/\/\S+/g, "");
+}
+
+/** Each line of a fenced block becomes a block break with the opening fence's indentation, blank lines included. */
+function removeFencedCode(text: string): string {
+	let fence: { marker: string; indent: string } | undefined;
+	return text
+		.split("\n")
+		.map((line) => {
+			const marker = FENCE.exec(line)?.[1];
+			if (fence) {
+				const indent = fence.indent;
+				if (marker && marker[0] === fence.marker[0] && marker.length >= fence.marker.length) fence = undefined;
+				return indent + BLOCK_BREAK;
+			}
+			if (!marker) return line;
+			fence = { marker, indent: indentOf(line) };
+			return fence.indent + BLOCK_BREAK;
+		})
+		.join("\n");
+}
+
+function indentOf(line: string): string {
+	return /^[ \t]*/.exec(line)?.[0] ?? "";
+}
+
+/** Indentation width in columns, a tab counting as TAB_WIDTH. */
+function indentWidth(indent: string): number {
+	return indent.replace(/\t/g, " ".repeat(TAB_WIDTH)).length;
+}
+
+function splitWords(text: string): string[] {
+	return text.match(/[A-Za-z0-9][\w'’./#:-]*/g) ?? [];
+}
+
+function clip(text: string, maxChars = EXAMPLE_SENTENCE_CHARS): string {
+	const collapsed = text.trim().replace(/\s+/g, " ");
+	return collapsed.length > maxChars ? `${collapsed.slice(0, maxChars)}…` : collapsed;
+}
+
+/** Paragraphs and list items, each joined onto one line, so a hard-wrapped sentence is measured whole. */
+function textBlocks(visible: string): string[] {
+	const blocks: string[] = [];
+	let blockLines: string[] = [];
+	const flush = () => {
+		if (blockLines.length) blocks.push(blockLines.join(" "));
+		blockLines = [];
+	};
+	for (const line of visible.split("\n")) {
+		if (!line.trim() || line.trim() === BLOCK_BREAK || HEADING.test(line)) {
+			flush();
+			continue;
+		}
+		const item = LIST_MARKER.exec(line);
+		if (item) flush();
+		blockLines.push(item ? line.slice(item[0].length) : line.trim());
+	}
+	flush();
+	return blocks;
+}
+
+/** Items of the longest list. A sub-list is a list of its own; its items do not count for the parent. */
+function longestListRun(visible: string): number {
+	let longest = 0;
+	const open: { indent: number; items: number }[] = [];
+	for (const line of visible.split("\n")) {
+		const item = LIST_MARKER.exec(line);
+		if (item) {
+			const indent = indentWidth(item[1]);
+			while (open.length && open[open.length - 1].indent > indent) open.pop();
+			const top = open[open.length - 1];
+			if (top?.indent === indent) top.items++;
+			else open.push({ indent, items: 1 });
+			longest = Math.max(longest, open[open.length - 1].items);
+		} else if (line.trim() && indentWidth(indentOf(line)) < 2) open.length = 0;
+	}
+	return longest;
+}
+
+const HEDGES = /\b(?:should|might|may)\b/gi;
+const FILLER = new RegExp(`\\b(?:${FILLER_TERMS.join("|")})\\b`, "gi");
+
+type LintRule = (text: GhText, visible: string) => string | undefined;
+
+const uniqueLowercased = (matches: string[]) => [...new Set(matches.map((m) => m.toLowerCase()))];
+
+/** Hedge words in any case, except "May" as a month ("May 2026"). */
+function findHedges(visible: string): string[] {
+	const monthAfterMatch = /[ \t]+\d/y;
+	const isMonth = (m: RegExpExecArray) => {
+		monthAfterMatch.lastIndex = m.index + m[0].length;
+		return m[0] === "May" && monthAfterMatch.test(visible);
+	};
+	return [...visible.matchAll(HEDGES)].filter((m) => !isMonth(m)).map((m) => m[0]);
+}
+
+const LINT_RULES: LintRule[] = [
+	({ title }) =>
+		title !== undefined && title.length > MAX_TITLE_CHARS
+			? `Title has ${title.length} characters. Keep it at ${MAX_TITLE_CHARS} or fewer.`
+			: undefined,
+	({ kind }, visible) => {
+		const limit = WORD_LIMITS[kind];
+		const count = splitWords(visible.split("\n").filter((l) => !HEADING.test(l)).join("\n")).length;
+		return count > limit
+			? `Body has ${count} visible words. Keep it at ${limit} or fewer: cut, or move long required content into one <details> block at the end.`
+			: undefined;
+	},
+	(_, visible) => (visible.includes("—") ? "Remove the em-dashes (—). Write two sentences or name the relation (because, but)." : undefined),
+	(_, visible) => {
+		const spans = visible.match(/\*\*[^*\n]+\*\*/g);
+		return spans ? `Remove the bold (${spans.slice(0, MAX_BOLD_EXAMPLES).map((b) => clip(b, EXAMPLE_BOLD_CHARS)).join(", ")}).` : undefined;
+	},
+	(_, visible) => {
+		const hedges = uniqueLowercased(findHedges(visible));
+		return hedges.length ? `Replace ${hedges.map((h) => `"${h}"`).join(", ")} with can, will or must, or delete it.` : undefined;
+	},
+	(_, visible) => {
+		const filler = uniqueLowercased(visible.match(FILLER) ?? []);
+		return filler.length ? `Delete the filler words: ${filler.map((f) => `"${f}"`).join(", ")}.` : undefined;
+	},
+	(_, visible) => {
+		const longSentences = textBlocks(visible)
+			.flatMap((block) => block.split(/(?<=[.!?])\s+/))
+			.filter((sentence) => splitWords(sentence).length > MAX_SENTENCE_WORDS);
+		return longSentences.length
+			? `Split ${longSentences.length} sentence(s) over ${MAX_SENTENCE_WORDS} words, for example: "${clip(longSentences[0])}"`
+			: undefined;
+	},
+	(_, visible) => {
+		const items = longestListRun(visible);
+		return items > MAX_LIST_ITEMS
+			? `A list has ${items} items. Keep at most ${MAX_LIST_ITEMS}: group them, or move the rest into a <details> block.`
+			: undefined;
+	},
+];
+
+/** Breaks of the mechanical rules in GITHUB_STYLE_GUIDE. Empty when the text passes. */
+export function lintGhText(ghText: GhText): string[] {
+	if (ghText.bodyFileTooLarge || (ghText.body !== undefined && ghText.body.length > MAX_LINT_CHARS)) {
+		return [`The body is longer than ${MAX_LINT_CHARS} characters. Cut it, or link to a file in the repository.`];
+	}
+	const visible = ghText.body === undefined ? "" : visibleWithBreaks(ghText.body);
+	return LINT_RULES.map((rule) => rule(ghText, visible)).filter((p): p is string => p !== undefined);
+}
+
+export function styleFeedback(problems: string[]): string {
+	return [
+		"dev-team GitHub style: rewrite the text before you send it (see \"GitHub text style\" in the system prompt).",
+		...problems.map((p) => `- ${p}`),
+		"Keep code, identifiers, commands, paths, error text, numbers and required template sections exactly as they are. If a rule cannot apply, send the same command with the same text again: the second identical call is not blocked.",
+	].join("\n");
+}
+
+// ---------------------------------------------------------------- gate
+
+export interface StyleVerdict {
+	/** Reason to block the call. */
+	block?: string;
+	/** Advisory for the model; the call runs. */
+	note?: string;
+}
+
+/**
+ * The block-once policy. In "block" mode a command whose text breaks the rules is blocked the first
+ * time and passes when sent again with the same text, so a rule that cannot apply never traps the
+ * agent. The key is the command and the text it sends, so an edited body file is checked again. The
+ * gate remembers blocked keys by hash, at most `maxRememberedBlocks`, oldest forgotten first.
+ */
+export function createStyleGate(maxRememberedBlocks = MAX_REMEMBERED_BLOCKS): (mode: GitHubStyleMode, command: string, cwd: string) => StyleVerdict {
+	const blockedCommandHashes = new Set<string>();
+	return (mode, command, cwd) => {
+		if (mode === "off") return {};
+		const ghTexts = extractGhTexts(command, cwd);
+		const problems = ghTexts.flatMap(lintGhText);
+		if (!problems.length) return {};
+		const feedback = styleFeedback(problems);
+		if (mode === "warn") return { note: feedback };
+		const key = createHash("sha256").update(JSON.stringify([command, ghTexts])).digest("hex");
+		if (blockedCommandHashes.has(key)) return {};
+		blockedCommandHashes.add(key);
+		if (blockedCommandHashes.size > maxRememberedBlocks) blockedCommandHashes.delete(blockedCommandHashes.values().next().value as string);
+		return { block: feedback };
+	};
+}