backend-skeleton 1.7.1 → 1.8.0

package/README.md

@@ -105,6 +105,10 @@ bskel scan                        # zero flags: every module/controller/entity/e
                                    #   files written, no gate touched
 ```
 
+Rails projects are scanned statically by default. On a trusted Rails checkout, add
+`--runtime-routes` to boot the application and use `bin/rails routes --expanded` as the route
+source; initializers and application boot code will run.
+
 That's a read-only look, not the gated workflow — for real feature work (collision-checked against
 a specific idea, contract-gated, codegen), see below.
 
@@ -595,6 +599,11 @@ string for anything missing.
 `D-adapter-registry` in `DECISIONS.md`):
 - `java-spring` — Spring Boot (`build.gradle`/`pom.xml` + `src/main/java`). Full capability set:
   operation extraction, request-body detection, and a real codegen provider for `handles emit`.
+- `ruby-rails` — Rails 8 (`Gemfile` + `config/application.rb` + `config/routes.rb`). Statically
+  expands conventional routes/resources and extracts ActiveRecord table/primary-key metadata.
+  Operation ids are deterministic bskel syntheses, not source declarations; `--runtime-routes`
+  explicitly boots the trusted application for authoritative framework routing. Scanner only:
+  request-shape extraction and handles codegen are not supported.
 - `python-fastapi` — FastAPI + SQLModel. Real codegen provider for `handles emit`; contract-grade
   operation extraction is not supported (FastAPI generates operation ids at runtime) — pass a real
   OpenAPI document via `--openapi-file` for a trustworthy contract.

package/bin/bskel.mjs

@@ -98,7 +98,7 @@ function usage() {
   bskel pattern show <pattern_id> --pattern-database-url-env <NAME> [--json]
   bskel pattern suggest --stack spring|fastapi --pattern-database-url-env <NAME> [--json]
   bskel preflight [--max-behind N] [--offline|--no-fetch] [--allow-dirty] [--max-age-minutes N] [--fetch-timeout-seconds N] [--json]
-  bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]
+  bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--runtime-routes] [--db [--database-url-env <NAME>] [--schema public]]
   bskel scan disposition --feature <id> --mode reuse|extend|replace|parallel [--module <name>] [--note "..."] [--breaking-approved]
   bskel scan explain <module> --feature <id> [--json]
   bskel scan repair --feature <id> [--json]
@@ -711,8 +711,10 @@ async function cmdScan(args) {
 	}
 	let report;
 	try {
-		report = runScan({ repoRoot: root, terms, includeDb: flags.db, dbSchema, rgAvailable });
+		report = runScan({ repoRoot: root, terms, includeDb: flags.db, dbSchema, rgAvailable, runtimeRoutes: flags['runtime-routes'] });
 	} catch (err) {
+		if (err.code === 'RUNTIME_ROUTES_UNSUPPORTED') fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
+		if (err.code === 'RUNTIME_ROUTES_FAILED') fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', err.message);
 		// Unreachable with the two shipped adapters (generic-grep's specificity-0 detect() is
 		// unconditional) -- becomes reachable the moment a future adapter's detect() is
 		// conditional, or two adapters tie at the same specificity. See scanners/index.mjs.

package/contracts/emit.mjs

@@ -135,7 +135,7 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 				let operationId = ep.operationId;
 				let verb = ep.verb;
 				let route = ep.path;
-				let provenance = 'scan';
+				let provenance = ep.operationIdSource === 'bskel-synthesized' ? 'scan-synthesized' : 'scan';
 				let openapiAttempted = false;
 				let openapiReason = null;
 				// A2/A3: only ever set for matched/adopted (contracts/openapi.mjs's applyRequestBodySchema/
@@ -225,7 +225,7 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 						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`,
+								message: `operationId "${operationId}" for ${res.verb} ${res.path} was not source-pinned by the scanner -- adopted directly from the OpenAPI document instead`,
 								detail: { verb: res.verb, path: res.path, scan_verb: ep.verb, scan_path: ep.path },
 							}));
 							break;
@@ -263,6 +263,13 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 							// recording that OpenAPI reconciliation was attempted and why it didn't help.
 							openapiAttempted = true;
 							openapiReason = res.reason;
+							if (ep.operationIdSource === 'bskel-synthesized') {
+								warnings.push(makeWarning('CONTRACT_OPENAPI_MISSING_OPERATION', {
+									subject: ep.operationId,
+									message: `bskel-synthesized operationId "${ep.operationId}" (${ep.verb} ${ep.path}) could not be reconciled to a unique OpenAPI operation (${res.reason}) -- keeping the synthesized id and scan path`,
+									detail: { verb: ep.verb, path: ep.path, reason: res.reason },
+								}));
+							}
 							break;
 						default:
 							break;

package/contracts/openapi.mjs

@@ -1768,7 +1768,7 @@ export function reconcileModule({ index, module, pathPrefix = null, includeDescr
 	const anchorDeltas = [];
 	for (const controller of module.controllers) {
 		for (const ep of controller.endpoints) {
-			if (!ep.operationId) continue;
+			if (!ep.operationId || ep.operationIdSource === 'bskel-synthesized') continue;
 			const docEntry = index.byOperationId.get(ep.operationId);
 			if (!docEntry || docEntry.verb !== ep.verb) continue; // verb mismatch => not a safe anchor, surfaces as drift below
 			const delta = computeDelta(ep.path, docEntry.path);
@@ -1828,7 +1828,7 @@ export function reconcileModule({ index, module, pathPrefix = null, includeDescr
 			const key = endpointKey(ci, ei);
 			let result;
 
-			if (ep.operationId) {
+			if (ep.operationId && ep.operationIdSource !== 'bskel-synthesized') {
 				const docEntry = index.byOperationId.get(ep.operationId);
 				if (!docEntry) {
 					result = { kind: 'missing', scanVerb: ep.verb, scanPath: ep.path };
@@ -1868,14 +1868,18 @@ export function reconcileModule({ index, module, pathPrefix = null, includeDescr
 						stats.drift++;
 					}
 				}
-			} else if (prefix.value == null) {
-				result = { kind: 'unresolved', reason: 'prefix-inconclusive', scanVerb: ep.verb, scanPath: ep.path };
-				stats.unresolved++;
 			} else {
-				const candidates = prefix.value === '' ? [ep.path] : [...new Set([prefix.value + ep.path, ep.path])];
+				// An explicitly bskel-synthesized operation id is useful when no source document
+				// exists, but it must never be treated as if an OpenAPI producer authored the same
+				// identifier. Reconcile it exactly like an unpinned endpoint: route first, then adopt
+				// the document's own operationId. Exact-path matching remains safe even when no
+				// prefix could be inferred; a caller only needs --path-prefix when exact matching fails.
+				const candidates = prefix.value == null
+					? [ep.path]
+					: prefix.value === '' ? [ep.path] : [...new Set([prefix.value + ep.path, ep.path])];
 				const hits = candidates.flatMap((c) => index.byRoute.get(`${ep.verb} ${canonicalRouteShape(c)}`) ?? []);
 				if (hits.length === 0) {
-					result = { kind: 'unresolved', reason: 'no-candidate', scanVerb: ep.verb, scanPath: ep.path };
+					result = { kind: 'unresolved', reason: prefix.value == null ? 'prefix-inconclusive' : 'no-candidate', scanVerb: ep.verb, scanPath: ep.path };
 					stats.unresolved++;
 				} else if (hits.length === 1 && hits[0].operationId) {
 					result = {

package/lib/cli.mjs

@@ -120,7 +120,7 @@ export const COMMANDS = {
 		},
 	},
 	scan: {
-		usage: 'bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]',
+		usage: 'bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--runtime-routes] [--db [--database-url-env <NAME>] [--schema public]]',
 		options: {
 			feature: { type: 'string', default: null },
 			terms: { type: 'string', default: '' },
@@ -132,6 +132,7 @@ export const COMMANDS = {
 			schema: { type: 'string', default: 'public' },
 			json: { type: 'boolean', default: false },
 			'accept-low-confidence': { type: 'boolean', default: false },
+			'runtime-routes': { type: 'boolean', default: false },
 		},
 	},
 	'scan disposition': {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "backend-skeleton",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "type": "module",
-  "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
+  "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scans Spring, Rails, FastAPI, and Express; scaffolding codegen included for selected stacks.",
   "license": "AGPL-3.0-or-later",
   "repository": {
     "type": "git",
@@ -49,6 +49,7 @@
     "test:java-ast": "node scripts/java-ast-smoke.mjs",
     "test:python-integration": "node scripts/python-integration-smoke.mjs",
     "test:typescript-compile": "node scripts/typescript-typecheck-smoke.mjs",
+    "test:rails-integration": "node scripts/rails-integration-smoke.mjs",
     "test:spring-initializr-canary": "node scripts/spring-initializr-canary.mjs",
     "test:shadow-validation": "node scripts/shadow-validation-smoke.mjs",
     "test:oracle-corpus": "node scripts/shadow-validation-smoke.mjs --manifest test/fixtures/oracle-manifest.json",

package/scanners/adapters/ruby-rails.mjs

@@ -0,0 +1,578 @@
+// Ruby on Rails scanner adapter. The default path is deliberately static and never boots the
+// target application. `bskel scan --runtime-routes` is the explicit opt-in that calls the
+// framework's own `bin/rails routes --expanded`; see introspectRailsRoutes() below.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { byShallowestThenName, binaryAvailable, lineNumberAt, listRgFiles } from '../text-util.mjs';
+
+// Large Rails applications may depend on the component gems directly instead of the `rails`
+// meta-gem (Discourse does this with `railties` plus action*/active*). `railties` is the precise
+// boot/framework marker; the Rails::Application + routes.rb checks below still prevent a library
+// that merely depends on railties from being mistaken for an application.
+const RAILS_DEP_RE = /(?:^|\n)\s*(?:gem\s*[ (]?\s*["'](?:rails|railties)["']|(?:rails|railties)\s*\()/m;
+const RAILS_APP_RE = /class\s+[A-Z]\w*(?:::[A-Z]\w*)*\s*<\s*Rails::Application\b/;
+const HTTP_VERBS = new Set(['get', 'post', 'put', 'patch', 'delete']);
+const RESOURCE_ACTIONS = Object.freeze(['index', 'create', 'new', 'show', 'edit', 'update', 'destroy']);
+// These are rooted at the detected Rails project. A `!**/tmp/**` form also matches an absolute
+// checkout path under the operating system's /tmp directory and excludes the entire repo on
+// Linux (the real oracle harness clones there), not merely Rails' own tmp/ subtree.
+const EXCLUDE_GLOBS = ['!.bundle/**', '!vendor/bundle/**', '!tmp/**', '!log/**', '!node_modules/**'];
+
+function railsFiles(root, globs) {
+	return listRgFiles(root, globs, EXCLUDE_GLOBS);
+}
+
+function rubyFilesUnder(projectRoot, prefixes) {
+	return railsFiles(projectRoot, ['*.rb']).filter((file) => {
+		const rel = path.relative(projectRoot, file).split(path.sep).join('/');
+		return prefixes.some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`));
+	});
+}
+
+function routeFiles(projectRoot) {
+	return rubyFilesUnder(projectRoot, ['config/routes.rb', 'config/routes']);
+}
+
+function railsReadFiles(projectRoot) {
+	const markers = railsFiles(projectRoot, ['Gemfile', 'Gemfile.lock']);
+	const ruby = rubyFilesUnder(projectRoot, ['config', 'app/controllers', 'app/models', 'lib']);
+	return [...new Set([...markers, ...ruby])].sort();
+}
+
+function candidateProjectRoots(repoRoot) {
+	const roots = new Set();
+	for (const file of railsFiles(repoRoot, ['Gemfile', 'Gemfile.lock'])) roots.add(path.dirname(file));
+	return [...roots].sort(byShallowestThenName);
+}
+
+function declaresRails(projectRoot) {
+	for (const name of ['Gemfile', 'Gemfile.lock']) {
+		const file = path.join(projectRoot, name);
+		try {
+			if (RAILS_DEP_RE.test(fs.readFileSync(file, 'utf8'))) return true;
+		} catch {
+			// optional marker file
+		}
+	}
+	return false;
+}
+
+export function detectRubyRailsRoot(repoRoot) {
+	for (const projectRoot of candidateProjectRoots(repoRoot)) {
+		if (!declaresRails(projectRoot)) continue;
+		const application = path.join(projectRoot, 'config', 'application.rb');
+		const routes = path.join(projectRoot, 'config', 'routes.rb');
+		if (!fs.existsSync(application) || !fs.existsSync(routes)) continue;
+		try {
+			if (!RAILS_APP_RE.test(fs.readFileSync(application, 'utf8'))) continue;
+		} catch {
+			continue;
+		}
+		return projectRoot;
+	}
+	return null;
+}
+
+function stripComment(line) {
+	let quote = null;
+	let escaped = false;
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (escaped) { escaped = false; continue; }
+		if (quote && ch === '\\') { escaped = true; continue; }
+		if (quote) { if (ch === quote) quote = null; continue; }
+		if (ch === '"' || ch === "'") { quote = ch; continue; }
+		if (ch === '#') return line.slice(0, i);
+	}
+	return line;
+}
+
+function bracketDelta(text) {
+	let delta = 0;
+	let quote = null;
+	let escaped = false;
+	for (const ch of text) {
+		if (escaped) { escaped = false; continue; }
+		if (quote && ch === '\\') { escaped = true; continue; }
+		if (quote) { if (ch === quote) quote = null; continue; }
+		if (ch === '"' || ch === "'") { quote = ch; continue; }
+		if ('([{'.includes(ch)) delta++;
+		else if (')]}'.includes(ch)) delta--;
+	}
+	return delta;
+}
+
+function logicalStatements(text) {
+	const out = [];
+	const lines = text.split('\n');
+	let pending = '';
+	let startLine = 1;
+	let depth = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const code = stripComment(lines[i]).trim();
+		if (!pending && !code) continue;
+		if (!pending) startLine = i + 1;
+		pending += `${pending ? ' ' : ''}${code}`;
+		depth += bracketDelta(code);
+		if (depth > 0 || /(?:,|=>|\\)\s*$/.test(code)) continue;
+		out.push({ text: pending.trim(), line: startLine });
+		pending = '';
+		depth = 0;
+	}
+	if (pending) out.push({ text: pending.trim(), line: startLine });
+	return out;
+}
+
+function firstLiteral(args) {
+	const m = args.match(/^\s*(?::([a-zA-Z_]\w*)|["']([^"']+)["'])/);
+	return m ? (m[1] ?? m[2]) : null;
+}
+
+function optionLiteral(args, name) {
+	const re = new RegExp(`(?:\\b${name}\\s*:|:${name}\\s*=>)\\s*(?:"([^"]*)"|'([^']*)'|:([a-zA-Z_]\\w*))`);
+	const m = args.match(re);
+	return m ? (m[1] ?? m[2] ?? m[3]) : null;
+}
+
+function optionSymbols(args, name) {
+	const start = args.search(new RegExp(`(?:\\b${name}\\s*:|:${name}\\s*=>)`));
+	if (start === -1) return null;
+	const tail = args.slice(start).replace(new RegExp(`^(?:${name}\\s*:|:${name}\\s*=>)\\s*`), '');
+	const percent = tail.match(/^%i[\[(]([^\])]+)[\])]/);
+	if (percent) return percent[1].split(/\s+/).filter(Boolean);
+	const array = tail.match(/^\[([^\]]*)\]/);
+	if (array) return [...array[1].matchAll(/:([a-zA-Z_]\w*)/g)].map((m) => m[1]);
+	const one = tail.match(/^:([a-zA-Z_]\w*)/);
+	return one ? [one[1]] : null;
+}
+
+function joinRoute(...segments) {
+	const joined = segments.filter((s) => s != null && s !== '').join('/').replace(/\/+/g, '/');
+	return joined.startsWith('/') ? joined : `/${joined}`;
+}
+
+function normalizeRoute(raw) {
+	if (!raw) return '/';
+	if (raw.includes('*') || /\([^)]*\)/.test(raw) || raw.includes('#{')) return null;
+	return joinRoute(raw).replace(/:([a-zA-Z_]\w*)/g, '{$1}').replace(/\/$/, '') || '/';
+}
+
+function regularSingular(name) {
+	if (/[^a-zA-Z0-9_]/.test(name)) return null;
+	if (/ies$/.test(name)) return `${name.slice(0, -3)}y`;
+	if (/(?:ches|shes|xes|zes|sses)$/.test(name)) return name.slice(0, -2);
+	if (/s$/.test(name) && !/ss$/.test(name)) return name.slice(0, -1);
+	return null;
+}
+
+function pascal(value) {
+	return String(value).split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join('');
+}
+
+function operationIdFor(endpoint) {
+	const tuple = `${endpoint.verb}\0${endpoint.path}\0${endpoint.controllerPath}#${endpoint.action}`;
+	const suffix = crypto.createHash('sha256').update(tuple).digest('hex').slice(0, 10);
+	const controller = endpoint.controllerPath.replace(/\//g, '_').replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
+	return `rails_${endpoint.verb.toLowerCase()}_${controller}_${endpoint.action}_${suffix}`;
+}
+
+function controllerClass(controllerPath) {
+	return `${controllerPath.split('/').map(pascal).join('::')}Controller`;
+}
+
+function controllerFile(projectRoot, controllerPath) {
+	return path.join(projectRoot, 'app', 'controllers', `${controllerPath}_controller.rb`);
+}
+
+function commonBasePath(paths) {
+	if (paths.length === 0) return '/';
+	const split = paths.map((p) => p.split('/').filter(Boolean));
+	const common = [];
+	for (let i = 0; i < Math.min(...split.map((p) => p.length)); i++) {
+		if (!split.every((p) => p[i] === split[0][i]) || split[0][i].startsWith('{')) break;
+		common.push(split[0][i]);
+	}
+	return common.length ? `/${common.join('/')}` : '/';
+}
+
+function scopedController(raw, modulePrefix) {
+	const cleaned = raw.replace(/^\//, '');
+	if (!modulePrefix || cleaned.includes('/')) return cleaned;
+	return `${modulePrefix}/${cleaned}`;
+}
+
+function parseTarget(args, modulePrefix) {
+	const m = args.match(/(?:\bto\s*:|=>)\s*["']([^"']+)#([a-zA-Z_]\w*)["']/);
+	if (!m) return null;
+	return { controllerPath: scopedController(m[1], modulePrefix), action: m[2] };
+}
+
+function resourceEndpoints({ singular, actions, collectionPath, memberPath, controllerPath, line, file, label }) {
+	const declaration = { rule: `ruby-rails:${singular ? 'resource' : 'resources'}`, line, label };
+	const rows = singular
+		? [
+			['new', 'GET', joinRoute(collectionPath, 'new')], ['create', 'POST', collectionPath],
+			['show', 'GET', collectionPath], ['edit', 'GET', joinRoute(collectionPath, 'edit')],
+			['update', 'PATCH', collectionPath], ['update', 'PUT', collectionPath], ['destroy', 'DELETE', collectionPath],
+		]
+		: [
+			['index', 'GET', collectionPath], ['create', 'POST', collectionPath],
+			['new', 'GET', joinRoute(collectionPath, 'new')], ['show', 'GET', memberPath],
+			['edit', 'GET', joinRoute(memberPath, 'edit')], ['update', 'PATCH', memberPath],
+			['update', 'PUT', memberPath], ['destroy', 'DELETE', memberPath],
+		];
+	return rows.filter(([action]) => actions.has(action)).map(([action, verb, routePath]) => ({
+		verb, path: routePath, controllerPath, action, method: action, line, routeFile: file, declaration,
+	}));
+}
+
+function note(notes, file, line, kind, detail) {
+	const key = `${kind}\0${path.basename(file)}`;
+	const current = notes.get(key) ?? { kind, file, count: 0, examples: [] };
+	current.count++;
+	if (current.examples.length < 3) current.examples.push(`${file}:${line}${detail ? ` (${detail})` : ''}`);
+	notes.set(key, current);
+}
+
+function finalizeNotes(notes) {
+	return [...notes.values()].sort((a, b) => a.kind.localeCompare(b.kind) || a.file.localeCompare(b.file)).map((n) =>
+		`ruby-rails static scan skipped ${n.count} ${n.kind} declaration(s); examples: ${n.examples.join(', ')}. Re-run with --runtime-routes to ask Rails for the computed route table.`,
+	);
+}
+
+function parseStaticRouteFile(projectRoot, file) {
+	const text = fs.readFileSync(file, 'utf8');
+	const endpoints = [];
+	const notes = new Map();
+	const stack = [{ kind: 'root', pathPrefix: '', modulePrefix: '', dynamic: false }];
+	const current = () => stack[stack.length - 1];
+
+	const addExplicit = (verb, args, line, inlineContext = null) => {
+		const ctx = inlineContext ?? current();
+		if (ctx.dynamic) { note(notes, file, line, 'dynamic', verb); return; }
+		let literal = firstLiteral(args);
+		if (!literal) { note(notes, file, line, 'non-literal', verb); return; }
+		const target = parseTarget(args, ctx.modulePrefix);
+		let controllerPath = target?.controllerPath ?? null;
+		let action = target?.action ?? null;
+		const on = optionLiteral(args, 'on');
+		const resourceCtx = [...stack].reverse().find((s) => s.kind === 'resource');
+		const mode = on ?? ctx.routeMode ?? null;
+		let base = ctx.pathPrefix;
+		if (resourceCtx && (mode === 'member' || mode === 'collection')) {
+			base = mode === 'member' ? resourceCtx.memberPath : resourceCtx.collectionPath;
+			controllerPath ??= resourceCtx.controllerPath;
+			action ??= literal.replace(/^\//, '').split('/').at(-1).replace(/[^a-zA-Z0-9_]/g, '_');
+		}
+		if (!controllerPath || !action) { note(notes, file, line, 'implicit-target', `${verb} ${literal}`); return; }
+		const routePath = normalizeRoute(joinRoute(base, literal));
+		if (!routePath) { note(notes, file, line, 'dynamic-path', `${verb} ${literal}`); return; }
+		endpoints.push({ verb: verb.toUpperCase(), path: routePath, controllerPath, action, method: action, line, routeFile: file });
+	};
+
+	for (const statement of logicalStatements(text)) {
+		let src = statement.text;
+		if (!src) continue;
+		if (/^end\b/.test(src)) { if (stack.length > 1) stack.pop(); continue; }
+
+		const inline = src.match(/^(member|collection)\s*\{\s*(.+)\s*\}\s*$/);
+		if (inline) {
+			const inner = inline[2].match(/^(get|post|put|patch|delete)\b\s*(.*)$/);
+			if (inner) addExplicit(inner[1], inner[2], statement.line, { ...current(), routeMode: inline[1] });
+			else note(notes, file, statement.line, 'unsupported-inline-block', inline[1]);
+			continue;
+		}
+
+		const dynamic = /^(?:if|unless|while|until|for)\b/.test(src) || /\.each\b[\s\S]*\bdo\s*$/.test(src);
+		if (dynamic) { stack.push({ ...current(), kind: 'dynamic', dynamic: true }); continue; }
+		if (/\.routes\.draw\s+do\s*$/.test(src)) { stack.push({ ...current(), kind: 'draw' }); continue; }
+		if (/^(?:concern|concerns|draw|mount|direct|resolve|match)\b/.test(src)) {
+			note(notes, file, statement.line, 'unsupported-dsl', src.split(/\s/)[0]);
+			if (/\bdo\s*$/.test(src)) stack.push({ ...current(), kind: 'unsupported', dynamic: true });
+			continue;
+		}
+
+		const namespace = src.match(/^namespace\b\s*(.*?)(?:\s+do)?$/);
+		if (namespace && /\bdo\s*$/.test(src)) {
+			const name = firstLiteral(namespace[1]);
+			if (!name) { note(notes, file, statement.line, 'non-literal-namespace', 'namespace'); stack.push({ ...current(), kind: 'unsupported', dynamic: true }); continue; }
+			stack.push({ ...current(), kind: 'namespace', pathPrefix: joinRoute(current().pathPrefix, name), modulePrefix: [current().modulePrefix, name].filter(Boolean).join('/') });
+			continue;
+		}
+
+		const scope = src.match(/^scope\b\s*(.*?)(?:\s+do)?$/);
+		if (scope && /\bdo\s*$/.test(src)) {
+			const first = firstLiteral(scope[1]);
+			const scopePath = optionLiteral(scope[1], 'path') ?? first;
+			const scopeModule = optionLiteral(scope[1], 'module');
+			if ((scopePath && scopePath.includes('#{')) || /\bshallow\s*:\s*true/.test(scope[1])) {
+				note(notes, file, statement.line, 'dynamic-scope', 'scope');
+				stack.push({ ...current(), kind: 'unsupported', dynamic: true });
+				continue;
+			}
+			stack.push({ ...current(), kind: 'scope', pathPrefix: scopePath && scopePath !== 'nil' ? joinRoute(current().pathPrefix, scopePath) : current().pathPrefix, modulePrefix: scopeModule ? [current().modulePrefix, scopeModule].filter(Boolean).join('/') : current().modulePrefix });
+			continue;
+		}
+
+		const routeMode = src.match(/^(member|collection)\b[\s\S]*\bdo\s*$/);
+		if (routeMode) { stack.push({ ...current(), kind: routeMode[1], routeMode: routeMode[1] }); continue; }
+
+		const resource = src.match(/^(resources|resource)\b\s*(.*)$/);
+		if (resource) {
+			if (current().dynamic) { note(notes, file, statement.line, 'dynamic', resource[1]); continue; }
+			const singular = resource[1] === 'resource';
+			const args = resource[2].replace(/\s+do\s*$/, '');
+			const name = firstLiteral(args);
+			if (!name) { note(notes, file, statement.line, 'non-literal', resource[1]); continue; }
+			if (/\bshallow\s*:\s*true/.test(args) || /\bconcerns?\s*:/.test(args)) {
+				note(notes, file, statement.line, 'unsupported-resource-option', name);
+				if (/\bdo\s*$/.test(src)) stack.push({ ...current(), kind: 'unsupported', dynamic: true });
+				continue;
+			}
+			const parent = [...stack].reverse().find((s) => s.kind === 'resource');
+			if (parent && !parent.nestedPath) {
+				note(notes, file, statement.line, 'ambiguous-nested-resource', name);
+				if (/\bdo\s*$/.test(src)) stack.push({ ...current(), kind: 'unsupported', dynamic: true });
+				continue;
+			}
+			const parentBase = parent ? parent.nestedPath : current().pathPrefix;
+			const pathSegment = optionLiteral(args, 'path') ?? name;
+			const collectionPath = normalizeRoute(joinRoute(parentBase, pathSegment));
+			if (!collectionPath) { note(notes, file, statement.line, 'dynamic-path', name); continue; }
+			const paramName = optionLiteral(args, 'param') ?? 'id';
+			const memberPath = singular ? collectionPath : joinRoute(collectionPath, `{${paramName}}`);
+			const controllerName = optionLiteral(args, 'controller') ?? name;
+			const controllerPath = scopedController(controllerName, current().modulePrefix);
+			const only = optionSymbols(args, 'only');
+			const except = optionSymbols(args, 'except');
+			const actions = new Set(only ?? RESOURCE_ACTIONS);
+			for (const action of except ?? []) actions.delete(action);
+			const invalid = [...actions].filter((a) => !RESOURCE_ACTIONS.includes(a));
+			if (invalid.length) { note(notes, file, statement.line, 'unknown-resource-action', invalid.join(',')); for (const a of invalid) actions.delete(a); }
+			endpoints.push(...resourceEndpoints({ singular, actions, collectionPath, memberPath, controllerPath, line: statement.line, file, label: `${resource[1]} :${name}` }));
+			if (/\bdo\s*$/.test(src)) {
+				const parentParam = optionLiteral(args, 'param') ?? regularSingular(name);
+				const nestedPath = singular ? collectionPath : (parentParam ? joinRoute(collectionPath, `{${parentParam}_id}`) : null);
+				stack.push({ ...current(), kind: 'resource', collectionPath, memberPath, nestedPath, controllerPath, resourceName: name });
+			}
+			continue;
+		}
+
+		const explicit = src.match(/^(get|post|put|patch|delete)\b\s*(.*)$/);
+		if (explicit) { addExplicit(explicit[1], explicit[2], statement.line); continue; }
+		const root = src.match(/^root\b\s*(.*)$/);
+		if (root) {
+			const target = parseTarget(root[1], current().modulePrefix);
+			if (!target) note(notes, file, statement.line, 'implicit-target', 'root');
+			else endpoints.push({ verb: 'GET', path: joinRoute(current().pathPrefix), controllerPath: target.controllerPath, action: target.action, method: target.action, line: statement.line, routeFile: file });
+			continue;
+		}
+		if (/\bdo\s*$/.test(src)) stack.push({ ...current(), kind: 'unknown', dynamic: true });
+	}
+
+	return { endpoints, notes: finalizeNotes(notes) };
+}
+
+function parseExpandedRoutes(output, projectRoot) {
+	const routes = [];
+	for (const block of output.split(/(?=--\[ Route \d+ \]-+)/)) {
+		const field = (name) => block.match(new RegExp(`^\\s*${name}\\s*\\|\\s*(.*)$`, 'm'))?.[1]?.trim() ?? '';
+		const verbs = field('Verb').split('|').map((v) => v.trim().toUpperCase()).filter(Boolean);
+		const rawUri = field('URI').replace(/\(\.:format\)$/, '');
+		const target = field('Controller#Action').match(/^([^\s#]+)#([a-zA-Z_]\w*)/);
+		if (!target || verbs.length === 0) continue;
+		const routePath = normalizeRoute(rawUri);
+		if (!routePath) continue;
+		const controllerPath = target[1];
+		if (!fs.existsSync(controllerFile(projectRoot, controllerPath))) continue;
+		const source = field('Source Location');
+		const sourceMatch = source.match(/^(.*?):(\d+)$/);
+		for (const verb of verbs) {
+			if (!HTTP_VERBS.has(verb.toLowerCase())) continue;
+			routes.push({
+				verb, path: routePath, controllerPath, action: target[2], method: target[2],
+				line: sourceMatch ? Number(sourceMatch[2]) : null,
+				routeFile: sourceMatch && path.isAbsolute(sourceMatch[1]) ? sourceMatch[1] : path.join(projectRoot, 'config', 'routes.rb'),
+			});
+		}
+	}
+	return routes;
+}
+
+export function introspectRailsRoutes(repoRoot, projectRoot) {
+	const binRails = path.join(projectRoot, 'bin', 'rails');
+	if (!fs.existsSync(binRails)) {
+		const err = new Error(`--runtime-routes requires ${path.relative(repoRoot, binRails)}; no Rails binstub was found`);
+		err.code = 'RUNTIME_ROUTES_FAILED';
+		throw err;
+	}
+	let stdout;
+	try {
+		stdout = execFileSync(binRails, ['routes', '--expanded'], {
+			cwd: projectRoot, encoding: 'utf8', timeout: 60_000, maxBuffer: 16 * 1024 * 1024,
+			env: process.env, stdio: ['ignore', 'pipe', 'pipe'],
+		});
+	} catch (cause) {
+		const detail = cause.signal === 'SIGTERM' ? 'timed out after 60 seconds' : (cause.stderr?.toString().trim() || cause.message);
+		const err = new Error(`Rails runtime route introspection failed: ${detail}`);
+		err.code = 'RUNTIME_ROUTES_FAILED';
+		throw err;
+	}
+	const endpoints = parseExpandedRoutes(stdout, projectRoot);
+	if (endpoints.length === 0) {
+		const err = new Error('Rails runtime route introspection returned no local controller routes; refusing to replace the static route set with an empty parse');
+		err.code = 'RUNTIME_ROUTES_FAILED';
+		throw err;
+	}
+	return {
+		endpoints,
+		metadata: {
+			kind: 'rails-routes', command: ['bin/rails', 'routes', '--expanded'],
+			project_root: path.relative(repoRoot, projectRoot) || '.', rails_env: process.env.RAILS_ENV || 'development', status: 'used',
+		},
+	};
+}
+
+function extractEntities(projectRoot) {
+	const entities = [];
+	for (const file of rubyFilesUnder(projectRoot, ['app/models'])) {
+		const text = fs.readFileSync(file, 'utf8');
+		for (const match of text.matchAll(/^\s*class\s+([A-Z]\w*(?:::[A-Z]\w*)*)\s*<\s*(?:ApplicationRecord|ActiveRecord::Base)\b/gm)) {
+			if (match[1] === 'ApplicationRecord') continue; // abstract Rails base, never a resource entity
+			const after = text.slice(match.index, text.indexOf('\nend', match.index) === -1 ? text.length : text.indexOf('\nend', match.index));
+			const table = after.match(/\bself\.table_name\s*=\s*["']([^"']+)["']/)?.[1] ?? null;
+			const idField = after.match(/\bself\.primary_key\s*=\s*["']([^"']+)["']/)?.[1] ?? null;
+			entities.push({ className: match[1], table, tableSource: table ? 'explicit' : null, idField, idFieldIsUuid: null, file, line: lineNumberAt(text, match.index) });
+		}
+	}
+	return entities;
+}
+
+function endpointKey(ep) {
+	return `${ep.verb}\0${ep.path}\0${ep.controllerPath}\0${ep.action}`;
+}
+
+function buildModules(projectRoot, rawEndpoints, entities, notes) {
+	const modules = new Map();
+	const entry = (name) => {
+		if (!modules.has(name)) modules.set(name, { module: name, controllers: [], entities: [], enums: [], dtos: [] });
+		return modules.get(name);
+	};
+	const byController = new Map();
+	const seen = new Set();
+	for (const raw of rawEndpoints) {
+		const file = controllerFile(projectRoot, raw.controllerPath);
+		if (!fs.existsSync(file)) {
+			notes.push(`ruby-rails skipped ${raw.verb} ${raw.path}: local controller file ${path.relative(projectRoot, file)} was not found.`);
+			continue;
+		}
+		const key = endpointKey(raw);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		if (!byController.has(raw.controllerPath)) byController.set(raw.controllerPath, []);
+		byController.get(raw.controllerPath).push(raw);
+	}
+
+	for (const [controllerPath, rows] of [...byController.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+		rows.sort((a, b) => a.path.localeCompare(b.path) || a.verb.localeCompare(b.verb) || a.action.localeCompare(b.action));
+		const declarations = [];
+		const declarationIndexes = new Map();
+		const endpoints = rows.map((row) => {
+			let declarationIndex;
+			if (row.declaration) {
+				const dKey = `${row.routeFile}\0${row.declaration.line}\0${row.declaration.rule}`;
+				if (!declarationIndexes.has(dKey)) { declarationIndexes.set(dKey, declarations.length); declarations.push(row.declaration); }
+				declarationIndex = declarationIndexes.get(dKey);
+			}
+			return {
+				verb: row.verb, path: row.path, operationId: operationIdFor(row), operationIdSource: 'bskel-synthesized',
+				method: row.method, line: row.line,
+				...(declarationIndex !== undefined ? { declarationIndex } : {}),
+			};
+		});
+		const leaf = controllerPath.split('/').at(-1).replace(/_controller$/, '');
+		entry(leaf).controllers.push({
+			className: controllerClass(controllerPath), basePath: commonBasePath(endpoints.map((e) => e.path)),
+			operationIds: [], endpoints, file: controllerFile(projectRoot, controllerPath),
+			...(declarations.length ? { declarations } : {}),
+		});
+	}
+
+	for (const entity of entities) {
+		const leaf = entity.className.split('::').at(-1).replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+		const target = [...modules.keys()].find((name) => name === leaf || regularSingular(name) === leaf);
+		entry(target ?? '_models').entities.push(entity);
+	}
+	return [...modules.values()].sort((a, b) => a.module.localeCompare(b.module));
+}
+
+export function scanRubyRails(repoRoot, projectRoot, { runtimeRoutes = null } = {}) {
+	const discoveredRouteFiles = routeFiles(projectRoot);
+	const staticEndpoints = [];
+	const scanNotes = [];
+	for (const file of discoveredRouteFiles) {
+		const parsed = parseStaticRouteFile(projectRoot, file);
+		staticEndpoints.push(...parsed.endpoints);
+		scanNotes.push(...parsed.notes);
+	}
+
+	let endpoints = staticEndpoints;
+	if (runtimeRoutes) {
+		const staticByKey = new Map(staticEndpoints.map((ep) => [endpointKey(ep), ep]));
+		endpoints = runtimeRoutes.endpoints.map((ep) => {
+			const source = staticByKey.get(endpointKey(ep));
+			return source?.declaration ? { ...ep, declaration: source.declaration } : ep;
+		});
+		scanNotes.push('Rails runtime route introspection is point-in-time and environment-dependent; changes in untracked environment variables cannot be represented in the scan gate input hash.');
+	}
+
+	const entities = extractEntities(projectRoot);
+	const filesRead = railsReadFiles(projectRoot)
+		.map((f) => path.relative(repoRoot, f));
+	return {
+		modules: buildModules(projectRoot, endpoints, entities, scanNotes),
+		filesRead,
+		scanNotes,
+		apiSurfaceSource: runtimeRoutes
+			? 'Rails-computed route table from explicit `bin/rails routes --expanded` runtime introspection; operation ids are deterministic bskel identifiers unless reconciled with --openapi-file'
+			: 'conservative static analysis of literal Rails routes.rb DSL only; dynamic declarations are listed in unknowns and operation ids are deterministic bskel identifiers',
+		...(runtimeRoutes ? { runtimeIntrospection: runtimeRoutes.metadata } : {}),
+	};
+}
+
+export const adapter = {
+	contract: 'sbf.adapter/2',
+	id: 'ruby-rails',
+	title: 'Ruby / Rails',
+	specificity: 95,
+	confidence: 'high',
+	verificationBasis: 'production-repo',
+	capabilities: {
+		'api.operations': true,
+		'api.request-shape': false,
+		'resource.fetch': false,
+		'codegen.handles': false,
+	},
+	detect: detectRubyRailsRoot,
+	scan(repoRoot, projectRoot, options) {
+		return scanRubyRails(repoRoot, projectRoot, options);
+	},
+	introspectRoutes: introspectRailsRoutes,
+	listReadSet(repoRoot) {
+		const root = detectRubyRailsRoot(repoRoot);
+		if (!root) return [];
+		return railsReadFiles(root)
+			.map((f) => path.relative(repoRoot, f));
+	},
+	diagnostics(repoRoot) {
+		const messages = [];
+		const root = detectRubyRailsRoot(repoRoot);
+		if (!root) messages.push({ level: 'info', code: 'rails-app-not-detected', message: 'no project combined a Rails dependency, config/application.rb < Rails::Application, and config/routes.rb' });
+		if (!binaryAvailable('rg')) messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter cannot discover Rails project/source files without it and will degrade to generic-grep' });
+		messages.push({ level: 'info', code: 'runtime-routes-hint', message: '`bskel scan --runtime-routes` runs `bin/rails routes --expanded` and therefore boots the target application and its initializers; use it only for a trusted repo when static unknowns matter.' });
+		messages.push({ level: 'info', code: 'openapi-extraction-hint', message: 'Rails has no framework-native OpenAPI generator. `contract emit` works with deterministic bskel operation ids; pass an application-generated --openapi-file when the project uses rswag or another OpenAPI integration and you need source-backed schemas/security.' });
+		return messages;
+	},
+};

package/scanners/capabilities.mjs

@@ -6,7 +6,7 @@
 // D-adapter-registry in DECISIONS.md.
 export const CAPABILITIES = Object.freeze({
 	'api.operations': {
-		summary: 'endpoints carry a source-pinned, non-null operationId',
+		summary: 'endpoints carry a stable, non-null operationId (source-pinned or explicitly marked as bskel-synthesized)',
 		why: 'a contract operation must be addressable by id -- generic-grep\'s route-pattern grep never correlates one (operationId is always null by construction, see D-generic-grep-reconnaissance in DECISIONS.md)',
 	},
 	'api.request-shape': {
@@ -19,7 +19,7 @@ export const CAPABILITIES = Object.freeze({
 	},
 	'codegen.handles': {
 		summary: 'a handle codegen provider exists for this adapter\'s stack',
-		why: 'two providers exist today (java-spring, python-fastapi) -- see D-handles-providers (G4) in DECISIONS.md; a stack without one still fails this capability honestly rather than pretending',
+		why: 'three providers exist today (java-spring, python-fastapi, typescript-express) -- see D-handles-providers (G4) and D-typescript-express-provider in DECISIONS.md; a stack without one still fails this capability honestly rather than pretending',
 	},
 });
 

package/scanners/index.mjs

@@ -187,7 +187,7 @@ export function computeDbDrift(liveTables, relatedModules) {
 // -- bin/bskel.mjs computes it once via lib/doctor.mjs's binaryAvailable('rg') and hands it in as
 // plain data. Defaults to `true` so every existing call site (this whole test suite included)
 // stays byte-for-byte unchanged.
-export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, adapters = ADAPTERS, rgAvailable = true }) {
+export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, adapters = ADAPTERS, rgAvailable = true, runtimeRoutes = false }) {
 	const detections = adapters
 		.map((a) => ({ a, d: a.detect(repoRoot) }))
 		.filter(({ d }) => d != null)
@@ -213,7 +213,16 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	}
 
 	const { a: chosen, d: detection } = detections[0];
-	const result = chosen.scan(repoRoot, detection);
+	let runtimeRouteSnapshot = null;
+	if (runtimeRoutes) {
+		if (typeof chosen.introspectRoutes !== 'function') {
+			const err = new Error(`--runtime-routes is not supported by the detected ${chosen.id} adapter`);
+			err.code = 'RUNTIME_ROUTES_UNSUPPORTED';
+			throw err;
+		}
+		runtimeRouteSnapshot = chosen.introspectRoutes(repoRoot, detection);
+	}
+	const result = chosen.scan(repoRoot, detection, { runtimeRoutes: runtimeRouteSnapshot });
 	const adapter = chosen.id;
 	const confidence = chosen.confidence;
 	const modules = result.modules;
@@ -222,6 +231,8 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	// unknowns[] -- optional (`?? []`) so an adapter that doesn't populate it degrades to "nothing
 	// to report" rather than throwing, the same discipline apiSurfaceSource/filesRead already use.
 	const repositoryResourceNotes = result.repositoryResourceNotes ?? [];
+	const scanNotes = result.scanNotes ?? [];
+	const runtimeIntrospection = result.runtimeIntrospection ?? null;
 	const apiSurfaceSource = result.apiSurfaceSource ?? DEFAULT_API_SURFACE_SOURCE;
 	// S2 (D-gate-precision, continued): the adapter's own real read-set, persisted so
 	// lib/gate-definitions.mjs's `scan` gate can hash it for a precise staleness token instead of
@@ -311,6 +322,9 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	if (repositoryResourceNotes.length > 0) {
 		unknowns.push(...repositoryResourceNotes);
 	}
+	if (scanNotes.length > 0) {
+		unknowns.push(...scanNotes);
+	}
 	// A1 §7: this scan can't correct a global path prefix (only --openapi-file's real-document
 	// reconciliation can, see D-openapi-reconciliation) -- but it CAN tell a user who doesn't know
 	// that flag exists that the defect is likely present, before they ever emit a wrong contract.
@@ -335,6 +349,7 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 		verdict,
 		rg_available: rgAvailable,
 		path_prefix_signals: pathPrefixSignals,
+		...(runtimeIntrospection ? { runtime_introspection: runtimeIntrospection } : {}),
 		related_modules: relatedModules,
 		collisions,
 		unknowns,

package/scanners/registry.mjs

@@ -81,7 +81,7 @@ async function loadOneAdapter(file, schema) {
 
 	// Validate only the JSON-shaped fields -- detect/scan/diagnostics/listReadSet are functions,
 	// which JSON Schema has no vocabulary for; checked separately below.
-	const { detect, scan, diagnostics, listReadSet, ...data } = descriptor;
+	const { detect, scan, diagnostics, listReadSet, introspectRoutes, ...data } = descriptor;
 	const validateFn = ajv().getSchema(schema.$id) ?? ajv().compile(schema);
 	if (!validateFn(data)) {
 		const details = (validateFn.errors ?? []).map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ');
@@ -101,6 +101,9 @@ async function loadOneAdapter(file, schema) {
 	if (descriptor.listReadSet !== undefined && typeof descriptor.listReadSet !== 'function') {
 		return { error: { file, message: 'adapter.listReadSet, if present, must be a function' } };
 	}
+	if (descriptor.introspectRoutes !== undefined && typeof descriptor.introspectRoutes !== 'function') {
+		return { error: { file, message: 'adapter.introspectRoutes, if present, must be a function' } };
+	}
 	return { adapter: descriptor };
 }
 

package/scanners/render.mjs

@@ -47,6 +47,9 @@ export function renderScanMarkdown(report) {
 	lines.push(`**Terms**: ${report.terms.join(', ') || '(none)'}`);
 	lines.push(`**Adapter**: ${report.adapter} (confidence: ${report.confidence})`);
 	lines.push(`**API surface source**: ${report.api_surface_source}`);
+	if (report.runtime_introspection) {
+		lines.push(`**Runtime routes**: ${report.runtime_introspection.command.join(' ')} (${report.runtime_introspection.rails_env}, project ${report.runtime_introspection.project_root})`);
+	}
 	lines.push(`**Verdict**: \`${report.verdict}\``);
 	lines.push('');
 

package/scanners/text-util.mjs

@@ -17,9 +17,12 @@ export function lineNumberAt(text, index) {
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 
-export function listRgFiles(dir, globs, excludeGlobs = []) {
+export function listRgFiles(dir, globs, excludeGlobs = [], execFn = execFileSync) {
 	try {
-		const out = execFileSync('rg', ['--files', ...globs.flatMap((g) => ['-g', g]), ...excludeGlobs.flatMap((g) => ['-g', g]), dir], { encoding: 'utf8' });
+		// A production Rails monorepo (Discourse) emits >1 MiB of paths for `-g '*.rb'`.
+		// Node's default execFileSync buffer then throws ENOBUFS, which the intentional "no files"
+		// catch below cannot distinguish and used to turn the entire scan into an empty result.
+		const out = execFn('rg', ['--files', ...globs.flatMap((g) => ['-g', g]), ...excludeGlobs.flatMap((g) => ['-g', g]), dir], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
 		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

package/schemas/oracle-manifest.schema.json

@@ -11,7 +11,7 @@
     "adapters": {
       "type": "object",
       "propertyNames": {
-        "enum": ["java-spring", "python-fastapi", "typescript-express", "javascript-express", "generic-grep"]
+        "enum": ["java-spring", "ruby-rails", "python-fastapi", "typescript-express", "javascript-express", "generic-grep"]
       },
       "additionalProperties": {
         "type": "array",

package/schemas/scan-report.schema.json

@@ -18,6 +18,18 @@
       "type": "boolean"
     },
     "path_prefix_signals": { "type": "array" },
+    "runtime_introspection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "command", "project_root", "rails_env", "status"],
+      "properties": {
+        "kind": { "const": "rails-routes" },
+        "command": { "type": "array", "items": { "type": "string" } },
+        "project_root": { "type": "string" },
+        "rails_env": { "type": "string" },
+        "status": { "const": "used" }
+      }
+    },
     "related_modules": {
       "type": "array",
       "items": {