@kitschpatrol/chagent 0.4.0 → 0.6.0

package/dist/{review-DftIAoEl.js → review-cNqsjqhu.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.4.0";
+var version = "0.6.0";
 var engines = { "node": "^24.16.0 || >=26.3.0" };
 
 // src/lib/defaults.ts
@@ -237,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(),
@@ -393,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}",
@@ -403,12 +427,25 @@ 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
 * to it. Follow the previous tag's format, then the first configured pattern,
 * then `v{version}`.
@@ -416,10 +453,26 @@ function tagVersion(tag, pkg, patterns) {
 function pendingTag(pkg, version, previous, patterns) {
 	return (previous?.tag?.includes(previous.version) === true ? previous.tag.replace(previous.version, "{version}") : patterns?.[0] ?? "v{version}").replaceAll("{name}", () => pkg.name).replaceAll("{version}", () => version);
 }
+/**
+* Order releases by Git ancestry, using SemVer only for tags on the same
+* commit.
+*/
+async function sortReleases(repository, releases) {
+	const history = await git(repository.root, [
+		"rev-list",
+		"--topo-order",
+		"--reverse",
+		repository.head
+	]);
+	const positions = new Map(history.split("\n").map((ref, index) => [ref, index]));
+	return releases.toSorted((a, b) => {
+		const difference = (positions.get(a.ref) ?? -1) - (positions.get(b.ref) ?? -1);
+		return difference === 0 ? semver.compare(a.version, b.version) : difference;
+	});
+}
 /** Resolve release intervals from reachable tags and locally bumped manifests. */
 async function resolveReleases(repository, pkg, config, context) {
-	const releases = await taggedReleases(repository, pkg, config);
-	releases.sort((a, b) => semver.compare(a.version, b.version));
+	const releases = await sortReleases(repository, await taggedReleases(repository, pkg, config));
 	for (let index = 1; index < releases.length; index++) {
 		const current = releases[index];
 		const previous = await precedingRelease(repository.root, releases.slice(0, index), current.ref);
@@ -428,7 +481,7 @@ async function resolveReleases(repository, pkg, config, context) {
 	}
 	const latest = releases.at(-1);
 	const currentVersion = pkg.version ?? (pkg.directory === "." ? context?.version : void 0);
-	if (await isPendingRelease(repository, pkg, latest, context) && currentVersion !== void 0) releases.push({
+	if (await isPendingRelease(repository, pkg, releases, context) && currentVersion !== void 0) releases.push({
 		date: context?.date ?? localDate(),
 		pending: true,
 		previousRef: latest?.ref,
@@ -540,25 +593,31 @@ function describedPackages(repository) {
 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;
@@ -574,13 +633,13 @@ async function taggedReleases(repository, pkg, config) {
 async function precedingRelease(root, candidates, ref) {
 	for (const candidate of candidates.toReversed()) if (await isAncestor(root, candidate.ref, ref)) return candidate;
 }
-async function isPendingRelease(repository, pkg, latest, context) {
+async function isPendingRelease(repository, pkg, releases, context) {
 	const currentVersion = pkg.version ?? (pkg.directory === "." ? context?.version : void 0);
 	const committed = await manifestAt(repository.root, pkg.directory, repository.head);
 	const versionChanged = currentVersion !== void 0 && currentVersion !== committed?.version;
 	const parent = await manifestAt(repository.root, pkg.directory, repository.head + "^");
 	const committedBump = parent?.version !== void 0 && parent.version !== committed?.version;
-	return currentVersion !== void 0 && semver.valid(currentVersion) !== null && (latest === void 0 || semver.gt(currentVersion, latest.version)) && (versionChanged || context !== void 0 || committedBump);
+	return currentVersion !== void 0 && semver.valid(currentVersion) !== null && releases.every((release) => release.version !== semver.valid(currentVersion)) && (versionChanged || context !== void 0 || committedBump && releases.every((release) => release.ref !== repository.head));
 }
 
 // src/lib/cache.ts
@@ -638,13 +697,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,
@@ -673,9 +744,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
@@ -714,25 +792,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);
 
@@ -762,6 +852,7 @@ const rootChangelogs = [
 ];
 
 // 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;
@@ -780,13 +871,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
@@ -794,8 +882,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.
 */
@@ -809,10 +897,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({
@@ -936,6 +1067,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() }) }) });
@@ -1038,9 +1246,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.");
@@ -1075,83 +1285,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(),
-	/**
-	* 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/changelog.ts
 const LINE_BOUNDARY = /(?<=\n)/v;
 const FENCE = /^\s{0,3}(`{3,}|~{3,})/v;
@@ -1163,9 +1296,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.";
@@ -1234,6 +1372,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, "");
 }
@@ -1273,6 +1426,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;
@@ -1282,7 +1475,7 @@ function releaseLink(github, release) {
 	return release.previousTag === void 0 ? `${base}/releases/tag/${encodeURIComponent(release.tag)}` : `${base}/compare/${encodeURIComponent(release.previousTag)}...${encodeURIComponent(release.tag)}`;
 }
 /** Insert new sections and update only the draft and its comparison link. */
-function updateMarkdown(original, entries, nodeException, github) {
+function updateMarkdown(original, entries, nodeException, github, releaseOrder) {
 	const content = original ?? "# 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";
 	const parsed = parseChangelog(content);
 	const { newline } = parsed;
@@ -1291,20 +1484,30 @@ function updateMarkdown(original, entries, nodeException, github) {
 	const definitions = [];
 	let { footer } = parsed;
 	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));
+	const released = parsed.sections.filter((section) => section.version !== "Unreleased").map((section) => ({
+		text: content.slice(section.start, section.end),
+		version: section.version
+	}));
 	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;
 		if (release.version === "Unreleased") draftText = section;
 		else {
-			additions.push(section);
+			additions.push({
+				text: section,
+				version: release.version
+			});
 			if (existingBody !== void 0) draftText = "";
 		}
 		if (link === void 0) continue;
@@ -1316,9 +1519,13 @@ function updateMarkdown(original, entries, nodeException, github) {
 	}
 	if (entries.length === 0 && header === parsed.header) return content;
 	if (draftText === "") footer = footer.replace(UNRELEASED_REFERENCE, "");
-	const generated = sectionSpacing(sectionSpacing(header, newline) + draftText, newline) + additions.toReversed().join("");
-	const preserved = released.join("") + footer;
-	return appendDefinitions(preserved === "" ? generated.trimEnd() + newline : generated + preserved, footer, definitions, newline);
+	const sections = [...additions.toReversed(), ...released];
+	if (releaseOrder !== void 0) {
+		const positions = new Map(releaseOrder.map((version, index) => [version, index]));
+		sections.sort((a, b) => (positions.get(b.version) ?? -1) - (positions.get(a.version) ?? -1));
+	}
+	const result = sectionSpacing(sectionSpacing(header, newline) + draftText, newline) + sections.map((section) => section.text).join("") + footer;
+	return appendDefinitions(footer === "" && released.length === 0 ? result.trimEnd() + newline : result, footer, definitions, newline);
 }
 /** Add link reference definitions after any existing footer. */
 function appendDefinitions(content, footer, definitions, newline) {
@@ -1335,8 +1542,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());
@@ -1352,17 +1566,26 @@ 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;
+/**
+* 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 excluded(file) {
+	return LOCKFILE_PATH.test(file) || NEVER_SOURCE.test(file);
+}
 /**
-* 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.
+* 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 ignored(file, packages) {
+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);
 }
 /**
 * A package's directory and, transitively, those of the workspace packages it
@@ -1435,7 +1658,10 @@ 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 = [...(pkg.directory === "." ? ["."] : await packageScope(repository, pkg, release.ref)).map((directory) => `:(literal)${directory}`), ...excludeDirectories.map((directory) => `:(exclude,literal)${directory}`)];
@@ -1457,20 +1683,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, [
@@ -1487,11 +1718,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) {
@@ -1628,7 +1854,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) {
@@ -1644,7 +1870,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) {
@@ -1657,6 +1883,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 = [];
@@ -1671,19 +1901,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 = 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,
@@ -1695,7 +1938,8 @@ async function prepareRelease(context, pkg, release, existingEntries, mode, from
 			from: from ?? release.previousRef,
 			to: release.ref
 		},
-		scope: pkg.directory === "." && repository.packages.length > 0 && options.rootChangelog === "summary" ? "repository" : "package",
+		scope: summarizesPackages(context, pkg) ? "repository" : "package",
+		styleReference,
 		version: release.version
 	};
 }
@@ -1761,9 +2005,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,
@@ -1776,24 +2022,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);
+		}));
 	}
 }
 /**
@@ -1826,7 +2072,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);
@@ -1839,8 +2085,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;
@@ -1849,45 +2096,80 @@ 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;
 }
-/** Select the releases newer than anything the changelog already records. */
+/**
+* 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 every reachable release the changelog does not already record. */
 function missingReleases(releases, content = "") {
 	const { sections } = parseChangelog(content);
 	const known = new Set(sections.map((section) => section.version));
 	const recorded = sections.filter((section) => section.version !== "Unreleased").map((section) => section.version);
 	const unrecognized = recorded.filter((version) => semver.valid(version) === null);
 	if (unrecognized.length > 0) throw new Error(`The existing changelog has unrecognized release headings (${unrecognized.join(", ")}). Normalize its release headings before updating it.`);
-	const newest = recorded.toSorted(semver.rcompare)[0];
-	if (newest !== void 0 && releases.every((release) => release.version !== newest)) throw new Error(`Cannot locate the Git release boundary for existing changelog version ${newest}. Fetch its tags or configure tagPatterns.`);
-	return releases.filter((release) => release.version === "Unreleased" || !known.has(release.version) && (newest === void 0 || semver.gt(release.version, newest)));
+	for (const version of recorded) if (releases.every((release) => release.version !== version)) throw new Error(`Cannot locate the Git release boundary for existing changelog version ${version}. Fetch its tags or configure tagPatterns.`);
+	return releases.filter((release) => release.version === "Unreleased" || !known.has(release.version));
 }
 /** Apply an explicit release context only to the package being released. */
 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;
@@ -1895,15 +2177,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,
@@ -1912,50 +2196,58 @@ 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);
+	const after = updateMarkdown(content, entries, exception, repository.github, releases.map((release) => release.version));
 	if (after !== file.content) plan.files.push({
 		after,
 		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,
@@ -1973,85 +2265,44 @@ function headingAnchor(heading) {
 function missingPackageSummaries(summaries, content = "") {
 	const parsed = parseChangelog(content);
 	const known = new Set(parsed.sections.map((section) => section.version));
-	return summaries.toSorted((a, b) => (a.date ?? "9999").localeCompare(b.date ?? "9999")).filter((summary) => {
-		if (summary.version === "Unreleased" || known.has(`${summary.packageName}@${summary.version}`)) return false;
-		return parsed.sections.every((section) => {
-			const prefix = summary.packageName + "@";
-			const version = section.version.startsWith(prefix) ? section.version.slice(prefix.length) : "";
-			return semver.valid(version) === null || semver.lt(version, summary.version);
-		});
-	});
+	return summaries.filter((summary) => summary.version !== "Unreleased" && !known.has(`${summary.packageName}@${summary.version}`));
 }
 
 // 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",
@@ -2061,52 +2312,63 @@ 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.
+*/
+async 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 ordered = await sortReleases(repository, summaries.filter((summary) => summary.version !== "Unreleased"));
+	const entries = Array.from(missingPackageSummaries(ordered, 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);
+	const after = updateMarkdown(content, entries, exception, repository.github, ordered.map((summary) => `${summary.packageName}@${summary.version}`));
 	if (after !== file.content) plan.files.push({
 		after,
 		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
@@ -2120,18 +2382,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 && item.ref === summary.ref && !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;
@@ -2139,21 +2389,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 ? missingReleases(rootReleases, rootContent) : void 0;
-	const needsPackageHistory = rootMissing === void 0 || rootMissing.some((release) => release.version !== "Unreleased");
-	const recordedAtRoot = (summary) => rootMissing === void 0 ? rootContent !== void 0 && missingPackageSummaries([summary], rootContent).length === 0 : rootMissing.every((release) => release.version !== summary.version || release.ref !== summary.ref);
+	const linksHistory = !shared || missingReleases(rootReleases, rootContent).some((release) => release.version !== "Unreleased");
 	const packages = [];
-	for (const pkg of describedPackages(repository)) 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) await renderIndependent(context, independent, results, summaries, exception);
 }
 
 // src/lib/generate.ts
@@ -2379,4 +2632,4 @@ async function reviewChangelog(plan, options = {}) {
 	}
 }
 
-export { maxTimeoutMinutes as C, defaults as S, git as _, defineConfig as a, setLogger as b, createAgent as c, rootChangelogs as d, LOCKFILE_PATH as f, manifestAt as g, localDate as h, generateChangelog as i, agentNames as l, isVersionOnlyChange as m, previewChangelog as n, loadConfig as o, inspectRepository as p, reviewChangelog as r, writeChangelog as s, assertReviewTerminal as t, efforts as u, isAncestor as v, version as w, defaultModels as x, runCommand 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 };