backend-skeleton 1.0.0-beta.1

package/scanners/index.mjs

@@ -0,0 +1,281 @@
+import { ADAPTERS, LOAD_ERRORS } from './registry.mjs';
+
+// D-scanner-evidence (CATALOG.md's D3 -- NOT the same as this file's own "D3" comment below,
+// which is this repo's internal DECISIONS.md numbering for something unrelated; see the
+// A2/A3 precedent in CATALOG.md for this exact collision class): weight per evidence signal -- the exact 8 values scoreModule() always
+// used, now named and shared between evidence collection and score summation instead of being
+// scattered `score += N` literals.
+const SIGNAL_WEIGHTS = Object.freeze({
+	module_name: 10,
+	controller_class: 6,
+	controller_path: 5,
+	endpoint_path: 5,
+	endpoint_operation_id: 5,
+	entity_table: 8,
+	entity_class: 6,
+	enum_name: 3,
+});
+
+// D-scanner-evidence: caps how many matches of the SAME signal type contribute to a module's score -- without
+// this, a controller with many endpoints inflates score linearly regardless of real relevance
+// (generic-grep.mjs already fixed exactly this class of bug once, for className-per-route; this
+// closes the same gap for endpoint_path/endpoint_operation_id, which were still uncapped). Every
+// match still appears in the evidence array (`counted:false` beyond the cap) -- capping affects
+// scoring, not transparency. Value chosen empirically, not guessed: validated against
+// Team-IZ-Backend (organization/curriculum modules) to confirm every previously-correct verdict
+// still holds at this value -- see D-scanner-evidence in DECISIONS.md for the sweep.
+const CAP_PER_SIGNAL = 5;
+
+// D-scanner-evidence: splits on non-alphanumeric runs AND camelCase boundaries (lower->upper, and an uppercase
+// run's last letter -> Uppercase+lowercase, so "APIController" -> "API","Controller" not
+// "APIController" whole) -- the SAME function handles both identifiers (className, no separators,
+// relies on camelCase splitting) and paths (basePath/endpoint path, no camelCase, relies on
+// separator splitting) correctly, since each just exercises the half of the regex it needs.
+const CAMEL_BOUNDARY_RE = /([a-z0-9])([A-Z])|([A-Z]+)([A-Z][a-z])/g;
+
+export function tokenize(s) {
+	if (!s) return [];
+	const spaced = String(s).replace(CAMEL_BOUNDARY_RE, (_, a, b, c, d) => (a ? `${a} ${b}` : `${c} ${d}`));
+	return spaced.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((t) => t.toLowerCase());
+}
+
+// A1 §7 (unchanged): the exact default string previously inlined below -- kept as a module
+// constant so an adapter can override it via `result.apiSurfaceSource` without this file needing
+// to know which adapters exist. Neither shipped adapter overrides it today, so output is
+// byte-identical to before G1.
+const DEFAULT_API_SURFACE_SOURCE = 'source-annotations only (this scan does not check for a committed ' +
+	'OpenAPI document -- if one is generated by the build, pass it via --openapi-file to ' +
+	'`contract emit`)';
+
+// D3 (see DECISIONS.md): verdict drives a disposition state machine, not an agent question.
+// A module scores >= COLLISION_THRESHOLD only when it's a strong, multi-signal match (module
+// name + controller/table/path/operationId overlap) -- e.g. scanning Team-IZ-Backend for
+// "organization" scores the `organization` module's module-name match (10) alone at the
+// threshold, before even counting its controller/table/path hits.
+const COLLISION_THRESHOLD = 10;
+
+// D-scanner-evidence: `termTokens` matches `textTokens` if it appears as a CONTIGUOUS
+// subsequence, comparing token-by-token with a bidirectional prefix check (not exact equality --
+// "organization" must still match the token "organizations", a real plural-form case the old
+// substring matcher supported by accident). This replaces the old whole-string, un-tokenized
+// `t.includes(nt) || nt.includes(t)` -- the catalog's "symmetric substring matching" complaint --
+// which let a short piece of text match anywhere inside an unrelated long term, or a short term
+// match anywhere inside an unrelated identifier, crossing real word boundaries either way (e.g.
+// term "man" matching inside the token "management" is still possible here since it's a real
+// prefix of that ONE token, but term "man" can no longer match by spanning from the tail of one
+// word into the head of the next, the way whole-string substring search allowed).
+function tokensMatch(termTokens, textTokens) {
+	if (termTokens.length === 0 || termTokens.length > textTokens.length) return false;
+	for (let start = 0; start <= textTokens.length - termTokens.length; start++) {
+		let allMatch = true;
+		for (let i = 0; i < termTokens.length; i++) {
+			const tt = termTokens[i];
+			const xt = textTokens[start + i];
+			if (!(xt.startsWith(tt) || tt.startsWith(xt))) { allMatch = false; break; }
+		}
+		if (allMatch) return true;
+	}
+	return false;
+}
+
+// Returns every term (not just whether ANY matched) that matches `text` -- D-scanner-evidence
+// needs one evidence record per matching term, not just a boolean.
+function matchingTerms(text, terms) {
+	const textTokens = tokenize(text);
+	if (textTokens.length === 0) return [];
+	return terms.filter((term) => tokensMatch(tokenize(term), textTokens));
+}
+
+// D-scanner-evidence: caps PER SIGNAL TYPE at collection time, not by collecting everything and
+// filtering afterward -- found live, not anticipated: collecting every raw match first (a
+// controller with 600 endpoints all matching one term produces 1200 evidence records for that
+// ONE module) pushed a real scan report past Node's default 1MB `execFileSync` buffer, crashing
+// the exact >64KB-report regression test this codebase already had (see D-process-exit-audit's
+// pipe-truncation history in DECISIONS.md -- this is the same failure class, a different cause).
+// Capping during collection keeps report size bounded regardless of repo size, and every
+// recorded entry always counts toward score (no separate `counted` flag needed) -- signals that
+// hit the cap are named in `cappedSignals` (one string per module, not one flag per entry) so
+// `bskel scan explain` can still say "N further widget-path matches exist, not shown" without an
+// unbounded per-entry record for each of them.
+class EvidenceCollector {
+	constructor() {
+		this.evidence = [];
+		this.counts = new Map();
+		this.cappedSignals = new Set();
+	}
+
+	// Encounter order is already deterministic here without a separate sort step: callers walk
+	// controllers/entities/enums in the adapter's own already-sorted (O6: rg --files sorted) file
+	// order, endpoints in document order within one file, and terms in the user's own --terms
+	// order -- the same ordering scoreModule() always scored in.
+	add(signal, term, value, file, line) {
+		const count = (this.counts.get(signal) ?? 0) + 1;
+		this.counts.set(signal, count);
+		if (count > CAP_PER_SIGNAL) {
+			this.cappedSignals.add(signal);
+			return;
+		}
+		this.evidence.push({ signal, term, value, weight: SIGNAL_WEIGHTS[signal], file, line: line ?? null });
+	}
+}
+
+// D-scanner-evidence: walks every signal-bearing field exactly once, in the same order
+// scoreModule() always scored them in.
+function collectEvidence(mod, terms) {
+	const c = new EvidenceCollector();
+	for (const term of matchingTerms(mod.module, terms)) c.add('module_name', term, mod.module, null, null);
+	for (const controller of mod.controllers) {
+		for (const term of matchingTerms(controller.className, terms)) c.add('controller_class', term, controller.className, controller.file, controller.line);
+		for (const term of matchingTerms(controller.basePath, terms)) c.add('controller_path', term, controller.basePath, controller.file, controller.line);
+		for (const ep of controller.endpoints) {
+			for (const term of matchingTerms(ep.path, terms)) c.add('endpoint_path', term, ep.path, controller.file, ep.line);
+			for (const term of matchingTerms(ep.operationId, terms)) c.add('endpoint_operation_id', term, ep.operationId, controller.file, ep.line);
+		}
+	}
+	for (const e of mod.entities) {
+		for (const term of matchingTerms(e.table, terms)) c.add('entity_table', term, e.table, e.file, e.line);
+		for (const term of matchingTerms(e.className, terms)) c.add('entity_class', term, e.className, e.file, e.line);
+	}
+	for (const en of mod.enums) {
+		for (const term of matchingTerms(en.name, terms)) c.add('enum_name', term, en.name, en.file, en.line);
+	}
+	return c;
+}
+
+export function scoreModule(mod, terms) {
+	const c = collectEvidence(mod, terms);
+	const score = c.evidence.reduce((sum, e) => sum + e.weight, 0);
+	return { score, evidence: c.evidence, cappedSignals: [...c.cappedSignals].sort() };
+}
+
+// A4 (D-db-schema-plane): case-insensitive comparison against every already-scanned entity's own
+// `.table` field -- tables the live DB has but no source entity declares, and entities whose
+// declared table isn't found live, both become plain-string `unknowns` entries (same shape every
+// other unknown in this report already uses), never a blocking verdict change. This is the
+// concrete "reveal live drift" value CATALOG.md's A4 Why names.
+export function computeDbDrift(liveTables, relatedModules) {
+	const liveNames = new Set(liveTables.map((t) => t.name.toLowerCase()));
+	const declaredTables = new Map(); // lowercased table name -> {module, entity}
+	for (const m of relatedModules) {
+		for (const e of m.entities ?? []) {
+			if (e.table) declaredTables.set(e.table.toLowerCase(), { module: m.module, entity: e.className });
+		}
+	}
+
+	const findings = [];
+	for (const name of liveNames) {
+		if (!declaredTables.has(name)) findings.push(`live DB table "${name}" has no matching source entity in any scanned module (Plane C drift)`);
+	}
+	for (const [table, { module, entity }] of declaredTables) {
+		if (!liveNames.has(table)) findings.push(`entity ${entity} (module "${module}") declares table "${table}", but it was not found in the live DB (Plane C drift)`);
+	}
+	return findings;
+}
+
+// G1: adapter dispatch, replacing the previous hardcoded two-branch if/else. `adapters` is
+// injectable (defaults to the real zero-registration registry) purely as a test seam for
+// arbitration/ambiguity tests -- every real caller gets the default. See D-adapter-registry in
+// DECISIONS.md.
+//
+// A4: `dbSchema` (`{migrations, live}` or null) is computed by the CALLER, not fetched here --
+// env var resolution and the live DB connection itself are CLI-boundary concerns (matching how
+// every other env-var-driven input in this codebase is resolved at the bin/bskel.mjs layer, never
+// inside a "pure" lib/scanner function), and keeps this function synchronous (Plane C's real I/O
+// is `await`ed by the caller before ever calling this).
+export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, adapters = ADAPTERS }) {
+	const detections = adapters
+		.map((a) => ({ a, d: a.detect(repoRoot) }))
+		.filter(({ d }) => d != null)
+		// Not relying on the caller to have pre-sorted `adapters` -- specificity is the sole
+		// source of truth for arbitration, computed here regardless of input order.
+		.sort((x, y) => y.a.specificity - x.a.specificity || x.a.id.localeCompare(y.a.id));
+
+	if (detections.length === 0) {
+		throw new Error(
+			`no scanner adapter detected this repo -- tried: ${adapters.map((a) => a.id).join(', ') || '(no adapters loaded)'}` +
+			`${LOAD_ERRORS.length > 0 ? `; ${LOAD_ERRORS.length} adapter(s) failed to load, see \`bskel doctor\`` : ''}`,
+		);
+	}
+	const topSpecificity = detections[0].a.specificity;
+	const tiedAtTop = detections.filter(({ a }) => a.specificity === topSpecificity);
+	if (tiedAtTop.length > 1) {
+		// O6-style refusal: when it's genuinely ambiguous, name every candidate and stop, rather
+		// than silently picking one (same principle as handles/emit.mjs's detectBasePackage()).
+		throw new Error(
+			`ambiguous adapter selection -- ${tiedAtTop.map(({ a }) => a.id).join(', ')} all detected this repo at ` +
+			`specificity ${topSpecificity}. Give one a higher specificity, or make its detect() more precise.`,
+		);
+	}
+
+	const { a: chosen, d: detection } = detections[0];
+	const result = chosen.scan(repoRoot, detection);
+	const adapter = chosen.id;
+	const confidence = chosen.confidence;
+	const modules = result.modules;
+	const pathPrefixSignals = result.pathPrefixSignals ?? [];
+	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
+	// a repo-wide head_sha proxy. Optional (`?? []`) so an adapter that doesn't populate it (a
+	// third-party adapter written before this existed) degrades to "no source-file inputs" rather
+	// than crashing -- the gate token still falls back to hashing the report itself.
+	const filesRead = result.filesRead ?? [];
+
+	// O6: score alone isn't a deterministic sort key -- two modules tying on score fall back to
+	// whatever order they were already in, which traces back to non-deterministic rg discovery
+	// order in the adapters above (mitigated there too, but a second determinism layer here is
+	// cheap and doesn't depend on every adapter getting it right). Module name is a stable,
+	// meaningful secondary key.
+	const scored = modules
+		.map((m) => {
+			const { score, evidence, cappedSignals } = scoreModule(m, terms);
+			return { ...m, score, evidence, capped_signals: cappedSignals };
+		})
+		.sort((a, b) => b.score - a.score || a.module.localeCompare(b.module));
+
+	const relatedModules = scored.filter((m) => m.score > 0);
+	const collisions = relatedModules.filter((m) => m.score >= COLLISION_THRESHOLD);
+
+	let verdict = 'greenfield';
+	if (collisions.length > 0) verdict = 'collision';
+	else if (relatedModules.length > 0) verdict = 'adjacent';
+
+	const unknowns = [];
+	if (!includeDb) {
+		unknowns.push('DB not scanned (Plane C is opt-in via --db --database-url-env <NAME>) -- pass --db to scan migration files, add --database-url-env for live introspection too. See A4 in CATALOG.md.');
+	} else if (!dbSchema?.live) {
+		unknowns.push('DB not live-introspected (Plane C needs --database-url-env <NAME> in addition to --db) -- migration files only, no live drift check performed.');
+	}
+	if (dbSchema?.live) {
+		unknowns.push(...computeDbDrift(dbSchema.live.tables, relatedModules));
+	}
+	// 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.
+	if (pathPrefixSignals.length > 0) {
+		const detail = pathPrefixSignals
+			.map((s) => `${s.kind} in ${s.file}${s.prefix ? ` (prefix "${s.prefix}")` : s.pattern ? ` (pattern "${s.pattern}")` : ''}`)
+			.join('; ');
+		unknowns.push(
+			`this repo applies a global path prefix outside controller source (${detail}) -- contract ` +
+			'paths built from source annotations alone (no --openapi-file) will be missing it. Generate ' +
+			'a real OpenAPI document and pass it to `bskel contract emit --openapi-file <path>`. See ' +
+			'D-openapi-reconciliation in DECISIONS.md.',
+		);
+	}
+
+	return {
+		schema: 'sbf.scan-report/1',
+		terms,
+		adapter,
+		confidence,
+		api_surface_source: apiSurfaceSource,
+		verdict,
+		path_prefix_signals: pathPrefixSignals,
+		related_modules: relatedModules,
+		collisions,
+		unknowns,
+		files_read: filesRead,
+		...(dbSchema ? { db_schema: dbSchema } : {}),
+	};
+}

package/scanners/registry.mjs

@@ -0,0 +1,130 @@
+// G1: zero-registration adapter discovery -- mirrors stack/apply.mjs's listCatalogChoices()/
+// loadCatalogEntry() (D7 in DECISIONS.md), with one unavoidable difference: a stack catalog entry
+// is pure YAML data, but a scanner adapter is CODE -- dropping a file here executes it. That is
+// acceptable because scanners/adapters/ lives inside this skill's own source, at the same trust
+// level as the rest of it.
+//
+// SECURITY: `loadAdapters({adaptersDir})` below is a test seam ONLY. Never wire it to a CLI flag
+// or an environment variable -- doing so would turn "which directory of JS gets executed" into
+// user-controllable input. See D-adapter-registry in DECISIONS.md.
+//
+// SYNC: `runScan()`/`cmdScan()`/`main()` in bin/bskel.mjs are all synchronous, and existing tests
+// (test/scan.test.mjs, test/contract.test.mjs) call `runScan` synchronously. `import()` is
+// inherently async, so adapter loading happens via a top-level await here instead of forcing
+// every caller of `runScan` to become async. `scanners/index.mjs` statically imports the
+// constants exported below -- Node resolves this module's top-level await as part of resolving
+// that static import, before any of index.mjs's own top-level code runs, so `runScan` itself
+// stays fully synchronous. No cycle risk: this module imports nothing from scanners/index.mjs,
+// and no adapter imports anything from this module.
+//
+// BUNDLER CAVEAT: dynamic `import()` over a `readdirSync` result is invisible to bundlers. There
+// is no build step in this project today (bin/bskel.mjs runs straight from source, no `build`
+// script in package.json), so this costs nothing now -- but adding esbuild/ncc/etc. later would
+// silently produce a zero-adapter registry. Worth remembering if a build step is ever added.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+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';
+
+let _ajv = null;
+function ajv() {
+	if (!_ajv) _ajv = new Ajv2020({ allErrors: true, strict: false });
+	return _ajv;
+}
+
+function loadAdapterSchema() {
+	return JSON.parse(fs.readFileSync(path.join(SCHEMAS_ROOT, 'adapter.schema.json'), 'utf8'));
+}
+
+// O6-style determinism: readdirSync has no cross-platform ordering guarantee either -- `.sort()`
+// on the filename list, same discipline as scanners/adapters/*.mjs's own `rg --files` fix.
+//
+// Filtered by NAME, not `withFileTypes()` + `isFile()` -- `isFile()` is false for a symlink, and
+// this skill is itself symlinked into `~/.claude/skills` (see D0 in DECISIONS.md), so a
+// symlinked adapter file is a plausible real shape, not a hypothetical. `_`/`.`-prefixed files
+// are the shared-helper convention (mirrors stack/apply.mjs's own catalog dir filtering) and are
+// silently skipped, not treated as malformed adapters.
+function candidateFiles(dir) {
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir)
+		.filter((name) => name.endsWith('.mjs') && !name.startsWith('_') && !name.startsWith('.'))
+		.sort()
+		.map((name) => path.join(dir, name));
+}
+
+async function loadOneAdapter(file, schema) {
+	const id = path.basename(file, '.mjs');
+	let mod;
+	try {
+		mod = await import(pathToFileURL(file).href);
+	} catch (err) {
+		return { error: { file, message: `failed to load: ${err.message}` } };
+	}
+	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' } };
+	}
+	if (descriptor.contract !== SUPPORTED_CONTRACT) {
+		return { error: { file, message: `declares contract "${descriptor.contract}" -- this build only understands "${SUPPORTED_CONTRACT}"` } };
+	}
+	if (descriptor.id !== id) {
+		return { error: { file, message: `adapter.id "${descriptor.id}" must equal its filename "${id}"` } };
+	}
+
+	// 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 validateFn = ajv().getSchema(schema.$id) ?? ajv().compile(schema);
+	if (!validateFn(data)) {
+		const details = (validateFn.errors ?? []).map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ');
+		return { error: { file, message: `does not match schemas/adapter.schema.json: ${details}` } };
+	}
+	for (const fnName of ['detect', 'scan']) {
+		if (typeof descriptor[fnName] !== 'function') {
+			return { error: { file, message: `adapter.${fnName} must be a function` } };
+		}
+	}
+	if (descriptor.diagnostics !== undefined && typeof descriptor.diagnostics !== 'function') {
+		return { error: { file, message: 'adapter.diagnostics, if present, must be a function' } };
+	}
+	// S2 (D-gate-precision, continued): optional -- an adapter that doesn't implement this just
+	// means lib/gate-definitions.mjs's `scan` gate falls back to a coarser staleness token for
+	// that adapter, never a crash. Every first-party adapter implements it.
+	if (descriptor.listReadSet !== undefined && typeof descriptor.listReadSet !== 'function') {
+		return { error: { file, message: 'adapter.listReadSet, if present, must be a function' } };
+	}
+	return { adapter: descriptor };
+}
+
+// Exported for the registry's own unit tests and for `bskel doctor`'s LOAD_ERRORS listing. A
+// broken adapter file must not brick every `bskel` command (this module is imported at process
+// start, before `main()` even parses argv) -- so loading is per-file try/catch: the adapters that
+// did load are still usable, and every failure is collected, never silently dropped.
+export async function loadAdapters({ adaptersDir = ADAPTERS_DIR } = {}) {
+	const schema = loadAdapterSchema();
+	const adapters = [];
+	const errors = [];
+	for (const file of candidateFiles(adaptersDir)) {
+		const result = await loadOneAdapter(file, schema);
+		if (result.error) errors.push(result.error);
+		else adapters.push(result.adapter);
+	}
+	// Arbitration order for scanners/index.mjs's dispatch loop: higher specificity first, id as a
+	// stable tiebreak. This is a display/iteration convenience only -- genuine ambiguity (two
+	// adapters at the SAME specificity both detecting the same repo) is caught at dispatch time in
+	// runScan(), not here, since detect() needs a real repoRoot to evaluate.
+	adapters.sort((a, b) => b.specificity - a.specificity || a.id.localeCompare(b.id));
+	return { adapters, errors };
+}
+
+export function adapterById(adapters, id) {
+	return adapters.find((a) => a.id === id) ?? null;
+}
+
+// Top-level await: see the SYNC note in the module header.
+export const { adapters: ADAPTERS, errors: LOAD_ERRORS } = await loadAdapters();

package/scanners/render.mjs

@@ -0,0 +1,136 @@
+// D-scanner-evidence: fixed presentation order (matches scanners/index.mjs's own SIGNAL_WEIGHTS
+// declaration order) rather than whatever order evidence happens to appear in -- duplicated here
+// as literal strings rather than imported, keeping this file a pure presentation layer over a
+// plain report object (its existing convention; scanners/index.mjs never imports render.mjs
+// either, no dependency direction to preserve either way).
+const SIGNAL_ORDER = [
+	'module_name', 'controller_class', 'controller_path',
+	'endpoint_path', 'endpoint_operation_id',
+	'entity_table', 'entity_class', 'enum_name',
+];
+
+// `bskel scan explain <module>` -- one module's full evidence breakdown, grouped by signal type,
+// with a running weight subtotal per group so the sum visibly reconciles with `mod.score`.
+export function renderScanExplain(mod) {
+	const lines = [`# scan explain: \`${mod.module}\` (score: ${mod.score})`, ''];
+	const bySignal = new Map();
+	for (const e of mod.evidence ?? []) {
+		if (!bySignal.has(e.signal)) bySignal.set(e.signal, []);
+		bySignal.get(e.signal).push(e);
+	}
+	if (bySignal.size === 0) {
+		lines.push('No evidence recorded -- this module scored 0.');
+		lines.push('');
+	}
+	for (const signal of SIGNAL_ORDER) {
+		const entries = bySignal.get(signal);
+		if (!entries || entries.length === 0) continue;
+		const subtotal = entries.reduce((sum, e) => sum + e.weight, 0);
+		lines.push(`## ${signal} (weight ${entries[0].weight} each, subtotal ${subtotal})`);
+		for (const e of entries) {
+			const where = e.file ? ` (${e.file}${e.line ? `:${e.line}` : ''})` : '';
+			lines.push(`- term \`${e.term}\` matched \`${e.value}\`${where}`);
+		}
+		lines.push('');
+	}
+	if ((mod.capped_signals ?? []).length > 0) {
+		lines.push(`**Capped**: ${mod.capped_signals.join(', ')} had more raw matches than shown above -- score still reflects every entry listed, additional matches beyond the cap did not add further weight.`);
+		lines.push('');
+	}
+	return `${lines.join('\n')}\n`;
+}
+
+export function renderScanMarkdown(report) {
+	const lines = [];
+	lines.push(`# Brownfield scan${report.feature_id ? `: ${report.feature_id}` : ''}`);
+	lines.push('');
+	lines.push(`**Terms**: ${report.terms.join(', ') || '(none)'}`);
+	lines.push(`**Adapter**: ${report.adapter} (confidence: ${report.confidence})`);
+	lines.push(`**API surface source**: ${report.api_surface_source}`);
+	lines.push(`**Verdict**: \`${report.verdict}\``);
+	lines.push('');
+
+	if (report.related_modules.length === 0) {
+		lines.push('No related modules found -- greenfield for these terms.');
+	} else {
+		lines.push('## Related modules');
+		lines.push('');
+		for (const mod of report.related_modules) {
+			lines.push(`### \`${mod.module}\` (score: ${mod.score} -- run \`bskel scan explain ${mod.module}\` for the evidence breakdown)`);
+			for (const c of mod.controllers) {
+				lines.push(`- Controller \`${c.className}\` (base path \`${c.basePath}\`), ${c.endpoints.length} endpoint(s):`);
+				for (const ep of c.endpoints) {
+					lines.push(`  - \`${ep.verb} ${ep.path}\` -- operationId \`${ep.operationId ?? '(unmatched)'}\` (\`${ep.method}\`)`);
+				}
+			}
+			for (const e of mod.entities) {
+				lines.push(`- Entity \`${e.className}\` -> table \`${e.table ?? '(unknown)'}\`, PK field \`${e.idField ?? '(unknown)'}\``);
+			}
+			for (const en of mod.enums) {
+				lines.push(`- Enum \`${en.name}\`: ${en.constants.join(', ')}`);
+			}
+			if (mod.dtos.length > 0) {
+				lines.push(`- DTOs: ${mod.dtos.join(', ')}`);
+			}
+			lines.push('');
+		}
+	}
+
+	// A4 (D-db-schema-plane): only present when --db was passed -- drift findings already land in
+	// `unknowns` (rendered above/below depending on source order), this section is just the raw
+	// table/column inventory for a human skimming the markdown without --json.
+	if (report.db_schema) {
+		lines.push('## Database schema (Plane A/C)');
+		const { migrations, live } = report.db_schema;
+		lines.push(`- Migrations: ${migrations.tool === 'none' ? 'none found' : `${migrations.tool}, ${migrations.files.length} file(s), ${migrations.tables.length} table reference(s)`}`);
+		if (live) {
+			lines.push(`- Live schema \`${live.schema}\`: ${live.tables.length} table(s), hash \`${live.schema_hash.slice(0, 12)}\``);
+			for (const t of live.tables) lines.push(`  - \`${t.name}\` (${t.columns.length} column(s))`);
+		} else {
+			lines.push('- Live schema: not introspected (pass --database-url-env for Plane C)');
+		}
+		lines.push('');
+	}
+
+	if (report.unknowns.length > 0) {
+		lines.push('## Unknowns');
+		for (const u of report.unknowns) lines.push(`- ${u}`);
+		lines.push('');
+	}
+
+	if (report.disposition) {
+		lines.push('## Disposition');
+		lines.push('');
+		lines.push(`**Mode**: \`${report.disposition.mode}\` (recorded ${report.disposition.at})`);
+		lines.push('');
+		lines.push(report.disposition.note || '(no note provided)');
+		lines.push('');
+	}
+
+	return `${lines.join('\n')}\n`;
+}
+
+export function renderPlanConstraints(report) {
+	if (!report.disposition) return null;
+	const { mode, note } = report.disposition;
+	const lines = [`# Plan constraints (from brownfield-scan disposition: ${mode})`, ''];
+
+	const modeInstructions = {
+		reuse: 'Plan MUST NOT create new entities/controllers/endpoints for the modules listed below. Restrict scope to regression tests and documentation corrections only.',
+		extend: 'Plan may ADD to the modules listed below, but every new field/endpoint must state why the existing one is insufficient. Do not duplicate existing functionality.',
+		replace: 'Plan replaces functionality in the modules listed below. Requires --breaking-approved to have been passed to `scan disposition`. Must include an explicit deprecation section for what is being replaced.',
+		parallel: 'Plan introduces a new, separately-named module alongside the ones listed below. Re-run `bskel scan` against the new module name before implementing to confirm no further collision.',
+	};
+	lines.push(modeInstructions[mode] ?? '');
+	lines.push('');
+	if (note) {
+		lines.push('## Human note');
+		lines.push(note);
+		lines.push('');
+	}
+	lines.push('## Existing modules this disposition applies to');
+	for (const mod of report.related_modules) {
+		lines.push(`- \`${mod.module}\` (score ${mod.score}) -- see brownfield-scan.md for full detail`);
+	}
+	return `${lines.join('\n')}\n`;
+}

package/scanners/text-util.mjs

@@ -0,0 +1,8 @@
+// D3 (D-scanner-evidence): extracted from python-fastapi.mjs/generic-grep.mjs, which each had
+// their own copy of this exact function -- java-spring.mjs needs the same thing now that D3
+// requires every adapter to track a line number per evidence-bearing match, not just endpoints.
+export function lineNumberAt(text, index) {
+	let line = 1;
+	for (let i = 0; i < index; i++) if (text[i] === '\n') line++;
+	return line;
+}

package/schemas/adapter.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:adapter:1",
+  "title": "backend-skeleton scanner adapter descriptor",
+  "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"],
+  "properties": {
+    "contract": { "const": "sbf.adapter/1" },
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "title": { "type": "string" },
+    "specificity": { "type": "number" },
+    "confidence": { "enum": ["high", "low"] },
+    "capabilities": {
+      "type": "object",
+      "propertyNames": {
+        "enum": ["api.operations", "api.request-shape", "resource.fetch", "codegen.handles"]
+      },
+      "additionalProperties": { "type": "boolean" }
+    }
+  }
+}

package/schemas/agent-envelope.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:envelope:1",
+  "title": "backend-skeleton agent request/response envelope",
+  "description": "Every request/response an AI agent produces for a feature must be wrapped in this envelope. feature_id + feature_uid scope it to a specific feature (and reject a stale copy-pasted payload from a renamed feature, since feature_uid is minted once and never reused); operation_id scopes payload to a specific operation's schema, enforced by the per-feature contract in specs/<feature_id>/contracts/<feature_id>.schema.json, not by this schema alone.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sbf", "feature_id", "feature_uid", "operation_id", "direction", "payload"],
+  "properties": {
+    "sbf": { "const": "1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "feature_uid": { "type": "string", "format": "uuid" },
+    "operation_id": { "type": "string", "pattern": "^[a-zA-Z][A-Za-z0-9]*$" },
+    "direction": { "enum": ["request", "response", "error"] },
+    "handles": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^sbf1_[A-Za-z0-9_-]+$" }
+    },
+    "payload": {}
+  }
+}

package/schemas/contract-resolution.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:contract-resolution:1",
+  "title": "backend-skeleton contract waiver resolution",
+  "description": "Documentation only, like state.schema.json -- nothing in the codebase loads this file at runtime (see contracts/completeness.mjs's loadResolution, which parses the JSON directly). Validates specs/<feature_id>/contracts/<feature_id>.resolution.json, written by `bskel contract waive`. Deliberately separate from the contract artifact itself (feature-contract.schema.json) -- see D-contract-completeness in DECISIONS.md for why waivers live in their own file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "waivers"],
+  "properties": {
+    "schema": { "const": "sbf.contract-resolution/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "waivers": {
+      "description": "Each entry is a specific {code, subject} pair, never a wildcard -- `bskel contract waive --all` expands to one entry per occurrence present at waive time, so a warning that doesn't exist yet is never covered.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "subject", "reason", "at"],
+        "properties": {
+          "code": { "type": "string", "pattern": "^CONTRACT_[A-Z_]+$" },
+          "subject": { "type": ["string", "null"] },
+          "reason": { "type": "string" },
+          "at": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}