backend-skeleton 1.2.0 → 1.4.0

package/lib/gate-definitions.mjs

@@ -295,6 +295,32 @@ export const GATE_DEFINITIONS = Object.freeze({
 			return inputs;
 		},
 	},
+	// D-business-rules (R7): a feature's compiled business rules. Its own gate rather than a
+	// widening of `dependencies` -- the same call cross_feature/dependencies/patch_transactions/
+	// conformance each made rather than overloading a neighbour, and the two genuinely differ:
+	// a dependency is an edge between two fields, a rule is a constraint checked against one
+	// feature's own contract. REQUIRED_WHEN_PRESENT because most features will never declare one.
+	//
+	// Positioned between `dependencies` and `handles`: after dependencies because a derived-field
+	// rule references a declared dependency edge, before handles because that is where generated
+	// code appears.
+	//
+	// contract_hash is an input, not just the two rules files: every pointer, scalar type, and
+	// enum state in a compiled rule was verified against the contract at compile time, so
+	// re-emitting the contract can invalidate a rule that still looks fine on its own. Without
+	// this token a contract change could silently leave a rule enforcing against a field that no
+	// longer exists. (`contract` is itself a REQUIRED gate, so this is defence in depth, not the
+	// only line -- the same relationship `handles`'s own contract_hash token already has.)
+	rules: {
+		name: 'rules',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		recompute: (root, featureId) => ({
+			rules_source_hash: sha256File(specPath(root, featureId, 'rules.yaml')),
+			rules_compiled_hash: sha256File(specPath(root, featureId, 'rules', `${featureId}.rules.json`)),
+			contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
+		}),
+	},
 	// Staleness = the generated Java (or the contract it was generated from) has moved since
 	// emit -- NOT "does the migration still match the DB schema" (unknowable without a live DB
 	// connection this tool deliberately never opens on its own, see D-migration-scope). Note
@@ -403,7 +429,7 @@ export const GATE_DEFINITIONS = Object.freeze({
 // test/gate-definitions.test.mjs asserts this stays exactly in sync with GATE_DEFINITIONS' own
 // key set, so a gate added to one and not the other fails loudly instead of silently vanishing
 // from `bskel verify` the way `stack` did before this module existed.
-export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'handles', 'stack', 'patch_transactions', 'conformance']);
+export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'rules', 'handles', 'stack', 'patch_transactions', 'conformance']);
 
 export function getGateDefinition(name) {
 	return Object.hasOwn(GATE_DEFINITIONS, name) ? GATE_DEFINITIONS[name] : null;

package/lib/workflow.mjs

@@ -44,6 +44,11 @@ const ESTABLISH_COMMAND = {
 	// directly on the first real stale occurrence and throws a raw TypeError instead of a clean
 	// stale report.
 	dependencies: (id) => `bskel dependency declare --feature ${id} --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."`,
+	// D-business-rules (R7): wired in the SAME commit as the `rules` gate itself, per the repeated
+	// warnings above -- this exact gap has now been found live three times (dependencies,
+	// conformance, and the cross_feature near-miss) and is the single most reliably-recurring
+	// mistake in this file.
+	rules: (id) => `bskel rules check --feature ${id}`,
 	handles: (id) => `bskel handles plan --feature ${id}   # then: bskel handles emit --feature ${id}`,
 	stack: () => 'bskel stack apply --choice <id> --apply',
 	// D-patch-transactions: added in the SAME commit as the gate itself -- per the
@@ -78,11 +83,21 @@ 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',
 	'bskel handles plan', 'bskel stack apply', 'bskel observe emit', 'bskel observe import',
 	'bskel patch propose', 'bskel patch approve', 'bskel patch apply', 'bskel patch rollback',
+	// D-business-rules (R7): `rules check` writes the compiled artifact and passes its gate;
+	// `rules emit` writes generated source. `rules list`/`rules explain` are read-only and
+	// correctly absent -- the same per-verb split `pattern list|show|suggest` was checked against.
+	'bskel rules check', 'bskel rules emit',
 ];
 
 // Exported (not just inlined into action()) so lib/workflow.mjs's own test suite can assert the

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.2.0",
+  "version": "1.4.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,8 @@
     "handles/",
     "new/",
     "stack/",
+    "patterns/",
+    "rules/",
     "schemas/",
     "scripts/preflight-base-ref.sh",
     "LICENSE",
@@ -38,6 +40,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 +52,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;
+}