backend-skeleton 1.0.0-beta.3 → 1.0.0-beta.4

package/README.md

@@ -1,5 +1,10 @@
 # backend-skeleton
 
+[![npm version](https://img.shields.io/npm/v/backend-skeleton.svg)](https://www.npmjs.com/package/backend-skeleton)
+[![npm license](https://img.shields.io/npm/l/backend-skeleton.svg)](https://github.com/popixoxipop-collab/backend-skeleton/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/backend-skeleton.svg)](https://www.npmjs.com/package/backend-skeleton)
+[![GitHub release](https://img.shields.io/github/v/release/popixoxipop-collab/backend-skeleton?include_prereleases&label=release)](https://github.com/popixoxipop-collab/backend-skeleton/releases)
+
 Spec-driven backend scaffolding for brownfield (and greenfield) Java/Spring Boot, Python/FastAPI,
 and TypeScript/JavaScript Express repos: a brownfield-collision gate before any spec/plan step,
 feature_id-scoped machine-readable contracts, UUID-addressable field handles, and stack-choice

package/bin/bskel.mjs

@@ -5,7 +5,7 @@ import { execFileSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
-import { repoRoot, localDefaultBranch } from '../lib/repo.mjs';
+import { repoRoot, localDefaultBranch, fileHistory, showFileAtRevision, headSha, currentBranch, isDirty } from '../lib/repo.mjs';
 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';
@@ -22,6 +22,7 @@ import {
 import { runScan } from '../scanners/index.mjs';
 import { scanMigrations } from '../scanners/db/migrations.mjs';
 import { introspectSchema, describeConnectionError } from '../scanners/db/introspect.mjs';
+import { auditHandles, summarizeAudit, isMissingHandleTables } from '../handles/audit.mjs';
 import { renderScanMarkdown, renderPlanConstraints, renderScanExplain } from '../scanners/render.mjs';
 import { ADAPTERS, LOAD_ERRORS, adapterById } from '../scanners/registry.mjs';
 import { COMMAND_CAPABILITIES, CAPABILITY_SATISFIERS, explainMissingCapability } from '../scanners/capabilities.mjs';
@@ -29,6 +30,7 @@ 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 { loadManifest, saveManifest } from '../lib/handles-manifest.mjs';
 import { STACKS as NEW_STACKS, ALL_STACK_PARAMS, stacksAccepting } from '../new/index.mjs';
 import {
 	requireSingleLineText, requireValidJavaPackageName, requireValidArtifactId,
@@ -67,14 +69,16 @@ function usage() {
   bskel feature archive <id> --reason "..." [--json]
   bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0] [--descriptions]
   bskel contract export --feature <id> [--out <path>] [--json] [--allow-unprefixed] [--status-codes range|literal]
+  bskel contract history --feature <id> [--json]
   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 "..."
+  bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path"|--all) --reason "..." [--expires <Nd>]
   bskel stack apply --choice <id> [--apply] [--port N] [--json]
   bskel catalog lint [<choice>] [--json]
   bskel handles plan --feature <id> [--module <name>] [--resource type1,type2] [--diff] [--ast]
-  bskel handles emit --feature <id> [--module <name>] [--resource type1,type2] [--force --reason "..."] [--check] [--diff]
+  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 verify --feature <id> [--build [--allow-skip-build]] [--json]
   bskel status [--feature <id>] [--json]
   bskel next [--feature <id>] [--json]
@@ -83,6 +87,7 @@ 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 doctor [--workflow ${DOCTOR_WORKFLOWS.join('|')}] [--json]
 `);
 }
@@ -360,6 +365,48 @@ function cmdGateShow(args) {
 	process.exit(0);
 }
 
+// D-gate-export (S7's own sibling item): a standalone, human- and machine-readable report of
+// exactly what THIS repo's own `.sbf/*.history.jsonl` shows -- current state + full history for
+// every gate, plus enough git provenance (branch/HEAD/dirty) to say when it was captured. Built to
+// answer "what did this PR actually get verified against" *independent of whether CI ran at all* --
+// the concrete, real mitigation for the exact GitHub-Actions-billing outage this repo itself has
+// been running under (see feedback_backend_skeleton_ci_gate_suspended_billing in project memory).
+// Pure reader -- never mutates a gate, never requires one to currently pass.
+function cmdGateExport(args) {
+	const flags = parseCommand('gate export', args);
+	if (flags.help) { console.log(renderCommandHelp('gate export')); process.exit(0); }
+	setContext('gate export', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+
+	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) };
+	}
+
+	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 rendered = `${JSON.stringify(report, 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)' : ''}`);
+		}
+	} else {
+		console.log(rendered);
+	}
+	process.exit(0);
+}
+
 // 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
@@ -942,6 +989,7 @@ function cmdContractEmit(args) {
 		warning_codes: countByCode(contract.warnings),
 		waived_count: evaluation.waived.length,
 		stale_waivers: evaluation.staleWaivers.length,
+		expired_waivers: evaluation.expiredWaivers.length,
 		openapi: reconciliation
 			? {
 				applied: true,
@@ -993,6 +1041,10 @@ function cmdContractEmit(args) {
 		}
 		for (const w of contract.warnings) console.error(`warning[${w.severity}] ${w.code}${w.subject ? ` (${w.subject})` : ''}: ${w.message}`);
 		if (!flags.quiet) console.log(`gate: contract -> ${gateState.gates.contract.status}`);
+		if (evaluation.expiredWaivers.length > 0) {
+			console.error(`\nnote: ${evaluation.expiredWaivers.length} recorded waiver(s) have expired and no longer cover their warning (re-waive with --expires if still needed):`);
+			for (const w of evaluation.expiredWaivers) console.error(`  ${w.code} (${w.subject ?? '*'}) expired ${w.expires_at}`);
+		}
 		if (evaluation.staleWaivers.length > 0) {
 			console.error(`\nnote: ${evaluation.staleWaivers.length} recorded waiver(s) no longer match any current warning (kept as-is, not auto-removed):`);
 			for (const w of evaluation.staleWaivers) console.error(`  ${w.code} (${w.subject ?? '*'})`);
@@ -1197,12 +1249,26 @@ function cmdContractExport(args) {
 // waiver: `--all` expands to the SPECIFIC code+subject pairs present right now, recorded as
 // individual entries -- a warning that doesn't exist yet (e.g. a new unannotated endpoint added
 // later) is never covered by an old waive. See D-contract-completeness in DECISIONS.md.
+// D-waiver-expiry: only `<N>d` (whole days) -- the realistic common case for "look at this
+// again later," not a general ISO-8601 duration parser nobody asked for. `N` must be a positive
+// integer; `0d`/negative would either be a no-op waiver (already expired the moment it's written)
+// or nonsensical, and silently accepting either would be more confusing than refusing.
+function parseExpiresFlag(raw) {
+	if (raw == null) return null;
+	const match = /^([1-9][0-9]*)d$/.exec(raw);
+	if (!match) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--expires must look like "<N>d" (whole days, N >= 1), got "${raw}"`);
+	}
+	const days = Number(match[1]);
+	return new Date(Date.now() + days * 24 * 60 * 60 * 1000).toISOString();
+}
+
 function cmdContractWaive(args) {
 	const flags = parseCommand('contract waive', args);
 	if (flags.help) { console.log(renderCommandHelp('contract waive')); process.exit(0); }
 	setContext('contract waive', flags);
 	const root = requireRepoRoot();
-	const usageText = 'usage: bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path" | --all) --reason "..."';
+	const usageText = 'usage: bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path" | --all) --reason "..." [--expires <Nd>]';
 	try {
 		requireWarningCode(flags.code);
 	} catch (err) {
@@ -1214,6 +1280,7 @@ function cmdContractWaive(args) {
 	if (!flags.subject && !flags.all) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', usageText);
 	}
+	const expiresAt = parseExpiresFlag(flags.expires);
 
 	const contract = loadContract(root, flags.feature);
 	if (contract.completeness.status === 'blocked') {
@@ -1247,7 +1314,7 @@ function cmdContractWaive(args) {
 		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 }));
+			.map((w) => ({ code: w.code, subject: w.subject, reason: flags.reason, at, ...(expiresAt ? { expires_at: expiresAt } : {}) }));
 		const next = {
 			schema: 'sbf.contract-resolution/1',
 			feature_id: flags.feature,
@@ -1265,6 +1332,7 @@ function cmdContractWaive(args) {
 		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 })) })
@@ -1274,9 +1342,13 @@ function cmdContractWaive(args) {
 		console.log(JSON.stringify({ waived: newEntries, 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)` : ''}`);
+			console.log(`waived ${newEntries.length} new warning(s)${newEntries.length < toWaive.length ? ` (${toWaive.length - newEntries.length} already waived)` : ''}${expiresAt ? `, expiring ${expiresAt}` : ''}`);
 			console.log(`gate: contract -> ${gateState.gates.contract.status}`);
 		}
+		if (evaluation.expiredWaivers.length > 0) {
+			console.error(`\nnote: ${evaluation.expiredWaivers.length} recorded waiver(s) have expired and no longer cover their warning (re-waive with --expires if still needed):`);
+			for (const w of evaluation.expiredWaivers) console.error(`  ${w.code} (${w.subject ?? '*'}) expired ${w.expires_at}`);
+		}
 		if (evaluation.blocking) {
 			console.error(`\nstill blocked: ${evaluation.unwaived.length} unresolved warning(s) remain:`);
 			for (const w of evaluation.unwaived) console.error(`  ${w.code} (${w.subject})`);
@@ -1285,6 +1357,74 @@ function cmdContractWaive(args) {
 	process.exit(evaluation.blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
 }
 
+// D-contract-history: a derived VIEW over the contract file's own git history in whatever repo
+// bskel is invoked in -- reads, never writes. Deliberately does NOT try to correlate a commit to
+// a specific `.sbf/<feature>.history.jsonl` gate-pass event: that file is per-machine, gitignored,
+// ephemeral state (see .gitignore's own comment on `.sbf/`), while a commit is shared -- the two
+// have no reliable 1:1 relationship, so this only reports what git itself can prove. `bskel gate
+// export` (a separate, later item) is the tool for "what did THIS machine's gate history record."
+function cmdContractHistory(args) {
+	const flags = parseCommand('contract history', args);
+	if (flags.help) { console.log(renderCommandHelp('contract history')); process.exit(0); }
+	setContext('contract history', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+
+	const contractPath = specPath(root, flags.feature, 'contracts', `${flags.feature}.schema.json`);
+	const relPath = path.relative(root, contractPath);
+	const commits = fileHistory(root, relPath);
+
+	if (commits.length === 0) {
+		if (flags.json) {
+			console.log(JSON.stringify({ feature_id: flags.feature, path: relPath, revisions: [] }, null, 2));
+		} else {
+			console.log(`no git history for ${relPath} -- either this feature's contract was never committed, or specs/ isn't tracked in this repo. bskel does not require specs/ to be committed; if you want a history view, commit the contract as part of your normal workflow.`);
+		}
+		process.exit(0);
+	}
+
+	let prevOperationNames = new Set();
+	const revisions = commits.map(({ sha, date, subject }) => {
+		const raw = showFileAtRevision(root, sha, relPath);
+		let parsed = null;
+		if (raw !== null) {
+			try { parsed = JSON.parse(raw); } catch { parsed = null; }
+		}
+		if (parsed === null) {
+			return { sha: sha.slice(0, 12), date, subject, parse_error: true };
+		}
+		const operationNames = new Set(Object.keys(parsed.operations ?? {}));
+		const added = [...operationNames].filter((n) => !prevOperationNames.has(n)).sort();
+		const removed = [...prevOperationNames].filter((n) => !operationNames.has(n)).sort();
+		prevOperationNames = operationNames;
+		return {
+			sha: sha.slice(0, 12), date, subject,
+			sbf_contract: parsed.sbf_contract ?? null,
+			completeness_status: parsed.completeness?.status ?? null,
+			operation_count: parsed.completeness?.operation_count ?? operationNames.size,
+			operations_added: added,
+			operations_removed: removed,
+		};
+	});
+
+	if (flags.json) {
+		console.log(JSON.stringify({ feature_id: flags.feature, path: relPath, revisions }, null, 2));
+	} else {
+		console.log(`${relPath} -- ${revisions.length} revision(s), oldest first:\n`);
+		for (const r of revisions) {
+			if (r.parse_error) {
+				console.log(`${r.date}  ${r.sha}  (unparseable at this revision -- pre-JSON format or corrupted)`);
+				continue;
+			}
+			const delta = [];
+			if (r.operations_added.length > 0) delta.push(`+${r.operations_added.join(',+')}`);
+			if (r.operations_removed.length > 0) delta.push(`-${r.operations_removed.join(',-')}`);
+			console.log(`${r.date}  ${r.sha}  sbf_contract=${r.sbf_contract} completeness=${r.completeness_status} operations=${r.operation_count}${delta.length > 0 ? `  (${delta.join(' ')})` : ''}`);
+		}
+	}
+	process.exit(0);
+}
+
 function cmdContractValidate(args) {
 	const flags = parseCommand('contract validate', args);
 	if (flags.help) { console.log(renderCommandHelp('contract validate')); process.exit(0); }
@@ -1572,7 +1712,8 @@ function renderHandlesPlan(plan, actions) {
 		lines.push(`## ${r.type}${r.willGenerateResolver ? '' : ' (resolver will NOT be generated -- see notes)'}`);
 		lines.push(`- table: ${r.table ?? '(unknown)'}, PK field: ${r.idField ?? '(unknown)'}`);
 		lines.push(`- read via: ${r.readPath ?? '(not found)'}`);
-		lines.push(`- requiredAuthority: ${r.requiredAuthority}`);
+		lines.push(`- requiredAuthority (fetch/recover): ${r.requiredAuthority}`);
+		if (r.requiredAuthorityForPatch !== undefined) lines.push(`- requiredAuthorityForPatch: ${r.requiredAuthorityForPatch}`);
 		lines.push('');
 	}
 	if (plan.notes.length > 0) {
@@ -1733,6 +1874,20 @@ function cmdHandlesEmit(args) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel handles emit --force requires --reason "..." -- every overwrite of diverged generated code must be auditable');
 	}
 
+	// O3 (D-handle-registry-enforcement): repo-wide, singleton state -- read BEFORE provider.emit()
+	// (which loads its own, separate in-memory copy for `files` tracking) so an omitted flag
+	// reuses whatever this repo's own manifest last recorded, rather than silently defaulting to
+	// off. --enforce-registry off requires --reason ONLY when it's a REAL downgrade (currently on)
+	// -- reaffirming an already-off value, or turning it on, never needs one.
+	const priorManifest = loadManifest(root);
+	if (flags['enforce-registry'] !== null && flags['enforce-registry'] !== 'on' && flags['enforce-registry'] !== 'off') {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--enforce-registry must be "on" or "off" (got "${flags['enforce-registry']}")`);
+	}
+	const enforceRegistry = flags['enforce-registry'] === null ? priorManifest.enforceRegistry : flags['enforce-registry'] === 'on';
+	if (flags['enforce-registry'] === 'off' && priorManifest.enforceRegistry === true && (!flags.reason || !flags.reason.trim())) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel handles emit --enforce-registry off requires --reason "..." when registry enforcement was previously on -- every downgrade of a security posture must be auditable');
+	}
+
 	// Handles are only emitted for a feature whose contract has actually been established --
 	// codegen against a feature nobody has scanned/contracted yet has nothing real to route to.
 	const contractResult = requireNamedGate(root, 'contract', flags.feature);
@@ -1766,8 +1921,21 @@ function cmdHandlesEmit(args) {
 	// does, without requiring both flags together.
 	const dryRun = flags.check || flags.diff;
 	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [] } = provider.emit({
-		repoRoot: root, featureId: flags.feature, plan, resourceFilter, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff,
+		repoRoot: root, featureId: flags.feature, plan, resourceFilter, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff, enforceRegistry,
 	});
+
+	// O3 (D-handle-registry-enforcement): persisted whenever the effective value actually changed
+	// on a real (non-dryRun) run -- deliberately NOT gated on `blocked` below: O2's own "infra is
+	// one all-or-nothing unit" rule means global/handle/* (including HandleController.java.tmpl/
+	// router.py.tmpl) either all wrote together or none did, independent of a SEPARATE resolver
+	// file conflicting -- the manifest should track what ACTUALLY landed on disk, not the overall
+	// command's exit code. Re-reads the manifest fresh rather than reusing `priorManifest`, since
+	// provider.emit() above may have just updated its own `files` tracking via a separate
+	// loadManifest()/saveManifest() pair inside handles/_engine.mjs.
+	if (!dryRun && enforceRegistry !== priorManifest.enforceRegistry) {
+		const freshManifest = loadManifest(root);
+		saveManifest(root, { ...freshManifest, enforceRegistry });
+	}
 	// D4: found live while grounding this against a real fixture -- `written` (pre-existing field,
 	// unchanged semantics) unconditionally includes a java-spring `outputs.spec` file like
 	// migration.sql even when its content is byte-identical (P4 already found this: it's never
@@ -1904,6 +2072,69 @@ function cmdHandlesPatchApprove(args) {
 	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
+// same regardless of which provider backed this feature), so it works even before a scan report
+// exists, as long as `specs/<id>/feature.json` does.
+async function cmdHandlesAudit(args) {
+	const flags = parseCommand('handles audit', args);
+	if (flags.help) { console.log(renderCommandHelp('handles audit')); process.exit(0); }
+	setContext('handles audit', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+	const featureRecord = loadFeatureRecord(root, flags.feature);
+
+	// Same "never read from .env directly, name an already-exported env var" convention as A4's
+	// --database-url-env (D-db-schema-plane) -- reused unchanged, not reinvented.
+	const connectionString = process.env[flags['database-url-env']];
+	if (!connectionString) {
+		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)`);
+	}
+	const resourceTypes = flags.resource ? flags.resource.split(',').map((s) => s.trim()).filter(Boolean) : null;
+
+	let rows;
+	try {
+		rows = await auditHandles({ connectionString, featureUid: featureRecord.feature_uid, resourceTypes });
+	} catch (err) {
+		if (isMissingHandleTables(err)) {
+			fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', `sbf_handle/sbf_handle_snapshot don't exist in this database -- the generated migration.sql (see \`bskel handles emit\`'s own output) was never applied here. bskel never applies a migration automatically (see D-migration-scope in DECISIONS.md).`);
+		}
+		fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', `could not query handle audit data: ${describeConnectionError(err)}`);
+	}
+
+	const summary = summarizeAudit(rows);
+	// Printed in EVERY mode, not just as a doc comment -- this command's whole value is genuinely
+	// capped until O3 (revocation enforcement)/O5 (authorization contracts) close, and that must
+	// not be discoverable only by someone who already read DECISIONS.md prose (see
+	// D-openapi-extraction-hint's own precedent for "the CLI itself carries this warning, not
+	// just documentation").
+	const caveat = 'this reports what the target application chose to record via @RecordHandleSnapshot / record_snapshot -- it is NOT, and cannot be, a security control on its own (see O3/O5 in CATALOG.md for revocation enforcement and authorization contracts). Absence of a snapshot does not mean a handle was never used, only that recording was never opted into for that call path.';
+	const report = {
+		schema: 'sbf.handle-audit/1',
+		feature_id: flags.feature,
+		feature_uid: featureRecord.feature_uid,
+		generated_at: new Date().toISOString(),
+		summary,
+		handles: rows,
+		caveat,
+	};
+
+	if (flags.json) {
+		console.log(JSON.stringify(report, null, 2));
+	} else {
+		console.log(`handle audit -- feature ${flags.feature} (${featureRecord.feature_uid})`);
+		console.log(`  ${summary.total_handles} handle(s), ${summary.revoked_handles} revoked, ${summary.never_snapshotted} never snapshotted, ${summary.total_snapshots} snapshot(s) total`);
+		for (const h of rows) {
+			const revokedNote = h.revoked_at ? ` -- REVOKED (${h.revoked_reason ?? 'no reason recorded'})` : '';
+			const pointerNote = h.pointer ? `#${h.pointer}` : '';
+			console.log(`  ${h.kind} ${h.resource_type}/${h.resource_uid}${pointerNote} -- ${h.snapshot_count} snapshot(s), last ${h.last_recorded_at ?? 'never'}${revokedNote}`);
+		}
+		console.error(`\nnote: ${caveat}`);
+	}
+	process.exit(0);
+}
+
 // S2: "stale" alone sends a human/agent re-running steps until one happens to stick. Name the
 // input that actually moved, using the exact reason requireGate()'s explainStaleness() reports.
 function describeStale(g) {
@@ -2082,6 +2313,10 @@ function cmdDoctor(args) {
 	const adapters = showAdapters
 		? ADAPTERS.map((a) => ({
 			id: a.id, specificity: a.specificity, confidence: a.confidence, capabilities: a.capabilities,
+			// D-adapter-verification-basis: a DIFFERENT axis from confidence (schemas/adapter.
+			// schema.json's own description has the full explanation) -- how well this adapter's
+			// codegen was ever checked against real code, not how sure detect() is about this repo.
+			verificationBasis: a.verificationBasis,
 			// `detect()` itself can return null on a legitimate non-match -- coerce to a real
 			// boolean here so `null` unambiguously means "not applicable, no root" below, not
 			// "detect() happened to return a falsy value".
@@ -2113,7 +2348,7 @@ function cmdDoctor(args) {
 			console.log('Scanner adapters:');
 			for (const a of adapters) {
 				const caps = Object.entries(a.capabilities).filter(([, v]) => v).map(([k]) => k).join(', ') || '(none)';
-				let line = `  ${a.id} (specificity ${a.specificity}, confidence ${a.confidence}) -- capabilities: ${caps}`;
+				let line = `  ${a.id} (specificity ${a.specificity}, confidence ${a.confidence}, verified: ${a.verificationBasis}) -- capabilities: ${caps}`;
 				if (a.detects !== null) line += a.detects ? ' -- DETECTS this repo' : ' -- does not detect this repo';
 				console.log(line);
 				for (const d of a.diagnostics) console.log(`      [${d.level}] ${d.code}: ${d.message}`);
@@ -2364,6 +2599,7 @@ async function dispatchCommand(cmd, rest) {
 			const subArgs = rest.slice(1);
 			if (sub === 'emit') return cmdContractEmit(subArgs);
 			if (sub === 'export') return cmdContractExport(subArgs);
+			if (sub === 'history') return cmdContractHistory(subArgs);
 			if (sub === 'validate') return cmdContractValidate(subArgs);
 			if (sub === 'tool-schema') return cmdContractToolSchema(subArgs);
 			if (sub === 'waive') return cmdContractWaive(subArgs);
@@ -2387,6 +2623,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] === 'audit') return await cmdHandlesAudit(rest.slice(1));
 			usage();
 			process.exit(14);
 			break;
@@ -2408,6 +2645,7 @@ async function dispatchCommand(cmd, rest) {
 			if (sub === 'revoke') return cmdGateRevoke(subArgs);
 			if (sub === 'history') return cmdGateHistory(subArgs);
 			if (sub === 'show') return cmdGateShow(subArgs);
+			if (sub === 'export') return cmdGateExport(subArgs);
 			usage();
 			process.exit(14);
 			break;

package/contracts/completeness.mjs

@@ -105,6 +105,15 @@ export const WARNING_CODES = Object.freeze({
 	// this operation carries is unaffected, this is a missed (opt-in) enhancement, same severity
 	// class as its A7/A8 siblings.
 	CONTRACT_OPENAPI_DESCRIPTION_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
+	// D-unsupported-annotation-warning: the source document uses a schema keyword (title/plural
+	// examples/externalDocs/xml/deprecated) this whole module unconditionally drops -- 0 real
+	// occurrences were ever measured on the one oracle these caps/keyword sets were built against,
+	// but a genuinely different real document can still use any of them. Module-wide, not
+	// per-operation (subject is the keyword NAME, not an operationId) -- contracts/openapi.mjs's
+	// findUnsupportedAnnotations() computes this once per document. WARN: nothing this projection
+	// already copies is affected, this is purely a disclosure that something in the source is
+	// silently unrepresented.
+	CONTRACT_OPENAPI_UNSUPPORTED_ANNOTATION_PRESENT: { severity: SEVERITY.WARN, waivable: true },
 });
 
 export const WARNING_CODE_NAMES = Object.freeze(Object.keys(WARNING_CODES));
@@ -199,10 +208,20 @@ export function saveResolution(root, featureId, resolution) {
 // blocks, waived or not). Deliberately no wildcard match: a waiver only cancels the EXACT
 // code+subject pair recorded for it, so a new unmatched endpoint added later is never silently
 // covered by an old "--all" waive -- see the "waiver invalidation" test in test/contract-cli.test.mjs.
+// D-waiver-expiry: `expires_at` is a genuinely different axis from `staleWaivers` below --
+// staleness means "the warning this waiver covered no longer exists at all" (the underlying
+// problem was fixed), expiry means "the waiver covered a warning that's STILL there, but the
+// grace period the person who filed it granted has run out" -- an expired waiver stops covering
+// 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.
 export function evaluateResolution(contract, resolution) {
 	const status = classifyContract(contract);
 	const waivers = resolution.waivers ?? [];
-	const waivedKeys = new Set(waivers.map(warningKey));
+	const now = Date.now();
+	const expiredWaivers = waivers.filter((w) => typeof w.expires_at === 'string' && Date.parse(w.expires_at) <= now);
+	const expiredKeys = new Set(expiredWaivers.map(warningKey));
+	const waivedKeys = new Set(waivers.filter((w) => !expiredKeys.has(warningKey(w))).map(warningKey));
 
 	const errorWarnings = contract.warnings.filter((w) => w.severity === SEVERITY.ERROR);
 	const unwaived = errorWarnings.filter((w) => !waivedKeys.has(warningKey(w)));
@@ -213,5 +232,5 @@ export function evaluateResolution(contract, resolution) {
 
 	const blocking = status === COMPLETENESS.BLOCKED || unwaived.length > 0;
 
-	return { status, blocking, unwaived, waived, staleWaivers };
+	return { status, blocking, unwaived, waived, staleWaivers, expiredWaivers };
 }

package/contracts/emit.mjs

@@ -103,6 +103,17 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 	const warnings = [];
 	let endpointCount = 0;
 
+	// D-unsupported-annotation-warning: module-wide, computed once, independent of targetModule/
+	// endpoint iteration below -- the source document either uses one of the 5 permanently-dropped
+	// schema keywords or it doesn't, a fact about the WHOLE document, not any one operation.
+	for (const keyword of openapi?.unsupportedAnnotations ?? []) {
+		warnings.push(makeWarning('CONTRACT_OPENAPI_UNSUPPORTED_ANNOTATION_PRESENT', {
+			subject: keyword,
+			message: `the source OpenAPI document uses the schema keyword "${keyword}" at least once -- this projection unconditionally drops it (0 real occurrences were measured against the reference document this behavior was built against, but this document has at least one), so it is never represented in any operation's projected schema`,
+			detail: { keyword },
+		}));
+	}
+
 	if (!targetModule) {
 		warnings.push(makeWarning('CONTRACT_NO_MODULE', {
 			message: 'no related module in the scan report -- emitting an empty operation set. Pass --module, or re-run `bskel scan` with terms that actually match the intended feature.',

package/contracts/openapi.mjs

@@ -179,6 +179,97 @@ const COPIED_KEYWORDS = Object.freeze(new Set([
 // `response-headers`.
 const DOCUMENTATION_KEYWORDS = Object.freeze(new Set(['description', 'example']));
 const DROPPED_KEYWORDS = Object.freeze(new Set(['title', 'examples', 'externalDocs', 'xml', 'deprecated']));
+
+// D-unsupported-annotation-warning: 0 real occurrences on the ONE oracle this whole module's
+// caps/keyword sets were measured against does not mean 0 occurrences everywhere -- a genuinely
+// different real-world document could use any of DROPPED_KEYWORDS, and silently dropping them
+// with no signal at all is a real honesty gap (see D-contract-history/D-gate-export's own backlog
+// for the broader "self-identified weaknesses" context this closes one instance of).
+//
+// Deliberately walks ONLY genuine Schema Object structure (via RECURSED_KEYWORDS, the exact same
+// `properties`/`items`/`additionalProperties`/`oneOf`/`anyOf`/`allOf` set inlineSchema() itself
+// recurses through) -- NOT a blanket "every key anywhere in the document" scan. That distinction
+// is load-bearing, not cosmetic: several of DROPPED_KEYWORDS' names collide with REAL, unrelated
+// OpenAPI concepts that live outside a Schema Object entirely -- an Operation Object's own
+// `deprecated` (marks a whole ENDPOINT deprecated) and a Parameter Object's own `deprecated`, both
+// legitimate 3.1 fields with nothing to do with inlineSchema()'s keyword handling. A blanket walk
+// would misreport those as "an unsupported schema keyword found," which is false. This function
+// only descends from confirmed schema roots (a `$ref`-or-inline `schema` under `content.<media>`
+// or `parameters[].schema`, or a named entry in `components.schemas`), the same roots
+// inlineSchema() itself is ever called on.
+//
+// NOT routed through walkSchemaNode()'s fail-closed machinery -- it must never throw on a shape
+// inlineSchema() itself would reject, since its only job is presence detection, not validation.
+// Bounded for free by loadOpenApiDocument()'s own MAX_DOCUMENT_BYTES check upstream.
+function collectUnsupportedAnnotationKeys(node, found, seen) {
+	if (node === null || typeof node !== 'object' || Array.isArray(node) || seen.has(node)) return;
+	seen.add(node);
+	for (const key of Object.keys(node)) {
+		if (DROPPED_KEYWORDS.has(key)) found.add(key);
+		if (RECURSED_KEYWORDS.has(key)) {
+			const value = node[key];
+			// `properties` is a field-NAME -> schema map (its VALUES are schemas, its keys are not
+			// schema keywords at all) -- a real bug caught live before merge: recursing into the
+			// map object itself, instead of `Object.values(value)`, silently walked past every
+			// property's actual schema and found nothing beneath `properties` ever. `items`/
+			// `additionalProperties` ARE schemas directly; `oneOf`/`anyOf`/`allOf` are arrays of
+			// schemas, already handled by the branch below.
+			if (key === 'properties' && value && typeof value === 'object' && !Array.isArray(value)) {
+				for (const propSchema of Object.values(value)) collectUnsupportedAnnotationKeys(propSchema, found, seen);
+			} else if (Array.isArray(value)) {
+				for (const item of value) collectUnsupportedAnnotationKeys(item, found, seen);
+			} else {
+				collectUnsupportedAnnotationKeys(value, found, seen);
+			}
+		}
+	}
+}
+
+function collectSchemaRootsFromMediaTypes(content, roots) {
+	if (!content || typeof content !== 'object' || Array.isArray(content)) return;
+	for (const mediaEntry of Object.values(content)) {
+		const schema = mediaEntry && typeof mediaEntry === 'object' && !Array.isArray(mediaEntry) ? mediaEntry.schema : null;
+		if (schema && typeof schema === 'object' && !Array.isArray(schema)) roots.push(schema);
+	}
+}
+
+// Every real schema root a document can offer `inlineSchema()`: named `components.schemas`
+// entries, every operation's requestBody/response content schemas, and every operation's
+// parameter schemas -- deliberately NOT `info`/`servers`/`tags`/security schemes, none of which
+// are ever schema-shaped.
+export function findUnsupportedAnnotations(doc) {
+	const roots = [];
+	const schemas = doc.components?.schemas;
+	if (schemas && typeof schemas === 'object' && !Array.isArray(schemas)) roots.push(...Object.values(schemas));
+
+	const paths = doc.paths;
+	if (paths && typeof paths === 'object' && !Array.isArray(paths)) {
+		for (const item of Object.values(paths)) {
+			if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+			for (const [verbOrKey, operation] of Object.entries(item)) {
+				if (!HTTP_METHODS.has(verbOrKey) || !operation || typeof operation !== 'object' || Array.isArray(operation)) continue;
+				collectSchemaRootsFromMediaTypes(operation.requestBody?.content, roots);
+				if (operation.responses && typeof operation.responses === 'object' && !Array.isArray(operation.responses)) {
+					for (const resp of Object.values(operation.responses)) {
+						collectSchemaRootsFromMediaTypes(resp?.content, roots);
+					}
+				}
+				if (Array.isArray(operation.parameters)) {
+					for (const p of operation.parameters) {
+						if (p && typeof p === 'object' && !Array.isArray(p) && p.schema && typeof p.schema === 'object' && !Array.isArray(p.schema)) {
+							roots.push(p.schema);
+						}
+					}
+				}
+			}
+		}
+	}
+
+	const found = new Set();
+	const seen = new Set();
+	for (const root of roots) collectUnsupportedAnnotationKeys(root, found, seen);
+	return [...found].sort();
+}
 // Real Team-IZ-Backend format-value histogram (request-body-reachable schemas only): uuid(20),
 // int32(10), email(7), date(10), date-time(3), int64(2). `uuid` is handled separately (rewritten
 // to BARE_UUID_PATTERN, see inlineSchema) -- not in this set, since it never survives as `format`.
@@ -1481,6 +1572,10 @@ export function buildReconciliation({ filePath, module, pathPrefix = null, inclu
 		// A7: only schemes actually referenced by at least one copied sourceSecurity requirement --
 		// contracts/emit.mjs attaches this at the contract root when non-empty.
 		sourceSecuritySchemes: recon.sourceSecuritySchemes,
+		// D-unsupported-annotation-warning: computed once per document, not per-operation -- a
+		// module-wide presence signal, not a per-operation fact, so contracts/emit.mjs pushes at
+		// most one warning per keyword name for the whole module, not one per operation.
+		unsupportedAnnotations: findUnsupportedAnnotations(loaded.doc),
 	};
 }