@bensandee/tooling 0.58.0 → 0.59.1

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { d as debug, f as debugExec, g as note, h as log, l as createRealExecutor$1, m as redact, p as isEnvVerbose, t as runDockerCheck, u as isExecSyncError } from "./check-B5DFYJ3x.mjs";
+import { _ as log, d as isExecSyncError, f as lintComposeFiles, g as redact, h as isEnvVerbose, m as debugExec, n as runDockerCheck, p as debug, t as deriveProjectName, u as createRealExecutor$1, v as note } from "./project-name-CAVRoqNy.mjs";
 import { defineCommand, runMain } from "citty";
 import * as p from "@clack/prompts";
 import { isCancel, select } from "@clack/prompts";
@@ -10,7 +10,7 @@ import JSON5 from "json5";
 import { parse } from "jsonc-parser";
 import { z } from "zod";
 import { FatalError, TransientError, UnexpectedError } from "@bensandee/common";
-import { isMap, isScalar, parse as parse$1, parseDocument, stringify, visit } from "yaml";
+import { isMap, isScalar, isSeq, parse as parse$1, parseDocument, stringify, visit } from "yaml";
 import picomatch from "picomatch";
 import { tmpdir } from "node:os";
 import { createHmac } from "node:crypto";
@@ -1330,6 +1330,11 @@ function buildWorkflowYaml(options) {
 function actionsExpr(expr) {
 	return `\${{ ${expr} }}`;
 }
+const MAIN_BRANCH_REF = "refs/heads/main";
+/** `if:` condition that gates a step to push events on the default branch. */
+const IS_MAIN_BRANCH = `github.ref == '${MAIN_BRANCH_REF}'`;
+/** Negated form for concurrency `cancel-in-progress` and similar uses. */
+const IS_NOT_MAIN_BRANCH = `github.ref != '${MAIN_BRANCH_REF}'`;
 function hasEnginesNode(ctx) {
 	const raw = ctx.read("package.json");
 	if (!raw) return false;
@@ -1473,7 +1478,7 @@ function hasReleaseAssets(ctx) {
 		return false;
 	}
 }
-const ARCHIVE_DIR$1 = ".tooling-archived";
+const ARCHIVE_DIR$2 = ".tooling-archived";
 async function generateDeployCi(ctx) {
 	const filePath = "deploy-ci";
 	if (!ctx.config.publishDocker || ctx.config.ci === "none") return {
@@ -1486,12 +1491,12 @@ async function generateDeployCi(ctx) {
 	if (ctx.config.releaseStrategy === "simple") {
 		const existing = ctx.read(workflowPath);
 		if (existing !== void 0) {
-			ctx.write(`${ARCHIVE_DIR$1}/${workflowPath}`, existing);
+			ctx.write(`${ARCHIVE_DIR$2}/${workflowPath}`, existing);
 			ctx.remove(workflowPath);
 			return {
 				filePath: workflowPath,
 				action: "archived",
-				description: `Moved to ${ARCHIVE_DIR$1}/${workflowPath} (docker publish runs in release.yml for simple strategy)`
+				description: `Moved to ${ARCHIVE_DIR$2}/${workflowPath} (docker publish runs in release.yml for simple strategy)`
 			};
 		}
 		return {
@@ -1593,7 +1598,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["@types/node"],
 	tsdown: {
 		"@changesets/cli": "2.31.0",
@@ -1609,7 +1614,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["tsdown"],
 	typescript: {
 		"@changesets/cli": "2.31.0",
@@ -1625,7 +1630,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["typescript"],
 	vitest: {
 		"@changesets/cli": "2.31.0",
@@ -1641,7 +1646,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["vitest"]
 };
 /** DevDeps that belong at the root regardless of structure. */
@@ -1660,7 +1665,7 @@ const ROOT_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["knip"],
 	lefthook: {
 		"@changesets/cli": "2.31.0",
@@ -1676,7 +1681,7 @@ const ROOT_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["lefthook"],
 	oxlint: {
 		"@changesets/cli": "2.31.0",
@@ -1692,7 +1697,7 @@ const ROOT_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["oxlint"]
 };
 /**
@@ -1733,7 +1738,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.1.1"
+				"pnpm": "11.1.2"
 			}["release-it"];
 			if (config.structure === "monorepo") deps["@release-it/bumper"] = {
 				"@changesets/cli": "2.31.0",
@@ -1749,7 +1754,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.1.1"
+				"pnpm": "11.1.2"
 			}["@release-it/bumper"];
 			break;
 		case "simple":
@@ -1767,7 +1772,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.1.1"
+				"pnpm": "11.1.2"
 			}["commit-and-tag-version"];
 			break;
 		case "changesets":
@@ -1785,7 +1790,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.1.1"
+				"pnpm": "11.1.2"
 			}["@changesets/cli"];
 			break;
 	}
@@ -1808,8 +1813,8 @@ async function generatePackageJson(ctx) {
 	}
 	const devDeps = { ...ROOT_DEV_DEPS };
 	if (!isMonorepo) Object.assign(devDeps, PER_PACKAGE_DEV_DEPS);
-	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.11.1";
-	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.58.0";
+	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.11.2";
+	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.59.1";
 	if (ctx.config.useEslintPlugin) devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.13.0";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
 		"@changesets/cli": "2.31.0",
@@ -1825,7 +1830,7 @@ async function generatePackageJson(ctx) {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["oxfmt"];
 	if (ctx.config.formatter === "prettier") devDeps["prettier"] = {
 		"@changesets/cli": "2.31.0",
@@ -1841,7 +1846,7 @@ async function generatePackageJson(ctx) {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.1.1"
+		"pnpm": "11.1.2"
 	}["prettier"];
 	addReleaseDeps(devDeps, ctx.config);
 	if (existing) {
@@ -1913,7 +1918,7 @@ async function generatePackageJson(ctx) {
 			"tsdown": "0.22.0",
 			"typescript": "6.0.3",
 			"vitest": "4.1.5",
-			"pnpm": "11.1.1"
+			"pnpm": "11.1.2"
 		}["pnpm"];
 		const desiredPm = pinnedPnpm ? `pnpm@${pinnedPnpm}` : void 0;
 		if (desiredPm) {
@@ -1965,7 +1970,7 @@ async function generatePackageJson(ctx) {
 			"tsdown": "0.22.0",
 			"typescript": "6.0.3",
 			"vitest": "4.1.5",
-			"pnpm": "11.1.1"
+			"pnpm": "11.1.2"
 		}["pnpm"]}`
 	};
 	ctx.write(filePath, JSON.stringify(pkg, null, 2) + "\n");
@@ -3385,7 +3390,7 @@ function hookSecretEnv(secrets) {
 }
 /** Step that runs after release with post-release webhook env wired up. */
 function postReleaseHookStep(opts) {
-	const ifCondition = opts?.condition ?? (opts?.guardMain ? "github.ref == 'refs/heads/main'" : void 0);
+	const ifCondition = opts?.condition ?? (opts?.guardMain ? IS_MAIN_BRANCH : void 0);
 	return { step: {
 		name: "Post-release hook",
 		...ifCondition && { if: ifCondition },
@@ -3566,12 +3571,31 @@ async function generateReleaseCi(ctx) {
 }
 //#endregion
 //#region src/generators/ci.ts
+function coverageHistorySteps() {
+	return [
+		{ step: {
+			name: "Print coverage summary",
+			if: IS_MAIN_BRANCH,
+			run: "pnpm exec bst coverage:summary"
+		} },
+		{ step: {
+			name: "Append record to bst/coverage-metrics branch",
+			if: IS_MAIN_BRANCH,
+			run: "pnpm exec bst coverage:record"
+		} },
+		{ step: {
+			name: "Show recent coverage trend",
+			if: IS_MAIN_BRANCH,
+			run: "pnpm exec bst coverage:status --limit 10"
+		} }
+	];
+}
 /** Build the release step for the check job (changesets strategy). */
 function changesetsReleaseStep(ci, publishesNpm) {
 	if (ci === "github") return { step: {
 		id: "release",
 		uses: "changesets/action@v1",
-		if: "github.ref == 'refs/heads/main'",
+		if: IS_MAIN_BRANCH,
 		with: {
 			publish: "pnpm changeset publish",
 			version: "pnpm changeset version"
@@ -3596,9 +3620,11 @@ function changesetsReleaseStep(ci, publishesNpm) {
 }
 const CI_CONCURRENCY = {
 	group: `ci-${actionsExpr("github.ref")}`,
-	"cancel-in-progress": actionsExpr("github.ref != 'refs/heads/main'")
+	"cancel-in-progress": actionsExpr(IS_NOT_MAIN_BRANCH)
 };
-function checkSteps(nodeVersionYaml, publishesNpm) {
+function checkSteps(nodeVersionYaml, publishesNpm, withCoverage) {
+	const isNodeVersionFile = nodeVersionYaml.startsWith("node-version-file");
+	const checkCommand = withCoverage ? "pnpm ci:check --with-coverage" : "pnpm ci:check";
 	return [
 		{ step: {
 			uses: "actions/checkout@v6",
@@ -3608,7 +3634,7 @@ function checkSteps(nodeVersionYaml, publishesNpm) {
 		{ step: {
 			uses: "actions/setup-node@v6",
 			with: {
-				...nodeVersionYaml.startsWith("node-version-file") ? { "node-version-file": "package.json" } : { "node-version": "24" },
+				...isNodeVersionFile ? { "node-version-file": "package.json" } : { "node-version": "24" },
 				cache: "pnpm",
 				...publishesNpm && { "registry-url": actionsExpr("vars.NPM_REGISTRY_URL || 'https://registry.npmjs.org'") }
 			}
@@ -3616,7 +3642,7 @@ function checkSteps(nodeVersionYaml, publishesNpm) {
 		{ step: { run: "pnpm install --frozen-lockfile" } },
 		{ step: {
 			name: "Run all checks",
-			run: "pnpm ci:check"
+			run: checkCommand
 		} }
 	];
 }
@@ -3637,6 +3663,8 @@ async function generateCi(ctx) {
 	const publishesNpm = ctx.config.publishNpm === true;
 	const hookCommand = getPostReleaseHookCommand(ctx);
 	const hookSecrets = getPostReleaseHookSecrets(ctx);
+	const coverage = resolveCoverageConfigFromContext(ctx, ctx.config.setupVitest);
+	const emitCoverageSteps = coverage.historyEnabled;
 	const hasDocker = isChangesets && hasDockerPackages(ctx);
 	const hasAssets = isChangesets && hasReleaseAssets(ctx);
 	const registryDerivable = hasDocker && hasRepositoryUrl(ctx);
@@ -3649,7 +3677,8 @@ async function generateCi(ctx) {
 		releaseEnv["RELEASE_TOKEN"] = actionsExpr("secrets.RELEASE_TOKEN");
 	}
 	const steps = [
-		...checkSteps(nodeVersionYaml, isChangesets && publishesNpm),
+		...checkSteps(nodeVersionYaml, isChangesets && publishesNpm, coverage.enabled),
+		...emitCoverageSteps ? coverageHistorySteps() : [],
 		...isChangesets ? [changesetsReleaseStep(ctx.config.ci, publishesNpm)] : [],
 		...hasAssets ? [{ step: {
 			name: "Upload Release Assets",
@@ -3679,6 +3708,7 @@ async function generateCi(ctx) {
 			},
 			pull_request: null
 		},
+		...emitCoverageSteps && { permissions: { contents: "write" } },
 		enableEmailNotifications: isForgejo,
 		...isChangesets && { concurrency: CI_CONCURRENCY },
 		jobName: "check",
@@ -3876,6 +3906,7 @@ async function generateRenovate(ctx) {
 //#region src/generators/pnpm-workspace.ts
 const FILE_PATH = "pnpm-workspace.yaml";
 const DEFAULT_MIN_RELEASE_AGE = 1440;
+const BENSANDEE_EXCLUDE_PATTERN = "@bensandee/*";
 const FRESH_MONOREPO = `packages:
   - "packages/*"
 
@@ -3909,9 +3940,11 @@ function isPnpmWorkspaceDisabled(ctx) {
 * Mandated:
 *   - `blockExoticSubdeps: true`
 *   - `minimumReleaseAge`: any non-negative number; seeded to 1440 if missing/invalid.
+*   - `minimumReleaseAgeExclude`: must contain `"@bensandee/*"` so this monorepo's
+*     own packages can be installed immediately after publish. Other entries are
+*     preserved.
 *
 * Not enforced (left alone after creation):
-*   - `minimumReleaseAgeExclude`
 *   - everything else (`packages`, `allowBuilds`, etc.)
 */
 function applyManagedKeys(doc) {
@@ -3925,6 +3958,14 @@ function applyManagedKeys(doc) {
 		doc.set("minimumReleaseAge", DEFAULT_MIN_RELEASE_AGE);
 		changes.push(`set minimumReleaseAge: ${DEFAULT_MIN_RELEASE_AGE}`);
 	}
+	const excludeNode = doc.get("minimumReleaseAgeExclude");
+	if (!isSeq(excludeNode)) {
+		doc.set("minimumReleaseAgeExclude", [BENSANDEE_EXCLUDE_PATTERN]);
+		changes.push(`set minimumReleaseAgeExclude: ["${BENSANDEE_EXCLUDE_PATTERN}"]`);
+	} else if (!excludeNode.items.some((item) => isScalar(item) && item.value === BENSANDEE_EXCLUDE_PATTERN)) {
+		excludeNode.add(BENSANDEE_EXCLUDE_PATTERN);
+		changes.push(`added "${BENSANDEE_EXCLUDE_PATTERN}" to minimumReleaseAgeExclude`);
+	}
 	return changes;
 }
 async function generatePnpmWorkspace(ctx) {
@@ -4020,6 +4061,22 @@ function parseClaudeSettings(raw) {
 		return;
 	}
 }
+/**
+* Instructions previously emitted to `.claude/settings.json#instructions`.
+* Migrated to a managed block in CLAUDE.md (see `claude-md.ts`); on sync we
+* strip any existing entry that matches (by either-direction prefix, mirroring
+* the upgrade-in-place semantics the merge logic used to apply on add).
+*/
+const MIGRATED_INSTRUCTIONS = [
+	"Use pnpm, not npm/yarn/npx. Run binaries with `pnpm exec`.",
+	"No typecasts (as/any). Use zod schemas, type guards, or narrowing instead.",
+	"Fix lint violations instead of suppressing them. Only add disable comments when suppression is genuinely the best option. For no-empty-function: add a `{ /* no-op */ }` comment body instead of a disable comment.",
+	"Prefer extensionless imports; if an extension is required, use .ts over .js.",
+	"The bst-hook manages Bash/file permissions. See .claude/hooks/bst-hook-guide.md for auto-approved, denied, and passthrough commands."
+];
+function isMigratedInstruction(s) {
+	return MIGRATED_INSTRUCTIONS.some((c) => s.startsWith(c) || c.startsWith(s));
+}
 function buildSettings(ctx) {
 	const allow = [];
 	const enabledPlugins = { "code-simplifier@claude-plugins-official": true };
@@ -4039,13 +4096,7 @@ function buildSettings(ctx) {
 				command: `node "$(git rev-parse --show-toplevel)/.claude/hooks/bst-hook.mjs"`
 			}]
 		}] },
-		instructions: [
-			"Use pnpm, not npm/yarn/npx. Run binaries with `pnpm exec`.",
-			"No typecasts (as/any). Use zod schemas, type guards, or narrowing instead.",
-			"Fix lint violations instead of suppressing them. Only add disable comments when suppression is genuinely the best option. For no-empty-function: add a `{ /* no-op */ }` comment body instead of a disable comment.",
-			"Prefer extensionless imports; if an extension is required, use .ts over .js.",
-			"The bst-hook manages Bash/file permissions. See .claude/hooks/bst-hook-guide.md for auto-approved, denied, and passthrough commands."
-		],
+		instructions: [],
 		enabledPlugins,
 		extraKnownMarketplaces
 	};
@@ -4060,11 +4111,12 @@ function removeObsoleteBstHookEntries(matchers, consolidatedMatcher) {
 		return false;
 	});
 }
-/** Remove enabledPlugins/extraKnownMarketplaces/hooks when empty to keep the file clean. */
+/** Remove empty optional fields to keep the file clean. */
 function serializeSettings$1(settings) {
-	const { enabledPlugins, extraKnownMarketplaces, hooks, ...rest } = settings;
+	const { enabledPlugins, extraKnownMarketplaces, hooks, instructions, ...rest } = settings;
 	const out = { ...rest };
 	if (Object.keys(hooks).length > 0) out["hooks"] = hooks;
+	if (instructions.length > 0) out["instructions"] = instructions;
 	if (Object.keys(enabledPlugins).length > 0) out["enabledPlugins"] = enabledPlugins;
 	if (Object.keys(extraKnownMarketplaces).length > 0) out["extraKnownMarketplaces"] = extraKnownMarketplaces;
 	return JSON.stringify(out, null, 2) + "\n";
@@ -4081,15 +4133,9 @@ function writeOrMergeSettings(ctx, filePath, generated) {
 		const { settings, rawJson } = parsed;
 		const missingAllow = generated.permissions.allow.filter((rule) => !settings.permissions.allow.includes(rule));
 		const missingDeny = generated.permissions.deny.filter((rule) => !settings.permissions.deny.includes(rule));
-		const mergedInstructions = [...settings.instructions];
-		let instructionChanges = 0;
-		for (const inst of generated.instructions) {
-			if (mergedInstructions.includes(inst)) continue;
-			const prefixIdx = mergedInstructions.findIndex((e) => inst.startsWith(e) || e.startsWith(inst));
-			if (prefixIdx !== -1) mergedInstructions[prefixIdx] = inst;
-			else mergedInstructions.push(inst);
-			instructionChanges++;
-		}
+		const filteredInstructions = settings.instructions.filter((s) => !isMigratedInstruction(s));
+		const instructionChanges = settings.instructions.length - filteredInstructions.length;
+		const mergedInstructions = filteredInstructions;
 		let hookChanges = 0;
 		const mergedHooks = { ...settings.hooks };
 		for (const [event, generatedMatchers] of Object.entries(generated.hooks)) {
@@ -4130,7 +4176,8 @@ function writeOrMergeSettings(ctx, filePath, generated) {
 			deny: [...settings.permissions.deny, ...missingDeny]
 		};
 		if (Object.keys(mergedHooks).length > 0) rawJson["hooks"] = mergedHooks;
-		rawJson["instructions"] = mergedInstructions;
+		if (mergedInstructions.length > 0) rawJson["instructions"] = mergedInstructions;
+		else delete rawJson["instructions"];
 		const updatedPlugins = { ...settings.enabledPlugins };
 		for (const [key, value] of missingPlugins) updatedPlugins[key] = value;
 		const updatedMarketplaces = { ...settings.extraKnownMarketplaces };
@@ -4284,7 +4331,7 @@ function buildConfig$1(formatter) {
 		""
 	].join("\n");
 }
-const ARCHIVE_DIR = ".tooling-archived";
+const ARCHIVE_DIR$1 = ".tooling-archived";
 /** Common client-side git hooks that husky may have configured. */
 const HUSKY_HOOK_NAMES = [
 	"pre-commit",
@@ -4315,12 +4362,12 @@ function archiveHuskyHooks(ctx, results) {
 		const huskyPath = `.husky/${hook}`;
 		const existing = ctx.read(huskyPath);
 		if (existing !== void 0) {
-			ctx.write(`${ARCHIVE_DIR}/${huskyPath}`, existing);
+			ctx.write(`${ARCHIVE_DIR$1}/${huskyPath}`, existing);
 			ctx.remove(huskyPath);
 			results.push({
 				filePath: huskyPath,
 				action: "archived",
-				description: `Moved to ${ARCHIVE_DIR}/${huskyPath}`
+				description: `Moved to ${ARCHIVE_DIR$1}/${huskyPath}`
 			});
 			found = true;
 		}
@@ -4333,12 +4380,12 @@ function archiveLintStagedConfigs(ctx, results) {
 	for (const lsPath of LINT_STAGED_CONFIG_PATHS) {
 		const existing = ctx.read(lsPath);
 		if (existing !== void 0) {
-			ctx.write(`${ARCHIVE_DIR}/${lsPath}`, existing);
+			ctx.write(`${ARCHIVE_DIR$1}/${lsPath}`, existing);
 			ctx.remove(lsPath);
 			results.push({
 				filePath: lsPath,
 				action: "archived",
-				description: `Moved to ${ARCHIVE_DIR}/${lsPath}`
+				description: `Moved to ${ARCHIVE_DIR$1}/${lsPath}`
 			});
 			found = true;
 		}
@@ -4518,43 +4565,12 @@ async function generateVscodeSettings(ctx) {
 }
 //#endregion
 //#region src/generators/coverage-ci.ts
-function coverageSteps(nodeVersionYaml) {
-	return [
-		{ step: {
-			uses: "actions/checkout@v6",
-			with: { "fetch-depth": 0 }
-		} },
-		{ step: { uses: "pnpm/action-setup@v5" } },
-		{ step: {
-			uses: "actions/setup-node@v6",
-			with: {
-				...nodeVersionYaml.startsWith("node-version-file") ? { "node-version-file": "package.json" } : { "node-version": "24" },
-				cache: "pnpm"
-			}
-		} },
-		{ step: { run: "pnpm install --frozen-lockfile" } },
-		{ step: {
-			name: "Build",
-			run: "pnpm build"
-		} },
-		{ step: {
-			name: "Run tests with coverage",
-			run: "pnpm test:coverage"
-		} },
-		{ step: {
-			name: "Print coverage summary",
-			run: "pnpm exec bst coverage:summary"
-		} },
-		{ step: {
-			name: "Append record to bst/coverage-metrics branch",
-			run: "pnpm exec bst coverage:record"
-		} },
-		{ step: {
-			name: "Show recent coverage trend",
-			run: "pnpm exec bst coverage:status --limit 10"
-		} }
-	];
-}
+const ARCHIVE_DIR = ".tooling-archived";
+/**
+* Cleanup-only generator: coverage steps now run inline in ci.yml (see
+* generateCi). Any legacy coverage.yml left over from a previous version is
+* archived to .tooling-archived/ on the next repo:sync.
+*/
 async function generateCoverageCi(ctx) {
 	const filePath = "coverage-ci";
 	if (ctx.config.ci === "none") return {
@@ -4562,100 +4578,92 @@ async function generateCoverageCi(ctx) {
 		action: "skipped",
 		description: "CI workflow not requested"
 	};
-	const config = resolveCoverageConfigFromContext(ctx, ctx.config.setupVitest);
-	if (!config.enabled || !config.historyEnabled) return {
-		filePath,
-		action: "skipped",
-		description: "Coverage tracking disabled"
-	};
-	const isGitHub = ctx.config.ci === "github";
-	const isForgejo = !isGitHub;
-	const workflowPath = isGitHub ? ".github/workflows/coverage.yml" : ".forgejo/workflows/coverage.yml";
-	const nodeVersionYaml = computeNodeVersionYaml(ctx);
-	const content = buildWorkflowYaml({
-		ci: ctx.config.ci,
-		name: "Coverage",
-		on: { push: {
-			branches: ["main"],
-			"tags-ignore": ["**"]
-		} },
-		permissions: { contents: "write" },
-		enableEmailNotifications: isForgejo,
-		jobName: "coverage",
-		steps: coverageSteps(nodeVersionYaml)
-	});
-	const alreadyExists = ctx.exists(workflowPath);
-	const existing = alreadyExists ? ctx.read(workflowPath) : void 0;
-	if (existing) {
-		if (isToolingIgnored(existing)) return {
-			filePath: workflowPath,
-			action: "skipped",
-			description: "Coverage workflow has ignore comment"
-		};
-		if (normalizeWorkflow(existing) === normalizeWorkflow(content)) return {
+	const workflowPath = ctx.config.ci === "github" ? ".github/workflows/coverage.yml" : ".forgejo/workflows/coverage.yml";
+	const existing = ctx.read(workflowPath);
+	if (existing !== void 0) {
+		ctx.write(`${ARCHIVE_DIR}/${workflowPath}`, existing);
+		ctx.remove(workflowPath);
+		return {
 			filePath: workflowPath,
-			action: "skipped",
-			description: "Coverage workflow already up to date"
+			action: "archived",
+			description: `Moved to ${ARCHIVE_DIR}/${workflowPath} (coverage now runs inline in ci.yml)`
 		};
 	}
-	const withPinnedActions = preservePinnedActions(preserveDevBinaryPath(content, existing), existing);
-	const final = existing ? insertCustomBlocks(withPinnedActions, extractCustomBlocks(existing)) : withPinnedActions;
-	ctx.write(workflowPath, final);
 	return {
-		filePath: workflowPath,
-		action: alreadyExists ? "updated" : "created",
-		description: `Generated ${isGitHub ? "GitHub" : "Forgejo"} Actions coverage workflow`
+		filePath,
+		action: "skipped",
+		description: "Coverage runs inline in ci.yml"
 	};
 }
 //#endregion
 //#region src/generators/claude-md.ts
 const FILE = "CLAUDE.md";
-const START_MARKER = "<!-- @tooling:coverage-rule -->";
-const END_MARKER = "<!-- @tooling:endcoverage-rule -->";
+/**
+* General agent rules previously emitted as the `instructions` array in
+* `.claude/settings.json`. Migrated here so CLAUDE.md is the single source
+* for human-readable agent guidance.
+*
+* Also includes the plan-lifecycle convention so `docs/plan-*.md` files get
+* retired consistently when they ship.
+*/
+const AGENT_RULES_BODY = [
+	"### Agent rules",
+	"",
+	"- Use pnpm, not npm/yarn/npx. Run binaries with `pnpm exec`.",
+	"- No typecasts (`as`/`any`). Use zod schemas, type guards, or narrowing instead.",
+	"- Fix lint violations instead of suppressing them. Only add disable comments when suppression is genuinely the best option. For `no-empty-function`: add a `{ /* no-op */ }` comment body instead of a disable comment.",
+	"- Prefer extensionless imports; if an extension is required, use `.ts` over `.js`.",
+	"- The bst-hook manages Bash/file permissions. See `.claude/hooks/bst-hook-guide.md` for auto-approved, denied, and passthrough commands.",
+	"",
+	"#### Plan lifecycle",
+	"",
+	"When a plan under `docs/` (e.g. `docs/plan-foo.md`) is fully implemented, retire it:",
+	"",
+	"1. Move the file into `docs/completed/`.",
+	"2. Rename so the `plan-` prefix becomes `completed-` — `docs/plan-foo.md` → `docs/completed/completed-foo.md`. Don't keep both prefixes (no `completed-plan-foo.md`).",
+	"3. Update the plan body: change the `Status:` line to `Status: **completed YYYY-MM-DD**` using today's date, and add a short \"Shipped:\" paragraph naming what landed and where the post-implementation truth lives (CLAUDE.md, source files, etc.).",
+	"4. Fix any relative links inside the moved file that broke from the move (e.g. `[todo.md](todo.md)` → `[todo.md](../todo.md)`).",
+	"5. Confirm no stale references to the old path remain elsewhere in the repo."
+].join("\n");
 /**
 * The coverage-baseline rule that the agent must consult before declaring a
 * task complete. Kept terse — the linked plan and `--help` carry the long form.
 */
-const RULE_BODY = [
+const COVERAGE_RULE_BODY = [
 	"### Coverage baseline",
 	"",
 	"Before declaring a task complete that touched files under `packages/*/src/` (or `src/` for single-package repos), run `pnpm test:coverage` then `pnpm exec bst coverage:check`. If any of the four overall totals (lines/statements/branches/functions) dropped by more than the configured tolerance, add tests until parity is restored — or, if a touched file is genuinely not worth covering, exclude it via `coverage.exclude` in `vitest.config.ts` and explain why in the commit message. If all four are flat-or-up, run `pnpm exec bst coverage:check --update-baseline` and stage `coverage-baseline.json` with the change. Skip this gate for docs-only, config-only, dependency-bump, or test-only changes."
 ].join("\n");
-/** Build the full managed block including markers. */
-function buildBlock() {
-	return `${START_MARKER}\n\n${RULE_BODY}\n\n${END_MARKER}\n`;
+function buildBlockText(block) {
+	return `${block.startMarker}\n\n${block.body}\n\n${block.endMarker}\n`;
 }
-function findBlock(existing) {
+function findBlock(existing, block) {
 	const lines = existing.split("\n");
 	let startLine = -1;
-	for (let i = 0; i < lines.length; i++) if (lines[i]?.trim() === START_MARKER) {
+	for (let i = 0; i < lines.length; i++) if (lines[i]?.trim() === block.startMarker) {
 		startLine = i;
 		break;
 	}
 	if (startLine === -1) return void 0;
-	for (let i = startLine + 1; i < lines.length; i++) if (lines[i]?.trim() === END_MARKER) return {
+	for (let i = startLine + 1; i < lines.length; i++) if (lines[i]?.trim() === block.endMarker) return {
 		startLine,
 		endLine: i
 	};
 }
-/**
-* Replace any existing `<!-- @tooling:coverage-rule -->...<!-- @tooling:endcoverage-rule -->`
-* block in `existing` with `block`, or append it at the end if no block is found.
-*/
 function upsertBlock(existing, block) {
-	const found = findBlock(existing);
-	if (!found) return `${existing.replace(/\n+$/, "")}\n\n${block}`;
+	const blockText = buildBlockText(block);
+	const found = findBlock(existing, block);
+	if (!found) return `${existing.replace(/\n+$/, "")}\n\n${blockText}`;
 	const lines = existing.split("\n");
 	const beforeLines = lines.slice(0, found.startLine);
 	const afterLines = lines.slice(found.endLine + 1);
 	const before = beforeLines.join("\n").replace(/\n+$/, "");
 	const after = afterLines.join("\n").replace(/^\n+/, "");
 	const tail = after.length > 0 ? `\n\n${after}` : "\n";
-	return `${before}\n\n${block.replace(/\n+$/, "")}${tail}`;
+	return `${before}\n\n${blockText.replace(/\n+$/, "")}${tail}`;
 }
-/** Strip a coverage-rule managed block (markers + body) from CLAUDE.md content. */
-function removeBlock(existing) {
-	const found = findBlock(existing);
+function removeBlock(existing, block) {
+	const found = findBlock(existing, block);
 	if (!found) return existing;
 	const lines = existing.split("\n");
 	const beforeLines = lines.slice(0, found.startLine);
@@ -4665,50 +4673,46 @@ function removeBlock(existing) {
 	if (after.length === 0) return `${before}\n`;
 	return `${before}\n\n${after}`;
 }
+function applyBlock(existing, block) {
+	return block.enabled ? upsertBlock(existing, block) : removeBlock(existing, block);
+}
 const STARTER_CLAUDE_MD = "# CLAUDE.md\n\nProject guidance for Claude Code.\n";
 async function generateClaudeMd(ctx) {
-	const config = resolveCoverageConfigFromContext(ctx, ctx.config.setupVitest);
+	const coverageConfig = resolveCoverageConfigFromContext(ctx, ctx.config.setupVitest);
+	const blocks = [{
+		name: "agent-rules",
+		startMarker: "<!-- @tooling:agent-rules -->",
+		endMarker: "<!-- @tooling:endagent-rules -->",
+		body: AGENT_RULES_BODY,
+		enabled: true
+	}, {
+		name: "coverage-rule",
+		startMarker: "<!-- @tooling:coverage-rule -->",
+		endMarker: "<!-- @tooling:endcoverage-rule -->",
+		body: COVERAGE_RULE_BODY,
+		enabled: coverageConfig.enabled
+	}];
 	const existing = ctx.read(FILE);
-	if (!config.enabled) {
-		if (!existing) return {
-			filePath: FILE,
-			action: "skipped",
-			description: "Coverage disabled; no CLAUDE.md to manage"
-		};
-		if (!existing.includes(START_MARKER)) return {
-			filePath: FILE,
-			action: "skipped",
-			description: "Coverage disabled; no managed block to remove"
-		};
-		const updated = removeBlock(existing);
-		ctx.write(FILE, updated);
-		return {
-			filePath: FILE,
-			action: "updated",
-			description: "Removed coverage-rule managed block"
-		};
-	}
-	const block = buildBlock();
+	let updated = existing ?? STARTER_CLAUDE_MD;
+	for (const block of blocks) updated = applyBlock(updated, block);
 	if (!existing) {
-		const content = upsertBlock(STARTER_CLAUDE_MD, block);
-		ctx.write(FILE, content);
+		ctx.write(FILE, updated);
 		return {
 			filePath: FILE,
 			action: "created",
-			description: "Generated CLAUDE.md with coverage-rule block"
+			description: "Generated CLAUDE.md with managed rule blocks"
 		};
 	}
-	const updated = upsertBlock(existing, block);
 	if (updated === existing) return {
 		filePath: FILE,
 		action: "skipped",
-		description: "Coverage-rule block already up to date"
+		description: "Managed rule blocks already up to date"
 	};
 	ctx.write(FILE, updated);
 	return {
 		filePath: FILE,
 		action: "updated",
-		description: "Updated coverage-rule managed block"
+		description: "Updated managed rule blocks"
 	};
 }
 //#endregion
@@ -4816,7 +4820,7 @@ async function runGenerators(ctx) {
 function generateMigratePrompt(results, config, detected) {
 	const sections = [];
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.58.0 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.59.1 repo:sync\` on ${timestamp}_\n`);
 	const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
 	if (changed.length > 0) {
 		const items = changed.map((r) => {
@@ -5083,6 +5087,10 @@ const syncCommand = defineCommand({
 			return;
 		}
 		const saved = loadToolingConfig(targetDir);
+		if (runComposeLintGate(targetDir, saved) > 0) {
+			process.exitCode = 1;
+			return;
+		}
 		const isFirstRun = !saved;
 		let config;
 		if (args.yes || !isFirstRun) {
@@ -5101,6 +5109,7 @@ const syncCommand = defineCommand({
 /** Run sync in check mode: dry-run drift detection. */
 async function runCheck(targetDir) {
 	const saved = loadToolingConfig(targetDir);
+	if (runComposeLintGate(targetDir, saved) > 0) return 1;
 	const detected = buildDefaultConfig(targetDir, {});
 	const { ctx, pendingWrites } = createDryRunContext(saved ? mergeWithSavedConfig(detected, saved) : detected);
 	logDetectionSummary(ctx);
@@ -5137,6 +5146,16 @@ async function runCheck(targetDir) {
 	}
 	return 1;
 }
+/**
+* Lint compose files before any generator or apply step runs. Returns the number
+* of issues found (0 = clean). Each issue is emitted via `log.error` so the
+* user sees the full message and the suggested fix.
+*/
+function runComposeLintGate(targetDir, config) {
+	const issues = lintComposeFiles(targetDir, config);
+	for (const issue of issues) log.error(issue.message);
+	return issues.length;
+}
 /** Files that are minified/bundled and produce unreadable diffs. */
 function isBundledFile(filePath) {
 	return filePath.endsWith("bst-hook.mjs");
@@ -6392,6 +6411,9 @@ function runRunChecks(targetDir, options = {}) {
 	const allChecks = [...CHECKS, ...add.map((name) => ({ name }))];
 	const failures = [];
 	const notDefined = [];
+	const withCoverage = options.withCoverage ?? false;
+	const useCoverageScript = withCoverage && definedScripts.has("test:coverage");
+	if (withCoverage && !useCoverageScript) log.warn("--with-coverage requested but test:coverage script is not defined; falling back to test");
 	for (const check of allChecks) {
 		if (shouldSkip(check.name, skip)) continue;
 		if (!definedScripts.has(check.name)) {
@@ -6401,7 +6423,8 @@ function runRunChecks(targetDir, options = {}) {
 			} else notDefined.push(check.name);
 			continue;
 		}
-		const cmd = check.args ? `pnpm run ${check.name} ${check.args}` : `pnpm run ${check.name}`;
+		const scriptName = check.name === "test" && useCoverageScript ? "test:coverage" : check.name;
+		const cmd = check.args ? `pnpm run ${scriptName} ${check.args}` : `pnpm run ${scriptName}`;
 		debug(vc, `Running: ${cmd} (in ${targetDir})`);
 		reporter.groupStart(check.name);
 		const start = Date.now();
@@ -6454,6 +6477,11 @@ const runChecksCommand = defineCommand({
 			type: "boolean",
 			description: "Emit detailed debug logging",
 			required: false
+		},
+		"with-coverage": {
+			type: "boolean",
+			description: "Run the test step with coverage (uses pnpm run test:coverage when defined)",
+			required: false
 		}
 	},
 	run({ args }) {
@@ -6461,7 +6489,8 @@ const runChecksCommand = defineCommand({
 			skip: args.skip ? new Set(args.skip.split(",").map((s) => s.trim())) : void 0,
 			add: args.add ? args.add.split(",").map((s) => s.trim()) : void 0,
 			failFast: args["fail-fast"] ? true : void 0,
-			verbose: args.verbose === true || isEnvVerbose()
+			verbose: args.verbose === true || isEnvVerbose(),
+			withCoverage: args["with-coverage"] === true
 		});
 		process.exitCode = exitCode;
 	}
@@ -6926,20 +6955,19 @@ const dockerCheckCommand = defineCommand({
 		const services = parseComposeServices(composeCwd, defaults.composeFiles);
 		const fileReader = createFileReader();
 		const rootPkgRaw = fileReader.readFile(path.join(cwd, "package.json"));
+		const rootPkg = rootPkgRaw ? parsePackageJson(rootPkgRaw) : void 0;
+		const projectName = deriveProjectName(rootPkg?.name ?? path.basename(cwd));
 		const locallyBuiltImageNames = [];
-		if (rootPkgRaw) {
-			const rootPkg = parsePackageJson(rootPkgRaw);
-			if (rootPkg?.name) {
-				const dockerPackages = detectDockerPackages(fileReader, cwd, rootPkg.name);
-				const composeImages = extractComposeImageNames(services);
-				const composeBuildDockerfiles = new Set(extractComposeBuildDockerfiles(services));
-				for (const pkg of dockerPackages) {
-					locallyBuiltImageNames.push(pkg.imageName);
-					const matchesImage = composeImages.some((img) => img === pkg.imageName || img.endsWith(`/${pkg.imageName}`));
-					const pkgDockerfileAbs = path.resolve(cwd, pkg.docker.dockerfile);
-					const matchesBuild = composeBuildDockerfiles.has(pkgDockerfileAbs);
-					if (!matchesImage && !matchesBuild) log.warn(`Docker package "${pkg.dir}" (image: ${pkg.imageName}) is not referenced in any compose service.`);
-				}
+		if (rootPkg?.name) {
+			const dockerPackages = detectDockerPackages(fileReader, cwd, rootPkg.name);
+			const composeImages = extractComposeImageNames(services);
+			const composeBuildDockerfiles = new Set(extractComposeBuildDockerfiles(services));
+			for (const pkg of dockerPackages) {
+				locallyBuiltImageNames.push(pkg.imageName);
+				const matchesImage = composeImages.some((img) => img === pkg.imageName || img.endsWith(`/${pkg.imageName}`));
+				const pkgDockerfileAbs = path.resolve(cwd, pkg.docker.dockerfile);
+				const matchesBuild = composeBuildDockerfiles.has(pkgDockerfileAbs);
+				if (!matchesImage && !matchesBuild) log.warn(`Docker package "${pkg.dir}" (image: ${pkg.imageName}) is not referenced in any compose service.`);
 			}
 		}
 		const tempOverlayPath = writeTempOverlay(generateCheckOverlay(services, locallyBuiltImageNames));
@@ -6953,6 +6981,7 @@ const dockerCheckCommand = defineCommand({
 				compose: {
 					cwd: composeCwd,
 					composeFiles,
+					projectName,
 					envFile: defaults.envFile,
 					services: defaults.services
 				},
@@ -8271,7 +8300,7 @@ const out = (msg) => console.log(msg);
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.58.0",
+		version: "0.59.1",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -8343,7 +8372,7 @@ const main = defineCommand({
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.58.0`);
+console.log(`@bensandee/tooling v0.59.1`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);