backend-skeleton 1.0.0-beta.9 → 1.0.0

package/bin/bskel.mjs

@@ -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,
@@ -52,6 +59,8 @@ import { detectBasePackage } from '../handles/providers/java-spring/plan.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 +79,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]
@@ -91,8 +102,13 @@ function usage() {
   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 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 +117,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 +411,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 +431,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 +477,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 +761,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():
@@ -2036,6 +2303,25 @@ 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 });
@@ -2211,6 +2497,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
@@ -2341,8 +2810,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 +2977,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 +2999,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 +3028,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 +3250,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 +3518,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 +3563,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 +3617,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;