backend-skeleton 1.0.0-beta.9 → 1.0.0

package/lib/cli.mjs

@@ -85,10 +85,29 @@ export const COMMANDS = {
 	// D-gate-export: unlike `gate show`, always feature-scoped -- the whole point is one feature's
 	// own evidence trail across all 5 gates, not a single gate/repo-level snapshot.
 	'gate export': {
-		usage: 'bskel gate export --feature <id> [--out <path>] [--json]',
+		usage: 'bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath>] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			out: { type: 'string', default: null },
+			sign: { type: 'boolean', default: false },
+			key: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-gate-attestation-signing.
+	'attest keygen': {
+		usage: 'bskel attest keygen --out <dir> [--force] [--json]',
+		options: {
+			out: { type: 'string', default: null, required: true },
+			force: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'attest verify': {
+		usage: 'bskel attest verify --file <path> --pubkey <path> [--json]',
+		options: {
+			file: { type: 'string', default: null, required: true },
+			pubkey: { type: 'string', default: null, required: true },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -129,6 +148,30 @@ export const COMMANDS = {
 		},
 		allowPositionals: true,
 	},
+	'scan cross-feature-check': {
+		usage: 'bskel scan cross-feature-check --feature <id> [--db [--database-url-env <NAME>] [--schema public]] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			// D-cross-feature-fk-inference: byte-identical shape to `scan`'s own --db/--database-url-env/
+			// --schema (resolved via the SAME resolveDbSchemaOrExit() helper) -- omitting them entirely
+			// is the exact prior behavior, unchanged.
+			db: { type: 'boolean', default: false },
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'scan cross-feature-waive': {
+		usage: 'bskel scan cross-feature-waive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			signal: { type: 'string', default: null, required: true },
+			identifier: { type: 'string', default: null, required: true },
+			'other-feature': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'feature init': {
 		usage: 'bskel feature init --slug <name>',
 		options: { slug: { type: 'string', default: null, required: true } },
@@ -343,10 +386,11 @@ export const COMMANDS = {
 		},
 	},
 	'observe import': {
-		usage: 'bskel observe import --feature <id> --receipts <path> [--json]',
+		usage: 'bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			receipts: { type: 'string', default: null, required: true },
+			'fail-on-violation': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -410,6 +454,70 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-patch-transactions: content-addressed patch transactions, Slice 1 (config_check ->
+	// config_apply). `propose`/`approve` only touch specs/, so no --force escape exists on either --
+	// re-propose is the only remediation for a stale target. `rollback` alone gets --force (reverting
+	// to a known-good, git-recoverable prior state is materially lower-risk than forcing a forward
+	// edit whose collateral effects were never re-verified).
+	'patch propose': {
+		usage: 'bskel patch propose --feature <id> [--kind config-apply --choice <stackChoiceId> --target <config_check target path> | --kind ddl-apply --database-url-env <NAME> --sql-file <path> [--schema public]] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			// D-ddl-apply: default 'config-apply' -- omitting --kind entirely is byte-identical to
+			// this project's prior behavior. choice/target/database-url-env/sql-file are validated
+			// by hand inside cmdPatchPropose (kind-conditional requirements aren't expressible via
+			// this table's own unconditional `required: true`), matching this file's existing
+			// convention for kind-conditional flags (e.g. --reason on approve/rollback).
+			kind: { type: 'string', default: 'config-apply' },
+			choice: { type: 'string', default: null },
+			target: { type: 'string', default: null },
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			'sql-file': { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch approve': {
+		usage: 'bskel patch approve --feature <id> --transaction <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch apply': {
+		usage: 'bskel patch apply --feature <id> --transaction <id> [--confirm <id-or-dropped-table-name>] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			// D-ddl-apply: required for any kind other than config-apply -- what value it must
+			// exactly equal is kind- AND transaction-specific (getPatchKind(kind).requiredConfirmValue(txn)):
+			// the transaction id for a non-drop ddl-apply transaction, or the sorted, comma-joined
+			// dropped-table name(s) for one that drops a table. Checked by hand inside cmdPatchApply
+			// once the transaction's own kind/shape is known, not declaratively here. Ignored for
+			// config-apply.
+			confirm: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch rollback': {
+		usage: 'bskel patch rollback --feature <id> --transaction <id> --reason "..." [--force] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			force: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch list': {
+		usage: 'bskel patch list --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	verify: {
 		usage: 'bskel verify --feature <id> [--build [--allow-skip-build]] [--json]',
 		options: {
@@ -444,13 +552,27 @@ export const COMMANDS = {
 		},
 	},
 	serve: {
-		usage: 'bskel serve [--port N] [--host <addr>] [--json]',
+		usage: 'bskel serve [--port N] [--host <addr>] [--database-url-env <NAME> [--schema public] [--sign-key <path>] [--require-sign-key]] [--json]',
 		options: {
 			// min:0 (unlike stack apply --port's min:1) -- 0 is the standard "let the OS pick a free
 			// ephemeral port" sentinel, genuinely useful both for tests and for a user who doesn't care
 			// which port they get, not just a testing convenience.
 			port: { type: 'string', default: '4747', numeric: { min: 0, max: 65535 } },
 			host: { type: 'string', default: '127.0.0.1' },
+			// D-ddl-apply: every new DB-schema/patch-transaction route is gated behind this one flag
+			// being present -- a plain `bskel serve` (no --database-url-env) stays byte-identical to
+			// today, those paths simply don't exist (404, not 403), mirroring --host's own "safe
+			// default, explicit override" convention. --sign-key is optional even when the DB surface
+			// is enabled (see D-ddl-apply's "detect and warn, never hard-require" signing posture).
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			'sign-key': { type: 'string', default: null },
+			// D-ddl-apply: opt-in-to-MORE-strictness -- refuses to even start the DDL surface without
+			// --sign-key also given, closing this feature's own named "mandatory signing... cheap,
+			// well-justified near-term addition" EXIT item. A no-op when --database-url-env wasn't
+			// given at all (nothing to enforce on a surface that isn't running), same as --schema/
+			// --sign-key themselves already being inert outside that case.
+			'require-sign-key': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},

package/lib/cross-feature-collisions.mjs

@@ -0,0 +1,286 @@
+// D-cross-feature-collision: detects NAME-identity collisions between features -- two DIFFERENT
+// features whose scan reports declare the same resourceType/DTO className, the same DB table name,
+// or the same contract operationId. Originally NOT a dependency-direction or FK claim (see
+// lib/field-dependencies.mjs's own declared-dependency system for that, a separate, complementary
+// concern) -- it existed because the runtime handle-resolver dispatch system (java-spring/python-
+// fastapi/typescript-express, all three) already implicitly assumes resourceType is unique across
+// a whole target repo, and nothing detected or protected against that assumption being silently
+// violated before this. See DECISIONS.md for the full design and the real collision this was found
+// against.
+//
+// D-cross-feature-fk-inference: closed this entry's own named EXIT item -- a 4th signal,
+// `db_foreign_key`, correlates a REAL live Postgres foreign-key edge (Plane C,
+// scanners/db/introspect.mjs) against which feature declares each side's table, reusing this same
+// per-other-feature loop (ownClasses/otherClasses) rather than a new subsystem or a persisted
+// "table -> feature" index. See resolveLiveTables()/findCollisions() below and DECISIONS.md.
+import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { listFeatures } from './featurelifecycle.mjs';
+
+const REPORT_SCHEMA = 'sbf.cross-feature-report/1';
+const RESOLUTION_SCHEMA = 'sbf.cross-feature-resolution/1';
+
+export function crossFeatureReportPath(root, featureId) {
+	return specPath(root, featureId, 'cross-feature-report.json');
+}
+
+export function crossFeatureResolutionPath(root, featureId) {
+	return specPath(root, featureId, 'cross-feature-resolution.json');
+}
+
+// Reads the PERSISTED report from the last `bskel scan cross-feature-check` run -- `bskel scan
+// cross-feature-waive` validates against this snapshot, never a live re-computation, matching
+// `contract waive`'s own established precedent (contracts/completeness.mjs's loadContract): a
+// waiver targets what was actually reported, and if reality has moved since, the gate's own
+// staleness token (which already covers every OTHER feature named in this same report) is what
+// surfaces that, not a silent re-check inside the waive command itself.
+export function loadCrossFeatureReport(root, featureId) {
+	return readJsonIfExists(crossFeatureReportPath(root, featureId));
+}
+
+export function loadCrossFeatureResolution(root, featureId) {
+	const path = crossFeatureResolutionPath(root, featureId);
+	const parsed = readJsonIfExists(path);
+	if (parsed === null) return { schema: RESOLUTION_SCHEMA, feature_id: featureId, waivers: [] };
+	const { ok, errors } = validateAgainstSchema('cross-feature-resolution.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${path}: does not match schemas/cross-feature-resolution.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveCrossFeatureResolution(root, featureId, resolution) {
+	const { ok, errors } = validateAgainstSchema('cross-feature-resolution.schema.json', resolution);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid cross-feature resolution for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(crossFeatureResolutionPath(root, featureId), `${JSON.stringify(resolution, null, 2)}\n`);
+	return resolution;
+}
+
+// The waiver key -- deliberately signal+identifier+other_feature only, never a message/reason, so
+// rephrasing a --reason later never silently stops a waiver from matching (same discipline
+// contracts/completeness.mjs's own warningKey() already established).
+export function waiverKey(w) {
+	return `${w.signal}::${w.identifier}::${w.other_feature}`;
+}
+
+// Own-module accessors -- reads THIS feature's own disposed module (className list + table names),
+// mirroring resolveClassFile()'s own lookup shape (lib/field-dependencies.mjs) but returning every
+// candidate at once instead of resolving one resourceType.
+function ownDisposedModule(root, featureId) {
+	const report = readJsonIfExists(specPath(root, featureId, 'brownfield-scan.json'));
+	if (!report) return null;
+	const moduleName = report.disposition?.module ?? report.related_modules?.[0]?.module;
+	if (!moduleName) return null;
+	return report.related_modules?.find((m) => m.module === moduleName) ?? null;
+}
+
+function ownOperationIds(root, featureId) {
+	const contract = readJsonIfExists(specPath(root, featureId, 'contracts', `${featureId}.schema.json`));
+	return contract ? Object.keys(contract.operations ?? {}) : [];
+}
+
+// D-cross-feature-fk-inference (Plane A FK extraction): Plane A is strictly LOWER priority than
+// any Plane C (live/persisted) source -- a migration FILE existing is not proof it was ever
+// actually applied (D-migration-scope's own standing caveat), so Plane C is always more
+// trustworthy when available. Migration files are repo-wide, not feature-scoped, so any ONE
+// feature's persisted db_schema.migrations carries the same content as any other's -- "first one
+// found" is sufficient, matching the persisted-live tier's own "first found" logic exactly.
+function migrationsTables(dbSchema) {
+	return dbSchema?.migrations?.tool && dbSchema.migrations.tool !== 'none' ? dbSchema.migrations.tables : null;
+}
+
+// D-cross-feature-fk-inference: resolves ONE usable live-table snapshot to correlate FK edges
+// against, in four tiers (live > this feature's own persisted live > another feature's persisted
+// live > migration-file-derived, Plane A). `liveDbSchema` is whatever the CLI boundary already
+// resolved (the SAME resolveDbSchemaOrExit() result `cmdScan` itself uses -- this function never
+// opens a connection itself). Plane C is already schema-wide (every table in `--schema`, not
+// filtered to any one feature), so there is nothing to MERGE across features' own snapshots --
+// locating one usable snapshot is enough; it already contains every table in that schema.
+function resolveLiveTables(root, featureId, liveDbSchema) {
+	// D-cross-feature-fk-inference (staleness/freshness token): `generated_at` threaded into
+	// `fk_check` at every tier below, read from whichever source that tier actually used --
+	// `introspectWithClient()`/`scanMigrations()` both stamp it at the real point of capture, this
+	// function only ever passes it through, never invents or re-derives it.
+	if (liveDbSchema?.live) {
+		return { tables: liveDbSchema.live.tables, fk_check: { mode: 'live', schema: liveDbSchema.live.schema, source_feature: null, generated_at: liveDbSchema.live.generated_at ?? null } };
+	}
+	const ownReport = readJsonIfExists(specPath(root, featureId, 'brownfield-scan.json'));
+	if (ownReport?.db_schema?.live) {
+		return { tables: ownReport.db_schema.live.tables, fk_check: { mode: 'persisted', schema: ownReport.db_schema.live.schema, source_feature: featureId, generated_at: ownReport.db_schema.live.generated_at ?? null } };
+	}
+	// Deterministic by feature_id sort order -- listFeatures() itself already returns records
+	// sorted by directory name, so "first other feature with a persisted live snapshot" is a
+	// stable, repeatable choice, not an arbitrary one. Reused below for the migrations tier too.
+	const otherFeatures = listFeatures(root).filter((record) => record.feature_id !== featureId);
+	for (const record of otherFeatures) {
+		const otherReport = readJsonIfExists(specPath(root, record.feature_id, 'brownfield-scan.json'));
+		if (otherReport?.db_schema?.live) {
+			return { tables: otherReport.db_schema.live.tables, fk_check: { mode: 'persisted', schema: otherReport.db_schema.live.schema, source_feature: record.feature_id, generated_at: otherReport.db_schema.live.generated_at ?? null } };
+		}
+	}
+
+	if (migrationsTables(liveDbSchema)) {
+		return { tables: migrationsTables(liveDbSchema), fk_check: { mode: 'migrations', schema: null, source_feature: null, generated_at: liveDbSchema.migrations.generated_at ?? null } };
+	}
+	if (migrationsTables(ownReport?.db_schema)) {
+		return { tables: migrationsTables(ownReport.db_schema), fk_check: { mode: 'migrations', schema: null, source_feature: featureId, generated_at: ownReport.db_schema.migrations.generated_at ?? null } };
+	}
+	for (const record of otherFeatures) {
+		const otherReport = readJsonIfExists(specPath(root, record.feature_id, 'brownfield-scan.json'));
+		if (migrationsTables(otherReport?.db_schema)) {
+			return { tables: migrationsTables(otherReport.db_schema), fk_check: { mode: 'migrations', schema: null, source_feature: record.feature_id, generated_at: otherReport.db_schema.migrations.generated_at ?? null } };
+		}
+	}
+
+	return { tables: null, fk_check: { mode: 'unavailable', schema: null, source_feature: null, generated_at: null } };
+}
+
+// Flattens Plane C's PER-TABLE foreign_keys[] (scanners/db/introspect.mjs) into one flat edge list
+// -- {table, column, references_table, references_column}, `table` being the CONSTRAINED
+// (child/referencing) side.
+function flattenLiveForeignKeys(liveTables) {
+	const edges = [];
+	for (const t of liveTables) {
+		for (const fk of t.foreign_keys ?? []) {
+			edges.push({ table: t.name, column: fk.column, references_table: fk.references_table, references_column: fk.references_column });
+		}
+	}
+	return edges;
+}
+
+// D-cross-feature-collision: the core comparison -- for the GIVEN feature's own disposed module,
+// checks every OTHER active feature (listFeatures() excludes archived by default, same reasoning
+// D-dependency-propagation-notice's own listDownstreamDependents() already established: an archived
+// feature's naming collision isn't worth blocking a human over) for a resourceType/table/operationId
+// match. One level only, symmetric-but-independent per feature -- feature B finding a collision
+// against feature A does not automatically waive feature A's own, separate check against B (each
+// feature's own cross-feature-resolution.json is its own record, matching contract waive's own
+// per-feature-file precedent).
+//
+// D-cross-feature-fk-inference: `liveDbSchema` (optional, `null` by default -- callers that never
+// pass it get the exact prior behavior for the first 3 signals, plus a `fk_check: {mode:
+// 'unavailable', ...}` and possibly one `unknowns` entry) is the ALREADY-RESOLVED
+// resolveDbSchemaOrExit() result. Returns {findings, fk_check, unknowns} -- a superset of the old
+// bare array, not a rename; findings for the existing 3 signals are byte-identical to before.
+export function findCollisions(root, featureId, { liveDbSchema = null } = {}) {
+	const ownModule = ownDisposedModule(root, featureId);
+	const ownClasses = ownModule ? [...(ownModule.entities ?? []), ...(ownModule.dtos ?? [])] : [];
+	const ownOperationIdSet = new Set(ownOperationIds(root, featureId));
+
+	const { tables: liveTables, fk_check } = resolveLiveTables(root, featureId, liveDbSchema);
+	const liveEdges = liveTables ? flattenLiveForeignKeys(liveTables) : [];
+	// This feature's own table -> entity map (case-folded), matching computeDbDrift()'s own
+	// established case-folding convention (scanners/index.mjs).
+	const ownTablesByName = new Map(ownClasses.filter((c) => c.table).map((c) => [c.table.toLowerCase(), c]));
+	// Every table name (own + every OTHER feature seen) that matched SOME feature, accumulated
+	// across the whole loop below -- used only to report FK edges touching an UNattributed table
+	// (see the unknowns pass after the loop). In-memory, local to this one call -- not a new
+	// persisted "table -> feature" index.
+	const matchedTableNames = new Set(ownTablesByName.keys());
+
+	const findings = [];
+	for (const record of listFeatures(root)) {
+		if (record.feature_id === featureId) continue;
+		const otherModule = ownDisposedModule(root, record.feature_id);
+		const otherClasses = otherModule ? [...(otherModule.entities ?? []), ...(otherModule.dtos ?? [])] : [];
+		const otherTablesByName = new Map(otherClasses.filter((c) => c.table).map((c) => [c.table.toLowerCase(), c]));
+		for (const name of otherTablesByName.keys()) matchedTableNames.add(name);
+
+		for (const ownClass of ownClasses) {
+			const match = otherClasses.find((c) => c.className === ownClass.className);
+			if (match) {
+				findings.push({ signal: 'resource_type', identifier: ownClass.className, other_feature: record.feature_id, confidence: 'high' });
+			}
+		}
+
+		// Table names: only compared when BOTH sides actually have one (a class with no table --
+		// e.g. a DTO, or an entity with no @Table and no fallback -- has nothing to collide on).
+		// Case-folded for comparison, matching computeDbDrift()'s own established convention
+		// (scanners/index.mjs) -- the ONE place in this codebase that already case-folds a `.table`
+		// value before comparing it.
+		for (const ownEntity of ownClasses.filter((c) => c.table)) {
+			const match = otherClasses.find((c) => c.table && c.table.toLowerCase() === ownEntity.table.toLowerCase());
+			if (match) {
+				const confidence = ownEntity.tableSource === 'explicit' && match.tableSource === 'explicit' ? 'high' : 'medium';
+				findings.push({ signal: 'table', identifier: ownEntity.table.toLowerCase(), other_feature: record.feature_id, confidence });
+			}
+		}
+
+		const otherOperationIds = ownOperationIds(root, record.feature_id);
+		for (const opId of ownOperationIdSet) {
+			if (otherOperationIds.includes(opId)) {
+				findings.push({ signal: 'operation_id', identifier: opId, other_feature: record.feature_id, confidence: 'high' });
+			}
+		}
+
+		// D-cross-feature-fk-inference: a real, live FK edge where ONE side is a table THIS
+		// feature declares and the OTHER side is a table `record` declares. Confidence reuses the
+		// exact `table` signal's own tableSource rule -- the FK itself is never in doubt (a live,
+		// Postgres-enforced constraint), what's uncertain is whether the source-derived table name
+		// on each side was a real annotation or an adapter's guessed fallback, the SAME risk the
+		// `table` signal already scores this way. Self-referencing/same-feature edges never reach
+		// here at all -- this only ever compares ownClasses against a DIFFERENT feature's classes.
+		for (const edge of liveEdges) {
+			const childName = edge.table.toLowerCase();
+			const parentName = edge.references_table.toLowerCase();
+			const identifier = `${edge.table}.${edge.column} -> ${edge.references_table}.${edge.references_column}`;
+
+			if (ownTablesByName.has(childName) && otherTablesByName.has(parentName)) {
+				const ownEntity = ownTablesByName.get(childName);
+				const otherEntity = otherTablesByName.get(parentName);
+				const confidence = ownEntity.tableSource === 'explicit' && otherEntity.tableSource === 'explicit' ? 'high' : 'medium';
+				findings.push({ signal: 'db_foreign_key', identifier, other_feature: record.feature_id, confidence, direction: 'references' });
+			}
+			if (ownTablesByName.has(parentName) && otherTablesByName.has(childName)) {
+				const ownEntity = ownTablesByName.get(parentName);
+				const otherEntity = otherTablesByName.get(childName);
+				const confidence = ownEntity.tableSource === 'explicit' && otherEntity.tableSource === 'explicit' ? 'high' : 'medium';
+				findings.push({ signal: 'db_foreign_key', identifier, other_feature: record.feature_id, confidence, direction: 'referenced_by' });
+			}
+		}
+	}
+
+	// D-cross-feature-fk-inference: honest, explicit reporting for the two "no useful FK signal"
+	// cases -- never a silent gap, matching this project's own repeated "no silent caps" discipline
+	// (see D-db-schema-plane's own unknowns precedent for the same reasoning on a different check).
+	const unknowns = [];
+	if (liveTables) {
+		for (const edge of liveEdges) {
+			const childName = edge.table.toLowerCase();
+			const parentName = edge.references_table.toLowerCase();
+			const identifier = `${edge.table}.${edge.column} -> ${edge.references_table}.${edge.references_column}`;
+			if (ownTablesByName.has(childName) && !matchedTableNames.has(parentName)) {
+				unknowns.push(`FK ${identifier}: referenced table "${edge.references_table}" is not declared by any active feature (untracked/external table)`);
+			} else if (ownTablesByName.has(parentName) && !matchedTableNames.has(childName)) {
+				unknowns.push(`FK ${identifier}: referencing table "${edge.table}" is not declared by any active feature (untracked/external table)`);
+			}
+		}
+	} else {
+		unknowns.push('no live DB foreign-key data available to check -- pass --db --database-url-env <NAME> to `bskel scan cross-feature-check`, or run `bskel scan --feature <id> --db --database-url-env <NAME>` at least once to persist a snapshot this check can reuse');
+	}
+
+	return { findings, fk_check, unknowns };
+}
+
+// Mirrors contracts/completeness.mjs's own evaluateResolution() exactly, for a different axis:
+// there, the split is by warning SEVERITY (error vs warn); here, it's by finding CONFIDENCE (high
+// vs medium) -- only a `high`-confidence, unwaived finding blocks. A `medium`-confidence finding
+// (an inferred/guessed table name on at least one side) is always reported, never blocking on its
+// own -- the named mitigation for python-fastapi/typescript-express's own table-name-guessing false-
+// match risk (see DECISIONS.md), not a silently dropped signal.
+export function evaluateCrossFeatureFindings(findings, resolution) {
+	const waivers = resolution.waivers ?? [];
+	const waivedKeys = new Set(waivers.map(waiverKey));
+
+	const highConfidence = findings.filter((f) => f.confidence === 'high');
+	const unwaived = highConfidence.filter((f) => !waivedKeys.has(waiverKey(f)));
+	const waived = highConfidence.filter((f) => waivedKeys.has(waiverKey(f)));
+
+	const currentKeys = new Set(findings.map(waiverKey));
+	const staleWaivers = waivers.filter((w) => !currentKeys.has(waiverKey(w)));
+
+	return { blocking: unwaived.length > 0, unwaived, waived, staleWaivers };
+}

package/lib/diff.mjs

@@ -0,0 +1,35 @@
+// D-patch-transactions: promoted verbatim from handles/_engine.mjs (D4/D-handles-dryrun's own
+// unifiedDiff()) -- pure code motion, zero behavior change. Generic enough that stack/config-apply.
+// mjs needs the identical mechanism for its own collateral-diff safety gate, and there was no
+// existing stack <-> handles import in either direction to introduce by leaving it where it was.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// D4 (D-handles-dryrun): a real unified diff via `git diff --no-index`, not a hand-rolled diff
+// algorithm -- `git` is already a hard dependency elsewhere in this codebase, so this adds zero
+// new dependencies. `cwd: tmpDir` + relative `a/<relPath>`/`b/<relPath>` paths (rather than
+// absolute temp paths) keep the diff header clean and reproducible -- the random tmpdir name
+// never leaks into the output. `git diff --no-index` exits 1 when the two sides differ (the
+// expected, common case here, not a failure) -- only a status other than 0/1 is a genuine error
+// worth throwing.
+export function unifiedDiff(relPath, before, after) {
+	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bskel-diff-'));
+	try {
+		const beforeAbs = path.join(tmpDir, 'a', relPath);
+		const afterAbs = path.join(tmpDir, 'b', relPath);
+		fs.mkdirSync(path.dirname(beforeAbs), { recursive: true });
+		fs.mkdirSync(path.dirname(afterAbs), { recursive: true });
+		fs.writeFileSync(beforeAbs, before ?? '');
+		fs.writeFileSync(afterAbs, after ?? '');
+		try {
+			return execFileSync('git', ['diff', '--no-index', '--no-color', '--', `a/${relPath}`, `b/${relPath}`], { cwd: tmpDir, encoding: 'utf8' });
+		} catch (err) {
+			if (err.status === 1 && typeof err.stdout === 'string') return err.stdout;
+			throw err;
+		}
+	} finally {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	}
+}

package/lib/fsutil.mjs

@@ -29,10 +29,15 @@ export function readJsonIfExists(filePath) {
 // Atomic write (temp + rename), same technique as lib/state.mjs -- reused by every command that
 // writes a durable artifact under specs/<feature_id>/ so a mid-write crash can't leave a
 // half-written file that a later gate check would treat as valid.
-export function writeFileAtomic(filePath, content) {
+// D-gate-attestation-signing: `mode` is additive and optional (undefined -> Node's own default
+// mode-minus-umask, byte-for-byte the same behavior every existing caller already gets) -- added
+// so a sensitive file (a private signing key) can be created with a restrictive mode from its
+// very first write, rather than a separate chmod() after the fact leaving a real, if brief,
+// window where the file exists at the default (world/group-readable) permissions.
+export function writeFileAtomic(filePath, content, mode) {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const tmp = `${filePath}.${process.pid}.tmp`;
-	fs.writeFileSync(tmp, content);
+	fs.writeFileSync(tmp, content, mode === undefined ? undefined : { mode });
 	fs.renameSync(tmp, filePath);
 }
 

package/lib/gate-definitions.mjs

@@ -23,6 +23,8 @@ import { specPath, sbfPath } from './paths.mjs';
 import { ADAPTERS, adapterById } from '../scanners/registry.mjs';
 import { loadManifest } from './handles-manifest.mjs';
 import { dependenciesPath, resolveClassFile } from './field-dependencies.mjs';
+import { crossFeatureReportPath, crossFeatureResolutionPath } from './cross-feature-collisions.mjs';
+import { listTransactions, transactionPath } from './patch-transactions.mjs';
 
 // S2: prefix for stack's per-applied-file input keys -- lib/gates.mjs's diffInputs() compares
 // top-level keys only, so a manifest-shaped input (one hash per applied file) has to flatten
@@ -48,6 +50,20 @@ const MODULE_FILE_PREFIX = 'module_file:';
 // would otherwise just repeat the identical file hash N times with zero added diagnostic value).
 const TARGET_FIELD_FILE_PREFIX = 'target_field_file:';
 const SOURCE_FIELD_FILE_PREFIX = 'source_field_file:';
+// D-cross-feature-collision: same flattened-manifest convention -- one pair of keys per OTHER
+// feature named in the LAST persisted cross-feature-report.json's own findings (not every feature
+// in the repo), so a change to a feature this one was never found colliding with never stales this
+// gate. Known, accepted limitation (same class as D-field-dependency's own): a BRAND NEW feature
+// created later with a colliding name is not caught until the next explicit re-check -- see
+// DECISIONS.md.
+const OTHER_FEATURE_SCAN_PREFIX = 'other_feature_scan:';
+const OTHER_FEATURE_CONTRACT_PREFIX = 'other_feature_contract:';
+// D-patch-transactions: same flattened-manifest convention -- one pair of keys per APPLIED
+// transaction (never proposed/approved/rolled_back ones -- only a LIVE edit is drift-risk), so a
+// deleted or hand-edited target file, or a hand-edited transaction record itself, is named
+// specifically rather than reported as a generic "stale".
+const APPLIED_TARGET_PREFIX = 'applied_target:';
+const TRANSACTION_RECORD_PREFIX = 'transaction_record:';
 
 // The preflight and stack gates are repo-scoped, not feature-scoped -- preflight runs before a
 // feature_id exists at all, and a stack choice is a project-wide decision, not per-feature.
@@ -154,6 +170,39 @@ export const GATE_DEFINITIONS = Object.freeze({
 			return inputs;
 		},
 	},
+	// D-cross-feature-collision: covers the persisted report+resolution files' own hashes (a
+	// re-check or a new waiver invalidates the old token, same as contract's own
+	// contract_hash/resolution_hash pair), plus one pair of keys per OTHER feature the LAST
+	// persisted report actually found a collision against -- so if that other feature's own scan
+	// report or contract later changes (renaming away the collision, or introducing a new one),
+	// this gate goes stale and names exactly which other feature moved. See
+	// OTHER_FEATURE_SCAN_PREFIX's own comment for the one accepted limitation this narrowing has.
+	cross_feature: {
+		name: 'cross_feature',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		// D-cross-feature-fk-inference: the new `db_foreign_key` signal needs ZERO changes here --
+		// `otherFeatures` is derived generically from every finding's own `other_feature`, never
+		// branching on `f.signal`, so this recompute already covers the new signal automatically.
+		// It also never touches a live DB itself (pure filesystem hashing over the already-persisted
+		// report/resolution) regardless of whether that report's findings came from a fresh live
+		// connection, a persisted snapshot, or neither -- D-db-schema-plane's "no gate whose
+		// recomputation requires a live DB connection" boundary is unaffected by this signal.
+		recompute: (root, featureId) => {
+			const reportPath = crossFeatureReportPath(root, featureId);
+			const inputs = {
+				cross_feature_report_hash: sha256File(reportPath),
+				cross_feature_resolution_hash: sha256File(crossFeatureResolutionPath(root, featureId)),
+			};
+			const report = readJsonIfExists(reportPath);
+			const otherFeatures = new Set((report?.findings ?? []).map((f) => f.other_feature));
+			for (const other of otherFeatures) {
+				inputs[`${OTHER_FEATURE_SCAN_PREFIX}${other}`] = sha256File(specPath(root, other, 'brownfield-scan.json'));
+				inputs[`${OTHER_FEATURE_CONTRACT_PREFIX}${other}`] = sha256File(specPath(root, other, 'contracts', `${other}.schema.json`));
+			}
+			return inputs;
+		},
+	},
 	// The contract gate's token covers the emitted contract file's own hash (re-emitting after
 	// a re-scan invalidates it) and head_sha -- NOT the scan report's hash directly, since the
 	// contract is a derived artifact; if the scan changes but the contract hasn't been
@@ -290,6 +339,41 @@ export const GATE_DEFINITIONS = Object.freeze({
 			return inputs;
 		},
 	},
+	// D-patch-transactions: feature-scoped (unlike `stack` above) -- a patch transaction is
+	// proposed against one feature's own workflow, mirroring `dependencies`/`cross_feature`'s own
+	// reasoning, not a repo-wide fact like a stack choice. Deliberately does NOT reuse `stack`'s own
+	// `.sbf/stack.json` record: `cmdStackApply` treats `applied_files` as this choice's FULL
+	// desired-state file set and overwrites it wholesale on every `stack apply --apply` (confirmed
+	// live, `bin/bskel.mjs`'s own comment on that line) -- a config-applied file appended there
+	// would silently vanish from tracking on the next ordinary `stack apply`. This gate owns its
+	// own, separate record instead.
+	patch_transactions: {
+		name: 'patch_transactions',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		// D-ddl-apply: `config-apply` (a filesystem-targeting kind) still hashes both the applied
+		// target file AND the transaction record, exactly as before. `ddl-apply`'s target is a live
+		// database, not a file -- it deliberately contributes ONLY the transaction-record hash,
+		// never re-touching the live DB here. Reusing D-db-schema-plane's own already-established
+		// "a gate that can only ever be satisfied with a live DB connection is a different
+		// risk/availability class -- detect and warn, never gate on live state" precedent: staying
+		// fs-only here means this gate can never itself require DB connectivity to recompute, at
+		// the honestly-accepted cost that it cannot detect someone reverting DDL by hand outside
+		// this tool (see DECISIONS.md D-ddl-apply's EXIT list).
+		recompute: (root, featureId) => {
+			const inputs = {};
+			for (const txn of listTransactions(root, featureId)) {
+				if (txn.status !== 'applied') continue; // only a LIVE edit is drift-risk
+				if (txn.kind === 'config-apply') {
+					const abs = resolveWithinRoot(root, txn.target.file);
+					if (!abs) continue; // a path escaping the repo is not something this feature applied
+					inputs[`${APPLIED_TARGET_PREFIX}${txn.transaction_id}`] = sha256File(abs); // null == deleted -> stale
+				}
+				inputs[`${TRANSACTION_RECORD_PREFIX}${txn.transaction_id}`] = sha256File(transactionPath(root, featureId, txn.transaction_id));
+			}
+			return inputs;
+		},
+	},
 	// D-runtime-conformance-receipts: passed by `bskel observe import`, never by `observe emit`
 	// (emitting the checking infra is not evidence; importing real receipts is). Opt-in like
 	// handles/stack -- not every feature runs runtime observation. Staleness = the contract moved
@@ -315,7 +399,7 @@ export const GATE_DEFINITIONS = Object.freeze({
 // test/gate-definitions.test.mjs asserts this stays exactly in sync with GATE_DEFINITIONS' own
 // key set, so a gate added to one and not the other fails loudly instead of silently vanishing
 // from `bskel verify` the way `stack` did before this module existed.
-export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'contract', 'dependencies', 'handles', 'stack', 'conformance']);
+export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'handles', 'stack', 'patch_transactions', 'conformance']);
 
 export function getGateDefinition(name) {
 	return Object.hasOwn(GATE_DEFINITIONS, name) ? GATE_DEFINITIONS[name] : null;

package/lib/gates.mjs

@@ -36,7 +36,11 @@ export function computeToken(inputs) {
 	return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
 }
 
-function sortKeysDeep(value) {
+// D-gate-attestation-signing: exported once a second real consumer (lib/attest.mjs's
+// canonicalize(), which needs the SAME deep-sort applied to an entire gate-export report, not
+// just one gate's `inputs`) needed the identical function -- no behavior change to any existing
+// caller in this file.
+export function sortKeysDeep(value) {
 	if (Array.isArray(value)) return value.map(sortKeysDeep);
 	if (value && typeof value === 'object') {
 		return Object.fromEntries(