@bensandee/tooling 0.57.4 → 0.59.0

package/README.md

@@ -78,6 +78,28 @@ Custom blocks are anchored to the nearest preceding non-blank line. When `repo:s
 
 To skip a workflow file entirely, add `# @bensandee/tooling:ignore` as the first line — `repo:sync` will leave the file untouched.
 
+### pnpm-workspace.yaml
+
+`repo:sync` manages `pnpm-workspace.yaml` with a narrow contract — mandated keys, a few seeded-on-creation keys, and everything else passed through verbatim.
+
+**Mandated** (drift fails `repo:sync --check`):
+
+- `blockExoticSubdeps: true`
+- `minimumReleaseAge` — any non-negative number (`0` is valid)
+
+**Seeded on creation only** (free to change or remove afterward):
+
+- `minimumReleaseAgeExclude: ["@bensandee/*"]`
+- `packages: ["packages/*"]` (monorepos only)
+
+All other keys — `allowBuilds`, custom entries — are preserved verbatim through `repo:sync`. The generator emits the file for single-package repos too, not just monorepos.
+
+Opt out entirely with `"pnpmWorkspace": false` in `.tooling.json`; the generator then never inspects or writes the file.
+
+### packageManager force-bump
+
+`repo:sync` rewrites `package.json#packageManager` when an existing value is `pnpm@<N>.x` with `N < 11`, setting it to the tooling's pinned pnpm version (currently `11.1.1`). This is delivered through `repo:sync` rather than Renovate because the mandated `pnpm-workspace.yaml` keys (`blockExoticSubdeps`) require pnpm 11+. Within-major bumps (`pnpm@11.x → 11.y`) remain Renovate's job; non-pnpm package managers (yarn, npm) are out of scope.
+
 ### Repository setup
 
 | Command                   | Description                                                                                                                            |
@@ -350,6 +372,7 @@ Available override fields:
 | `releaseStrategy`    | string  | Detected from existing config, else monorepo: `"changesets"`, single: `"simple"` |
 | `projectType`        | string  | Auto-detected from `package.json` deps                                           |
 | `detectPackageTypes` | boolean | `true`                                                                           |
+| `pnpmWorkspace`      | `false` | Set to `false` to opt out of `pnpm-workspace.yaml` management                    |
 
 ## Debug logging
 

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";
@@ -39,7 +39,8 @@ const PackageJsonSchema = z.looseObject({
 	types: z.string().optional(),
 	typings: z.string().optional(),
 	engines: StringRecord.optional(),
-	repository: z.union([z.string(), z.looseObject({ url: z.string() })]).optional()
+	repository: z.union([z.string(), z.looseObject({ url: z.string() })]).optional(),
+	packageManager: z.string().optional()
 });
 const TsconfigSchema = z.looseObject({
 	extends: z.union([z.string(), z.array(z.string())]).optional(),
@@ -644,7 +645,8 @@ const ToolingConfigSchema = z.strictObject({
 	releaseAssets: z.array(ReleaseAssetSchema).optional().meta({ description: "Custom assets to build and upload to the release" }),
 	postReleaseHook: z.string().optional().meta({ description: "Override the post-release hook command (default: POST to POST_RELEASE_HOOK_URL with HMAC-SHA256 auth)" }),
 	postReleaseHookSecrets: z.array(z.string()).optional().meta({ description: "Additional secret names to inject as env vars in the post-release hook step (e.g. ['WEBHOOK_SECRET'])" }),
-	coverage: z.union([z.literal(false), CoverageConfigSchema]).optional().meta({ description: "Coverage tracking configuration. Set to false to disable; omit for default-on (when a vitest config is present)." })
+	coverage: z.union([z.literal(false), CoverageConfigSchema]).optional().meta({ description: "Coverage tracking configuration. Set to false to disable; omit for default-on (when a vitest config is present)." }),
+	pnpmWorkspace: z.literal(false).optional().meta({ description: "Set to false to opt out of pnpm-workspace.yaml management (skips both generation and the repo:sync --check validation)." })
 });
 /** Format a Zod issue as a human-readable bullet: location + plain-English explanation. */
 function formatIssue(issue) {
@@ -1591,7 +1593,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["@types/node"],
 	tsdown: {
 		"@changesets/cli": "2.31.0",
@@ -1607,7 +1609,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["tsdown"],
 	typescript: {
 		"@changesets/cli": "2.31.0",
@@ -1623,7 +1625,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["typescript"],
 	vitest: {
 		"@changesets/cli": "2.31.0",
@@ -1639,7 +1641,7 @@ const PER_PACKAGE_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["vitest"]
 };
 /** DevDeps that belong at the root regardless of structure. */
@@ -1658,7 +1660,7 @@ const ROOT_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["knip"],
 	lefthook: {
 		"@changesets/cli": "2.31.0",
@@ -1674,7 +1676,7 @@ const ROOT_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["lefthook"],
 	oxlint: {
 		"@changesets/cli": "2.31.0",
@@ -1690,7 +1692,7 @@ const ROOT_DEV_DEPS = {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["oxlint"]
 };
 /**
@@ -1731,7 +1733,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.0.9"
+				"pnpm": "11.1.1"
 			}["release-it"];
 			if (config.structure === "monorepo") deps["@release-it/bumper"] = {
 				"@changesets/cli": "2.31.0",
@@ -1747,7 +1749,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.0.9"
+				"pnpm": "11.1.1"
 			}["@release-it/bumper"];
 			break;
 		case "simple":
@@ -1765,7 +1767,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.0.9"
+				"pnpm": "11.1.1"
 			}["commit-and-tag-version"];
 			break;
 		case "changesets":
@@ -1783,7 +1785,7 @@ function addReleaseDeps(deps, config) {
 				"tsdown": "0.22.0",
 				"typescript": "6.0.3",
 				"vitest": "4.1.5",
-				"pnpm": "11.0.9"
+				"pnpm": "11.1.1"
 			}["@changesets/cli"];
 			break;
 	}
@@ -1806,8 +1808,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.0";
-	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.57.4";
+	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.11.2";
+	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.59.0";
 	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",
@@ -1823,7 +1825,7 @@ async function generatePackageJson(ctx) {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["oxfmt"];
 	if (ctx.config.formatter === "prettier") devDeps["prettier"] = {
 		"@changesets/cli": "2.31.0",
@@ -1839,7 +1841,7 @@ async function generatePackageJson(ctx) {
 		"tsdown": "0.22.0",
 		"typescript": "6.0.3",
 		"vitest": "4.1.5",
-		"pnpm": "11.0.9"
+		"pnpm": "11.1.1"
 	}["prettier"];
 	addReleaseDeps(devDeps, ctx.config);
 	if (existing) {
@@ -1897,6 +1899,36 @@ async function generatePackageJson(ctx) {
 			pkg["engines"] = { node: ">=24.13.0" };
 			changes.push("set engines.node >= 24.13.0");
 		}
+		const pinnedPnpm = {
+			"@changesets/cli": "2.31.0",
+			"@release-it/bumper": "7.0.5",
+			"@types/node": "24.12.3",
+			"commit-and-tag-version": "12.7.1",
+			"knip": "6.12.1",
+			"lefthook": "2.1.6",
+			"oxfmt": "0.48.0",
+			"oxlint": "1.63.0",
+			"prettier": "3.8.3",
+			"release-it": "20.0.1",
+			"tsdown": "0.22.0",
+			"typescript": "6.0.3",
+			"vitest": "4.1.5",
+			"pnpm": "11.1.1"
+		}["pnpm"];
+		const desiredPm = pinnedPnpm ? `pnpm@${pinnedPnpm}` : void 0;
+		if (desiredPm) {
+			const currentPm = pkg.packageManager;
+			if (!currentPm) {
+				pkg.packageManager = desiredPm;
+				changes.push(`set packageManager: ${desiredPm}`);
+			} else {
+				const match = /^pnpm@(\d+)\./.exec(currentPm);
+				if (match && Number(match[1]) < 11) {
+					pkg.packageManager = desiredPm;
+					changes.push(`bumped packageManager: ${currentPm} → ${desiredPm}`);
+				}
+			}
+		}
 		if (changes.length === 0) return {
 			filePath,
 			action: "skipped",
@@ -1933,7 +1965,7 @@ async function generatePackageJson(ctx) {
 			"tsdown": "0.22.0",
 			"typescript": "6.0.3",
 			"vitest": "4.1.5",
-			"pnpm": "11.0.9"
+			"pnpm": "11.1.1"
 		}["pnpm"]}`
 	};
 	ctx.write(filePath, JSON.stringify(pkg, null, 2) + "\n");
@@ -3842,26 +3874,103 @@ async function generateRenovate(ctx) {
 }
 //#endregion
 //#region src/generators/pnpm-workspace.ts
-const WORKSPACE_YAML = `packages:
+const FILE_PATH = "pnpm-workspace.yaml";
+const DEFAULT_MIN_RELEASE_AGE = 1440;
+const BENSANDEE_EXCLUDE_PATTERN = "@bensandee/*";
+const FRESH_MONOREPO = `packages:
   - "packages/*"
+
+blockExoticSubdeps: true
+
+minimumReleaseAge: ${DEFAULT_MIN_RELEASE_AGE}
+minimumReleaseAgeExclude:
+  - "@bensandee/*"
+`;
+const FRESH_SINGLE = `blockExoticSubdeps: true
+
+minimumReleaseAge: ${DEFAULT_MIN_RELEASE_AGE}
+minimumReleaseAgeExclude:
+  - "@bensandee/*"
 `;
+/** Minimal projection of `.tooling.json` needed by this generator. */
+const PnpmWorkspaceOptOutSchema = z.object({ pnpmWorkspace: z.literal(false).optional() });
+function isPnpmWorkspaceDisabled(ctx) {
+	const raw = ctx.read(".tooling.json");
+	if (!raw) return false;
+	try {
+		const result = PnpmWorkspaceOptOutSchema.safeParse(JSON.parse(raw));
+		return result.success && result.data.pnpmWorkspace === false;
+	} catch {
+		return false;
+	}
+}
+/**
+* Apply managed-key contract to an existing doc. Returns the list of changes made.
+*
+* 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):
+*   - everything else (`packages`, `allowBuilds`, etc.)
+*/
+function applyManagedKeys(doc) {
+	const changes = [];
+	if (doc.get("blockExoticSubdeps") !== true) {
+		doc.set("blockExoticSubdeps", true);
+		changes.push("set blockExoticSubdeps: true");
+	}
+	const minAge = doc.get("minimumReleaseAge");
+	if (typeof minAge !== "number" || !Number.isFinite(minAge) || minAge < 0) {
+		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) {
-	const filePath = "pnpm-workspace.yaml";
-	if (ctx.config.structure !== "monorepo") return {
-		filePath,
+	if (isPnpmWorkspaceDisabled(ctx)) return {
+		filePath: FILE_PATH,
 		action: "skipped",
-		description: "Not a monorepo"
+		description: "pnpmWorkspace: false in .tooling.json"
 	};
-	if (ctx.exists(filePath)) return {
-		filePath,
+	const isMonorepo = ctx.config.structure === "monorepo";
+	const existing = ctx.read(FILE_PATH);
+	if (existing === void 0) {
+		ctx.write(FILE_PATH, isMonorepo ? FRESH_MONOREPO : FRESH_SINGLE);
+		return {
+			filePath: FILE_PATH,
+			action: "created",
+			description: "Generated pnpm-workspace.yaml"
+		};
+	}
+	const doc = parseDocument(existing);
+	if (doc.errors.length > 0) return {
+		filePath: FILE_PATH,
 		action: "skipped",
-		description: "pnpm-workspace.yaml already exists"
+		description: `Could not parse existing pnpm-workspace.yaml: ${doc.errors[0]?.message ?? "unknown error"}`
 	};
-	ctx.write(filePath, WORKSPACE_YAML);
+	const changes = applyManagedKeys(doc);
+	if (changes.length === 0) return {
+		filePath: FILE_PATH,
+		action: "skipped",
+		description: "Already up to spec"
+	};
+	ctx.write(FILE_PATH, doc.toString());
 	return {
-		filePath,
-		action: "created",
-		description: "Generated pnpm-workspace.yaml"
+		filePath: FILE_PATH,
+		action: "updated",
+		description: changes.join(", ")
 	};
 }
 //#endregion
@@ -3922,6 +4031,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 };
@@ -3941,13 +4066,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
 	};
@@ -3962,11 +4081,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";
@@ -3983,15 +4103,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)) {
@@ -4032,7 +4146,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 };
@@ -4512,52 +4627,72 @@ async function generateCoverageCi(ctx) {
 //#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);
@@ -4567,50 +4702,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
@@ -4718,7 +4849,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.57.4 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.59.0 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) => {
@@ -4985,6 +5116,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) {
@@ -5003,6 +5138,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);
@@ -5039,6 +5175,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");
@@ -6828,20 +6974,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));
@@ -6855,6 +7000,7 @@ const dockerCheckCommand = defineCommand({
 				compose: {
 					cwd: composeCwd,
 					composeFiles,
+					projectName,
 					envFile: defaults.envFile,
 					services: defaults.services
 				},
@@ -8173,7 +8319,7 @@ const out = (msg) => console.log(msg);
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.57.4",
+		version: "0.59.0",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -8245,7 +8391,7 @@ const main = defineCommand({
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.57.4`);
+console.log(`@bensandee/tooling v0.59.0`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);

package/dist/docker-check/index.d.mts

@@ -53,6 +53,12 @@ interface ComposeConfig {
   cwd: string;
   /** Compose files to use (e.g. ["docker-compose.yaml", "docker-compose.check.yaml"]). */
   composeFiles: string[];
+  /**
+   * Project namespace passed to `docker compose --project-name`. Required so a
+   * check run cannot share a project (and thus its named volumes) with another
+   * stack on the same docker daemon. See `deriveProjectName()`.
+   */
+  projectName: string;
   /** Optional env file for compose. */
   envFile?: string;
   /** Service names to monitor for container-level health. */
@@ -125,4 +131,118 @@ declare function getContainerHealth(containers: ContainerInfo[], serviceName: st
 /** Run a single HTTP health check, returning true if the validator passes. */
 declare function checkHttpHealth(executor: DockerCheckExecutor, check: HttpHealthCheck): Promise<boolean>;
 //#endregion
-export { type CheckConfig, type CheckResult, type ComposeConfig, type ContainerInfo, type DockerCheckExecutor, type HttpHealthCheck, checkHttpHealth, composeArgs, composeDown, composeLogs, composePs, composeUp, createRealExecutor, getContainerHealth, runDockerCheck };
+//#region src/docker-check/project-name.d.ts
+/**
+ * Derive the `docker compose --project-name` value for a check run.
+ *
+ * Always returns a unique, non-colliding namespace so a stray `compose down -v`
+ * during the check cannot target volumes belonging to a long-running stack
+ * sharing the same docker daemon (the failure mode that wiped prod volumes
+ * when a CI runner bind-mounted /var/run/docker.sock and the check overlay
+ * inherited the base file's `name:`).
+ *
+ * Format: `<sanitized-repo>-check-<suffix>` where suffix prefers a CI run id
+ * for traceability and falls back to `process.pid` locally so two concurrent
+ * `bst docker:check` invocations on the same machine don't collide.
+ */
+declare function deriveProjectName(repoName: string, env?: NodeJS.ProcessEnv): string;
+//#endregion
+//#region src/utils/tooling-config.d.ts
+declare const ToolingConfigSchema: z.ZodObject<{
+  $schema: z.ZodOptional<z.ZodString>;
+  structure: z.ZodOptional<z.ZodEnum<{
+    single: "single";
+    monorepo: "monorepo";
+  }>>;
+  useEslintPlugin: z.ZodOptional<z.ZodBoolean>;
+  formatter: z.ZodOptional<z.ZodEnum<{
+    prettier: "prettier";
+    oxfmt: "oxfmt";
+  }>>;
+  setupVitest: z.ZodOptional<z.ZodBoolean>;
+  ci: z.ZodOptional<z.ZodEnum<{
+    github: "github";
+    forgejo: "forgejo";
+    none: "none";
+  }>>;
+  setupRenovate: z.ZodOptional<z.ZodBoolean>;
+  releaseStrategy: z.ZodOptional<z.ZodEnum<{
+    none: "none";
+    "release-it": "release-it";
+    simple: "simple";
+    changesets: "changesets";
+  }>>;
+  publishNpm: z.ZodOptional<z.ZodBoolean>;
+  publishDocker: z.ZodOptional<z.ZodBoolean>;
+  projectType: z.ZodOptional<z.ZodEnum<{
+    default: "default";
+    node: "node";
+    react: "react";
+    library: "library";
+  }>>;
+  detectPackageTypes: z.ZodOptional<z.ZodBoolean>;
+  docker: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    dockerfile: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodString>;
+    buildArgs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  }, z.core.$strip>>>;
+  dockerCheck: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    composeFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    envFile: z.ZodOptional<z.ZodString>;
+    services: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    healthChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      url: z.ZodString;
+      status: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    buildCommand: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    buildCwd: z.ZodOptional<z.ZodString>;
+    smoketest: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    smoketestCwd: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>]>>;
+  registryHost: z.ZodOptional<z.ZodString>;
+  registryNamespace: z.ZodOptional<z.ZodString>;
+  releaseAssets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    file: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>>;
+  postReleaseHook: z.ZodOptional<z.ZodString>;
+  postReleaseHookSecrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  coverage: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    history: z.ZodOptional<z.ZodEnum<{
+      none: "none";
+      "orphan-branch": "orphan-branch";
+    }>>;
+    historyBranch: z.ZodOptional<z.ZodString>;
+    tolerancePp: z.ZodOptional<z.ZodNumber>;
+    gateOnPullRequests: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>]>>;
+  pnpmWorkspace: z.ZodOptional<z.ZodLiteral<false>>;
+}, z.core.$strict>;
+type ToolingConfig = z.infer<typeof ToolingConfigSchema>;
+//#endregion
+//#region src/docker-check/compose-lint.d.ts
+interface ComposeLintIssue {
+  kind: "missing-name" | "duplicate-name";
+  /** Repo-relative paths involved in this issue (1 for missing-name, 2+ for duplicate-name). */
+  files: string[];
+  /** Pre-rendered human-readable message ready for `log.error`. */
+  message: string;
+}
+/**
+ * Walk compose files in `targetDir` and report lint violations:
+ *
+ * - Rule A (`missing-name`): every override compose file must declare a
+ *   top-level `name:` directive. Base files (docker-compose.yml etc.) are
+ *   exempt — their default of dir-basename is fine — but overrides without
+ *   `name:` silently inherit the base's project namespace, which is how a
+ *   `compose down -v` against the check overlay wiped the prod-volume project.
+ * - Rule B (`duplicate-name`): no two compose files in a single dir may
+ *   declare the same `name:`. Base files participate in collision detection.
+ */
+declare function lintComposeFiles(targetDir: string, config: ToolingConfig | undefined): ComposeLintIssue[];
+//#endregion
+export { type CheckConfig, type CheckResult, type ComposeConfig, type ComposeLintIssue, type ContainerInfo, type DockerCheckExecutor, type HttpHealthCheck, checkHttpHealth, composeArgs, composeDown, composeLogs, composePs, composeUp, createRealExecutor, deriveProjectName, getContainerHealth, lintComposeFiles, runDockerCheck };

package/dist/docker-check/index.mjs

@@ -1,2 +1,2 @@
-import { a as composeDown, c as composeUp, i as composeArgs, l as createRealExecutor, n as checkHttpHealth, o as composeLogs, r as getContainerHealth, s as composePs, t as runDockerCheck } from "../check-B5DFYJ3x.mjs";
-export { checkHttpHealth, composeArgs, composeDown, composeLogs, composePs, composeUp, createRealExecutor, getContainerHealth, runDockerCheck };
+import { a as composeArgs, c as composePs, f as lintComposeFiles, i as getContainerHealth, l as composeUp, n as runDockerCheck, o as composeDown, r as checkHttpHealth, s as composeLogs, t as deriveProjectName, u as createRealExecutor } from "../project-name-CAVRoqNy.mjs";
+export { checkHttpHealth, composeArgs, composeDown, composeLogs, composePs, composeUp, createRealExecutor, deriveProjectName, getContainerHealth, lintComposeFiles, runDockerCheck };

package/dist/index.d.mts

@@ -1,118 +1,2 @@
-import { z } from "zod";
-
-//#region src/utils/json.d.ts
-declare const PackageJsonSchema: z.ZodObject<{
-  name: z.ZodOptional<z.ZodString>;
-  version: z.ZodOptional<z.ZodString>;
-  private: z.ZodOptional<z.ZodBoolean>;
-  type: z.ZodOptional<z.ZodString>;
-  scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  bin: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-  exports: z.ZodOptional<z.ZodUnknown>;
-  main: z.ZodOptional<z.ZodString>;
-  types: z.ZodOptional<z.ZodString>;
-  typings: z.ZodOptional<z.ZodString>;
-  engines: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  repository: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-    url: z.ZodString;
-  }, z.core.$loose>]>>;
-}, z.core.$loose>;
-type PackageJson = z.infer<typeof PackageJsonSchema>;
-//#endregion
-//#region src/types.d.ts
-type CiPlatform = "github" | "forgejo" | "none";
-type ReleaseStrategy = "release-it" | "simple" | "changesets" | "none";
-type Formatter = "oxfmt" | "prettier";
-/** User's answers from the interactive prompt or CLI flags. */
-interface ProjectConfig {
-  /** Project name (from package.json name or user input) */
-  name: string;
-  /** Project structure */
-  structure: "single" | "monorepo";
-  /** Include @bensandee/eslint-plugin oxlint plugin */
-  useEslintPlugin: boolean;
-  /** Formatter choice */
-  formatter: Formatter;
-  /** Set up vitest with a starter test */
-  setupVitest: boolean;
-  /** CI platform choice */
-  ci: CiPlatform;
-  /** Set up Renovate for automated dependency updates */
-  setupRenovate: boolean;
-  /** Release management strategy */
-  releaseStrategy: ReleaseStrategy;
-  /** Opt-in: publish packages to npm registry */
-  publishNpm: boolean;
-  /** Opt-in: publish Docker images to a registry */
-  publishDocker: boolean;
-  /** Project type determines tsconfig base configuration */
-  projectType: "default" | "node" | "react" | "library";
-  /** Auto-detect and configure tsconfig bases for monorepo packages */
-  detectPackageTypes: boolean;
-  /** Target directory (default: cwd) */
-  targetDir: string;
-}
-/** Result from a single generator: what file was written and how. */
-interface GeneratorResult {
-  filePath: string;
-  action: "created" | "updated" | "skipped" | "archived" | "removed";
-  /** Human-readable description of what changed */
-  description: string;
-}
-/** Context passed to each generator function. */
-interface GeneratorContext {
-  config: ProjectConfig;
-  /** Absolute path to target directory */
-  targetDir: string;
-  /** Pre-parsed package.json from the target directory, or undefined if missing/invalid */
-  packageJson: PackageJson | undefined;
-  /** Check whether a file exists in the target directory */
-  exists: (relativePath: string) => boolean;
-  /** Read an existing file from the target directory, returns undefined if not found */
-  read: (relativePath: string) => string | undefined;
-  /** Write a file to the target directory (creating directories as needed) */
-  write: (relativePath: string, content: string) => void;
-  /** Remove a file from the target directory (no-op if not found) */
-  remove: (relativePath: string) => void;
-  /** Prompt user for conflict resolution on non-mergeable files */
-  confirmOverwrite: (relativePath: string) => Promise<"overwrite" | "skip">;
-}
-/** Generator function signature. */
-type Generator = (ctx: GeneratorContext) => Promise<GeneratorResult>;
-/** State detected from an existing project directory. */
-interface DetectedProjectState {
-  hasPackageJson: boolean;
-  hasTsconfig: boolean;
-  hasOxlintConfig: boolean;
-  /** Existing oxlint.config.ts already imports @bensandee/config/oxlint/recommended */
-  oxlintExtendsRecommended: boolean;
-  /** Legacy .oxlintrc.json found (should be migrated to oxlint.config.ts) */
-  hasLegacyOxlintJson: boolean;
-  hasGitignore: boolean;
-  hasVitestConfig: boolean;
-  hasTsdownConfig: boolean;
-  hasPnpmWorkspace: boolean;
-  hasKnipConfig: boolean;
-  hasRenovateConfig: boolean;
-  hasReleaseItConfig: boolean;
-  hasSimpleReleaseConfig: boolean;
-  hasChangesetsConfig: boolean;
-  /** Whether package.json has a repository field (needed for release workflows) */
-  hasRepositoryField: boolean;
-  /** Whether commit-and-tag-version is in root devDependencies (required for simple release strategy) */
-  hasCommitAndTagVersion: boolean;
-  /** Git remote origin URL (for inferring repository field) */
-  gitRemoteUrl: string | null;
-  /** Legacy tooling configs found */
-  legacyConfigs: LegacyConfig[];
-}
-declare const LEGACY_TOOLS: readonly ["eslint", "prettier", "jest", "webpack", "rollup"];
-type LegacyTool = (typeof LEGACY_TOOLS)[number];
-interface LegacyConfig {
-  tool: LegacyTool;
-  files: string[];
-}
-//#endregion
+import { a as LegacyConfig, i as GeneratorResult, n as Generator, o as ProjectConfig, r as GeneratorContext, t as DetectedProjectState } from "./types-DtwkblrK.mjs";
 export { type DetectedProjectState, type Generator, type GeneratorContext, type GeneratorResult, type LegacyConfig, type ProjectConfig };

package/dist/{check-B5DFYJ3x.mjs → project-name-CAVRoqNy.mjs}

@@ -1,6 +1,9 @@
 import * as clack from "@clack/prompts";
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { z } from "zod";
+import { parse } from "yaml";
 //#region src/utils/log.ts
 const out = (msg) => console.log(msg);
 const isCI = Boolean(process.env["CI"]);
@@ -42,6 +45,148 @@ function debugExec(config, label, result) {
 	log.info(lines.join("\n"));
 }
 //#endregion
+//#region src/docker-check/compose-lint.ts
+const ComposeFileShape = z.looseObject({ name: z.unknown().optional() });
+/**
+* Compose files live by convention in `./` or `docker/`. The lint walks those
+* by default; if `.tooling.json#dockerCheck.composeFiles` overrides the
+* location, each listed file (and its parent dir) is also linted.
+*/
+const COMPOSE_DIR_CANDIDATES = [".", "docker"];
+/** Base compose file names whose project namespace defaults to dir basename. */
+const BASE_COMPOSE_FILES = new Set([
+	"docker-compose.yml",
+	"docker-compose.yaml",
+	"compose.yml",
+	"compose.yaml"
+]);
+const COMPOSE_FILENAME_PATTERN = /^(?:docker-compose|compose).*\.(?:yml|yaml)$/;
+/**
+* Walk compose files in `targetDir` and report lint violations:
+*
+* - Rule A (`missing-name`): every override compose file must declare a
+*   top-level `name:` directive. Base files (docker-compose.yml etc.) are
+*   exempt — their default of dir-basename is fine — but overrides without
+*   `name:` silently inherit the base's project namespace, which is how a
+*   `compose down -v` against the check overlay wiped the prod-volume project.
+* - Rule B (`duplicate-name`): no two compose files in a single dir may
+*   declare the same `name:`. Base files participate in collision detection.
+*/
+function lintComposeFiles(targetDir, config) {
+	const issues = [];
+	const visitedDirs = /* @__PURE__ */ new Set();
+	const standaloneFiles = [];
+	const dockerCheck = config?.dockerCheck;
+	const isObjectConfig = dockerCheck !== void 0 && dockerCheck !== false;
+	for (const candidate of COMPOSE_DIR_CANDIDATES) {
+		const absDir = path.resolve(targetDir, candidate);
+		if (existsSync(absDir)) visitDir(targetDir, absDir, visitedDirs, issues);
+	}
+	if (isObjectConfig && dockerCheck.composeFiles) for (const rel of dockerCheck.composeFiles) {
+		const absFile = path.resolve(targetDir, rel);
+		if (!existsSync(absFile)) continue;
+		const dir = path.dirname(absFile);
+		if (visitedDirs.has(dir)) continue;
+		const basename = path.basename(absFile);
+		standaloneFiles.push({
+			absPath: absFile,
+			relPath: path.relative(targetDir, absFile),
+			basename
+		});
+	}
+	const standaloneByDir = /* @__PURE__ */ new Map();
+	for (const file of standaloneFiles) {
+		const dir = path.dirname(file.absPath);
+		const list = standaloneByDir.get(dir) ?? [];
+		list.push(file);
+		standaloneByDir.set(dir, list);
+	}
+	for (const files of standaloneByDir.values()) {
+		files.sort((a, b) => a.relPath.localeCompare(b.relPath));
+		lintDirFiles(files, issues);
+	}
+	return issues;
+}
+function visitDir(targetDir, absDir, visitedDirs, issues) {
+	if (visitedDirs.has(absDir)) return;
+	visitedDirs.add(absDir);
+	let entries;
+	try {
+		entries = readdirSync(absDir);
+	} catch (_error) {
+		return;
+	}
+	const files = entries.filter((name) => COMPOSE_FILENAME_PATTERN.test(name)).toSorted().map((name) => {
+		const absPath = path.join(absDir, name);
+		return {
+			absPath,
+			relPath: path.relative(targetDir, absPath),
+			basename: name
+		};
+	});
+	if (files.length === 0) return;
+	lintDirFiles(files, issues);
+}
+function lintDirFiles(files, issues) {
+	const namesByFile = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const declaredName = readTopLevelName(file.absPath);
+		namesByFile.set(file.relPath, declaredName);
+		if (!BASE_COMPOSE_FILES.has(file.basename) && (declaredName === void 0 || declaredName === "")) {
+			const suggested = suggestProjectName(file);
+			issues.push({
+				kind: "missing-name",
+				files: [file.relPath],
+				message: `${file.relPath}: override compose file is missing required top-level 'name:' directive.\n  Add: name: ${suggested}\n  Why: without an explicit name, this override inherits the base file's project namespace.\n  A 'docker compose down -v' against this override would target the base project's volumes\n  — which has caused production volume loss in the past.`
+			});
+		}
+	}
+	const filesByName = /* @__PURE__ */ new Map();
+	for (const [relPath, declaredName] of namesByFile) {
+		if (declaredName === void 0 || declaredName === "") continue;
+		const list = filesByName.get(declaredName) ?? [];
+		list.push(relPath);
+		filesByName.set(declaredName, list);
+	}
+	for (const [declaredName, dupFiles] of filesByName) {
+		if (dupFiles.length < 2) continue;
+		dupFiles.sort();
+		const [first, second, ...rest] = dupFiles;
+		const ext = rest.length > 0 ? `, ${rest.join(", ")}` : "";
+		issues.push({
+			kind: "duplicate-name",
+			files: dupFiles,
+			message: `${String(first)} and ${String(second)}${ext} both declare 'name: ${declaredName}'.\n  Each compose file in the same directory must declare a unique 'name:'.\n  Suggested fix: rename one (e.g. 'name: ${declaredName}-test' in one of them).`
+		});
+	}
+}
+/** Suggest a default name for an override file by stripping the variant from the filename. */
+function suggestProjectName(file) {
+	const parts = file.basename.replace(/\.(yml|yaml)$/, "").split(".");
+	const variant = parts[parts.length - 1];
+	if (parts.length > 1 && variant) return `<project>-${variant}`;
+	return "<project>-check";
+}
+function readTopLevelName(absPath) {
+	let raw;
+	try {
+		raw = readFileSync(absPath, "utf-8");
+	} catch (_error) {
+		return;
+	}
+	let yamlValue;
+	try {
+		yamlValue = parse(raw);
+	} catch (_error) {
+		return;
+	}
+	const parsed = ComposeFileShape.safeParse(yamlValue);
+	if (!parsed.success) return void 0;
+	const value = parsed.data.name;
+	if (typeof value !== "string") return void 0;
+	return value;
+}
+//#endregion
 //#region src/utils/exec.ts
 /** Type guard for `execSync` errors that carry stdout/stderr/status. */
 function isExecSyncError(err) {
@@ -116,7 +261,11 @@ const ContainerInfoSchema = z.object({
 });
 /** Build the `docker compose` base args from config. */
 function composeArgs(config) {
-	const args = ["compose"];
+	const args = [
+		"compose",
+		"--project-name",
+		config.projectName
+	];
 	for (const f of config.composeFiles) args.push("-f", f);
 	if (config.envFile) args.push("--env-file", config.envFile);
 	return args;
@@ -340,4 +489,25 @@ async function runDockerCheck(executor, config) {
 	}
 }
 //#endregion
-export { composeDown as a, composeUp as c, debug as d, debugExec as f, note as g, log as h, composeArgs as i, createRealExecutor as l, redact as m, checkHttpHealth as n, composeLogs as o, isEnvVerbose as p, getContainerHealth as r, composePs as s, runDockerCheck as t, isExecSyncError as u };
+//#region src/docker-check/project-name.ts
+/**
+* Derive the `docker compose --project-name` value for a check run.
+*
+* Always returns a unique, non-colliding namespace so a stray `compose down -v`
+* during the check cannot target volumes belonging to a long-running stack
+* sharing the same docker daemon (the failure mode that wiped prod volumes
+* when a CI runner bind-mounted /var/run/docker.sock and the check overlay
+* inherited the base file's `name:`).
+*
+* Format: `<sanitized-repo>-check-<suffix>` where suffix prefers a CI run id
+* for traceability and falls back to `process.pid` locally so two concurrent
+* `bst docker:check` invocations on the same machine don't collide.
+*/
+function deriveProjectName(repoName, env = process.env) {
+	return `${sanitize(repoName)}-check-${sanitize(env["GITHUB_RUN_ID"] ?? env["CI_RUN_ID"] ?? String(process.pid))}`;
+}
+function sanitize(name) {
+	return name.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "repo";
+}
+//#endregion
+export { log as _, composeArgs as a, composePs as c, isExecSyncError as d, lintComposeFiles as f, redact as g, isEnvVerbose as h, getContainerHealth as i, composeUp as l, debugExec as m, runDockerCheck as n, composeDown as o, debug as p, checkHttpHealth as r, composeLogs as s, deriveProjectName as t, createRealExecutor as u, note as v };

package/dist/types-DtwkblrK.d.mts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+
+//#region src/utils/json.d.ts
+declare const PackageJsonSchema: z.ZodObject<{
+  name: z.ZodOptional<z.ZodString>;
+  version: z.ZodOptional<z.ZodString>;
+  private: z.ZodOptional<z.ZodBoolean>;
+  type: z.ZodOptional<z.ZodString>;
+  scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  bin: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+  exports: z.ZodOptional<z.ZodUnknown>;
+  main: z.ZodOptional<z.ZodString>;
+  types: z.ZodOptional<z.ZodString>;
+  typings: z.ZodOptional<z.ZodString>;
+  engines: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  repository: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    url: z.ZodString;
+  }, z.core.$loose>]>>;
+  packageManager: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type PackageJson = z.infer<typeof PackageJsonSchema>;
+//#endregion
+//#region src/types.d.ts
+type CiPlatform = "github" | "forgejo" | "none";
+type ReleaseStrategy = "release-it" | "simple" | "changesets" | "none";
+type Formatter = "oxfmt" | "prettier";
+/** User's answers from the interactive prompt or CLI flags. */
+interface ProjectConfig {
+  /** Project name (from package.json name or user input) */
+  name: string;
+  /** Project structure */
+  structure: "single" | "monorepo";
+  /** Include @bensandee/eslint-plugin oxlint plugin */
+  useEslintPlugin: boolean;
+  /** Formatter choice */
+  formatter: Formatter;
+  /** Set up vitest with a starter test */
+  setupVitest: boolean;
+  /** CI platform choice */
+  ci: CiPlatform;
+  /** Set up Renovate for automated dependency updates */
+  setupRenovate: boolean;
+  /** Release management strategy */
+  releaseStrategy: ReleaseStrategy;
+  /** Opt-in: publish packages to npm registry */
+  publishNpm: boolean;
+  /** Opt-in: publish Docker images to a registry */
+  publishDocker: boolean;
+  /** Project type determines tsconfig base configuration */
+  projectType: "default" | "node" | "react" | "library";
+  /** Auto-detect and configure tsconfig bases for monorepo packages */
+  detectPackageTypes: boolean;
+  /** Target directory (default: cwd) */
+  targetDir: string;
+}
+/** Result from a single generator: what file was written and how. */
+interface GeneratorResult {
+  filePath: string;
+  action: "created" | "updated" | "skipped" | "archived" | "removed";
+  /** Human-readable description of what changed */
+  description: string;
+}
+/** Context passed to each generator function. */
+interface GeneratorContext {
+  config: ProjectConfig;
+  /** Absolute path to target directory */
+  targetDir: string;
+  /** Pre-parsed package.json from the target directory, or undefined if missing/invalid */
+  packageJson: PackageJson | undefined;
+  /** Check whether a file exists in the target directory */
+  exists: (relativePath: string) => boolean;
+  /** Read an existing file from the target directory, returns undefined if not found */
+  read: (relativePath: string) => string | undefined;
+  /** Write a file to the target directory (creating directories as needed) */
+  write: (relativePath: string, content: string) => void;
+  /** Remove a file from the target directory (no-op if not found) */
+  remove: (relativePath: string) => void;
+  /** Prompt user for conflict resolution on non-mergeable files */
+  confirmOverwrite: (relativePath: string) => Promise<"overwrite" | "skip">;
+}
+/** Generator function signature. */
+type Generator = (ctx: GeneratorContext) => Promise<GeneratorResult>;
+/** State detected from an existing project directory. */
+interface DetectedProjectState {
+  hasPackageJson: boolean;
+  hasTsconfig: boolean;
+  hasOxlintConfig: boolean;
+  /** Existing oxlint.config.ts already imports @bensandee/config/oxlint/recommended */
+  oxlintExtendsRecommended: boolean;
+  /** Legacy .oxlintrc.json found (should be migrated to oxlint.config.ts) */
+  hasLegacyOxlintJson: boolean;
+  hasGitignore: boolean;
+  hasVitestConfig: boolean;
+  hasTsdownConfig: boolean;
+  hasPnpmWorkspace: boolean;
+  hasKnipConfig: boolean;
+  hasRenovateConfig: boolean;
+  hasReleaseItConfig: boolean;
+  hasSimpleReleaseConfig: boolean;
+  hasChangesetsConfig: boolean;
+  /** Whether package.json has a repository field (needed for release workflows) */
+  hasRepositoryField: boolean;
+  /** Whether commit-and-tag-version is in root devDependencies (required for simple release strategy) */
+  hasCommitAndTagVersion: boolean;
+  /** Git remote origin URL (for inferring repository field) */
+  gitRemoteUrl: string | null;
+  /** Legacy tooling configs found */
+  legacyConfigs: LegacyConfig[];
+}
+declare const LEGACY_TOOLS: readonly ["eslint", "prettier", "jest", "webpack", "rollup"];
+type LegacyTool = (typeof LEGACY_TOOLS)[number];
+interface LegacyConfig {
+  tool: LegacyTool;
+  files: string[];
+}
+//#endregion
+export { LegacyConfig as a, GeneratorResult as i, Generator as n, ProjectConfig as o, GeneratorContext as r, DetectedProjectState as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.57.4",
+  "version": "0.59.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {
@@ -55,7 +55,7 @@
     "release-it": "20.0.1",
     "tsdown": "0.22.0",
     "@bensandee/claude-hooks": "0.7.4",
-    "@bensandee/config": "0.11.0"
+    "@bensandee/config": "0.11.2"
   },
   "scripts": {
     "build": "tsdown",

package/tooling.schema.json

@@ -258,6 +258,11 @@
           "additionalProperties": false
         }
       ]
+    },
+    "pnpmWorkspace": {
+      "description": "Set to false to opt out of pnpm-workspace.yaml management (skips both generation and the repo:sync --check validation).",
+      "type": "boolean",
+      "const": false
     }
   },
   "additionalProperties": false