backend-skeleton 1.6.0 → 1.7.1

package/README.md

@@ -602,9 +602,10 @@ string for anything missing.
   (entities come from `@Entity`/`@PrimaryGeneratedColumn`); no operation extraction — plain Express
   has no operationId concept, so pass `--openapi-file` for a contract. See
   `D-typescript-express-provider` in `DECISIONS.md`.
-- `javascript-express` — plain-JavaScript ESM Express with **no ORM** (raw `mysql2`/`mariadb`),
-  including `serverless-http`/Lambda deployments. **Scanner only** — routes and their real absolute
-  paths are resolved through a full mount-graph walk, but every capability is honestly `false`:
+- `javascript-express` — plain-JavaScript Express, both ESM and CommonJS, with **no ORM** (raw
+  `mysql2`/`mariadb`), including `serverless-http`/Lambda deployments. **Scanner only** — routes
+  and their real absolute paths are resolved through a full mount-graph walk (including direct
+  CommonJS `require()` mounts and `module.exports`), but every capability is honestly `false`:
   there is no codegen provider, because raw SQL string literals carry no trustworthy
   table/primary-key/column-allow-list metadata. See `D-javascript-express-adapter` in `DECISIONS.md`
   for the measured reasoning.

package/bin/bskel.mjs

@@ -30,8 +30,9 @@ 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, publicKeyIdFromPrivate, publicKeyIdFromPublic } from '../lib/attest.mjs';
@@ -42,7 +43,7 @@ import {
 	declareDependency, removeDependency, buildDependencyListReport,
 } from '../lib/field-dependencies.mjs';
 import {
-	ImpactOperationError, checkImpact, acceptImpact, recordDisposition, acknowledgeInbound,
+	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';
@@ -103,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]
@@ -117,12 +119,13 @@ 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> --reason "..." [--tracked-by "..."] [--expires-days <N>] [--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]
@@ -134,6 +137,7 @@ 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|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]
@@ -1025,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;
 	});
 
@@ -1048,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():
@@ -1913,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);
@@ -1944,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) {
@@ -1962,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
@@ -2142,11 +2289,30 @@ function cmdImpactAccept(args) {
 	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, {
@@ -3346,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;
 	});
 
@@ -3353,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"
@@ -4681,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;
 		}
@@ -4705,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;
@@ -4768,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);

package/contracts/completeness.mjs

@@ -225,11 +225,22 @@ export function saveResolution(root, featureId, resolution) {
 // its warning, so `unwaived`/`blocking` treat it exactly as if it had never been recorded. A
 // waiver can be BOTH stale and expired at once (nothing prevents that combination); the two
 // lists are independent, not mutually exclusive.
+// D-waiver-renewal: the single shared expiry predicate. Previously inlined once here and NOT
+// consulted by `cmdContractWaive`'s own "is this already waived" check (bin/bskel.mjs) -- that
+// second, unsynchronized check meant an expired waiver was `waived` for evaluateResolution's
+// purposes (correctly stops blocking) but simultaneously "already exists" for the CLI's own
+// existingKeys set, so re-waiving it silently matched zero new entries and never updated the
+// stored expires_at. Exporting one function closes that gap at the source instead of requiring
+// two call sites to independently reimplement `Date.parse(w.expires_at) <= now` in sync forever.
+export function isWaiverExpired(waiver, now = Date.now()) {
+	return typeof waiver.expires_at === 'string' && Date.parse(waiver.expires_at) <= now;
+}
+
 export function evaluateResolution(contract, resolution) {
 	const status = classifyContract(contract);
 	const waivers = resolution.waivers ?? [];
 	const now = Date.now();
-	const expiredWaivers = waivers.filter((w) => typeof w.expires_at === 'string' && Date.parse(w.expires_at) <= now);
+	const expiredWaivers = waivers.filter((w) => isWaiverExpired(w, now));
 	const expiredKeys = new Set(expiredWaivers.map(warningKey));
 	const waivedKeys = new Set(waivers.filter((w) => !expiredKeys.has(warningKey(w))).map(warningKey));
 

package/lib/cli.mjs

@@ -187,6 +187,20 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+	// waiver entry (its absence is the state) and appends a `withdraw` decision event. Never a
+	// snapshot restore.
+	'scan cross-feature-unwaive': {
+		usage: 'bskel scan cross-feature-unwaive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			signal: { type: 'string', default: null, required: true },
+			identifier: { type: 'string', default: null, required: true },
+			'other-feature': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'feature init': {
 		usage: 'bskel feature init --slug <name>',
 		options: { slug: { type: 'string', default: null, required: true } },
@@ -299,6 +313,20 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+	// waiver entry (its absence is the state) and appends a `withdraw` decision event. Never a
+	// snapshot restore (the entry's prior reason/expiry is preserved only in the decision log, not
+	// restorable through this command).
+	'contract unwaive': {
+		usage: 'bskel contract unwaive --feature <id> --code <CODE> --subject "VERB /path" --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			code: { type: 'string', default: null, required: true },
+			subject: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'contract validate': {
 		usage: 'bskel contract validate --feature <id> --file <envelope.json>',
 		options: {
@@ -370,16 +398,21 @@ export const COMMANDS = {
 	},
 	// D-cross-feature-impact-graph (D6): three modes, three mechanically different consequences --
 	// `migrate` requires --tracked-by, `waive` requires --expires-days. `compatible` needs neither.
+	// D-decision-event-log (D6): --withdraw is a flag variant of this same command, not a separate
+	// subcommand -- a withdrawal needs no --mode, so `mode` is NOT `required: true` at the parse
+	// layer (recordDisposition() itself still refuses a missing/invalid mode on the record path --
+	// see cmdImpactDisposition's own comment for why this split is deliberate).
 	'impact disposition': {
-		usage: 'bskel impact disposition --feature <id> --change <change_key> --downstream <id> --mode compatible|migrate|waive --reason "..." [--tracked-by "<ref>"] [--expires-days <N>] [--json]',
+		usage: 'bskel impact disposition --feature <id> --change <change_key> --downstream <id> (--mode compatible|migrate|waive [--tracked-by "<ref>"] [--expires-days <N>] | --withdraw) --reason "..." [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			change: { type: 'string', default: null, required: true },
 			downstream: { type: 'string', default: null, required: true },
-			mode: { type: 'string', default: null, required: true },
+			mode: { type: 'string', default: null },
 			reason: { type: 'string', default: '' },
 			'tracked-by': { type: 'string', default: null },
 			'expires-days': { type: 'string', default: null, numeric: { min: 1 } },
+			withdraw: { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -645,6 +678,19 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke` -- removes the
+	// approval entry (its absence is the state) and appends a `withdraw` decision event. Never a
+	// snapshot restore.
+	'handles patch unapprove': {
+		usage: 'bskel handles patch unapprove --feature <id> --resource <Type> --field <name> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			resource: { type: 'string', default: null, required: true },
+			field: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	// D-patch-transactions: content-addressed patch transactions, Slice 1 (config_check ->
 	// config_apply). `propose`/`approve` only touch specs/, so no --force escape exists on either --
 	// re-propose is the only remediation for a stale target. `rollback` alone gets --force (reverting

package/lib/decision-log.mjs

@@ -0,0 +1,58 @@
+// D-decision-event-log: an append-only audit trail for the four spec-side decision files
+// (contract waivers, cross-feature waivers, impact dispositions, patch approvals) -- mirrors
+// lib/state.mjs's appendGateEvent()/readGateHistory() shape exactly (same file family, same
+// schema-validated-JSONL contract, same corrupt-line-is-skipped-not-fatal resilience). A sibling
+// to .sbf/<featureId>.history.jsonl, not a replacement for it -- gates keep their own log.
+//   WHY: F2 (found during this item's own grounding) -- all four decision files silently
+//   OVERWRITE the prior decision (reason/actor/timestamp) on re-decision, and none of the four had
+//   any retraction command. `gate revoke` is the only retraction primitive in the whole tool.
+//   COST: one more .sbf/ file per feature. Machine-local, gitignored-by-convention -- this log is
+//   NOT tamper-evident on its own (see schemas/decision-event.schema.json's own description);
+//   its evidentiary value comes from being rolled into a SIGNED gate-export attestation.
+//   EXIT: no cross-feature aggregate view; per-feature only, matching gate history's own scoping.
+import fs from 'node:fs';
+import { sbfDir } from './state.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+
+export function decisionLogPath(repoRoot, featureId) {
+	return `${sbfDir(repoRoot)}/${featureId}.decisions.jsonl`;
+}
+
+// Called from inside the SAME withLockSync(root, 'state', ...) each of the four write paths
+// already holds -- never opens its own lock, so the decision write and the log append can never
+// observe each other out of order (same discipline setGate() already applies to gate writes).
+export function appendDecisionEvent(repoRoot, featureId, event) {
+	const line = { schema: 'sbf.decision-event/1', ...event };
+	const { ok, errors } = validateAgainstSchema('decision-event.schema.json', line);
+	if (!ok) {
+		throw new Error(`refusing to append an invalid decision event for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	fs.mkdirSync(sbfDir(repoRoot), { recursive: true });
+	fs.appendFileSync(decisionLogPath(repoRoot, featureId), `${JSON.stringify(line)}\n`);
+}
+
+// Mirrors lib/gate-export.mjs's readGateHistory() resilience contract exactly: a corrupt/invalid
+// line is skipped with a warning, never a hard failure.
+export function readDecisionLog(repoRoot, featureId, { kind = null, onWarning } = {}) {
+	const file = decisionLogPath(repoRoot, 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 {
+			onWarning?.(`${file}:${i + 1}: not valid JSON, skipped`);
+			continue;
+		}
+		const { ok, errors } = validateAgainstSchema('decision-event.schema.json', parsed);
+		if (!ok) {
+			onWarning?.(`${file}:${i + 1}: does not match schemas/decision-event.schema.json, skipped`, errors);
+			continue;
+		}
+		if (kind && parsed.kind !== kind) continue;
+		events.push(parsed);
+	}
+	return events;
+}