@kitschpatrol/chagent 0.3.0 → 0.5.0

package/dist/{review-ClBbl31P.js → review-Bl10DPO7.js}

@@ -9,13 +9,13 @@ import semver from "semver";
 import { parse } from "yaml";
 import crossSpawn from "cross-spawn";
 import { existsSync } from "node:fs";
-import { pathToFileURL } from "node:url";
 import { cosmiconfig } from "cosmiconfig";
+import { pathToFileURL } from "node:url";
 import { isCancel, select } from "@clack/prompts";
 
 // package.json
 var name = "@kitschpatrol/chagent";
-var version = "0.3.0";
+var version = "0.5.0";
 var engines = { "node": "^24.16.0 || >=26.3.0" };
 
 // src/lib/defaults.ts
@@ -25,6 +25,7 @@ const defaults = {
 	effort: "xhigh",
 	github: true,
 	maxInputChars: 8e4,
+	rootChangelog: "summary",
 	timeout: 20
 };
 const defaultModels = {
@@ -236,6 +237,7 @@ async function readBlobs(root, objects) {
 const LOCKFILE_PATH = /(?:^|\/)(?:pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|deno\.lock|uv\.lock|poetry\.lock|pdm\.lock|Pipfile\.lock|Cargo\.lock|Gemfile\.lock|composer\.lock|go\.sum)$/v;
 const TAG_DECORATION = "tag: refs/tags/";
 const GITHUB_REMOTE = /github\.com[:\/]([^\/]+\/[^\/]+?)(?:\.git)?$/v;
+const SHORT_VERSION = /^\d+(?:\.\d+)?$/v;
 const manifestSchema$1 = z.object({
 	dependencies: z.record(z.string(), z.string()).optional(),
 	engines: z.object({ node: z.string().optional() }).optional(),
@@ -392,6 +394,29 @@ function packageInfo(manifest, directory, fallback) {
 		version: manifest?.version
 	};
 }
+/**
+* Read a version, with how many of its parts are spelled out. Short versions
+* such as `1` or `1.2` name the first release of their series.
+*/
+function parseVersion(value) {
+	const version = semver.valid(value);
+	if (version !== null) return {
+		precision: 3,
+		version
+	};
+	if (!SHORT_VERSION.test(value)) return;
+	const parts = value.split(".");
+	const padded = semver.valid([
+		...parts,
+		"0",
+		"0"
+	].slice(0, 3).join("."));
+	return padded === null ? void 0 : {
+		precision: parts.length,
+		version: padded
+	};
+}
+/** Read the version a tag names for a package, using its tag patterns. */
 function tagVersion(tag, pkg, patterns) {
 	const templates = patterns ?? [
 		"{name}@{version}",
@@ -402,10 +427,23 @@ function tagVersion(tag, pkg, patterns) {
 	for (const pattern of templates) {
 		const [prefix, suffix = ""] = pattern.replaceAll("{name}", () => pkg.name).split("{version}", 2);
 		if (prefix === void 0 || !tag.startsWith(prefix) || !tag.endsWith(suffix)) continue;
-		const value = tag.slice(prefix.length, suffix === "" ? void 0 : -suffix.length);
-		const version = semver.valid(value);
-		if (version !== null) return version;
+		const parsed = parseVersion(tag.slice(prefix.length, suffix === "" ? void 0 : -suffix.length));
+		const bareNumber = parsed?.precision === 1 && patterns === void 0 && !prefix.endsWith("v");
+		if (parsed !== void 0 && !bareNumber) return parsed;
+	}
+}
+/**
+* Check that a short tag such as `v1` or `v1.2` precedes every more precise tag
+* in its series. Floating tags that follow the latest release fail this check.
+*/
+async function leadsSeries(root, candidate, candidates) {
+	const major = semver.major(candidate.version);
+	const minor = semver.minor(candidate.version);
+	for (const other of candidates) {
+		if (other.precision <= candidate.precision || semver.major(other.version) !== major || candidate.precision === 2 && semver.minor(other.version) !== minor || semver.lt(other.version, candidate.version)) continue;
+		if (other.tag.commit === candidate.tag.commit || !await isAncestor(root, candidate.tag.commit, other.tag.commit)) return false;
 	}
+	return true;
 }
 /**
 * Predict the tag of a release that is not tagged yet, so its heading can link
@@ -486,21 +524,15 @@ function pnpmWorkspaceGlobs(text) {
 	if (!workspace.success) throw new Error(`Invalid pnpm-workspace.yaml:\n${z.prettifyError(workspace.error)}`, { cause: workspace.error });
 	return workspace.data?.packages;
 }
-async function workspacePackages(root, manifest, config) {
-	let patterns = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages ?? [];
-	const workspaceText = await readOptional(path.join(root, "pnpm-workspace.yaml"));
-	if (workspaceText !== void 0) patterns = pnpmWorkspaceGlobs(workspaceText) ?? patterns;
-	patterns = config.packages ?? patterns;
+/** Find directories matching globs, as POSIX paths relative to the root. */
+async function matchDirectories(root, patterns, exclude = []) {
 	const directories = [];
-	const positive = patterns.filter((pattern) => !pattern.startsWith("!"));
-	const negative = patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1));
-	const matches = glob(positive, {
+	const matches = glob(patterns, {
 		cwd: root,
 		exclude: [
 			"**/node_modules/**",
 			"**/.git/**",
-			...negative,
-			...config.exclude ?? []
+			...exclude
 		],
 		withFileTypes: true
 	});
@@ -508,6 +540,27 @@ async function workspacePackages(root, manifest, config) {
 		if (!entry.isDirectory()) continue;
 		directories.push(path.relative(root, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"));
 	}
+	return directories;
+}
+/** Mark the packages that remain boundaries but get no changelog. */
+async function markSkipped(root, packages, patterns) {
+	const skipped = /* @__PURE__ */ new Set();
+	for (const pattern of patterns) {
+		const matches = (await matchDirectories(root, [pattern])).filter((directory) => packages.some((pkg) => pkg.directory === directory));
+		if (matches.length === 0) throw new Error(`skipPackage pattern "${pattern}" matches no workspace package directory. Use a directory glob relative to the repository root, such as "packages/docs"; rootChangelog controls the root changelog.`);
+		for (const directory of matches) skipped.add(directory);
+	}
+	return packages.map((pkg) => skipped.has(pkg.directory) ? {
+		...pkg,
+		skipped: true
+	} : pkg);
+}
+async function workspacePackages(root, manifest, config) {
+	let patterns = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages ?? [];
+	const workspaceText = await readOptional(path.join(root, "pnpm-workspace.yaml"));
+	if (workspaceText !== void 0) patterns = pnpmWorkspaceGlobs(workspaceText) ?? patterns;
+	patterns = config.packages ?? patterns;
+	const directories = await matchDirectories(root, patterns.filter((pattern) => !pattern.startsWith("!")), [...patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1)), ...config.exclude ?? []]);
 	const packages = [];
 	for (const directory of directories.toSorted()) {
 		if (!(await realpath(path.join(root, directory))).startsWith(root + path.sep)) throw new Error(`Workspace package escapes the repository: ${directory}`);
@@ -515,30 +568,40 @@ async function workspacePackages(root, manifest, config) {
 		if (text === void 0 && config.packages === void 0) continue;
 		packages.push(packageInfo(text === void 0 ? void 0 : parseManifest(text, `${directory}/package.json`), directory, path.posix.basename(directory)));
 	}
-	return packages;
+	return markSkipped(root, packages, config.skipPackage ?? []);
+}
+/** Select the workspace packages that get changelogs of their own. */
+function describedPackages(repository) {
+	return repository.packages.filter((pkg) => pkg.skipped !== true);
 }
 async function taggedReleases(repository, pkg, config) {
 	const candidates = [];
 	for (const tag of repository.tags) {
-		const version = tagVersion(tag.name, pkg, config.tagPatterns);
-		if (version !== void 0) candidates.push({
-			tag,
-			version
+		const match = tagVersion(tag.name, pkg, config.tagPatterns);
+		if (match !== void 0) candidates.push({
+			...match,
+			tag
 		});
 	}
 	const isRoot = pkg.directory === ".";
 	const manifests = isRoot ? /* @__PURE__ */ new Map() : await manifestsAt(repository.root, pkg.directory, candidates.map(({ tag }) => tag.commit));
-	const releases = [];
-	for (const { tag, version } of candidates) {
+	const owned = [];
+	for (const candidate of candidates) {
 		if (!isRoot) {
-			const manifest = manifests.get(tag.commit);
-			if (manifest?.version !== void 0 && semver.valid(manifest.version) !== version) continue;
+			const manifest = manifests.get(candidate.tag.commit);
+			if (manifest?.version !== void 0 && semver.valid(manifest.version) !== candidate.version) continue;
 			if (manifest === void 0 && await git(repository.root, [
 				"cat-file",
 				"-t",
-				`${tag.commit}:${pkg.directory}`
+				`${candidate.tag.commit}:${pkg.directory}`
 			], true) !== "tree") continue;
 		}
+		owned.push(candidate);
+	}
+	const releases = [];
+	for (const candidate of owned) {
+		if (candidate.precision < 3 && !await leadsSeries(repository.root, candidate, owned)) continue;
+		const { tag, version } = candidate;
 		const existing = releases.find((release) => release.version === version);
 		if (existing && existing.ref !== tag.commit) throw new Error(`Multiple reachable tags disagree about ${pkg.name} ${version}. Configure tagPatterns to select a release series.`);
 		if (existing) continue;
@@ -618,13 +681,25 @@ manager, manifest format, or directory layout. Use snapshots at those refs, not
 uncommitted files or newer code at HEAD. Respect repository.directory and
 repository.excludeDirectories when deciding which changes belong in this entry;
 you may inspect related files for context. The supplied evidence is a starting
-point, not a limit on your research.
+point, not a limit on your research. Supplied commits leave out lockfiles and
+directories named build, coverage, dist, or changelog at the top of a package,
+which usually hold generated output. Judge those directories yourself: when one
+holds a project's source rather than generated output, its changes belong in the
+changelog like any others.
 
 When mode is initialize, reconstruct this release as part of the project's full
-historical changelog. When mode is update, cover all missing changes in the supplied range. In both modes, review
-every commit, diff, and associated PR before deciding what to include. A changelog
-records the evolution of the project, including maintenance releases; it is not
-just a list of new application features.
+historical changelog. When mode is update, cover all missing changes in the
+supplied range. When mode is revise, the existing entries are your own earlier
+draft of this release, describing it up to repository.from, and the supplied
+range is what has happened since. Return the complete entries for the release as
+it now stands; they replace the draft. Carry over what still holds, fold later
+fixes and refinements into the entries they affect, combine entries that turn
+out to describe one change, and drop an entry only when the range reverts or
+supersedes it. Keep the wording of entries that need no change. In every mode,
+review every commit, diff, and associated PR in the supplied range before
+deciding what to include. A changelog records the evolution of the project,
+including maintenance releases; it is not just a list of new application
+features.
 
 Cover distinct changes to behavior, public APIs and types, CLI flags and output,
 runtime compatibility, installation and distribution, documentation and examples,
@@ -653,9 +728,16 @@ Give distinct changes separate readable bullets;
 do not compress unrelated features or breaking changes into one long entry. Keep
 each entry concise without sacrificing coverage. Consolidate related commits,
 not unrelated changes. There is no three-entry limit for package scope, including
-a single-package repository's root changelog. Only scope=repository denotes a
-short monorepo root summary; prefer three highlights there because package
-changelogs contain the details.
+a single-package repository's root changelog.
+
+Only scope=repository asks for a summary: an entry in a monorepo's root
+changelog, which the caller ends with links to the package changelogs that hold
+the details. Write what a reader of the whole repository most needs to know, in
+at most three entries, rather than repeating package entries one by one. Combine
+related changes across packages and name the packages they affect. When
+repository.directory is a package, summarize that package's release; otherwise
+summarize the repository, including changes outside any package. Do not write
+the links yourself.
 
 Use commit messages and PRs to understand intent, then check the changed files
 and diffs. Inspect public interfaces at both ends of the range before claiming
@@ -694,25 +776,37 @@ Put breaking public changes in the appropriate standard category and set breakin
 to true; do not create a Breaking Changes category.
 Descriptions are single-line Markdown suitable for a list item,
 without a bullet prefix, heading, process explanation, or introductory paragraph.
-Every change must cite at least one evidence ID supplied for its own release in
-sources. Prefer the associated commit ID; use that release's range ID for changes
-established through your own Git research. Include a PR
+Every change must cite, in sources, at least one evidence ID supplied for its own
+release or the full ID of a commit within that release's range. Prefer the commit
+that made the change, including one found through your own Git research; use the
+release's range ID when no single commit establishes it. When mode is revise,
+cite the draft evidence ID for an entry carried over or rewritten from the
+existing entries, along with any commit that changed it. Include a PR
 link only when its URL and association are supplied. Do not fabricate links.
 
-Existing entries are provided only for deduplication and preservation. They are
-not independent evidence. Omit changes already expressed by those entries, even
-if you would phrase them differently. GitHub release-note bodies are deliberately
+Existing entries are provided for deduplication and preservation, and when mode
+is revise, as the draft to rewrite. They are not independent evidence. Unless
+mode is revise, omit changes already expressed by those entries, even if you
+would phrase them differently. GitHub release-note bodies are deliberately
 absent because this output will itself become GitHub release notes.
 Do not read existing changelog files, generated release-note files, or GitHub
 release bodies as source material, even when researching the repository directly.
 
+When styleReference is present, it is a recent release section of the changelog
+these entries will join. Match its writing conventions: voice and tense,
+capitalization, terminal punctuation, and how code, issues, and PRs are
+referenced. It is a style sample and nothing more. It describes another release,
+so it is not evidence, and its length and choice of categories say nothing about
+this one.
+
 Before returning, check coverage across behavior/API, compatibility, dependencies,
 documentation, build/test/CI, and distribution. Do not drop a change just because
 its commit is called chore, docs, build, or dependency updates. Return an empty
 changes array only when the evidence is entirely release-version bookkeeping,
 lockfile-only resolution changes, generated artifacts, formatting noise, or
-changes already covered by existing entries. Do not pad the result with
-unsupported changes.`;
+changes already covered by existing entries. When mode is revise, an empty array
+removes the draft, so return one only when nothing in the draft still holds. Do
+not pad the result with unsupported changes.`;
 /** Invalidates cached drafts whenever the instructions change. */
 const instructionVersion = hash(instructions);
 
@@ -735,8 +829,14 @@ const efforts = [
 	"xhigh",
 	"max"
 ];
+const rootChangelogs = [
+	"summary",
+	"package",
+	"none"
+];
 
 // src/lib/agents.ts
+const COMMIT_ID = /^[\da-f]{7,64}$/iv;
 const CONTROL_CHARACTERS = /\p{Cc}/v;
 const HEADING = /^#{1,6}\s/v;
 const LIST_MARKER = /^(?:[\-*]|\d+\.)(?:\s+|$)/v;
@@ -755,13 +855,10 @@ const responseJsonSchema = JSON.stringify(z.toJSONSchema(responseSchema, { targe
 function normalizeDescription(description) {
 	return description.replaceAll(WHITESPACE_RUN, " ").trim().replace(LIST_MARKER, "");
 }
-function validateChanges(changes, release) {
-	const ids = new Set(release.evidence.map((item) => item.id));
+function validateDescriptions(changes, id) {
 	return changes.map((change) => {
-		const unknown = change.sources.filter((source) => !ids.has(source));
-		if (unknown.length > 0) throw new Error(`Agent output for ${release.id} cites evidence that was not supplied: ${unknown.join(", ")}.`);
 		const description = normalizeDescription(change.description);
-		if (description === "" || CONTROL_CHARACTERS.test(description) || HEADING.test(description) || description.includes("<!--")) throw new Error(`Agent output for ${release.id} has an empty description, heading, or hidden markup: ${JSON.stringify(change.description)}.`);
+		if (description === "" || CONTROL_CHARACTERS.test(description) || HEADING.test(description) || description.includes("<!--")) throw new Error(`Agent output for ${id} has an empty description, heading, or hidden markup: ${JSON.stringify(change.description)}.`);
 		return {
 			...change,
 			description
@@ -769,8 +866,8 @@ function validateChanges(changes, release) {
 	});
 }
 /**
-* Validate structure, completeness, release identity, and citations before
-* accepting any adapter's output.
+* Validate structure, completeness, and release identity before accepting any
+* adapter's output. Citations are checked separately, by `verifyCitations`.
 *
 * @returns The change sets, with descriptions normalized.
 */
@@ -784,10 +881,53 @@ function validateResponse(value, releases) {
 	const omitted = expected.keys().filter((id) => !ids.includes(id)).toArray();
 	if (omitted.length > 0) throw new Error(`Agent output omitted requested releases: ${omitted.join(", ")}.`);
 	return response.data.releases.map(({ changes, id }) => ({
-		changes: validateChanges(changes, expected.get(id)),
+		changes: validateDescriptions(changes, id),
 		id
 	}));
 }
+/** List every commit in a release's range. */
+async function rangeCommits(root, { repository }) {
+	const { from, to } = repository;
+	return (await git(root, ["rev-list", from === void 0 ? to : `${from}..${to}`])).split("\n");
+}
+async function verifyChanges(root, release, changes) {
+	const supplied = new Set(release.evidence.map((item) => item.id));
+	let commits;
+	const verified = [];
+	for (const change of changes) {
+		const sources = /* @__PURE__ */ new Set();
+		for (const source of change.sources) if (supplied.has(source)) sources.add(source);
+		else if (COMMIT_ID.test(source)) {
+			commits ??= await rangeCommits(root, release);
+			const matches = commits.filter((commit) => commit.startsWith(source.toLowerCase()));
+			if (matches.length === 1) sources.add(matches[0]);
+		}
+		if (sources.size === 0) throw new Error(`Agent output for ${release.id} cites no supplied evidence or commit in its range: ${change.sources.join(", ")}. Cite an evidence ID supplied for that release, or the ID of a commit within its range.`);
+		verified.push({
+			...change,
+			sources: [...sources]
+		});
+	}
+	return verified;
+}
+/**
+* Check citations against Git instead of trusting them. A change may cite
+* evidence supplied for its release or any commit within that release's range,
+* which lets an agent cite what its own research found. Abbreviated commit IDs
+* are completed, and sources that hold up are kept when others do not. Pass the
+* requested releases with their complete evidence.
+*
+* @throws {Error} When a change is left without a source.
+*/
+async function verifyCitations(root, changeSets, releases) {
+	const requested = new Map(releases.map((release) => [release.id, release]));
+	const verified = [];
+	for (const { changes, id } of changeSets) verified.push({
+		changes: await verifyChanges(root, requested.get(id), changes),
+		id
+	});
+	return verified;
+}
 function prompt({ releases, repair, repositoryRoot }) {
 	const correction = repair === void 0 ? "" : `\n\nYour previous response failed validation: ${repair.error}\nPrevious response (JSON):\n${JSON.stringify(repair.response)}\nReturn the complete corrected JSON object. Keep your previous findings, and repeat only the research the correction needs.`;
 	return `${instructions}${correction}\n\nInput data (JSON):\n${JSON.stringify({
@@ -911,6 +1051,83 @@ function createAgent(name) {
 	};
 }
 
+// src/lib/config.ts
+const configSchema = z.strictObject({
+	agent: z.enum(agentNames).optional(),
+	cache: z.boolean().optional(),
+	effort: z.enum(efforts).optional(),
+	exclude: z.array(z.string()).optional(),
+	github: z.boolean().optional(),
+	/** Maximum evidence characters per agent request. */
+	maxInputChars: z.number().int().min(4e3).optional(),
+	model: z.string().min(1).optional(),
+	/** Workspace directory globs, overriding manifest workspace discovery. */
+	packages: z.array(z.string()).optional(),
+	/**
+	* What a monorepo's root changelog records: a summary of package releases,
+	* the root package's own changes, or nothing.
+	*/
+	rootChangelog: z.enum(rootChangelogs).optional(),
+	/** Workspace package directory globs that get no changelog of their own. */
+	skipPackage: z.array(z.string()).optional(),
+	/** Templates containing {version} and optionally {name}. */
+	tagPatterns: z.array(z.string().includes("{version}")).optional(),
+	/** Minutes each agent session may run. */
+	timeout: z.number().positive().max(maxTimeoutMinutes).optional()
+});
+const resolvedConfigSchema = configSchema.required({
+	agent: true,
+	cache: true,
+	effort: true,
+	github: true,
+	maxInputChars: true,
+	rootChangelog: true,
+	timeout: true
+}).transform(({ timeout, ...config }) => ({
+	...config,
+	timeoutMs: timeout * 6e4
+}));
+function invalidConfig(source, error) {
+	return new Error(`Invalid options in ${source}:\n${z.prettifyError(error)}`, { cause: error });
+}
+/** Define optional repository configuration with TypeScript completion. */
+function defineConfig(config) {
+	return config;
+}
+/** Load configuration from the repository root or an explicitly selected file. */
+async function loadConfig(root, file) {
+	const explorer = cosmiconfig("chagent", {
+		searchPlaces: [
+			"chagent.config.ts",
+			"chagent.config.mjs",
+			"chagent.config.js",
+			"chagent.config.json",
+			"package.json"
+		],
+		searchStrategy: "none"
+	});
+	const result = file === void 0 ? await explorer.search(root) : await explorer.load(file);
+	if (!result) {
+		log.debug("No configuration file found.");
+		return {};
+	}
+	log.debug(`Loaded configuration from ${result.filepath}.`);
+	const parsed = configSchema.safeParse(result.config);
+	if (!parsed.success) throw invalidConfig(result.filepath, parsed.error);
+	return parsed.data;
+}
+/**
+* Apply configuration layers over the defaults; later layers win and undefined
+* values do not.
+*/
+function resolveConfig(...layers) {
+	const merged = { ...defaults };
+	for (const layer of layers) for (const [key, value] of Object.entries(layer)) if (value !== void 0) merged[key] = value;
+	const parsed = resolvedConfigSchema.safeParse(merged);
+	if (!parsed.success) throw invalidConfig("generation settings", parsed.error);
+	return parsed.data;
+}
+
 // src/lib/format.ts
 const FORMATTER_PACKAGES = ["@kitschpatrol/shared-config", "@kitschpatrol/prettier-config"];
 const manifestSchema = z.object({ exports: z.object({ ".": z.object({ import: z.string() }) }) });
@@ -1013,9 +1230,11 @@ async function writeChangelog(plan) {
 			const edit = plan.files.find((file) => file.path === checkpoint.path);
 			try {
 				const written = edit === void 0 ? void 0 : await readOptional(edit.path);
+				const edited = edit !== void 0 && changelogHash(edit.after) !== checkpoint.contentHash;
 				await writeCache(path.join(stateDirectory, "checkpoints"), checkpoint.path, {
 					...checkpoint,
-					contentHash: written === void 0 ? checkpoint.contentHash : changelogHash(written)
+					contentHash: written === void 0 ? checkpoint.contentHash : changelogHash(written),
+					generated: checkpoint.generated && !edited
 				});
 			} catch {
 				plan.diagnostics.push("Could not save incremental metadata; the next run will recheck the full release range.");
@@ -1050,75 +1269,6 @@ async function acquireLock(file) {
 	}
 }
 
-// src/lib/config.ts
-const configSchema = z.strictObject({
-	agent: z.enum(agentNames).optional(),
-	cache: z.boolean().optional(),
-	effort: z.enum(efforts).optional(),
-	exclude: z.array(z.string()).optional(),
-	github: z.boolean().optional(),
-	/** Maximum evidence characters per agent request. */
-	maxInputChars: z.number().int().min(4e3).optional(),
-	model: z.string().min(1).optional(),
-	/** Workspace directory globs, overriding manifest workspace discovery. */
-	packages: z.array(z.string()).optional(),
-	/** Templates containing {version} and optionally {name}. */
-	tagPatterns: z.array(z.string().includes("{version}")).optional(),
-	/** Minutes each agent session may run. */
-	timeout: z.number().positive().max(maxTimeoutMinutes).optional()
-});
-const resolvedConfigSchema = configSchema.required({
-	agent: true,
-	cache: true,
-	effort: true,
-	github: true,
-	maxInputChars: true,
-	timeout: true
-}).transform(({ timeout, ...config }) => ({
-	...config,
-	timeoutMs: timeout * 6e4
-}));
-function invalidConfig(source, error) {
-	return new Error(`Invalid options in ${source}:\n${z.prettifyError(error)}`, { cause: error });
-}
-/** Define optional repository configuration with TypeScript completion. */
-function defineConfig(config) {
-	return config;
-}
-/** Load configuration from the repository root or an explicitly selected file. */
-async function loadConfig(root, file) {
-	const explorer = cosmiconfig("chagent", {
-		searchPlaces: [
-			"chagent.config.ts",
-			"chagent.config.mjs",
-			"chagent.config.js",
-			"chagent.config.json",
-			"package.json"
-		],
-		searchStrategy: "none"
-	});
-	const result = file === void 0 ? await explorer.search(root) : await explorer.load(file);
-	if (!result) {
-		log.debug("No configuration file found.");
-		return {};
-	}
-	log.debug(`Loaded configuration from ${result.filepath}.`);
-	const parsed = configSchema.safeParse(result.config);
-	if (!parsed.success) throw invalidConfig(result.filepath, parsed.error);
-	return parsed.data;
-}
-/**
-* Apply configuration layers over the defaults; later layers win and undefined
-* values do not.
-*/
-function resolveConfig(...layers) {
-	const merged = { ...defaults };
-	for (const layer of layers) for (const [key, value] of Object.entries(layer)) if (value !== void 0) merged[key] = value;
-	const parsed = resolvedConfigSchema.safeParse(merged);
-	if (!parsed.success) throw invalidConfig("generation settings", parsed.error);
-	return parsed.data;
-}
-
 // src/lib/changelog.ts
 const LINE_BOUNDARY = /(?<=\n)/v;
 const FENCE = /^\s{0,3}(`{3,}|~{3,})/v;
@@ -1130,9 +1280,14 @@ const WHITESPACE = /\s+/gv;
 const TERMINAL_PUNCTUATION = /[.!]$/v;
 const NEWLINE = /\r?\n/v;
 const BULLET = /^\s*[\-*] /v;
+const ENTRY = /^\s*[\-*] /mv;
+const STYLE_REFERENCE_LENGTH = 2e3;
 const CATEGORY_HEADING = /^### /mv;
+const PACKAGES_HEADING = /^### Packages\s*$/mv;
+const LINK_TARGET = /\]\(([^\)]*)\)/gv;
 const SEMVER_LINE = /^.*\[Semantic Versioning\].*(?:\r?\n|$)/mv;
 const UNRELEASED_REFERENCE = /^\[unreleased\]:[^\r\n]*(?:\r?\n)?/imv;
+const V_PREFIX = /^v\d/v;
 const changelogHeader = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n";
 /** The body of a release section without any changes to record. */
 const noNotableChanges = "No notable changes.";
@@ -1201,6 +1356,21 @@ function parseChangelog(content) {
 		sections
 	};
 }
+/**
+* Pick the newest release section with entries, to show an agent how this
+* changelog is written. Long sections are cut at a line boundary.
+*/
+function styleReference({ sections }) {
+	const body = sections.filter(({ version }) => version !== "Unreleased").map((section) => withoutPackageLinks(section.body)).find((entries) => ENTRY.test(entries));
+	if (body === void 0) return;
+	const lines = body.trim().split(LINE_BOUNDARY);
+	let sample = "";
+	for (const line of lines) {
+		if (sample.length + line.length > STYLE_REFERENCE_LENGTH) break;
+		sample += line;
+	}
+	return sample.trim() === "" ? void 0 : sample.trimEnd();
+}
 function normalized(description) {
 	return description.trim().toLowerCase().replaceAll(WHITESPACE, " ").replace(TERMINAL_PUNCTUATION, "");
 }
@@ -1240,6 +1410,46 @@ function laterCategoryIndex(body, category) {
 	const indexes = categories.slice(categories.indexOf(category) + 1).map((item) => categoryHeading(body, item)?.index).filter((index) => index !== void 0);
 	return indexes.length === 0 ? void 0 : Math.min(...indexes);
 }
+/** Locate the package links that end a root summary's section. */
+function packagesBlock(body) {
+	const heading = PACKAGES_HEADING.exec(body);
+	if (heading === null) return;
+	const after = heading.index + heading[0].length;
+	const next = CATEGORY_HEADING.exec(body.slice(after));
+	return {
+		start: heading.index,
+		end: next === null ? body.length : after + next.index
+	};
+}
+/** Remove the package links from a root summary's section, leaving its entries. */
+function withoutPackageLinks(body) {
+	const block = packagesBlock(body);
+	return block === void 0 ? body : body.slice(0, block.start) + body.slice(block.end);
+}
+/**
+* Check whether a section links to other package releases than it should.
+* Targets are compared, since a formatter may restyle the list around them.
+*/
+function packageLinksDiffer(body, links) {
+	const block = body === void 0 ? void 0 : packagesBlock(body);
+	const targets = body === void 0 || block === void 0 ? [] : body.slice(block.start, block.end).matchAll(LINK_TARGET).map((match) => match[1]).toArray();
+	return !isDeepStrictEqual(targets, links.map(({ url }) => url));
+}
+/**
+* Merge new changes into a section's draft, or replace a revised draft with
+* them, and end the section with its package links.
+*/
+function sectionBody({ changes, existingBody = "", links, revise }, newline) {
+	const draft = links === void 0 ? existingBody : withoutPackageLinks(existingBody);
+	const body = mergeChanges(revise === true ? "" : draft, changes, newline);
+	if (links === void 0 || links.length === 0) return body;
+	const list = links.map(({ label, url }) => `- [${label}](${url})`);
+	return body.trimEnd() + newline + newline + [
+		"### Packages",
+		"",
+		...list
+	].join(newline);
+}
 /** Render a release heading with an optional comparison link. */
 function releaseLink(github, release) {
 	if (github === void 0) return;
@@ -1260,12 +1470,16 @@ function updateMarkdown(original, entries, nodeException, github) {
 	const draft = parsed.sections.find((section) => section.version === "Unreleased");
 	const released = parsed.sections.filter((section) => section.version !== "Unreleased").map((section) => content.slice(section.start, section.end));
 	let draftText = draft === void 0 ? "" : content.slice(draft.start, draft.end);
-	for (const { changes, existingBody, release } of entries) {
+	for (const entry of entries) {
+		const { existingBody, release } = entry;
 		const link = releaseLink(github, release);
 		const heading = `## ${link === void 0 ? release.version : `[${release.version}]`}${release.date === void 0 ? "" : ` - ${release.date}`}`;
-		let body = mergeChanges(existingBody ?? "", changes, newline);
+		let body = sectionBody(entry, newline);
 		if (body.trim() === "") {
-			if (release.version === "Unreleased") continue;
+			if (release.version === "Unreleased") {
+				if (existingBody !== void 0) draftText = "";
+				continue;
+			}
 			body = newline + noNotableChanges + newline;
 		}
 		const section = heading + newline + newline + body.trim() + newline + newline;
@@ -1302,8 +1516,15 @@ function addNodeNote(header, newline, nodeException) {
 	}
 	return header;
 }
+/**
+* Read a heading's version the way default tag patterns read a tag, so `1.2`
+* and `v1` name the first release of their series and a bare `1` names none.
+*/
 function normalizeVersion(raw) {
-	return raw.toLowerCase() === "unreleased" ? "Unreleased" : semver.valid(raw) ?? raw;
+	if (raw.toLowerCase() === "unreleased") return "Unreleased";
+	const prefixed = V_PREFIX.test(raw);
+	const parsed = parseVersion(prefixed ? raw.slice(1) : raw);
+	return parsed === void 0 || !prefixed && parsed.precision === 1 ? raw : parsed.version;
 }
 function releaseHeadingVersion(line) {
 	const match = RELEASE_HEADING.exec(line.trimEnd());
@@ -1319,20 +1540,32 @@ function sectionSpacing(content, newline) {
 
 // src/lib/evidence.ts
 const COMMIT_MARKER = "
";
-const GENERATED_DIRECTORY = /^(?:build|changelog|coverage|dist)(?:\/|$)/iv;
-const GENERATED_ANYWHERE = /(?:^|\/)(?:changelog(?:\.md)?$|node_modules(?:\/|$))/iv;
+const OUTPUT_DIRECTORY = /^(?:build|changelog|coverage|dist)(?:\/|$)/iv;
+const NEVER_SOURCE = /(?:^|\/)(?:changelog(?:\.md)?$|node_modules(?:\/|$))/iv;
 /**
-* Generated output lives at the top of a package, so `packages/build` and
-* `src/dist` remain source. Lockfiles record resolved versions, not declared
-* dependency ranges.
+* Changelogs are this tool's own output, installed dependencies are another
+* project's source, and lockfiles record resolved versions, not declared
+* dependency ranges. None of them is evidence of a change.
 */
-function ignored(file, packages) {
+function excluded(file) {
+	return LOCKFILE_PATH.test(file) || NEVER_SOURCE.test(file);
+}
+/**
+* Recognize directories at the top of a package that usually hold generated
+* output, so `packages/build` and `src/dist` remain source. Supplied commits
+* leave them out, but they still count as changes to research: only the agent
+* can tell a build artifact from a project whose source lives in `coverage`.
+*/
+function likelyGenerated(file, packages) {
 	const owner = packages.findLast(({ directory }) => file.startsWith(`${directory}/`));
 	const relative = owner === void 0 ? file : file.slice(owner.directory.length + 1);
-	return LOCKFILE_PATH.test(file) || GENERATED_ANYWHERE.test(file) || GENERATED_DIRECTORY.test(relative);
+	return OUTPUT_DIRECTORY.test(relative);
 }
-async function scopes(repository, pkg, ref) {
-	if (pkg.directory === ".") return ["."];
+/**
+* A package's directory and, transitively, those of the workspace packages it
+* depends on at a ref.
+*/
+async function packageScope(repository, pkg, ref) {
 	const directories = /* @__PURE__ */ new Set([pkg.directory]);
 	const visit = async (current) => {
 		const manifest = await manifestAt(repository.root, current.directory, ref);
@@ -1399,10 +1632,13 @@ async function commitsInRange(root, range, paths) {
 	}
 	return commits.values().toArray();
 }
-/** Collect source changes, excluding generated notes and release-only commits. */
+/**
+* Collect a release's starting evidence, or nothing when its range holds only
+* changelogs, lockfiles, and version bookkeeping.
+*/
 async function collectEvidence(repository, pkg, release, excludeDirectories = []) {
 	const { packages, root } = repository;
-	const paths = [...(await scopes(repository, pkg, release.ref)).map((directory) => `:(literal)${directory}`), ...excludeDirectories.map((directory) => `:(exclude,literal)${directory}`)];
+	const paths = [...(pkg.directory === "." ? ["."] : await packageScope(repository, pkg, release.ref)).map((directory) => `:(literal)${directory}`), ...excludeDirectories.map((directory) => `:(exclude,literal)${directory}`)];
 	const range = release.previousRef === void 0 ? release.ref : `${release.previousRef}..${release.ref}`;
 	const from = release.previousRef ?? await git(root, [
 		"hash-object",
@@ -1421,20 +1657,25 @@ async function collectEvidence(repository, pkg, release, excludeDirectories = []
 		release.ref,
 		"--",
 		...paths
-	])).split("\0").filter((file) => file !== "" && !ignored(file, packages));
+	])).split("\0").filter((file) => file !== "" && !excluded(file));
 	const rangeBlobs = await readBlobs(root, manifestObjects(candidates, from, release.ref));
 	const changed = new Set(candidates.filter((file) => !isManifest(file) || !isVersionOnlyEdit(rangeBlobs.get(`${from}:${file}`), rangeBlobs.get(`${release.ref}:${file}`))));
 	if (changed.size === 0) return [];
 	const sourceCommits = (await commitsInRange(root, range, paths)).map((item) => ({
 		...item,
-		files: item.files.filter((file) => !ignored(file, packages))
+		files: item.files.filter((file) => !excluded(file) && !likelyGenerated(file, packages))
 	}));
 	const commitBlobs = await readBlobs(root, sourceCommits.flatMap(({ files, id }) => manifestObjects(files, `${id}^`, id)));
-	const evidence = sourceCommits.filter(({ files, id }) => files.some((file) => changed.has(file)) && hasSourceChanges(files, id, commitBlobs)).map(({ files, id, message }) => ({
+	const evidence = [{
+		id: `range:${from}..${release.ref}`,
+		kind: "range",
+		text: `Research the complete Git range ${range} using git log, git diff, git show, and git ls-tree. The supplied commits are a starting point, not a complete description of changes. Follow the scope and exclusions in repository.`
+	}];
+	for (const { files, id, message } of sourceCommits) if (files.some((file) => changed.has(file)) && hasSourceChanges(files, id, commitBlobs)) evidence.push({
 		id,
 		kind: "commit",
 		text: `${message}\nFiles: ${files.join(", ")}`
-	}));
+	});
 	if (release.pending === true) {
 		const file = path.posix.join(pkg.directory, "package.json");
 		const diff = await git(root, [
@@ -1451,11 +1692,6 @@ async function collectEvidence(repository, pkg, release, excludeDirectories = []
 			text: diff
 		});
 	}
-	if (evidence.length > 0) evidence.unshift({
-		id: `range:${from}..${release.ref}`,
-		kind: "range",
-		text: `Research the complete Git range ${range} using git log, git diff, git show, and git ls-tree. The supplied commits are a starting point, not a complete description of changes. Follow the scope and exclusions in repository.`
-	});
 	return evidence;
 }
 function githubUnavailable(error) {
@@ -1592,7 +1828,7 @@ function releaseBatches(requests, limit) {
 	for (const release of requests) {
 		const minimum = {
 			...release,
-			evidence: release.evidence.filter((item) => item.kind === "range")
+			evidence: release.evidence.filter((item) => required(item))
 		};
 		const length = JSON.stringify(minimum).length + 1;
 		if (size + length > limit && batch.length > 0) {
@@ -1608,7 +1844,7 @@ function releaseBatches(requests, limit) {
 		const allowance = Math.max(0, Math.floor((limit - JSON.stringify(items).length) / items.length));
 		const seeded = items.map((item) => ({
 			...item,
-			evidence: [...item.evidence, ...researchEvidence(full.get(item.id).filter((entry) => entry.kind !== "range"), allowance + 2)]
+			evidence: [...item.evidence, ...researchEvidence(full.get(item.id).filter((entry) => !required(entry)), allowance + 2)]
 		}));
 		let remaining = limit - JSON.stringify(seeded).length;
 		for (const item of seeded) {
@@ -1621,6 +1857,10 @@ function releaseBatches(requests, limit) {
 		return seeded;
 	});
 }
+/** Keep what a request cannot do without: its range, and a draft it may cite. */
+function required(item) {
+	return item.kind === "range" || item.kind === "draft";
+}
 /** Bound the starting context; adapters can read the complete range themselves. */
 function researchEvidence(evidence, limit) {
 	const seed = [];
@@ -1635,19 +1875,32 @@ function researchEvidence(evidence, limit) {
 }
 
 // src/lib/jobs.ts
+/** Lets a revised entry cite the draft it came from. */
+const draftEvidence = {
+	id: "draft",
+	kind: "draft",
+	text: "The existing entries, which describe this release up to repository.from. Cite this ID for entries carried over or rewritten from them."
+};
+/** Check whether a package's changelog is a monorepo's root summary. */
+function summarizesPackages(context, pkg) {
+	return pkg.directory === "." && context.repository.packages.length > 0 && context.options.rootChangelog === "summary";
+}
 /**
 * Prepare one release without launching a model, so repository research can be
 * shared.
 */
-async function prepareRelease(context, pkg, release, existingEntries, mode, from, onlyRepositoryFiles = false) {
+async function prepareRelease(context, pkg, release, details) {
 	const { options, repository } = context;
+	const { existingEntries = "", from, mode, onlyRepositoryFiles = false, styleReference } = details;
 	options.signal?.throwIfAborted();
-	const excludeDirectories = onlyRepositoryFiles ? repository.packages.map((item) => item.directory) : [];
+	const excludeDirectories = await excludedPackages(context, pkg, release.ref, onlyRepositoryFiles);
+	const evidence = await collectEvidence(repository, pkg, from === void 0 ? release : {
+		...release,
+		previousRef: from
+	}, excludeDirectories);
+	if (mode === "revise" && evidence.length > 0) evidence.splice(1, 0, draftEvidence);
 	return {
-		evidence: await collectEvidence(repository, pkg, from === void 0 ? release : {
-			...release,
-			previousRef: from
-		}, excludeDirectories),
+		evidence,
 		existingEntries,
 		id: `${pkg.directory}@${release.version}`,
 		initialRelease: release.previousRef === void 0 && from === void 0,
@@ -1659,10 +1912,25 @@ async function prepareRelease(context, pkg, release, existingEntries, mode, from
 			from: from ?? release.previousRef,
 			to: release.ref
 		},
-		scope: pkg.directory === "." && repository.packages.length > 0 ? "repository" : "package",
+		scope: summarizesPackages(context, pkg) ? "repository" : "package",
+		styleReference,
 		version: release.version
 	};
 }
+/**
+* Select the package directories a release leaves out: every package when
+* describing repository files alone, skipped packages in a whole-repository
+* summary, or, when the root is a package itself, those it does not depend on.
+*/
+async function excludedPackages(context, pkg, ref, onlyRepositoryFiles) {
+	const { options, repository } = context;
+	const directories = repository.packages.map((item) => item.directory);
+	if (onlyRepositoryFiles || directories.length === 0) return directories;
+	if (pkg.directory !== ".") return [];
+	if (options.rootChangelog === "summary") return repository.packages.filter((item) => item.skipped === true).map((item) => item.directory);
+	const scope = new Set(await packageScope(repository, pkg, ref));
+	return directories.filter((directory) => !scope.has(directory));
+}
 function cacheKey(context, release) {
 	const { effort, maxInputChars, model } = context.options;
 	return JSON.stringify({
@@ -1711,9 +1979,11 @@ function progressMessage(pending, sessions) {
 }
 /**
 * Run one agent session. A long session is worth saving, so invalid output gets
-* one correction request before the run fails.
+* one correction request before the run fails. Citations are checked against
+* the releases as they were before their evidence was trimmed to fit, since an
+* agent researching a range can cite what trimming left out.
 */
-async function runSession(context, releases) {
+async function runSession(context, releases, untrimmed) {
 	const { agent, options, repository } = context;
 	const request = {
 		releases,
@@ -1726,24 +1996,24 @@ async function runSession(context, releases) {
 		}
 	};
 	log.debug(`Starting a ${agent.name} session for ${releases.map(({ id }) => id).join(", ")} with model ${options.model ?? "default"}, effort ${options.effort}, and a ${options.timeoutMs} ms timeout.`);
+	const accept = async (value) => verifyCitations(repository.root, validateResponse(value, releases), untrimmed);
 	const started = performance.now();
 	const response = await agent.generate(request);
 	log.debug(`The ${agent.name} session finished in ${Math.round(performance.now() - started)} ms.`);
 	try {
-		return validateResponse(response, releases);
+		return await accept(response);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		log.warn(`Requesting a correction of invalid agent output. ${message}`);
 		options.onProgress?.("Requesting a correction of invalid agent output.");
 		options.signal?.throwIfAborted();
-		const corrected = await agent.generate({
+		return accept(await agent.generate({
 			...request,
 			repair: {
 				error: message,
 				response
 			}
-		});
-		return validateResponse(corrected, releases);
+		}));
 	}
 }
 /**
@@ -1776,7 +2046,7 @@ async function generateReleases(context, requests) {
 	options.onProgress?.(status);
 	for (const releases of batches) {
 		options.signal?.throwIfAborted();
-		const changeSets = await runSession(context, releases);
+		const changeSets = await runSession(context, releases, releases.map(({ id }) => unabridged.get(id)));
 		for (const { changes, id } of changeSets) {
 			results.set(id, changes);
 			await saveChanges(context, unabridged.get(id), changes);
@@ -1789,8 +2059,9 @@ async function generateReleases(context, requests) {
 const checkpointSchema = z.object({
 	baseRef: z.string(),
 	contentHash: z.string(),
+	generated: z.boolean(),
 	head: z.string(),
-	instructionVersion: z.literal(instructionVersion),
+	instructionVersion: z.string(),
 	path: z.string()
 });
 const HEADING_PREFIX = /^#{1,3}\s+/v;
@@ -1799,27 +2070,43 @@ const ANCHOR_PUNCTUATION = /[^\p{L}\p{N}_\s\-]/gv;
 const ANCHOR_SPACE = /\s/gv;
 /**
 * Remember what this run covered, so the next one can research only newer
-* commits.
+* commits, and whether the draft it leaves is entirely generated.
 */
-function recordCheckpoint(context, file, content, release) {
+function recordCheckpoint(context, file, content, release, generated) {
 	if (release === void 0 || !context.options.cache) return;
 	context.plan.checkpoints.push({
 		baseRef: release.previousRef ?? "initial",
 		contentHash: changelogHash(content),
+		generated,
 		head: context.repository.head,
 		instructionVersion,
 		path: file
 	});
 }
 /**
-* Find the commit a changelog already covers, when its checkpoint is still
-* valid.
+* Read what the last run recorded about a changelog, when the file still reads
+* as that run left it.
 */
-async function incrementalBase(context, file, content, release) {
+async function readCheckpoint(context, file, content) {
 	if (content === void 0 || !context.options.cache) return;
 	const result = checkpointSchema.safeParse(await readCache(path.join(context.repository.gitDirectory, "chagent", "checkpoints"), file));
-	if (!result.success || result.data.contentHash !== changelogHash(content) || result.data.baseRef !== (release.previousRef ?? "initial")) return;
-	return await isAncestor(context.repository.root, result.data.head, release.ref) ? result.data.head : void 0;
+	return result.success && result.data.contentHash === changelogHash(content) ? result.data : void 0;
+}
+/**
+* Find the commit a release's entries already cover, when the checkpoint
+* describes the same release.
+*/
+async function incrementalBase(context, checkpoint, release) {
+	if (checkpoint?.instructionVersion !== instructionVersion || checkpoint.baseRef !== (release.previousRef ?? "initial")) return;
+	return await isAncestor(context.repository.root, checkpoint.head, release.ref) ? checkpoint.head : void 0;
+}
+/**
+* Decide whether the draft a run leaves is entirely generated: one that was
+* before stays so, and a draft written from nothing or revised becomes so.
+*/
+function leavesGeneratedDraft(entries, previously) {
+	const draft = entries.find((entry) => entry.release.version === "Unreleased");
+	return previously || draft !== void 0 && (draft.existingBody === void 0 || draft.revise === true);
 }
 /** Select the releases newer than anything the changelog already records. */
 function missingReleases(releases, content = "") {
@@ -1836,8 +2123,28 @@ function missingReleases(releases, content = "") {
 function releaseContext(options, pkg) {
 	return pkg.directory === options.releaseDirectory ? options.release : void 0;
 }
-/** Resolve a package's releases and prepare requests for those it still needs. */
-async function preparePackage(context, pkg, aggregateHistory = false, recordedAtRoot) {
+/** Prepare the request for a release the changelog still needs. */
+async function prepareWork(context, pkg, release, details) {
+	const { checkpoint, existingBody, mode } = details;
+	const from = existingBody === void 0 ? void 0 : await incrementalBase(context, checkpoint, release);
+	const revise = from !== void 0 && checkpoint?.generated === true;
+	return {
+		existingBody,
+		release,
+		request: await prepareRelease(context, pkg, release, {
+			existingEntries: existingBody !== void 0 && summarizesPackages(context, pkg) ? withoutPackageLinks(existingBody) : existingBody,
+			from,
+			mode: revise ? "revise" : mode,
+			styleReference: details.styleReference
+		})
+	};
+}
+/**
+* Resolve a package's releases and prepare requests for those its changelog
+* still needs. Summaries cover those releases alone, or with `allSummaries`,
+* every release, so that a root changelog can link to any of them.
+*/
+async function preparePackage(context, pkg, allSummaries = false) {
 	const { repository } = context;
 	const file = await findChangelog(path.join(repository.root, pkg.directory));
 	const content = context.options.rebuild ? void 0 : file.content;
@@ -1845,15 +2152,17 @@ async function preparePackage(context, pkg, aggregateHistory = false, recordedAt
 	const releases = await resolveReleases(repository, pkg, context.options, releaseContext(context.options, pkg));
 	const missing = missingReleases(releases, content);
 	log.debug(`${pkg.name}: ${releases.length} releases, missing [${missing.map((release) => release.version).join(", ")}], changelog ${file.path}.`);
-	const draft = parseChangelog(content ?? "").sections.find((section) => section.version === "Unreleased");
+	const parsed = parseChangelog(content ?? "");
+	const draft = parsed.sections.find((section) => section.version === "Unreleased");
+	const checkpoint = draft === void 0 ? void 0 : await readCheckpoint(context, file.path, content);
 	const newest = releases.findLast((release) => release.version !== "Unreleased");
 	const draftPromoted = draft !== void 0 && newest !== void 0 && missing.includes(newest);
 	const work = [];
 	const summaries = [];
 	for (const release of releases) {
 		const shouldWrite = missing.includes(release);
-		if (!shouldWrite && !aggregateHistory) continue;
-		const summary = {
+		if (!shouldWrite && !allSummaries) continue;
+		summaries.push({
 			changelogPath: file.path,
 			changes: [],
 			date: release.date,
@@ -1862,41 +2171,49 @@ async function preparePackage(context, pkg, aggregateHistory = false, recordedAt
 			ref: release.ref,
 			tag: release.tag,
 			version: release.version
-		};
-		summaries.push(summary);
-		if (!shouldWrite && recordedAtRoot?.(summary) === true) continue;
-		const existingBody = (draftPromoted ? release === newest : release.version === "Unreleased") ? draft?.body : void 0;
-		const from = existingBody === void 0 ? void 0 : await incrementalBase(context, file.path, content, release);
-		const request = await prepareRelease(context, pkg, release, existingBody ?? "", mode, from);
-		work.push({
-			existingBody,
-			release,
-			request,
-			shouldWrite
 		});
+		if (!shouldWrite) continue;
+		const ownsDraft = draftPromoted ? release === newest : release.version === "Unreleased";
+		work.push(await prepareWork(context, pkg, release, {
+			checkpoint,
+			existingBody: ownsDraft ? draft?.body : void 0,
+			mode,
+			styleReference: styleReference(parsed)
+		}));
 	}
+	const exception = await hasNodeException(repository, pkg, releases);
 	return {
 		content,
-		exception: await hasNodeException(repository, pkg, releases),
+		draftGenerated: checkpoint?.generated === true,
+		exception,
 		file,
+		pkg,
 		releases,
 		summaries,
 		work
 	};
 }
-/** Write a package's edit into the plan and complete its summaries. */
-function renderPackage(context, prepared, results) {
+/**
+* Write a package's edit into the plan and complete its summaries. A root
+* summary passes `linksFor` to end each section it writes with links to the
+* package releases that section covers.
+*/
+function renderPackage(context, prepared, results, linksFor) {
 	const { plan, repository } = context;
 	const { content, exception, file, releases, summaries, work } = prepared;
 	const entries = [];
 	const changesByVersion = /* @__PURE__ */ new Map();
-	for (const { existingBody, release, request, shouldWrite } of work) {
+	for (const { existingBody, release, request } of work) {
 		const changes = results.get(request.id) ?? [];
+		const links = linksFor?.(release);
+		const revise = request.mode === "revise" && results.has(request.id);
 		changesByVersion.set(release.version, changes);
-		if (shouldWrite && (release.version !== "Unreleased" || changes.length > 0)) entries.push({
+		if (revise || release.version !== "Unreleased" || changes.length > 0 || links !== void 0 && packageLinksDiffer(existingBody, links)) entries.push({
 			changes,
 			existingBody,
-			release
+			links,
+			release,
+			revise
 		});
 	}
 	const after = updateMarkdown(content, entries, exception, repository.github);
@@ -1905,7 +2222,7 @@ function renderPackage(context, prepared, results) {
 		before: file.content,
 		path: file.path
 	});
-	recordCheckpoint(context, file.path, after, releases.at(-1));
+	recordCheckpoint(context, file.path, after, releases.at(-1), leavesGeneratedDraft(entries, prepared.draftGenerated));
 	const { sections } = parseChangelog(after);
 	return summaries.map((summary) => ({
 		...summary,
@@ -1934,74 +2251,40 @@ function missingPackageSummaries(summaries, content = "") {
 }
 
 // src/lib/workspace.ts
+/** Link to a package's release section, when its changelog has one. */
 function packageLink(repository, summary) {
-	const relative = path.relative(repository.root, summary.changelogPath).split(path.sep).join("/");
-	const anchor = summary.anchor ?? (summary.version === "Unreleased" ? "unreleased" : `${summary.version.replaceAll(".", "")}${summary.date === void 0 ? "" : "---" + summary.date}`);
-	return repository.github === void 0 ? `${relative}#${anchor}` : `https://github.com/${repository.github}/blob/HEAD/${relative}#${anchor}`;
-}
-function aggregateChanges(repository, summaries) {
-	const changes = [];
-	for (const summary of summaries) {
-		if (summary.version === "Unreleased" && summary.changes.length === 0) continue;
-		const link = `[${summary.packageName} ${summary.version}](${packageLink(repository, summary)})`;
-		const highlights = summary.changes.slice(0, 3);
-		if (highlights.length === 0) changes.push({
-			breaking: false,
-			category: "Maintenance",
-			description: `${link}: See the package changelog.`,
-			sources: []
-		});
-		else for (const change of highlights) changes.push({
-			...change,
-			description: `${link}: ${change.description}`
-		});
-	}
-	return changes;
-}
-function promotePackageDraft(content, summary, repository) {
-	const changes = [];
-	const draft = parseChangelog(content ?? "").sections.find((section) => section.version === "Unreleased");
-	if (content === void 0 || draft === void 0) return {
-		changes,
-		content
-	};
-	const source = `[${summary.packageName} Unreleased](`;
-	const target = `[${summary.packageName} ${summary.version}](${packageLink(repository, summary)})`;
-	const remaining = [];
-	let category = "Changed";
-	for (const line of draft.body.split(LINE_BOUNDARY)) {
-		category = categories.find((item) => line.trimEnd() === `### ${item}`) ?? category;
-		const breaking = line.startsWith("- **Breaking:** ");
-		const prefix = breaking ? "- **Breaking:** " : "- ";
-		const end = line.indexOf(")", prefix.length + source.length);
-		if (end === -1 || !line.startsWith(prefix + source)) {
-			remaining.push(line);
-			continue;
-		}
-		changes.push({
-			breaking,
-			category,
-			description: target + line.slice(end + 1).trimEnd(),
-			sources: []
-		});
-	}
-	if (changes.length === 0) return {
-		changes,
-		content
-	};
-	const replacement = remaining.some((line) => line.trim() !== "" && categories.every((item) => line.trimEnd() !== `### ${item}`)) ? draft.heading + remaining.join("") : "";
-	return {
-		changes,
-		content: content.slice(0, draft.start) + replacement + content.slice(draft.end)
-	};
-}
-async function prepareIndependent(context, summaries) {
+	if (summary.anchor === void 0) return [];
+	const target = `${path.relative(repository.root, summary.changelogPath).split(path.sep).join("/")}#${summary.anchor}`;
+	return [{
+		label: `${summary.packageName} ${summary.version}`,
+		url: repository.github === void 0 ? target : `https://github.com/${repository.github}/blob/HEAD/${target}`
+	}];
+}
+/** Name the root's summary of a package release. */
+function summaryId(summary) {
+	return `.@${summary.packageName}@${summary.version}`;
+}
+async function prepareIndependent(context, packages) {
 	const { repository } = context;
 	const file = await findChangelog(repository.root);
 	const content = context.options.rebuild ? void 0 : file.content;
-	let remaining = content;
-	for (const summary of missingPackageSummaries(summaries, content)) remaining = promotePackageDraft(remaining, summary, repository).content;
-	const releaseRefs = new Set(summaries.filter((summary) => summary.version !== "Unreleased").map((summary) => summary.ref));
+	const parsed = parseChangelog(content ?? "");
+	const details = {
+		mode: content === void 0 ? "initialize" : "update",
+		styleReference: styleReference(parsed)
+	};
+	const releases = [];
+	for (const item of packages) for (const summary of missingPackageSummaries(item.summaries, content)) {
+		const release = item.releases.find((candidate) => candidate.version === summary.version);
+		const request = await prepareRelease(context, item.pkg, release, details);
+		releases.push({
+			...request,
+			evidence: request.evidence.filter((evidence) => evidence.kind === "range"),
+			id: summaryId(summary),
+			scope: "repository"
+		});
+	}
+	const releaseRefs = new Set(packages.flatMap((item) => item.summaries).filter((summary) => summary.version !== "Unreleased").map((summary) => summary.ref));
 	const release = {
 		previousRef: (await git(repository.root, [
 			"rev-list",
@@ -2011,44 +2294,54 @@ async function prepareIndependent(context, summaries) {
 		ref: repository.head,
 		version: "Unreleased"
 	};
-	const draft = parseChangelog(remaining ?? "").sections.find((section) => section.version === "Unreleased")?.body;
-	const from = await incrementalBase(context, file.path, remaining, release);
+	const draft = parsed.sections.find((section) => section.version === "Unreleased")?.body;
+	const checkpoint = await readCheckpoint(context, file.path, content);
+	const from = await incrementalBase(context, checkpoint, release);
+	const draftGenerated = checkpoint?.generated === true;
 	return {
 		content,
+		draft,
+		draftGenerated,
 		file,
-		release,
-		request: await prepareRelease(context, repository.rootPackage, release, draft ?? "", content === void 0 ? "initialize" : "update", from, true)
+		releases,
+		unreleased: {
+			release,
+			request: await prepareRelease(context, repository.rootPackage, release, {
+				...details,
+				existingEntries: draft === void 0 ? void 0 : withoutPackageLinks(draft),
+				from,
+				mode: draft !== void 0 && from !== void 0 && draftGenerated ? "revise" : details.mode,
+				onlyRepositoryFiles: true
+			})
+		}
 	};
 }
-function aggregateIndependent(context, prepared, results, summaries, exception) {
+/**
+* Write a section for each package release the root does not record yet, and
+* keep the draft's links to packages with unreleased changes current.
+*/
+function renderIndependent(context, prepared, results, summaries, exception) {
 	const { plan, repository } = context;
-	const { file } = prepared;
-	let { content } = prepared;
-	const entries = [];
-	for (const summary of missingPackageSummaries(summaries, content)) {
-		const label = `${summary.packageName}@${summary.version}`;
-		const promoted = promotePackageDraft(content, summary, repository);
-		content = promoted.content;
-		entries.push({
-			changes: [...promoted.changes, ...aggregateChanges(repository, [summary])],
-			release: {
-				date: summary.date,
-				ref: summary.ref,
-				tag: summary.tag,
-				version: label
-			}
-		});
-	}
-	const unreleased = aggregateChanges(repository, summaries.filter((summary) => summary.version === "Unreleased"));
-	const draft = parseChangelog(content ?? "").sections.find((section) => section.version === "Unreleased")?.body;
-	unreleased.push(...results.get(prepared.request.id) ?? []);
-	if (unreleased.length > 0) entries.push({
-		changes: unreleased,
-		existingBody: draft,
+	const { content, draft, file, unreleased } = prepared;
+	const entries = Array.from(missingPackageSummaries(summaries, content), (summary) => ({
+		changes: results.get(summaryId(summary)) ?? [],
+		links: packageLink(repository, summary),
 		release: {
-			ref: repository.head,
-			version: "Unreleased"
+			date: summary.date,
+			ref: summary.ref,
+			tag: summary.tag,
+			version: `${summary.packageName}@${summary.version}`
 		}
+	}));
+	const changes = results.get(unreleased.request.id) ?? [];
+	const links = summaries.filter((summary) => summary.version === "Unreleased").flatMap((summary) => packageLink(repository, summary));
+	const revise = unreleased.request.mode === "revise" && results.has(unreleased.request.id);
+	if (revise || changes.length > 0 || packageLinksDiffer(draft, links)) entries.push({
+		changes,
+		existingBody: draft,
+		links,
+		release: unreleased.release,
+		revise
 	});
 	const after = updateMarkdown(content, entries, exception, repository.github);
 	if (after !== file.content) plan.files.push({
@@ -2056,7 +2349,7 @@ function aggregateIndependent(context, prepared, results, summaries, exception)
 		before: file.content,
 		path: file.path
 	});
-	recordCheckpoint(context, file.path, after, prepared.release);
+	recordCheckpoint(context, file.path, after, unreleased.release, leavesGeneratedDraft(entries, prepared.draftGenerated));
 }
 /**
 * Find package releases whose own section records no notable changes, so a
@@ -2070,18 +2363,6 @@ function quietReleases(plan, packages) {
 	}
 	return quiet;
 }
-function aggregateShared(context, prepared, results, exception, quiet) {
-	const { plan, repository } = context;
-	renderPackage(context, prepared, results);
-	const rootEdit = plan.files.find((file) => path.dirname(file.path) === repository.root);
-	if (rootEdit === void 0) return;
-	const additions = prepared.summaries.map((summary) => ({
-		changes: aggregateChanges(repository, plan.releases.filter((item) => item.version === summary.version && !quiet.has(`${item.changelogPath}@${item.version}`))),
-		existingBody: parseChangelog(rootEdit.after).sections.find((section) => section.version === summary.version)?.body,
-		release: prepared.releases.find((item) => item.version === summary.version)
-	}));
-	rootEdit.after = updateMarkdown(prepared.content, additions, exception || prepared.exception, repository.github);
-}
 /** Generate package changelogs and the root changelog that summarizes them. */
 async function generateWorkspace(context) {
 	const { options, plan, repository } = context;
@@ -2089,21 +2370,24 @@ async function generateWorkspace(context) {
 	const shared = rootReleases.some((release) => release.version !== "Unreleased");
 	const rootFile = await findChangelog(repository.root);
 	const rootContent = options.rebuild ? void 0 : rootFile.content;
-	const rootMissing = shared ? new Set(missingReleases(rootReleases, rootContent).map((release) => release.version)) : void 0;
-	const needsPackageHistory = rootMissing === void 0 || rootMissing.values().some((version) => version !== "Unreleased");
-	const recordedAtRoot = (summary) => rootMissing === void 0 ? rootContent !== void 0 && missingPackageSummaries([summary], rootContent).length === 0 : !rootMissing.has(summary.version);
+	const linksHistory = !shared || missingReleases(rootReleases, rootContent).some((release) => release.version !== "Unreleased");
 	const packages = [];
-	for (const pkg of repository.packages) packages.push(await preparePackage(context, pkg, needsPackageHistory, recordedAtRoot));
+	for (const pkg of describedPackages(repository)) packages.push(await preparePackage(context, pkg, linksHistory));
 	const root = shared ? await preparePackage(context, repository.rootPackage) : void 0;
-	const independent = shared ? void 0 : await prepareIndependent(context, packages.flatMap((pkg) => pkg.summaries));
+	const independent = shared ? void 0 : await prepareIndependent(context, packages);
 	const requests = [...packages, ...root === void 0 ? [] : [root]].flatMap((pkg) => pkg.work.map((item) => item.request));
-	if (independent !== void 0) requests.push(independent.request);
+	if (independent !== void 0) requests.push(...independent.releases, independent.unreleased.request);
 	const results = await generateReleases(context, requests);
 	const summaries = packages.flatMap((pkg) => renderPackage(context, pkg, results));
 	plan.releases.push(...summaries);
 	const exception = packages.some((pkg) => pkg.exception);
-	if (root !== void 0) aggregateShared(context, root, results, exception, quietReleases(plan, packages));
-	else if (independent !== void 0) aggregateIndependent(context, independent, results, summaries, exception);
+	if (root !== void 0) {
+		const quiet = quietReleases(plan, packages);
+		renderPackage(context, {
+			...root,
+			exception: exception || root.exception
+		}, results, (release) => summaries.filter((summary) => summary.version === release.version && summary.ref === release.ref && !quiet.has(`${summary.changelogPath}@${summary.version}`)).flatMap((summary) => packageLink(repository, summary)));
+	} else if (independent !== void 0) renderIndependent(context, independent, results, summaries, exception);
 }
 
 // src/lib/generate.ts
@@ -2127,6 +2411,7 @@ async function generateChangelog(options = {}) {
 	log.debug(`Resolved options: ${JSON.stringify(config)}`);
 	const repository = await inspectRepository(root, config);
 	log.debug(`Repository ${root} at ${repository.head}: ${repository.tags.length} reachable tags, ${repository.packages.length} workspace packages.`);
+	if (config.rootChangelog === "none" && describedPackages(repository).length === 0) throw new Error("The root changelog is set to \"none\", but no workspace packages remain to describe, so there is no changelog to generate. Choose another root changelog mode, or configure packages that are not skipped.");
 	const agent = typeof selected === "object" ? selected : createAgent(config.agent);
 	const plan = {
 		checkpoints: [],
@@ -2154,14 +2439,20 @@ async function generateChangelog(options = {}) {
 		plan,
 		repository
 	};
-	if (repository.packages.length === 0) {
-		const prepared = await preparePackage(context, repository.rootPackage);
-		const results = await generateReleases(context, prepared.work.map((item) => item.request));
-		plan.releases.push(...renderPackage(context, prepared, results));
-	} else await generateWorkspace(context);
+	if (repository.packages.length > 0 && config.rootChangelog === "summary") await generateWorkspace(context);
+	else await generatePackages(context);
 	if (rebuild) keepEmptyRebuilds(plan);
 	return plan;
 }
+/** Generate each changelog on its own, with no root summary. */
+async function generatePackages(context) {
+	const { options, plan, repository } = context;
+	const packages = options.rootChangelog === "none" ? describedPackages(repository) : [repository.rootPackage, ...describedPackages(repository)];
+	const prepared = [];
+	for (const pkg of packages) prepared.push(await preparePackage(context, pkg));
+	const results = await generateReleases(context, prepared.flatMap((item) => item.work.map((work) => work.request)));
+	for (const item of prepared) plan.releases.push(...renderPackage(context, item, results));
+}
 /** A rebuild that finds nothing to record must not erase an existing changelog. */
 function keepEmptyRebuilds(plan) {
 	plan.files = plan.files.filter((edit) => {
@@ -2322,4 +2613,4 @@ async function reviewChangelog(plan, options = {}) {
 	}
 }
 
-export { version as C, maxTimeoutMinutes as S, isAncestor as _, defineConfig as a, defaultModels as b, createAgent as c, LOCKFILE_PATH as d, inspectRepository as f, git as g, manifestAt as h, generateChangelog as i, agentNames as l, localDate as m, previewChangelog as n, loadConfig as o, isVersionOnlyChange as p, reviewChangelog as r, writeChangelog as s, assertReviewTerminal as t, efforts as u, runCommand as v, defaults as x, setLogger as y };
+export { defaultModels as C, version as E, setLogger as S, maxTimeoutMinutes as T, manifestAt as _, writeChangelog as a, isAncestor as b, resolveConfig as c, efforts as d, rootChangelogs as f, localDate as g, isVersionOnlyChange as h, generateChangelog as i, createAgent as l, inspectRepository as m, previewChangelog as n, defineConfig as o, LOCKFILE_PATH as p, reviewChangelog as r, loadConfig as s, assertReviewTerminal as t, agentNames as u, tagVersion as v, defaults as w, runCommand as x, git as y };