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

package/lib/handles-manifest.mjs

@@ -16,21 +16,27 @@ export function manifestPath(root) {
 
 export function loadManifest(root) {
 	const parsed = readJsonIfExists(manifestPath(root));
-	if (!parsed) return { schema: MANIFEST_SCHEMA, files: {} };
+	if (!parsed) return { schema: MANIFEST_SCHEMA, files: {}, enforceRegistry: false };
 	if (parsed.schema !== MANIFEST_SCHEMA) {
 		throw new Error(`${manifestPath(root)}: unrecognized handles-manifest schema "${parsed.schema}" (expected ${MANIFEST_SCHEMA})`);
 	}
-	return parsed;
+	// O3 (D-handle-registry-enforcement): additive field, no schema bump -- a manifest written
+	// before this existed simply has no key here, and `false` is exactly its correct historical
+	// value (registry enforcement did not exist yet, so it was never "on").
+	return { enforceRegistry: false, ...parsed };
 }
 
 // Sorted keys for stable diffs if a target repo commits this file. Callers are responsible for
 // only calling this when something in `manifest.files` actually changed -- classifyFile()'s
 // 'unchanged' action means "don't touch the manifest entry", not "resave it unchanged", so a
 // true no-op re-emit leaves this file byte-identical (see test/handles-manifest.test.mjs and the
-// e2e regression in test/handles-ownership-cli.test.mjs).
+// e2e regression in test/handles-ownership-cli.test.mjs). `enforceRegistry` (O3,
+// D-handle-registry-enforcement) is repo-wide, singleton state -- the same "infra is one
+// all-or-nothing unit" scope O2's own `files` entries already give `global/handle/*` -- so it is
+// always written, never omitted, even when `false` (the default).
 export function saveManifest(root, manifest) {
 	const sortedFiles = Object.fromEntries(Object.keys(manifest.files).sort().map((k) => [k, manifest.files[k]]));
-	writeFileAtomic(manifestPath(root), `${JSON.stringify({ schema: manifest.schema, files: sortedFiles }, null, 2)}\n`);
+	writeFileAtomic(manifestPath(root), `${JSON.stringify({ schema: manifest.schema, files: sortedFiles, enforceRegistry: manifest.enforceRegistry ?? false }, null, 2)}\n`);
 }
 
 // Every resolver stub's doc comment carries "... for feature <id>." -- ResourceResolverStub.java

package/lib/repo.mjs

@@ -42,3 +42,59 @@ export function remoteTrackingTip(cwd = process.cwd(), branch) {
 		return null;
 	}
 }
+
+// D-contract-history: the chronological commit list touching one file, oldest first (reversed
+// from git's own newest-first `log` order -- a caller building a diff-over-time view wants to
+// walk forward). `--follow` survives a rename (specs/<feature>/ is renamed wholesale by `bskel
+// feature rename`, see D6). Empty array (not an error) when the path was never committed --
+// `specs/` is a TARGET repo's own file, entirely outside bskel's control whether it's tracked at
+// all, so an empty result is a normal, expected outcome here, not a failure.
+export function fileHistory(cwd, relPath) {
+	let raw;
+	try {
+		raw = git(['log', '--follow', '--format=%H%x1f%aI%x1f%s', '--', relPath], cwd);
+	} catch {
+		return [];
+	}
+	if (!raw) return [];
+	return raw.split('\n').map((line) => {
+		const [sha, date, subject] = line.split('\x1f');
+		return { sha, date, subject };
+	}).reverse();
+}
+
+// The file's exact content at one historical revision -- `git show <sha>:<path>`, not a working-
+// tree read, so this is safe to call across arbitrary history without touching the checkout.
+// Returns null (not a throw) when the path didn't exist at that revision, matching fileHistory()'s
+// own "absence is a normal outcome, not a failure" posture.
+export function showFileAtRevision(cwd, sha, relPath) {
+	try {
+		return git(['show', `${sha}:${relPath}`], cwd);
+	} catch {
+		return null;
+	}
+}
+
+// D-gate-export: the CURRENTLY checked-out branch name (`git rev-parse --abbrev-ref HEAD`) --
+// deliberately distinct from `localDefaultBranch()` above, which answers "what does origin/HEAD
+// point at," not "what is checked out right now." `HEAD` (detached) is a real, valid return value,
+// not an error -- callers that care should check for it explicitly rather than this function
+// papering over it.
+export function currentBranch(cwd = process.cwd()) {
+	try {
+		return git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+	} catch {
+		return null;
+	}
+}
+
+// D-gate-export: whether the working tree has any uncommitted change (`git status --porcelain`
+// non-empty) -- provenance context for a report that claims to describe "what this repo's gate
+// history shows," since an uncommitted change means the working tree no longer matches HEAD.
+export function isDirty(cwd = process.cwd()) {
+	try {
+		return git(['status', '--porcelain'], cwd).length > 0;
+	} catch {
+		return null;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "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/scanners/adapters/_express-shared.mjs

@@ -15,6 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { listRgFiles as sharedListRgFiles, byShallowestThenName } from '../text-util.mjs';
 
 export const EXCLUDE_GLOBS = ['!**/node_modules/**', '!**/dist/**', '!**/build/**'];
 export const VERBS = ['get', 'post', 'put', 'patch', 'delete'];
@@ -24,13 +25,13 @@ export const VERBS = ['get', 'post', 'put', 'patch', 'delete'];
 // plain path with no interpolation, not a regular string.
 export const STRING_LITERAL_RE = /^\s*["'`]([^"'`]*)["'`]/;
 
+// D-cross-adapter-root-detection: listRgFiles/byShallowestThenName themselves now live in
+// scanners/text-util.mjs (shared with python-fastapi.mjs/java-spring.mjs too) -- this file keeps
+// its own thin wrapper so every existing call site here keeps passing just (dir, globs), with
+// EXCLUDE_GLOBS applied automatically the same way it always was.
+export { byShallowestThenName };
 export function listRgFiles(dir, globs) {
-	try {
-		const out = execFileSync('rg', ['--files', ...globs.flatMap((g) => ['-g', g]), ...EXCLUDE_GLOBS.flatMap((g) => ['-g', g]), dir], { encoding: 'utf8' });
-		return out.split('\n').filter(Boolean).sort(); // O6: rg --files order isn't guaranteed.
-	} catch {
-		return []; // rg exits 1 on "no files matched" -- not an error, just nothing to report
-	}
+	return sharedListRgFiles(dir, globs, EXCLUDE_GLOBS);
 }
 
 // `rg -l -e <pattern> -g <glob>...` -- the "which source files even mention this" pass both
@@ -47,12 +48,6 @@ export function rgFilesMatching(pattern, globs, dir) {
 	}
 }
 
-export function byShallowestThenName(a, b) {
-	const depthA = a.split(path.sep).length;
-	const depthB = b.split(path.sep).length;
-	return depthA !== depthB ? depthA - depthB : a.localeCompare(b);
-}
-
 export function listCandidatePackageFiles(repoRoot) {
 	return listRgFiles(repoRoot, ['package.json']).sort(byShallowestThenName);
 }
@@ -234,5 +229,15 @@ export function expressDiagnostics(repoRoot) {
 	if (!rgOk) {
 		messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it and will throw, not degrade, if it is missing' });
 	}
+	// D-openapi-extraction-hint: like FastAPI, both Express adapters declare `api.operations:
+	// false` -- --openapi-file is load-bearing for `contract emit` to adopt any operation, not just
+	// an accuracy improvement. Unlike java-spring/python-fastapi, plain Express has NO framework-
+	// native OpenAPI generation mechanism at all -- said plainly, not papered over with vague
+	// "check your framework's docs" language. If the target project already uses a third-party
+	// generator (swagger-jsdoc, tsoa, zod-to-openapi, etc.), that tool's own output is what to pass.
+	messages.push({
+		level: 'info', code: 'openapi-extraction-hint',
+		message: '--openapi-file is not just an accuracy improvement for this adapter -- api.operations is false (no operationId concept in plain Express), so `contract emit` cannot adopt any operation without one. Plain Express has NO framework-native OpenAPI generation -- if this project already uses a third-party generator (swagger-jsdoc, tsoa, zod-to-openapi, etc.), pass that tool\'s own output. Ignore this if you already have a source document.',
+	});
 	return messages;
 }

package/scanners/adapters/generic-grep.mjs

@@ -101,11 +101,15 @@ export function scanGenericGrep(repoRoot) {
 // regardless of what generic-grep itself finds. See D-generic-grep-reconnaissance for why every
 // capability below is honestly false rather than a best-effort partial implementation.
 export const adapter = {
-	contract: 'sbf.adapter/1',
+	contract: 'sbf.adapter/2',
 	id: 'generic-grep',
 	title: 'Generic route-pattern grep (fallback)',
 	specificity: 0,
 	confidence: 'low',
+	// D-adapter-verification-basis: reconnaissance-only by design (G3) -- every codegen capability
+	// is honestly false, so there is no codegen output to verify against any oracle at all. Not
+	// "unverified" in the sense the other four values mean; genuinely not applicable.
+	verificationBasis: 'not-applicable',
 	capabilities: {
 		'api.operations': false,
 		'api.request-shape': false,

package/scanners/adapters/java-spring.mjs

@@ -5,14 +5,35 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { lineNumberAt } from '../text-util.mjs';
+import { lineNumberAt, listRgFiles, byShallowestThenName } from '../text-util.mjs';
 import { maskNonCode, findClassOrRecordDeclaration, findClassLevelMappingArgs, findMappingAnnotations } from './_java-spring-analyzer.mjs';
 
+const JAVA_BUILD_FILE_GLOBS = ['build.gradle', 'build.gradle.kts', 'pom.xml'];
+
+// D-cross-adapter-root-detection: until now, the ONLY one of this project's 4 real adapters whose
+// detect() assumed repoRoot itself was the project root -- python-fastapi.mjs/typescript-express.mjs/
+// javascript-express.mjs each already walk the WHOLE repo for their own project marker file
+// (python-fastapi.mjs's own comment names the exact reason: "a real target [oracle] is a monorepo
+// whose FastAPI project lives under backend/"). A Spring project nested the same way (e.g.
+// backend-java/build.gradle in a polyglot monorepo) was silently invisible to this adapter --
+// found live by direct comparison of all 4 adapters' detect() functions, not anticipated
+// defensively. `runScan()`'s specificity-based arbitration (see scanners/index.mjs and
+// python-fastapi.mjs's own specificity comment) already handles the "two adapters both detect the
+// same repoRoot" case deterministically; this fix addresses the OTHER failure mode -- a real
+// Spring project going completely undetected and silently falling through to generic-grep.
+//
+// Every candidate build file is tried in turn, shallowest first, not just the first one found
+// (unlike python-fastapi's single-candidate check) -- a real multi-module Gradle project's ROOT
+// build.gradle is routinely just an aggregator (`subprojects { ... }`) with no src/main/java of
+// its own; the actual source lives under a child module's own build.gradle. Same two-signal bar
+// as before either way: a build file AND a sibling src/main/java, both required.
 export function detectJavaSpringRoot(repoRoot) {
-	const buildFiles = ['build.gradle', 'build.gradle.kts', 'pom.xml'];
-	if (!buildFiles.some((f) => fs.existsSync(path.join(repoRoot, f)))) return null;
-	const srcRoot = path.join(repoRoot, 'src', 'main', 'java');
-	return fs.existsSync(srcRoot) ? srcRoot : null;
+	const buildFiles = listRgFiles(repoRoot, JAVA_BUILD_FILE_GLOBS).sort(byShallowestThenName);
+	for (const buildFile of buildFiles) {
+		const srcRoot = path.join(path.dirname(buildFile), 'src', 'main', 'java');
+		if (fs.existsSync(srcRoot)) return srcRoot;
+	}
+	return null;
 }
 
 // O6: `rg --files` (no `--sort`) is explicitly unordered/parallel by ripgrep's own docs -- two
@@ -167,8 +188,12 @@ export function detectGlobalPathPrefixSignals(repoRoot) {
 	// mentioning configurePathMatch, then a content read confirms addPathPrefix( is actually
 	// present (a configurePathMatch override that does something else entirely -- a custom
 	// PathMatcher, a trailing-slash setting -- must not be reported as a prefix).
-	const srcRoot = path.join(repoRoot, 'src', 'main', 'java');
-	if (fs.existsSync(srcRoot)) {
+	// D-cross-adapter-root-detection: reuses detectJavaSpringRoot() rather than re-deriving
+	// `path.join(repoRoot, 'src', 'main', 'java')` independently -- the latter was a SECOND place
+	// this file assumed repoRoot itself was the project root, found alongside the same bug in
+	// detectJavaSpringRoot() itself.
+	const srcRoot = detectJavaSpringRoot(repoRoot);
+	if (srcRoot) {
 		let candidates = [];
 		try {
 			candidates = execFileSync('rg', ['-l', 'configurePathMatch', '-g', '*.java', srcRoot], { encoding: 'utf8' }).split('\n').filter(Boolean).sort();
@@ -250,11 +275,15 @@ export function scanJavaSpring(repoRoot) {
 // build file AND src/main/java both exist -- a build-file-plus-source-layout-confirmed match, the
 // strongest signal any adapter in this codebase can give.
 export const adapter = {
-	contract: 'sbf.adapter/1',
+	contract: 'sbf.adapter/2',
 	id: 'java-spring',
 	title: 'Java / Spring Boot',
 	specificity: 100,
 	confidence: 'high',
+	// D-adapter-verification-basis: the whole A1-A12 OpenAPI-passthrough line, plus O1-O6's
+	// handles codegen, was verified against a real production Spring Boot repo (Team-IZ-Backend) --
+	// the strongest basis any adapter in this codebase has.
+	verificationBasis: 'production-repo',
 	capabilities: {
 		'api.operations': true,
 		'api.request-shape': true,
@@ -278,13 +307,17 @@ export const adapter = {
 	},
 	diagnostics(repoRoot) {
 		const messages = [];
-		const buildFiles = ['build.gradle', 'build.gradle.kts', 'pom.xml'];
-		if (!buildFiles.some((f) => fs.existsSync(path.join(repoRoot, f)))) {
-			messages.push({ level: 'info', code: 'no-build-file', message: `none of ${buildFiles.join(', ')} found at repo root` });
+		// D-cross-adapter-root-detection: recursive now (matches detectJavaSpringRoot() itself),
+		// not repoRoot-only -- these two checks used to have their own private, repoRoot-only copy
+		// of the same signals detectJavaSpringRoot() computes, which is exactly what let the
+		// underlying bug (a nested build.gradle going undetected) hide from `bskel doctor` too.
+		const buildFiles = listRgFiles(repoRoot, JAVA_BUILD_FILE_GLOBS);
+		if (buildFiles.length === 0) {
+			messages.push({ level: 'info', code: 'no-build-file', message: `none of ${JAVA_BUILD_FILE_GLOBS.join(', ')} found anywhere in the repo` });
 		}
-		const srcRoot = path.join(repoRoot, 'src', 'main', 'java');
-		if (!fs.existsSync(srcRoot)) {
-			messages.push({ level: 'info', code: 'no-src-main-java', message: 'src/main/java does not exist' });
+		const srcRoot = detectJavaSpringRoot(repoRoot);
+		if (!srcRoot) {
+			messages.push({ level: 'info', code: 'no-src-main-java', message: buildFiles.length > 0 ? 'found a build file, but none has a sibling src/main/java' : 'src/main/java does not exist' });
 		} else {
 			let rgOk = true;
 			try {
@@ -296,6 +329,19 @@ export const adapter = {
 				messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it and will throw, not degrade, if it is missing' });
 			}
 		}
+		// D-openapi-extraction-hint: `contract emit --openapi-file` (A1-A12) is where real accuracy
+		// comes from for this adapter (path/schema/parameter/security correction, not just the
+		// name-heuristic fallback) -- most useful before that flag has ever been used, hence
+		// `level: 'info'`, not a warning. If springdoc-openapi is on the classpath: with the Gradle
+		// plugin (`org.springdoc.openapi-gradle-plugin`) configured, `./gradlew generateOpenApiDocs`
+		// boots the app briefly and writes build/api-docs.json without a human ever starting/curling
+		// a server by hand -- this repo's own real Team-IZ-Backend oracle file was produced exactly
+		// this way. Without that plugin, the only way is to actually run the app and capture its
+		// live /v3/api-docs endpoint -- named honestly as manual, not hidden behind vague language.
+		messages.push({
+			level: 'info', code: 'openapi-extraction-hint',
+			message: 'for real schema/path accuracy, pass --openapi-file to `contract emit`. If springdoc-openapi is on the classpath: with the Gradle plugin (org.springdoc.openapi-gradle-plugin) configured, `./gradlew generateOpenApiDocs` writes build/api-docs.json without running the app by hand; otherwise, run the app and capture its live /v3/api-docs endpoint (e.g. `curl http://localhost:8080/v3/api-docs > api-docs.json`). Ignore this if you already have a source document.',
+		});
 		return messages;
 	},
 };

package/scanners/adapters/javascript-express.mjs

@@ -382,7 +382,7 @@ export function scanJavaScriptExpress(repoRoot, detection) {
 // metadata and a working codegen provider), so it should win that overlap quietly rather than
 // tripping runScan()'s same-specificity ambiguity error. Checkable via `bskel doctor`.
 export const adapter = {
-	contract: 'sbf.adapter/1',
+	contract: 'sbf.adapter/2',
 	id: 'javascript-express',
 	title: 'JavaScript / Express (ESM, no ORM)',
 	specificity: 80,
@@ -391,6 +391,10 @@ export const adapter = {
 	// walk), not how many capabilities it can offer. generic-grep is `low` because it has no module
 	// inference and no prefix resolution at all -- this adapter has both.
 	confidence: 'high',
+	// D-adapter-verification-basis: no real-world oracle at all, unlike every other real framework
+	// adapter -- the real target repository was deliberately never touched, and the committed
+	// synthetic fixture carries all of the regression weight. Named honestly, not hidden.
+	verificationBasis: 'synthetic-only',
 	capabilities: {
 		// false: plain Express has no operationId concept at all. --openapi-file is the honest path
 		// forward for an app that has one; see CAPABILITY_SATISFIERS in scanners/capabilities.mjs.

package/scanners/adapters/python-fastapi.mjs

@@ -12,7 +12,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { lineNumberAt } from '../text-util.mjs';
+import { lineNumberAt, listRgFiles as sharedListRgFiles, byShallowestThenName } from '../text-util.mjs';
 
 const PROJECT_FILE_GLOBS = ['pyproject.toml', 'requirements*.txt'];
 const EXCLUDE_GLOBS = ['!**/.venv/**', '!**/site-packages/**', '!**/node_modules/**', '!**/__pycache__/**'];
@@ -28,18 +28,7 @@ const CLASS_RE = /^class\s+(\w+)\s*\(([^)]*)\)\s*:/gm;
 const INCLUDE_ROUTER_RE = /include_router\s*\(/g;
 
 function listRgFiles(dir, globs) {
-	try {
-		const out = execFileSync('rg', ['--files', ...globs.flatMap((g) => ['-g', g]), ...EXCLUDE_GLOBS.flatMap((g) => ['-g', g]), dir], { encoding: 'utf8' });
-		return out.split('\n').filter(Boolean).sort(); // O6: rg --files order isn't guaranteed -- see java-spring.mjs's listJavaFiles.
-	} catch {
-		return []; // rg exits 1 on "no files matched" -- not an error, just nothing to report
-	}
-}
-
-function byShallowestThenName(a, b) {
-	const depthA = a.split(path.sep).length;
-	const depthB = b.split(path.sep).length;
-	return depthA !== depthB ? depthA - depthB : a.localeCompare(b);
+	return sharedListRgFiles(dir, globs, EXCLUDE_GLOBS);
 }
 
 function listCandidateProjectFiles(repoRoot) {
@@ -288,11 +277,15 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 // them has to win, and it must be the same one every time" -- not a functional gap on this side
 // anymore, a real, documented trade-off (see DECISIONS.md), checkable via `bskel doctor`.
 export const adapter = {
-	contract: 'sbf.adapter/1',
+	contract: 'sbf.adapter/2',
 	id: 'python-fastapi',
 	title: 'Python / FastAPI',
 	specificity: 90,
 	confidence: 'high',
+	// D-adapter-verification-basis: verified against `fastapi/full-stack-fastapi-template`, the
+	// official FastAPI-author-maintained reference stack -- the strongest verification tier this
+	// project distinguishes (unlike java-spring's real-but-non-canonical production repo).
+	verificationBasis: 'official-reference',
 	capabilities: {
 		// false: FastAPI generates operation ids at runtime (per-project, sometimes customized) --
 		// never statically derivable from source. --openapi-file is the honest path forward; see
@@ -343,6 +336,16 @@ export const adapter = {
 		if (!rgOk) {
 			messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it and will throw, not degrade, if it is missing' });
 		}
+		// D-openapi-extraction-hint: unlike java-spring, this adapter's own capabilities already
+		// declare `api.operations: false` (FastAPI assigns operationIds at runtime) -- --openapi-file
+		// isn't just an accuracy improvement here, it's load-bearing for `contract emit` to adopt any
+		// operation at all (see D-fastapi-adapter). FastAPI exposes its own OpenAPI schema directly
+		// via `app.openapi()` -- no server needs to actually be listening, just importing the app
+		// object is enough, the real mechanism this project's own oracle checks used.
+		messages.push({
+			level: 'info', code: 'openapi-extraction-hint',
+			message: '--openapi-file is not just an accuracy improvement for this adapter -- api.operations is false (FastAPI assigns operationIds at runtime), so `contract emit` cannot adopt any operation without one. No server needs to be running: `python -c "from app.main import app; import json; print(json.dumps(app.openapi()))" > api-docs.json` (adjust the import path to your own app module). Ignore this if you already have a source document.',
+		});
 		return messages;
 	},
 };

package/scanners/adapters/typescript-express.mjs

@@ -264,11 +264,16 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 // (not an inherent "TypeScript signals are weaker" claim) so a polyglot repo's adapter selection
 // stays deterministic, checkable via `bskel doctor`.
 export const adapter = {
-	contract: 'sbf.adapter/1',
+	contract: 'sbf.adapter/2',
 	id: 'typescript-express',
 	title: 'TypeScript / Express / TypeORM',
 	specificity: 85,
 	confidence: 'high',
+	// D-adapter-verification-basis: no framework-maintained Express reference exists (confirmed by
+	// real research before this adapter was built) -- verified instead against the best-validated
+	// real community boilerplate found, `mkosir/typeorm-express-typescript`. Permanently weaker
+	// than java-spring/python-fastapi's own basis, named honestly rather than hidden.
+	verificationBasis: 'community-sample',
 	capabilities: {
 		// false: plain Express has no operationId concept at all. --openapi-file is the honest path
 		// forward for an app that has one; see CAPABILITY_SATISFIERS in scanners/capabilities.mjs.

package/scanners/registry.mjs

@@ -29,7 +29,10 @@ import Ajv2020 from 'ajv/dist/2020.js';
 const REGISTRY_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ADAPTERS_DIR = path.join(REGISTRY_DIR, 'adapters');
 const SCHEMAS_ROOT = path.join(REGISTRY_DIR, '..', 'schemas');
-const SUPPORTED_CONTRACT = 'sbf.adapter/1';
+// D-adapter-verification-basis (W2/B6): bumped 1->2 for the new required `verificationBasis`
+// field -- a real breaking change to the descriptor shape, same "bump the contract const" house
+// style A7-A11 already established for sbf_contract.
+const SUPPORTED_CONTRACT = 'sbf.adapter/2';
 
 let _ajv = null;
 function ajv() {
@@ -67,7 +70,7 @@ async function loadOneAdapter(file, schema) {
 	}
 	const descriptor = mod.adapter;
 	if (!descriptor || typeof descriptor !== 'object') {
-		return { error: { file, message: 'must `export const adapter = {...}` (sbf.adapter/1 shape) -- no such export found' } };
+		return { error: { file, message: `must \`export const adapter = {...}\` (${SUPPORTED_CONTRACT} shape) -- no such export found` } };
 	}
 	if (descriptor.contract !== SUPPORTED_CONTRACT) {
 		return { error: { file, message: `declares contract "${descriptor.contract}" -- this build only understands "${SUPPORTED_CONTRACT}"` } };

package/scanners/text-util.mjs

@@ -6,3 +6,28 @@ export function lineNumberAt(text, index) {
 	for (let i = 0; i < index; i++) if (text[i] === '\n') line++;
 	return line;
 }
+
+// D-cross-adapter-root-detection: same extraction pattern as lineNumberAt above, one adapter
+// generation later -- python-fastapi.mjs and scanners/adapters/_express-shared.mjs (shared by
+// typescript-express.mjs/javascript-express.mjs) each already had their own private copy of both
+// functions before java-spring.mjs needed them too. `excludeGlobs` is a parameter, not baked in,
+// because the two existing copies actually disagreed on it (Python's excludes .venv/site-packages/
+// __pycache__; the Express one excludes dist/build) -- inlining either would have been wrong for
+// the other caller.
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+export function listRgFiles(dir, globs, excludeGlobs = []) {
+	try {
+		const out = execFileSync('rg', ['--files', ...globs.flatMap((g) => ['-g', g]), ...excludeGlobs.flatMap((g) => ['-g', g]), dir], { encoding: 'utf8' });
+		return out.split('\n').filter(Boolean).sort(); // O6: rg --files order isn't guaranteed.
+	} catch {
+		return []; // rg exits 1 on "no files matched" -- not an error, just nothing to report
+	}
+}
+
+export function byShallowestThenName(a, b) {
+	const depthA = a.split(path.sep).length;
+	const depthB = b.split(path.sep).length;
+	return depthA !== depthB ? depthA - depthB : a.localeCompare(b);
+}

package/schemas/adapter.schema.json

@@ -5,9 +5,9 @@
   "description": "Validates the JSON-shaped fields of the `adapter` object a scanners/adapters/<id>.mjs module must export (detect/scan/diagnostics/listReadSet are functions and are checked separately -- JSON Schema has no vocabulary for them). Loaded by scanners/registry.mjs at process start. See D-adapter-registry in DECISIONS.md.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["contract", "id", "title", "specificity", "confidence", "capabilities"],
+  "required": ["contract", "id", "title", "specificity", "confidence", "capabilities", "verificationBasis"],
   "properties": {
-    "contract": { "const": "sbf.adapter/1" },
+    "contract": { "const": "sbf.adapter/2" },
     "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
     "title": { "type": "string" },
     "specificity": { "type": "number" },
@@ -18,6 +18,10 @@
         "enum": ["api.operations", "api.request-shape", "resource.fetch", "codegen.handles"]
       },
       "additionalProperties": { "type": "boolean" }
+    },
+    "verificationBasis": {
+      "description": "D-adapter-verification-basis (W2/B6): a DIFFERENT axis from `confidence` above -- confidence means \"how sure was detect() this repo uses this framework,\" verificationBasis means \"how well was this adapter's own parsing/codegen logic checked against real code, ever.\" official-reference: verified against a framework-author-maintained reference stack. production-repo: verified against a real production repo. community-sample: verified against one hand-read community boilerplate, no official reference exists. synthetic-only: no real-world oracle at all, only a committed synthetic fixture. not-applicable: reconnaissance-only, no codegen to verify (generic-grep).",
+      "enum": ["official-reference", "production-repo", "community-sample", "synthetic-only", "not-applicable"]
     }
   }
 }

package/schemas/contract-resolution.schema.json

@@ -20,7 +20,12 @@
           "code": { "type": "string", "pattern": "^CONTRACT_[A-Z_]+$" },
           "subject": { "type": ["string", "null"] },
           "reason": { "type": "string" },
-          "at": { "type": "string", "format": "date-time" }
+          "at": { "type": "string", "format": "date-time" },
+          "expires_at": {
+            "description": "D-waiver-expiry: optional, set only when `contract waive --expires <Nd>` was used. Once now >= expires_at, this waiver stops covering its warning -- see contracts/completeness.mjs's evaluateResolution().",
+            "type": "string",
+            "format": "date-time"
+          }
         }
       }
     }

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"
           }
         }
       }

package/schemas/handles-plan.schema.json

@@ -22,6 +22,7 @@
           "idField": { "type": ["string", "null"] },
           "readPath": { "type": ["string", "null"] },
           "requiredAuthority": { "type": "string" },
+          "requiredAuthorityForPatch": { "type": "string", "description": "O5 (D-resolver-authorization-action-aware): java-spring only -- derived independently from the entity's UPDATE endpoint, not copied from requiredAuthority (which is fetch/recover's own value)." },
           "willGenerateResolver": { "type": "boolean" }
         }
       }

package/stack/bootstrap/db-up.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Generated by backend-skeleton (stack choice: postgres-dev-db). Self-contained in this repo --
+# does not require backend-skeleton to be installed to run. See scripts/_bskel-lib.sh for
+# shared helpers (the same env_upsert() the ngrok stack choice's script already uses).
+#
+# D-docker-postgres-stack: this is a LOCAL DEV database only, not a production deployment
+# recipe -- no TLS, a fixed default password, a single unreplicated container. Named here as a
+# deliberate, permanent scope limit, the same "narrow and honest beats broad and wrong" posture
+# A12's own scoping already established for this backlog.
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+source scripts/_bskel-lib.sh
+
+COMPOSE_FILE="docker-compose.postgres.yml"
+ENV_FILE=".env"
+POSTGRES_USER="${POSTGRES_USER:-app}"
+POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-app}"
+POSTGRES_DB="${POSTGRES_DB:-app}"
+POSTGRES_PORT="${POSTGRES_PORT:-5432}"
+TIMEOUT_S=30
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--timeout) TIMEOUT_S="$2"; shift 2 ;;
+		*) echo "unknown argument: $1" >&2; exit 14 ;;
+	esac
+done
+
+if ! command -v docker >/dev/null 2>&1; then
+	echo "docker not found on PATH -- install Docker before running this script" >&2
+	exit 1
+fi
+
+export POSTGRES_USER POSTGRES_PASSWORD POSTGRES_DB POSTGRES_PORT
+echo "starting postgres via $COMPOSE_FILE..."
+docker compose -f "$COMPOSE_FILE" up -d
+
+echo "waiting for postgres to accept connections (up to ${TIMEOUT_S}s)..."
+waited=0
+until docker compose -f "$COMPOSE_FILE" exec -T db pg_isready -U "$POSTGRES_USER" >/dev/null 2>&1; do
+	waited=$((waited + 1))
+	if [ "$waited" -ge "$TIMEOUT_S" ]; then
+		echo "postgres did not become ready within ${TIMEOUT_S}s -- check: docker compose -f $COMPOSE_FILE logs" >&2
+		exit 1
+	fi
+	sleep 1
+done
+
+DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${POSTGRES_PORT}/${POSTGRES_DB}"
+env_upsert "$ENV_FILE" DATABASE_URL "$DATABASE_URL"
+echo "postgres is up, wrote DATABASE_URL to $ENV_FILE"
+echo "note: if your app reads a differently-named variable, copy/rename this value (and pass that name to \`bskel scan --db --database-url-env <NAME>\` for schema introspection) -- see .env.example"

package/stack/bootstrap/docker-compose.postgres.yml

@@ -0,0 +1,18 @@
+# Generated by backend-skeleton (stack choice: postgres-dev-db). A LOCAL-ONLY Postgres for
+# development -- never started automatically by bskel itself; run it via scripts/db-up.sh.
+# `${VAR:-default}` below is Docker Compose's own env substitution syntax (single braces), not
+# this project's own double-brace template syntax -- scripts/db-up.sh exports these before
+# calling `docker compose up`.
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-app}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}
+      POSTGRES_DB: ${POSTGRES_DB:-app}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - bskel-postgres-dev-data:/var/lib/postgresql/data
+volumes:
+  bskel-postgres-dev-data: