backend-skeleton 1.1.1 → 1.3.0

package/handles/providers/typescript-express/templates/receiptSign.ts.tmpl

@@ -0,0 +1,65 @@
+// Generated by backend-skeleton (bskel observe emit). Do not hand-edit -- change the source
+// template and regenerate.
+//
+// D-runtime-conformance-receipts (cryptographic receipt attestation): signs a receipt at emission
+// time so `bskel observe import --pubkey <path>` can prove it genuinely came from this running
+// app, not a hand-fabricated file. A self-contained PORT of lib/attest.mjs's own canonicalize()/
+// signPayload() -- never imported directly. This file runs inside a DEPLOYED target app, a
+// foreign process from this CLI's own even though both happen to be Node -- same "port, don't
+// cross-import into generated code" rule codec.ts.tmpl already established for handles/codec.mjs.
+// node:crypto only, zero new dependency, matching this project's own "no new dependency where the
+// runtime already provides the primitive" discipline (the same reasoning java-spring's own
+// ReceiptSigner.java uses java.security.Signature instead of a Bouncy Castle dependency).
+//
+// Canonicalization must be byte-identical to `bskel observe import`'s own verification side (Node's
+// lib/attest.mjs canonicalize()) -- proven cross-language-compatible by direct execution against a
+// real receipt containing a forward slash, a quote, and non-ASCII text (see DECISIONS.md
+// D-runtime-conformance-receipts). Deep-sorted object keys, array order preserved, compact JSON,
+// non-ASCII left unescaped -- exactly Node's own JSON.stringify default behavior once keys are
+// pre-sorted, so no special-casing is needed here the way Python's ensure_ascii=False is.
+
+import { sign as cryptoSign } from 'node:crypto';
+
+let privateKeyPem: string | null = null;
+
+/**
+ * NOT called by any generated code -- a human calls this once, themselves, at application
+ * startup, passing a PKCS#8 PEM private key string -- the exact format `bskel attest keygen`
+ * already writes. Never hardcode a real key value in source; read it from wherever you already
+ * keep secrets (an env var, a mounted file, a secrets manager). Unconfigured (the default,
+ * including null/blank) means every receipt stays unsigned -- backward compatible with every
+ * already-deployed app using this feature before signing existed.
+ */
+export function setSigningKey(pem: string | null | undefined): void {
+	privateKeyPem = pem && pem.trim().length > 0 ? pem : null;
+}
+
+export function isConfigured(): boolean {
+	return privateKeyPem !== null;
+}
+
+function sortKeysDeep(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(sortKeysDeep);
+	if (value !== null && typeof value === 'object') {
+		const sorted: Record<string, unknown> = {};
+		for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+			sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+		}
+		return sorted;
+	}
+	return value;
+}
+
+function canonicalize(value: unknown): string {
+	return JSON.stringify(sortKeysDeep(value));
+}
+
+/**
+ * Returns the base64 Ed25519 signature over the canonicalized receipt. Callers must pass an
+ * object that does not yet carry a "signature" key -- this module never strips one itself.
+ */
+export function sign(receiptWithoutSignature: unknown): string {
+	if (!privateKeyPem) throw new Error('receiptSign.sign() called before setSigningKey()');
+	const canonical = canonicalize(receiptWithoutSignature);
+	return cryptoSign(null, Buffer.from(canonical), privateKeyPem).toString('base64');
+}

package/lib/cli.mjs

@@ -148,6 +148,13 @@ export const COMMANDS = {
 		},
 		allowPositionals: true,
 	},
+	'scan repair': {
+		usage: 'bskel scan repair --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'scan cross-feature-check': {
 		usage: 'bskel scan cross-feature-check --feature <id> [--db [--database-url-env <NAME>] [--schema public]] [--json]',
 		options: {
@@ -234,6 +241,33 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-contract-csv: deliberately fewer flags than `contract export` -- no `--allow-unprefixed`
+	// (there is no hard refusal here to override, only a warning that always fires), no
+	// `--status-codes` (not an OpenAPI-shaped concept). `--bom` is CSV-specific: opt-in UTF-8 BOM
+	// for Excel-on-Windows, see D-contract-csv in DECISIONS.md.
+	'contract export-csv': {
+		usage: 'bskel contract export-csv --feature <id> [--out <path>] [--bom] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			out: { type: 'string', default: null },
+			bom: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-db-erd: the other "recognizable artifact" export, read-only, repo-independent like
+	// `bskel new` (no --feature -- the database plane is not feature-scoped, see E6 in D-db-erd,
+	// DECISIONS.md). Deliberately no `--db` flag: `db` IS the verb, so it's implied -- internally
+	// reuses `resolveDbSchemaOrExit(root, {...flags, db:true})` unchanged, so env-var handling and
+	// error strings stay byte-identical to `scan --db`.
+	'db erd': {
+		usage: 'bskel db erd [--database-url-env <NAME>] [--schema public] [--out <path>] [--json]',
+		options: {
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			out: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	// D-contract-history: read-only, so no --module/--openapi-file/etc -- it only ever reads what
 	// git already recorded for this feature's own contract file.
 	'contract history': {
@@ -394,12 +428,20 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): --pubkey alone has real
+	// standalone meaning (verify signatures where present, tolerate unsigned receipts) -- mirrors
+	// `serve`'s own `--sign-key` (opt-in signing, no `--require-sign-key` needed), NOT `gate export
+	// --sign`/`--key`'s mutual-requirement (a bare `--key` there is meaningless without `--sign`).
+	// --require-signature without --pubkey is refused -- mirrors `serve`'s own "mandatory signing,
+	// opt-in-to-more-strictness" `--require-sign-key`-without-`--sign-key` precedent exactly.
 	'observe import': {
-		usage: 'bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--json]',
+		usage: 'bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--pubkey <path> [--require-signature]] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			receipts: { type: 'string', default: null, required: true },
 			'fail-on-violation': { type: 'boolean', default: false },
+			pubkey: { type: 'string', default: null },
+			'require-signature': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -410,12 +452,18 @@ export const COMMANDS = {
 	// nobody actually asked for. The real defaults live in new/spring.mjs / new/fastapi.mjs, one
 	// place each.
 	new: {
-		usage: 'bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none]',
+		usage: 'bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none] [--record-pattern --pattern-database-url-env <NAME>]',
 		options: {
 			stack: { type: 'string', default: null, required: true },
 			slug: { type: 'string', default: null, required: true },
 			dir: { type: 'string', default: null },
 			offline: { type: 'boolean', default: false },
+			// D-pattern-accrual: both opt-in, both required together -- omitting either leaves
+			// `bskel new` byte-identical to today (no recording, no DB connection attempted). The
+			// actual write is best-effort (never fails the scaffold); only the "flag given but the
+			// other half missing / env var unset" usage mistake is checked before scaffold.
+			'record-pattern': { type: 'boolean', default: false },
+			'pattern-database-url-env': { type: 'string', default: null },
 
 			// Both stacks.
 			name: { type: 'string', default: null },
@@ -451,6 +499,34 @@ export const COMMANDS = {
 			'boot-version': { type: 'string', default: null, hidden: true },
 		},
 	},
+	// D-pattern-accrual: all three read-only, all requiring --pattern-database-url-env --
+	// there is no meaningful "run without a live connection" mode, same posture as `handles audit`
+	// (O7). Distinct flag name from every other command's --database-url-env: that flag always means
+	// the TARGET APPLICATION's database; this one is the user's own cross-project pattern store.
+	'pattern list': {
+		usage: 'bskel pattern list --pattern-database-url-env <NAME> [--stack spring|fastapi] [--json]',
+		options: {
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			stack: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'pattern show': {
+		usage: 'bskel pattern show <pattern_id> --pattern-database-url-env <NAME> [--json]',
+		options: {
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	},
+	'pattern suggest': {
+		usage: 'bskel pattern suggest --stack spring|fastapi --pattern-database-url-env <NAME> [--json]',
+		options: {
+			stack: { type: 'string', default: null, required: true },
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'handles patch approve': {
 		usage: 'bskel handles patch approve --feature <id> [--module <name>] --resource <Type> --field <name> --strategy patch-wrapper|null-means-unchanged --reason "..." [--json]',
 		options: {

package/lib/doctor.mjs

@@ -2,10 +2,18 @@
 // D1's lib/workflow.mjs separates `computeWorkflowState()` from its cmdStatus/cmdNext callers --
 // this stays pure enough to unit test without spawning the CLI, and bin/bskel.mjs just renders
 // whatever this returns.
-import { execFileSync } from 'node:child_process';
 import { detectBuildCommand } from './verify.mjs';
 import { listCatalogChoices, loadCatalogEntry } from '../stack/apply.mjs';
 import { detectAstHelperAvailable } from '../handles/providers/java-spring/ast-bridge.mjs';
+// D-zero-config-scan: re-exported from scanners/text-util.mjs (a cycle-free leaf module), NOT
+// defined here -- this file transitively imports scanners/registry.mjs (via ./verify.mjs), which
+// dynamically import()s every scanner adapter; an adapter importing binaryAvailable() FROM here
+// would close that cycle. See scanners/text-util.mjs's own comment on binaryAvailable() for the
+// real hang this caused before the fix. Every existing caller of `binaryAvailable` from this file
+// (bin/bskel.mjs) needs no change -- it's still available at this same import path.
+import { binaryAvailable } from '../scanners/text-util.mjs';
+
+export { binaryAvailable };
 
 // D5: the three workflows that have tool requirements beyond "git + a supported Node runtime"
 // (every workflow needs those two -- preflight/contract don't need anything ELSE, so they're
@@ -34,15 +42,8 @@ function nodeVersionOk(versionString) {
 }
 
 function binaryCheck(name, { required, remediation }) {
-	let ok = true;
-	let detail = '';
-	try {
-		execFileSync(name, ['--version'], { stdio: 'pipe' });
-	} catch {
-		ok = false;
-		detail = 'not found on PATH';
-	}
-	return { name: `binary: ${name}`, required, ok, detail, remediation: ok ? null : remediation };
+	const ok = binaryAvailable(name);
+	return { name: `binary: ${name}`, required, ok, detail: ok ? '' : 'not found on PATH', remediation: ok ? null : remediation };
 }
 
 function nodeVersionCheck() {

package/lib/field-dependencies.mjs

@@ -11,6 +11,7 @@
 // that gets passed and the token later required can never diverge.
 import path from 'node:path';
 import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { hydrateScanReportFilePaths } from './scan-report-paths.mjs';
 import { specPath } from './paths.mjs';
 import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
 import { listFeatures, loadFeatureFile } from './featurelifecycle.mjs';
@@ -119,7 +120,7 @@ export function dependencyKey(dep) {
 // slice doesn't address.
 export function resolveClassFile(root, featureId, resourceType) {
 	const reportPath = specPath(root, featureId, 'brownfield-scan.json');
-	const report = readJsonIfExists(reportPath);
+	const report = hydrateScanReportFilePaths(readJsonIfExists(reportPath), root);
 	if (!report) return { file: null, reason: 'no_scan_report' };
 	const moduleName = report.disposition?.module ?? report.related_modules?.[0]?.module;
 	if (!moduleName) return { file: null, reason: 'no_disposition' };

package/lib/gate-definitions.mjs

@@ -23,6 +23,7 @@ import { specPath, sbfPath } from './paths.mjs';
 import { ADAPTERS, adapterById } from '../scanners/registry.mjs';
 import { loadManifest } from './handles-manifest.mjs';
 import { dependenciesPath, resolveClassFile } from './field-dependencies.mjs';
+import { hydrateScanReportFilePaths } from './scan-report-paths.mjs';
 import { crossFeatureReportPath, crossFeatureResolutionPath } from './cross-feature-collisions.mjs';
 import { listTransactions, transactionPath } from './patch-transactions.mjs';
 
@@ -243,7 +244,7 @@ export const GATE_DEFINITIONS = Object.freeze({
 		verifyPolicy: VERIFY_POLICY.REQUIRED,
 		recompute: (root, featureId) => {
 			const reportPath = specPath(root, featureId, 'brownfield-scan.json');
-			const report = readJsonIfExists(reportPath);
+			const report = hydrateScanReportFilePaths(readJsonIfExists(reportPath), root);
 			const inputs = {
 				scan_report_hash: sha256File(reportPath),
 				contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
@@ -257,9 +258,12 @@ export const GATE_DEFINITIONS = Object.freeze({
 			// (part 3)" in DECISIONS.md.
 			for (const item of [...(mod?.controllers ?? []), ...(mod?.entities ?? []), ...(mod?.enums ?? []), ...(mod?.dtos ?? [])]) {
 				if (!item.file) continue;
-				// related_modules[].{controllers,entities,enums}[].file are stored ABSOLUTE
-				// (unlike Part 1's own repo-relative files_read) -- confirmed live against a real
-				// scan report before writing this.
+				// D-scan-report-portable-paths: `.file` is repo-relative on disk (adapters write
+				// it that way now); `hydrateScanReportFilePaths()` above already re-anchored it to
+				// THIS root, so a plain path.relative(root, item.file) is correct regardless of
+				// where `bskel scan` originally ran -- no longer sensitive to a stale baked-in
+				// absolute path from a different worktree/clone. See DECISIONS.md for the real
+				// bug this closes (found via a real second-worktree pilot re-verification).
 				const rel = path.relative(root, item.file);
 				inputs[`${MODULE_FILE_PREFIX}${rel}`] = sha256File(item.file);
 			}

package/lib/scan-report-paths.mjs

@@ -0,0 +1,47 @@
+// D-scan-report-portable-paths: every scanner adapter builds `related_modules[].{controllers,
+// entities,enums,dtos}[].file` ABSOLUTE (this is deliberate, unchanged -- it is the shape every
+// in-memory/direct-API consumer has always expected and still does: `runScan()` called directly
+// and handed straight to `provider.plan()`/`planHandles()` is a real, widely-used pattern across
+// this project's own test suite, not just the CLI). The ONLY place an absolute `.file` is a real
+// problem is once it gets COMMITTED to git as part of `specs/<feature>/brownfield-scan.json`
+// (confirmed NOT gitignored for real feature work) -- a value baked in from wherever `bskel scan`
+// originally ran is meaningless once that same committed branch is checked out somewhere else (a
+// second worktree, a different clone, CI). So the fix lives at exactly the disk-persistence
+// boundary, not in the adapters or in every downstream consumer:
+//   - `dehydrateScanReportFilePaths()` converts absolute -> repo-relative, called ONCE, right
+//     before `bin/bskel.mjs`'s `cmdScan` writes the report to disk (mirrors the adapters' own
+//     pre-existing `filesRead` convention -- one `path.relative(repoRoot, f)` call, just applied
+//     at the write boundary instead of duplicated across 4 adapters).
+//   - `hydrateScanReportFilePaths()` converts back, called at every point something RE-LOADS the
+//     on-disk report (`loadHydratedScanReportOrExit`, the `contract` gate, `resolveClassFile`) --
+//     `path.isAbsolute(item.file)` doubles as a legacy-shape guard, so a report committed BEFORE
+//     this fix (already absolute on disk) passes through as a correct no-op rather than a bug;
+//     `bskel scan repair` is the real remedy for a stale-but-still-absolute value from a moved
+//     worktree, not this function.
+//
+// Both functions return a NEW object (via structuredClone), never mutate their input -- `cmdScan`
+// needs the SAME in-memory `report` for both the disk write (dehydrated) and the `--json` stdout
+// print (left absolute, untouched) from ONE scan; mutating in place would make whichever happened
+// first corrupt the other.
+import path from 'node:path';
+
+function mapScanReportFiles(report, transform) {
+	if (!report) return report;
+	const next = structuredClone(report);
+	for (const mod of next.related_modules ?? []) {
+		for (const key of ['controllers', 'entities', 'enums', 'dtos']) {
+			for (const item of mod[key] ?? []) {
+				if (item.file) item.file = transform(item.file);
+			}
+		}
+	}
+	return next;
+}
+
+export function hydrateScanReportFilePaths(report, repoRoot) {
+	return mapScanReportFiles(report, (file) => (path.isAbsolute(file) ? file : path.join(repoRoot, file)));
+}
+
+export function dehydrateScanReportFilePaths(report, repoRoot) {
+	return mapScanReportFiles(report, (file) => (path.isAbsolute(file) ? path.relative(repoRoot, file) : file));
+}

package/lib/workflow.mjs

@@ -78,6 +78,12 @@ function awaitingDispositionCommand(gateName, featureId) {
 // been exercised through `next` recommending the real `conformance`-gate command, so a real
 // `mutating: false` misclassification on a command that actually writes files + passes a gate went
 // unnoticed) -- see D-field-dependency's COST section in DECISIONS.md.
+// D-pattern-accrual: `bskel new`/`bskel pattern list|show|suggest` were deliberately checked
+// against this same gap (per this comment's own warning above) and found NOT to need an entry
+// here or in ESTABLISH_COMMAND -- none of the four corresponds to a GATE_NAMES gate (`new` predates
+// any feature/gate existing at all; the three `pattern` verbs are a repo-independent, cross-project
+// read surface `next`/`status` never has reason to recommend). `handles audit` (O7) is the existing
+// precedent for a read-only command correctly staying out of this list.
 const MUTATING_PREFIXES = [
 	'bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive',
 	'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit',

package/new/index.mjs

@@ -9,6 +9,13 @@
 // parameters it accepts and which it explicitly refuses), and deliberately still a plain object.
 // The reason two first-party stacks don't justify a registry hasn't changed just because each entry
 // grew three fields.
+//
+// D-pattern-accrual: a FOURTH field, `reusableParams` -- the subset of `acceptedParams` worth
+// persisting to a user-owned pattern store when they opt in via `--record-pattern`. Deliberately a
+// subset, not `acceptedParams` itself: per-project identity (`name`/`description`/`project-version`,
+// spring's `artifact-id`/`package-name`) describes THIS project, not a reusable convention, and
+// storing project names in a database buys nothing (see D-pattern-accrual's own EXIT for the full
+// list and why each exclusion is drawn).
 import { scaffoldSpring } from './spring.mjs';
 import { scaffoldFastapi } from './fastapi.mjs';
 
@@ -39,6 +46,10 @@ export const STACKS = Object.freeze({
 			'dependencies', 'add-dependencies',
 		]),
 		refusedParams: SPRING_REFUSED_PARAMS,
+		// D-pattern-accrual: `group-id` is the one per-project-identity-shaped field kept in
+		// (unlike `artifact-id`/`package-name`) -- an organization's group id is itself a reusable
+		// convention (`com.ourco`, applied to every project), not a name unique to this one project.
+		reusableParams: Object.freeze(['java-version', 'packaging', 'dependencies', 'add-dependencies', 'group-id']),
 	}),
 	fastapi: Object.freeze({
 		id: 'fastapi',
@@ -46,9 +57,18 @@ export const STACKS = Object.freeze({
 		requiresNetwork: false,
 		acceptedParams: Object.freeze([...COMMON_PARAMS, 'python-version', 'port', 'license', 'database']),
 		refusedParams: Object.freeze({}),
+		reusableParams: Object.freeze(['python-version', 'port', 'license', 'database']),
 	}),
 });
 
+// D-pattern-accrual: the one place `bskel new`'s best-effort recording call and `bskel pattern
+// suggest` both look up which flags are worth persisting for a stack -- never re-derived, never a
+// hand-copied list at either call site.
+export function reusableParamsFor(stackId) {
+	const stack = STACKS[stackId];
+	return stack ? stack.reusableParams : [];
+}
+
 // Every parameter any stack knows about -- the set cmdNew checks a passed flag against to decide
 // "wrong stack" vs. "not a stack parameter at all". Derived, never a hand-maintained third list.
 export const ALL_STACK_PARAMS = Object.freeze([...new Set(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.1.1",
+  "version": "1.3.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).",
   "license": "AGPL-3.0-or-later",
@@ -26,6 +26,7 @@
     "handles/",
     "new/",
     "stack/",
+    "patterns/",
     "schemas/",
     "scripts/preflight-base-ref.sh",
     "LICENSE",
@@ -38,6 +39,8 @@
     "test:java-compile": "node scripts/java-compile-smoke.mjs",
     "test:python-import": "node scripts/python-import-smoke.mjs",
     "test:db-introspect": "node scripts/db-introspect-smoke.mjs",
+    "test:pattern-db": "node scripts/pattern-db-smoke.mjs",
+    "test:db-erd": "node scripts/db-erd-smoke.mjs",
     "test:registry-coverage": "node scripts/handles-registry-coverage-smoke.mjs",
     "test:ddl-apply": "node scripts/ddl-apply-smoke.mjs",
     "test:cross-feature-fk": "node scripts/cross-feature-fk-smoke.mjs",
@@ -48,7 +51,7 @@
     "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",
-    "test:all-smoke": "npm test && npm run test:pack && npm run test:java-compile && npm run test:java-integration && npm run test:python-import && npm run test:python-integration && npm run test:db-introspect && npm run test:registry-coverage && npm run test:ddl-apply && npm run test:cross-feature-fk && npm run test:java-ast && npm run test:typescript-compile"
+    "test:all-smoke": "npm test && npm run test:pack && npm run test:java-compile && npm run test:java-integration && npm run test:python-import && npm run test:python-integration && npm run test:db-introspect && npm run test:pattern-db && npm run test:db-erd && npm run test:registry-coverage && npm run test:ddl-apply && npm run test:cross-feature-fk && npm run test:java-ast && npm run test:typescript-compile"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/patterns/schema.sql

@@ -0,0 +1,18 @@
+-- D-pattern-accrual: the sbf_pattern table `bskel new --record-pattern` writes to and
+-- `bskel pattern list/show/suggest` read from. This is a database YOU own for YOUR OWN
+-- projects' conventions -- bskel never creates it automatically (D-migration-scope: the same
+-- "detect the missing table, name this exact file, never auto-DDL" posture handles/migration.sql.tmpl
+-- already established for sbf_handle/sbf_handle_snapshot). Run this by hand, once, against
+-- whatever Postgres database --pattern-database-url-env will point at.
+--
+-- `params` is JSONB, not one column per parameter, because the accepted parameter set differs
+-- per stack (new/index.mjs's reusableParams) and grows independently of this table's own schema --
+-- adding a stack, or widening a stack's reusableParams, needs zero migration here.
+CREATE TABLE IF NOT EXISTS sbf_pattern (
+	pattern_id UUID PRIMARY KEY,
+	stack TEXT NOT NULL,
+	params JSONB NOT NULL,
+	recorded_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS sbf_pattern_stack_idx ON sbf_pattern (stack);

package/patterns/store.mjs

@@ -0,0 +1,122 @@
+// D-pattern-accrual: a database the USER owns for THEIR OWN past `bskel new` invocations --
+// never bskel's own repo state, never a shared/external source (see D-pattern-accrual's own WHY
+// for the line this draws against `.bskel/config.yml`'s standing refusal). Reuses A4/D-db-schema-plane's
+// own `pg`/connection conventions unchanged: one `pg.Client`, sequential queries, `BEGIN TRANSACTION
+// READ ONLY` on every read path (structural defense-in-depth, same as scanners/db/introspect.mjs and
+// handles/audit.mjs). The one write path here (recordPattern) is a plain INSERT, no transaction
+// needed for a single statement.
+import pg from 'pg';
+import { randomUUID } from 'node:crypto';
+import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
+
+const { Client } = pg;
+
+// Postgres error code for "relation does not exist" -- the real, expected shape when
+// patterns/schema.sql was never applied to this database (D-migration-scope: bskel never applies
+// it automatically). Byte-identical convention to handles/audit.mjs's own isMissingHandleTables.
+const UNDEFINED_TABLE = '42P01';
+
+export function isMissingPatternTable(err) {
+	return err?.code === UNDEFINED_TABLE;
+}
+
+function rowToRecord(row) {
+	return {
+		schema: 'sbf.pattern/1',
+		pattern_id: row.pattern_id,
+		stack: row.stack,
+		params: row.params,
+		recorded_at: row.recorded_at instanceof Date ? row.recorded_at.toISOString() : row.recorded_at,
+	};
+}
+
+function validateRecord(record) {
+	const { ok, errors } = validateAgainstSchema('pattern-record.schema.json', record);
+	if (!ok) {
+		throw new Error(`refusing to write invalid pattern record:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+}
+
+// `params` here is already the raw, user-typed CLI flag values for whatever
+// `new/index.mjs`'s reusableParamsFor(stack) names -- the caller (cmdNew) owns filtering down to
+// that set; this function only validates the resulting record's shape and writes it. Best-effort
+// from the CALLER's perspective (bin/bskel.mjs never lets a failure here fail `bskel new` itself) --
+// this function itself throws on any real failure, same as every other patterns/store.mjs function.
+export async function recordPattern({ connectionString, stack, params }) {
+	const record = {
+		schema: 'sbf.pattern/1',
+		pattern_id: randomUUID(),
+		stack,
+		params,
+		recorded_at: new Date().toISOString(),
+	};
+	validateRecord(record);
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query(
+			'INSERT INTO sbf_pattern (pattern_id, stack, params, recorded_at) VALUES ($1, $2, $3, $4)',
+			[record.pattern_id, record.stack, JSON.stringify(record.params), record.recorded_at],
+		);
+	} finally {
+		await client.end();
+	}
+	return record;
+}
+
+export async function listPatterns({ connectionString, stack = null }) {
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query('BEGIN TRANSACTION READ ONLY');
+		const sql = stack
+			? 'SELECT pattern_id, stack, params, recorded_at FROM sbf_pattern WHERE stack = $1 ORDER BY recorded_at DESC'
+			: 'SELECT pattern_id, stack, params, recorded_at FROM sbf_pattern ORDER BY recorded_at DESC';
+		const res = await client.query(sql, stack ? [stack] : []);
+		await client.query('COMMIT');
+		return res.rows.map(rowToRecord);
+	} finally {
+		await client.end();
+	}
+}
+
+export async function getPattern({ connectionString, patternId }) {
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query('BEGIN TRANSACTION READ ONLY');
+		const res = await client.query(
+			'SELECT pattern_id, stack, params, recorded_at FROM sbf_pattern WHERE pattern_id = $1',
+			[patternId],
+		);
+		await client.query('COMMIT');
+		return res.rows.length > 0 ? rowToRecord(res.rows[0]) : null;
+	} finally {
+		await client.end();
+	}
+}
+
+// Pure -- no DB access, unit-testable directly (test/pattern-store.test.mjs). For each name in
+// `reusableParams`, ranks every distinct value actually seen across `records` by how many records
+// carried it, denominator always `records.length` (the full recorded-run count for this stack,
+// NOT just the runs that happened to set this particular param -- an omitted param is real
+// information, not missing data). Never collapses to one "best" value -- see D-pattern-accrual's
+// WHY for the confidence-label posture this mirrors (D-cross-feature-collision).
+export function summarizePatternFrequency(records, reusableParams) {
+	const total = records.length;
+	const summary = [];
+	for (const param of reusableParams) {
+		const counts = new Map();
+		for (const record of records) {
+			const value = record.params[param];
+			if (value == null) continue;
+			counts.set(value, (counts.get(value) ?? 0) + 1);
+		}
+		if (counts.size === 0) continue;
+		const values = [...counts.entries()]
+			.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+			.map(([value, count]) => ({ value, count, total }));
+		summary.push({ param, values });
+	}
+	return summary;
+}

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