@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/skills/project-docs/scripts/state.ts

@@ -0,0 +1,316 @@
+/**
+ * Changelog state, for the `project-docs` skill.
+ *
+ * The skill's judgement is the model's; the counting is not. This prints what a
+ * changelog can be asked mechanically — the file, the last tag, the commits since it,
+ * the `[Unreleased]` categories, the empty and duplicate headings, the scope prefixes
+ * in use, and the link references — so an audit starts from facts instead of a
+ * hand-run `git log` whose flags and column are remembered differently each time.
+ *
+ * It ships inside the skill and resolves against the skill's own directory, so it
+ * imports nothing from the package's `lib/`: an installed copy has `skills/` and
+ * nothing else.
+ *
+ * Usage: `bun <skill>/scripts/state.ts [dir]`
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+/** One `###` category under `[Unreleased]`, as the file spells it. */
+export interface Category {
+	/** The heading text, exactly as written: `Fixed`, not `Fix`. */
+	name: string;
+	/** 1-based line of the heading. */
+	line: number;
+	/** Top-level bullets between this heading and the next one. */
+	bullets: number;
+}
+
+/** What the file's text alone says; `gitFacts` adds the part that needs a repository. */
+export interface State {
+	/** Whether the first paragraphs name Keep a Changelog and Semantic Versioning. */
+	keepAChangelog: boolean;
+	/** The `[Unreleased]` section, when the file keeps one. */
+	unreleased?: { line: number; categories: Category[]; bullets: number };
+	/** Every dated `## [X.Y.Z]` heading, newest first, which is the order released sections appear in. */
+	dated: { version: string; line: number }[];
+	/** A heading text used twice inside one section, with every line it occurs on. */
+	duplicates: { name: string; lines: number[] }[];
+	/** Scope prefixes and how often each appears, most used first. */
+	scopes: { name: string; count: number }[];
+	/** The link references the file defines, lowercased, and the dated sections that lack one. */
+	refs: { unreleased: boolean; dated: number; missing: string[] };
+}
+
+/** What the repository adds: the tag the window starts at, and what is in the window. */
+export interface GitFacts {
+	/** The newest tag, when the repository has one. */
+	tag?: string;
+	/** Subject lines of the non-merge commits since the tag, newest first. */
+	commits: string[];
+	/** Why a fact is absent, in words the report can print: no repository, no tags. */
+	note?: string;
+}
+
+/** Keep a Changelog's `## [Unreleased]`, and the un-bracketed spelling some files use. */
+const UNRELEASED = /^\[?unreleased\]?$/i;
+/** A dated section heading: `[0.17.0] - 2025-06-01`, `0.17.0`, or a project's own suffix. */
+const DATED = /^\[?(\d+\.\d+\.\d+[^\s\]]*)\]?/;
+const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+const FENCE = /^\s*(?:```|~~~)/;
+const BULLET = /^[-*+]\s+/;
+/** A bullet's scope: backticked, bold, or a bare `area:` prefix. Not a path, and not prose. */
+const SCOPE = /^[-*+]\s+(?:`([^`]+)`|\*\*([^*]+)\*\*|([A-Za-z][A-Za-z0-9./-]{0,24}))\s*:/;
+const LINK_REF = /^\[([^\]]+)\]:\s*\S+/;
+
+/** Report caps, so a long history stays one screen. */
+export const MAX_COMMITS = 40;
+export const MAX_SCOPES = 6;
+
+interface Heading {
+	level: number;
+	text: string;
+	line: number;
+}
+
+/** The changelog a project root holds, in the order projects name one. */
+export const CHANGELOG_NAMES = [
+	"CHANGELOG.md",
+	"CHANGELOG",
+	"CHANGES.md",
+	"HISTORY.md",
+	"NEWS.md",
+	join("docs", "CHANGELOG.md"),
+	join("docs", "changelog.md"),
+];
+
+/** The first changelog file in `dir`, as an absolute path, or undefined when it has none. */
+export function findChangelog(dir: string): string | undefined {
+	const root = resolve(dir);
+	for (const name of CHANGELOG_NAMES) {
+		const candidate = join(root, name);
+		if (existsSync(candidate)) return candidate;
+	}
+	return undefined;
+}
+
+/** Every heading outside a fence, so a `## example` in a code block is not a section. */
+function headingsOf(markdown: string): Heading[] {
+	const headings: Heading[] = [];
+	let fenced = false;
+	markdown.split("\n").forEach((text, index) => {
+		if (FENCE.test(text)) {
+			fenced = !fenced;
+			return;
+		}
+		if (fenced) return;
+		const match = HEADING.exec(text);
+		if (match !== null) headings.push({ level: match[1].length, text: match[2].trim(), line: index + 1 });
+	});
+	return headings;
+}
+
+/** The scope a bullet leads with, if it leads with one. */
+function scopeOf(line: string): string | undefined {
+	const match = SCOPE.exec(line);
+	if (match === null) return undefined;
+	return (match[1] ?? match[2] ?? match[3]).trim();
+}
+
+/** Bullet count and scopes over the given 1-based inclusive line window, outside fences. */
+function scanBullets(lines: readonly string[], start: number, end: number): { bullets: number; scopes: string[] } {
+	let bullets = 0;
+	const scopes: string[] = [];
+	let fenced = false;
+	for (let line = start; line <= end && line <= lines.length; line++) {
+		const text = lines[line - 1];
+		if (FENCE.test(text)) {
+			fenced = !fenced;
+			continue;
+		}
+		if (fenced || !BULLET.test(text)) continue;
+		bullets++;
+		const scope = scopeOf(text);
+		if (scope !== undefined) scopes.push(scope);
+	}
+	return { bullets, scopes };
+}
+
+/** Read the file's text into the facts the report prints. Pure, so a fixture can drive it. */
+export function readState(markdown: string): State {
+	const lines = markdown.split("\n");
+	const headings = headingsOf(markdown);
+	const preamble = lines.slice(0, 20).join("\n");
+
+	const unreleasedAt = headings.findIndex((heading) => heading.level === 2 && UNRELEASED.test(heading.text));
+	const dated = headings
+		.filter((heading) => heading.level === 2)
+		.flatMap((heading) => {
+			const version = DATED.exec(heading.text)?.[1];
+			return version === undefined ? [] : [{ version, line: heading.line }];
+		});
+
+	const scopes = new Map<string, number>();
+	for (const scope of scanBullets(lines, 1, lines.length).scopes) {
+		scopes.set(scope, (scopes.get(scope) ?? 0) + 1);
+	}
+
+	const duplicates = duplicateHeadings(headings);
+
+	const refs = new Map<string, number>();
+	for (const line of lines) {
+		const name = LINK_REF.exec(line)?.[1];
+		if (name !== undefined) refs.set(name.toLowerCase(), (refs.get(name.toLowerCase()) ?? 0) + 1);
+	}
+
+	let unreleased: State["unreleased"];
+	if (unreleasedAt !== -1) {
+		const heading = headings[unreleasedAt];
+		const nextSection = headings.slice(unreleasedAt + 1).find((entry) => entry.level <= 2);
+		const windowEnd = nextSection === undefined ? lines.length : nextSection.line - 1;
+		const inner = headings.filter((entry) => entry.line > heading.line && entry.line <= windowEnd);
+		const categories: Category[] = [];
+		inner
+			.filter((entry) => entry.level === 3)
+			.forEach((entry, index) => {
+				const next = inner.filter((item) => item.level === 3)[index + 1];
+				const categoryEnd = next === undefined ? windowEnd : next.line - 1;
+				categories.push({
+					name: entry.text,
+					line: entry.line,
+					bullets: scanBullets(lines, entry.line + 1, categoryEnd).bullets,
+				});
+			});
+		unreleased = {
+			line: heading.line,
+			categories,
+			bullets: categories.reduce((total, category) => total + category.bullets, 0),
+		};
+	}
+
+	return {
+		keepAChangelog: /keep a changelog/i.test(preamble) && /semantic versioning/i.test(preamble),
+		unreleased,
+		dated,
+		duplicates,
+		scopes: [...scopes.entries()]
+			.map(([name, count]) => ({ name, count }))
+			.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)),
+		refs: {
+			unreleased: refs.has("unreleased"),
+			dated: dated.length,
+			missing: dated.filter((entry) => !refs.has(entry.version.toLowerCase())).map((entry) => entry.version),
+		},
+	};
+}
+
+/** A trim with an ellipsis, so one long line cannot wrap the report. */
+function clip(text: string, width: number): string {
+	return text.length > width ? `${text.slice(0, width - 1)}…` : text;
+}
+
+/**
+ * A heading repeated inside one section, which is what a reader sees as one category
+ * split in two. The same `### Fixed` under each release is the format working, not a
+ * duplicate, so headings are grouped by the `##` section that contains them.
+ */
+function duplicateHeadings(headings: readonly Heading[]): { name: string; lines: number[] }[] {
+	const groups = new Map<string, { name: string; lines: number[] }>();
+	let section = "top";
+	for (const heading of headings) {
+		if (heading.level <= 2) section = heading.level === 2 ? heading.text.toLowerCase() : "top";
+		const key = `${section}\u0000${heading.text.toLowerCase()}`;
+		const group = groups.get(key) ?? { name: heading.text, lines: [] };
+		group.lines.push(heading.line);
+		groups.set(key, group);
+	}
+	return [...groups.values()].filter((group) => group.lines.length > 1);
+}
+
+/**
+ * The report. Every line is a fact with its source, in the order an audit uses them:
+ * the file, the window, the unreleased section, then what is wrong with the file, then
+ * what the window contains.
+ */
+export function formatState(file: string, state: State, git: GitFacts): string {
+	const out: string[] = [];
+	const preamble = state.keepAChangelog ? "Keep a Changelog preamble" : "no Keep a Changelog preamble";
+	out.push(`changelog   ${file} · ${preamble}`);
+
+	const count = `${git.commits.length} commit${git.commits.length === 1 ? "" : "s"} since, merges skipped`;
+	out.push(`last tag    ${git.tag === undefined ? (git.note ?? "no tags") : `${git.tag} · ${count}`}`);
+
+	out.push(
+		state.unreleased === undefined
+			? "unreleased  missing: the file has no `[Unreleased]` section"
+			: `unreleased  line ${state.unreleased.line} · ${state.unreleased.bullets} bullets`,
+	);
+	if (state.unreleased !== undefined) {
+		const named = state.unreleased.categories.map((category) => `${category.name} ${category.bullets}`);
+		out.push(`categories  ${named.length === 0 ? "none" : named.join(" · ")}   (file order)`);
+		const empty = state.unreleased.categories.filter((category) => category.bullets === 0).map((item) => item.name);
+		out.push(`empty       ${empty.length === 0 ? "none" : empty.join(" · ")}`);
+	}
+	out.push(
+		state.duplicates.length === 0
+			? "duplicate   none"
+			: `duplicate   ${state.duplicates
+					.slice(0, 4)
+					.map((entry) => `${entry.name} at lines ${entry.lines.join(", ")}`)
+					.join(" · ")}`,
+	);
+	const scopes = state.scopes.slice(0, MAX_SCOPES).map((entry) => `${entry.name} ${entry.count}`);
+	const rest = state.scopes.length - MAX_SCOPES;
+	out.push(
+		`scopes      ${scopes.length === 0 ? "none" : `${scopes.join(" · ")}${rest > 0 ? ` · … ${rest} more` : ""}`}`,
+	);
+	out.push(
+		`refs        [Unreleased] ${state.refs.unreleased ? "yes" : "no"} · dated refs ${state.refs.dated - state.refs.missing.length}/${state.refs.dated}${
+			state.refs.missing.length === 0 ? "" : `, missing ${state.refs.missing.slice(0, 5).join(", ")}`
+		}`,
+	);
+
+	if (git.commits.length > 0) {
+		out.push(`commits since ${git.tag ?? "the beginning"}`);
+		for (const commit of git.commits.slice(0, MAX_COMMITS)) out.push(`  ${clip(commit, 110)}`);
+		const more = git.commits.length - MAX_COMMITS;
+		if (more > 0) out.push(`  … ${more} more`);
+	}
+	return `${out.join("\n")}\n`;
+}
+
+/** Run one git command, returning its trimmed stdout or a reason it produced none. */
+function git(args: readonly string[], cwd: string): { text?: string; error?: string } {
+	const result = Bun.spawnSync({ cmd: ["git", ...args], cwd, stdout: "pipe", stderr: "pipe" });
+	if (result.exitCode !== 0) return { error: result.stderr.toString().trim() || `git ${args[0]} failed` };
+	return { text: result.stdout.toString().trim() };
+}
+
+/**
+ * The tag to audit from, and the non-merge commits after it. A repository with no
+ * tags has no window, and a directory outside git has neither; both are reported as a
+ * note rather than an error, because the file half of the report is still useful.
+ */
+export function gitFacts(cwd: string): GitFacts {
+	const inside = git(["rev-parse", "--is-inside-work-tree"], cwd);
+	if (inside.text !== "true") return { commits: [], note: "not a git repository" };
+
+	const described = git(["describe", "--tags", "--abbrev=0"], cwd);
+	const tag = described.text === "" ? undefined : described.text;
+	const range = tag === undefined ? ["HEAD"] : [`${tag}..HEAD`];
+	const log = git(["log", "--no-merges", "--format=%h %s", ...range], cwd);
+	const commits = (log.text ?? "").split("\n").filter((line) => line.trim() !== "");
+	return { tag, commits, note: tag === undefined ? "no tags" : undefined };
+}
+
+if (import.meta.main) {
+	const dir = resolve(process.argv[2] ?? ".");
+	const changelog = findChangelog(dir);
+	if (changelog === undefined) {
+		console.error(`no changelog in ${dir}: looked for ${CHANGELOG_NAMES.join(", ")}`);
+		process.exit(1);
+	}
+	const state = readState(readFileSync(changelog, "utf-8"));
+	process.stdout.write(formatState(relative(dir, changelog), state, gitFacts(dir)));
+}

package/skills/refactor/SKILL.md

@@ -1,141 +1,116 @@
 ---
 name: refactor
-description: "Find and rank refactoring opportunities in a project or path: duplication, oversized modules, coupling, drift, and high-churn code with weak tests. Use when asked what to refactor, where the code is tangled, or for a refactor audit; discovery is read-only and returns an evidence-based shortlist."
+description: "Audit a project or path for refactoring opportunities — duplication, oversized modules, coupling, drift, high-churn code with weak tests — and return a ranked shortlist with path:line evidence, or carry one chosen candidate through a behaviour-preserving refactor. Use when asked what to refactor, where the code is tangled, for a refactor audit, or to execute a refactor already agreed; discovery is read-only."
+compatibility: "Bun for scripts/inventory.ts; git for the churn window."
 ---
 
 # Find refactoring opportunities
 
-This is an audit, not an edit session. The deliverable is a ranked shortlist with
-evidence; do not modify files while discovering. The skill is model-invoked when
-a request matches the description; `/skill:refactor` is the explicit fallback.
+Goal: a ranked shortlist a reader can act on — evidence at `path:line`, a verification
+command per candidate, and the reasoning a reviewer can argue with. This is an audit:
+nothing is modified before the user picks a candidate.
 
 A refactor changes structure without changing behavior. If the request changes
-behavior, call it a behavior change and report it separately. Read the
-repository's own instructions first; they win over this skill.
+behavior, say so and treat it as a behavior change, not as this. The project's own
+instructions and thresholds win over anything here.
+
+## Start here
+
+```bash
+bun <skill>/scripts/inventory.ts <path ...> [--churn-days N] [--limit N]
+```
+
+Resolved against this skill's own directory. It prints the scope, the languages it
+measured, the size distribution, fan-in, churn over a stated window, test proximity,
+and the files above the 90th percentile in any of those — facts, never a verdict. The
+numbers are the evidence; the ranking is yours.
+
+When it reports `no history`, an `unresolved` count, or a `skipped` language, repeat
+that in the report rather than reading the gap as zero. See
+[`references/signals.md`](./references/signals.md) for what it measures, what it
+cannot, and what each signal needs before it counts.
 
 ## 1. Resolve the scope
 
-The text after `/skill:refactor` is the task. It may contain a path (`@src`,
-`src`, `packages/api`, or a path inside a sentence), a question, or both.
-
-- Resolve each path from the working directory. A directory is the audit scope;
-  a file is the initial target. Audit multiple paths separately and report them
-  together.
-- No path means the current project. If the project is large, propose a scope
-  from the documented layout instead of scanning everything blindly.
-- If a path does not exist, say so and ask for a real one. Do not guess. Do not
-  leave the working directory unless the user explicitly supplied an outside
-  path.
+The text after `/skill:refactor` is the task: a path, a question, or both.
+
+- Resolve each path from the working directory. A directory is the audit scope; a file
+  is the initial target. Audit several paths separately and report them together.
+- No path means the current project. When the project is large, do not scan
+  everything: ask which scope to audit, offering two to four concrete directories with
+  their file counts.
+- A path that does not exist is a question, not a guess. Ask for a real one, and do not
+  leave the working directory unless the user named a path outside it.
 - State the resolved scope and the number of files examined in the report.
 
 ## 2. Learn the project's standards
 
-- Read the repository's instruction files, contributor guide, architecture
-  notes, shared-helper documentation, and CI configuration.
-- Record the languages, layout, test framework, documented check commands, size
-  or complexity thresholds, and ignore rules.
-- Do not import an external style guide, install a tool, or apply a threshold the
-  project never stated. If there is no stated threshold, compare against the rest
-  of the scope and say that is the basis.
-- Note the available evidence: tests, coverage, type checking, linting, git
-  history, and any scanner already installed.
-
-## 3. Inventory the scope
-
-- Map source files, tests, exports, imports, and entry points. Mark public
-  surface versus internal modules.
-- Measure cheap facts: file and function sizes, nesting depth, parameter counts,
-  export counts, fan-in and fan-out, and the distance to the nearest test.
-- Read git history for churn (`git log --numstat`) inside the scope. Churn is
-  context, not a verdict: a frequently changed, tangled file is a stronger
-  candidate than a stable, isolated oddity.
-- Skip version-control metadata, dependencies, build output, generated files,
-  vendored trees, and secrets unless the user explicitly includes them. Respect
-  the project's ignore files.
-- For a large scope, delegate a read-only survey to a read-only helper if the
-  host provides one. Keep the filtering and ranking in the main session.
-
-## 4. Detect signals
-
-For every signal, point at a file and line and explain why it matters here.
-
-| Signal | What to look for | Evidence to cite |
-|---|---|---|
-| Duplication | The same body or a near-identical block in several places; copy-paste with tiny edits; a helper that already exists in a shared location | Paths and line ranges of each copy; the shared location it should use |
-| Size and responsibility | A module or function past the project's limit, or a relative outlier; unrelated exports; deep nesting; long parameter lists | Measured size or responsibility list; the seams where it could split |
-| Coupling | Circular or layer-crossing imports, high fan-in or fan-out, feature envy, repeated type switches | The import edge or repeated branch, with both sides named |
-| Cohesion and drift | A grab-bag utility module; a name that no longer matches behavior; dead exports; commented-out code; two implementations of one concept | The mismatch or unused export, with its callers |
-| Change pressure | High recent churn combined with complexity or weak tests | Churn count over a stated window plus the complexity or test gap |
-| Test friction | Behavior with no direct test; tests that mock the unit heavily or assert internals; duplicated setup that hides a missing seam | The test path and the missing or brittle assertion |
-| Boundary erosion | Leaking internal types, unchecked casts, mode-selecting boolean parameters, null-heavy returns | The boundary location and the caller that must know the internals |
-
-## 5. Verify and filter
-
-A signal is not a candidate until it is confirmed.
-
-- Read the callers and tests, not just the definition. Duplication may be
-  intentional for a protocol version; a large module may be cohesive; an
-  "unused" export may be public API.
-- Require one concrete artifact: a path with line numbers, a counted duplicate, a
-  measured size, a dependency edge, or a test gap. If you cannot point at it,
-  drop it.
-- Keep pure refactors separate from behavior changes and bugs. Report a bug as a
-  bug; do not smuggle it into the refactor list.
-- Prefer candidates with an existing test that catches a regression. If the
-  behavior is untested, mark the candidate "tests first".
-- Reject weak candidates explicitly. A short "not worth it" list proves the
-  audit was selective rather than a tour of everything unfamiliar.
-
-## 6. Rank
-
-Use three tiers:
-
-- **Do next:** safe, contained blast radius, high leverage, small or medium
-  effort, and a fast verification command.
-- **Worth planning:** high leverage but more risk or effort, a public surface, or
+Read the instruction files, contributor guide, architecture notes, and CI
+configuration. Record the languages, layout, test framework, the check command, the
+size or complexity thresholds, and the ignore rules.
+
+A threshold counts only when it is quoted with the file that states it. With no stated
+threshold, compare against the rest of the scope — and say that the comparison is what
+the finding rests on. Do not import an external style guide, install a tool, or apply a
+number the project never chose.
+
+## 3. Read, detect, confirm
+
+The outlier list from the script is the reading list and the budget; the report says
+what was left outside it. Walk the signals in
+[`references/signals.md`](./references/signals.md) — duplication, size, coupling,
+cohesion and drift, change pressure, shotgun surgery, test friction, boundary erosion,
+doc-versus-code drift — and remember the script measures per file, not per symbol, so
+nesting, parameter counts, and function length come from reading.
+
+A signal is not a candidate until it is confirmed. Read the callers and tests, not just
+the definition: duplication may be deliberate, a large module may be cohesive, an
+"unused" export may be public API. Every kept candidate carries one concrete artifact —
+a path with line numbers, a counted duplicate, a measured size, an import edge, or a
+named test gap. A bug is reported as a bug, never smuggled into the list. A candidate
+without a test is marked "tests first".
+
+## 5. Rank
+
+Three tiers, and no numeric score — the reasons have to be readable.
+
+- **Do next**: contained blast radius, high leverage, small or medium effort, fast
+  verification.
+- **Worth planning**: high leverage with more risk or effort, a public surface, or
   missing tests.
-- **Leave it:** low confidence, little leverage, or not worth the churn.
-
-Within a tier, order by leverage first, then safety, then cost. Do not invent a
-numeric score; the reasons must be readable.
-
-## 7. Report
-
-Keep the report scannable. Use this shape:
-
-- **Scope and method:** path, file count, tools used, and what was not examined.
-- **Top three to five opportunities**, each with a title, tier, evidence at
-  `path:line`, the proposed structural change, expected benefit, risk and blast
-  radius, effort (S/M/L), and the narrow plus full verification command.
-- **Rejected signals:** one line each with the reason it did not qualify.
-- **Next step:** ask which candidate to take. Do not start editing.
-
-## 8. Stop conditions
-
-- No worthwhile opportunities: say so with the evidence that was checked instead
-  of inventing work.
-- The request is a specific refactor rather than an audit: skip the shortlist,
-  but use the handoff below.
-- The request changes behavior or asks for a rewrite: treat it as an approved
-  design change, not this audit.
-- The scope cannot be read (missing path, secrets, binary or generated files, or
-  an inaccessible tree): report the limitation.
-
-## After selection: safe handoff
-
-If the user chooses a candidate, execution follows these rules:
-
-- State the behavior contract and run the project's documented check to get a
-  baseline. Record pre-existing failures.
-- If the behavior is untested, add characterization tests first.
-- Enter plan mode when the host provides it and the change spans files, changes a
-  public surface, or has an unknown step list. Otherwise track the steps in a
-  todo list or a short written sequence.
-- Make one structural change per step and verify each step. Never mix in
-  formatting, bug fixes, or unrelated cleanup.
-- Finish with the full project check and report the diff, results, and remaining
-  risk. Do not commit unless the user asks.
-
-The audit is done when the scope is stated, every candidate has `path:line`
-evidence and a verification command, the shortlist is capped, rejected signals
-are explained, and no files were modified.
+- **Leave it**: low confidence, little leverage, or not worth the churn.
+
+Within a tier, order by leverage, then safety, then cost.
+
+## 6. Report
+
+- **Scope and method**: path, file count, what was measured, and what was not examined.
+- **Top three to five**: title, tier, evidence at `path:line`, the structural change,
+  expected benefit, risk and blast radius, effort (S/M/L), and the narrow plus full
+  verification command.
+- **Rejected signals**: one line each, with the reason it did not qualify.
+- **Next step**: ask which candidate to take, offering the shortlist by name.
+
+## 7. From audit to execution
+
+When the user picks one, read [`references/handoff.md`](./references/handoff.md)
+before the first edit: a stated behaviour contract, a recorded baseline,
+characterisation tests first when the behaviour is untested, one structural change per
+step, and no mixed cleanup are what keep the promise.
+
+## Quality gate
+
+- The scope, the file count, and what was not examined are stated.
+- Every candidate has `path:line` evidence, a verification command, a tier, and an
+  effort; none carries a numeric score.
+- The rejected list is not empty, and it explains each rejection.
+- No file was modified, and no bug or behaviour change is in the refactor list.
+
+## Stop conditions
+
+- Nothing worth doing: say so with what was checked instead of inventing work.
+- The request is one specific refactor, not an audit: skip the shortlist and go to
+  handoff.
+- The request is a rewrite or a behaviour change: treat it as the design change it is.
+- The scope cannot be read — missing path, secrets, generated or binary files, an
+  inaccessible tree: report the limitation and stop.

package/skills/refactor/references/handoff.md

@@ -0,0 +1,35 @@
+# After a candidate is chosen
+
+The audit is over; this is execution, and its only promise is that behavior does not
+change. These are the rules that keep that promise — the rest is ordinary work.
+
+## Before the first edit
+
+- **State the behaviour contract.** One paragraph: what must stay true, which callers
+  rely on it, and which parts are explicitly free to change. If the contract is
+  ambiguous, ask now rather than discovering it in the diff.
+- **Record a baseline.** Run the project's documented check and keep the result. A
+  pre-existing failure is not this refactor's to fix, and a refactor that turns one
+  test from red to green has changed something nobody asked about.
+- **Add characterisation tests first when the behaviour is untested.** They capture
+  what the code does today, including the parts you consider wrong, because that is
+  the only net under a structural change.
+
+## While it moves
+
+- **One structural change per step**, each with its own verification. A rename, an
+  extraction, and a move are three steps, not one; a step that cannot be verified on
+  its own is too large.
+- **Never mix in** formatting, a bug fix, a dependency bump, or unrelated cleanup. If
+  the new structure makes one of those obvious, finish, report it, and do it as its
+  own change.
+- **Ceremony by size**: plan mode for a change that spans files, touches a public
+  surface, or has a step list you cannot write down up front; a todo list for the rest.
+- **Stop if it turns into a behaviour change.** Say so, and treat it as the design
+  change it now is, rather than smuggling it through under the old name.
+
+## Finishing
+
+- Run the full check, not only the narrow command, and compare against the baseline.
+- Report the diff's shape, what the check said, and what is still risky or unverified.
+- Do not commit unless the user asks.