backend-skeleton 1.0.0 → 1.1.0

package/README.md

@@ -23,6 +23,29 @@ of just another thing to double-check by hand.
 commits behind the real default branch and never noticed. Every gate in this tool is a regression
 check for a specific failure mode found the same way — see `DECISIONS.md` for the full record.
 
+![bskel run against a real fixture repo: preflight, a brownfield collision scan, and a feature status gate table](https://raw.githubusercontent.com/popixoxipop-collab/backend-skeleton/main/docs/demo.gif)
+
+*A real terminal, a real `bskel` binary, a real fixture repo — not a scripted transcript. Source:
+[`docs/demo.tape`](docs/demo.tape), regenerated with [`docs/record-demo.sh`](docs/record-demo.sh).*
+
+## Contents
+
+- [Status: 1.0.0](#status-100)
+- [Quickstart](#quickstart)
+  - [Starting from nothing (greenfield)](#starting-from-nothing-greenfield)
+  - [Publishing a feature's contract as OpenAPI (optional)](#publishing-a-features-contract-as-openapi-optional)
+  - [Database schema (optional)](#database-schema-optional)
+  - [Applying DDL to a live database (optional)](#applying-ddl-to-a-live-database-optional)
+  - [Declaring field-to-field dependencies (optional)](#declaring-field-to-field-dependencies-optional)
+  - [Patching a config file (optional)](#patching-a-config-file-optional)
+  - [Signed gate attestations (optional)](#signed-gate-attestations-optional)
+- [Compatibility](#compatibility)
+- [Generated-file policy](#generated-file-policy)
+- [Security model](#security-model)
+- [Troubleshooting](#troubleshooting)
+- [What ships in the package](#what-ships-in-the-package)
+- [License](#license)
+
 ## Status: 1.0.0
 
 As of `1.0.0`, this project makes an explicit API-stability promise: **`bskel`'s CLI surface --
@@ -50,10 +73,13 @@ production -- which still splits the same way it always has:
   gaps remain and are explicitly still open, not closed: registry enforcement is opt-in, off by
   default; authorization inference now recognizes both `@PreAuthorize(hasRole(...))` and
   `hasAuthority(...)` (see `DECISIONS.md`'s `D-resolver-authorization-action-aware`), but
-  `hasAnyRole`/`hasAnyAuthority` (list-shape), ownership, and tenant policy are still unaddressed;
-  and Java/Python are the only providers either applies to -- TypeScript Express has no persistent
-  handle table at all. Treat `handles emit`'s output as a scaffold to finish by hand, not a
-  production-ready subsystem, until a real deployment happens.
+  `hasAnyRole`/`hasAnyAuthority` (list-shape), ownership, and tenant policy are still unaddressed.
+  All three providers (Java/Python/TypeScript) now generate a real `sbf_handle`/
+  `sbf_handle_snapshot` schema and support `--enforce-registry`/`recover()` -- TypeScript's own
+  registration mechanism is a higher-order wrapper function, not a decorator (no Java-AOP or
+  Python-decorator equivalent exists in this ecosystem the templates could safely rely on; see
+  `D-typescript-express-registry-parity` in `DECISIONS.md`). Treat `handles emit`'s output as a
+  scaffold to finish by hand, not a production-ready subsystem, until a real deployment happens.
 
 ## Quickstart
 
@@ -86,6 +112,36 @@ bskel verify --feature 001-organization-management --build
                                    #   target repo's own build wrapper (gradlew/mvnw/npm), if present
 ```
 
+`bskel status`/`bskel next` are what you actually run over and over — real output, captured against
+a fixture repo partway through the flow above, not written by hand:
+
+```text
+$ bskel status --feature 001-organization-management
+# Status: 001-organization-management
+
+## Gates
+- [PASS] preflight
+- [PASS] scan
+- [(not_run)] cross_feature (required-when-present, feature-scoped)
+- [BLOCKING] contract
+- [(not_run)] dependencies (required-when-present, feature-scoped)
+- [(not_run)] handles (required-when-present, feature-scoped)
+- [(not_run)] stack (required-when-present, repo-scoped)
+- [(not_run)] patch_transactions (required-when-present, feature-scoped)
+- [(not_run)] conformance (required-when-present, feature-scoped)
+
+## Artifacts
+- [OK] contract: specs/001-organization-management/contracts/001-organization-management.schema.json
+
+## Next
+- bskel contract waive --feature 001-organization-management --code <CODE> (--subject "..."|--all) --reason "..."   # or: bskel gate force contract --feature 001-organization-management --reason "..." if intentional   # contract gate is awaiting disposition
+
+## Optional, not yet run: handles, stack
+```
+
+Every gate line is a real, disk-verified check — the `Next` line is always the exact command to
+unblock whatever's currently `BLOCKING`, so there's no separate doc to cross-reference mid-workflow.
+
 ### Starting from nothing (greenfield)
 
 Every command above assumes an existing Spring Boot or FastAPI repo. If you don't have one yet:
@@ -246,6 +302,12 @@ between the two — and, like every other mutating command in this project, both
 not query parameters. `GET`/`HEAD` responses carry `Access-Control-Allow-Origin: *`; the mutating
 routes never do, so only same-origin requests (the bundled UI itself) can write.
 
+![bskel serve's dependency-graph UI, showing a real declared field-to-field dependency resolved as synced](https://raw.githubusercontent.com/popixoxipop-collab/backend-skeleton/main/docs/serve-ui.png)
+
+*The page's own header describes it honestly: "Not a redesign of the original Fieldwire mockup --
+this exists to prove the API actually works, nothing more." It's a minimal read-only check page, not
+a polished dashboard — every table on it comes straight from `GET /api/graph`.*
+
 ### Patching a config file (optional)
 
 `bskel stack apply`'s `config_check` sometimes reports `needs-manual-patch` — a target file exists

package/bin/bskel.mjs

@@ -9,10 +9,10 @@ import { repoRoot, localDefaultBranch, fileHistory, showFileAtRevision, headSha,
 import { forceNamedGate, revokeNamedGate, requireNamedGate, passNamedGate, awaitNamedGateDisposition, EXIT } from '../lib/gates.mjs';
 import { REPO_GATE_ID, GATE_NAMES, gateScopeId, requireGateDefinition } from '../lib/gate-definitions.mjs';
 import { getGate, loadState, historyPath } from '../lib/state.mjs';
-import { writeFileAtomic, sha256File } from '../lib/fsutil.mjs';
+import { writeFileAtomic, sha256File, readJsonIfExists } from '../lib/fsutil.mjs';
 import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
 import { withLockSync } from '../lib/lock.mjs';
-import { specDir, specPath } from '../lib/paths.mjs';
+import { specDir, specPath, sbfPath } from '../lib/paths.mjs';
 import { requireValidFeatureId, requireValidSlug, requireValidFeatureOrRepoId, slugWords, nextFeatureNumber } from '../lib/featureid.mjs';
 import {
 	loadFeatureFile, saveFeatureFile, loadFeatureIndex, saveFeatureIndex,
@@ -56,6 +56,7 @@ import { loadCatalogEntry, listCatalogChoices, planApply, applyPlan } from '../s
 import { PROVIDERS, PROVIDER_LOAD_ERRORS, providerById } from '../handles/registry.mjs';
 import { detectAstHelperAvailable, runAstClassify } from '../handles/providers/java-spring/ast-bridge.mjs';
 import { detectBasePackage } from '../handles/providers/java-spring/plan.mjs';
+import { hasSpringAopDependency, springAopArtifactName } from '../handles/providers/java-spring/emit.mjs';
 import { emitObserveJavaSpring } from '../handles/providers/java-spring/observe.mjs';
 import { plan as planPythonFastApi } from '../handles/providers/python-fastapi/plan.mjs';
 import { emitObservePythonFastApi } from '../handles/providers/python-fastapi/observe.mjs';
@@ -96,12 +97,12 @@ function usage() {
   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 stack apply --choice <id> [--apply] [--port N] [--json]
+  bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."] [--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] [--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 handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--module <name>] [--check-registry-coverage] [--json]
   bskel patch propose --feature <id> [--kind config-apply|ddl-apply] --choice <stackChoiceId> --target <config_check target path> --database-url-env <NAME> --schema <name> --sql-file <path> [--json]
   bskel patch approve --feature <id> --transaction <id> --reason "..." [--json]
   bskel patch apply --feature <id> --transaction <id> [--confirm <id-or-dropped-table-name>] [--json]
@@ -1867,14 +1868,29 @@ function cmdContractToolSchema(args) {
 	}
 
 	// Anthropic tool-use `input_schema` is a JSON Schema subset -- the operation's payload
-	// schema (already plain JSON Schema, no $ref/$defs) is directly usable as-is. A2: when `op`
-	// carries a projected `requestBodySchema`, it flows through here for free -- this function
-	// changed not at all; contracts/openapi.mjs's inlineSchema() is what guarantees the no-$ref
-	// promise this comment makes.
+	// schema is directly usable as-is UNLESS it's recursive. Confirmed against Anthropic's own
+	// documented JSON Schema limitations (platform.claude.com/docs/en/build-with-claude/
+	// structured-outputs): internal (non-external-URL) $ref/$defs ARE supported, but "recursive
+	// schemas" are explicitly listed as unsupported and return a real 400 error at the API. A2:
+	// when `op` carries a projected `requestBodySchema`, it flows through here for free -- this
+	// function changed not at all. D-openapi-cyclic-refs: contracts/openapi.mjs's inlineSchema()
+	// now emits `$ref`/`$defs` for a genuinely cyclic component (e.g. a real recursive
+	// filter-group tree) rather than failing the whole projection closed -- that's real progress
+	// for `contract validate`/`contract export`, but this ONE consumer genuinely cannot accept
+	// it: refuse explicitly here, citing the real reason, rather than emitting a schema that
+	// would only fail later at the actual Anthropic API call site.
+	const inputSchema = operationPayloadSchema(op);
+	if (inputSchema && Object.hasOwn(inputSchema, '$defs')) {
+		fail(
+			EXIT_CODES.NOT_PASSED,
+			'RECURSIVE_SCHEMA_UNSUPPORTED',
+			`operation "${flags.operation}"'s payload schema is recursive (a genuinely self-referential real shape, e.g. a nested filter-group tree) -- Anthropic tool-use input_schema does not support recursive schemas (see platform.claude.com/docs/en/build-with-claude/structured-outputs), so no tool-use schema can be generated for this operation`,
+		);
+	}
 	const toolSchema = {
 		name: flags.operation,
 		description: `${op.verb} ${op.path} (feature ${flags.feature})`,
-		input_schema: operationPayloadSchema(op),
+		input_schema: inputSchema,
 	};
 	console.log(JSON.stringify(toolSchema, null, 2));
 	process.exit(0);
@@ -1904,7 +1920,13 @@ function cmdStackApply(args) {
 	const root = requireRepoRoot();
 	requirePreflightPassed(root);
 	if (!flags.choice) {
-		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `usage: bskel stack apply --choice <id> [--apply] [--port N]   (known choices: ${listCatalogChoices().join(', ') || '(none)'})`);
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `usage: bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."]   (known choices: ${listCatalogChoices().join(', ') || '(none)'})`);
+	}
+	// D-write-safety-phase0 (item 2): mirrors handles emit's own --force/--reason validation --
+	// every overwrite of a file that diverged from what `stack apply` itself last wrote must be
+	// auditable.
+	if (flags.force && (!flags.reason || !flags.reason.trim())) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel stack apply --force requires --reason "..." -- every overwrite of a diverged generated file must be auditable');
 	}
 
 	let entry;
@@ -1928,12 +1950,21 @@ function cmdStackApply(args) {
 		process.exit(0);
 	}
 
-	let written;
+	let written, conflicts, fileHashes;
 	try {
-		written = applyPlan(root, plan);
+		({ written, conflicts, fileHashes } = applyPlan(root, plan, { force: flags.force }));
 	} catch (err) {
 		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
 	}
+	// D-write-safety-phase0 (item 2): a file that diverged from what `stack apply` itself last
+	// wrote is refused outright without --force -- mirrors handles emit's own conflict-refusal
+	// exactly, including the exit code family (a new, dedicated STACK_CONFLICT rather than reusing
+	// HANDLES_CONFLICT, since this is a different write surface).
+	if (conflicts.length > 0) {
+		console.error(`refusing to overwrite ${conflicts.length} file(s) that diverged from what \`bskel stack apply\` last generated${flags.force ? '' : ' -- pass --force --reason "..." to overwrite (only if the divergence is git-recoverable)'}:`);
+		for (const c of conflicts) console.error(`  ${c.path}\n    ${c.reason}`);
+		process.exit(EXIT_CODES.STACK_CONFLICT);
+	}
 	// S2: `applied_files` must be this choice's FULL file set in this repo (its desired state),
 	// not just whatever `applyPlan()` happened to write THIS run -- applyPlan() skips files whose
 	// action is 'unchanged', so a second, idempotent `--apply` used to overwrite this with `[]`,
@@ -1944,17 +1975,22 @@ function cmdStackApply(args) {
 		...plan.files.map((f) => f.path),
 		...(plan.envExampleActions.length > 0 ? ['.env.example'] : []),
 	])].sort();
+	// D-write-safety-phase0 (item 2): `fileHashes` only covers files applyPlan() actually wrote
+	// THIS run -- an unchanged file isn't in it, so this merges onto the PRIOR record's file_hashes
+	// (now a genuine read boundary -- planApply() reads this same record to classify files, see
+	// stack/apply.mjs) rather than replacing it wholesale, or an unchanged file's provenance would
+	// be lost on every apply after the first.
+	const priorRecord = readJsonIfExists(sbfPath(root, 'stack.json'));
 	const stackRecord = {
 		schema: 'sbf.stack/1', choice: flags.choice, applied_files: appliedFiles,
 		env_example_keys: plan.envExampleActions.map((e) => e.key), at: new Date().toISOString(),
+		file_hashes: { ...(priorRecord?.file_hashes ?? {}), ...fileHashes },
 	};
 	// S5 (D-persistence-integrity): schemas/stack-record.schema.json is new -- this record had NO
 	// schema at all before (not the same file as stack-choice.schema.json, which validates a
 	// stack/catalog/<id>.yml CATALOG ENTRY, a completely different persistence boundary). Validated
 	// before it touches disk, same "fail loud here" reasoning as every other write site this item
-	// touched. No corresponding read helper -- nothing in this codebase reads .sbf/stack.json back
-	// (confirmed by grep before adding this), so there's no read boundary to close yet; adding an
-	// unused loadStackRecord() export would just be dead code.
+	// touched.
 	{
 		const { ok, errors } = validateAgainstSchema('stack-record.schema.json', stackRecord);
 		if (!ok) {
@@ -2078,8 +2114,10 @@ function writeScanReportOrExit(reportPath, report) {
 }
 
 // D4 (D-handles-dryrun): the marker vocabulary a human report uses for classifyFile()'s 6
-// possible actions (+ the java-spring-only 'spec' kind, which reuses the same 3 labels since it's
-// classified the same 3-way create/unchanged/update, just outside classifyFile() itself).
+// possible actions (+ the 'spec' kind every observe.mjs provider uses for its always-regenerated
+// observed-schema.json, which reuses the same 3 labels since it's classified the same 3-way
+// create/unchanged/update, just outside classifyFile() itself -- migration.sql used to be the
+// other 'spec' user too, until D-write-safety-phase0 moved it onto real manifest tracking).
 const ACTION_MARKERS = { create: '+', unchanged: '=', update: '~', 'adopt-unchanged': '=', 'adopt-update': '~', conflict: '!' };
 
 // D4: shared between `handles plan`'s preview and `handles emit --check`'s report -- both show
@@ -2327,6 +2365,21 @@ function cmdHandlesEmit(args) {
 	requireCapabilitiesOrExit(scanReport, 'handles emit', { featureId: flags.feature, scanReportPath });
 	const provider = selectProviderOrExit(scanReport);
 	requireProviderCapabilitiesOrExit(scanReport, provider, 'handles emit', { featureId: flags.feature, scanReportPath });
+
+	// D-write-safety-phase1 (item 1): HandleAspect.java cannot intercept anything without
+	// spring-boot-starter-aop on the target's own classpath -- refusing here, before any code is
+	// written, rather than letting the operator discover it only after `--enforce-registry on`
+	// silently produces resolvers that will 404 every fetch/patch. java-spring only: python-fastapi's
+	// @record_snapshot decorator needs no extra dependency (see python-fastapi/emit.mjs's own note).
+	if (enforceRegistry && scanReport.adapter === 'java-spring' && !hasSpringAopDependency(root)) {
+		// D-handles-pilot-cohort: the correct artifact name is version-dependent (spring-boot-starter-aop
+		// before Spring Boot 4, spring-boot-starter-aspectj from Spring Boot 4 on -- confirmed against
+		// a real Spring Boot 4.1.0 target, the old artifact is a genuine 404 on Maven Central for it).
+		// springAopArtifactName(root) names the one THIS repo's own detected Boot version actually needs.
+		const artifactName = springAopArtifactName(root);
+		fail(EXIT_CODES.HANDLES_MISSING_DEPENDENCY, 'HANDLES_MISSING_DEPENDENCY', `bskel handles emit --enforce-registry on requires ${artifactName} on this repo's own build.gradle/build.gradle.kts/pom.xml classpath -- HandleAspect.java (the class that actually intercepts @RecordHandleSnapshot-annotated methods) does nothing without it, and no other Spring starter enables AOP. Add the dependency to your build file, then re-run.`);
+	}
+
 	const resourceFilter = flags.resource ? flags.resource.split(',').map((s) => s.trim()).filter(Boolean) : null;
 
 	let plan;
@@ -2339,7 +2392,7 @@ function cmdHandlesEmit(args) {
 	// a diff" that also means "and actually write it", so --diff forces dryRun the same as --check
 	// does, without requiring both flags together.
 	const dryRun = flags.check || flags.diff;
-	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [] } = provider.emit({
+	const { written, resolverStubs, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [], registrationGaps = [] } = provider.emit({
 		repoRoot: root, featureId: flags.feature, plan, resourceFilter, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff, enforceRegistry,
 	});
 
@@ -2400,6 +2453,25 @@ function cmdHandlesEmit(args) {
 		process.exit(EXIT_CODES.HANDLES_CONFLICT);
 	}
 
+	// D-write-safety-phase1 (item 2): a registration gap is checked separately from `blocked`
+	// above (conflicts are already handled and exited by this point) -- semantically different
+	// reason (a hand-written file bskel never touches lacking an annotation it cannot add itself,
+	// not a generated file diverging), so its own dedicated exit code and message. Unlike a
+	// conflict, the resolver files ARE still written either way (there is nothing wrong with their
+	// content) -- only the overall command's reported success, and the `handles` gate passing, are
+	// gated on acknowledging the gap with --force --reason.
+	if (enforceRegistry && registrationGaps.length > 0 && !flags.force) {
+		if (flags.json) {
+			console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, registrationGaps, blocked: true, gate: null, check: dryRun }, null, 2));
+		} else {
+			const verb = dryRun ? 'would refuse to report success' : 'refusing to report success';
+			console.error(`${verb}: ${registrationGaps.length} resource(s) have --enforce-registry on but no static registration path found:`);
+			for (const g of registrationGaps) console.error(`  ${g.resourceType} (${g.file})\n    ${g.note}`);
+			if (!dryRun) console.error(`\nthe resolver file(s) above were still written -- nothing about their content is wrong. Fix the registration gap and re-run, or acknowledge and proceed with: bskel handles emit --feature ${flags.feature}${flags.module ? ` --module ${flags.module}` : ''}${flags.resource ? ` --resource ${flags.resource}` : ''} --enforce-registry on --force --reason "..."`);
+		}
+		process.exit(EXIT_CODES.HANDLES_REGISTRATION_GAP);
+	}
+
 	// D4: dryRun never marks the gate passed -- nothing real happened this run.
 	const gateState = dryRun ? null : passNamedGate(root, 'handles', flags.feature, { resolverStubs });
 
@@ -2718,6 +2790,35 @@ async function cmdHandlesAudit(args) {
 	// 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.';
+
+	// D-write-safety-phase1 (item 3): the live-database closure of D-handle-registry-enforcement's
+	// own named EXIT gap ("an already-empty registry... would need live target-app database
+	// access, a larger scope than this item's own"). Opt-in: resolves the CURRENT plan the same
+	// way `cmdHandlesPlan` does, then cross-references the rows already fetched above against each
+	// resource type the plan will actually generate a resolver for -- a real answer to "will
+	// --enforce-registry on 404 on its very first fetch for this resource", checked against the
+	// live database rather than a static regex proxy.
+	let registryCoverage = null;
+	if (flags['check-registry-coverage']) {
+		const scanReport = loadScanReportOrExit(root, flags.feature);
+		const scanReportPath = specPath(root, flags.feature, 'brownfield-scan.json');
+		requireCapabilitiesOrExit(scanReport, 'handles audit --check-registry-coverage', { featureId: flags.feature, scanReportPath });
+		const provider = selectProviderOrExit(scanReport);
+		requireProviderCapabilitiesOrExit(scanReport, provider, 'handles audit --check-registry-coverage', { featureId: flags.feature, scanReportPath });
+		let plan;
+		try {
+			plan = provider.plan({ repoRoot: root, scanReport, module: flags.module, resourceFilter: resourceTypes });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		registryCoverage = plan.resources
+			.filter((r) => r.willGenerateResolver)
+			.map((r) => ({
+				resourceType: r.type,
+				covered: rows.some((row) => row.resource_type === r.type && row.kind === 'r' && row.revoked_at === null),
+			}));
+	}
+
 	const report = {
 		schema: 'sbf.handle-audit/1',
 		feature_id: flags.feature,
@@ -2725,6 +2826,7 @@ async function cmdHandlesAudit(args) {
 		generated_at: new Date().toISOString(),
 		summary,
 		handles: rows,
+		registry_coverage: registryCoverage,
 		caveat,
 	};
 
@@ -2738,6 +2840,11 @@ async function cmdHandlesAudit(args) {
 			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}`);
 		}
+		if (registryCoverage) {
+			console.log('\nregistry coverage (would --enforce-registry on 404 on the first fetch for this resource?):');
+			for (const c of registryCoverage) console.log(`  ${c.resourceType}: ${c.covered ? 'covered' : 'NOT COVERED -- no non-revoked kind=r row exists yet'}`);
+			if (registryCoverage.length === 0) console.log('  (no resources in this plan will generate a resolver)');
+		}
 		console.error(`\nnote: ${caveat}`);
 	}
 	process.exit(0);

package/contracts/export.mjs

@@ -82,8 +82,18 @@ const ERROR_RESPONSE_DESCRIPTION = 'Error. The source contract records the union
 // meaning moves from "never built" to "content-AND-flag-conditional"), while `title`/`examples`
 // (plural)/`externalDocs`/`xml`/`deprecated` move to a new, narrower structural entry
 // (`field-metadata`) -- measured 0 real occurrences each against the Team-IZ-Backend oracle, so
-// they stay permanently unbuilt on the same "don't build for zero real cases" grounds as the two
-// A8 entries below, not this item's scope. What else stays structural: `vendor-extensions` (x-*
+// they stayed unbuilt on the same "don't build for zero real cases" grounds as the two A8 entries
+// below, not this item's scope.
+// A14 (D-openapi-field-metadata-passthrough): D-oracle-corpus-openapi-remeasurement (ROADMAP
+// Phase 5c) found `title`/plural `examples`/`deprecated` DO occur for real against a much larger
+// second corpus (polarsource/polar, 1046 component schemas vs 308) -- those 3 of the original 5
+// `field-metadata` keywords are now conditionally copied (contracts/openapi.mjs's
+// DOCUMENTATION_KEYWORDS), same "gated on --descriptions" doctrine as A11's own description/
+// example. `field-metadata` migrates from a STRUCTURAL (always-present) omission to an ANY-based
+// one below -- the exact same migration A10 made for `operation-descriptions` when it left the
+// original single `descriptions` structural entry. `externalDocs`/`xml` remain 0 real occurrences
+// even at Polar's scale, so THOSE two keep the narrower structural entry
+// `external-docs-and-xml-metadata`. What else stays structural: `vendor-extensions` (x-*
 // keys on an operation are never copied -- excluded in principle, not by cap or failure, since
 // their semantics are tool-specific), and two A8 additions: `non-json-response-schemas` (a non-JSON
 // response media type's NAME is copied via a per-status entry's `mediaTypes`, but its SHAPE is never
@@ -92,7 +102,7 @@ const ERROR_RESPONSE_DESCRIPTION = 'Error. The source contract records the union
 // -- 0/694 real occurrences, a genuinely visible gap only now that per-status responses look
 // complete).
 const STRUCTURAL_OMISSIONS = Object.freeze([
-	'field-metadata',
+	'external-docs-and-xml-metadata',
 	'non-json-response-schemas',
 	'response-headers',
 	'vendor-extensions',
@@ -102,7 +112,8 @@ const OMISSION_PROSE = Object.freeze({
 	'cookie-parameters': 'cookie parameters, for at least one operation that does not carry a fully-copied set (never emitted at all when --openapi-file was not given, or the source document declared none)',
 	'error-schemas': 'a JSON error-body schema for at least one operation',
 	'field-descriptions': 'a schema field\'s own `description`/`example` (a property\'s own annotation, distinct from the operation-level `description` field -- see `operation-descriptions` below), for at least one field in the request-body/response/error schema of at least one operation -- copied only when `contract emit --descriptions` was used (the same flag as operation-level description) AND the source declared one for that exact field AND it did not exceed the length/size cap; otherwise the field carries no `description`/`example` key, never synthesized. Not tracked separately for per-status responses, non-JSON request media types, or path-parameter schemas -- those may carry field docs when the flag is on, but their presence is not reflected in this specific omission entry',
-	'field-metadata': 'a schema field\'s `title`, plural `examples`, `externalDocs`, `xml`, or `deprecated` keyword -- dropped unconditionally while inlining a schema (contracts/openapi.mjs\'s DROPPED_KEYWORDS), regardless of `--descriptions`. Permanently unbuilt: 0 real occurrences of any of these five measured against the Team-IZ-Backend oracle',
+	'field-metadata': 'a schema field\'s `title`, plural `examples`, or `deprecated` keyword, for at least one field in the request-body/response/error schema of at least one operation -- copied only when `--descriptions` is passed (contracts/openapi.mjs\'s DOCUMENTATION_KEYWORDS, A14/D-openapi-field-metadata-passthrough), same doctrine as `field-descriptions`. Present whenever the flag was not used at all, none of this operation\'s projected schemas carry any of the three, or the value exceeded its cap (MAX_TITLE_LENGTH/MAX_EXAMPLES_ARRAY_LENGTH/MAX_EXAMPLE_LENGTH)',
+	'external-docs-and-xml-metadata': 'a schema field\'s `externalDocs` or `xml` keyword -- dropped unconditionally while inlining a schema (contracts/openapi.mjs\'s DROPPED_KEYWORDS), regardless of `--descriptions`. Permanently unbuilt: 0 real occurrences of either keyword measured against either real corpus (the original Team-IZ-Backend oracle or the larger polarsource/polar re-measurement) -- see D-oracle-corpus-openapi-remeasurement in DECISIONS.md',
 	'header-parameters': 'header parameters, for at least one operation that does not carry a fully-copied set (never emitted at all when --openapi-file was not given, or the source document declared none)',
 	'non-json-request-media-types': 'the media type of the request body, for at least one operation that takes one -- a non-application/json request media type is emitted only when a real source document declared one for that exact operation, copied byte-for-byte; otherwise this document shows a JSON media-type entry because that is all the contract knows, never because the real body is known to be JSON',
 	'non-json-response-schemas': 'a JSON Schema for any response body in a media type other than application/json -- the media type is named where a source document declared one for that status, but its shape is never projected',
@@ -145,6 +156,26 @@ function schemaHasFieldDocs(node, seen = new Set()) {
 	return false;
 }
 
+// A14 (D-openapi-field-metadata-passthrough): the exact same recursive shape as schemaHasFieldDocs
+// above, checking the OTHER three DOCUMENTATION_KEYWORDS (title/examples/deprecated) instead of
+// description/example -- kept as a separate function rather than merged into schemaHasFieldDocs
+// so the two disclosure keys (`field-descriptions` vs `field-metadata`) stay independently
+// derived from what's ACTUALLY in the projected schema, not conflated into one flag a caller
+// can't tell apart.
+function schemaHasFieldMetadata(node, seen = new Set()) {
+	if (node === null || typeof node !== 'object' || Array.isArray(node) || seen.has(node)) return false;
+	seen.add(node);
+	if (typeof node.title === 'string' || Object.hasOwn(node, 'examples') || Object.hasOwn(node, 'deprecated')) return true;
+	if (node.properties && typeof node.properties === 'object' && !Array.isArray(node.properties)) {
+		for (const propSchema of Object.values(node.properties)) {
+			if (schemaHasFieldMetadata(propSchema, seen)) return true;
+		}
+	}
+	if (node.items && typeof node.items === 'object' && schemaHasFieldMetadata(node.items, seen)) return true;
+	if (node.additionalProperties && typeof node.additionalProperties === 'object' && schemaHasFieldMetadata(node.additionalProperties, seen)) return true;
+	return false;
+}
+
 // Derived from the contract's ACTUAL content, not hardcoded -- an operation that takes a body but
 // has no projected schema, or has no response/error schema, each add their own entry, so the list
 // says what is missing from THIS document rather than reciting a fixed disclaimer.
@@ -196,6 +227,10 @@ export function collectOmissions(contract) {
 		// not gated on whether a schema exists first.
 		const fieldSchemas = [op.requestBodySchema, op.responseSchema, op.errorSchema].filter(Boolean);
 		if (!fieldSchemas.some((s) => schemaHasFieldDocs(s))) omissions.add('field-descriptions');
+		// A14: same ANY-based doctrine as field-descriptions immediately above -- added whenever
+		// NONE of this operation's projected schemas carry a field-level title/examples/deprecated,
+		// including the case where the operation has no projected schema at all.
+		if (!fieldSchemas.some((s) => schemaHasFieldMetadata(s))) omissions.add('field-metadata');
 	}
 	return [...omissions].sort();
 }