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

package/README.md

@@ -133,8 +133,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

@@ -65,7 +65,7 @@ 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 validate --feature <id> --file <envelope.json>
   bskel contract tool-schema --feature <id> --operation <operationId>
@@ -844,6 +844,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 +883,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);
 			}
@@ -978,6 +983,12 @@ 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}`);

package/contracts/completeness.mjs

@@ -99,6 +99,12 @@ 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 },
 });
 
 export const WARNING_CODE_NAMES = Object.freeze(Object.keys(WARNING_CODES));

package/contracts/emit.mjs

@@ -15,24 +15,42 @@ import { pathPrefixCandidates, unreflectedPathPrefixes } from './export.mjs';
 // a path param. Direction stays one-way (openapi.mjs imports from emit.mjs, never the reverse).
 export const BARE_UUID_PATTERN = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$';
 
-// A7/A8: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
+// A7/A8/A9/A10: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
 // const -- bin/bskel.mjs's loadContract() imports this too, so the friendly "re-emit with the
-// current bskel" message and the value actually written here cannot drift apart. Bumped "5" -> "6"
-// for this item (sourceResponses/sourceRequestBody) -- cheap this time: the friendly re-emit
-// pre-check in loadContract() needed zero code change, it already compares against this imported
-// constant -- see D-openapi-per-status.
-export const CONTRACT_SCHEMA_VERSION = '6';
+// current bskel" message and the value actually written here cannot drift apart. Bumped "7" -> "8"
+// for this item (sourceDescription) -- again cheap, the friendly re-emit pre-check needs zero
+// code change -- see D-openapi-description.
+export const CONTRACT_SCHEMA_VERSION = '8';
 
-function pathParamsSchema(routePath) {
+// A9 (D-openapi-path-params): `sourcePathParamSchemas` (a Map<name, schema>, contracts/openapi.mjs's
+// applyPathParameterSchemas -- present only for a matched/adopted operation whose source document
+// resolved at least one real path-param schema) is preferred per-segment over the name heuristic
+// below. The heuristic remains the fallback for any segment the source doesn't answer (no source
+// document at all, source declared no schema for that name, or the schema failed to resolve) --
+// this function's OWN correctness posture is unchanged for those cases, exactly as before this
+// item. `pathParamsHeuristic` names every segment that still fell back, so a downstream consumer
+// (contracts/export.mjs's collectOmissions()) can tell, per operation, whether ANY segment is still
+// a guess -- `null` (never `[]`) when every segment was source-resolved or the route has none.
+function pathParamsSchema(routePath, sourcePathParamSchemas = null) {
 	const params = [...routePath.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
 	const properties = {};
+	const heuristicNames = [];
 	for (const p of params) {
+		const sourced = sourcePathParamSchemas ? sourcePathParamSchemas.get(p) : undefined;
+		if (sourced) {
+			properties[p] = sourced;
+			continue;
+		}
 		// Naming convention seen throughout Team-IZ-Backend (`UUID organizationId`, etc.) --
 		// a heuristic, not a guarantee; wrong for a path param that happens to end in "Id" but
 		// isn't a UUID, which just means an over-strict uuid-shaped check on that one field.
 		properties[p] = /id$/i.test(p) ? { type: 'string', pattern: BARE_UUID_PATTERN } : { type: 'string' };
+		heuristicNames.push(p);
 	}
-	return { type: 'object', additionalProperties: false, properties, required: params };
+	return {
+		pathParams: { type: 'object', additionalProperties: false, properties, required: params },
+		pathParamsHeuristic: heuristicNames.length > 0 ? heuristicNames : null,
+	};
 }
 
 // Re-reads the controller source (already located by the scan) to check whether this specific
@@ -122,6 +140,12 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 				let sourceResponses = null;
 				let sourceRequestBody = null;
 				let requestMediaTypesUnresolvedReason = null;
+				// A9: same discipline -- transient (Map), consulted below by pathParamsSchema(), never
+				// itself spread into the persisted operation object (see that function's own comment).
+				let pathParamSchemas = null;
+				// A10: same discipline, for the opt-in operation-level description.
+				let sourceDescription = null;
+				let descriptionUnresolvedReason = null;
 
 				if (res) {
 					switch (res.kind) {
@@ -148,6 +172,9 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 							sourceResponses = res.sourceResponses ?? null;
 							sourceRequestBody = res.sourceRequestBody ?? null;
 							requestMediaTypesUnresolvedReason = res.requestMediaTypesUnresolvedReason ?? null;
+							pathParamSchemas = res.pathParamSchemas ?? null;
+						sourceDescription = res.sourceDescription ?? null;
+						descriptionUnresolvedReason = res.descriptionUnresolvedReason ?? null;
 							break;
 						case 'adopted':
 							// No @Operation(operationId=...) in source at all -- the id itself comes from
@@ -174,6 +201,9 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 							sourceResponses = res.sourceResponses ?? null;
 							sourceRequestBody = res.sourceRequestBody ?? null;
 							requestMediaTypesUnresolvedReason = res.requestMediaTypesUnresolvedReason ?? null;
+							pathParamSchemas = res.pathParamSchemas ?? null;
+						sourceDescription = res.sourceDescription ?? null;
+						descriptionUnresolvedReason = res.descriptionUnresolvedReason ?? null;
 							warnings.push(makeWarning('CONTRACT_OPENAPI_DERIVED_OPERATION_ID', {
 								subject: operationId,
 								message: `operationId "${operationId}" for ${res.verb} ${res.path} was not found in the source (no @Operation(operationId=...)) -- adopted directly from the OpenAPI document instead`,
@@ -320,10 +350,22 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 						detail: { reason: requestMediaTypesUnresolvedReason, verb, path: route, operationId },
 					}));
 				}
+				// A10: only fires when --descriptions was passed AND the source declared one AND it
+				// exceeded MAX_DESCRIPTION_LENGTH -- independent from every other unresolved code above
+				// (a genuinely new failure mode, not reusing an existing one), same reasoning A8 used to
+				// justify its own new multipart code instead of overloading an existing one.
+				if (descriptionUnresolvedReason) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_DESCRIPTION_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) declares a description that could not be copied (${descriptionUnresolvedReason}) -- description stays unrepresented for this operation, same as before --descriptions`,
+						detail: { reason: descriptionUnresolvedReason, verb, path: route, operationId },
+					}));
+				}
+				const { pathParams, pathParamsHeuristic } = pathParamsSchema(route, pathParamSchemas);
 				operations[operationId] = {
 					verb,
 					path: route,
-					pathParams: pathParamsSchema(route),
+					pathParams,
 					body: hasBody === null ? 'unknown' : hasBody,
 					provenance,
 					// A2/A3/A7: omitted entirely (not null/false) when there's nothing to project/copy --
@@ -338,6 +380,12 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 					...(sourceTags ? { sourceTags } : {}),
 					...(sourceResponses ? { sourceResponses } : {}),
 					...(sourceRequestBody ? { sourceRequestBody } : {}),
+					// A9: omitted (not []) when every segment resolved from source, or the route has none.
+					...(pathParamsHeuristic ? { pathParamsHeuristic } : {}),
+					// A10: omitted entirely when --descriptions was not passed, the source had none, or
+					// it failed the length cap -- same "omitted, never null/false" discipline as every
+					// other field above.
+					...(sourceDescription ? { sourceDescription } : {}),
 				};
 			}
 		}

package/contracts/export.mjs

@@ -16,12 +16,20 @@
 // but ONLY when a real source document (--openapi-file) licensed it for that EXACT operation; where
 // no source stated one, the key is still omitted, meaning "unspecified". A8 (D-openapi-per-status)
 // extends the same discipline to per-status responses (additive to, never replacing, the
-// responseSchema/errorSchema union) and non-JSON request media types. Operation-level
-// `description` remains excluded -- measured too expensive to default-on (2,442.7 bytes/operation
-// average, larger than every other field this projection copies combined), still disclosed as
-// structural. Every omission is disclosed in prose (`info.description`) and machine-readably
+// responseSchema/errorSchema union) and non-JSON request media types. A9 (D-openapi-path-params) is
+// different in kind from A7/A8 -- not additive, a REPLACEMENT in place: a path parameter's own
+// `pathParams` schema is corrected from the source document per-segment when it resolves one,
+// falling back to the pre-existing name heuristic only where the source doesn't answer. A10
+// (D-openapi-description) finally builds operation-level `description` -- the one field this whole
+// effort measured too expensive to default-on (2,442.7 bytes/operation average, larger than every
+// other field this projection copies combined) -- as the one source-backed field that is opt-in
+// (`contract emit --descriptions`) rather than default-on. A11 (D-openapi-field-docs) extends the
+// SAME `--descriptions` flag one level deeper: schema FIELD-level `description`/`example` (a
+// property's own annotation, not the operation's), reusing the flag rather than adding a second
+// one. Every omission is disclosed in prose (`info.description`) and machine-readably
 // (`info.x-bskel-omitted`) rather than papered over -- see D-openapi-export, D-openapi-passthrough,
-// and D-openapi-per-status in DECISIONS.md.
+// D-openapi-per-status, D-openapi-path-params, D-openapi-description, and D-openapi-field-docs in
+// DECISIONS.md.
 import { createHash } from 'node:crypto';
 import { BSKEL_GENERATED_EXTENSION, BSKEL_PASSTHROUGH_EXTENSION, PATH_PREFIX_RE, RESPONSE_STATUS_KEY_RE, MEDIA_TYPE_RE, PER_STATUS_NO_DESCRIPTION_STANDIN, SUCCESS_STATUS_RE, ERROR_STATUS_RE, DEFAULT_STATUS_KEY } from './openapi.mjs';
 
@@ -58,34 +66,48 @@ const ERROR_RESPONSE_DESCRIPTION = 'Error. The source contract records the union
 // A7: query/header/cookie parameters, security, summaries, and tags moved OUT of this list -- they
 // are now real emitted content when a source document licensed them, so they only belong in the
 // DERIVED (ANY-based) set collectOmissions() builds below. A8 moves `per-status-responses` and
-// `non-json-request-media-types` (renamed from `non-json-media-types`) out the same way. What
-// stays structural: `descriptions` (field-level AND operation-level -- the latter measured and
-// deliberately excluded, not merely unbuilt), `path-parameter-schemas` (path-param schemas come
-// from this contract's own name heuristic, never from a source document, even when --openapi-file
-// was given -- see the real `batchRequestId` finding in D-openapi-passthrough), `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 projected -- 0/674 real occurrences, so building that machinery would violate
-// this project's own "don't build for zero real cases" discipline) and `response-headers`
-// (response `headers`/`links` -- 0/694 real occurrences, a genuinely visible gap only now that
-// per-status responses look complete).
+// `non-json-request-media-types` (renamed from `non-json-media-types`) out the same way. A9 moves
+// `path-parameter-schemas` out the same way too -- path-param schemas now come from a real source
+// document whenever it declares a resolvable one (see D-openapi-path-params, the real fix for the
+// `batchRequestId` finding this omission entry used to describe unconditionally), falling back to
+// the contract's own name heuristic only per-segment, so its presence is now content-conditional
+// like every other A7/A8 field, not a permanent structural fact. A10 splits the old single
+// `descriptions` entry in two: `operation-descriptions` moves out (opt-in via `--descriptions`, so
+// its presence is now content-AND-flag-conditional, same ANY-based doctrine), while
+// `field-descriptions` (schema-field-level `description`/`title`/`example`, dropped as
+// DROPPED_KEYWORDS while inlining ANY schema) stays structural at that point. A11
+// (D-openapi-field-docs) splits `field-descriptions` again the same way: `description`/`example`
+// move OUT to the ANY-based set below (`--descriptions` now doubles as the field-level flag too,
+// keeping the `field-descriptions` NAME since that is still exactly what it describes -- only its
+// 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-*
+// 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
+// projected -- 0/674 real occurrences, so building that machinery would violate this project's own
+// "don't build for zero real cases" discipline) and `response-headers` (response `headers`/`links`
+// -- 0/694 real occurrences, a genuinely visible gap only now that per-status responses look
+// complete).
 const STRUCTURAL_OMISSIONS = Object.freeze([
-	'descriptions',
+	'field-metadata',
 	'non-json-response-schemas',
-	'path-parameter-schemas',
 	'response-headers',
 	'vendor-extensions',
 ]);
 
 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)',
-	descriptions: 'field-level descriptions/titles/examples (contracts/openapi.mjs drops them as DROPPED_KEYWORDS while inlining a schema), and operation-level `description` -- measured and deliberately excluded (real average 2,442.7 bytes/operation, larger than every other field this projection copies combined); if ever built, it must be opt-in behind a flag, unlike everything else this projection copies by default',
 	'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',
 	'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',
-	'path-parameter-schemas': 'path parameter schemas -- always derived from this contract\'s own name heuristic (a trailing "Id" is assumed to be a UUID), never from a source document even when --openapi-file was given; a real, small false-negative of this heuristic is known and disclosed, not fixed, by this projection',
+	'operation-descriptions': 'the operation-level `description`, for at least one operation -- copied only when `contract emit --descriptions` was used (opt-in: measured real average 2,442.7 bytes/operation, larger than every other field this projection copies combined) AND the source document declared one for that exact operation AND it did not exceed the length cap; otherwise this key is absent for that operation, never synthesized',
+	'path-parameter-schemas': 'a path parameter\'s schema, for at least one path segment on at least one operation -- derived from this contract\'s own name heuristic (a trailing "Id" is assumed to be a UUID) rather than a real source document, because no source document was given, the source declared no schema for that segment, or the schema failed to resolve; a segment not covered by this note was resolved from the source document\'s own real schema',
 	'per-status-responses': 'per-status responses, for at least one operation -- that operation\'s entry collapses every documented 2xx body into one `2XX` union and every 4xx/5xx body into one `default` union, and records no real status codes. Where a real source document (--openapi-file) documented statuses for an operation, its own status codes and descriptions are emitted verbatim instead; nothing is invented for an operation the source said nothing about',
 	'query-parameters': 'query 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)',
 	'request-body-schemas': 'a JSON request-body schema for at least one operation that takes a body',
@@ -101,6 +123,28 @@ function hasSourceParamIn(op, loc) {
 	return Array.isArray(op.sourceParameters) && op.sourceParameters.some((p) => p.in === loc);
 }
 
+// A11: whether AT LEAST ONE node anywhere in this schema carries a copied `description`/`example`
+// -- deliberately the same coarse "presence, not completeness" doctrine `operation-descriptions`
+// already uses for `op.sourceDescription` (this cannot know, from the exported contract alone,
+// whether a field WITHOUT one had none in the source or was simply never reached with the flag
+// off; it only discloses whether ANY field-level annotation survived at all). `seen` guards the
+// same delete-on-exit-shaped cycle risk inlineSchema() itself defends against -- belt-and-braces,
+// since a contract's own schemas are already acyclic by construction, but this walk is generic over
+// whatever JSON shape ends up in a contract field.
+function schemaHasFieldDocs(node, seen = new Set()) {
+	if (node === null || typeof node !== 'object' || Array.isArray(node) || seen.has(node)) return false;
+	seen.add(node);
+	if (typeof node.description === 'string' || Object.hasOwn(node, 'example')) return true;
+	if (node.properties && typeof node.properties === 'object' && !Array.isArray(node.properties)) {
+		for (const propSchema of Object.values(node.properties)) {
+			if (schemaHasFieldDocs(propSchema, seen)) return true;
+		}
+	}
+	if (node.items && typeof node.items === 'object' && schemaHasFieldDocs(node.items, seen)) return true;
+	if (node.additionalProperties && typeof node.additionalProperties === 'object' && schemaHasFieldDocs(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.
@@ -133,6 +177,25 @@ export function collectOmissions(contract) {
 		if ((op.body === true || op.body === 'unknown') && !op.requestBodySchema && !op.sourceRequestBody) {
 			omissions.add('non-json-request-media-types');
 		}
+		// A9: path-parameter schemas -- ANY-based, same doctrine as every check above. An operation
+		// with zero path params, or every one source-resolved, has no pathParamsHeuristic at all
+		// (contracts/emit.mjs never persists an empty array), so it naturally never trips this check.
+		if (Array.isArray(op.pathParamsHeuristic) && op.pathParamsHeuristic.length > 0) {
+			omissions.add('path-parameter-schemas');
+		}
+		// A10: operation-level description -- ANY-based, same doctrine. Absent whenever
+		// --descriptions was not used at all (every operation then lacks sourceDescription, so this
+		// always trips until the flag is used), the source had none for this operation, or it
+		// exceeded the length cap.
+		if (!op.sourceDescription) omissions.add('operation-descriptions');
+		// A11: schema field-level description/example -- ANY-based, same doctrine as
+		// response-schemas/error-schemas just above: added whenever NONE of this operation's
+		// projected schemas carry a field-level annotation, including the (common) case where the
+		// operation has no projected schema at all to carry one -- same "absence of the whole class
+		// is itself disclosed" posture response-schemas/error-schemas already take unconditionally,
+		// 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');
 	}
 	return [...omissions].sort();
 }
@@ -464,25 +527,31 @@ export function buildOpenApiDocument({ contract, snapshot = null, options = {} }
 		// for this exact operation. `security: []` is spec-legal (confirmed by executing the
 		// meta-schema) AND, when copied, a genuine positive claim FROM THE SOURCE that no
 		// authentication is required -- Array.isArray, not a truthy check, so `[]` is correctly
-		// treated as present. `op.sourceSecurity` is never emitted when absent; `description` (the
-		// operation-level field, not the response-object one) remains deliberately unset -- Phase 2.
+		// treated as present. `op.sourceSecurity` is never emitted when absent.
 		if (Array.isArray(op.sourceSecurity)) operation.security = op.sourceSecurity;
 		if (op.sourceSummary) operation.summary = op.sourceSummary;
 		if (Array.isArray(op.sourceTags) && op.sourceTags.length > 0) operation.tags = op.sourceTags;
+		// A10: same "only when the contract carries a copied value" discipline -- `sourceDescription`
+		// is present only when `contract emit --descriptions` was used AND the source had one for this
+		// exact operation, so this is never a synthesized or inferred string.
+		if (op.sourceDescription) operation.description = op.sourceDescription;
 
 		// A8: two more clauses -- an operation whose ONLY passthrough is per-status responses or a
 		// copied multipart body (no source parameters/security/summary/tags at all) previously got NO
 		// marker, reopening the exact self-import hole A7 closed for that one operation. Never arises
 		// on the real oracle (148/148 already carry summary+tags+security) but is structurally
 		// reachable from a minimal hand-written document declaring only `responses` -- see
-		// D-openapi-per-status.
+		// D-openapi-per-status. A10 adds a third clause for the same reason: an operation whose ONLY
+		// passthrough is a copied description (structurally reachable even though never arises on the
+		// real oracle, which already carries summary/tags/security everywhere).
 		const hasPassthrough = Boolean(
 			(Array.isArray(op.sourceParameters) && op.sourceParameters.length > 0)
 			|| Array.isArray(op.sourceSecurity)
 			|| op.sourceSummary
 			|| (Array.isArray(op.sourceTags) && op.sourceTags.length > 0)
 			|| (op.sourceResponses && typeof op.sourceResponses === 'object' && Object.keys(op.sourceResponses).length > 0)
-			|| (op.sourceRequestBody && typeof op.sourceRequestBody === 'object'),
+			|| (op.sourceRequestBody && typeof op.sourceRequestBody === 'object')
+			|| op.sourceDescription,
 		);
 		passthroughByOperation[operationId] = hasPassthrough;
 		if (hasPassthrough) {

package/contracts/openapi.mjs

@@ -53,6 +53,20 @@ const MAX_SECURITY_SCHEMES = 64;
 // 9). MAX_REQUEST_MEDIA_TYPES is new: real max observed on one operation's requestBody.content is
 // 1 (always either application/json alone or multipart/form-data alone in the oracle).
 const MAX_REQUEST_MEDIA_TYPES = 16;
+// A10: operation-level `description`, same "generous multiple of the real observed max" style as
+// every cap above -- real max observed on the Team-IZ-Backend oracle (148 operations, 146 carry a
+// non-empty description) is 9,083 (`.length`, UTF-16 code units, same measure MAX_PATTERN_LENGTH
+// already uses -- NOT a UTF-8 byte count, which runs higher for this oracle's real multi-byte
+// Korean text: 13,758 bytes for the same longest description).
+const MAX_DESCRIPTION_LENGTH = 40000;
+// A11: a FIELD-level `example` value, inside a schema this whole file resolves -- unlike
+// MAX_DESCRIPTION_LENGTH's single operation-level string, `example` is an arbitrary JSON value
+// (string/number/array/object all occur for real, see D-openapi-field-docs), so the cap applies to
+// its serialized (`JSON.stringify(value).length`) size, not `.length` directly. Real max observed
+// on the oracle: 70. A generously round bound, not a tight multiple, since a legitimately useful
+// example (e.g. a full sample response object) could reasonably run longer than any single real
+// value happened to here.
+const MAX_EXAMPLE_LENGTH = 2000;
 // A6 (D-openapi-export): widened from `/^2[0-9]{2}$/` and `/^[45][0-9]{2}$/` to also accept
 // OpenAPI's own RANGE keys. These are ordinary in real hand-written documents and legal per the
 // official 3.1 meta-schema, whose `responses` object accepts exactly `^[1-5](?:[0-9]{2}|XX)$` plus
@@ -130,12 +144,16 @@ export const PER_STATUS_NO_DESCRIPTION_STANDIN = 'The source document documents
 
 // inlineSchema()'s keyword policy: RECURSED keywords are walked into; ASSERTION keywords are
 // copied verbatim (their values are scalars/arrays of scalars, not schema nodes -- nothing to
-// recurse); DROPPED keywords carry no validation meaning and are silently discarded (their
-// absence changes nothing about what a schema accepts); anything else fails that schema closed.
-// The FORMAT set is checked separately (see inlineSchema's format handling) since `uuid` gets
-// rewritten rather than either copied or dropped. A missing-and-therefore-fail-closed keyword is
-// deliberate: silently dropping an assertion (e.g. an unrecognized `pattern`-like keyword) would
-// emit a schema WEAKER than the real one, which is worse than emitting no schema at all -- see
+// recurse); DOCUMENTATION keywords (A11) are copied verbatim ONLY when opted in
+// (`includeFieldDocs`), dropped otherwise -- unlike an ASSERTION keyword, dropping one never
+// changes what a schema VALIDATES, only how well-documented it is, so there is no fail-closed
+// concern either way; DROPPED keywords carry no validation meaning AND have zero real occurrences
+// on the oracle (measured, not assumed -- see D-openapi-field-docs), so they are unconditionally
+// discarded regardless of any flag; anything else fails that schema closed. The FORMAT set is
+// checked separately (see inlineSchema's format handling) since `uuid` gets rewritten rather than
+// either copied or dropped. A missing-and-therefore-fail-closed keyword is deliberate: silently
+// dropping an assertion (e.g. an unrecognized `pattern`-like keyword) would emit a schema WEAKER
+// than the real one, which is worse than emitting no schema at all -- see
 // D-openapi-request-schema in DECISIONS.md.
 const RECURSED_KEYWORDS = Object.freeze(new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf']));
 // A7: `default` added -- annotation-only per 2020-12 (Ajv runs with useDefaults off here, so it's
@@ -151,7 +169,16 @@ const COPIED_KEYWORDS = Object.freeze(new Set([
 	'minItems', 'maxItems', 'uniqueItems',
 	'minProperties', 'maxProperties',
 ]));
-const DROPPED_KEYWORDS = Object.freeze(new Set(['description', 'title', 'example', 'examples', 'externalDocs', 'xml', 'deprecated']));
+// A11 (D-openapi-field-docs): `description`/`example` measured real and heavily used at the FIELD
+// level (3,982 / 2,077 occurrences across the oracle's request/response/parameter schemas,
+// 520,527 / 32,708 real bytes) -- moved out of DROPPED_KEYWORDS into their own conditionally-
+// copied set. `title`/`examples`(plural)/`externalDocs`/`xml`/`deprecated` stay unconditionally
+// dropped: 0 real occurrences for every one of them (measured, not assumed), so building any
+// copy path for them would violate this project's own "don't build for zero real cases"
+// discipline -- named here, not built, a permanent gap like A8's `non-json-response-schemas`/
+// `response-headers`.
+const DOCUMENTATION_KEYWORDS = Object.freeze(new Set(['description', 'example']));
+const DROPPED_KEYWORDS = Object.freeze(new Set(['title', 'examples', 'externalDocs', 'xml', 'deprecated']));
 // 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`.
@@ -374,7 +401,11 @@ export function indexOpenApiDocument(doc) {
 			const security = Array.isArray(operation.security) ? operation.security : null;
 			const summary = typeof operation.summary === 'string' ? operation.summary : null;
 			const tags = Array.isArray(operation.tags) ? operation.tags : null;
-			const entry = { verb, path: routeKey, operationId, requestBody, responses, parameters, security, summary, tags };
+			// A10: same "raw, no size cap at index time" reasoning as summary above -- MAX_DESCRIPTION_
+			// LENGTH is enforced only at applyDescription() (the point of actually copying it into the
+			// contract), matching where every other length/count cap in this file is enforced.
+			const description = typeof operation.description === 'string' ? operation.description : null;
+			const entry = { verb, path: routeKey, operationId, requestBody, responses, parameters, security, summary, tags, description };
 
 			const routeMatchKey = `${verb} ${normalizedRoute}`;
 			const existingRoute = byRoute.get(routeMatchKey);
@@ -438,6 +469,9 @@ export function inlineSchema(node, componentSchemas, opts = {}) {
 		maxDepth: opts.maxDepth ?? MAX_SCHEMA_DEPTH,
 		maxNodes: opts.maxNodes ?? MAX_SCHEMA_NODES,
 		maxPatternLength: opts.maxPatternLength ?? MAX_PATTERN_LENGTH,
+		// A11: opt-in only (default false, matching every prior call site's existing behavior
+		// byte-for-byte when the caller doesn't pass it) -- see D-openapi-field-docs.
+		includeFieldDocs: opts.includeFieldDocs ?? false,
 	};
 	const state = { nodes: 0 };
 	try {
@@ -464,11 +498,14 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 		// module doesn't attempt to MERGE $ref with a sibling assertion, with ONE exception (A7):
 		// `default` is a real, human-authored override worth carrying through (the exact real shape
 		// `{"$ref": ".../ProjectListSort", "default": "READINESS"}` -- a $ref-typed parameter
-		// schema with its own default value, 9 real occurrences). A DROPPED_KEYWORDS sibling (e.g. a
-		// documentation-only `description`) is harmless and ignored; anything else would need merge
-		// semantics this vertical slice doesn't implement, so it fails closed.
+		// schema with its own default value, 9 real occurrences). A DROPPED_KEYWORDS or
+		// DOCUMENTATION_KEYWORDS sibling (e.g. a documentation-only `description`) is harmless and
+		// ignored -- NOT merged onto the resolved schema even when includeFieldDocs is on (A11: 0
+		// real occurrences of a $ref carrying a sibling description/example, measured directly, so
+		// there is no real case to build merge semantics for, unlike `default`'s 9); anything else
+		// would need merge semantics this vertical slice doesn't implement, so it fails closed.
 		const siblingKeys = Object.keys(node).filter((k) => k !== '$ref');
-		if (siblingKeys.some((k) => !DROPPED_KEYWORDS.has(k) && k !== 'default')) fail('ref-with-siblings');
+		if (siblingKeys.some((k) => !DROPPED_KEYWORDS.has(k) && !DOCUMENTATION_KEYWORDS.has(k) && k !== 'default')) fail('ref-with-siblings');
 		const ref = node['$ref'];
 		if (typeof ref !== 'string' || !ref.startsWith(SCHEMA_REF_PREFIX)) fail('unsupported-ref');
 		const name = ref.slice(SCHEMA_REF_PREFIX.length);
@@ -516,6 +553,32 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 		if (key === '$ref' || key === 'format') continue; // format already handled above
 		if (DROPPED_KEYWORDS.has(key)) continue;
 
+		// A11: description/example are DROPPED (same as before this item) unless includeFieldDocs is
+		// on -- when it is, copy verbatim IF the value passes a defensive length check, else drop
+		// (silently, same as if the flag were off for this one field) rather than failing the whole
+		// schema closed. Unlike an ASSERTION keyword's fail-closed policy, dropping an annotation
+		// NEVER changes what the schema validates -- only how well-documented it is -- so there is no
+		// correctness reason to fail the operation over one oversized documentation string, and a
+		// per-FIELD warning here would be unusably noisy (a single schema can carry dozens of these,
+		// unlike A10's one-per-operation description). Real data never exercises this path (measured
+		// max: 3,148 for description, 70 for example -- both far under their caps), so this is a
+		// defensive bound against a hostile/malformed --openapi-file, not an expected real branch.
+		if (DOCUMENTATION_KEYWORDS.has(key)) {
+			if (!limits.includeFieldDocs) continue;
+			if (key === 'description') {
+				if (typeof node.description === 'string' && node.description.length <= MAX_DESCRIPTION_LENGTH) {
+					out.description = node.description;
+				}
+			} else if (key === 'example') {
+				let serialized;
+				try { serialized = JSON.stringify(node.example); } catch { serialized = null; }
+				if (serialized !== undefined && serialized !== null && serialized.length <= MAX_EXAMPLE_LENGTH) {
+					out.example = node.example;
+				}
+			}
+			continue;
+		}
+
 		if (key === 'pattern') {
 			// Two patterns can't be expressed without allOf, which this slice doesn't attempt to
 			// synthesize -- a node with BOTH format:'uuid' and an explicit pattern fails closed
@@ -597,7 +660,7 @@ function walkSchemaNode(node, componentSchemas, depth, visiting, state, limits)
 // let alone body shape. `docEntry` is the OpenAPI-side entry (from byOperationId or byRoute) whose
 // `.requestBody` indexOpenApiDocument() retained. Never treats "nothing to project" as a failure --
 // only an actual unresolvable schema increments schema_unresolved / sets schemaUnresolvedReason.
-function applyRequestBodySchema(result, docEntry, componentSchemas, stats) {
+function applyRequestBodySchema(result, docEntry, componentSchemas, stats, includeFieldDocs) {
 	const requestBody = docEntry.requestBody;
 	if (!requestBody || Object.hasOwn(requestBody, '$ref')) {
 		stats.schema_none++;
@@ -614,7 +677,7 @@ function applyRequestBodySchema(result, docEntry, componentSchemas, stats) {
 		stats.schema_none++;
 		return;
 	}
-	const resolved = inlineSchema(schemaNode, componentSchemas);
+	const resolved = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
 	if (resolved.ok) {
 		result.requestBodySchema = resolved.schema;
 		result.requestBodyRequired = requestBody.required === true;
@@ -666,7 +729,7 @@ function canonicalJson(value) {
 // nothing it had before (nothing read `default` at all until now); one whose `default` describes an
 // error -- the overwhelmingly common case, and the only case `bskel contract export` itself emits --
 // gains a real error schema it previously dropped silently.
-function projectResponseSchemas(responses, statusRe, componentSchemas, { includeDefault = false } = {}) {
+function projectResponseSchemas(responses, statusRe, componentSchemas, { includeDefault = false, includeFieldDocs = false } = {}) {
 	if (!responses) return { outcome: 'none' };
 	const statusKeys = Object.keys(responses);
 	if (statusKeys.length > MAX_RESPONSES_PER_OPERATION) {
@@ -693,9 +756,14 @@ function projectResponseSchemas(responses, statusRe, componentSchemas, { include
 		return { outcome: sawContentWithoutJson ? 'skipped-media-type' : 'none' };
 	}
 
+	// A11: includeFieldDocs can make two previously-identical-looking resolved schemas turn out
+	// distinct (different field-level description/example), which correctly increases `sources` --
+	// see D-openapi-field-docs for why this is a self-consistent consequence of being more precise
+	// about equality, not a bug, and the real measurement confirming it never actually happens on
+	// the Team-IZ-Backend oracle.
 	const resolvedByCanonical = new Map();
 	for (const node of rawNodesByKey.values()) {
-		const resolved = inlineSchema(node, componentSchemas);
+		const resolved = inlineSchema(node, componentSchemas, { includeFieldDocs });
 		if (!resolved.ok) return { outcome: 'unresolved', reason: resolved.reason };
 		const canonicalKey = canonicalJson(resolved.schema);
 		if (!resolvedByCanonical.has(canonicalKey)) resolvedByCanonical.set(canonicalKey, resolved.schema);
@@ -719,10 +787,10 @@ function projectResponseSchemas(responses, statusRe, componentSchemas, { include
 // schemaProjection.enabled guard). Fields are set ONLY when resolved -- omitted, not null/false,
 // so an operation with nothing to project stays byte-identical to pre-A3 output (same discipline
 // as A2's requestBodySchema).
-function applyResponseSchemas(result, docEntry, componentSchemas, stats) {
-	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, SUCCESS_STATUS_RE, componentSchemas), stats, 'response');
+function applyResponseSchemas(result, docEntry, componentSchemas, stats, includeFieldDocs) {
+	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, SUCCESS_STATUS_RE, componentSchemas, { includeFieldDocs }), stats, 'response');
 	// A6: `default` contributes to the ERROR side only -- see projectResponseSchemas' own comment.
-	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, ERROR_STATUS_RE, componentSchemas, { includeDefault: true }), stats, 'error');
+	applyProjectionOutcome(result, projectResponseSchemas(docEntry.responses, ERROR_STATUS_RE, componentSchemas, { includeDefault: true, includeFieldDocs }), stats, 'error');
 }
 
 function applyProjectionOutcome(result, projected, stats, kind) {
@@ -811,7 +879,7 @@ function collectNonPathParameters(rawParameters) {
 // The middle+last cases both add the parameter to sourceParameters (every OTHER field it carries is
 // real and safe); the last case additionally drives CONTRACT_OPENAPI_PARAMETERS_UNRESOLVED, exactly
 // the "found but couldn't project" distinction applyRequestBodySchema already draws for a body.
-function copyParameter(raw, componentSchemas) {
+function copyParameter(raw, componentSchemas, includeFieldDocs) {
 	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, reason: 'not-a-parameter-object' };
 	if (Object.hasOwn(raw, '$ref')) return { ok: false, reason: 'ref-parameter' };
 	if (Object.hasOwn(raw, 'content')) return { ok: false, reason: 'content-parameter' };
@@ -829,7 +897,7 @@ function copyParameter(raw, componentSchemas) {
 	}
 
 	if (Object.hasOwn(raw, 'schema')) {
-		const resolved = inlineSchema(raw.schema, componentSchemas);
+		const resolved = inlineSchema(raw.schema, componentSchemas, { includeFieldDocs });
 		if (resolved.ok) {
 			parameter.schema = resolved.schema;
 		} else {
@@ -846,7 +914,7 @@ function copyParameter(raw, componentSchemas) {
 // `result`: parametersTotal/parametersCleanCount (reconciliation-internal bookkeeping consumed only
 // by snapshotFromReconciliation, never copied into the contract itself), parametersSkippedDialect,
 // sourceParameters (omitted when empty), parametersUnresolved (omitted when empty).
-function applyParameters(result, docEntry, index, stats, schemaProjectionEnabled) {
+function applyParameters(result, docEntry, index, stats, schemaProjectionEnabled, includeFieldDocs) {
 	const candidates = collectNonPathParameters(docEntry.parameters);
 	if (candidates.length === 0) {
 		stats.parameters_none++;
@@ -871,7 +939,7 @@ function applyParameters(result, docEntry, index, stats, schemaProjectionEnabled
 		}
 	} else {
 		for (const raw of candidates) {
-			const outcome = copyParameter(raw, index.componentSchemas);
+			const outcome = copyParameter(raw, index.componentSchemas, includeFieldDocs);
 			if (!outcome.ok) {
 				unresolved.push({ name: safeParamName(raw), in: safeParamIn(raw), reason: outcome.reason });
 				continue;
@@ -954,6 +1022,34 @@ function applySummaryAndTags(result, docEntry, stats) {
 	}
 }
 
+// A10 (D-openapi-description): the one A7/A8/A9 sibling that is NOT default-on -- gated behind
+// `includeDescriptions`, opt-in only, because the measured cost (2,442.7 bytes/operation average
+// across the real oracle, re-confirmed exactly at this item's own implementation) is larger than
+// every other field this whole passthrough effort copies COMBINED. Copied verbatim, no
+// transformation (unlike a schema, there is no keyword whitelist to apply to a plain string) --
+// fails closed only on length, via MAX_DESCRIPTION_LENGTH, the same defensive posture every other
+// unbounded-size field in this file has (same defensive-cap class as D-security-1/D-security-2) --
+// protecting the contract file/gate-token hashing cost from a malformed or hostile --openapi-file,
+// not a normal document.
+function applyDescription(result, docEntry, stats, includeDescriptions) {
+	if (!includeDescriptions) {
+		stats.description_skipped_flag++;
+		return;
+	}
+	const raw = docEntry.description;
+	if (typeof raw !== 'string' || raw.length === 0) {
+		stats.description_none++;
+		return;
+	}
+	if (raw.length > MAX_DESCRIPTION_LENGTH) {
+		result.descriptionUnresolvedReason = 'too-long';
+		stats.description_unresolved++;
+		return;
+	}
+	result.sourceDescription = raw;
+	stats.description_copied++;
+}
+
 // A8: per-status responses -- additive to (never replacing) the responseSchema/errorSchema union
 // projection above; contracts/validate.mjs is untouched by this item, see D-openapi-per-status.
 // Gated on schemaProjectionEnabled, same reasoning as applyParameters -- a JSON Schema resolved
@@ -971,7 +1067,7 @@ function applySummaryAndTags(result, docEntry, stats) {
 // at it instead of re-resolving. When sources>1 (never observed on real data, but structurally
 // possible) or the status sits outside both buckets (a 1xx/3xx key), the status's own schema is
 // resolved individually into an inline `schema` instead.
-function applyPerStatusResponses(result, docEntry, componentSchemas, stats, schemaProjectionEnabled) {
+function applyPerStatusResponses(result, docEntry, componentSchemas, stats, schemaProjectionEnabled, includeFieldDocs) {
 	if (!schemaProjectionEnabled) {
 		result.perStatusResponsesSkippedDialect = true;
 		stats.per_status_skipped_dialect++;
@@ -1020,7 +1116,7 @@ function applyPerStatusResponses(result, docEntry, componentSchemas, stats, sche
 					} else if ((ERROR_STATUS_RE.test(key) || key === DEFAULT_STATUS_KEY) && result.errorSchema && result.errorSchemaSources === 1) {
 						entry.schemaFrom = 'error';
 					} else {
-						const resolved = inlineSchema(schemaNode, componentSchemas);
+						const resolved = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
 						// unresolved here just leaves `schema` absent -- `description` alone (if any) stays
 						// valid, same "copied without schema" posture copyParameter() already takes.
 						if (resolved.ok) entry.schema = resolved.schema;
@@ -1050,7 +1146,7 @@ function applyPerStatusResponses(result, docEntry, componentSchemas, stats, sche
 // schemas/feature-contract.schema.json too). Gated on schemaProjectionEnabled for the same reason
 // as applyPerStatusResponses above -- a media-type schema resolves through the same inlineSchema()
 // path.
-function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schemaProjectionEnabled) {
+function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schemaProjectionEnabled, includeFieldDocs) {
 	if (!schemaProjectionEnabled) {
 		result.requestMediaTypesSkippedDialect = true;
 		stats.request_media_types_skipped_dialect++;
@@ -1086,7 +1182,7 @@ function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schem
 		const entry = {};
 		const schemaNode = mediaEntry && typeof mediaEntry === 'object' && !Array.isArray(mediaEntry) ? mediaEntry.schema : null;
 		if (schemaNode && typeof schemaNode === 'object' && !Array.isArray(schemaNode)) {
-			const resolved = inlineSchema(schemaNode, componentSchemas);
+			const resolved = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
 			if (resolved.ok) { entry.schema = resolved.schema; cleanCount++; }
 		} else {
 			cleanCount++; // no schema declared for this media type at all is not a failure -- same
@@ -1105,18 +1201,73 @@ function applyRequestMediaTypes(result, docEntry, componentSchemas, stats, schem
 	}
 }
 
+// A9 (D-openapi-path-params): the real fix for A7's own disclosed `batchRequestId` finding --
+// contracts/emit.mjs's pathParamsSchema() names a path segment by NAME ONLY (`/id$/i` ->
+// BARE_UUID_PATTERN), a heuristic that is provably wrong for at least one real path parameter
+// (`batchRequestId`, a plain string despite the "Id" suffix). Unlike A7's own parameters (query/
+// header/cookie, which stay ADDITIVE alongside pathParams' own separate story), this one REPLACES
+// the heuristic's guess in place for any segment the source document can answer -- the same
+// "positive information overrides a guess" principle A8's `hasSourceMediaTypeInfo` already
+// established, applied here to path-param TYPE instead of request media type.
+//
+// Returns a Map (never a plain object -- this is `--openapi-file`-sourced, untrusted data keyed by
+// parameter NAME, the exact class RESPONSE_STATUS_KEY_RE/MEDIA_TYPE_RE exist to defend against
+// elsewhere in this file; a Map sidesteps prototype pollution entirely rather than needing a third
+// whitelist regex) from resolved path-parameter name to its inlined schema, stashed transiently on
+// `result` for contracts/emit.mjs's pathParamsSchema() call to consult -- never itself persisted to
+// the contract; only the corrected `pathParams` (and, when at least one segment still falls back to
+// the heuristic, `pathParamsHeuristic`) are.
+function applyPathParameterSchemas(result, docEntry, componentSchemas, stats, schemaProjectionEnabled, includeFieldDocs) {
+	const rawParameters = Array.isArray(docEntry.parameters) ? docEntry.parameters : [];
+	const pathParams = rawParameters.filter((p) => p && typeof p === 'object' && !Array.isArray(p) && p.in === 'path');
+	if (pathParams.length === 0) {
+		stats.path_params_none++;
+		return;
+	}
+	if (!schemaProjectionEnabled) {
+		result.pathParamsSkippedDialect = true;
+		stats.path_params_skipped_dialect++;
+		return;
+	}
+	const resolved = new Map();
+	for (const p of pathParams) {
+		const name = safeParamName(p);
+		if (name === null || !Object.hasOwn(p, 'schema')) continue; // no name, or source declared no schema -- nothing to prefer over the heuristic for this one segment
+		const schemaNode = p.schema;
+		if (!schemaNode || typeof schemaNode !== 'object' || Array.isArray(schemaNode)) continue;
+		const out = inlineSchema(schemaNode, componentSchemas, { includeFieldDocs });
+		if (out.ok) resolved.set(name, out.schema);
+	}
+	if (resolved.size > 0) {
+		result.pathParamSchemas = resolved;
+		stats.path_params_copied++;
+	} else {
+		stats.path_params_unresolved++;
+	}
+}
+
 // A7: the single entry point called from reconcileModule()'s two matched/adopted call sites --
 // exactly the placement A2/A3's own helpers already occupy, which IS the refusal mechanism for
 // every other resolution kind (drift/missing/ambiguous/unresolved never reach this function at
 // all, see reconcileModule below).
-function applyPassthrough(result, docEntry, index, stats, schemaProjectionEnabled, referencedSchemeNames) {
-	applyParameters(result, docEntry, index, stats, schemaProjectionEnabled);
+function applyPassthrough(result, docEntry, index, stats, schemaProjectionEnabled, referencedSchemeNames, includeDescriptions) {
+	// A11 (D-openapi-field-docs): includeDescriptions doubles as includeFieldDocs here -- reusing
+	// the existing --descriptions flag rather than adding a second one, since it already governs
+	// "copy source-authored documentation prose" at the operation level (A10); field-level
+	// description/example is the same policy applied one level deeper into the same schemas.
+	applyParameters(result, docEntry, index, stats, schemaProjectionEnabled, includeDescriptions);
 	applySecurity(result, docEntry, index, stats, referencedSchemeNames);
 	applySummaryAndTags(result, docEntry, stats);
 	// A8: same matched/adopted-only placement as the three calls above -- this IS the refusal
 	// mechanism for every other resolution kind, extended unchanged for the two new fields.
-	applyPerStatusResponses(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled);
-	applyRequestMediaTypes(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled);
+	applyPerStatusResponses(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled, includeDescriptions);
+	applyRequestMediaTypes(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled, includeDescriptions);
+	// A9: same placement again, for the path-parameter schema fix.
+	applyPathParameterSchemas(result, docEntry, index.componentSchemas, stats, schemaProjectionEnabled, includeDescriptions);
+	// A10: same placement again -- applyDescription() itself decides whether includeDescriptions
+	// gates it off, matching how applyParameters decides its own schemaProjectionEnabled gate
+	// internally rather than being skipped by the caller.
+	applyDescription(result, docEntry, stats, includeDescriptions);
 }
 
 // The core reconciliation, pure (no I/O). `module` is a scanReport related_modules entry (as
@@ -1124,7 +1275,7 @@ function applyPassthrough(result, docEntry, index, stats, schemaProjectionEnable
 // selection buildContract() will use, so endpointKey(ci,ei) lines up). `pathPrefix`, if given
 // (from --path-prefix), overrides inference entirely but the anchor pass still runs so its
 // deltas are recorded for audit in the snapshot.
-export function reconcileModule({ index, module, pathPrefix = null }) {
+export function reconcileModule({ index, module, pathPrefix = null, includeDescriptions = false }) {
 	const anchorDeltas = [];
 	for (const controller of module.controllers) {
 		for (const ep of controller.endpoints) {
@@ -1164,6 +1315,11 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 		// the A7 counters above.
 		per_status_copied: 0, per_status_skipped_unresolved: 0, per_status_none: 0, per_status_skipped_dialect: 0,
 		request_media_types_copied: 0, request_media_types_unresolved: 0, request_media_types_none: 0, request_media_types_skipped_dialect: 0,
+		// A9: source-backed path-parameter schema counters, same per-operation-tally shape.
+		path_params_copied: 0, path_params_unresolved: 0, path_params_none: 0, path_params_skipped_dialect: 0,
+		// A10: operation-level description counters. skipped_flag is the common case when
+		// --descriptions was not passed -- distinct from `none` (flag WAS passed, source had nothing).
+		description_copied: 0, description_unresolved: 0, description_none: 0, description_skipped_flag: 0,
 	};
 	// A7: accumulates every security-scheme name any operation's COPIED security requirement
 	// actually referenced, across the WHOLE module -- becomes the contract-root sourceSecuritySchemes
@@ -1206,14 +1362,14 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 						// A2/A3: matched/adopted ONLY -- schema enrichment never applies to drift/missing/
 						// ambiguous/unresolved, same "don't guess" rule A1 established for path/verb.
 						if (schemaProjection.enabled) {
-							applyRequestBodySchema(result, docEntry, index.componentSchemas, stats);
-							applyResponseSchemas(result, docEntry, index.componentSchemas, stats);
+							applyRequestBodySchema(result, docEntry, index.componentSchemas, stats, includeDescriptions);
+							applyResponseSchemas(result, docEntry, index.componentSchemas, stats, includeDescriptions);
 						}
 						// A7: same matched/adopted-only placement -- this IS the refusal mechanism for
 						// every other resolution kind. Called unconditionally (not gated on
 						// schemaProjection.enabled): parameters gate internally (schema-bearing);
 						// security/summary/tags are dialect-independent and always attempted.
-						applyPassthrough(result, docEntry, index, stats, schemaProjection.enabled, referencedSecuritySchemeNames);
+						applyPassthrough(result, docEntry, index, stats, schemaProjection.enabled, referencedSecuritySchemeNames, includeDescriptions);
 					} else {
 						result = {
 							kind: 'drift', reason: 'path',
@@ -1239,10 +1395,10 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 					};
 					stats.adopted++;
 					if (schemaProjection.enabled) {
-						applyRequestBodySchema(result, hits[0], index.componentSchemas, stats);
-						applyResponseSchemas(result, hits[0], index.componentSchemas, stats);
+						applyRequestBodySchema(result, hits[0], index.componentSchemas, stats, includeDescriptions);
+						applyResponseSchemas(result, hits[0], index.componentSchemas, stats, includeDescriptions);
 					}
-					applyPassthrough(result, hits[0], index, stats, schemaProjection.enabled, referencedSecuritySchemeNames);
+					applyPassthrough(result, hits[0], index, stats, schemaProjection.enabled, referencedSecuritySchemeNames, includeDescriptions);
 				} else if (hits.length === 1) {
 					// A single route match, but the document itself never gave that operation an
 					// operationId -- nothing to route by, so this can't become an addressable
@@ -1277,7 +1433,7 @@ export function reconcileModule({ index, module, pathPrefix = null }) {
 
 // Convenience entry point: load + index + reconcile in one call, propagating the first failure.
 // This is what bin/bskel.mjs's cmdContractEmit calls.
-export function buildReconciliation({ filePath, module, pathPrefix = null }) {
+export function buildReconciliation({ filePath, module, pathPrefix = null, includeDescriptions = false }) {
 	if (pathPrefix != null && !PATH_PREFIX_RE.test(pathPrefix)) {
 		return { ok: false, error: `--path-prefix "${pathPrefix}" is not a valid path prefix (expected e.g. "/api/v0")` };
 	}
@@ -1301,7 +1457,7 @@ export function buildReconciliation({ filePath, module, pathPrefix = null }) {
 	}
 	const indexed = indexOpenApiDocument(loaded.doc);
 	if (!indexed.ok) return indexed;
-	const recon = reconcileModule({ index: indexed, module, pathPrefix });
+	const recon = reconcileModule({ index: indexed, module, pathPrefix, includeDescriptions });
 	return {
 		ok: true,
 		document: {
@@ -1365,6 +1521,18 @@ function requestMediaTypesDecision(result) {
 	if (result.requestMediaTypesUnresolvedReason) return `unresolved:${result.requestMediaTypesUnresolvedReason}`;
 	return 'none';
 }
+// A9: same decision-only audit-trail shape, for the path-parameter schema fix.
+function pathParamSchemasDecision(result) {
+	if (result.pathParamsSkippedDialect) return 'skipped:dialect';
+	if (result.pathParamSchemas) return `copied:${result.pathParamSchemas.size}`;
+	return 'none';
+}
+// A10: same decision-only audit-trail shape as every field above.
+function descriptionDecision(result) {
+	if (result.sourceDescription) return 'copied';
+	if (result.descriptionUnresolvedReason) return `unresolved:${result.descriptionUnresolvedReason}`;
+	return 'none';
+}
 
 // `sourceFile`: {file, outsideRepo} precomputed by the caller (bin/bskel.mjs knows the repo
 // root; this module deliberately doesn't) -- keeps machine-specific absolute paths out of a
@@ -1405,6 +1573,10 @@ export function snapshotFromReconciliation(reconciliation, { featureId, sourceFi
 				// A8: same decision-only audit trail, for the two new passthrough fields.
 				per_status_responses: perStatusResponsesDecision(result),
 				request_media_types: requestMediaTypesDecision(result),
+				// A9: same decision-only audit trail, for the path-parameter schema fix.
+				path_param_schemas: pathParamSchemasDecision(result),
+				// A10: same decision-only audit trail, for the opt-in operation-level description.
+				description: descriptionDecision(result),
 			};
 		}
 	}

package/lib/cli.mjs

@@ -152,13 +152,18 @@ export const COMMANDS = {
 		allowPositionals: true,
 	},
 	'contract emit': {
-		usage: 'bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0]',
+		usage: 'bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0] [--descriptions]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			module: { type: 'string', default: null },
 			json: { type: 'boolean', default: false },
 			'openapi-file': { type: 'string', default: null },
 			'path-prefix': { type: 'string', default: null },
+			// A10 (D-openapi-description): the one source-backed field that is NOT default-on --
+			// measured real cost (2,442.7 bytes/operation average) is larger than every other field
+			// this whole passthrough effort copies combined, so it stays opt-in rather than joining
+			// A7/A8/A9's default-on behavior.
+			descriptions: { type: 'boolean', default: false },
 		},
 	},
 	// A6 (D-openapi-export): the export direction. `--allow-unprefixed` is deliberately NOT a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "type": "module",
   "description": "Spec-driven backend scaffolding: brownfield-scan gate, feature_id-keyed contracts, UUID bidirectional handles, stack-choice wiring.",
   "license": "AGPL-3.0-or-later",

package/schemas/feature-contract.schema.json

@@ -7,7 +7,7 @@
   "additionalProperties": false,
   "required": ["sbf_contract", "feature_id", "feature_uid", "source", "operations", "warnings", "completeness"],
   "properties": {
-    "sbf_contract": { "const": "6" },
+    "sbf_contract": { "const": "8" },
     "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
     "feature_uid": { "type": "string", "format": "uuid" },
     "source": {
@@ -98,6 +98,15 @@
                 }
               }
             }
+          },
+          "pathParamsHeuristic": {
+            "description": "A9: names every path-parameter segment in `pathParams` whose schema still came from this contract's own name heuristic (`/id$/i` -> a UUID pattern) rather than a real source document -- because no source document was given, the source declared no schema for that segment, or the schema failed to resolve. Present only when at least one segment is still heuristic-derived; a segment absent from this list was resolved from the source document's own real schema.",
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "sourceDescription": {
+            "description": "A10: the operation's `description`, copied verbatim from a real source document. Present only when `contract emit --descriptions` (opt-in, unlike every other source-backed field in this schema) was passed AND the source document declared one for this exact operation AND it did not exceed the length cap.",
+            "type": "string"
           }
         }
       }