backend-skeleton 1.5.0 → 1.7.0

package/bin/bskel.mjs

@@ -9,6 +9,7 @@ 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 { buildGateExportReport, readGateHistory } from '../lib/gate-export.mjs';
 import { writeFileAtomic, sha256File, readJsonIfExists } from '../lib/fsutil.mjs';
 import { hydrateScanReportFilePaths, dehydrateScanReportFilePaths } from '../lib/scan-report-paths.mjs';
 import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
@@ -29,17 +30,23 @@ import { ADAPTERS, LOAD_ERRORS, adapterById } from '../scanners/registry.mjs';
 import { COMMAND_CAPABILITIES, CAPABILITY_SATISFIERS, explainMissingCapability } from '../scanners/capabilities.mjs';
 import { buildContract, selectModule, CONTRACT_SCHEMA_VERSION } from '../contracts/emit.mjs';
 import { validateEnvelope, operationPayloadSchema } from '../contracts/validate.mjs';
-import { evaluateResolution, loadResolution, saveResolution, requireWarningCode, warningKey, countByCode } from '../contracts/completeness.mjs';
+import { evaluateResolution, loadResolution, saveResolution, requireWarningCode, warningKey, countByCode, isWaiverExpired } from '../contracts/completeness.mjs';
 import { loadPatchApprovals, savePatchApprovals, approvalKey } from '../lib/patch-approvals.mjs';
+import { appendDecisionEvent, readDecisionLog } from '../lib/decision-log.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 { generateKeypair, signPayload, verifyPayload, publicKeyIdFromPrivate, publicKeyIdFromPublic } 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 {
+	ImpactOperationError, checkImpact, acceptImpact, recordDisposition, acknowledgeInbound, withdrawDisposition,
+} from '../lib/impact.mjs';
+import { buildImpactGraph } from '../lib/impact-graph.mjs';
+import { toGraphifyExtraction, toMermaid } from '../lib/impact-export-graphify.mjs';
 import {
 	findCollisions, evaluateCrossFeatureFindings, waiverKey,
 	crossFeatureReportPath, loadCrossFeatureReport, loadCrossFeatureResolution, saveCrossFeatureResolution,
@@ -97,6 +104,7 @@ function usage() {
   bskel scan repair --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 scan cross-feature-unwaive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..." [--json]
   bskel feature init --slug <name>
   bskel feature list [--all] [--json]
   bskel feature show <id> [--json]
@@ -111,9 +119,15 @@ function usage() {
   bskel contract validate --feature <id> --file <envelope.json>
   bskel contract tool-schema --feature <id> --operation <operationId>
   bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path"|--all) --reason "..." [--expires <Nd>]
+  bskel contract unwaive --feature <id> --code <CODE> --subject "VERB /path" --reason "..." [--json]
   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 impact check --feature <id> [--all] [--json]
+  bskel impact accept --feature <id> [--json]
+  bskel impact disposition --feature <id> --change <change_key> --downstream <id> (--mode <compatible|migrate|waive> [--tracked-by "..."] [--expires-days <N>] | --withdraw) --reason "..." [--json]
+  bskel impact ack --feature <id> --from <id> --change <change_key> --reason "..." [--json]
+  bskel impact export --format <graphify|json|mermaid> [--out <path>] [--focus <id>] [--rings <N>]
   bskel rules check --feature <id> [--init] [--json]
   bskel rules list --feature <id> [--json]
   bskel rules explain --feature <id> --rule <id> [--json]
@@ -123,8 +137,9 @@ function usage() {
   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 patch unapprove --feature <id> --resource <Type> --field <name> --reason "..." [--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 propose --feature <id> [--kind config-apply|ddl-apply|java-source-splice] --choice <stackChoiceId> --target <config_check target path> --database-url-env <NAME> --schema <name> --sql-file <path> --splice-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]
@@ -139,9 +154,9 @@ 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>] [--sign --key <privateKeyPath>] [--json]
+  bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath> [--allow-dirty]] [--json]
   bskel attest keygen --out <dir> [--force] [--json]
-  bskel attest verify --file <path> --pubkey <path> [--json]
+  bskel attest verify --file <path> --pubkey <path> [--expect-head <sha>] [--max-age-minutes N] [--reject-dirty] [--json]
   bskel doctor [--workflow ${DOCTOR_WORKFLOWS.join('|')}] [--json]
   bskel serve [--port N] [--host <addr>] [--database-url-env <NAME>] [--schema <name>] [--sign-key <path>] [--require-sign-key] [--json]
 `);
@@ -352,32 +367,6 @@ function cmdGateRevoke(args) {
 	process.exit(EXIT_CODES.NOT_PASSED);
 }
 
-// S4 (D-gate-history): reads the append-only .sbf/<feature>.history.jsonl -- a corrupt/invalid
-// line is skipped with a warning, not a hard failure, matching JSONL's own resilience rationale
-// (see lib/state.mjs's appendGateEvent).
-function readGateHistory(root, featureId, gateName) {
-	const file = historyPath(root, featureId);
-	if (!fs.existsSync(file)) return [];
-	const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
-	const events = [];
-	for (const [i, line] of lines.entries()) {
-		let parsed;
-		try {
-			parsed = JSON.parse(line);
-		} catch {
-			console.error(`warning: ${file}:${i + 1}: not valid JSON, skipped`);
-			continue;
-		}
-		const { ok, errors } = validateAgainstSchema('gate-event.schema.json', parsed);
-		if (!ok) {
-			console.error(`warning: ${file}:${i + 1}: does not match schemas/gate-event.schema.json, skipped:\n${formatSchemaErrors(errors).join('\n')}`);
-			continue;
-		}
-		if (parsed.gate === gateName) events.push(parsed);
-	}
-	return events;
-}
-
 function cmdGateHistory(args) {
 	const flags = parseCommand('gate history', args);
 	if (flags.help) { console.log(renderCommandHelp('gate history')); process.exit(0); }
@@ -386,7 +375,11 @@ function cmdGateHistory(args) {
 	const gateName = flags._[0];
 	if (!gateName) fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'usage: bskel gate history <name> [--feature <id>] [--json]');
 	resolveGateArg(gateName, flags.feature);
-	const events = readGateHistory(root, flags.feature, gateName);
+	// S4 (D-gate-history): a corrupt/invalid history line is skipped with a warning, not a hard
+	// failure, matching JSONL's own resilience rationale (see lib/state.mjs's appendGateEvent).
+	const events = readGateHistory(root, flags.feature, gateName, {
+		onWarning: (msg, errors) => console.error(`warning: ${msg}${errors ? `:\n${formatSchemaErrors(errors).join('\n')}` : ''}`),
+	});
 	if (flags.json) {
 		console.log(JSON.stringify(events, null, 2));
 	} else if (events.length === 0) {
@@ -439,20 +432,15 @@ function cmdGateExport(args) {
 	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) {
-		const scopeId = gateScopeId(name, flags.feature);
-		gates[name] = { scope: scopeId, current: getGate(root, scopeId, name), history: readGateHistory(root, scopeId, name) };
+	// D-attestation-payload-completeness (K4): --allow-dirty only means something alongside --sign
+	// -- an unsigned export never refuses a dirty tree (unchanged behavior), so a bare --allow-dirty
+	// would otherwise be a silently-ignored flag, the exact failure mode D-cli-contract already
+	// refuses everywhere else.
+	if (flags['allow-dirty'] && !flags.sign) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--allow-dirty only has an effect together with --sign -- an unsigned gate export never refuses a dirty tree');
 	}
 
-	const report = {
-		schema: 'sbf.gate-export/1',
-		feature_id: flags.feature,
-		generated_at: new Date().toISOString(),
-		git: { branch: currentBranch(root), head_sha: headSha(root), dirty: isDirty(root) },
-		gates,
-	};
+	const report = buildGateExportReport(root, flags.feature, { dirtyAcknowledged: Boolean(flags['allow-dirty']) });
 	// 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.
 	{
@@ -464,6 +452,20 @@ function cmdGateExport(args) {
 
 	let payload = report;
 	if (flags.sign) {
+		// D-attestation-payload-completeness (K4): refuses to sign over a dirty working tree unless
+		// explicitly acknowledged -- direct reuse of scripts/preflight-base-ref.sh's own already-
+		// shipped --allow-dirty convention (same flag name, same DIRTY exit code, same reasoning: "so
+		// evidence can honestly distinguish 'clean tree, passed' from 'dirty tree, --allow-dirty
+		// overrode it'"). Signing is a strictly stronger claim than preflighting, so it cannot be
+		// laxer. `report.git.dirty === true` is checked specifically, not truthiness -- isDirty()
+		// (and therefore this field) can be `null` when git itself failed, and "we could not
+		// determine dirtiness" must not silently pass this refusal.
+		if (report.git.dirty === null) {
+			fail(EXIT_CODES.DIRTY, 'DIRTY', 'refusing to sign an attestation: could not determine whether the working tree is dirty (git status failed) -- fix the git error, or pass --allow-dirty to sign anyway.');
+		}
+		if (report.git.dirty === true && !flags['allow-dirty']) {
+			fail(EXIT_CODES.DIRTY, 'DIRTY', `refusing to sign an attestation over a dirty working tree (${report.git.dirty_file_count} uncommitted change(s)) -- commit/stash them, or pass --allow-dirty to sign anyway (the acknowledgement is recorded inside the signed payload). The same refusal \`bskel preflight\` already makes.`);
+		}
 		let privateKeyPem;
 		try {
 			privateKeyPem = fs.readFileSync(path.resolve(process.cwd(), flags.key), 'utf8');
@@ -471,12 +473,14 @@ function cmdGateExport(args) {
 			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read --key "${flags.key}": ${err.message}`);
 		}
 		let signatureValue;
+		let keyId;
 		try {
 			signatureValue = signPayload(report, privateKeyPem);
+			keyId = publicKeyIdFromPrivate(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 attestation = { schema: 'sbf.gate-attestation/1', report, signature: { algorithm: 'ed25519', value: signatureValue, key_id: keyId } };
 		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('; ')}`);
@@ -489,9 +493,11 @@ function cmdGateExport(args) {
 		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;
+			const passCount = report.verdict.passing;
 			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)' : ''}`);
+			const dirtyNote = report.git.dirty ? (report.git.dirty_acknowledged ? ', dirty (acknowledged)' : ', dirty') : '';
+			const blockingNote = report.verdict.blocking_gates.length > 0 ? ` -- blocking: ${report.verdict.blocking_gates.join(', ')}` : '';
+			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)'}${dirtyNote}${blockingNote}`);
 		}
 	} else {
 		console.log(rendered);
@@ -562,13 +568,64 @@ function cmdAttestVerify(args) {
 	const valid = verifyPayload(attestation.report, attestation.signature.value, publicKeyPem);
 	const passCount = GATE_NAMES.filter((n) => attestation.report.gates[n]?.current?.status === 'pass').length;
 
+	// D-attestation-payload-completeness (K5): three OPT-IN, default-off assertions, evaluated
+	// purely against fields already inside the report (so verification stays fully offline and
+	// repo-independent). They exist for both sbf.gate-export/1 and /2 reports -- head_sha/
+	// generated_at/dirty are unchanged fields from /1, nothing here needed a /2-only field.
+	const assertions = [];
+	if (flags['expect-head']) {
+		const actual = attestation.report.git?.head_sha ?? null;
+		const ok = actual === flags['expect-head'];
+		assertions.push({ name: 'expect-head', ok, detail: ok ? `head_sha matches ${flags['expect-head']}` : `report's head_sha is "${actual}", expected "${flags['expect-head']}"` });
+	}
+	const maxAgeMinutes = flags['max-age-minutes'] != null ? Number(flags['max-age-minutes']) : 0;
+	if (maxAgeMinutes > 0) {
+		const generatedAtMs = Date.parse(attestation.report.generated_at);
+		const ageSeconds = Number.isFinite(generatedAtMs) ? Math.max(0, Math.round((Date.now() - generatedAtMs) / 1000)) : null;
+		const ok = ageSeconds !== null && ageSeconds <= maxAgeMinutes * 60;
+		assertions.push({ name: 'max-age-minutes', ok, detail: ageSeconds === null ? `report's generated_at ("${attestation.report.generated_at}") is not a parseable timestamp` : `age ${ageSeconds}s, limit ${maxAgeMinutes * 60}s` });
+	}
+	if (flags['reject-dirty']) {
+		const dirty = attestation.report.git?.dirty ?? null;
+		const ok = dirty !== true;
+		assertions.push({ name: 'reject-dirty', ok, detail: ok ? 'report is not dirty' : 'report.git.dirty === true' });
+	}
+	const assertionsOk = assertions.every((a) => a.ok);
+
+	// D-attestation-payload-completeness (K6): key_id is a SELECTION HINT only -- it sits OUTSIDE
+	// the signed bytes (only `report` is signed), so it cannot change whether `valid` is true. It
+	// exists purely to make a wrong---pubkey mistake legible instead of an unexplained INVALID.
+	let keyIdNote = null;
+	if (attestation.signature.key_id) {
+		try {
+			const actualKeyId = publicKeyIdFromPublic(publicKeyPem);
+			if (attestation.signature.key_id !== actualKeyId) {
+				keyIdNote = `this attestation declares key_id ${attestation.signature.key_id}, but --pubkey is ${actualKeyId} -- you may have the wrong public key`;
+			}
+		} catch {
+			// A --pubkey that isn't even a parseable key already drives verifyPayload() to false
+			// above; nothing more useful to say here.
+		}
+	}
+	const legacyReport = attestation.report.schema === 'sbf.gate-export/1';
+
 	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));
+		console.log(JSON.stringify({
+			valid,
+			report_format: attestation.report.schema ?? 'sbf.gate-export/1',
+			report_summary: { feature_id: attestation.report.feature_id, generated_at: attestation.report.generated_at, gates_passing: `${passCount}/${GATE_NAMES.length}` },
+			assertions,
+			key_id_note: keyIdNote,
+		}, 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');
+		if (legacyReport) console.log('report format: sbf.gate-export/1 (pre-D-attestation-payload-completeness -- no tool version, no live gate verdict)');
+		if (keyIdNote) console.log(`note: ${keyIdNote}`);
 		console.log(`report says: feature ${attestation.report.feature_id}, ${passCount}/${GATE_NAMES.length} gate(s) passing, generated ${attestation.report.generated_at}`);
+		for (const a of assertions) console.log(`assertion ${a.name}: ${a.ok ? 'ok' : 'FAILED'} -- ${a.detail}`);
 	}
-	process.exit(valid ? EXIT_CODES.OK : EXIT_CODES.CHECK_FAILED);
+	if (!valid) process.exit(EXIT_CODES.CHECK_FAILED);
+	process.exit(assertionsOk ? EXIT_CODES.OK : EXIT_CODES.ATTESTATION_ASSERTION_FAILED);
 }
 
 // Structural enforcement of "preflight blocks everything below it" (see the workflow table in
@@ -972,6 +1029,10 @@ function cmdScanCrossFeatureWaive(args) {
 			waivers: [...resolution.waivers.filter((w) => waiverKey(w) !== key), entry],
 		};
 		saveCrossFeatureResolution(root, flags.feature, next);
+		appendDecisionEvent(root, flags.feature, {
+			kind: 'cross_feature_waiver', action: 'record', at: entry.at, reason: entry.reason, feature_id: flags.feature,
+			subject: { signal: entry.signal, identifier: entry.identifier, other_feature: entry.other_feature },
+		});
 		return next;
 	});
 
@@ -995,6 +1056,64 @@ function cmdScanCrossFeatureWaive(args) {
 	process.exit(evaluation.blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
 }
 
+// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+// waiver entry and appends a `withdraw` decision event. Never a snapshot restore.
+function cmdScanCrossFeatureUnwaive(args) {
+	const flags = parseCommand('scan cross-feature-unwaive', args);
+	if (flags.help) { console.log(renderCommandHelp('scan cross-feature-unwaive')); process.exit(0); }
+	setContext('scan cross-feature-unwaive', 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-unwaive requires --reason "..." -- every withdrawal must be auditable');
+	}
+	const report = loadCrossFeatureReport(root, flags.feature);
+	if (!report) {
+		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no cross-feature-report.json for feature "${flags.feature}"`);
+	}
+	const key = waiverKey({ signal: flags.signal, identifier: flags.identifier, other_feature: flags['other-feature'] });
+
+	const updated = withLockSync(root, 'state', () => {
+		const resolution = loadCrossFeatureResolution(root, flags.feature);
+		const match = resolution.waivers.find((w) => waiverKey(w) === key);
+		if (!match) {
+			fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no waiver recorded for --signal ${flags.signal} --identifier "${flags.identifier}" --other-feature ${flags['other-feature']} -- nothing to unwaive`);
+		}
+		const at = new Date().toISOString();
+		const next = {
+			schema: 'sbf.cross-feature-resolution/1',
+			feature_id: flags.feature,
+			waivers: resolution.waivers.filter((w) => waiverKey(w) !== key),
+		};
+		saveCrossFeatureResolution(root, flags.feature, next);
+		appendDecisionEvent(root, flags.feature, {
+			kind: 'cross_feature_waiver', action: 'withdraw', at, reason: flags.reason, feature_id: flags.feature,
+			subject: { signal: match.signal, identifier: match.identifier, other_feature: match.other_feature },
+		});
+		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({ withdrawn: true, gate: gateState.gates.cross_feature }, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`unwaived: ${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():
@@ -1860,20 +1979,38 @@ function cmdContractWaive(args) {
 	// entries). Locking only the final write (inside saveResolution()) would NOT close this race --
 	// the window is between this function's own loadResolution() read and its save, not inside the
 	// write call itself.
-	const { resolution: updatedResolution, newEntries } = withLockSync(root, 'state', () => {
+	// D-waiver-renewal: `existingKeys` -- the "already waived, do nothing" set -- must only contain
+	// keys of waivers that are still LIVE. Before this fix it was built from every stored waiver
+	// regardless of expires_at, so an expired waiver's key permanently "existed" and every renewal
+	// attempt matched it and produced zero new entries (see contracts/completeness.mjs's
+	// isWaiverExpired() for the shared predicate this now shares with evaluateResolution() -- the
+	// two were previously two unsynchronized inline checks). A renewal replaces the expired entry
+	// (same key never appears twice) rather than appending alongside it, which would otherwise leave
+	// evaluateResolution()'s expiredKeys/waivedKeys sets computing over two same-key entries.
+	const { resolution: updatedResolution, newEntries, renewedEntries } = withLockSync(root, 'state', () => {
 		const resolution = loadResolution(root, flags.feature);
-		const existingKeys = new Set((resolution.waivers ?? []).map(warningKey));
+		const now = Date.now();
+		const liveWaivers = (resolution.waivers ?? []).filter((w) => !isWaiverExpired(w, now));
+		const expiredKeys = new Set((resolution.waivers ?? []).filter((w) => isWaiverExpired(w, now)).map(warningKey));
+		const liveKeys = new Set(liveWaivers.map(warningKey));
 		const at = new Date().toISOString();
-		const entries = toWaive
-			.filter((w) => !existingKeys.has(warningKey(w)))
-			.map((w) => ({ code: w.code, subject: w.subject, reason: flags.reason, at, ...(expiresAt ? { expires_at: expiresAt } : {}) }));
+		const toRecord = toWaive.filter((w) => !liveKeys.has(warningKey(w)));
+		const entries = toRecord.map((w) => ({ code: w.code, subject: w.subject, reason: flags.reason, at, ...(expiresAt ? { expires_at: expiresAt } : {}) }));
+		const newEntriesOut = entries.filter((e) => !expiredKeys.has(warningKey(e)));
+		const renewedEntriesOut = entries.filter((e) => expiredKeys.has(warningKey(e)));
 		const next = {
 			schema: 'sbf.contract-resolution/1',
 			feature_id: flags.feature,
-			waivers: [...(resolution.waivers ?? []), ...entries],
+			waivers: [...liveWaivers, ...entries],
 		};
 		saveResolution(root, flags.feature, next);
-		return { resolution: next, newEntries: entries };
+		for (const e of newEntriesOut) {
+			appendDecisionEvent(root, flags.feature, { kind: 'contract_waiver', action: 'record', at: e.at, reason: e.reason, feature_id: flags.feature, subject: { code: e.code, subject: e.subject ?? null }, expires_at: e.expires_at ?? null });
+		}
+		for (const e of renewedEntriesOut) {
+			appendDecisionEvent(root, flags.feature, { kind: 'contract_waiver', action: 'renew', at: e.at, reason: e.reason, feature_id: flags.feature, subject: { code: e.code, subject: e.subject ?? null }, expires_at: e.expires_at ?? null });
+		}
+		return { resolution: next, newEntries: newEntriesOut, renewedEntries: renewedEntriesOut };
 	});
 
 	const evaluation = evaluateResolution(contract, updatedResolution);
@@ -1891,10 +2028,14 @@ function cmdContractWaive(args) {
 		: passNamedGate(root, 'contract', flags.feature, evidence);
 
 	if (flags.json) {
-		console.log(JSON.stringify({ waived: newEntries, gate: gateState.gates.contract }, null, 2));
+		console.log(JSON.stringify({ waived: newEntries, renewed: renewedEntries, gate: gateState.gates.contract }, null, 2));
 	} else {
 		if (!flags.quiet) {
-			console.log(`waived ${newEntries.length} new warning(s)${newEntries.length < toWaive.length ? ` (${toWaive.length - newEntries.length} already waived)` : ''}${expiresAt ? `, expiring ${expiresAt}` : ''}`);
+			const alreadyWaived = toWaive.length - newEntries.length - renewedEntries.length;
+			console.log(`waived ${newEntries.length} new warning(s)${alreadyWaived > 0 ? ` (${alreadyWaived} already waived)` : ''}${expiresAt ? `, expiring ${expiresAt}` : ''}`);
+			if (renewedEntries.length > 0) {
+				console.log(`renewed ${renewedEntries.length} expired waiver(s)${expiresAt ? `, expiring ${expiresAt}` : ''}`);
+			}
 			console.log(`gate: contract -> ${gateState.gates.contract.status}`);
 		}
 		if (evaluation.expiredWaivers.length > 0) {
@@ -1909,6 +2050,65 @@ function cmdContractWaive(args) {
 	process.exit(evaluation.blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
 }
 
+// D-decision-event-log (D6): forward-only retraction of exactly one {code, subject} waiver --
+// mirrors `gate revoke`'s own precedent (the entry's absence IS the state, not a snapshot restore
+// of its prior reason/expiry, which stays recoverable only from the decision log). Re-evaluates
+// and re-sets the gate the same way `cmdContractWaive` does, since removing a waiver can turn a
+// passing gate back into an awaiting_disposition one.
+function cmdContractUnwaive(args) {
+	const flags = parseCommand('contract unwaive', args);
+	if (flags.help) { console.log(renderCommandHelp('contract unwaive')); process.exit(0); }
+	setContext('contract unwaive', flags);
+	const root = requireRepoRoot();
+	if (!flags.reason || !flags.reason.trim()) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel contract unwaive requires --reason "..." -- every withdrawal must be auditable');
+	}
+	const contract = loadContract(root, flags.feature);
+	const key = warningKey({ code: flags.code, subject: flags.subject });
+
+	const updatedResolution = withLockSync(root, 'state', () => {
+		const resolution = loadResolution(root, flags.feature);
+		const match = (resolution.waivers ?? []).find((w) => warningKey(w) === key);
+		if (!match) {
+			fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no waiver recorded for "${flags.code}" (${flags.subject}) on "${flags.feature}" -- nothing to unwaive`);
+		}
+		const at = new Date().toISOString();
+		const next = {
+			schema: 'sbf.contract-resolution/1',
+			feature_id: flags.feature,
+			waivers: (resolution.waivers ?? []).filter((w) => warningKey(w) !== key),
+		};
+		saveResolution(root, flags.feature, next);
+		appendDecisionEvent(root, flags.feature, {
+			kind: 'contract_waiver', action: 'withdraw', at, reason: flags.reason, feature_id: flags.feature,
+			subject: { code: match.code, subject: match.subject ?? null }, expires_at: match.expires_at ?? null,
+		});
+		return next;
+	});
+
+	const evaluation = evaluateResolution(contract, updatedResolution);
+	const evidence = {
+		operation_count: contract.completeness.operation_count,
+		endpoint_count: contract.completeness.endpoint_count,
+		completeness: evaluation.status,
+		warning_codes: countByCode(contract.warnings),
+		waived_count: evaluation.waived.length,
+		stale_waivers: evaluation.staleWaivers.length,
+		expired_waivers: evaluation.expiredWaivers.length,
+	};
+	const gateState = evaluation.blocking
+		? awaitNamedGateDisposition(root, 'contract', flags.feature, { ...evidence, unwaived: evaluation.unwaived.map(({ code, subject }) => ({ code, subject })) })
+		: passNamedGate(root, 'contract', flags.feature, evidence);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ withdrawn: { code: flags.code, subject: flags.subject }, gate: gateState.gates.contract }, null, 2));
+	} else {
+		console.log(`unwaived: ${flags.code} (${flags.subject})`);
+		console.log(`gate: contract -> ${gateState.gates.contract.status}`);
+	}
+	process.exit(evaluation.blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
+}
+
 // D-dependency-propagation-notice: called from cmdContractEmit/cmdHandlesEmit to warn a SOURCE
 // feature, at the moment its own generated artifacts are refreshed, that other features declared a
 // dependency on one of its fields. Only surfaces a note when the dependent's OWN `dependencies` gate
@@ -2026,6 +2226,162 @@ function cmdDependencyList(args) {
 	process.exit(0);
 }
 
+// D-cross-feature-impact-graph: `bskel impact check` -- read-mostly, never advances the baseline.
+// `--all` sweeps every active feature; this is the only thing that closes the `impact` gate's own
+// counterparty-narrowing limitation (a brand-new downstream feature is otherwise only caught at the
+// next explicit check, see D4/D7 in DECISIONS.md) -- the recommended CI invocation.
+function cmdImpactCheck(args) {
+	const flags = parseCommand('impact check', args);
+	if (flags.help) { console.log(renderCommandHelp('impact check')); process.exit(0); }
+	setContext('impact check', flags);
+	const root = requireRepoRoot();
+	if (!flags.all && !flags.feature) fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel impact check requires --feature <id> or --all');
+	const featureIds = flags.all ? listFeatures(root).map((r) => r.feature_id) : [flags.feature];
+
+	const results = [];
+	for (const featureId of featureIds) {
+		let outcome;
+		try {
+			outcome = checkImpact(root, featureId);
+		} catch (err) {
+			if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+			throw err;
+		}
+		results.push({ feature_id: featureId, ...outcome });
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify(flags.all ? results : results[0], null, 2));
+	} else {
+		for (const r of results) {
+			console.log(`impact check -- ${r.feature_id}`);
+			console.log(`  changes: ${r.report.changes.length}, outbound: ${r.report.outbound.length}, inbound: ${r.report.inbound.length}`);
+			console.log(`  gate: ${r.evaluation.blocking ? 'awaiting_disposition' : 'pass'}`);
+			for (const o of r.evaluation.blockingOutbound) console.log(`    BLOCKING: ${o.change_key} -> ${o.downstream_feature} (${o.via}, ${o.confidence})`);
+			for (const i of r.evaluation.blockingInbound) console.log(`    BLOCKING (inbound): ${i.change_key} from ${i.upstream_feature}, unacknowledged`);
+		}
+	}
+	const anyBlocking = results.some((r) => r.evaluation.blocking);
+	process.exit(anyBlocking ? EXIT_CODES.AWAITING_DISPOSITION : EXIT.PASS);
+}
+
+// D-cross-feature-impact-graph: the DECIDE half -- refuses (exit 3) if anything proven is
+// undisposed, otherwise atomically rewrites impact-baseline.json from the CURRENT surface.
+function cmdImpactAccept(args) {
+	const flags = parseCommand('impact accept', args);
+	if (flags.help) { console.log(renderCommandHelp('impact accept')); process.exit(0); }
+	setContext('impact accept', flags);
+	const root = requireRepoRoot();
+	let result;
+	try {
+		result = acceptImpact(root, flags.feature);
+	} catch (err) {
+		if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+	const gateState = passNamedGate(root, 'impact', flags.feature);
+	if (flags.json) {
+		console.log(JSON.stringify({ ...result, gate: gateState.gates.impact }, null, 2));
+	} else {
+		console.log(`accepted: ${flags.feature} -- baseline captured at ${result.baseline.captured_at}`);
+		console.log(`gate: impact -> ${gateState.gates.impact.status}`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+// D-decision-event-log (D6): --withdraw is a flag variant of this same command, not a separate
+// subcommand -- withdrawal needs no --mode (there is nothing left to mode-classify once the
+// disposition is gone), so branching inside cmdImpactDisposition keeps the option set honest
+// rather than requiring --mode on a withdrawal that doesn't use it.
+function cmdImpactDisposition(args) {
+	const flags = parseCommand('impact disposition', args);
+	if (flags.help) { console.log(renderCommandHelp('impact disposition')); process.exit(0); }
+	setContext('impact disposition', flags);
+	const root = requireRepoRoot();
+	if (flags.withdraw) {
+		let result;
+		try {
+			result = withdrawDisposition(root, { feature: flags.feature, changeKey: flags.change, downstreamFeature: flags.downstream, reason: flags.reason });
+		} catch (err) {
+			if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+			throw err;
+		}
+		if (flags.json) {
+			console.log(JSON.stringify(result, null, 2));
+		} else {
+			console.log(`disposition withdrawn: ${flags.change} -> ${flags.downstream}`);
+		}
+		process.exit(EXIT.PASS);
+	}
+	let result;
+	try {
+		result = recordDisposition(root, {
+			feature: flags.feature, changeKey: flags.change, downstreamFeature: flags.downstream,
+			mode: flags.mode, reason: flags.reason, trackedBy: flags['tracked-by'],
+			expiresDays: flags['expires-days'] != null ? Number(flags['expires-days']) : null,
+		});
+	} catch (err) {
+		if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+	if (flags.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else {
+		console.log(`disposition recorded: ${flags.change} -> ${flags.downstream} (${flags.mode})`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+function cmdImpactAck(args) {
+	const flags = parseCommand('impact ack', args);
+	if (flags.help) { console.log(renderCommandHelp('impact ack')); process.exit(0); }
+	setContext('impact ack', flags);
+	const root = requireRepoRoot();
+	let result;
+	try {
+		result = acknowledgeInbound(root, { feature: flags.feature, from: flags.from, changeKey: flags.change, reason: flags.reason });
+	} catch (err) {
+		if (err instanceof ImpactOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+	if (flags.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else {
+		console.log(`acknowledged: ${flags.change} from ${flags.from}`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+// D-cross-feature-impact-graph (IG8/IG9): the one seam to the LLM-driven exploration layer -- writes
+// data only, spawns nothing, never touches a gate. `--format graphify` writes graphify's own native
+// extraction shape directly (see lib/impact-export-graphify.mjs's header for why this bypasses its
+// own Steps 1-3 entirely).
+function cmdImpactExport(args) {
+	const flags = parseCommand('impact export', args);
+	if (flags.help) { console.log(renderCommandHelp('impact export')); process.exit(0); }
+	setContext('impact export', flags);
+	const root = requireRepoRoot();
+	if (!['graphify', 'json', 'mermaid'].includes(flags.format)) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--format must be one of graphify|json|mermaid (got "${flags.format}")`);
+	}
+	const graph = buildImpactGraph(root);
+	const rings = flags.rings != null ? Number(flags.rings) : null;
+	if (rings != null && !flags.focus) fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--rings only has an effect together with --focus');
+
+	let output;
+	if (flags.format === 'json') output = `${JSON.stringify(graph, null, 2)}\n`;
+	else if (flags.format === 'mermaid') output = `${toMermaid(graph)}\n`;
+	else output = `${JSON.stringify(toGraphifyExtraction(graph, { focus: flags.focus, rings }), null, 2)}\n`;
+
+	if (flags.out) {
+		writeFileAtomic(flags.out, output);
+		console.log(`wrote ${flags.out}`);
+	} else {
+		process.stdout.write(output);
+	}
+	process.exit(EXIT.PASS);
+}
+
 // D-business-rules (R6): compiles specs/<id>/rules.yaml (optional) plus the feature's own contract
 // into specs/<id>/rules/<id>.rules.json, and establishes the `rules` gate.
 //
@@ -2719,6 +3075,15 @@ function renderHandlesPlan(plan, actions) {
 		lines.push(`- read via: ${r.readPath ?? '(not found)'}`);
 		lines.push(`- requiredAuthority (fetch/recover): ${r.requiredAuthority}`);
 		if (r.requiredAuthorityForPatch !== undefined) lines.push(`- requiredAuthorityForPatch: ${r.requiredAuthorityForPatch}`);
+		// D-resolver-policy-contract (PC2): one line per policies[] record -- java-spring only
+		// (the field is absent on python-fastapi/typescript-express plans).
+		for (const p of r.policies ?? []) {
+			if (p.status === 'materialized') {
+				lines.push(`- policy[${p.action}]: materialized (${p.mode}) ${p.authority} -- ${p.evidence.kind}${p.evidence.file ? ` @ ${p.evidence.file}${p.evidence.line ? `:${p.evidence.line}` : ''}` : ''}`);
+			} else {
+				lines.push(`- policy[${p.action}]: UNRESOLVED (${p.mode}) -- ${p.evidence.kind}${p.evidence.file ? ` @ ${p.evidence.file}${p.evidence.line ? `:${p.evidence.line}` : ''}` : ''} -- ${p.reason}`);
+			}
+		}
 		lines.push('');
 	}
 	if (plan.notes.length > 0) {
@@ -2959,7 +3324,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 = [], registrationGaps = [] } = provider.emit({
+	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [], registrationGaps = [], unresolvedPolicies = [] } = provider.emit({
 		repoRoot: root, featureId: flags.feature, plan, resourceFilter, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff, enforceRegistry,
 	});
 
@@ -3039,6 +3404,24 @@ function cmdHandlesEmit(args) {
 		process.exit(EXIT_CODES.HANDLES_REGISTRATION_GAP);
 	}
 
+	// D-resolver-policy-contract (PC9): unconditional -- NOT gated on enforceRegistry (orthogonal
+	// axis: that one is about revocation/lifecycle and produces 404s; this one is about
+	// authorization and produces 403s/boot failures). Same acknowledgement mechanism as
+	// registrationGaps above (--force --reason, no new flag) -- the AuthorizationPolicy.java
+	// file(s) ARE still written either way; only the overall command's reported success, and the
+	// `handles` gate passing, are gated on acknowledging the gap.
+	if (unresolvedPolicies.length > 0 && !flags.force) {
+		if (flags.json) {
+			console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, unresolvedPolicies, blocked: true, gate: null, check: dryRun }, null, 2));
+		} else {
+			const verb = dryRun ? 'would refuse to report success' : 'refusing to report success';
+			console.error(`${verb}: ${unresolvedPolicies.length} resource action(s) could not have their authorization safely auto-derived:`);
+			for (const u of unresolvedPolicies) console.error(`  ${u.resourceType} [${u.action}] (${u.kind}${u.file ? ` @ ${u.file}${u.line ? `:${u.line}` : ''}` : ''})\n    ${u.note}`);
+			if (!dryRun) console.error(`\nthe resolver/AuthorizationPolicy file(s) above were still written -- nothing about their content is wrong. Implement the generated AuthorizationPolicy interface(s) by hand and re-run, or acknowledge and proceed with: bskel handles emit --feature ${flags.feature}${flags.module ? ` --module ${flags.module}` : ''}${flags.resource ? ` --resource ${flags.resource}` : ''} --force --reason "..."`);
+		}
+		process.exit(EXIT_CODES.HANDLES_UNRESOLVED_POLICY);
+	}
+
 	// D4: dryRun never marks the gate passed -- nothing real happened this run.
 	const gateState = dryRun ? null : passNamedGate(root, 'handles', flags.feature, { resolverStubs });
 
@@ -3048,7 +3431,7 @@ function cmdHandlesEmit(args) {
 	postEmitNotes.push(...describeDownstreamImpact(root, flags.feature));
 
 	if (flags.json) {
-		console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, blocked: false, gate: gateState?.gates.handles ?? null, check: dryRun, postEmitNotes }, null, 2));
+		console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, unresolvedPolicies, blocked: false, gate: gateState?.gates.handles ?? null, check: dryRun, postEmitNotes }, null, 2));
 	} else if (!flags.quiet) {
 		console.log(`${dryRun ? 'would write' : 'wrote'} ${written.length} file(s):`);
 		for (const w of written) console.log(`  ${w}`);
@@ -3129,6 +3512,10 @@ function cmdHandlesPatchApprove(args) {
 		const withoutExisting = (current.approvals ?? []).filter((a) => approvalKey(a.resource, a.field) !== key);
 		const next = { schema: 'sbf.patch-approvals/1', feature_id: flags.feature, approvals: [...withoutExisting, entry] };
 		savePatchApprovals(root, flags.feature, next);
+		appendDecisionEvent(root, flags.feature, {
+			kind: 'patch_approval', action: 'record', at, reason: flags.reason, feature_id: flags.feature,
+			subject: { resource: flags.resource, field: flags.field }, strategy: flags.strategy,
+		});
 		return next;
 	});
 
@@ -3136,6 +3523,41 @@ function cmdHandlesPatchApprove(args) {
 	process.exit(0);
 }
 
+// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+// approval entry and appends a `withdraw` decision event. patch-approvals.json is not itself a
+// gate input (F3's fix is binding it into signed attestations, not making it a gate -- see
+// D-decision-event-log's own EXIT), so unlike the other three withdraw commands there is no gate
+// to re-evaluate here.
+function cmdHandlesPatchUnapprove(args) {
+	const flags = parseCommand('handles patch unapprove', args);
+	if (flags.help) { console.log(renderCommandHelp('handles patch unapprove')); process.exit(0); }
+	setContext('handles patch unapprove', flags);
+	const root = requireRepoRoot();
+	if (!flags.reason || !flags.reason.trim()) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel handles patch unapprove requires --reason "..." -- every withdrawal must be auditable');
+	}
+	const key = approvalKey(flags.resource, flags.field);
+
+	const updated = withLockSync(root, 'state', () => {
+		const current = loadPatchApprovals(root, flags.feature);
+		const match = (current.approvals ?? []).find((a) => approvalKey(a.resource, a.field) === key);
+		if (!match) {
+			fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no approval recorded for "${flags.resource}.${flags.field}" on "${flags.feature}" -- nothing to unapprove`);
+		}
+		const at = new Date().toISOString();
+		const next = { schema: 'sbf.patch-approvals/1', feature_id: flags.feature, approvals: (current.approvals ?? []).filter((a) => approvalKey(a.resource, a.field) !== key) };
+		savePatchApprovals(root, flags.feature, next);
+		appendDecisionEvent(root, flags.feature, {
+			kind: 'patch_approval', action: 'withdraw', at, reason: flags.reason, feature_id: flags.feature,
+			subject: { resource: flags.resource, field: flags.field }, strategy: match.strategy,
+		});
+		return next;
+	});
+
+	console.log(flags.json ? JSON.stringify(updated, null, 2) : `unapproved: ${flags.resource}.${flags.field}`);
+	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"
@@ -3164,7 +3586,7 @@ async function cmdPatchPropose(args) {
 		}
 		params = { choice: flags.choice, target: flags.target };
 		source = { choice: flags.choice };
-	} else {
+	} else if (kind === 'ddl-apply') {
 		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>');
 		}
@@ -3176,6 +3598,23 @@ async function cmdPatchPropose(args) {
 		}
 		params = { databaseUrlEnv: flags['database-url-env'], schema: flags.schema, sqlText };
 		source = { database_url_env: flags['database-url-env'], schema: flags.schema };
+	} else {
+		// java-source-splice
+		if (!flags['splice-file']) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel patch propose --kind java-source-splice requires --splice-file <path>');
+		}
+		let spliceDoc;
+		try {
+			spliceDoc = JSON.parse(fs.readFileSync(flags['splice-file'], 'utf8'));
+		} catch (err) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not read/parse --splice-file "${flags['splice-file']}": ${err.message}`);
+		}
+		const { ok: spliceOk, errors: spliceErrors } = validateAgainstSchema('java-source-splice.schema.json', spliceDoc);
+		if (!spliceOk) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `"${flags['splice-file']}" does not match schemas/java-source-splice.schema.json:\n${formatSchemaErrors(spliceErrors).join('\n')}`);
+		}
+		params = { file: spliceDoc.file, edits: spliceDoc.edits };
+		source = { request_file: flags['splice-file'] };
 	}
 
 	let plan;
@@ -3202,6 +3641,12 @@ function describePatchTransaction(txn) {
 	if (txn.kind === 'config-apply') {
 		return `${txn.target.file} @ ${txn.target.key_path.join('.')}: "${txn.current_value}" -> "${txn.proposed_value}"`;
 	}
+	if (txn.kind === 'java-source-splice') {
+		const members = txn.target.edits
+			.map((e) => (e.locator ? `${e.op}:${e.locator.member_name}` : `add-import:${e.imports?.[0]}`))
+			.join(', ');
+		return `[java-source-splice] ${txn.target.file}: ${members}`;
+	}
 	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 ? '...' : ''}`;
 }
@@ -3231,12 +3676,33 @@ async function cmdPatchApprove(args) {
 	} catch (err) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
 	}
-	const updated = approveTransaction(root, flags.feature, flags.transaction, flags.reason, freshPlan);
+	let updated;
+	try {
+		updated = approveTransaction(root, flags.feature, flags.transaction, flags.reason, freshPlan);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', describeStaleTransactionError(err, root, txn, freshPlan));
+	}
 
 	console.log(flags.json ? JSON.stringify(updated, null, 2) : `approved: ${flags.transaction}`);
 	process.exit(0);
 }
 
+// D-java-source-splice: enriches a StaleTransactionError with the kind's own optional
+// describeStaleness() hook (only java-source-splice defines one today) -- never changes WHETHER
+// the transaction is rejected, only the diagnostic text. Checked by `.name`, not `instanceof`
+// (StaleTransactionError is intentionally not exported from lib/patch-transactions.mjs -- this is
+// its only consumer, and importing the class just to narrow a catch is unnecessary coupling).
+function describeStaleTransactionError(err, root, txn, freshPlan) {
+	if (err.name !== 'StaleTransactionError') return err.message;
+	const describe = getPatchKind(txn.kind).describeStaleness;
+	if (!describe) return err.message;
+	try {
+		return describe(root, txn, freshPlan);
+	} catch {
+		return err.message;
+	}
+}
+
 // 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
@@ -3262,7 +3728,12 @@ async function cmdPatchApply(args) {
 	} 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);
+	let updated;
+	try {
+		updated = await applyTransaction(root, flags.feature, flags.transaction, freshPlan, getPatchKind(txn.kind).apply);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', describeStaleTransactionError(err, root, txn, freshPlan));
+	}
 
 	const evidence = { transaction_id: updated.transaction_id, kind: updated.kind, applied_at: updated.apply.at };
 	const gateState = passNamedGate(root, 'patch_transactions', flags.feature, evidence);
@@ -4415,6 +4886,7 @@ async function dispatchCommand(cmd, rest) {
 			if (rest[0] === 'repair') return cmdScanRepair(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));
+			if (rest[0] === 'cross-feature-unwaive') return cmdScanCrossFeatureUnwaive(rest.slice(1));
 			await cmdScan(rest);
 			break;
 		}
@@ -4439,6 +4911,7 @@ async function dispatchCommand(cmd, rest) {
 			if (sub === 'validate') return cmdContractValidate(subArgs);
 			if (sub === 'tool-schema') return cmdContractToolSchema(subArgs);
 			if (sub === 'waive') return cmdContractWaive(subArgs);
+			if (sub === 'unwaive') return cmdContractUnwaive(subArgs);
 			usage();
 			process.exit(14);
 			break;
@@ -4453,6 +4926,18 @@ async function dispatchCommand(cmd, rest) {
 			process.exit(14);
 			break;
 		}
+		case 'impact': {
+			const sub = rest[0];
+			const subArgs = rest.slice(1);
+			if (sub === 'check') return cmdImpactCheck(subArgs);
+			if (sub === 'accept') return cmdImpactAccept(subArgs);
+			if (sub === 'disposition') return cmdImpactDisposition(subArgs);
+			if (sub === 'ack') return cmdImpactAck(subArgs);
+			if (sub === 'export') return cmdImpactExport(subArgs);
+			usage();
+			process.exit(14);
+			break;
+		}
 		case 'rules': {
 			const sub = rest[0];
 			const subArgs = rest.slice(1);
@@ -4490,6 +4975,7 @@ async function dispatchCommand(cmd, rest) {
 			if (rest[0] === 'plan') return cmdHandlesPlan(rest.slice(1));
 			if (rest[0] === 'emit') return cmdHandlesEmit(rest.slice(1));
 			if (rest[0] === 'patch' && rest[1] === 'approve') return cmdHandlesPatchApprove(rest.slice(2));
+			if (rest[0] === 'patch' && rest[1] === 'unapprove') return cmdHandlesPatchUnapprove(rest.slice(2));
 			if (rest[0] === 'audit') return await cmdHandlesAudit(rest.slice(1));
 			usage();
 			process.exit(14);