backend-skeleton 1.2.0 → 1.4.0

package/rules/store.mjs

@@ -0,0 +1,141 @@
+// D-business-rules (R1/R2): the I/O boundary for business rules. Paths, reading the hand-authored
+// YAML source, and reading/writing the compiled JSON artifact with schema validation on BOTH
+// sides -- the exact shape lib/cross-feature-collisions.mjs's
+// loadCrossFeatureResolution/saveCrossFeatureResolution and contracts/completeness.mjs's
+// loadResolution/saveResolution already hold ("refusing to write an invalid ...").
+//
+// rules/compile.mjs stays pure and filesystem-free; everything that touches disk lives here.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { specPath } from '../lib/paths.mjs';
+import { readJsonIfExists, writeFileAtomic } from '../lib/fsutil.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
+import { RULES_SOURCE_SCHEMA } from './compile.mjs';
+
+// The hand-authored file. Sits directly in the feature's spec dir alongside dependencies.json --
+// both are human-authored declarations about this feature's own fields, so they are siblings.
+export function rulesSourcePath(root, featureId) {
+	return specPath(root, featureId, 'rules.yaml');
+}
+
+// The compiled artifact. In its own `rules/` subdirectory, matching how `handles/migration.sql`
+// already nests a generated artifact under the feature's spec dir.
+export function rulesArtifactPath(root, featureId) {
+	return specPath(root, featureId, 'rules', `${featureId}.rules.json`);
+}
+
+/**
+ * Reads and parses specs/<featureId>/rules.yaml. Returns null when the file does not exist at all
+ * -- a legal, common state meaning "this feature declares no hand-authored rules", which still
+ * compiles to a real artifact from contract-projected rules alone (R4).
+ *
+ * Throws on malformed YAML or a wrong/missing `schema` key. Deliberately NOT schema-validated
+ * beyond that: rules/compile.mjs resolves every rule against the contract itself and produces
+ * strictly better refusals (naming real known fields, real declared types, real enum states) than
+ * a structural schema could -- see schemas/feature-rules.schema.json's own description.
+ */
+export function loadRulesSource(root, featureId) {
+	const file = rulesSourcePath(root, featureId);
+	if (!fs.existsSync(file)) return null;
+	let parsed;
+	try {
+		parsed = parseYaml(fs.readFileSync(file, 'utf8'));
+	} catch (err) {
+		throw new Error(`${file}: not valid YAML -- ${err.message}`);
+	}
+	if (parsed === null || parsed === undefined) return { schema: RULES_SOURCE_SCHEMA, rules: [] };
+	if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+		throw new Error(`${file}: must be a YAML mapping with a "rules:" list, got ${Array.isArray(parsed) ? 'a list' : typeof parsed}`);
+	}
+	if (parsed.schema !== RULES_SOURCE_SCHEMA) {
+		throw new Error(`${file}: expected \`schema: ${RULES_SOURCE_SCHEMA}\` at the top of the file, got ${parsed.schema === undefined ? '(nothing)' : JSON.stringify(parsed.schema)}`);
+	}
+	if (parsed.rules !== undefined && !Array.isArray(parsed.rules)) {
+		throw new Error(`${file}: "rules" must be a list, got ${typeof parsed.rules}`);
+	}
+	return { schema: parsed.schema, rules: parsed.rules ?? [] };
+}
+
+export function loadRulesArtifact(root, featureId) {
+	const file = rulesArtifactPath(root, featureId);
+	const parsed = readJsonIfExists(file);
+	if (parsed === null) return null;
+	const { ok, errors } = validateAgainstSchema('feature-rules.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${file}: does not match schemas/feature-rules.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveRulesArtifact(root, featureId, artifact) {
+	const { ok, errors } = validateAgainstSchema('feature-rules.schema.json', artifact);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid rules artifact for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	const file = rulesArtifactPath(root, featureId);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	// Tab-indented + trailing newline, matching every other generated JSON artifact in this repo
+	// (observe's own <feature>.observed-schema.json uses exactly this). Byte-stable across runs so
+	// a no-op recompile leaves the file untouched and the `rules` gate stays green.
+	writeFileAtomic(file, `${JSON.stringify(artifact, null, '\t')}\n`);
+	return artifact;
+}
+
+// A starter rules.yaml, written only when the user explicitly asks for one and only when no file
+// exists. Deliberately contains ZERO real rules -- every example is commented out. Writing a live
+// rule here would be `bskel` inventing a constraint about the user's domain, exactly the line
+// D-greenfield-parameters draws ("does the generated file encode a claim about the user's domain
+// that the user did not state?").
+export function starterRulesSource(featureId) {
+	return `# Business rules for ${featureId}.
+#
+# Compiled by \`bskel rules check --feature ${featureId}\` into
+# specs/${featureId}/rules/${featureId}.rules.json, which is what the generated
+# runtime checkers actually execute. Nothing here is enforced until you run that command.
+#
+# Constraints your OpenAPI document already states (minLength, maximum, enum, ...) are picked up
+# AUTOMATICALLY from the contract -- you do not need to repeat them here. This file is only for
+# the rules no schema keyword can express.
+schema: ${RULES_SOURCE_SCHEMA}
+rules: []
+#
+# Uncomment and adapt any of these -- then run \`bskel rules check --feature ${featureId}\`, which
+# verifies every pointer, type, and enum state against your own contract before compiling.
+#
+#  - id: end-after-start
+#    kind: cross
+#    operation: createBooking
+#    pointers: [/startDate, /endDate]
+#    assert: lt
+#    reason: "a booking cannot end before it starts"
+#
+#  - id: publish-flow
+#    kind: transition
+#    operation: updateArticle
+#    pointer: /status
+#    from: [draft]
+#    to: [published, archived]
+#    reason: "an article may only be published or archived out of draft"
+#
+#  - id: discount-cap
+#    kind: field
+#    operation: createOrder
+#    pointer: /discountPercent
+#    assert: maximum
+#    value: 50
+#    reason: "policy cap, not expressible in the public API schema"
+#
+#  - id: order-total
+#    kind: derived
+#    resource: Order
+#    field: total
+#    expr:
+#      op: sub
+#      args:
+#        - op: mul
+#          args: [{ ref: price }, { ref: quantity }]
+#        - { ref: discount }
+#    reason: "total = price * quantity - discount; compiles to a real Order Rules pure function"
+`;
+}

package/rules/vocabulary.mjs

@@ -0,0 +1,172 @@
+// D-business-rules (R3): the closed vocabulary of business-rule assertions this project compiles
+// into target-language code. Frozen, small, and every member mechanically executable in Java,
+// Python, and TypeScript without interpretation -- that constraint is the whole design, not a
+// convenience. See DECISIONS.md's D-business-rules, R3.
+//
+// This module is PURE DATA plus pure predicates over it. It imports nothing, so it can be read by
+// the compiler, the CLI, and every provider emitter without any risk of the import cycle
+// D-zero-config-scan hit (adapter -> lib/doctor.mjs -> lib/verify.mjs -> scanners/registry.mjs).
+//
+// DELIBERATE NON-OVERLAP with `handles/observe-schema-projection.mjs`. That module already
+// projects `required`/`type`/`pattern` out of a contract's own requestBodySchema, and every
+// provider's generated checker already enforces those three. This vocabulary covers exactly the
+// constraints that projection DROPS -- so a single violation is never reported twice by two
+// different checkers, and neither module has to know what the other kept. `required` as an
+// unconditional assertion is therefore deliberately absent here: it is the contract's/OpenAPI
+// document's own statement, not a business rule layered on top. Its genuinely-new sibling,
+// `requiredIf` (conditional on another field), IS here, because no schema keyword expresses it.
+
+// ---- field assertions: one scalar JSON Pointer, one bounded comparison ----------------------
+//
+// `valueType` is what the rule's own `value` must be (validated at compile time, so a generated
+// runtime never has to defend against a malformed rule). `appliesTo` is the set of projected
+// scalar types the assertion is meaningful against -- checked against the contract's own
+// requestBodySchema at compile time (R6), which is how a rule that says "minLength on an integer"
+// is refused with the real type named instead of silently never firing.
+export const FIELD_ASSERTS = Object.freeze({
+	minLength:        Object.freeze({ valueType: 'integer', appliesTo: Object.freeze(['string']), summary: 'string length >= value' }),
+	maxLength:        Object.freeze({ valueType: 'integer', appliesTo: Object.freeze(['string']), summary: 'string length <= value' }),
+	minimum:          Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number >= value' }),
+	maximum:          Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number <= value' }),
+	exclusiveMinimum: Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number > value' }),
+	exclusiveMaximum: Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number < value' }),
+	multipleOf:       Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number is an exact multiple of value' }),
+	enum:             Object.freeze({ valueType: 'array',   appliesTo: Object.freeze(['string', 'number', 'integer', 'boolean']), summary: 'value is one of a fixed list' }),
+});
+
+// ---- cross-field assertions: two or more pointers, compared to each other -------------------
+//
+// `arity: 2` means exactly two pointers; `arity: 'n'` means two or more. `comparison: true` marks
+// the members whose operands must be mutually comparable (both numeric, or both string) -- a
+// `lt` between a string and an integer is refused at compile time rather than given some
+// language-specific coercion behavior that would differ across the three runtimes.
+export const CROSS_ASSERTS = Object.freeze({
+	lt:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first < second' }),
+	lte:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first <= second' }),
+	gt:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first > second' }),
+	gte:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first >= second' }),
+	eq:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first == second' }),
+	neq:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first != second' }),
+	requiredIf:        Object.freeze({ arity: 2,   comparison: false, summary: 'if the first is present, the second must be too' }),
+	mutuallyExclusive: Object.freeze({ arity: 'n', comparison: false, summary: 'at most one of these may be present' }),
+});
+
+// ---- the three predicate rule kinds -----------------------------------------------------------
+//
+// `derived` is deliberately NOT here: it produces a value rather than answering true/false about
+// one, so it cannot be executed by a predicate checker at all and takes a different compilation
+// path entirely (R5). Keeping the predicate kinds in their own frozen list is what lets the
+// compiler and every checker iterate them generically.
+export const PREDICATE_KINDS = Object.freeze(['field', 'cross', 'transition']);
+
+// Every kind an authored rule may declare -- PREDICATE_KINDS plus `derived`. Used only at the
+// "is this kind even real" dispatch point in rules/compile.mjs; every other consumer (the
+// checkers, `rules explain`'s search) still branches on PREDICATE_KINDS vs. `derived` separately,
+// because the two are executed through genuinely different mechanisms (R5).
+export const ALL_RULE_KINDS = Object.freeze([...PREDICATE_KINDS, 'derived']);
+
+// R5/Phase 3: the closed arithmetic vocabulary a `derived` rule's expr tree may use. Deliberately
+// tiny and binary-only (exactly 2 args per op) -- the explicit "no arbitrary arithmetic beyond the
+// frozen operator set" scope boundary this item's own plan named. A third operand is expressed by
+// nesting (`mul(mul(a,b),c)`), never by widening arity.
+export const DERIVED_OPS = Object.freeze(['add', 'sub', 'mul', 'div']);
+
+// PascalCase for Java/TypeScript method names (`computeTotal`), snake_case for Python
+// (`compute_total`) -- pure string transforms, reused by all three provider emitters so a
+// resource/field name is capitalized identically everywhere rather than three subtly different
+// regexes drifting apart.
+export function pascalCase(name) {
+	return String(name).replace(/(^\w|[-_]\w)/g, (m) => m.replace(/[-_]/, '').toUpperCase());
+}
+
+export function snakeCase(name) {
+	return String(name)
+		.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+		.replace(/[-\s]+/g, '_')
+		.toLowerCase();
+}
+
+// Where a compiled rule came from. `contract` = projected from the feature's own
+// requestBodySchema, i.e. a fact the user's OpenAPI document already asserts, transported (R4 --
+// the same "copying is not synthesizing" posture D-openapi-passthrough established). `declared` =
+// a human wrote it in rules.yaml. Kept distinct in the compiled artifact so an auditor can always
+// tell which constraints the document licensed and which a human added on top.
+export const RULE_ORIGINS = Object.freeze(['contract', 'declared']);
+
+// The scalar types a rule can address, matching observe-schema-projection.mjs's own SCALAR_TYPES
+// exactly -- a rule can only constrain something that module already projects as a scalar leaf.
+export const RULE_SCALAR_TYPES = Object.freeze(['string', 'number', 'integer', 'boolean']);
+
+export const FIELD_ASSERT_NAMES = Object.freeze(Object.keys(FIELD_ASSERTS).sort());
+export const CROSS_ASSERT_NAMES = Object.freeze(Object.keys(CROSS_ASSERTS).sort());
+
+export function getFieldAssert(name) {
+	return Object.hasOwn(FIELD_ASSERTS, name) ? FIELD_ASSERTS[name] : null;
+}
+
+export function getCrossAssert(name) {
+	return Object.hasOwn(CROSS_ASSERTS, name) ? CROSS_ASSERTS[name] : null;
+}
+
+// The typo-defense points, same shape as lib/gate-definitions.mjs's requireGateDefinition() and
+// contracts/completeness.mjs's requireWarningCode(): name the known values rather than letting a
+// misspelled assertion silently compile to a rule that can never fire.
+export function requireFieldAssert(name) {
+	const spec = getFieldAssert(name);
+	if (!spec) throw new Error(`unknown field assertion "${name}" -- known field assertions: ${FIELD_ASSERT_NAMES.join(', ')}`);
+	return spec;
+}
+
+export function requireCrossAssert(name) {
+	const spec = getCrossAssert(name);
+	if (!spec) throw new Error(`unknown cross-field assertion "${name}" -- known cross-field assertions: ${CROSS_ASSERT_NAMES.join(', ')}`);
+	return spec;
+}
+
+// Is `value` the right shape for this assertion's declared valueType? Deliberately strict:
+// `integer` rejects 1.5 AND rejects a numeric string, because a rule whose operand needs coercing
+// is a rule whose behavior would differ between Java, Python, and JS.
+export function valueMatchesType(valueType, value) {
+	switch (valueType) {
+		case 'integer': return typeof value === 'number' && Number.isInteger(value);
+		case 'number':  return typeof value === 'number' && Number.isFinite(value);
+		case 'array':   return Array.isArray(value) && value.length > 0;
+		case 'none':    return value === undefined;
+		default:        return false;
+	}
+}
+
+// Two projected scalar types are comparable if they are both numeric or both string. Booleans are
+// deliberately never comparable with `lt`/`gt` (ordering booleans is a language-specific accident,
+// not a business rule); `eq`/`neq` between two booleans is still refused here for the same reason
+// consistency matters more than convenience -- use a field `enum` assertion instead.
+export function typesAreComparable(a, b) {
+	const numeric = new Set(['number', 'integer']);
+	if (numeric.has(a) && numeric.has(b)) return true;
+	return a === 'string' && b === 'string';
+}
+
+// Renders one compiled rule as a plain-English sentence, for `bskel rules explain`. Pure and
+// exported (rather than built inline in the CLI) so it has a direct unit test, and so the same
+// wording can be reused by any future renderer -- the same call lib/workflow.mjs made when it
+// exported isMutatingCommand() instead of inlining it.
+export function explainRule({ kind, rule }) {
+	if (kind === 'field') {
+		const spec = getFieldAssert(rule.assert);
+		const what = spec ? spec.summary.replace('value', JSON.stringify(rule.value)) : `${rule.assert} ${JSON.stringify(rule.value)}`;
+		return `${rule.pointer} must satisfy: ${what}`;
+	}
+	if (kind === 'cross') {
+		const spec = getCrossAssert(rule.assert);
+		if (rule.assert === 'requiredIf') return `if ${rule.pointers[0]} is present, ${rule.pointers[1]} must be present too`;
+		if (rule.assert === 'mutuallyExclusive') return `at most one of ${rule.pointers.join(', ')} may be present`;
+		return `${rule.pointers[0]} must be ${spec ? spec.summary.replace('first ', '').replace(' second', '') : rule.assert} ${rule.pointers[1]}`;
+	}
+	if (kind === 'transition') {
+		return `${rule.pointer} may only change from {${rule.from.join(', ')}} to {${rule.to.join(', ')}}`;
+	}
+	if (kind === 'derived') {
+		return `${rule.resource}.${rule.field} is computed from (${rule.params.join(', ')}) -- see \`rules/derived.mjs\`'s renderExprInfix() for the exact formula, or the generated <Resource>Rules class itself`;
+	}
+	return `(no explanation available for kind "${kind}")`;
+}

package/scanners/adapters/_express-shared.mjs

@@ -15,7 +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';
+import { listRgFiles as sharedListRgFiles, byShallowestThenName, binaryAvailable } from '../text-util.mjs';
 
 export const EXCLUDE_GLOBS = ['!**/node_modules/**', '!**/dist/**', '!**/build/**'];
 export const VERBS = ['get', 'post', 'put', 'patch', 'delete'];
@@ -220,14 +220,12 @@ export function expressDiagnostics(repoRoot) {
 	} else if (!pkgFiles.some((f) => declaresExpress(f))) {
 		messages.push({ level: 'info', code: 'express-not-a-dependency', message: `found ${pkgFiles.length} package.json file(s), but none declare an express dependency` });
 	}
-	let rgOk = true;
-	try {
-		execFileSync('rg', ['--version'], { stdio: 'pipe' });
-	} catch {
-		rgOk = false;
-	}
-	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-zero-config-scan: traced live -- this does NOT throw at scan time as the message used to
+	// claim. detect()'s own rg shell-outs (e.g. listCandidatePackageFiles()) are wrapped in a
+	// blanket try/catch that returns [] on failure, so a missing `rg` makes this adapter silently
+	// detect nothing (degrades to generic-grep) rather than crashing. Corrected below.
+	if (!binaryAvailable('rg')) {
+		messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it for file discovery and silently detects nothing without it (degrades to the generic-grep fallback), it does not throw' });
 	}
 	// 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

package/scanners/adapters/java-spring.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { lineNumberAt, listRgFiles, byShallowestThenName } from '../text-util.mjs';
+import { lineNumberAt, listRgFiles, byShallowestThenName, binaryAvailable } 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'];
@@ -423,14 +423,12 @@ export const adapter = {
 		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 {
-				execFileSync('rg', ['--version'], { stdio: 'pipe' });
-			} catch {
-				rgOk = false;
-			}
-			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-zero-config-scan: traced live -- this does NOT throw at scan time as the message used
+			// to claim. detectJavaSpringRoot() itself (and every other rg shell-out at detect() time)
+			// is wrapped in a blanket try/catch that returns [] on failure, so a missing `rg` makes
+			// this adapter silently detect nothing (degrades to generic-grep) rather than crashing.
+			if (!binaryAvailable('rg')) {
+				messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it for file discovery and silently detects nothing without it (degrades to the generic-grep fallback), it does not throw' });
 			}
 		}
 		// D-openapi-extraction-hint: `contract emit --openapi-file` (A1-A12) is where real accuracy

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, listRgFiles as sharedListRgFiles, byShallowestThenName } from '../text-util.mjs';
+import { lineNumberAt, listRgFiles as sharedListRgFiles, byShallowestThenName, binaryAvailable } from '../text-util.mjs';
 
 const PROJECT_FILE_GLOBS = ['pyproject.toml', 'requirements*.txt'];
 const EXCLUDE_GLOBS = ['!**/.venv/**', '!**/site-packages/**', '!**/node_modules/**', '!**/__pycache__/**'];
@@ -489,14 +489,12 @@ export const adapter = {
 		})) {
 			messages.push({ level: 'info', code: 'fastapi-not-a-dependency', message: `found ${depFiles.length} Python project file(s), but none declare a fastapi dependency` });
 		}
-		let rgOk = true;
-		try {
-			execFileSync('rg', ['--version'], { stdio: 'pipe' });
-		} catch {
-			rgOk = false;
-		}
-		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-zero-config-scan: traced live -- this does NOT throw at scan time as the message used to
+		// claim. detectPythonFastApiRoot()'s own rg shell-out is wrapped in a blanket try/catch that
+		// returns [] on failure, so a missing `rg` makes this adapter silently detect nothing
+		// (degrades to generic-grep) rather than crashing.
+		if (!binaryAvailable('rg')) {
+			messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it for file discovery and silently detects nothing without it (degrades to the generic-grep fallback), it does not throw' });
 		}
 		// D-openapi-extraction-hint: unlike java-spring, this adapter's own capabilities already
 		// declare `api.operations: false` (FastAPI assigns operationIds at runtime) -- --openapi-file

package/scanners/index.mjs

@@ -182,7 +182,12 @@ export function computeDbDrift(liveTables, relatedModules) {
 // 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 }) {
+//
+// D-zero-config-scan: `rgAvailable` is the SAME kind of CLI-boundary-resolved input as `dbSchema`
+// -- 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 }) {
 	const detections = adapters
 		.map((a) => ({ a, d: a.detect(repoRoot) }))
 		.filter(({ d }) => d != null)
@@ -221,26 +226,73 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	// 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));
+	// D-zero-config-scan: an empty `terms` array is how bin/bskel.mjs's cmdScan signals its new
+	// zero-flag "inventory" mode (neither --terms nor --feature was given) -- every detected module
+	// is listed exactly as the adapter found it, with NO term-matching/scoring/collision-detection
+	// performed. Faking `score: 0` here would be actively misleading -- 0 already means "scored,
+	// found nothing" in the existing contract -- so each module is built as an explicit allowlist
+	// (never `{...m}`), which guarantees `score`/`evidence`/`capped_signals` are genuinely ABSENT
+	// from the object, not merely `undefined`, and stops any future adapter-internal field from
+	// leaking into this report shape by accident.
+	const isInventory = terms.length === 0;
+	let relatedModules;
+	let collisions;
+	let verdict;
+	if (isInventory) {
+		relatedModules = modules
+			.map((m) => ({ module: m.module, controllers: m.controllers, entities: m.entities, enums: m.enums, dtos: m.dtos }))
+			.sort((a, b) => a.module.localeCompare(b.module)); // deterministic -- no score to sort by
+		collisions = []; // not "nothing collides" -- nothing was CHECKED. See the disclaimer below.
+		verdict = 'inventory';
+	} else {
+		// 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);
+		relatedModules = scored.filter((m) => m.score > 0);
+		collisions = relatedModules.filter((m) => m.score >= COLLISION_THRESHOLD);
 
-	let verdict = 'greenfield';
-	if (collisions.length > 0) verdict = 'collision';
-	else if (relatedModules.length > 0) verdict = 'adjacent';
+		verdict = 'greenfield';
+		if (collisions.length > 0) verdict = 'collision';
+		else if (relatedModules.length > 0) verdict = 'adjacent';
+	}
 
 	const unknowns = [];
+	// D-zero-config-scan: the FIRST unknowns entry in inventory mode -- visible in --json too, not
+	// just prose a human might skim past -- so nothing downstream (human or agent) backfills a
+	// relevance/collision judgment this report never made. See D-greenfield-parameters's safe/
+	// unsafe line: every module/controller/entity listed below is a real, observed fact about this
+	// repo; this disclaimer is what keeps "here's what exists" from being read as "here's what's
+	// safe to build".
+	if (isInventory) {
+		unknowns.push(
+			'this is an unscored inventory of every module this adapter found -- no term-matching, ' +
+			'relevance scoring, or collision/greenfield classification was performed against any ' +
+			'specific feature idea. Re-run with --terms <keywords> or --feature <id> to check a ' +
+			'specific idea against this repo before treating anything here as "safe" or "colliding".',
+		);
+	}
+	// D-zero-config-scan: without `rg`, every real adapter's detect() silently degrades (a blanket
+	// try/catch around the rg shell-out returns [] on failure -- see scanners/text-util.mjs's
+	// listRgFiles()), so a real Spring/FastAPI/Express repo can look indistinguishable from one
+	// this tool genuinely doesn't recognize. `rg_available` (always present on the returned report,
+	// both modes) is the machine-checkable signal; this is the human-readable one.
+	if (!rgAvailable) {
+		unknowns.push(
+			'ripgrep (`rg`) was not found on PATH -- every real scanner adapter depends on it for file ' +
+			'discovery, so a low-confidence or apparently-empty result here may simply mean `rg` is ' +
+			'missing, not that this repo lacks recognizable backend structure. Install it (`brew ' +
+			'install ripgrep`) and re-run, or run `bskel doctor` for full diagnostics.',
+		);
+	}
 	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) {
@@ -271,6 +323,7 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 		confidence,
 		api_surface_source: apiSurfaceSource,
 		verdict,
+		rg_available: rgAvailable,
 		path_prefix_signals: pathPrefixSignals,
 		related_modules: relatedModules,
 		collisions,

package/scanners/render.mjs

@@ -50,13 +50,22 @@ export function renderScanMarkdown(report) {
 	lines.push(`**Verdict**: \`${report.verdict}\``);
 	lines.push('');
 
+	// D-zero-config-scan: inventory mode has no term/collision semantics -- "greenfield for these
+	// terms" would be a lie when there were no terms to begin with, and a scored module's heading
+	// would dangle a `bskel scan explain` pointer that mode can never actually serve (it requires
+	// --feature, structurally unreachable here).
+	const isInventory = report.verdict === 'inventory';
 	if (report.related_modules.length === 0) {
-		lines.push('No related modules found -- greenfield for these terms.');
+		lines.push(isInventory
+			? `No modules detected by the \`${report.adapter}\` adapter in this repo.`
+			: 'No related modules found -- greenfield for these terms.');
 	} else {
-		lines.push('## Related modules');
+		lines.push(isInventory ? '## Modules found' : '## 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)`);
+			lines.push(isInventory
+				? `### \`${mod.module}\``
+				: `### \`${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) {

package/scanners/text-util.mjs

@@ -31,3 +31,25 @@ export function byShallowestThenName(a, b) {
 	const depthB = b.split(path.sep).length;
 	return depthA !== depthB ? depthA - depthB : a.localeCompare(b);
 }
+
+// D-zero-config-scan: the pure "is this binary on PATH" check, deliberately living HERE (a
+// leaf module with zero project-internal imports) rather than in lib/doctor.mjs, where it was
+// first written. lib/doctor.mjs imports lib/verify.mjs, which imports scanners/registry.mjs --
+// and every adapter file is dynamically import()ed BY registry.mjs's own top-level await. An
+// adapter importing lib/doctor.mjs would close that cycle (adapter -> lib/doctor.mjs ->
+// lib/verify.mjs -> scanners/registry.mjs -> [import()s the adapter]) and registry.mjs's OWN
+// header comment already flags exactly this risk ("no adapter imports anything from this
+// module" -- true of registry.mjs itself, but lib/doctor.mjs transitively reaches it). Found
+// live: the first version of this change put binaryAvailable() in lib/doctor.mjs and every
+// adapter import of it hung the whole CLI (a real "Detected unsettled top-level await" Node
+// warning, reproduced against a real fixture repo, not a hypothetical). lib/doctor.mjs now
+// re-exports this for its own existing callers (bin/bskel.mjs, its own binaryCheck()) --
+// nothing outside this file needs to know it moved.
+export function binaryAvailable(name, execFn = execFileSync) {
+	try {
+		execFn(name, ['--version'], { stdio: 'pipe' });
+		return true;
+	} catch {
+		return false;
+	}
+}