backend-skeleton 1.7.1 → 1.9.0

package/README.md

@@ -34,6 +34,7 @@ check for a specific failure mode found the same way — see `DECISIONS.md` for
 - [Quickstart](#quickstart)
   - [Try it in 10 seconds](#try-it-in-10-seconds)
   - [The gated workflow](#the-gated-workflow)
+  - [Pull-request gate checks](#pull-request-gate-checks)
   - [Starting from nothing (greenfield)](#starting-from-nothing-greenfield)
   - [Publishing a feature's contract as OpenAPI (optional)](#publishing-a-features-contract-as-openapi-optional)
   - [A CSV table of a feature's contract (optional)](#a-csv-table-of-a-features-contract-optional)
@@ -105,6 +106,10 @@ bskel scan                        # zero flags: every module/controller/entity/e
                                    #   files written, no gate touched
 ```
 
+Rails projects are scanned statically by default. On a trusted Rails checkout, add
+`--runtime-routes` to boot the application and use `bin/rails routes --expanded` as the route
+source; initializers and application boot code will run.
+
 That's a read-only look, not the gated workflow — for real feature work (collision-checked against
 a specific idea, contract-gated, codegen), see below.
 
@@ -139,6 +144,45 @@ bskel verify --feature 001-organization-management --build
                                    #   target repo's own build wrapper (gradlew/mvnw/npm), if present
 ```
 
+### Pull-request gate checks
+
+`bskel ci check` is the read-only CI counterpart to `verify`: it computes the merge-base with a
+PR base ref, selects changed active features, and runs the same gate/artifact/build calculation
+and `bskel next` remediation. It never refreshes preflight, passes a gate, or runs remediation.
+
+```bash
+bskel ci check --base origin/main --build \
+  --summary-file "$GITHUB_STEP_SUMMARY" \
+  --sarif-file bskel.sarif
+```
+
+`--feature 001-a,002-b` overrides automatic selection. Without it, changes confined to one or
+more `specs/<feature-id>/` directories select those active features; a non-document change outside
+feature specs checks all active features; documentation-only diffs are an explicit successful
+no-op. `--json` writes exactly one report document even when checks fail. SARIF generation only
+creates a file; uploading it is your workflow's policy.
+
+The repository root is also a composite action:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # ci check needs the PR base and merge-base locally
+- uses: popixoxipop-collab/backend-skeleton@main
+  id: bskel
+  with:
+    build: 'true'
+
+# Optional: the action output is only a local file. Uploading requires this explicit policy.
+- uses: github/codeql-action/upload-sarif@v3
+  if: always() && steps.bskel.outputs.sarif-file != ''
+  with:
+    sarif_file: ${{ steps.bskel.outputs.sarif-file }}
+```
+
+Use this action only on GitHub-hosted or otherwise trusted runners for pull requests; it executes
+the checked-out repository's configured build command when `build: 'true'` is selected.
+
 `bskel status`/`bskel next` are what you actually run over and over — real output, captured against
 a fixture repo partway through the flow above, not written by hand:
 
@@ -595,6 +639,11 @@ string for anything missing.
 `D-adapter-registry` in `DECISIONS.md`):
 - `java-spring` — Spring Boot (`build.gradle`/`pom.xml` + `src/main/java`). Full capability set:
   operation extraction, request-body detection, and a real codegen provider for `handles emit`.
+- `ruby-rails` — Rails 8 (`Gemfile` + `config/application.rb` + `config/routes.rb`). Statically
+  expands conventional routes/resources and extracts ActiveRecord table/primary-key metadata.
+  Operation ids are deterministic bskel syntheses, not source declarations; `--runtime-routes`
+  explicitly boots the trusted application for authoritative framework routing. Scanner only:
+  request-shape extraction and handles codegen are not supported.
 - `python-fastapi` — FastAPI + SQLModel. Real codegen provider for `handles emit`; contract-grade
   operation extraction is not supported (FastAPI generates operation ids at runtime) — pass a real
   OpenAPI document via `--openapi-file` for a trustworthy contract.

package/action.yml

@@ -0,0 +1,76 @@
+name: backend-skeleton PR check
+description: Run read-only backend-skeleton feature gates for the changed pull-request surface.
+inputs:
+  base:
+    description: Base commit or ref. Defaults to the GitHub PR base SHA/ref, then origin/HEAD.
+    required: false
+  feature:
+    description: Optional comma-separated active feature IDs; overrides changed-file selection.
+    required: false
+  build:
+    description: Run the existing bskel build check for every selected feature.
+    required: false
+    default: 'false'
+  allow-skip-build:
+    description: Permit --build when no recognized build tool exists.
+    required: false
+    default: 'false'
+  sarif:
+    description: Emit a SARIF 2.1.0 file. Upload policy remains the caller's responsibility.
+    required: false
+    default: 'true'
+outputs:
+  result:
+    description: One of pass, fail, or noop.
+    value: ${{ steps.check.outputs.result }}
+  sarif-file:
+    description: Absolute path to the generated SARIF file when sarif=true; empty otherwise.
+    value: ${{ steps.check.outputs.sarif-file }}
+runs:
+  using: composite
+  steps:
+    - name: Install action dependencies
+      shell: bash
+      run: npm ci --ignore-scripts --prefix "$GITHUB_ACTION_PATH"
+    - id: check
+      shell: bash
+      env:
+        INPUT_BASE: ${{ inputs.base }}
+        INPUT_FEATURE: ${{ inputs.feature }}
+        INPUT_BUILD: ${{ inputs.build }}
+        INPUT_ALLOW_SKIP_BUILD: ${{ inputs.allow-skip-build }}
+        INPUT_SARIF: ${{ inputs.sarif }}
+        EVENT_NAME: ${{ github.event_name }}
+        RUNNER_ENVIRONMENT: ${{ runner.environment }}
+      run: |
+        set -uo pipefail
+        if [ "$EVENT_NAME" = "pull_request" ] && [ "$RUNNER_ENVIRONMENT" = "self-hosted" ]; then
+          printf '%s\n' '::error title=backend-skeleton PR check::Refusing untrusted pull_request code on a self-hosted runner.'
+          exit 1
+        fi
+        summary_file="$RUNNER_TEMP/bskel-pr-check-summary.md"
+        result_file="$RUNNER_TEMP/bskel-pr-check-result.json"
+        sarif_file="$RUNNER_TEMP/bskel-pr-check.sarif"
+        args=(ci check --summary-file "$summary_file" --json)
+        if [ -n "$INPUT_BASE" ]; then args+=(--base "$INPUT_BASE"); fi
+        if [ -n "$INPUT_FEATURE" ]; then args+=(--feature "$INPUT_FEATURE"); fi
+        if [ "$INPUT_BUILD" = "true" ]; then args+=(--build); fi
+        if [ "$INPUT_ALLOW_SKIP_BUILD" = "true" ]; then args+=(--allow-skip-build); fi
+        if [ "$INPUT_SARIF" = "true" ]; then args+=(--sarif-file "$sarif_file"); else sarif_file=''; fi
+
+        set +e
+        node "$GITHUB_ACTION_PATH/bin/bskel.mjs" "${args[@]}" > "$result_file"
+        status=$?
+        set -e
+
+        cat "$summary_file" >> "$GITHUB_STEP_SUMMARY"
+        result="$(node -e 'const fs=require("fs"); console.log(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).outcome || "fail")' "$result_file")"
+        printf 'result=%s\n' "$result" >> "$GITHUB_OUTPUT"
+        printf 'sarif-file<<EOF\n%s\nEOF\n' "$sarif_file" >> "$GITHUB_OUTPUT"
+
+        if [ "$status" -ne 0 ]; then
+          # Keep workflow-command data fixed: no changed filename, diagnostic, or user input is
+          # interpolated here. This avoids command injection through %/CR/LF in untrusted paths.
+          printf '%s\n' '::error title=backend-skeleton PR check::Blocking bskel issues found; see the job summary.'
+          exit "$status"
+        fi

package/bin/bskel.mjs

@@ -80,7 +80,8 @@ import { plan as planPythonFastApi } from '../handles/providers/python-fastapi/p
 import { emitObservePythonFastApi } from '../handles/providers/python-fastapi/observe.mjs';
 import { plan as planTypeScriptExpress } from '../handles/providers/typescript-express/plan.mjs';
 import { emitObserveTypeScriptExpress } from '../handles/providers/typescript-express/observe.mjs';
-import { collectGateStatuses, runBuildCheck, checkArtifacts, checkResolverConflicts } from '../lib/verify.mjs';
+import { evaluateFeatureVerification } from '../lib/verify.mjs';
+import { runCiCheck, renderCiSummary, toSarif } from '../lib/ci-check.mjs';
 import { computeWorkflowState } from '../lib/workflow.mjs';
 import { computeDoctorChecks, WORKFLOWS as DOCTOR_WORKFLOWS, binaryAvailable } from '../lib/doctor.mjs';
 import { parseCommand, renderCommandHelp, diagnostic } from '../lib/cli.mjs';
@@ -98,7 +99,7 @@ function usage() {
   bskel pattern show <pattern_id> --pattern-database-url-env <NAME> [--json]
   bskel pattern suggest --stack spring|fastapi --pattern-database-url-env <NAME> [--json]
   bskel preflight [--max-behind N] [--offline|--no-fetch] [--allow-dirty] [--max-age-minutes N] [--fetch-timeout-seconds N] [--json]
-  bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]
+  bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--runtime-routes] [--db [--database-url-env <NAME>] [--schema public]]
   bskel scan disposition --feature <id> --mode reuse|extend|replace|parallel [--module <name>] [--note "..."] [--breaking-approved]
   bskel scan explain <module> --feature <id> [--json]
   bskel scan repair --feature <id> [--json]
@@ -120,6 +121,7 @@ function usage() {
   bskel contract tool-schema --feature <id> --operation <operationId>
   bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path"|--all) --reason "..." [--expires <Nd>]
   bskel contract unwaive --feature <id> --code <CODE> --subject "VERB /path" --reason "..." [--json]
+  bskel ci check [--base <ref>] [--feature <id[,id...]>] [--build] [--allow-skip-build] [--summary-file <path>] [--sarif-file <path>] [--json]
   bskel dependency declare --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--memo "..."]
   bskel dependency remove --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."
   bskel dependency list --feature <id> [--json]
@@ -711,8 +713,10 @@ async function cmdScan(args) {
 	}
 	let report;
 	try {
-		report = runScan({ repoRoot: root, terms, includeDb: flags.db, dbSchema, rgAvailable });
+		report = runScan({ repoRoot: root, terms, includeDb: flags.db, dbSchema, rgAvailable, runtimeRoutes: flags['runtime-routes'] });
 	} catch (err) {
+		if (err.code === 'RUNTIME_ROUTES_UNSUPPORTED') fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
+		if (err.code === 'RUNTIME_ROUTES_FAILED') fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', err.message);
 		// Unreachable with the two shipped adapters (generic-grep's specificity-0 detect() is
 		// unconditional) -- becomes reachable the moment a future adapter's detect() is
 		// conditional, or two adapters tie at the same specificity. See scanners/index.mjs.
@@ -4273,15 +4277,9 @@ function cmdVerify(args) {
 	if (flags.help) { console.log(renderCommandHelp('verify')); process.exit(0); }
 	setContext('verify', flags);
 	const root = requireRepoRoot();
-	const gates = collectGateStatuses(root, flags.feature, { getGate, requireNamedGate });
-	const artifacts = checkArtifacts(root, flags.feature, gates);
-	const handlesRan = gates.find((g) => g.gate === 'handles')?.ran ?? false;
-	const conflicts = checkResolverConflicts(root, flags.feature, handlesRan);
-	const build = flags.build ? runBuildCheck(root) : null;
 	const allowSkipBuild = flags['allow-skip-build'];
-
-	const gatesOk = gates.every((g) => !g.blocking);
-	const artifactsPresent = artifacts.every((a) => a.exists);
+	const verification = evaluateFeatureVerification(root, flags.feature, { build: flags.build, allowSkipBuild });
+	const { gates, artifacts, conflicts, build, pass: overallPass } = verification;
 	// S6 (D-verify-integrity): `conflicts` is deliberately NON-BLOCKING, same "detect and warn,
 	// never gate" precedent as A1 §7's path-prefix signals and A4's DB drift reporting -- and the
 	// SAME reasoning D-gate-precision (S2) already used to keep generated content OUT of the
@@ -4295,9 +4293,6 @@ function cmdVerify(args) {
 	// used to be silently treated as "doesn't block" -- confirmed live that this let `bskel verify
 	// --build` report an overall PASS even though the build assurance the user explicitly asked
 	// for never actually ran. Now only acceptable with the explicit --allow-skip-build opt-out.
-	const buildOk = !build || build.ok || (!build.ran && allowSkipBuild);
-	const overallPass = gatesOk && artifactsPresent && buildOk;
-
 	if (flags.json) {
 		console.log(JSON.stringify({ feature: flags.feature, pass: overallPass, gates, artifacts, conflicts, build }, null, 2));
 	} else if (!flags.quiet) {
@@ -4309,6 +4304,44 @@ function cmdVerify(args) {
 	process.exit(overallPass ? 0 : 1);
 }
 
+function cmdCiCheck(args) {
+	const flags = parseCommand('ci check', args);
+	if (flags.help) { console.log(renderCommandHelp('ci check')); process.exit(0); }
+	setContext('ci check', flags);
+	const root = requireRepoRoot();
+	const report = runCiCheck(root, {
+		base: flags.base,
+		feature: flags.feature,
+		build: flags.build,
+		allowSkipBuild: flags['allow-skip-build'],
+	});
+	if (report.badBase || report.badArgs) {
+		if (flags['summary-file']) writeFileAtomic(path.resolve(process.cwd(), flags['summary-file']), renderCiSummary({ ...report, outcome: 'error' }));
+		if (flags['sarif-file']) writeFileAtomic(path.resolve(process.cwd(), flags['sarif-file']), `${JSON.stringify(toSarif(report), null, 2)}\n`);
+		fail(EXIT_CODES.BAD_ARGS, report.badBase ? 'BAD_BASE' : 'BAD_ARGS', report.message);
+	}
+	if (flags['summary-file']) {
+		writeFileAtomic(path.resolve(process.cwd(), flags['summary-file']), renderCiSummary(report));
+	}
+	if (flags['sarif-file']) {
+		writeFileAtomic(path.resolve(process.cwd(), flags['sarif-file']), `${JSON.stringify(toSarif(report), null, 2)}\n`);
+	}
+	if (flags.json) {
+		console.log(JSON.stringify(report, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`CI CHECK: ${report.outcome.toUpperCase()} — ${report.selected_features.length} feature(s), ${report.changed_file_count} changed file(s) [${report.selection_reason}]`);
+		for (const feature of report.features) {
+			console.log(`- [${feature.pass ? 'PASS' : 'FAIL'}] ${feature.feature}${feature.remediation ? ` — next: ${feature.remediation.command}` : ''}`);
+		}
+		if (report.outcome === 'noop') console.log('- no active feature requires verification');
+		if (report.issues.length > 0) console.log(`- blocking issues: ${report.issues.length}`);
+	}
+	// CI reports can include a large changed-file list and many feature reports. Do not force an
+	// immediate process exit after writing JSON: Node may truncate a still-buffered pipe, violating
+	// the command's one-document JSON contract. Let the event loop flush like contract export does.
+	process.exitCode = report.ok ? EXIT_CODES.OK : EXIT_CODES.CHECK_FAILED;
+}
+
 // D1: same per-gate line shape renderVerifyReport uses (reusing describeStale), but framed as
 // "where am I" rather than a pass/fail verdict -- no VERIFY: PASS/FAIL line, and blocked_by/
 // next_actions/optional_not_run are appended so a human doesn't have to re-derive them by eye.
@@ -4991,6 +5024,11 @@ async function dispatchCommand(cmd, rest) {
 		case 'verify':
 			cmdVerify(rest);
 			break;
+		case 'ci':
+			if (rest[0] === 'check') return cmdCiCheck(rest.slice(1));
+			usage();
+			process.exit(14);
+			break;
 		case 'status':
 			cmdStatus(rest);
 			break;

package/contracts/emit.mjs

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

package/contracts/openapi.mjs

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

package/lib/ci-check.mjs

@@ -0,0 +1,195 @@
+// PR-native, read-only verification.  This is intentionally a composition layer over the
+// existing verify/workflow primitives: it chooses features from a git diff, then reports their
+// normal gate/artifact/build verdicts and the normal `bskel next` remediation.  It never passes,
+// refreshes, or otherwise changes a gate.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { localDefaultBranch, headSha } from './repo.mjs';
+import { listFeatures } from './featurelifecycle.mjs';
+import { evaluateFeatureVerification } from './verify.mjs';
+import { computeWorkflowState } from './workflow.mjs';
+import { requireValidFeatureId } from './featureid.mjs';
+
+function git(root, args) {
+	return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+}
+
+function tryGit(root, args) {
+	try { return git(root, args); } catch { return null; }
+}
+
+export function defaultCiBase(root, env = process.env) {
+	// GitHub gives the immutable PR base SHA when available; it wins over a movable branch name.
+	// `GITHUB_BASE_REF` is useful on minimally configured CI and local `origin/HEAD` is the
+	// deterministic non-CI fallback.  We deliberately never assume `main`.
+	let eventBaseSha = null;
+	if (env.GITHUB_EVENT_PATH) {
+		try { eventBaseSha = JSON.parse(fs.readFileSync(env.GITHUB_EVENT_PATH, 'utf8'))?.pull_request?.base?.sha ?? null; } catch { /* the env variable is advisory */ }
+	}
+	return env.GITHUB_EVENT_PULL_REQUEST_BASE_SHA
+		|| eventBaseSha
+		|| env.GITHUB_BASE_REF
+		|| localDefaultBranch(root)
+		|| null;
+}
+
+export function resolveCiBase(root, requestedBase, env = process.env) {
+	const requested = requestedBase || defaultCiBase(root, env);
+	if (!requested) {
+		return { ok: false, message: 'could not determine a base ref: pass --base <ref>, set GITHUB_EVENT_PULL_REQUEST_BASE_SHA/GITHUB_BASE_REF, or configure origin/HEAD (bskel never guesses main)' };
+	}
+	const sha = tryGit(root, ['rev-parse', '--verify', '--quiet', `${requested}^{commit}`])
+		|| (!String(requested).startsWith('origin/') ? tryGit(root, ['rev-parse', '--verify', '--quiet', `origin/${requested}^{commit}`]) : null);
+	if (!sha) return { ok: false, message: `cannot resolve base ref "${requested}" locally -- fetch it first or pass an existing commit/ref with --base` };
+	return { ok: true, requested, sha };
+}
+
+function changedFiles(root, mergeBase) {
+	try {
+		const raw = execFileSync('git', ['diff', '--name-only', '-z', `${mergeBase}...HEAD`], { cwd: root, encoding: 'utf8' });
+		return raw.split('\0').filter(Boolean).sort((a, b) => a.localeCompare(b));
+	} catch (err) {
+		throw new Error(`could not list changed files from ${mergeBase}...HEAD: ${err.message}`);
+	}
+}
+
+function isDocumentationPath(file) {
+	return file === 'README.md'
+		|| file === 'SKILL.md'
+		|| file === 'DECISIONS.md'
+		|| file === 'ROADMAP.md'
+		|| file === 'CATALOG.md'
+		|| file === 'LICENSE'
+		|| file === 'COMMERCIAL-LICENSE.md'
+		|| file === 'COMMERCIAL-LICENSE-AGREEMENT.md'
+		|| file.startsWith('docs/');
+}
+
+function featureIdForPath(file, activeIds) {
+	const match = /^specs\/([^/]+)\//.exec(file);
+	return match && activeIds.has(match[1]) ? match[1] : null;
+}
+
+export function selectCiFeatures({ activeFeatures, changed, requestedFeatures = null }) {
+	const activeIds = activeFeatures.map((f) => f.feature_id).sort((a, b) => a.localeCompare(b));
+	const activeSet = new Set(activeIds);
+	if (requestedFeatures !== null) {
+		const requested = [...new Set(requestedFeatures)].sort((a, b) => a.localeCompare(b));
+		const unknown = requested.filter((id) => !activeSet.has(id));
+		if (unknown.length) throw new Error(`--feature names no active feature: ${unknown.join(', ')} (active: ${activeIds.join(', ') || '(none)'})`);
+		return { selectedFeatures: requested, selectionReason: 'explicit_feature' };
+	}
+
+	const scoped = new Set();
+	let sharedProductChange = false;
+	for (const file of changed) {
+		const featureId = featureIdForPath(file, activeSet);
+		if (featureId) scoped.add(featureId);
+		else if (!isDocumentationPath(file)) sharedProductChange = true;
+	}
+	if (sharedProductChange) return { selectedFeatures: activeIds, selectionReason: 'shared_product_change_all_active' };
+	if (scoped.size > 0) return { selectedFeatures: [...scoped].sort((a, b) => a.localeCompare(b)), selectionReason: 'feature_scoped_changes' };
+	return { selectedFeatures: [], selectionReason: changed.length === 0 ? 'no_changes' : 'documentation_only_or_no_active_feature_change' };
+}
+
+function parseFeatureList(value) {
+	if (value == null) return null;
+	const values = value.split(',').map((v) => v.trim()).filter(Boolean);
+	if (values.length === 0) throw new Error('--feature must name at least one comma-separated feature id');
+	for (const id of values) requireValidFeatureId(id);
+	return values;
+}
+
+export function runCiCheck(root, { base = null, feature = null, build = false, allowSkipBuild = false, env = process.env } = {}) {
+	const baseResult = resolveCiBase(root, base, env);
+	if (!baseResult.ok) return { ok: false, badBase: true, message: baseResult.message };
+	const mergeBase = tryGit(root, ['merge-base', baseResult.sha, 'HEAD']);
+	if (!mergeBase) return { ok: false, badBase: true, message: `cannot compute a merge-base between ${baseResult.requested} (${baseResult.sha}) and HEAD -- pass a related --base ref` };
+	const changed = changedFiles(root, mergeBase);
+	const activeFeatures = listFeatures(root);
+	let selection;
+	try {
+		selection = selectCiFeatures({ activeFeatures, changed, requestedFeatures: parseFeatureList(feature) });
+	} catch (err) {
+		return { ok: false, badArgs: true, message: err.message };
+	}
+	const common = {
+		schema: 'sbf.ci-check/1',
+		base: { requested: baseResult.requested, sha: baseResult.sha },
+		merge_base: mergeBase,
+		head: headSha(root),
+		changed_files: changed,
+		changed_file_count: changed.length,
+		selection_reason: selection.selectionReason,
+		selected_features: selection.selectedFeatures,
+	};
+	if (selection.selectedFeatures.length === 0) {
+		return { ...common, ok: true, outcome: 'noop', features: [], issues: [] };
+	}
+	const features = selection.selectedFeatures.map((featureId) => {
+		const verification = evaluateFeatureVerification(root, featureId, { build, allowSkipBuild });
+		const workflow = computeWorkflowState(root, featureId);
+		return { ...verification, remediation: workflow.next_actions[0] ?? null };
+	});
+	const issues = collectIssues(features);
+	return { ...common, ok: issues.length === 0, outcome: issues.length === 0 ? 'pass' : 'fail', features, issues };
+}
+
+function featureLocation(featureId) {
+	return `specs/${featureId}/feature.json`;
+}
+
+export function collectIssues(features) {
+	const issues = [];
+	for (const report of features) {
+		for (const gate of report.gates.filter((g) => g.blocking)) {
+			issues.push({ kind: 'gate', feature: report.feature, name: gate.gate, path: featureLocation(report.feature), message: `${report.feature}: ${gate.gate} gate is ${gate.status}` });
+		}
+		for (const artifact of report.artifacts.filter((a) => !a.exists)) {
+			issues.push({ kind: 'artifact', feature: report.feature, name: artifact.artifact, path: artifact.path, message: `${report.feature}: missing ${artifact.artifact} (${artifact.path})` });
+		}
+		if (report.build_blocking) {
+			issues.push({ kind: 'build', feature: report.feature, name: report.build.tool ?? 'build', path: 'package.json', message: `${report.feature}: ${report.build.message ?? `${report.build.tool} build failed`}` });
+		}
+	}
+	return issues.sort((a, b) => [a.feature, a.kind, a.name, a.path].join('\0').localeCompare([b.feature, b.kind, b.name, b.path].join('\0')));
+}
+
+export function renderCiSummary(report) {
+	const lines = ['# backend-skeleton PR check', '', `- Outcome: **${report.outcome ?? 'error'}**`];
+	if (report.base) lines.push(`- Base: \`${report.base.requested}\` (${report.base.sha})`, `- Merge base: \`${report.merge_base}\``, `- Head: \`${report.head}\``);
+	if (report.changed_file_count != null) lines.push(`- Changed files: ${report.changed_file_count}`, `- Selection: \`${report.selection_reason}\``);
+	if (report.selected_features) lines.push(`- Selected features: ${report.selected_features.length ? report.selected_features.map((id) => `\`${id}\``).join(', ') : '(none)'}`);
+	if (report.outcome === 'noop') return `${lines.concat(['', 'No active feature requires verification for this diff.']).join('\n')}\n`;
+	lines.push('', '## Features');
+	for (const feature of report.features ?? []) {
+		lines.push(`- [${feature.pass ? 'PASS' : 'FAIL'}] \`${feature.feature}\`${feature.remediation ? ` — next: \`${feature.remediation.command}\`` : ''}`);
+	}
+	if (report.issues?.length) {
+		lines.push('', '## Blocking issues');
+		for (const issue of report.issues) lines.push(`- \`${issue.feature}\`: ${issue.message}`);
+	}
+	return `${lines.join('\n')}\n`;
+}
+
+export function toSarif(report) {
+	const results = (report.issues ?? []).map((issue) => ({
+		ruleId: `bskel/${issue.kind}`,
+		level: 'error',
+		message: { text: issue.message },
+		locations: issue.path ? [{ physicalLocation: { artifactLocation: { uri: issue.path.replaceAll(path.sep, '/') } } }] : [],
+	}));
+	return {
+		$schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+		version: '2.1.0',
+		runs: [{
+			tool: { driver: { name: 'backend-skeleton', informationUri: 'https://github.com/popixoxipop-collab/backend-skeleton', rules: [
+				{ id: 'bskel/gate', shortDescription: { text: 'A required bskel gate is not passing' } },
+				{ id: 'bskel/artifact', shortDescription: { text: 'A required bskel artifact is missing' } },
+				{ id: 'bskel/build', shortDescription: { text: 'The requested build check did not pass' } },
+			] } },
+			results,
+		}],
+	};
+}

package/lib/cli.mjs

@@ -120,7 +120,7 @@ export const COMMANDS = {
 		},
 	},
 	scan: {
-		usage: 'bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]',
+		usage: 'bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--runtime-routes] [--db [--database-url-env <NAME>] [--schema public]]',
 		options: {
 			feature: { type: 'string', default: null },
 			terms: { type: 'string', default: '' },
@@ -132,6 +132,7 @@ export const COMMANDS = {
 			schema: { type: 'string', default: 'public' },
 			json: { type: 'boolean', default: false },
 			'accept-low-confidence': { type: 'boolean', default: false },
+			'runtime-routes': { type: 'boolean', default: false },
 		},
 	},
 	'scan disposition': {
@@ -770,6 +771,18 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	'ci check': {
+		usage: 'bskel ci check [--base <ref>] [--feature <id[,id...]>] [--build] [--allow-skip-build] [--summary-file <path>] [--sarif-file <path>] [--json]',
+		options: {
+			base: { type: 'string', default: null },
+			feature: { type: 'string', default: null },
+			build: { type: 'boolean', default: false },
+			'allow-skip-build': { type: 'boolean', default: false },
+			'summary-file': { type: 'string', default: null },
+			'sarif-file': { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	status: {
 		usage: 'bskel status [--feature <id>] [--json]',
 		options: {
@@ -819,10 +832,10 @@ export const COMMANDS = {
 };
 
 function describeParseArgsError(err, spec) {
-	const known = [
+	const known = [...new Set([
 		...Object.keys(spec.options).filter((f) => !spec.options[f].hidden),
 		'help', 'json', 'quiet',
-	].sort().map((f) => `--${f}`).join(', ');
+	])].sort().map((f) => `--${f}`).join(', ');
 	return `${err.message}\nusage: ${spec.usage}\nknown flags: ${known}`;
 }
 
@@ -887,7 +900,10 @@ export function renderCommandHelp(name) {
 		if (def.required) parts.push('required');
 		lines.push(`  --${flag}  (${parts.join(', ')})`);
 	}
-	lines.push('  --json  (boolean)');
+	// `--json` is global, but most command specs also list it explicitly so their usage/default
+	// snapshots are self-describing. Render the global row only when the command did not already
+	// render its explicit row; otherwise help incorrectly printed it twice.
+	if (!Object.hasOwn(spec.options, 'json')) lines.push('  --json  (boolean)');
 	lines.push('  --quiet  (boolean)');
 	lines.push('  --help  (boolean)');
 	lines.push('', "see 'bskel --help' for the full command list");

package/lib/verify.mjs

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { GATE_NAMES, GATE_DEFINITIONS, VERIFY_POLICY, gateScopeId } from './gate-definitions.mjs';
-import { EXIT } from './gates.mjs';
+import { EXIT, requireNamedGate } from './gates.mjs';
+import { getGate } from './state.mjs';
 import { specPath } from './paths.mjs';
 import { loadManifest, manifestPath } from './handles-manifest.mjs';
 import { resolveWithinRoot } from './fsutil.mjs';
@@ -81,6 +82,30 @@ export function runBuildCheck(repoRoot) {
 	}
 }
 
+// The complete read-only verification calculation.  `bskel verify` and the PR-oriented
+// `bskel ci check` deliberately share this instead of maintaining two subtly different ideas of
+// what it means for a feature to pass.  This function never writes gate state; the only optional
+// side effect is the build command explicitly requested by the caller.
+export function evaluateFeatureVerification(root, featureId, { build = false, allowSkipBuild = false } = {}) {
+	const gates = collectGateStatuses(root, featureId, { getGate, requireNamedGate });
+	const artifacts = checkArtifacts(root, featureId, gates);
+	const handlesRan = gates.find((g) => g.gate === 'handles')?.ran ?? false;
+	const conflicts = checkResolverConflicts(root, featureId, handlesRan);
+	const buildResult = build ? runBuildCheck(root) : null;
+	const gatesOk = gates.every((g) => !g.blocking);
+	const artifactsPresent = artifacts.every((a) => a.exists);
+	const buildOk = !buildResult || buildResult.ok || (!buildResult.ran && allowSkipBuild);
+	return {
+		feature: featureId,
+		pass: gatesOk && artifactsPresent && buildOk,
+		gates,
+		artifacts,
+		conflicts,
+		build: buildResult,
+		build_blocking: Boolean(buildResult && (!buildResult.ran ? !allowSkipBuild : buildResult.ok === false)),
+	};
+}
+
 // G4: which spec-scoped output files a `handles` gate is expected to have produced -- provider-
 // aware, via the same scan report -> adapter -> provider chain bin/bskel.mjs's handles commands
 // use. Falls back to the pre-G4 single migration.sql expectation whenever the scan report is