backend-skeleton 1.0.0-beta.9 → 1.1.0

package/bin/bskel.mjs

@@ -9,10 +9,10 @@ import { repoRoot, localDefaultBranch, fileHistory, showFileAtRevision, headSha,
 import { forceNamedGate, revokeNamedGate, requireNamedGate, passNamedGate, awaitNamedGateDisposition, EXIT } from '../lib/gates.mjs';
 import { REPO_GATE_ID, GATE_NAMES, gateScopeId, requireGateDefinition } from '../lib/gate-definitions.mjs';
 import { getGate, loadState, historyPath } from '../lib/state.mjs';
-import { writeFileAtomic, sha256File } from '../lib/fsutil.mjs';
+import { writeFileAtomic, sha256File, readJsonIfExists } from '../lib/fsutil.mjs';
 import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
 import { withLockSync } from '../lib/lock.mjs';
-import { specDir, specPath } from '../lib/paths.mjs';
+import { specDir, specPath, sbfPath } from '../lib/paths.mjs';
 import { requireValidFeatureId, requireValidSlug, requireValidFeatureOrRepoId, slugWords, nextFeatureNumber } from '../lib/featureid.mjs';
 import {
 	loadFeatureFile, saveFeatureFile, loadFeatureIndex, saveFeatureIndex,
@@ -30,12 +30,19 @@ import { buildContract, selectModule, CONTRACT_SCHEMA_VERSION } from '../contrac
 import { validateEnvelope, operationPayloadSchema } from '../contracts/validate.mjs';
 import { evaluateResolution, loadResolution, saveResolution, requireWarningCode, warningKey, countByCode } from '../contracts/completeness.mjs';
 import { loadPatchApprovals, savePatchApprovals, approvalKey } from '../lib/patch-approvals.mjs';
+import { proposeTransaction, approveTransaction, applyTransaction, rollbackTransaction, loadTransaction, listTransactions } from '../lib/patch-transactions.mjs';
+import { getPatchKind, replanTransaction, PATCH_KIND_NAMES } from '../lib/patch-kinds.mjs';
+import { generateKeypair, signPayload, verifyPayload } from '../lib/attest.mjs';
 import { loadManifest, saveManifest } from '../lib/handles-manifest.mjs';
 import { createHttpServer } from '../lib/http-server.mjs';
 import {
 	resolveClassFile, listDownstreamDependents, DependencyOperationError,
 	declareDependency, removeDependency, buildDependencyListReport,
 } from '../lib/field-dependencies.mjs';
+import {
+	findCollisions, evaluateCrossFeatureFindings, waiverKey,
+	crossFeatureReportPath, loadCrossFeatureReport, loadCrossFeatureResolution, saveCrossFeatureResolution,
+} from '../lib/cross-feature-collisions.mjs';
 import { STACKS as NEW_STACKS, ALL_STACK_PARAMS, stacksAccepting } from '../new/index.mjs';
 import {
 	requireSingleLineText, requireValidJavaPackageName, requireValidArtifactId,
@@ -49,9 +56,12 @@ import { loadCatalogEntry, listCatalogChoices, planApply, applyPlan } from '../s
 import { PROVIDERS, PROVIDER_LOAD_ERRORS, providerById } from '../handles/registry.mjs';
 import { detectAstHelperAvailable, runAstClassify } from '../handles/providers/java-spring/ast-bridge.mjs';
 import { detectBasePackage } from '../handles/providers/java-spring/plan.mjs';
+import { hasSpringAopDependency, springAopArtifactName } from '../handles/providers/java-spring/emit.mjs';
 import { emitObserveJavaSpring } from '../handles/providers/java-spring/observe.mjs';
 import { plan as planPythonFastApi } from '../handles/providers/python-fastapi/plan.mjs';
 import { emitObservePythonFastApi } from '../handles/providers/python-fastapi/observe.mjs';
+import { plan as planTypeScriptExpress } from '../handles/providers/typescript-express/plan.mjs';
+import { emitObserveTypeScriptExpress } from '../handles/providers/typescript-express/observe.mjs';
 import { collectGateStatuses, runBuildCheck, checkArtifacts, checkResolverConflicts } from '../lib/verify.mjs';
 import { computeWorkflowState } from '../lib/workflow.mjs';
 import { computeDoctorChecks, WORKFLOWS as DOCTOR_WORKFLOWS } from '../lib/doctor.mjs';
@@ -70,6 +80,8 @@ function usage() {
   bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]
   bskel scan disposition --feature <id> --mode reuse|extend|replace|parallel [--module <name>] [--note "..."] [--breaking-approved]
   bskel scan explain <module> --feature <id> [--json]
+  bskel scan cross-feature-check --feature <id> [--db [--database-url-env <NAME>] [--schema public]] [--json]
+  bskel scan cross-feature-waive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..."
   bskel feature init --slug <name>
   bskel feature list [--all] [--json]
   bskel feature show <id> [--json]
@@ -85,14 +97,19 @@ function usage() {
   bskel dependency declare --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--memo "..."]
   bskel dependency remove --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."
   bskel dependency list --feature <id> [--json]
-  bskel stack apply --choice <id> [--apply] [--port N] [--json]
+  bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."] [--json]
   bskel catalog lint [<choice>] [--json]
   bskel handles plan --feature <id> [--module <name>] [--resource type1,type2] [--diff] [--ast]
   bskel handles emit --feature <id> [--module <name>] [--resource type1,type2] [--force --reason "..."] [--check] [--diff] [--enforce-registry on|off --reason "..."]
   bskel handles patch approve --feature <id> [--module <name>] --resource <Type> --field <name> --strategy patch-wrapper|null-means-unchanged --reason "..." [--json]
-  bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--json]
+  bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--module <name>] [--check-registry-coverage] [--json]
+  bskel patch propose --feature <id> [--kind config-apply|ddl-apply] --choice <stackChoiceId> --target <config_check target path> --database-url-env <NAME> --schema <name> --sql-file <path> [--json]
+  bskel patch approve --feature <id> --transaction <id> --reason "..." [--json]
+  bskel patch apply --feature <id> --transaction <id> [--confirm <id-or-dropped-table-name>] [--json]
+  bskel patch rollback --feature <id> --transaction <id> --reason "..." [--force] [--json]
+  bskel patch list --feature <id> [--json]
   bskel observe emit --feature <id> [--module <name>] [--force --reason "..."] [--check] [--diff] [--json]
-  bskel observe import --feature <id> --receipts <path> [--json]
+  bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--json]
   bskel verify --feature <id> [--build [--allow-skip-build]] [--json]
   bskel status [--feature <id>] [--json]
   bskel next [--feature <id>] [--json]
@@ -101,9 +118,11 @@ function usage() {
   bskel gate revoke <name> --reason "..." [--feature <id>]
   bskel gate history <name> [--feature <id>] [--json]
   bskel gate show [<name>] [--feature <id>]
-  bskel gate export --feature <id> [--out <path>] [--json]
+  bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath>] [--json]
+  bskel attest keygen --out <dir> [--force] [--json]
+  bskel attest verify --file <path> --pubkey <path> [--json]
   bskel doctor [--workflow ${DOCTOR_WORKFLOWS.join('|')}] [--json]
-  bskel serve [--port N] [--host <addr>] [--json]
+  bskel serve [--port N] [--host <addr>] [--database-url-env <NAME>] [--schema <name>] [--sign-key <path>] [--require-sign-key] [--json]
 `);
 }
 
@@ -393,6 +412,12 @@ function cmdGateExport(args) {
 	setContext('gate export', flags);
 	const root = requireRepoRoot();
 	requireValidFeatureId(flags.feature);
+	if (flags.sign && !flags.key) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel gate export --sign requires --key <privateKeyPath>');
+	}
+	if (flags.key && !flags.sign) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--key only has an effect together with --sign');
+	}
 
 	const gates = {};
 	for (const name of GATE_NAMES) {
@@ -407,14 +432,45 @@ function cmdGateExport(args) {
 		git: { branch: currentBranch(root), head_sha: headSha(root), dirty: isDirty(root) },
 		gates,
 	};
-	const rendered = `${JSON.stringify(report, null, 2)}\n`;
+	// D-gate-attestation-signing: validated unconditionally, signed or not -- a document that can
+	// be exported unsigned should be exactly as trustworthy in shape as one that gets signed later.
+	{
+		const { ok, errors } = validateAgainstSchema('gate-export.schema.json', report);
+		if (!ok) {
+			fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `internal error: the computed gate-export report failed its own schema -- ${formatSchemaErrors(errors).join('; ')}`);
+		}
+	}
+
+	let payload = report;
+	if (flags.sign) {
+		let privateKeyPem;
+		try {
+			privateKeyPem = fs.readFileSync(path.resolve(process.cwd(), flags.key), 'utf8');
+		} catch (err) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read --key "${flags.key}": ${err.message}`);
+		}
+		let signatureValue;
+		try {
+			signatureValue = signPayload(report, privateKeyPem);
+		} catch (err) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--key "${flags.key}" is not a usable Ed25519 private key: ${err.message}`);
+		}
+		const attestation = { schema: 'sbf.gate-attestation/1', report, signature: { algorithm: 'ed25519', value: signatureValue } };
+		const { ok, errors } = validateAgainstSchema('gate-attestation.schema.json', attestation);
+		if (!ok) {
+			fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `internal error: the computed gate attestation failed its own schema -- ${formatSchemaErrors(errors).join('; ')}`);
+		}
+		payload = attestation;
+	}
+	const rendered = `${JSON.stringify(payload, null, 2)}\n`;
 
 	if (flags.out) {
 		const outPath = path.resolve(process.cwd(), flags.out);
 		writeFileAtomic(outPath, rendered);
 		if (!flags.quiet) {
 			const passCount = GATE_NAMES.filter((n) => gates[n].current?.status === 'pass').length;
-			console.log(`wrote ${flags.out} -- ${passCount}/${GATE_NAMES.length} gate(s) currently passing, ${report.git.branch}@${report.git.head_sha?.slice(0, 12) ?? '(unknown)'}${report.git.dirty ? ' (dirty)' : ''}`);
+			const signedNote = flags.sign ? ' (signed)' : '';
+			console.log(`wrote ${flags.out}${signedNote} -- ${passCount}/${GATE_NAMES.length} gate(s) currently passing, ${report.git.branch}@${report.git.head_sha?.slice(0, 12) ?? '(unknown)'}${report.git.dirty ? ' (dirty)' : ''}`);
 		}
 	} else {
 		console.log(rendered);
@@ -422,6 +478,78 @@ function cmdGateExport(args) {
 	process.exit(0);
 }
 
+// D-gate-attestation-signing: --out is always required, never a default/home-directory location --
+// this codebase has zero existing home-directory persistence convention anywhere, and inventing
+// one is explicitly out of scope for this slice (a real fork the user weighed and decided, see
+// DECISIONS.md). Repo-independent -- does not require a git repo at all, matching `attest verify`'s
+// own posture below (both operate purely on files the caller names).
+function cmdAttestKeygen(args) {
+	const flags = parseCommand('attest keygen', args);
+	if (flags.help) { console.log(renderCommandHelp('attest keygen')); process.exit(0); }
+	setContext('attest keygen', flags);
+	const outDir = path.resolve(process.cwd(), flags.out);
+	const privatePath = path.join(outDir, 'attest-private.pem');
+	const publicPath = path.join(outDir, 'attest-public.pem');
+	if (!flags.force) {
+		const existing = [privatePath, publicPath].filter((p) => fs.existsSync(p));
+		if (existing.length > 0) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `refusing to overwrite existing key file(s) without --force: ${existing.join(', ')} -- regenerating would orphan any attestation already signed with the old key`);
+		}
+	}
+	const { publicKeyPem, privateKeyPem } = generateKeypair();
+	// Restrictive mode (owner read/write only) from the very first write -- see the
+	// `D-gate-attestation-signing` entry's own note in `lib/fsutil.mjs` on why this is a
+	// `writeFileAtomic` parameter, not a chmod() called after the fact.
+	writeFileAtomic(privatePath, privateKeyPem, 0o600);
+	writeFileAtomic(publicPath, publicKeyPem);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ private_key: privatePath, public_key: publicPath }, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`wrote ${privatePath} (0600) and ${publicPath}`);
+	}
+	process.exit(0);
+}
+
+// Deliberately repo-independent (no requireRepoRoot()) -- verifying a previously-exported
+// attestation has nothing to do with the current directory's own git state; the whole point is to
+// check a document someone else produced, possibly on a different machine, offline. Exit code is
+// driven ONLY by signature validity -- whether the gates INSIDE the report passed is a separate,
+// printed question (see DECISIONS.md for why conflating the two would be actively misleading).
+function cmdAttestVerify(args) {
+	const flags = parseCommand('attest verify', args);
+	if (flags.help) { console.log(renderCommandHelp('attest verify')); process.exit(0); }
+	setContext('attest verify', flags);
+
+	let attestation;
+	try {
+		attestation = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), flags.file), 'utf8'));
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read/parse --file "${flags.file}": ${err.message}`);
+	}
+	const { ok: schemaOk, errors: schemaErrors } = validateAgainstSchema('gate-attestation.schema.json', attestation);
+	if (!schemaOk) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `"${flags.file}" is not a valid gate attestation: ${formatSchemaErrors(schemaErrors).join('; ')}`);
+	}
+	let publicKeyPem;
+	try {
+		publicKeyPem = fs.readFileSync(path.resolve(process.cwd(), flags.pubkey), 'utf8');
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read --pubkey "${flags.pubkey}": ${err.message}`);
+	}
+
+	const valid = verifyPayload(attestation.report, attestation.signature.value, publicKeyPem);
+	const passCount = GATE_NAMES.filter((n) => attestation.report.gates[n]?.current?.status === 'pass').length;
+
+	if (flags.json) {
+		console.log(JSON.stringify({ valid, report_summary: { feature_id: attestation.report.feature_id, generated_at: attestation.report.generated_at, gates_passing: `${passCount}/${GATE_NAMES.length}` } }, null, 2));
+	} else if (!flags.quiet) {
+		console.log(valid ? 'VALID: this attestation was genuinely signed by the holder of the matching private key' : 'INVALID: signature does not match this report + public key');
+		console.log(`report says: feature ${attestation.report.feature_id}, ${passCount}/${GATE_NAMES.length} gate(s) passing, generated ${attestation.report.generated_at}`);
+	}
+	process.exit(valid ? EXIT_CODES.OK : EXIT_CODES.CHECK_FAILED);
+}
+
 // Structural enforcement of "preflight blocks everything below it" (see the workflow table in
 // SKILL.md) for every feature-scoped command -- not just documented as a step order, checked.
 // Ad-hoc `bskel scan` (no --feature) is exempt: it's an explicit side-channel quick-look
@@ -634,6 +762,146 @@ function cmdScanExplain(args) {
 	process.exit(0);
 }
 
+// D-cross-feature-collision: mirrors cmdContractEmit's own "always write the artifact, gate
+// blocks only if unresolved issues remain" shape exactly, for a different data source (NAME-
+// identity collisions against every OTHER feature, not this feature's own contract completeness).
+//
+// D-cross-feature-fk-inference: async now -- reuses the EXACT same resolveDbSchemaOrExit() helper
+// cmdScan() already calls for `--db [--database-url-env <NAME>] [--schema public]`, so this command
+// gains those same flags with zero new live-DB code path. If `--db` was never given (the existing,
+// unmodified call shape every current caller -- 5 CI smoke scripts, README's Quickstart -- already
+// uses), findCollisions() falls back to a persisted snapshot or reports fk_check:'unavailable';
+// the first 3 signals' findings and blocking behavior are byte-identical to before this item.
+async function cmdScanCrossFeatureCheck(args) {
+	const flags = parseCommand('scan cross-feature-check', args);
+	if (flags.help) { console.log(renderCommandHelp('scan cross-feature-check')); process.exit(0); }
+	setContext('scan cross-feature-check', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+
+	const liveDbSchema = await resolveDbSchemaOrExit(root, flags);
+	const { findings, fk_check, unknowns } = findCollisions(root, flags.feature, { liveDbSchema });
+	const report = {
+		schema: 'sbf.cross-feature-report/1',
+		feature_id: flags.feature,
+		generated_at: new Date().toISOString(),
+		findings,
+		fk_check,
+		unknowns,
+	};
+	const { ok, errors } = validateAgainstSchema('cross-feature-report.schema.json', report);
+	if (!ok) {
+		fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `internal error: the computed cross-feature report failed its own schema -- ${formatSchemaErrors(errors).join('; ')}`);
+	}
+	writeFileAtomic(crossFeatureReportPath(root, flags.feature), `${JSON.stringify(report, null, 2)}\n`);
+
+	const resolution = loadCrossFeatureResolution(root, flags.feature);
+	const evaluation = evaluateCrossFeatureFindings(findings, resolution);
+	const evidence = {
+		finding_count: findings.length,
+		high_confidence_count: findings.filter((f) => f.confidence === 'high').length,
+		waived_count: evaluation.waived.length,
+		stale_waivers: evaluation.staleWaivers.length,
+	};
+	const gateState = evaluation.blocking
+		? awaitNamedGateDisposition(root, 'cross_feature', flags.feature, { ...evidence, unwaived: evaluation.unwaived })
+		: passNamedGate(root, 'cross_feature', flags.feature, evidence);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ report, gate: gateState.gates.cross_feature }, null, 2));
+	} else {
+		if (!flags.quiet) {
+			const otherCount = new Set(findings.map((f) => f.other_feature)).size;
+			console.log(`${findings.length} finding(s) (${evidence.high_confidence_count} high-confidence) across ${otherCount} other feature(s)`);
+			for (const f of findings) console.log(`  [${f.confidence}] ${f.signal}: "${f.identifier}" also declared by ${f.other_feature}`);
+			// D-cross-feature-fk-inference (staleness/freshness token): the actual point of the field
+			// -- a human SEEING how stale a persisted/migrations-mode correlation is, not just the
+			// JSON carrying it silently.
+			const fkCheckDetails = [];
+			if (fk_check.source_feature) fkCheckDetails.push(`from ${fk_check.source_feature}'s own persisted snapshot`);
+			if (fk_check.generated_at) fkCheckDetails.push(`captured ${fk_check.generated_at}`);
+			console.log(`fk_check: ${fk_check.mode}${fkCheckDetails.length ? ` (${fkCheckDetails.join(', ')})` : ''}`);
+			for (const u of unknowns) console.log(`  note: ${u}`);
+			console.log(`gate: cross_feature -> ${gateState.gates.cross_feature.status}`);
+		}
+		if (evaluation.staleWaivers.length > 0) {
+			console.error(`\nnote: ${evaluation.staleWaivers.length} recorded waiver(s) no longer match any current finding (kept as-is, not auto-removed):`);
+			for (const w of evaluation.staleWaivers) console.error(`  ${w.signal} "${w.identifier}" (${w.other_feature})`);
+		}
+		if (evaluation.blocking) {
+			console.error(`\nblocked: ${evaluation.unwaived.length} unresolved high-confidence collision(s):`);
+			for (const f of evaluation.unwaived) {
+				console.error(`  bskel scan cross-feature-waive --feature ${flags.feature} --signal ${f.signal} --identifier "${f.identifier}" --other-feature ${f.other_feature} --reason "..."`);
+			}
+		}
+	}
+	process.exit(evaluation.blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
+}
+
+const CROSS_FEATURE_SIGNALS = ['resource_type', 'table', 'operation_id', 'db_foreign_key'];
+
+// Validates against the PERSISTED report from the last `cross-feature-check` run, never a live
+// re-computation -- same precedent `contract waive` already establishes against `loadContract`
+// (contracts/completeness.mjs). If reality moved since that check, the gate's own staleness token
+// (which covers every OTHER feature named in the report) is what surfaces that, not a silent
+// re-check inside this command.
+function cmdScanCrossFeatureWaive(args) {
+	const flags = parseCommand('scan cross-feature-waive', args);
+	if (flags.help) { console.log(renderCommandHelp('scan cross-feature-waive')); process.exit(0); }
+	setContext('scan cross-feature-waive', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+	requireValidFeatureId(flags['other-feature']);
+	if (!flags.reason || !flags.reason.trim()) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel scan cross-feature-waive requires --reason "..." -- every waiver must be auditable');
+	}
+	if (!CROSS_FEATURE_SIGNALS.includes(flags.signal)) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--signal must be one of: ${CROSS_FEATURE_SIGNALS.join(', ')}`);
+	}
+
+	const report = loadCrossFeatureReport(root, flags.feature);
+	if (!report) {
+		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no cross-feature-report.json for feature "${flags.feature}" -- run \`bskel scan cross-feature-check --feature ${flags.feature}\` first`);
+	}
+	const match = report.findings.find((f) => f.signal === flags.signal && f.identifier === flags.identifier && f.other_feature === flags['other-feature']);
+	if (!match) {
+		const known = report.findings.map((f) => `${f.signal} "${f.identifier}" (${f.other_feature})`);
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `no current finding matches --signal ${flags.signal} --identifier "${flags.identifier}" --other-feature ${flags['other-feature']} -- current findings: ${known.join('; ') || '(none)'}`);
+	}
+
+	const updated = withLockSync(root, 'state', () => {
+		const resolution = loadCrossFeatureResolution(root, flags.feature);
+		const key = waiverKey({ signal: flags.signal, identifier: flags.identifier, other_feature: flags['other-feature'] });
+		const entry = { signal: flags.signal, identifier: flags.identifier, other_feature: flags['other-feature'], reason: flags.reason, at: new Date().toISOString() };
+		const next = {
+			schema: 'sbf.cross-feature-resolution/1',
+			feature_id: flags.feature,
+			waivers: [...resolution.waivers.filter((w) => waiverKey(w) !== key), entry],
+		};
+		saveCrossFeatureResolution(root, flags.feature, next);
+		return next;
+	});
+
+	const evaluation = evaluateCrossFeatureFindings(report.findings, updated);
+	const evidence = {
+		finding_count: report.findings.length,
+		high_confidence_count: report.findings.filter((f) => f.confidence === 'high').length,
+		waived_count: evaluation.waived.length,
+		stale_waivers: evaluation.staleWaivers.length,
+	};
+	const gateState = evaluation.blocking
+		? awaitNamedGateDisposition(root, 'cross_feature', flags.feature, { ...evidence, unwaived: evaluation.unwaived })
+		: passNamedGate(root, 'cross_feature', flags.feature, evidence);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ waived: true, gate: gateState.gates.cross_feature }, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`waived: ${flags.signal} "${flags.identifier}" (${flags['other-feature']})`);
+		console.log(`gate: cross_feature -> ${gateState.gates.cross_feature.status}`);
+	}
+	process.exit(evaluation.blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
+}
+
 // D6 (D-feature-lifecycle): the whole read-specs/->compute-NNN->write-feature.json->
 // load-modify-save-feature-index.json sequence runs under one exclusive lock -- confirmed live
 // during this item's own grounding, the same lost-update shape S5 already fixed for setGate():
@@ -1600,14 +1868,29 @@ function cmdContractToolSchema(args) {
 	}
 
 	// Anthropic tool-use `input_schema` is a JSON Schema subset -- the operation's payload
-	// schema (already plain JSON Schema, no $ref/$defs) is directly usable as-is. A2: when `op`
-	// carries a projected `requestBodySchema`, it flows through here for free -- this function
-	// changed not at all; contracts/openapi.mjs's inlineSchema() is what guarantees the no-$ref
-	// promise this comment makes.
+	// schema is directly usable as-is UNLESS it's recursive. Confirmed against Anthropic's own
+	// documented JSON Schema limitations (platform.claude.com/docs/en/build-with-claude/
+	// structured-outputs): internal (non-external-URL) $ref/$defs ARE supported, but "recursive
+	// schemas" are explicitly listed as unsupported and return a real 400 error at the API. A2:
+	// when `op` carries a projected `requestBodySchema`, it flows through here for free -- this
+	// function changed not at all. D-openapi-cyclic-refs: contracts/openapi.mjs's inlineSchema()
+	// now emits `$ref`/`$defs` for a genuinely cyclic component (e.g. a real recursive
+	// filter-group tree) rather than failing the whole projection closed -- that's real progress
+	// for `contract validate`/`contract export`, but this ONE consumer genuinely cannot accept
+	// it: refuse explicitly here, citing the real reason, rather than emitting a schema that
+	// would only fail later at the actual Anthropic API call site.
+	const inputSchema = operationPayloadSchema(op);
+	if (inputSchema && Object.hasOwn(inputSchema, '$defs')) {
+		fail(
+			EXIT_CODES.NOT_PASSED,
+			'RECURSIVE_SCHEMA_UNSUPPORTED',
+			`operation "${flags.operation}"'s payload schema is recursive (a genuinely self-referential real shape, e.g. a nested filter-group tree) -- Anthropic tool-use input_schema does not support recursive schemas (see platform.claude.com/docs/en/build-with-claude/structured-outputs), so no tool-use schema can be generated for this operation`,
+		);
+	}
 	const toolSchema = {
 		name: flags.operation,
 		description: `${op.verb} ${op.path} (feature ${flags.feature})`,
-		input_schema: operationPayloadSchema(op),
+		input_schema: inputSchema,
 	};
 	console.log(JSON.stringify(toolSchema, null, 2));
 	process.exit(0);
@@ -1637,7 +1920,13 @@ function cmdStackApply(args) {
 	const root = requireRepoRoot();
 	requirePreflightPassed(root);
 	if (!flags.choice) {
-		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `usage: bskel stack apply --choice <id> [--apply] [--port N]   (known choices: ${listCatalogChoices().join(', ') || '(none)'})`);
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `usage: bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."]   (known choices: ${listCatalogChoices().join(', ') || '(none)'})`);
+	}
+	// D-write-safety-phase0 (item 2): mirrors handles emit's own --force/--reason validation --
+	// every overwrite of a file that diverged from what `stack apply` itself last wrote must be
+	// auditable.
+	if (flags.force && (!flags.reason || !flags.reason.trim())) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel stack apply --force requires --reason "..." -- every overwrite of a diverged generated file must be auditable');
 	}
 
 	let entry;
@@ -1661,12 +1950,21 @@ function cmdStackApply(args) {
 		process.exit(0);
 	}
 
-	let written;
+	let written, conflicts, fileHashes;
 	try {
-		written = applyPlan(root, plan);
+		({ written, conflicts, fileHashes } = applyPlan(root, plan, { force: flags.force }));
 	} catch (err) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
 	}
+	// D-write-safety-phase0 (item 2): a file that diverged from what `stack apply` itself last
+	// wrote is refused outright without --force -- mirrors handles emit's own conflict-refusal
+	// exactly, including the exit code family (a new, dedicated STACK_CONFLICT rather than reusing
+	// HANDLES_CONFLICT, since this is a different write surface).
+	if (conflicts.length > 0) {
+		console.error(`refusing to overwrite ${conflicts.length} file(s) that diverged from what \`bskel stack apply\` last generated${flags.force ? '' : ' -- pass --force --reason "..." to overwrite (only if the divergence is git-recoverable)'}:`);
+		for (const c of conflicts) console.error(`  ${c.path}\n    ${c.reason}`);
+		process.exit(EXIT_CODES.STACK_CONFLICT);
+	}
 	// S2: `applied_files` must be this choice's FULL file set in this repo (its desired state),
 	// not just whatever `applyPlan()` happened to write THIS run -- applyPlan() skips files whose
 	// action is 'unchanged', so a second, idempotent `--apply` used to overwrite this with `[]`,
@@ -1677,17 +1975,22 @@ function cmdStackApply(args) {
 		...plan.files.map((f) => f.path),
 		...(plan.envExampleActions.length > 0 ? ['.env.example'] : []),
 	])].sort();
+	// D-write-safety-phase0 (item 2): `fileHashes` only covers files applyPlan() actually wrote
+	// THIS run -- an unchanged file isn't in it, so this merges onto the PRIOR record's file_hashes
+	// (now a genuine read boundary -- planApply() reads this same record to classify files, see
+	// stack/apply.mjs) rather than replacing it wholesale, or an unchanged file's provenance would
+	// be lost on every apply after the first.
+	const priorRecord = readJsonIfExists(sbfPath(root, 'stack.json'));
 	const stackRecord = {
 		schema: 'sbf.stack/1', choice: flags.choice, applied_files: appliedFiles,
 		env_example_keys: plan.envExampleActions.map((e) => e.key), at: new Date().toISOString(),
+		file_hashes: { ...(priorRecord?.file_hashes ?? {}), ...fileHashes },
 	};
 	// S5 (D-persistence-integrity): schemas/stack-record.schema.json is new -- this record had NO
 	// schema at all before (not the same file as stack-choice.schema.json, which validates a
 	// stack/catalog/<id>.yml CATALOG ENTRY, a completely different persistence boundary). Validated
 	// before it touches disk, same "fail loud here" reasoning as every other write site this item
-	// touched. No corresponding read helper -- nothing in this codebase reads .sbf/stack.json back
-	// (confirmed by grep before adding this), so there's no read boundary to close yet; adding an
-	// unused loadStackRecord() export would just be dead code.
+	// touched.
 	{
 		const { ok, errors } = validateAgainstSchema('stack-record.schema.json', stackRecord);
 		if (!ok) {
@@ -1811,8 +2114,10 @@ function writeScanReportOrExit(reportPath, report) {
 }
 
 // D4 (D-handles-dryrun): the marker vocabulary a human report uses for classifyFile()'s 6
-// possible actions (+ the java-spring-only 'spec' kind, which reuses the same 3 labels since it's
-// classified the same 3-way create/unchanged/update, just outside classifyFile() itself).
+// possible actions (+ the 'spec' kind every observe.mjs provider uses for its always-regenerated
+// observed-schema.json, which reuses the same 3 labels since it's classified the same 3-way
+// create/unchanged/update, just outside classifyFile() itself -- migration.sql used to be the
+// other 'spec' user too, until D-write-safety-phase0 moved it onto real manifest tracking).
 const ACTION_MARKERS = { create: '+', unchanged: '=', update: '~', 'adopt-unchanged': '=', 'adopt-update': '~', conflict: '!' };
 
 // D4: shared between `handles plan`'s preview and `handles emit --check`'s report -- both show
@@ -2036,11 +2341,45 @@ function cmdHandlesEmit(args) {
 		});
 	}
 
+	// D-cross-feature-collision: making "mandatory disposition" actually mandatory, not just
+	// available -- `handles emit` is specifically the step that generates the runtime resolver
+	// code every codegen provider's own resourceType-keyed dispatch (Java/Python/TS, all three)
+	// already implicitly assumes is repo-unique. `cross_feature`'s own gate `verifyPolicy` stays
+	// REQUIRED_WHEN_PRESENT (so `bskel verify` doesn't retroactively fail a contract-only feature
+	// that never touches handles at all) -- this hard-requires it ONLY here, the one command where
+	// the real risk actually lives, mirroring the `contract` gate check immediately above exactly.
+	// Deliberately NOT added to `cmdHandlesPlan` -- that command never writes (dryRun always),
+	// same reasoning it already gives for skipping the `contract` gate entirely.
+	const crossFeatureResult = requireNamedGate(root, 'cross_feature', flags.feature);
+	if (crossFeatureResult.code !== EXIT.PASS) {
+		const cfHint = crossFeatureResult.status === 'awaiting_disposition'
+			? `resolve it first -- \`bskel scan cross-feature-waive --feature ${flags.feature} --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..."\`, or \`bskel gate force cross_feature --feature ${flags.feature} --reason "..."\` if intentional.`
+			: `run \`bskel scan cross-feature-check --feature ${flags.feature}\` first.`;
+		fail(crossFeatureResult.code, gateReasonForCode(crossFeatureResult.code), `blocked: \`cross_feature\` gate for ${flags.feature} is ${crossFeatureResult.status} -- ${cfHint}`, {
+			next_actions: [{ command: `bskel scan cross-feature-check --feature ${flags.feature}`, reason: 'the cross_feature gate has not passed yet', mutating: true }],
+		});
+	}
+
 	const scanReport = loadScanReportOrExit(root, flags.feature);
 	const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
 	requireCapabilitiesOrExit(scanReport, 'handles emit', { featureId: flags.feature, scanReportPath });
 	const provider = selectProviderOrExit(scanReport);
 	requireProviderCapabilitiesOrExit(scanReport, provider, 'handles emit', { featureId: flags.feature, scanReportPath });
+
+	// D-write-safety-phase1 (item 1): HandleAspect.java cannot intercept anything without
+	// spring-boot-starter-aop on the target's own classpath -- refusing here, before any code is
+	// written, rather than letting the operator discover it only after `--enforce-registry on`
+	// silently produces resolvers that will 404 every fetch/patch. java-spring only: python-fastapi's
+	// @record_snapshot decorator needs no extra dependency (see python-fastapi/emit.mjs's own note).
+	if (enforceRegistry && scanReport.adapter === 'java-spring' && !hasSpringAopDependency(root)) {
+		// D-handles-pilot-cohort: the correct artifact name is version-dependent (spring-boot-starter-aop
+		// before Spring Boot 4, spring-boot-starter-aspectj from Spring Boot 4 on -- confirmed against
+		// a real Spring Boot 4.1.0 target, the old artifact is a genuine 404 on Maven Central for it).
+		// springAopArtifactName(root) names the one THIS repo's own detected Boot version actually needs.
+		const artifactName = springAopArtifactName(root);
+		fail(EXIT_CODES.HANDLES_MISSING_DEPENDENCY, 'HANDLES_MISSING_DEPENDENCY', `bskel handles emit --enforce-registry on requires ${artifactName} on this repo's own build.gradle/build.gradle.kts/pom.xml classpath -- HandleAspect.java (the class that actually intercepts @RecordHandleSnapshot-annotated methods) does nothing without it, and no other Spring starter enables AOP. Add the dependency to your build file, then re-run.`);
+	}
+
 	const resourceFilter = flags.resource ? flags.resource.split(',').map((s) => s.trim()).filter(Boolean) : null;
 
 	let plan;
@@ -2053,7 +2392,7 @@ function cmdHandlesEmit(args) {
 	// a diff" that also means "and actually write it", so --diff forces dryRun the same as --check
 	// does, without requiring both flags together.
 	const dryRun = flags.check || flags.diff;
-	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [] } = provider.emit({
+	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [], registrationGaps = [] } = provider.emit({
 		repoRoot: root, featureId: flags.feature, plan, resourceFilter, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff, enforceRegistry,
 	});
 
@@ -2114,6 +2453,25 @@ function cmdHandlesEmit(args) {
 		process.exit(EXIT_CODES.HANDLES_CONFLICT);
 	}
 
+	// D-write-safety-phase1 (item 2): a registration gap is checked separately from `blocked`
+	// above (conflicts are already handled and exited by this point) -- semantically different
+	// reason (a hand-written file bskel never touches lacking an annotation it cannot add itself,
+	// not a generated file diverging), so its own dedicated exit code and message. Unlike a
+	// conflict, the resolver files ARE still written either way (there is nothing wrong with their
+	// content) -- only the overall command's reported success, and the `handles` gate passing, are
+	// gated on acknowledging the gap with --force --reason.
+	if (enforceRegistry && registrationGaps.length > 0 && !flags.force) {
+		if (flags.json) {
+			console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, registrationGaps, blocked: true, gate: null, check: dryRun }, null, 2));
+		} else {
+			const verb = dryRun ? 'would refuse to report success' : 'refusing to report success';
+			console.error(`${verb}: ${registrationGaps.length} resource(s) have --enforce-registry on but no static registration path found:`);
+			for (const g of registrationGaps) console.error(`  ${g.resourceType} (${g.file})\n    ${g.note}`);
+			if (!dryRun) console.error(`\nthe resolver file(s) above were still written -- nothing about their content is wrong. Fix the registration gap and re-run, or acknowledge and proceed with: bskel handles emit --feature ${flags.feature}${flags.module ? ` --module ${flags.module}` : ''}${flags.resource ? ` --resource ${flags.resource}` : ''} --enforce-registry on --force --reason "..."`);
+		}
+		process.exit(EXIT_CODES.HANDLES_REGISTRATION_GAP);
+	}
+
 	// D4: dryRun never marks the gate passed -- nothing real happened this run.
 	const gateState = dryRun ? null : passNamedGate(root, 'handles', flags.feature, { resolverStubs });
 
@@ -2211,6 +2569,189 @@ function cmdHandlesPatchApprove(args) {
 	process.exit(0);
 }
 
+// D-patch-transactions: Slice 1 (config_check -> config_apply). All four commands only touch
+// specs/<featureId>/patch-transactions/ except `apply`/`rollback`, which write to the real target
+// file too -- matching D4's own "propose/approve are specs/-only, apply/rollback touch the repo"
+// distinction cmdHandlesEmit/cmdHandlesPlan already draw for --check vs a real emit.
+// D-ddl-apply: `--kind` picks which patch-transaction kind to propose (default 'config-apply',
+// fully backward compatible -- every existing call site/script that never passed --kind gets the
+// exact prior behavior). Kind-specific params are validated by hand here (not via COMMANDS'
+// declarative `required: true`, which is unconditional per-flag) -- matches this file's own
+// existing convention for kind-conditional requirements (e.g. --reason on approve/rollback).
+async function cmdPatchPropose(args) {
+	const flags = parseCommand('patch propose', args);
+	if (flags.help) { console.log(renderCommandHelp('patch propose')); process.exit(0); }
+	setContext('patch propose', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+	const kind = flags.kind || 'config-apply';
+	if (!PATCH_KIND_NAMES.includes(kind)) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--kind must be one of: ${PATCH_KIND_NAMES.join(', ')}`);
+	}
+
+	let params;
+	let source;
+	if (kind === 'config-apply') {
+		if (!flags.choice || !flags.target) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel patch propose --kind config-apply requires --choice <stackChoiceId> --target <config_check target path>');
+		}
+		params = { choice: flags.choice, target: flags.target };
+		source = { choice: flags.choice };
+	} else {
+		if (!flags['database-url-env'] || !flags['sql-file']) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel patch propose --kind ddl-apply requires --database-url-env <NAME> --sql-file <path>');
+		}
+		let sqlText;
+		try {
+			sqlText = fs.readFileSync(flags['sql-file'], 'utf8');
+		} catch (err) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read --sql-file "${flags['sql-file']}": ${err.message}`);
+		}
+		params = { databaseUrlEnv: flags['database-url-env'], schema: flags.schema, sqlText };
+		source = { database_url_env: flags['database-url-env'], schema: flags.schema };
+	}
+
+	let plan;
+	try {
+		plan = await getPatchKind(kind).planFresh(root, params);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
+	}
+	const txn = proposeTransaction(root, flags.feature, kind, plan, source);
+
+	if (flags.json) {
+		console.log(JSON.stringify(txn, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`proposed: ${txn.transaction_id}`);
+		console.log(`  ${describePatchTransaction(txn)}`);
+		console.log(`next: bskel patch approve --feature ${flags.feature} --transaction ${txn.transaction_id} --reason "..."`);
+	}
+	process.exit(0);
+}
+
+// Kind-aware one-line summary, reused by propose/list's human-readable output -- config-apply's
+// target is a file+key_path, ddl-apply's is raw SQL text (truncated for a terminal line).
+function describePatchTransaction(txn) {
+	if (txn.kind === 'config-apply') {
+		return `${txn.target.file} @ ${txn.target.key_path.join('.')}: "${txn.current_value}" -> "${txn.proposed_value}"`;
+	}
+	const sql = txn.target.sql_text.replace(/\s+/g, ' ').trim();
+	return `[${txn.kind}] ${txn.target.database_url_env}/${txn.target.schema}: ${sql.slice(0, 100)}${sql.length > 100 ? '...' : ''}`;
+}
+
+function requireTransactionOrExit(root, featureId, transactionId) {
+	const txn = loadTransaction(root, featureId, transactionId);
+	if (!txn) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `no patch transaction "${transactionId}" for feature "${featureId}"`);
+	}
+	return txn;
+}
+
+async function cmdPatchApprove(args) {
+	const flags = parseCommand('patch approve', args);
+	if (flags.help) { console.log(renderCommandHelp('patch approve')); process.exit(0); }
+	setContext('patch approve', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+	if (!flags.reason || !flags.reason.trim()) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel patch approve requires --reason "..." -- every approval must be auditable');
+	}
+	const txn = requireTransactionOrExit(root, flags.feature, flags.transaction);
+
+	let freshPlan;
+	try {
+		freshPlan = await replanTransaction(root, txn);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
+	}
+	const updated = approveTransaction(root, flags.feature, flags.transaction, flags.reason, freshPlan);
+
+	console.log(flags.json ? JSON.stringify(updated, null, 2) : `approved: ${flags.transaction}`);
+	process.exit(0);
+}
+
+// D-ddl-apply: --confirm is required (and must exactly equal --transaction) for any kind other
+// than 'config-apply' -- deliberately checked here, at the CLI boundary, before applyTransaction()
+// is ever called, as human-factors friction layered ON TOP of the engine's own load-bearing
+// preimage-hash TOCTOU check (this check does not replace it). Optional/ignored for config-apply,
+// zero behavior change for that kind.
+async function cmdPatchApply(args) {
+	const flags = parseCommand('patch apply', args);
+	if (flags.help) { console.log(renderCommandHelp('patch apply')); process.exit(0); }
+	setContext('patch apply', flags);
+	const root = requireRepoRoot();
+	requirePreflightPassed(root);
+	requireValidFeatureId(flags.feature);
+	const txn = requireTransactionOrExit(root, flags.feature, flags.transaction);
+
+	const requiredConfirm = getPatchKind(txn.kind).requiredConfirmValue(txn);
+	if (requiredConfirm !== null && flags.confirm !== requiredConfirm) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `bskel patch apply --kind ${txn.kind} requires --confirm ${JSON.stringify(requiredConfirm)} exactly -- pass --confirm ${requiredConfirm} once you've reviewed this transaction`);
+	}
+
+	let freshPlan;
+	try {
+		freshPlan = await replanTransaction(root, txn);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
+	}
+	const updated = await applyTransaction(root, flags.feature, flags.transaction, freshPlan, getPatchKind(txn.kind).apply);
+
+	const evidence = { transaction_id: updated.transaction_id, kind: updated.kind, applied_at: updated.apply.at };
+	const gateState = passNamedGate(root, 'patch_transactions', flags.feature, evidence);
+
+	console.log(flags.json ? JSON.stringify({ transaction: updated, gate: gateState.gates.patch_transactions }, null, 2) : `applied: ${flags.transaction} [${updated.kind}]`);
+	process.exit(0);
+}
+
+async function cmdPatchRollback(args) {
+	const flags = parseCommand('patch rollback', args);
+	if (flags.help) { console.log(renderCommandHelp('patch rollback')); process.exit(0); }
+	setContext('patch rollback', flags);
+	const root = requireRepoRoot();
+	requirePreflightPassed(root);
+	requireValidFeatureId(flags.feature);
+	if (!flags.reason || !flags.reason.trim()) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel patch rollback requires --reason "..." -- every rollback must be auditable');
+	}
+	const txn = requireTransactionOrExit(root, flags.feature, flags.transaction);
+	const updated = await rollbackTransaction(root, flags.feature, flags.transaction, flags.reason, { force: flags.force }, getPatchKind(txn.kind).rollback);
+
+	// Re-passing (not revoking) mirrors cmdScanCrossFeatureWaive's own precedent for this exact
+	// situation -- recompute() only loops status:'applied' transactions, so a rolled-back one
+	// naturally drops out of the gate's own input set on the next pass; a fresh pass here reflects
+	// "still fine, just smaller" immediately rather than leaving the gate to be reactively
+	// discovered stale by the next `bskel verify`.
+	const evidence = { transaction_id: updated.transaction_id, kind: updated.kind, rolled_back_at: updated.rollback.at };
+	const gateState = passNamedGate(root, 'patch_transactions', flags.feature, evidence);
+
+	console.log(flags.json ? JSON.stringify({ transaction: updated, gate: gateState.gates.patch_transactions }, null, 2) : `rolled back: ${flags.transaction} [${updated.kind}]`);
+	process.exit(0);
+}
+
+// A deliberately-omitted-until-now, easy read-only convenience (D-patch-transactions' own EXIT
+// list named it explicitly) -- mirrors `dependency list`/`contract history`'s own pure-reader
+// posture, gate-independent like both.
+function cmdPatchList(args) {
+	const flags = parseCommand('patch list', args);
+	if (flags.help) { console.log(renderCommandHelp('patch list')); process.exit(0); }
+	setContext('patch list', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+	const transactions = listTransactions(root, flags.feature);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ feature: flags.feature, transactions }, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`patch transactions -- feature ${flags.feature}`);
+		for (const t of transactions) {
+			console.log(`  ${t.transaction_id} [${t.status}] ${describePatchTransaction(t)}`);
+		}
+		if (transactions.length === 0) console.log('  (none proposed)');
+	}
+	process.exit(0);
+}
+
 // O7 (D-handle-audit-report): a pure reader, deliberately gate-independent -- matches
 // D-contract-history/D-gate-export's own posture, not `handles plan`/`handles emit`'s capability
 // gating. It never touches adapter-specific codegen (the query is over `feature_uid` alone, the
@@ -2249,6 +2790,35 @@ async function cmdHandlesAudit(args) {
 	// D-openapi-extraction-hint's own precedent for "the CLI itself carries this warning, not
 	// just documentation").
 	const caveat = 'this reports what the target application chose to record via @RecordHandleSnapshot / record_snapshot -- it is NOT, and cannot be, a security control on its own (see O3/O5 in CATALOG.md for revocation enforcement and authorization contracts). Absence of a snapshot does not mean a handle was never used, only that recording was never opted into for that call path.';
+
+	// D-write-safety-phase1 (item 3): the live-database closure of D-handle-registry-enforcement's
+	// own named EXIT gap ("an already-empty registry... would need live target-app database
+	// access, a larger scope than this item's own"). Opt-in: resolves the CURRENT plan the same
+	// way `cmdHandlesPlan` does, then cross-references the rows already fetched above against each
+	// resource type the plan will actually generate a resolver for -- a real answer to "will
+	// --enforce-registry on 404 on its very first fetch for this resource", checked against the
+	// live database rather than a static regex proxy.
+	let registryCoverage = null;
+	if (flags['check-registry-coverage']) {
+		const scanReport = loadScanReportOrExit(root, flags.feature);
+		const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
+		requireCapabilitiesOrExit(scanReport, 'handles audit --check-registry-coverage', { featureId: flags.feature, scanReportPath });
+		const provider = selectProviderOrExit(scanReport);
+		requireProviderCapabilitiesOrExit(scanReport, provider, 'handles audit --check-registry-coverage', { featureId: flags.feature, scanReportPath });
+		let plan;
+		try {
+			plan = provider.plan({ repoRoot: root, scanReport, module: flags.module, resourceFilter: resourceTypes });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		registryCoverage = plan.resources
+			.filter((r) => r.willGenerateResolver)
+			.map((r) => ({
+				resourceType: r.type,
+				covered: rows.some((row) => row.resource_type === r.type && row.kind === 'r' && row.revoked_at === null),
+			}));
+	}
+
 	const report = {
 		schema: 'sbf.handle-audit/1',
 		feature_id: flags.feature,
@@ -2256,6 +2826,7 @@ async function cmdHandlesAudit(args) {
 		generated_at: new Date().toISOString(),
 		summary,
 		handles: rows,
+		registry_coverage: registryCoverage,
 		caveat,
 	};
 
@@ -2269,6 +2840,11 @@ async function cmdHandlesAudit(args) {
 			const pointerNote = h.pointer ? `#${h.pointer}` : '';
 			console.log(`  ${h.kind} ${h.resource_type}/${h.resource_uid}${pointerNote} -- ${h.snapshot_count} snapshot(s), last ${h.last_recorded_at ?? 'never'}${revokedNote}`);
 		}
+		if (registryCoverage) {
+			console.log('\nregistry coverage (would --enforce-registry on 404 on the first fetch for this resource?):');
+			for (const c of registryCoverage) console.log(`  ${c.resourceType}: ${c.covered ? 'covered' : 'NOT COVERED -- no non-revoked kind=r row exists yet'}`);
+			if (registryCoverage.length === 0) console.log('  (no resources in this plan will generate a resolver)');
+		}
 		console.error(`\nnote: ${caveat}`);
 	}
 	process.exit(0);
@@ -2341,8 +2917,23 @@ function cmdObserveEmit(args) {
 		} catch (err) {
 			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
 		}
+	} else if (scanReport.adapter === 'typescript-express') {
+		// typescript-express's own project-root detection needs a module to anchor itself too (same
+		// reasoning as python-fastapi's own --module dependency) -- plan.mjs's detectProjectRoot()
+		// walks up from the module's own scanned files.
+		let tsPlan;
+		try {
+			tsPlan = planTypeScriptExpress({ repoRoot: root, scanReport, module: flags.module, resourceFilter: null });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		try {
+			result = emitObserveTypeScriptExpress({ repoRoot: root, featureId: flags.feature, contract, plan: tsPlan, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
 	} else {
-		fail(EXIT_CODES.MISSING_CAPABILITY, 'MISSING_CAPABILITY', `bskel observe emit does not support the "${scanReport.adapter}" adapter yet (supported: java-spring, python-fastapi)`);
+		fail(EXIT_CODES.MISSING_CAPABILITY, 'MISSING_CAPABILITY', `bskel observe emit does not support the "${scanReport.adapter}" adapter yet (supported: java-spring, python-fastapi, typescript-express)`);
 	}
 	const { written, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [] } = result;
 	const wouldChange = actions.some((a) => a.action !== 'unchanged' && a.action !== 'adopt-unchanged');
@@ -2493,11 +3084,20 @@ function cmdObserveImport(args) {
 	const reportPath = specPath(root, flags.feature, 'observe', `${flags.feature}.conformance-report.json`);
 	writeFileAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`);
 
-	// Evidence-first, not verdict-first (same as `contract`'s own precedent: a `partial` contract
-	// is still passable via waiver) -- passes on a successful STRUCTURAL import, never on "zero
-	// violations found". Whether violation counts should block CI is a policy question for whoever
-	// reads the report, deliberately not decided here -- see DECISIONS.md's own deferred list.
-	const gateState = passNamedGate(root, 'conformance', flags.feature, { receipt_count: receipts.length, matched, violations: violationCount });
+	// Evidence-first, not verdict-first by DEFAULT (same as `contract`'s own precedent: a `partial`
+	// contract is still passable via waiver) -- passes on a successful STRUCTURAL import, never on
+	// "zero violations found", unless --fail-on-violation opts into the stricter behavior. Whether
+	// violation counts should block CI was a policy question deliberately left undecided in v1 --
+	// this is that v1.1 layer, see D-runtime-conformance-receipts's own "Continued" entry in
+	// DECISIONS.md. `awaitNamedGateDisposition` is the EXACT same disposition mechanism `contract`
+	// already uses for "evidence exists but isn't good enough to pass silently" -- resolved by the
+	// already-generic `bskel gate force conformance --feature <id> --reason "..."` (no new CLI verb
+	// needed; `bskel next`'s own generic awaitingDispositionCommand() fallback already names it).
+	const evidence = { receipt_count: receipts.length, matched, violations: violationCount };
+	const blocking = flags['fail-on-violation'] && violationCount > 0;
+	const gateState = blocking
+		? awaitNamedGateDisposition(root, 'conformance', flags.feature, evidence)
+		: passNamedGate(root, 'conformance', flags.feature, evidence);
 
 	if (flags.json) {
 		console.log(JSON.stringify({ report, noise_lines: noiseLines, gate: gateState.gates.conformance }, null, 2));
@@ -2506,8 +3106,11 @@ function cmdObserveImport(args) {
 		console.log(`${violationCount} violation(s), ${unsupportedCount} unsupported field(s) across matched receipts`);
 		console.log(`wrote ${path.relative(root, reportPath)}`);
 		console.log(`gate: conformance -> ${gateState.gates.conformance.status}`);
+		if (blocking) {
+			console.error(`\nblocked: ${violationCount} violation(s) found (--fail-on-violation) -- review ${path.relative(root, reportPath)}, then \`bskel gate force conformance --feature ${flags.feature} --reason "..."\` once accounted for.`);
+		}
 	}
-	process.exit(0);
+	process.exit(blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
 }
 
 // S2: "stale" alone sends a human/agent re-running steps until one happens to stick. Name the
@@ -2532,10 +3135,17 @@ function renderVerifyReport({ featureId, gates, artifacts, conflicts, build, all
 		const completenessNote = g.gate === 'contract' && evidence?.completeness
 			? ` (${evidence.completeness}${evidence.waived_count ? `: ${evidence.waived_count} waived` : ''})`
 			: '';
+		// D-runtime-conformance-receipts (Continued, --fail-on-violation): same "surface the evidence
+		// right in the verify report" precedent as `completenessNote` above -- fires for both `pass`
+		// and `awaiting_disposition` states, since a human should see the count even when it didn't
+		// end up blocking (i.e. --fail-on-violation wasn't used at import time).
+		const conformanceNote = g.gate === 'conformance' && evidence?.violations
+			? ` (${evidence.violations} violation(s), ${evidence.matched}/${evidence.receipt_count} matched)`
+			: '';
 		// S4 (D-gate-history): a revoked gate's reason is exactly the kind of "why is this
 		// blocking" detail describeStale() already surfaces for stale gates -- same treatment here.
 		const revokedNote = g.status === 'revoked' && g.record?.reason ? ` (revoked: ${g.record.reason})` : '';
-		lines.push(`- [${marker}] ${g.gate}${suffix}${completenessNote}${describeStale(g)}${revokedNote}`);
+		lines.push(`- [${marker}] ${g.gate}${suffix}${completenessNote}${conformanceNote}${describeStale(g)}${revokedNote}`);
 	}
 	lines.push('', '## Artifacts');
 	for (const a of artifacts) lines.push(`- [${a.exists ? 'OK' : 'MISSING'}] ${a.artifact}: ${a.path}`);
@@ -2747,19 +3357,46 @@ async function cmdServe(args) {
 	const root = requireRepoRoot();
 	const port = Number.parseInt(flags.port, 10);
 
+	// D-ddl-apply: eagerly checked here, at startup -- the DB-touching routes must not silently
+	// 404 forever because of a typo'd env var name; missing/unset is BAD_ARGS at the CLI boundary,
+	// same convention as resolveDbSchemaOrExit's own `bskel scan --db` handling. The live
+	// connection itself still only ever opens lazily, per-request (no eager connect-at-startup, no
+	// pool) -- a transient DB outage must not block the unrelated, DB-independent parts of the UI.
+	let dbConfig = null;
+	if (flags['database-url-env']) {
+		if (!process.env[flags['database-url-env']]) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--database-url-env ${flags['database-url-env']} names an environment variable that isn't set -- export it first (never read from .env directly; see D-db-schema-plane in DECISIONS.md)`);
+		}
+		dbConfig = { databaseUrlEnv: flags['database-url-env'], schema: flags.schema, signKeyPath: flags['sign-key'] };
+		// D-ddl-apply: closes this feature's own named "mandatory signing... cheap, well-justified
+		// near-term addition" EXIT item -- an opt-in-to-MORE-strictness knob, letting a cautious team
+		// enforce mandatory signing for themselves without this tool forcing it on every user. A
+		// no-op when --database-url-env wasn't given at all (this whole block never runs then) --
+		// nothing to enforce on a DDL surface that isn't running.
+		if (flags['require-sign-key'] && !dbConfig.signKeyPath) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--require-sign-key was given but --sign-key was not -- refusing to start the DDL surface without an audit-signing key. Pass --sign-key <path>, or drop --require-sign-key to allow starting unsigned (with a warning).');
+		}
+	}
+
 	let started;
 	try {
-		started = await createHttpServer(root, { host: flags.host, port });
+		started = await createHttpServer(root, { host: flags.host, port, dbConfig });
 	} catch (err) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not start server: ${err.message}`);
 	}
 
 	if (flags.json) {
-		console.log(JSON.stringify({ listening: started.url, host: started.host, port: started.port, repo: root }));
+		console.log(JSON.stringify({ listening: started.url, host: started.host, port: started.port, repo: root, ddlApplyEnabled: Boolean(dbConfig) }));
 	} else if (!flags.quiet) {
 		console.log(`bskel serve -- listening on ${started.url}`);
 		console.log(`  UI:  ${started.url}/`);
 		console.log(`  API: ${started.url}/api/...`);
+		if (dbConfig) {
+			console.log(`  DDL apply routes: ENABLED (schema "${dbConfig.schema}", connection from $${dbConfig.databaseUrlEnv})`);
+			if (!dbConfig.signKeyPath) {
+				console.log('  WARNING: no --sign-key given -- every propose/approve/apply is recorded in specs/ but NOT cryptographically attested. Pass --sign-key <path> to change this.');
+			}
+		}
 		console.log('press Ctrl+C to stop');
 	}
 
@@ -2988,6 +3625,8 @@ async function dispatchCommand(cmd, rest) {
 		case 'scan': {
 			if (rest[0] === 'disposition') return cmdScanDisposition(rest.slice(1));
 			if (rest[0] === 'explain') return cmdScanExplain(rest.slice(1));
+			if (rest[0] === 'cross-feature-check') return cmdScanCrossFeatureCheck(rest.slice(1));
+			if (rest[0] === 'cross-feature-waive') return cmdScanCrossFeatureWaive(rest.slice(1));
 			await cmdScan(rest);
 			break;
 		}
@@ -3031,6 +3670,16 @@ async function dispatchCommand(cmd, rest) {
 			process.exit(14);
 			break;
 		}
+		case 'patch': {
+			if (rest[0] === 'propose') return cmdPatchPropose(rest.slice(1));
+			if (rest[0] === 'approve') return cmdPatchApprove(rest.slice(1));
+			if (rest[0] === 'apply') return cmdPatchApply(rest.slice(1));
+			if (rest[0] === 'rollback') return cmdPatchRollback(rest.slice(1));
+			if (rest[0] === 'list') return cmdPatchList(rest.slice(1));
+			usage();
+			process.exit(14);
+			break;
+		}
 		case 'catalog': {
 			if (rest[0] === 'lint') return cmdCatalogLint(rest.slice(1));
 			usage();
@@ -3075,6 +3724,13 @@ async function dispatchCommand(cmd, rest) {
 			process.exit(14);
 			break;
 		}
+		case 'attest': {
+			if (rest[0] === 'keygen') return cmdAttestKeygen(rest.slice(1));
+			if (rest[0] === 'verify') return cmdAttestVerify(rest.slice(1));
+			usage();
+			process.exit(14);
+			break;
+		}
 		case 'doctor':
 			cmdDoctor(rest);
 			break;