backend-skeleton 1.0.0-beta.2 → 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
@@ -133,8 +138,13 @@ operation, copied byte-for-byte, never reconstructed. `security: []` is emitted
 document itself said `[]` (a genuine claim that no authentication is required); it is never
 invented as a default. Where no source document was given, or it said nothing for an operation
 (or a particular field of one), the key is simply omitted, meaning "unspecified." Operation-level
-`description` remains excluded — measured too expensive to copy by default (real average 2,442.7
-bytes/operation).
+`description` is copied too, but **opt-in only** (`contract emit --descriptions`) — measured too
+expensive to copy by default (real average 2,442.7 bytes/operation, larger than every other field
+this projection copies combined). The same flag also copies a schema FIELD's own `description`/
+`example` (a property's own annotation, not the operation's) one level deeper into request-body/
+response/error/parameter/per-status/path-param schemas — `title`, plural `examples`,
+`externalDocs`, `xml`, and `deprecated` stay unconditionally dropped either way (0 real occurrences
+measured against the Team-IZ-Backend oracle).
 
 Export refuses a zero-operation contract, refuses when the scan found a global path prefix the
 contract's paths don't reflect (`--allow-unprefixed` overrides), and stamps every document with an

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,
@@ -65,16 +67,18 @@ function usage() {
   bskel feature rename <id> --to <new-slug> --reason "..." [--json]
   bskel feature link <keepId> <aliasId> --reason "..." [--json]
   bskel feature archive <id> --reason "..." [--json]
-  bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0]
+  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
@@ -844,6 +891,11 @@ function cmdContractEmit(args) {
 	if (flags['path-prefix'] && !flags['openapi-file']) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--path-prefix only applies when reconciling against a real OpenAPI document -- pass --openapi-file <path> together with it, or drop --path-prefix (the value has no effect on its own).`);
 	}
+	// A10: same "would be a silent no-op" reasoning as --path-prefix above -- --descriptions only has
+	// any effect inside buildReconciliation(), which only runs when --openapi-file is also given.
+	if (flags.descriptions && !flags['openapi-file']) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--descriptions only applies when reconciling against a real OpenAPI document -- pass --openapi-file <path> together with it, or drop --descriptions (it has no effect on its own).`);
+	}
 
 	const root = requireRepoRoot();
 	requirePreflightPassed(root);
@@ -878,7 +930,7 @@ function cmdContractEmit(args) {
 	if (flags['openapi-file']) {
 		const targetModule = selectModule(scanReport, flags.module);
 		if (targetModule) {
-			const result = buildReconciliation({ filePath: flags['openapi-file'], module: targetModule, pathPrefix: flags['path-prefix'] });
+			const result = buildReconciliation({ filePath: flags['openapi-file'], module: targetModule, pathPrefix: flags['path-prefix'], includeDescriptions: flags.descriptions });
 			if (!result.ok) {
 				fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', result.error);
 			}
@@ -937,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,
@@ -978,10 +1031,20 @@ function cmdContractEmit(args) {
 				console.log(`openapi: ${p.parameters_copied} operation(s) with parameters copied (${p.parameters_unresolved} partial/unresolved), ${p.security_copied + p.security_public} with security copied, ${p.summary_copied} summaries + ${p.tags_copied} tag sets copied`);
 				// A8: same "just print the numbers" style.
 				console.log(`openapi: ${p.per_status_copied} operation(s) with per-status responses copied, ${p.request_media_types_copied} with non-JSON request media type(s) copied`);
+				// A10: printed only when --descriptions was actually passed -- unlike A7/A8/A9's
+				// default-on fields, printing "0 copied" unconditionally here would misleadingly
+				// suggest this opt-in field was attempted when it never was.
+				if (flags.descriptions) {
+					console.log(`openapi: ${p.description_copied} operation(s) with description copied, ${p.description_unresolved} unresolved`);
+				}
 			}
 		}
 		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 ?? '*'})`);
@@ -1186,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) {
@@ -1203,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') {
@@ -1236,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,
@@ -1254,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 })) })
@@ -1263,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})`);
@@ -1274,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); }
@@ -1561,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) {
@@ -1722,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);
@@ -1755,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
@@ -1893,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) {
@@ -2071,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".
@@ -2102,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}`);
@@ -2353,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);
@@ -2376,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;
@@ -2397,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

@@ -99,6 +99,21 @@ export const WARNING_CODES = Object.freeze({
 	// it reuses CONTRACT_OPENAPI_RESPONSE_SCHEMA_UNRESOLVED/CONTRACT_OPENAPI_ERROR_SCHEMA_UNRESOLVED
 	// unchanged -- see D-openapi-per-status.
 	CONTRACT_OPENAPI_REQUEST_MEDIA_TYPE_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
+	// A10: the operation's description exceeded MAX_DESCRIPTION_LENGTH -- independent of every code
+	// above (nothing else tracks description length), so it gets its own code rather than reusing
+	// one, same reasoning A8 used to justify its own new multipart code. WARN: every other field
+	// 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));
@@ -193,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)));
@@ -207,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 };
 }