@stdd/plugin 0.9.0

package/runtime/cli/generated-files.mjs

@@ -0,0 +1,1693 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	AGENT_ADAPTERS,
+	assertSemanticVersion,
+	CI_ADAPTERS,
+	getAgentAdapter,
+	renderAgentInstructions,
+} from "../sdk/adapters.mjs";
+import { sameFileIdentity } from "../sdk/file-observation.mjs";
+import { assertSkillName, resolveRepoPath, resolveWritableRepoPath } from "../sdk/path.mjs";
+import { isStddSourceCheckout } from "./claude-hooks.mjs";
+import {
+	openNativeRepoPath,
+	openOrCreateNativeRepoDirectory,
+	publishNativeRepoFile,
+	readNativeFile,
+	verifyNativeRepoDirectory,
+	writeNativeFileContent,
+} from "./held-fs.mjs";
+import { DEFAULT_CONFIG, parseFrontmatter, sha256 } from "./lib.mjs";
+import { fail } from "./runtime.mjs";
+import { MANIFEST_HASH_PATTERN } from "./state-validation.mjs";
+
+export const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8")).version;
+export const KNOWN_TOOLS = Object.keys(AGENT_ADAPTERS);
+export const KNOWN_CI = Object.keys(CI_ADAPTERS);
+export const KNOWN_CAPABILITIES = Object.keys(DEFAULT_CONFIG.capabilities);
+export const CLEANUP_JOURNAL_REL = ".stdd/cleanup-transaction.json";
+const SHIPPED_PLAYBOOK_FILES = new Set(
+	fs.readdirSync(path.join(PKG_ROOT, "playbooks")).filter((file) => file.endsWith(".md")),
+);
+// This append-only registry is package data: deleting a shipped playbook does
+// not delete its ownership record, so existing installs can retire it safely
+// without a release author remembering to move a basename between two lists.
+const MANAGED_PLAYBOOK_REGISTRY = JSON.parse(
+	fs.readFileSync(path.join(PKG_ROOT, "playbooks", "managed-playbooks.json"), "utf8"),
+);
+if (
+	typeof MANAGED_PLAYBOOK_REGISTRY !== "object" ||
+	MANAGED_PLAYBOOK_REGISTRY === null ||
+	!Array.isArray(MANAGED_PLAYBOOK_REGISTRY.managed) ||
+	MANAGED_PLAYBOOK_REGISTRY.managed.some(
+		(file) =>
+			typeof file !== "string" ||
+			!file.endsWith(".md") ||
+			path.posix.basename(file) !== file ||
+			file === "." ||
+			file === "..",
+	) ||
+	new Set(MANAGED_PLAYBOOK_REGISTRY.managed).size !== MANAGED_PLAYBOOK_REGISTRY.managed.length ||
+	[...SHIPPED_PLAYBOOK_FILES].some((file) => !MANAGED_PLAYBOOK_REGISTRY.managed.includes(file))
+) {
+	throw new Error(
+		"playbooks/managed-playbooks.json must be an append-only registry of shipped basenames",
+	);
+}
+const KNOWN_MANAGED_PLAYBOOK_FILES = new Set(MANAGED_PLAYBOOK_REGISTRY.managed);
+const NATIVE_JOURNAL_IDENTITY = Symbol("native cleanup journal identity");
+export const NATIVE_MANIFEST_IDENTITY = Symbol("native manifest identity");
+export const STAMP = `generated by stdd v${VERSION} — do not edit, re-run \`stdd init\``;
+export const NPM_RUNNER = `npm exec --offline --package=@stdd/cli@${VERSION} -- stdd`;
+export const SOURCE_RUNNER = 'node "$(git rev-parse --show-toplevel)/cli/stdd.mjs"';
+
+export function validateAdapterSelection(field, values, known, { nonEmpty = false } = {}) {
+	if (!Array.isArray(values)) throw new TypeError(`${field} must be an array`);
+	if (nonEmpty && values.length === 0) {
+		throw new TypeError(`${field} must be a non-empty array`);
+	}
+	if (values.some((id) => typeof id !== "string" || !known.includes(id))) {
+		throw new TypeError(`${field} contains an unknown adapter ID`);
+	}
+	if (new Set(values).size !== values.length) {
+		throw new TypeError(`${field} must not contain duplicate adapter IDs`);
+	}
+	return [...values];
+}
+
+function validateManifestTargets(value) {
+	const required = ["tools", "ci", "hooks", "sessionHook", "stopHook"];
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new TypeError("must be an object");
+	}
+	const keys = Object.keys(value);
+	const missing = required.filter((key) => !Object.hasOwn(value, key));
+	const unknown = keys.filter((key) => !required.includes(key));
+	if (missing.length > 0 || unknown.length > 0) {
+		throw new TypeError(
+			`must contain exactly ${required.join(", ")}${
+				missing.length > 0 ? `; missing ${missing.join(", ")}` : ""
+			}${unknown.length > 0 ? `; unknown ${unknown.join(", ")}` : ""}`,
+		);
+	}
+	const tools = validateAdapterSelection("tools", value.tools, KNOWN_TOOLS, {
+		nonEmpty: true,
+	});
+	const ci = validateAdapterSelection("ci", value.ci, KNOWN_CI);
+	for (const field of ["hooks", "sessionHook", "stopHook"]) {
+		if (typeof value[field] !== "boolean") throw new TypeError(`${field} must be a boolean`);
+	}
+	return {
+		tools,
+		ci,
+		hooks: value.hooks,
+		sessionHook: value.sessionHook,
+		stopHook: value.stopHook,
+	};
+}
+
+export function loadPlaybooks() {
+	const dir = path.join(PKG_ROOT, "playbooks");
+	return fs
+		.readdirSync(dir)
+		.filter((f) => f.endsWith(".md"))
+		.map((f) => {
+			const source = fs.readFileSync(path.join(dir, f), "utf8");
+			const { meta, body } = parseFrontmatter(source);
+			if (!meta.name || !meta.description) {
+				fail(`playbook ${f} is missing required frontmatter (name, description)`);
+			}
+			try {
+				assertSkillName(meta.name, `playbook ${f} name`);
+			} catch (err) {
+				fail(err.message);
+			}
+			return { file: f, source, meta, body };
+		});
+}
+
+/**
+ * Project recipes: repo-owned playbooks in `.stdd/playbooks/local/`, same
+ * frontmatter contract as the kit's. Never generated, never overwritten.
+ */
+export function loadLocalPlaybooks(targetDir) {
+	let dir;
+	try {
+		dir = resolveWritableRepoPath(targetDir, ".stdd/playbooks/local", "local playbooks directory");
+	} catch (err) {
+		fail(err.message);
+	}
+	if (!fs.existsSync(dir)) return [];
+	const playbooks = fs
+		.readdirSync(dir, { withFileTypes: true })
+		.filter((entry) => entry.name.endsWith(".md"))
+		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+		.map((entry) => {
+			if (!entry.isFile()) fail(`local playbook local/${entry.name} must be a regular file`);
+			const f = entry.name;
+			let filePath;
+			try {
+				filePath = resolveWritableRepoPath(
+					targetDir,
+					`.stdd/playbooks/local/${f}`,
+					`local playbook local/${f}`,
+				);
+			} catch (err) {
+				fail(err.message);
+			}
+			const source = fs.readFileSync(filePath, "utf8");
+			const { meta, body } = parseFrontmatter(source);
+			if (!meta.name || !meta.description) {
+				fail(`local playbook local/${f} is missing required frontmatter (name, description)`);
+			}
+			try {
+				assertSkillName(meta.name, `local playbook local/${f} name`);
+			} catch (err) {
+				fail(err.message);
+			}
+			return { file: f, source, meta, body };
+		});
+	const byName = new Map();
+	for (const playbook of playbooks) {
+		const previous = byName.get(playbook.meta.name);
+		if (previous) {
+			fail(
+				`duplicate local playbook name "${playbook.meta.name}" in .stdd/playbooks/local/${previous.file} and .stdd/playbooks/local/${playbook.file}; rename one recipe or give it a unique frontmatter name`,
+			);
+		}
+		byName.set(playbook.meta.name, playbook);
+	}
+	return playbooks;
+}
+
+function isRecognizedGeneratedOutput(file) {
+	const exact = new Set([
+		".stdd/method.md",
+		...Object.values(AGENT_ADAPTERS).map((adapter) => adapter.snippetFile),
+		...Object.values(CI_ADAPTERS)
+			.map((adapter) => adapter.outputFile)
+			.filter((output) => output !== null),
+		...[...KNOWN_MANAGED_PLAYBOOK_FILES].map((name) => `.stdd/playbooks/${name}`),
+	]);
+	if (exact.has(file)) return true;
+
+	for (const adapter of Object.values(AGENT_ADAPTERS)) {
+		const prefix = `${adapter.skillRoot}/`;
+		if (!file.startsWith(prefix)) continue;
+		const parts = file.slice(prefix.length).split("/");
+		if (parts.length === 2 && parts[1] === "SKILL.md") {
+			try {
+				assertSkillName(parts[0], "manifest generated skill name");
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	}
+
+	if (isPrivateGeneratedQuarantinePath(file)) return true;
+	if (!MANIFEST_QUARANTINE_BASENAME.test(path.posix.basename(file))) return false;
+	const parent = path.posix.dirname(file);
+	const exactParents = new Set([...exact].map((output) => path.posix.dirname(output)));
+	if (exactParents.has(parent)) return true;
+	for (const adapter of Object.values(AGENT_ADAPTERS)) {
+		const prefix = `${adapter.skillRoot}/`;
+		if (!parent.startsWith(prefix)) continue;
+		const skillName = parent.slice(prefix.length);
+		try {
+			assertSkillName(skillName, "manifest quarantined skill name");
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	return false;
+}
+
+/**
+ * Read and validate the generated-file manifest once for every caller.
+ * Returns null when the manifest is absent and throws an actionable shape
+ * or path error for a present manifest that cannot be trusted.
+ */
+export function readManifestDocument(targetDir) {
+	let manifestPath;
+	try {
+		manifestPath = resolveWritableRepoPath(targetDir, ".stdd/manifest.json", "manifest path");
+	} catch (err) {
+		throw new TypeError(`has an unsafe path: ${err.message}`);
+	}
+	if (!fs.existsSync(manifestPath)) return null;
+	return parseManifestDocument(targetDir, fs.readFileSync(manifestPath, "utf8"));
+}
+
+function parseManifestDocument(targetDir, text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (err) {
+		throw new TypeError(`is not valid JSON: ${err.message}`);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new TypeError("must contain a JSON object");
+	}
+	if (!Object.hasOwn(parsed, "generatedBy") || parsed.generatedBy !== "stdd") {
+		throw new TypeError('generatedBy must equal "stdd"');
+	}
+	if (!Object.hasOwn(parsed, "version")) {
+		throw new TypeError("version must be a semantic version");
+	}
+	assertSemanticVersion(parsed.version, "version");
+	if (
+		!Object.hasOwn(parsed, "files") ||
+		typeof parsed.files !== "object" ||
+		parsed.files === null ||
+		Array.isArray(parsed.files)
+	) {
+		throw new TypeError("files must be an object");
+	}
+	const files = Object.create(null);
+	for (const file of Object.keys(parsed.files)) {
+		try {
+			resolveWritableRepoPath(targetDir, file, `manifest path ${JSON.stringify(file)}`);
+		} catch (err) {
+			throw new TypeError(`has an unsafe path: ${err.message}`);
+		}
+		if (!isRecognizedGeneratedOutput(file)) {
+			throw new TypeError(
+				`files[${JSON.stringify(file)}] is not a recognized STDD-generated output path`,
+			);
+		}
+		const hash = parsed.files[file];
+		if (typeof hash !== "string" || !MANIFEST_HASH_PATTERN.test(hash)) {
+			throw new TypeError(
+				`files[${JSON.stringify(file)}] must be an exact sha256:<64 lowercase hex> hash`,
+			);
+		}
+		files[file] = hash;
+	}
+	const normalized = { ...parsed, files };
+	if (Object.hasOwn(parsed, "quarantineIdentities")) {
+		if (
+			typeof parsed.quarantineIdentities !== "object" ||
+			parsed.quarantineIdentities === null ||
+			Array.isArray(parsed.quarantineIdentities)
+		) {
+			throw new TypeError("quarantineIdentities must be an object");
+		}
+		const quarantineIdentities = Object.create(null);
+		for (const [relative, observation] of Object.entries(parsed.quarantineIdentities)) {
+			if (
+				!Object.hasOwn(files, relative) ||
+				!(
+					MANIFEST_QUARANTINE_BASENAME.test(path.posix.basename(relative)) ||
+					isPrivateGeneratedQuarantinePath(relative)
+				) ||
+				typeof observation !== "object" ||
+				observation === null ||
+				Array.isArray(observation) ||
+				typeof observation.identity !== "object" ||
+				observation.identity === null ||
+				observation.identity.version !== 2 ||
+				typeof observation.identity.platform !== "string" ||
+				typeof observation.identity.volume !== "string" ||
+				typeof observation.identity.fileId !== "string" ||
+				observation.identity.kind !== "file" ||
+				["owner", "permissions", "linkCount"].some(
+					(field) => Object.hasOwn(observation, field) && typeof observation[field] !== "string",
+				) ||
+				(Object.hasOwn(observation, "parentObservation") &&
+					(typeof observation.parentObservation !== "object" ||
+						observation.parentObservation === null ||
+						observation.parentObservation.identity?.version !== 2 ||
+						typeof observation.parentObservation.identity?.platform !== "string" ||
+						typeof observation.parentObservation.identity?.volume !== "string" ||
+						typeof observation.parentObservation.identity?.fileId !== "string" ||
+						observation.parentObservation.identity?.kind !== "directory" ||
+						["owner", "permissions", "linkCount"].some(
+							(field) =>
+								Object.hasOwn(observation.parentObservation, field) &&
+								typeof observation.parentObservation[field] !== "string",
+						)))
+			) {
+				throw new TypeError(
+					`quarantineIdentities[${JSON.stringify(relative)}] must describe a listed portable file identity`,
+				);
+			}
+			quarantineIdentities[relative] = observation;
+		}
+		normalized.quarantineIdentities = quarantineIdentities;
+	}
+	if (Object.hasOwn(parsed, "targets")) {
+		try {
+			normalized.targets = validateManifestTargets(parsed.targets);
+		} catch (err) {
+			throw new TypeError(`targets ${err.message}`);
+		}
+	}
+	const validateRetainedJournal = (relative, field) => {
+		if (
+			typeof relative !== "string" ||
+			!isPrivateGeneratedQuarantinePath(relative) ||
+			!relative
+				.split("/")
+				.some((segment) => /^\.stdd-cleanup-journal-[0-9a-f]{32}\.tmp$/.test(segment)) ||
+			!Object.hasOwn(files, relative)
+		) {
+			throw new TypeError(`${field} must name a listed retained cleanup-journal quarantine`);
+		}
+		return relative;
+	};
+	if (Object.hasOwn(parsed, "retainedCleanupJournal")) {
+		normalized.retainedCleanupJournal = validateRetainedJournal(
+			parsed.retainedCleanupJournal,
+			"retainedCleanupJournal",
+		);
+	}
+	if (Object.hasOwn(parsed, "retainedCleanupJournals")) {
+		if (
+			!Array.isArray(parsed.retainedCleanupJournals) ||
+			new Set(parsed.retainedCleanupJournals).size !== parsed.retainedCleanupJournals.length
+		) {
+			throw new TypeError("retainedCleanupJournals must be an array without duplicates");
+		}
+		normalized.retainedCleanupJournals = parsed.retainedCleanupJournals.map((relative, index) =>
+			validateRetainedJournal(relative, `retainedCleanupJournals[${index}]`),
+		);
+	}
+	return normalized;
+}
+
+/** Files recorded by the previous init, or an empty map when none exists. */
+export function readManifestFiles(targetDir) {
+	try {
+		return readManifestDocument(targetDir)?.files ?? Object.create(null);
+	} catch (err) {
+		fail(`.stdd/manifest.json ${err.message}`);
+	}
+}
+
+function readCleanupJournal(targetDir) {
+	const journalPath = resolveRepoPath(targetDir, CLEANUP_JOURNAL_REL, "cleanup journal path");
+	const parentPath = path.dirname(journalPath);
+	let before;
+	try {
+		before = fs.lstatSync(journalPath);
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+	let parentDescriptor = null;
+	let journalDescriptor = null;
+	let text;
+	try {
+		const parentBefore = fs.lstatSync(parentPath);
+		if (parentBefore.isSymbolicLink() || !parentBefore.isDirectory()) {
+			throw new Error("cleanup journal parent must be a non-symlinked directory");
+		}
+		parentDescriptor = fs.openSync(
+			parentPath,
+			fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW,
+		);
+		const parentOpened = fs.fstatSync(parentDescriptor);
+		if (!sameFileIdentity(parentBefore, parentOpened)) {
+			throw new Error("cleanup journal parent changed before it could be opened");
+		}
+		const descriptorPath = journalPath;
+		journalDescriptor = fs.openSync(descriptorPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+		const opened = fs.fstatSync(journalDescriptor);
+		const currentUid = typeof process.getuid === "function" ? process.getuid() : null;
+		const safeShape = (stat) =>
+			stat.isFile() &&
+			!stat.isSymbolicLink() &&
+			(stat.mode & 0o777) === 0o600 &&
+			stat.nlink === 1 &&
+			(currentUid === null || stat.uid === currentUid);
+		if (!safeShape(before) || !safeShape(opened) || !sameFileIdentity(before, opened)) {
+			throw new Error(
+				"cleanup journal must be one unchanged regular file owned by the current user, single-linked, and exactly mode 0600",
+			);
+		}
+		text = fs.readFileSync(journalDescriptor, "utf8");
+		const openedAfter = fs.fstatSync(journalDescriptor);
+		const after = fs.lstatSync(journalPath);
+		const parentAfter = fs.lstatSync(parentPath);
+		if (
+			!safeShape(openedAfter) ||
+			!safeShape(after) ||
+			!sameFileIdentity(opened, openedAfter) ||
+			!sameFileIdentity(opened, after) ||
+			!sameFileIdentity(parentOpened, parentAfter)
+		) {
+			throw new Error("cleanup journal or its parent changed while it was read");
+		}
+	} finally {
+		if (journalDescriptor !== null) {
+			try {
+				fs.closeSync(journalDescriptor);
+			} catch {}
+		}
+		if (parentDescriptor !== null) {
+			try {
+				fs.closeSync(parentDescriptor);
+			} catch {}
+		}
+	}
+	return validateNativeCleanupJournal(targetDir, JSON.parse(text));
+}
+
+const MANIFEST_QUARANTINE_BASENAME = /^\.stdd-cleanup-(?:journal-)?[0-9a-f]{32}\.tmp$/;
+const PRIVATE_GENERATED_QUARANTINE_ROOT = ".stdd/generated-quarantines";
+
+function privateQuarantineContainer(relative) {
+	const prefix = `${PRIVATE_GENERATED_QUARANTINE_ROOT}/`;
+	if (!relative.startsWith(prefix)) return null;
+	const remainder = relative.slice(prefix.length);
+	const separator = remainder.indexOf("/");
+	const container = separator === -1 ? remainder : remainder.slice(0, separator);
+	return MANIFEST_QUARANTINE_BASENAME.test(container) ? container : null;
+}
+
+function isPrivateGeneratedQuarantinePath(relative) {
+	const container = privateQuarantineContainer(relative);
+	if (!container) return false;
+	const suffix = relative.slice(`${PRIVATE_GENERATED_QUARANTINE_ROOT}/${container}/`.length);
+	return suffix.length > 0 && path.posix.basename(suffix) === suffix;
+}
+
+function newPrivateCleanupQuarantine(fileName, journal = false) {
+	const container = `.stdd-cleanup-${journal ? "journal-" : ""}${randomBytes(16).toString("hex")}.tmp`;
+	return `${PRIVATE_GENERATED_QUARANTINE_ROOT}/${container}/${fileName}`;
+}
+
+/**
+ * Read one manifest-tracked output without following a symlink or trusting a
+ * check-then-read path race. Callers receive a finding, never a filesystem
+ * exception. `missing` remains distinct so check keeps its established hint.
+ */
+function inspectManifestOutput(targetDir, file) {
+	let filePath;
+	try {
+		filePath = resolveWritableRepoPath(targetDir, file, `manifest path ${JSON.stringify(file)}`);
+	} catch (err) {
+		return { kind: "invalid", reason: err.message };
+	}
+
+	let before;
+	try {
+		before = fs.lstatSync(filePath);
+	} catch (err) {
+		if (err.code === "ENOENT") return { kind: "missing" };
+		return { kind: "invalid", reason: `metadata could not be read safely: ${err.message}` };
+	}
+	if (before.isSymbolicLink()) {
+		return { kind: "invalid", reason: "is a symlink, not a regular file" };
+	}
+	if (!before.isFile()) {
+		return {
+			kind: "invalid",
+			reason: before.isDirectory() ? "is a directory, not a regular file" : "is a non-regular file",
+		};
+	}
+
+	let descriptor = null;
+	let result;
+	try {
+		descriptor = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+		const opened = fs.fstatSync(descriptor);
+		if (!opened.isFile()) {
+			result = {
+				kind: "invalid",
+				reason: "was replaced during inspection with a non-regular file",
+			};
+		} else {
+			const bytes = fs.readFileSync(descriptor);
+			const after = fs.lstatSync(filePath);
+			// Re-run the path walk after reading: a parent directory may have
+			// become a symlink after the initial resolution.
+			resolveWritableRepoPath(targetDir, file, `manifest path ${JSON.stringify(file)}`);
+			const realRoot = fs.realpathSync(targetDir);
+			const realFile = fs.realpathSync(filePath);
+			const fromRoot = path.relative(realRoot, realFile);
+			const escaped =
+				fromRoot === ".." || fromRoot.startsWith(`..${path.sep}`) || path.isAbsolute(fromRoot);
+			const finalStat = fs.lstatSync(filePath);
+			if (
+				escaped ||
+				after.isSymbolicLink() ||
+				!after.isFile() ||
+				!sameFileIdentity(opened, after) ||
+				finalStat.isSymbolicLink() ||
+				!finalStat.isFile() ||
+				!sameFileIdentity(opened, finalStat)
+			) {
+				result = {
+					kind: "invalid",
+					reason: escaped
+						? "resolved outside the repository during inspection"
+						: "was replaced during inspection",
+				};
+			} else {
+				result = {
+					kind: "ok",
+					filePath,
+					bytes,
+					identity: opened,
+					realParentPath: path.dirname(realFile),
+				};
+			}
+		}
+	} catch (err) {
+		result = {
+			kind: "invalid",
+			reason:
+				err.code === "ENOENT"
+					? "was replaced or removed during inspection"
+					: `could not be read safely: ${err.message}`,
+		};
+	} finally {
+		if (descriptor !== null) {
+			try {
+				fs.closeSync(descriptor);
+			} catch (err) {
+				result = {
+					kind: "invalid",
+					reason: `could not be closed safely after reading: ${err.message}`,
+				};
+			}
+		}
+	}
+	return result;
+}
+
+/**
+ * Quarantine and remove a verified output through a held parent directory.
+ * Linux procfs gives pathname operations a stable dirfd-like anchor. Other
+ * runtimes fail closed and preserve the output for manual cleanup.
+ */
+function nativeIdentityMatches(identity, portable, legacyDevice, legacyFile) {
+	if (portable) {
+		return (
+			identity.version === portable.version &&
+			identity.platform === portable.platform &&
+			identity.volume === portable.volume &&
+			identity.fileId === portable.fileId &&
+			identity.kind === portable.kind
+		);
+	}
+	return (
+		identity.platform === "linux" && identity.volume === legacyDevice && identity.fileId === legacyFile
+	);
+}
+
+function recordedObservationMatches(current, recorded, kind) {
+	if (!recorded || !nativeIdentityMatches(current.identity, recorded.identity, null, null)) {
+		return false;
+	}
+	if (current.identity.kind !== kind) return false;
+	return ["owner", "permissions", "linkCount"].every(
+		(field) => !Object.hasOwn(recorded, field) || current[field] === recorded[field],
+	);
+}
+
+function nativeOwnerMatchesRoot(context, observation) {
+	return (
+		observation.identity.platform === "win32" || observation.owner === context.root.observation.owner
+	);
+}
+
+function quarantineObservation(file, parent) {
+	return { ...file, parentObservation: parent };
+}
+
+function stableQuarantineObservation(file, parent) {
+	const stable = ({ identity, owner, permissions, linkCount }) => ({
+		identity,
+		owner,
+		permissions,
+		linkCount,
+	});
+	return { ...stable(file), parentObservation: stable(parent) };
+}
+
+async function nativeOpenParent(context, relative, label) {
+	const parentRelative = path.posix.dirname(relative);
+	try {
+		return await openNativeRepoPath(context, parentRelative, label);
+	} catch (error) {
+		if (error.cause?.code === "not-found" || error.code === "not-found") return null;
+		throw error;
+	}
+}
+
+async function nativeInspectOutput(context, relative, expected = null) {
+	resolveRepoPath(context.rootPath, relative, `generated path ${JSON.stringify(relative)}`);
+	const parent = await nativeOpenParent(context, relative, `generated parent for ${relative}`);
+	if (!parent) return { kind: "missing" };
+	let file;
+	try {
+		file = await context.session.openChild(parent.cap, path.posix.basename(relative));
+	} catch (error) {
+		if (error.code === "not-found") return { kind: "missing", parent };
+		return {
+			kind: "invalid",
+			parent,
+			reason: error.code === "symlink-rejected" ? `unsafe symlink: ${error.message}` : error.message,
+		};
+	}
+	if (file.observation.identity.kind !== "file") {
+		return { kind: "invalid", parent, reason: "is not a non-symlinked regular file" };
+	}
+	try {
+		if (
+			file.observation.identity.platform === "win32" &&
+			file.observation.owner !== context.root.observation.owner
+		) {
+			await context.session.verifyPrivate(file.cap);
+		}
+		const bytes = await readNativeFile(context, file);
+		if (
+			expected &&
+			!nativeIdentityMatches(
+				file.observation.identity,
+				expected.fileIdentity,
+				expected.fileDev,
+				expected.fileIno,
+			)
+		) {
+			return { kind: "other", parent, file, bytes };
+		}
+		return { kind: "ok", parent, file, bytes };
+	} catch (error) {
+		return { kind: "invalid", parent, file, reason: error.message };
+	}
+}
+
+export async function readManifestDocumentWithCapabilities(context) {
+	const inspected = await nativeInspectOutput(context, ".stdd/manifest.json");
+	if (inspected.kind === "missing") return null;
+	if (inspected.kind !== "ok") {
+		throw new TypeError(`cannot be read safely: ${inspected.reason}`);
+	}
+	const observation = inspected.file.observation;
+	if (observation.linkCount !== "1" || !nativeOwnerMatchesRoot(context, observation)) {
+		throw new TypeError("must be single-linked and owned by the repository owner");
+	}
+	if (
+		observation.identity.platform !== "win32" &&
+		![0o600, 0o644].includes(Number(observation.permissions) & 0o777)
+	) {
+		throw new TypeError("must be mode 0600 or canonical VCS checkout mode 0644");
+	}
+	const manifest = parseManifestDocument(context.rootPath, inspected.bytes.toString("utf8"));
+	Object.defineProperty(manifest, NATIVE_MANIFEST_IDENTITY, {
+		value: observation.identity,
+	});
+	return manifest;
+}
+
+function validateNativeCleanupJournal(targetDir, parsed) {
+	if (
+		typeof parsed !== "object" ||
+		parsed === null ||
+		Array.isArray(parsed) ||
+		parsed.version !== 1 ||
+		!Array.isArray(parsed.entries) ||
+		parsed.entries.length === 0
+	) {
+		throw new Error("cleanup journal has an invalid schema");
+	}
+	for (const entry of parsed.entries) {
+		if (
+			typeof entry !== "object" ||
+			entry === null ||
+			!["planned", "quarantined", "unresolved"].includes(entry.phase) ||
+			typeof entry.source !== "string" ||
+			typeof entry.quarantine !== "string" ||
+			typeof entry.parentDev !== "string" ||
+			typeof entry.parentIno !== "string" ||
+			typeof entry.fileDev !== "string" ||
+			typeof entry.fileIno !== "string" ||
+			typeof entry.keepSource !== "boolean" ||
+			typeof entry.reason !== "string" ||
+			entry.source === entry.quarantine ||
+			!MANIFEST_HASH_PATTERN.test(entry.hash)
+		) {
+			throw new Error("cleanup journal has an invalid entry");
+		}
+		for (const [field, kind] of [
+			["parentIdentity", "directory"],
+			["fileIdentity", "file"],
+			["quarantineParentIdentity", "directory"],
+		]) {
+			if (!Object.hasOwn(entry, field)) continue;
+			const identity = entry[field];
+			if (
+				typeof identity !== "object" ||
+				identity === null ||
+				identity.version !== 2 ||
+				typeof identity.platform !== "string" ||
+				typeof identity.volume !== "string" ||
+				typeof identity.fileId !== "string" ||
+				identity.kind !== kind
+			) {
+				throw new Error("cleanup journal has an invalid portable identity");
+			}
+		}
+		const source = resolveRepoPath(targetDir, entry.source, "cleanup journal source");
+		const quarantine = resolveRepoPath(targetDir, entry.quarantine, "cleanup journal quarantine");
+		if (
+			path.dirname(source) !== path.dirname(quarantine) &&
+			!Object.hasOwn(entry, "quarantineParentIdentity") &&
+			entry.phase !== "planned"
+		) {
+			throw new Error("cleanup journal entry paths must share one parent");
+		}
+		if (
+			!MANIFEST_QUARANTINE_BASENAME.test(path.posix.basename(entry.quarantine)) &&
+			!isPrivateGeneratedQuarantinePath(entry.quarantine)
+		) {
+			throw new Error("cleanup journal has an invalid quarantine name");
+		}
+	}
+	return parsed;
+}
+
+async function readCleanupJournalNative(context) {
+	const inspected = await nativeInspectOutput(context, CLEANUP_JOURNAL_REL);
+	if (inspected.kind === "missing") return null;
+	if (inspected.kind !== "ok") {
+		throw new Error(`cleanup journal could not be read safely: ${inspected.reason}`);
+	}
+	const observation = inspected.file.observation;
+	if (observation.linkCount !== "1" || !nativeOwnerMatchesRoot(context, observation)) {
+		throw new Error("cleanup journal must be one unchanged regular file owned by the current user");
+	}
+	if (observation.identity.platform !== "win32" && (Number(observation.permissions) & 0o777) !== 0o600) {
+		throw new Error("cleanup journal must be exactly mode 0600");
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(inspected.bytes.toString("utf8"));
+	} catch (error) {
+		throw new Error(`cleanup journal is not valid JSON: ${error.message}`);
+	}
+	const validated = validateNativeCleanupJournal(context.rootPath, parsed);
+	Object.defineProperty(validated, NATIVE_JOURNAL_IDENTITY, {
+		value: observation.identity,
+		writable: true,
+	});
+	return validated;
+}
+
+async function writeCleanupJournalNative(context, journal) {
+	const published = await publishNativeRepoFile(
+		context,
+		CLEANUP_JOURNAL_REL,
+		`${JSON.stringify(journal, null, "\t")}\n`,
+		{
+			mode: 0o600,
+			tempPrefix: ".cleanup-journal-",
+			directoryMode: 0o700,
+			expectedTarget: journal[NATIVE_JOURNAL_IDENTITY] ?? null,
+		},
+	);
+	if (Object.hasOwn(journal, NATIVE_JOURNAL_IDENTITY)) {
+		journal[NATIVE_JOURNAL_IDENTITY] = published.observation.identity;
+	} else {
+		Object.defineProperty(journal, NATIVE_JOURNAL_IDENTITY, {
+			value: published.observation.identity,
+			writable: true,
+		});
+	}
+}
+
+async function inspectCleanupEntryStateNative(context, entry) {
+	try {
+		const source = await nativeInspectOutput(context, entry.source, entry);
+		const quarantine = await nativeInspectOutput(context, entry.quarantine, entry);
+		const sourceParent = source.parent;
+		const quarantineParent = quarantine.parent;
+		if (
+			!sourceParent ||
+			!nativeIdentityMatches(
+				sourceParent.observation.identity,
+				entry.parentIdentity,
+				entry.parentDev,
+				entry.parentIno,
+			)
+		) {
+			throw new Error("logical parent no longer maps to the journaled directory identity");
+		}
+		if (
+			entry.quarantineParentIdentity &&
+			(!quarantineParent ||
+				!nativeIdentityMatches(
+					quarantineParent.observation.identity,
+					entry.quarantineParentIdentity,
+					entry.quarantineParentIdentity.volume,
+					entry.quarantineParentIdentity.fileId,
+				))
+		) {
+			throw new Error("quarantine parent no longer maps to the journaled directory identity");
+		}
+		const exact = (candidate) =>
+			candidate.kind === "ok" &&
+			nativeIdentityMatches(
+				candidate.file.observation.identity,
+				entry.fileIdentity,
+				entry.fileDev,
+				entry.fileIno,
+			) &&
+			sha256(candidate.bytes) === entry.hash;
+		if (exact(quarantine)) {
+			return {
+				kind: "quarantined",
+				keepSource: source.kind !== "missing",
+				sourceParent,
+				quarantineParent,
+				quarantine,
+			};
+		}
+		if (exact(source) && quarantine.kind === "missing") {
+			return { kind: "restored", sourceParent, quarantineParent, source };
+		}
+		throw new Error(
+			`cannot prove the journaled file identity at either path (source=${source.kind}, quarantine=${quarantine.kind})`,
+		);
+	} catch (error) {
+		return { kind: "unresolved", reason: error.message };
+	}
+}
+
+async function rollbackCleanupJournalNative(context, journal) {
+	const unresolved = [];
+	for (const entry of [...journal.entries].reverse()) {
+		const state = await inspectCleanupEntryStateNative(context, entry);
+		if (state.kind === "restored") continue;
+		if (state.kind !== "quarantined" || state.keepSource) {
+			entry.phase = "unresolved";
+			entry.reason =
+				state.kind === "unresolved"
+					? state.reason
+					: "rollback found both the source and quarantine occupied";
+			unresolved.push(`${entry.source}: ${entry.reason}`);
+			continue;
+		}
+		try {
+			await context.session.rename({
+				fromParent: state.quarantineParent.cap,
+				from: path.posix.basename(entry.quarantine),
+				expected: entry.fileIdentity ?? state.quarantine.file.observation.identity,
+				toParent: state.sourceParent.cap,
+				to: path.posix.basename(entry.source),
+				replace: "never",
+			});
+			await context.session.flush(
+				state.sourceParent.cap,
+				"namespace",
+				state.sourceParent.observation.identity,
+			);
+			if (state.quarantineParent.cap !== state.sourceParent.cap) {
+				await context.session.flush(
+					state.quarantineParent.cap,
+					"namespace",
+					state.quarantineParent.observation.identity,
+				);
+			}
+			await verifyNativeRepoDirectory(
+				context,
+				path.posix.dirname(entry.source),
+				state.sourceParent.observation.identity,
+				"cleanup rollback parent",
+			);
+			if (entry.quarantineParentIdentity) {
+				await verifyNativeRepoDirectory(
+					context,
+					path.posix.dirname(entry.quarantine),
+					state.quarantineParent.observation.identity,
+					"cleanup rollback quarantine",
+				);
+			}
+			const restored = await inspectCleanupEntryStateNative(context, entry);
+			if (restored.kind !== "restored") throw new Error(restored.reason ?? restored.kind);
+		} catch (error) {
+			entry.phase = "unresolved";
+			entry.reason = `capability-bound rollback failed: ${error.message}`;
+			unresolved.push(`${entry.source}: ${entry.reason}`);
+		}
+	}
+	if (unresolved.length > 0) await writeCleanupJournalNative(context, journal).catch(() => {});
+	return unresolved;
+}
+
+async function clearCleanupJournalNative(context, retainedRelative) {
+	const inspected = await nativeInspectOutput(context, CLEANUP_JOURNAL_REL);
+	if (inspected.kind === "missing") return null;
+	if (inspected.kind !== "ok")
+		throw new Error(`cleanup journal changed before clear: ${inspected.reason}`);
+	const retainedParent = await openOrCreateNativeRepoDirectory(
+		context,
+		path.posix.dirname(retainedRelative),
+		{ mode: 0o700, label: "retained cleanup journal parent" },
+	);
+	if (
+		retainedParent.observation.identity.platform !== "win32" &&
+		(Number(retainedParent.observation.permissions) & 0o777) !== 0o700
+	) {
+		throw new Error("retained cleanup journal parent must be owner-private mode 0700");
+	}
+	if (!nativeOwnerMatchesRoot(context, retainedParent.observation)) {
+		throw new Error("retained cleanup journal parent must be owned by the repository owner");
+	}
+	try {
+		await context.session.openChild(retainedParent.cap, path.posix.basename(retainedRelative));
+		throw new Error("retained cleanup journal basename is already occupied");
+	} catch (error) {
+		if (error?.code !== "not-found") throw error;
+	}
+	const zeroes = Buffer.alloc(inspected.bytes.length);
+	let journalMutated = false;
+	try {
+		journalMutated = true;
+		await writeNativeFileContent(context, inspected.file, zeroes);
+		await context.session.truncate(inspected.file.cap, 0, inspected.file.observation.identity);
+		await context.session.flush(inspected.file.cap, "all", inspected.file.observation.identity);
+		await context.session.rename({
+			fromParent: inspected.parent.cap,
+			from: path.posix.basename(CLEANUP_JOURNAL_REL),
+			expected: inspected.file.observation.identity,
+			toParent: retainedParent.cap,
+			to: path.posix.basename(retainedRelative),
+			replace: "never",
+		});
+		await context.session.flush(retainedParent.cap, "namespace", retainedParent.observation.identity);
+		await context.session.flush(
+			inspected.parent.cap,
+			"namespace",
+			inspected.parent.observation.identity,
+		);
+		await verifyNativeRepoDirectory(
+			context,
+			path.posix.dirname(retainedRelative),
+			retainedParent.observation.identity,
+			"retained cleanup journal parent",
+		);
+		await verifyNativeRepoDirectory(
+			context,
+			path.posix.dirname(CLEANUP_JOURNAL_REL),
+			inspected.parent.observation.identity,
+			"cleanup journal source parent",
+		);
+	} catch (error) {
+		if (journalMutated) error.mutation = "committed";
+		throw error;
+	}
+	return retainedRelative;
+}
+
+function cleanupJournalCommittedNative(manifest, journal) {
+	if (!manifest) return false;
+	return journal.entries.every(
+		(entry) =>
+			entry.phase === "quarantined" &&
+			Object.hasOwn(manifest.files, entry.quarantine) &&
+			manifest.files[entry.quarantine] === entry.hash &&
+			(entry.keepSource
+				? manifest.files[entry.source] === entry.hash
+				: !Object.hasOwn(manifest.files, entry.source)),
+	);
+}
+
+export async function recoverCleanupJournalWithCapabilities(context) {
+	let journal;
+	try {
+		journal = await readCleanupJournalNative(context);
+	} catch (error) {
+		const manifest = await readManifestDocumentWithCapabilities(context);
+		const active = await nativeInspectOutput(context, CLEANUP_JOURNAL_REL);
+		const retained = [
+			...(manifest?.retainedCleanupJournals ?? []),
+			...(manifest?.retainedCleanupJournal ? [manifest.retainedCleanupJournal] : []),
+		]
+			.reverse()
+			.find((relative) => {
+				const recorded = manifest?.quarantineIdentities?.[relative];
+				const expected = recorded?.identity ?? recorded;
+				return (
+					manifest?.files?.[relative] === sha256(Buffer.alloc(0)) &&
+					active.kind === "ok" &&
+					expected &&
+					nativeIdentityMatches(
+						active.file.observation.identity,
+						expected,
+						expected.volume,
+						expected.fileId,
+					)
+				);
+			});
+		if (!retained) throw error;
+		await clearCleanupJournalNative(context, retained);
+		return [];
+	}
+	if (!journal) return [];
+	const manifest = await readManifestDocumentWithCapabilities(context);
+	if (cleanupJournalCommittedNative(manifest, journal)) {
+		const states = await Promise.all(
+			journal.entries.map((entry) => inspectCleanupEntryStateNative(context, entry)),
+		);
+		const invalid = states
+			.map((state, index) => ({ state, entry: journal.entries[index] }))
+			.filter(
+				({ state, entry }) => state.kind !== "quarantined" || state.keepSource !== entry.keepSource,
+			);
+		if (invalid.length > 0) {
+			throw new Error(
+				`${CLEANUP_JOURNAL_REL} has unresolved cleanup state — ${invalid
+					.map(({ state, entry }) => `${entry.source}: ${state.reason ?? state.kind}`)
+					.join("; ")}`,
+			);
+		}
+		const retained =
+			manifest.retainedCleanupJournals?.at(-1) ??
+			manifest.retainedCleanupJournal ??
+			newPrivateCleanupQuarantine("cleanup-transaction.tombstone", true);
+		await clearCleanupJournalNative(context, retained);
+		return [];
+	}
+	const unresolved = await rollbackCleanupJournalNative(context, journal);
+	if (unresolved.length > 0) {
+		throw new Error(`${CLEANUP_JOURNAL_REL} has unresolved cleanup state — ${unresolved.join("; ")}`);
+	}
+	// A rolled-back WAL is still retired rather than pathname-deleted. It is
+	// not broadly discoverable; the next successful manifest publication
+	// records this exact retained basename.
+	const retained = newPrivateCleanupQuarantine("cleanup-transaction.tombstone", true);
+	await clearCleanupJournalNative(context, retained);
+	return [retained];
+}
+
+/**
+ * Capability-native generated retirement and manifest publication. This is
+ * the async API shared by init/configure and the other mutation subsystems.
+ */
+export async function finalizeGeneratedFilesWithCapabilities(
+	context,
+	{
+		oldFiles,
+		oldQuarantineIdentities = Object.create(null),
+		initialQuarantineIdentities = Object.create(null),
+		generated,
+		targets,
+		retainedCleanupJournals = [],
+		legacyRetainedCleanupJournal = null,
+		expectedManifestIdentity = null,
+		retireOnlyFiles = [],
+	},
+) {
+	const journal = { version: 1, entries: [] };
+	const retireOnly = new Set(retireOnlyFiles);
+	const quarantineIdentities = Object.assign(Object.create(null), initialQuarantineIdentities);
+	let manifestRenamePossible = false;
+	let manifestDurable = false;
+	try {
+		for (const [file, hash] of Object.entries(oldFiles)) {
+			if (Object.hasOwn(generated, file)) continue;
+			const inspected = await nativeInspectOutput(context, file);
+			if (inspected.kind === "missing") continue;
+			if (inspected.kind !== "ok") {
+				if (retireOnly.has(file)) {
+					throw new Error(
+						`Preserved user-owned ${file}; it could not be safely revalidated for WAL-backed retirement (${inspected.reason})`,
+					);
+				}
+				generated[file] = hash;
+				console.error(
+					`Preserved unsafe formerly generated output ${file}; it cannot be safely inspected (${inspected.reason}) and remains manifest-tracked until removed or relocated`,
+				);
+				continue;
+			}
+			if (
+				(MANIFEST_QUARANTINE_BASENAME.test(path.posix.basename(file)) ||
+					isPrivateGeneratedQuarantinePath(file)) &&
+				sha256(inspected.bytes) === hash
+			) {
+				const quarantineModeSafe =
+					inspected.parent.observation.identity.platform === "win32" ||
+					(Number(inspected.parent.observation.permissions) & 0o777) === 0o700;
+				if (
+					!quarantineModeSafe ||
+					!nativeOwnerMatchesRoot(context, inspected.parent.observation) ||
+					!nativeOwnerMatchesRoot(context, inspected.file.observation) ||
+					inspected.file.observation.linkCount !== "1"
+				) {
+					generated[file] = hash;
+					quarantineIdentities[file] =
+						oldQuarantineIdentities[file] ??
+						quarantineObservation(inspected.file.observation, inspected.parent.observation);
+					console.error(
+						`Preserved unsafe retained quarantine ${file}; its owner, mode, or link count no longer matches the durable quarantine contract`,
+					);
+					continue;
+				}
+				const expected = oldQuarantineIdentities[file] ?? null;
+				if (
+					expected &&
+					(!recordedObservationMatches(inspected.file.observation, expected, "file") ||
+						(expected.parentObservation &&
+							!recordedObservationMatches(
+								inspected.parent.observation,
+								expected.parentObservation,
+								"directory",
+							)))
+				) {
+					generated[file] = hash;
+					quarantineIdentities[file] = oldQuarantineIdentities[file];
+					console.error(
+						`Preserved replaced retained quarantine ${file}; its bytes match but durable parent/file metadata does not`,
+					);
+					continue;
+				}
+				generated[file] = hash;
+				quarantineIdentities[file] =
+					expected ?? quarantineObservation(inspected.file.observation, inspected.parent.observation);
+				continue;
+			}
+			if (sha256(inspected.bytes) !== hash) {
+				if (retireOnly.has(file)) {
+					throw new Error(`Preserved user-owned ${file}; it changed before WAL-backed retirement`);
+				}
+				generated[file] = hash;
+				console.error(
+					`Preserved modified formerly generated file ${file}; it remains manifest-tracked and stale until removed or relocated`,
+				);
+				continue;
+			}
+			if (
+				!nativeOwnerMatchesRoot(context, inspected.file.observation) ||
+				inspected.file.observation.linkCount !== "1"
+			) {
+				if (retireOnly.has(file)) {
+					throw new Error(
+						`Preserved user-owned ${file}; owner or link count is not trusted for WAL-backed retirement`,
+					);
+				}
+				generated[file] = hash;
+				console.error(
+					`Preserved unsafe formerly generated output ${file}; owner or link count is not trusted and it remains manifest-tracked until removed or relocated`,
+				);
+				continue;
+			}
+			const quarantine = newPrivateCleanupQuarantine(path.posix.basename(file));
+			const parentIdentity = inspected.parent.observation.identity;
+			const fileIdentity = inspected.file.observation.identity;
+			const entry = {
+				source: file,
+				quarantine,
+				hash,
+				parentDev: parentIdentity.volume,
+				parentIno: parentIdentity.fileId,
+				fileDev: fileIdentity.volume,
+				fileIno: fileIdentity.fileId,
+				phase: "planned",
+				keepSource: false,
+				reason: "",
+				parentIdentity,
+				fileIdentity,
+				parentObservation: inspected.parent.observation,
+				fileObservation: inspected.file.observation,
+			};
+			journal.entries.push(entry);
+			await writeCleanupJournalNative(context, journal);
+			const quarantineParent = await openOrCreateNativeRepoDirectory(
+				context,
+				path.posix.dirname(quarantine),
+				{ mode: 0o700, label: "generated cleanup quarantine" },
+			);
+			if (
+				quarantineParent.observation.identity.platform !== "win32" &&
+				(Number(quarantineParent.observation.permissions) & 0o777) !== 0o700
+			) {
+				throw new Error("generated cleanup quarantine must be owner-private mode 0700");
+			}
+			if (!nativeOwnerMatchesRoot(context, quarantineParent.observation)) {
+				throw new Error("generated cleanup quarantine must be owned by the repository owner");
+			}
+			entry.quarantineParentIdentity = quarantineParent.observation.identity;
+			entry.quarantineParentObservation = quarantineParent.observation;
+			await writeCleanupJournalNative(context, journal);
+			try {
+				await context.session.rename({
+					fromParent: inspected.parent.cap,
+					from: path.posix.basename(file),
+					expected: fileIdentity,
+					toParent: quarantineParent.cap,
+					to: path.posix.basename(quarantine),
+					replace: "never",
+				});
+				await context.session.flush(
+					inspected.parent.cap,
+					"namespace",
+					inspected.parent.observation.identity,
+				);
+				await context.session.flush(
+					quarantineParent.cap,
+					"namespace",
+					quarantineParent.observation.identity,
+				);
+				await verifyNativeRepoDirectory(
+					context,
+					path.posix.dirname(file),
+					inspected.parent.observation.identity,
+					"generated cleanup parent",
+				);
+				await verifyNativeRepoDirectory(
+					context,
+					path.posix.dirname(quarantine),
+					quarantineParent.observation.identity,
+					"generated cleanup quarantine",
+				);
+			} catch (error) {
+				entry.phase = "unresolved";
+				entry.reason = `generated cleanup quarantine failed: ${error.message}`;
+				await writeCleanupJournalNative(context, journal).catch(() => {});
+				throw error;
+			}
+			const state = await inspectCleanupEntryStateNative(context, entry);
+			if (state.kind !== "quarantined") {
+				entry.phase = "unresolved";
+				entry.reason = state.reason ?? "cleanup did not retain the exact journaled identity";
+				await writeCleanupJournalNative(context, journal).catch(() => {});
+				throw new Error(entry.reason);
+			}
+			entry.phase = "quarantined";
+			entry.keepSource = state.keepSource;
+			await writeCleanupJournalNative(context, journal);
+			if (retireOnly.has(file) && state.keepSource) {
+				entry.phase = "unresolved";
+				entry.reason = "a replacement occupied the user-owned source during WAL-backed retirement";
+				await writeCleanupJournalNative(context, journal).catch(() => {});
+				throw new Error(`${file}: ${entry.reason}`);
+			}
+			generated[quarantine] = hash;
+			quarantineIdentities[quarantine] = quarantineObservation(
+				state.quarantine.file.observation,
+				state.quarantineParent.observation,
+			);
+			if (state.keepSource) generated[file] = hash;
+			console.log(
+				`Quarantined ${file} as ${quarantine} (no longer loaded by this profile; retained for identity-safe cleanup)`,
+			);
+		}
+
+		const retainedCleanupJournal =
+			journal.entries.length > 0
+				? newPrivateCleanupQuarantine("cleanup-transaction.tombstone", true)
+				: null;
+		const allRetainedCleanupJournals = [
+			...new Set([
+				...retainedCleanupJournals,
+				...(legacyRetainedCleanupJournal ? [legacyRetainedCleanupJournal] : []),
+				...(retainedCleanupJournal ? [retainedCleanupJournal] : []),
+			]),
+		];
+		const retainedCleanupParent = retainedCleanupJournal
+			? await openOrCreateNativeRepoDirectory(context, path.posix.dirname(retainedCleanupJournal), {
+					mode: 0o700,
+					label: "retained cleanup journal parent",
+				})
+			: null;
+		for (const relative of allRetainedCleanupJournals) {
+			// Existing retained paths were already classified by the old-files
+			// loop above. In particular, operator-removed tombstones stay removed
+			// instead of being resurrected as missing manifest entries.
+			if (relative !== retainedCleanupJournal && Object.hasOwn(oldFiles, relative)) continue;
+			generated[relative] = sha256(Buffer.alloc(0));
+			if (relative !== retainedCleanupJournal) {
+				const retained = await nativeInspectOutput(context, relative);
+				if (retained.kind !== "ok" || retained.bytes.length !== 0) {
+					throw new Error(`retained cleanup journal ${relative} changed before publication`);
+				}
+				quarantineIdentities[relative] = quarantineObservation(
+					retained.file.observation,
+					retained.parent.observation,
+				);
+			}
+		}
+		const publishedRetainedCleanupJournals = allRetainedCleanupJournals.filter((relative) =>
+			Object.hasOwn(generated, relative),
+		);
+		if (retainedCleanupJournal) {
+			const cleanupJournal = await nativeInspectOutput(context, CLEANUP_JOURNAL_REL);
+			if (cleanupJournal.kind !== "ok") {
+				throw new Error("cleanup journal changed before retained identity publication");
+			}
+			quarantineIdentities[retainedCleanupJournal] = stableQuarantineObservation(
+				cleanupJournal.file.observation,
+				retainedCleanupParent.observation,
+			);
+		}
+		const manifest = {
+			generatedBy: "stdd",
+			version: VERSION,
+			files: generated,
+			targets: {
+				tools: targets.tools,
+				ci: targets.ci,
+				hooks: targets.hooks,
+				sessionHook: targets.sessionHook,
+				stopHook: targets.stopHook,
+			},
+			...(Object.keys(quarantineIdentities).length > 0 ? { quarantineIdentities } : {}),
+			...(legacyRetainedCleanupJournal && Object.hasOwn(generated, legacyRetainedCleanupJournal)
+				? { retainedCleanupJournal: legacyRetainedCleanupJournal }
+				: {}),
+			...(publishedRetainedCleanupJournals.length > 0
+				? { retainedCleanupJournals: publishedRetainedCleanupJournals }
+				: {}),
+		};
+		try {
+			await publishNativeRepoFile(
+				context,
+				".stdd/manifest.json",
+				`${JSON.stringify(manifest, null, "\t")}\n`,
+				{
+					mode: 0o600,
+					tempPrefix: ".manifest-",
+					directoryMode: 0o700,
+					expectedTarget: expectedManifestIdentity,
+				},
+			);
+		} catch (error) {
+			manifestRenamePossible = error.mutation === "possible" || error.mutation === "committed";
+			throw error;
+		}
+		manifestDurable = true;
+		if (retainedCleanupJournal) {
+			await clearCleanupJournalNative(context, retainedCleanupJournal);
+		}
+	} catch (error) {
+		const unresolved = [];
+		let rolledBackForRecovery = false;
+		if (journal.entries.length > 0) {
+			if (
+				journal.entries.some((entry) => entry.phase === "unresolved") ||
+				manifestRenamePossible ||
+				manifestDurable
+			) {
+				unresolved.push(
+					manifestDurable
+						? "manifest publication is durable but cleanup journal settlement did not complete"
+						: manifestRenamePossible
+							? "manifest publication crossed an indeterminate mutation boundary"
+							: "cleanup settlement is unresolved",
+				);
+			} else {
+				unresolved.push(...(await rollbackCleanupJournalNative(context, journal)));
+				rolledBackForRecovery = unresolved.length === 0;
+			}
+			if (unresolved.length > 0) {
+				throw new Error(
+					`${error.message}; ${CLEANUP_JOURNAL_REL} remains for recovery — ${unresolved.join("; ")}`,
+					{ cause: error },
+				);
+			}
+			if (rolledBackForRecovery) {
+				throw new Error(
+					`${error.message}; ${CLEANUP_JOURNAL_REL} remains for recovery after capability-bound rollback`,
+					{ cause: error },
+				);
+			}
+		}
+		throw error;
+	}
+}
+
+/**
+ * Retire obsolete generated outputs and durably publish the replacement manifest.
+ * Mutates `generated` with preserved/quarantined entries; failures terminate through `fail`.
+ */
+const NO_PROJECT_LOG_METHOD_PREAMBLE = `# Repository policy: no project log
+
+This repository sets \`projectLog.enabled\` to \`false\`. It does not use a
+project log. Do not create or search dated decision, design, or deferred-work
+archives. Keep current behavior in canonical docs; use PR descriptions and git
+history for rationale and decisions.
+
+This repository policy overrides generic project-log examples later in this
+method.
+
+---
+
+`;
+
+export function renderInstalledMethod(source, projectLogEnabled) {
+	return projectLogEnabled ? source : `${NO_PROJECT_LOG_METHOD_PREAMBLE}${source}`;
+}
+
+/** Managed outputs that remain discoverable even when a partial init never
+ * published its manifest, or an older buggy cleanup forgot one. */
+function discoverGeneratedOutputs(targetDir) {
+	const found = new Set();
+	const addIfPresent = (relative) => {
+		const candidate = path.join(targetDir, relative);
+		try {
+			fs.lstatSync(candidate);
+			found.add(relative);
+		} catch (err) {
+			if (err.code !== "ENOENT") found.add(relative);
+		}
+	};
+
+	addIfPresent(".stdd/method.md");
+	for (const adapter of Object.values(AGENT_ADAPTERS)) addIfPresent(adapter.snippetFile);
+	const shippedPlaybooks = loadPlaybooks();
+	const reservedSkillNames = new Set([
+		...shippedPlaybooks.map((playbook) => playbook.meta.name),
+		...loadLocalPlaybooks(targetDir).map((playbook) => playbook.meta.name),
+	]);
+	for (const playbook of shippedPlaybooks) addIfPresent(`.stdd/playbooks/${playbook.file}`);
+	for (const adapter of Object.values(CI_ADAPTERS)) {
+		if (adapter.outputFile) addIfPresent(adapter.outputFile);
+	}
+
+	for (const adapter of Object.values(AGENT_ADAPTERS)) {
+		// Shipped and validated local skill names reserve generated-output paths. Surface an
+		// exact final object even when it cannot be opened as a stamped regular
+		// file; absence remains normal, and unrelated user skill names are
+		// still considered only when their contents carry the generated stamp.
+		for (const name of reservedSkillNames) {
+			addIfPresent(`${adapter.skillRoot}/${name}/SKILL.md`);
+		}
+		const skillsRoot = path.join(targetDir, adapter.skillRoot);
+		let entries;
+		try {
+			entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+		} catch (err) {
+			if (err.code !== "ENOENT") found.add(adapter.skillRoot);
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const relative = `${adapter.skillRoot}/${entry.name}/SKILL.md`;
+			const skillPath = path.join(targetDir, relative);
+			try {
+				if (
+					fs.lstatSync(skillPath).isFile() &&
+					/<!-- generated by stdd v[^\s]+ —/u.test(fs.readFileSync(skillPath, "utf8"))
+				) {
+					found.add(relative);
+				}
+			} catch {
+				// A broken generated-looking skill path is still surfaced when
+				// the manifest names it; unknown user-owned entries stay alone.
+			}
+		}
+	}
+	return [...found].sort();
+}
+
+/**
+ * Generated-file drift, as `{ file, message }` findings. With a manifest
+ * (written by `stdd init`), every generated file is verified by content
+ * hash and managed outputs may not exist outside its inventory. Without a
+ * manifest, any generated output is a failed or legacy partial install that
+ * must be regenerated before it can be trusted.
+ */
+export function scanGeneratedDrift(targetDir, config) {
+	const stale = [];
+	try {
+		const cleanupJournal = readCleanupJournal(targetDir);
+		if (cleanupJournal) {
+			stale.push({
+				file: CLEANUP_JOURNAL_REL,
+				message:
+					"pending generated-output cleanup transaction — run stdd init to recover or inspect its unresolved paths",
+			});
+		}
+	} catch (err) {
+		stale.push({
+			file: CLEANUP_JOURNAL_REL,
+			message: `invalid cleanup transaction journal (${err.message}) — inspect it before running stdd init`,
+		});
+	}
+	let manifest;
+	try {
+		manifest = readManifestDocument(targetDir);
+	} catch (err) {
+		return [
+			...stale,
+			{
+				file: ".stdd/manifest.json",
+				message: `${err.message} — re-run stdd init`,
+			},
+		];
+	}
+	if (manifest) {
+		let installedMethodBytes = null;
+		if (manifest.version !== VERSION) {
+			stale.push({
+				file: ".stdd/manifest.json",
+				message: `written by stdd v${manifest.version}, CLI is v${VERSION} — re-run stdd init`,
+			});
+		}
+		for (const [file, hash] of Object.entries(manifest.files)) {
+			const inspected = inspectManifestOutput(targetDir, file);
+			if (inspected.kind === "missing") {
+				stale.push({
+					file,
+					message: "listed in .stdd/manifest.json but missing — re-run stdd init",
+				});
+			} else if (inspected.kind === "invalid") {
+				stale.push({
+					file,
+					message: `cannot be safely inspected as a readable regular file (${inspected.reason}) — remove it or re-run stdd init`,
+				});
+			} else {
+				if (file === ".stdd/method.md") installedMethodBytes = inspected.bytes;
+				if (sha256(inspected.bytes) === hash) continue;
+				stale.push({
+					file,
+					message: "edited by hand or stale — re-run stdd init",
+				});
+			}
+		}
+		for (const file of discoverGeneratedOutputs(targetDir)) {
+			if (!Object.hasOwn(manifest.files, file)) {
+				stale.push({
+					file,
+					message:
+						"looks generated by stdd but is not listed in .stdd/manifest.json — remove it or re-run stdd init",
+				});
+			}
+		}
+		if (installedMethodBytes !== null) {
+			const canonicalMethod = Buffer.from(
+				renderInstalledMethod(
+					fs.readFileSync(path.join(PKG_ROOT, "method", "README.md"), "utf8"),
+					config.projectLog.enabled,
+				),
+			);
+			if (!installedMethodBytes.equals(canonicalMethod)) {
+				stale.push({
+					file: ".stdd/method.md",
+					message: "does not match the canonical method shipped by this CLI — re-run stdd init",
+				});
+			}
+		}
+		const automationRunner = isStddSourceCheckout(targetDir) ? SOURCE_RUNNER : NPM_RUNNER;
+		for (const tool of manifest.targets?.tools ?? []) {
+			const adapter = getAgentAdapter(tool);
+			const inspected = inspectManifestOutput(targetDir, adapter.snippetFile);
+			if (inspected.kind !== "ok") continue;
+			const expectedSnippet = Buffer.from(
+				renderAgentInstructions({
+					adapter,
+					stamp: STAMP,
+					npmRunner: automationRunner,
+					crossCli: config.capabilities.crossCli,
+					projectLogEnabled: config.projectLog.enabled,
+				}),
+			);
+			if (
+				!inspected.bytes.equals(expectedSnippet) &&
+				!stale.some((finding) => finding.file === adapter.snippetFile)
+			) {
+				stale.push({
+					file: adapter.snippetFile,
+					message: "does not match the current repository policy — re-run stdd init",
+				});
+			}
+		}
+		return stale;
+	}
+
+	const partial = discoverGeneratedOutputs(targetDir);
+	if (partial.length > 0) {
+		for (const file of partial) {
+			const inspected = inspectManifestOutput(targetDir, file);
+			if (inspected.kind === "invalid") {
+				stale.push({
+					file,
+					message: `unsafe object occupies an exact generated-output path (${inspected.reason}) — remove it or re-run stdd init`,
+				});
+			}
+		}
+		stale.push({
+			file: ".stdd/manifest.json",
+			message: `is missing for a partial install with generated output ${partial[0]} — re-run stdd init`,
+		});
+	}
+	return stale;
+}
+
+/**
+ * Inventory only durable, provenance-backed generated quarantines. This is
+ * intentionally not a filesystem scan: an unrelated temp-looking basename is
+ * never attributed to STDD without a manifest or cleanup-WAL record.
+ */
+export function generatedQuarantineInventory(targetDir) {
+	const found = new Map();
+	try {
+		const manifest = readManifestDocument(targetDir);
+		if (manifest) {
+			for (const relative of Object.keys(manifest.files)) {
+				if (
+					MANIFEST_QUARANTINE_BASENAME.test(path.posix.basename(relative)) ||
+					isPrivateGeneratedQuarantinePath(relative)
+				) {
+					found.set(relative, "manifest");
+				}
+			}
+			for (const relative of [
+				manifest.retainedCleanupJournal,
+				...(Array.isArray(manifest.retainedCleanupJournals) ? manifest.retainedCleanupJournals : []),
+			]) {
+				if (
+					typeof relative === "string" &&
+					(MANIFEST_QUARANTINE_BASENAME.test(path.posix.basename(relative)) ||
+						isPrivateGeneratedQuarantinePath(relative))
+				) {
+					found.set(relative, "manifest");
+				}
+			}
+		}
+	} catch {
+		// The ordinary manifest finding is the actionable diagnostic. Never
+		// infer quarantine ownership from a malformed document.
+	}
+	try {
+		const journal = readCleanupJournal(targetDir);
+		for (const entry of journal?.entries ?? []) {
+			found.set(entry.quarantine, "cleanup journal");
+		}
+	} catch {
+		// The pending/malformed journal finding is reported separately.
+	}
+	return [...found]
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([relative, provenance]) => ({ relative, provenance }));
+}