backend-skeleton 1.0.0-beta.1

package/lib/lock.mjs

@@ -0,0 +1,68 @@
+// S5 (D-persistence-integrity): closes the lost-update race in lib/state.mjs's setGate() (and
+// contracts/completeness.mjs's saveResolution()) -- both do load -> modify -> save with no
+// synchronization, confirmed live during this item's own grounding (two processes racing a
+// load-modify-save cycle silently drop one write). mkdir-based advisory lock: `fs.mkdirSync` is
+// atomic on both POSIX and Windows (fails with EEXIST if the dir already exists), needs no new
+// dependency, and needs no cleanup daemon -- a crashed holder just leaves a directory a human can
+// `rm -rf`, which the timeout error message below points at directly.
+//
+// Deliberately SYNCHRONOUS, not Promise-based: setGate() (and every passGate/awaitDispositionGate/
+// forceGate/passNamedGate caller above it, all the way up through bin/bskel.mjs's cmdXxx functions
+// and main()) is synchronous today. Making the lock async would force `async`/`await` through that
+// entire call chain for a correctness property that doesn't need it -- this is a short-lived CLI
+// process, not a server, so blocking the (single) event loop for up to a few seconds while polling
+// for a lock is not a real cost. `Atomics.wait` gives a genuine synchronous blocking sleep on
+// Node's main thread (confirmed directly: not restricted to worker threads).
+import fs from 'node:fs';
+import path from 'node:path';
+
+const RETRY_INTERVAL_MS = 20;
+const DEFAULT_TIMEOUT_MS = 5000;
+
+const _sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+	Atomics.wait(_sleepBuffer, 0, 0, ms);
+}
+
+function locksDir(repoRoot) {
+	return path.join(repoRoot, '.sbf', '.locks');
+}
+
+function tryAcquire(lockPath) {
+	try {
+		fs.mkdirSync(lockPath, { recursive: false });
+		return true;
+	} catch (err) {
+		if (err.code === 'EEXIST') return false;
+		throw err;
+	}
+}
+
+// Runs `fn` with an exclusive lock named `lockName`, scoped to this repo. Retries acquisition
+// with a short fixed backoff until `timeoutMs` elapses, then throws with a message naming the
+// exact stale-lock path to remove -- this tool is a short-lived CLI, not a daemon, so "another
+// bskel process is stuck or crashed" is the only realistic cause, and the fix is always the same
+// (confirm nothing else is running, then delete the lock directory).
+export function withLockSync(repoRoot, lockName, fn, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+	const dir = locksDir(repoRoot);
+	fs.mkdirSync(dir, { recursive: true });
+	const lockPath = path.join(dir, `${lockName}.lock`);
+
+	const deadline = Date.now() + timeoutMs;
+	while (!tryAcquire(lockPath)) {
+		if (Date.now() >= deadline) {
+			throw new Error(
+				`could not acquire lock "${lockName}" within ${timeoutMs}ms (${lockPath} already exists) -- ` +
+				'another bskel process may be running against this repo, or a previous run crashed and left ' +
+				`this lock behind. If nothing else is running, remove ${lockPath} and try again.`,
+			);
+		}
+		sleepSync(RETRY_INTERVAL_MS);
+	}
+
+	try {
+		return fn();
+	} finally {
+		fs.rmSync(lockPath, { recursive: true, force: true });
+	}
+}

package/lib/patch-approvals.mjs

@@ -0,0 +1,56 @@
+// A3 (D-patch-strategy): the explicit human gate before ANY patchField() switch-case gets
+// generated. Mirrors contracts/completeness.mjs's loadResolution()/saveResolution() shape
+// exactly (same "documentation-file, validated at both read and write, no built-in locking of its
+// own" contract) -- feature-scoped like contract-resolution.schema.json, not repo-scoped like
+// .sbf/handles-manifest.json, because approving a field's patch strategy is a human DECISION made
+// in the context of one feature's actual need, not a file-safety fact about the repo. Per-field,
+// never a wildcard -- matches `bskel contract waive`'s own "no --all covering future warnings"
+// precedent (A5): approving Organization.name today must never silently also approve a field
+// added to that DTO next month.
+import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+
+const APPROVALS_SCHEMA = 'sbf.patch-approvals/1';
+
+export function patchApprovalsPath(root, featureId) {
+	return specPath(root, featureId, 'handles', 'patch-approvals.json');
+}
+
+export function loadPatchApprovals(root, featureId) {
+	const path = patchApprovalsPath(root, featureId);
+	const parsed = readJsonIfExists(path);
+	if (parsed === null) {
+		return { schema: APPROVALS_SCHEMA, feature_id: featureId, approvals: [] };
+	}
+	const { ok, errors } = validateAgainstSchema('patch-approvals.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${path}: does not match schemas/patch-approvals.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function savePatchApprovals(root, featureId, approvals) {
+	const { ok, errors } = validateAgainstSchema('patch-approvals.schema.json', approvals);
+	if (!ok) {
+		throw new Error(`refusing to write invalid patch approvals for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(patchApprovalsPath(root, featureId), `${JSON.stringify(approvals, null, 2)}\n`);
+	return approvals;
+}
+
+export function approvalKey(resource, field) {
+	return `${resource}::${field}`;
+}
+
+// The single lookup emit.mjs's codegen needs: is {resource, field} approved, and if so for
+// exactly which strategy? A stale approval (the DTO changed since approval, the classifier now
+// computes a different bucket) must never silently generate against a strategy that no longer
+// matches reality -- callers compare the returned strategy against the CURRENT classifier output
+// themselves and fall back to the stub on any mismatch (fail-closed, same principle as
+// D-resolver-scope's willGenerateResolver check).
+export function approvedStrategyFor(approvals, resource, field) {
+	const key = approvalKey(resource, field);
+	const match = (approvals.approvals ?? []).find((a) => approvalKey(a.resource, a.field) === key);
+	return match ? match.strategy : null;
+}

package/lib/paths.mjs

@@ -0,0 +1,21 @@
+// Shared path-building helpers for anything under specs/<feature_id>/ or .sbf/ -- pulled out of
+// bin/bskel.mjs so lib/gate-definitions.mjs and lib/verify.mjs don't each grow their own copy
+// (that kind of duplication is exactly what let lib/verify.mjs's GATE_SPECS drift out of sync
+// with bin/bskel.mjs's GATE_RECOMPUTERS -- see lib/gate-definitions.mjs).
+//
+// This module only joins paths. It does NOT validate `featureId` -- that's the CLI boundary's
+// job (lib/featureid.mjs's requireValidFeatureId/requireValidFeatureOrRepoId), and duplicating
+// that check in here would just create a second place for it to go stale.
+import path from 'node:path';
+
+export function specDir(root, featureId) {
+	return path.join(root, 'specs', featureId);
+}
+
+export function specPath(root, featureId, ...segments) {
+	return path.join(specDir(root, featureId), ...segments);
+}
+
+export function sbfPath(root, ...segments) {
+	return path.join(root, '.sbf', ...segments);
+}

package/lib/repo.mjs

@@ -0,0 +1,44 @@
+import { execFileSync } from 'node:child_process';
+
+function git(args, cwd) {
+	return execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+}
+
+export function repoRoot(cwd = process.cwd()) {
+	try {
+		return git(['rev-parse', '--show-toplevel'], cwd);
+	} catch {
+		return null;
+	}
+}
+
+export function headSha(cwd = process.cwd()) {
+	return git(['rev-parse', 'HEAD'], cwd);
+}
+
+// Cheap, local-only re-check of the default branch (no network) -- used to build the
+// `preflight` gate's re-verifiable token inputs, NOT as a replacement for the full 3-way
+// cross-check scripts/preflight-base-ref.sh does at actual preflight time.
+export function localDefaultBranch(cwd = process.cwd()) {
+	try {
+		return git(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], cwd).replace(/^origin\//, '');
+	} catch {
+		return null;
+	}
+}
+
+// D-preflight-freshness (S3): the SHA the LOCAL `origin/<branch>` remote-tracking ref currently
+// points at -- purely local (`git rev-parse`, no network), same "cheap, local-only re-check"
+// class as `localDefaultBranch()` above. Lets `require` notice when something else (an IDE's
+// auto-fetch, a manual `git fetch`) has already pulled a newer remote tip into this local repo,
+// without `require` itself ever fetching -- see D-preflight-freshness in DECISIONS.md for why
+// this deliberately does NOT mean "the remote tip is guaranteed current": if nothing has fetched
+// since the ref was last updated, this returns the same stale value it always did.
+export function remoteTrackingTip(cwd = process.cwd(), branch) {
+	if (!branch) return null;
+	try {
+		return git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`], cwd);
+	} catch {
+		return null;
+	}
+}

package/lib/schema-validate.mjs

@@ -0,0 +1,56 @@
+// S5 (D-persistence-integrity): validates this tool's own persisted JSON documents against their
+// declared schemas at read/write boundaries. Separate singleton from contracts/validate.mjs's own
+// ajv() -- that one validates runtime AGENT ENVELOPES against a per-feature contract (a different
+// concern), and lib/ importing from contracts/ would be a backwards dependency direction (contracts/
+// already imports from lib/, see bin/bskel.mjs's import graph).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMAS_ROOT = path.join(__dirname, '..', 'schemas');
+
+let _ajv = null;
+function ajv() {
+	if (!_ajv) {
+		_ajv = new Ajv2020({ allErrors: true, strict: false });
+		try {
+			addFormats(_ajv);
+		} catch {
+			// ajv-formats not installed -- format keywords (uuid, date-time) become no-ops rather
+			// than a hard failure; structural validation below still catches everything else.
+		}
+	}
+	return _ajv;
+}
+
+const _schemaCache = new Map();
+function loadSchema(schemaFileName) {
+	let schema = _schemaCache.get(schemaFileName);
+	if (!schema) {
+		schema = JSON.parse(fs.readFileSync(path.join(SCHEMAS_ROOT, schemaFileName), 'utf8'));
+		_schemaCache.set(schemaFileName, schema);
+	}
+	return schema;
+}
+
+// Validates `data` against `schemas/<schemaFileName>`. Returns {ok, errors} (mirrors
+// contracts/validate.mjs's validateEnvelopeStructure() return shape) rather than throwing --
+// callers decide how to surface a failure (a plain Error for lib-style read functions, a
+// fail()/EXIT_CODES call for CLI-layer ones), matching this codebase's existing split between
+// "throws, main()'s catch-all translates it" and "already-CLI-code calls fail() directly".
+export function validateAgainstSchema(schemaFileName, data) {
+	const schema = loadSchema(schemaFileName);
+	const validateFn = ajv().getSchema(schema.$id) ?? ajv().compile(schema);
+	const ok = validateFn(data);
+	return { ok, errors: ok ? [] : (validateFn.errors ?? []) };
+}
+
+// Renders ajv errors into the same "path message" shape contracts/validate.mjs's callers already
+// build inline (envelope validation errors) -- centralized here so every call site formats
+// consistently instead of re-deriving `${e.instancePath} ${e.message}` on its own.
+export function formatSchemaErrors(errors) {
+	return errors.map((e) => `${e.instancePath || '(root)'} ${e.message}`);
+}

package/lib/state.mjs

@@ -0,0 +1,124 @@
+// D1: gate state lives on disk as content-hash tokens, not as prose the agent is asked to honor.
+//   WHY: the spec-kit trial proved agent-honored steps are luck; spec-kit's own `optional:false`
+//        hooks are just text injected into the agent's context, not a process gate.
+//   COST: extra files per feature; stale-token friction when the spec changes mid-session.
+//   EXIT: `bskel gate force <name> --reason "..."` records the bypass so it's auditable, not silent.
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { withLockSync } from './lock.mjs';
+
+const STATE_SCHEMA = 'sbf.state/1';
+
+export function sbfDir(repoRoot) {
+	return path.join(repoRoot, '.sbf');
+}
+
+export function statePath(repoRoot, featureId) {
+	return path.join(sbfDir(repoRoot), `${featureId}.json`);
+}
+
+// S4 (D-gate-history): sibling to statePath's own .sbf/<featureId>.json -- the append-only event
+// log for the same scope, same naming convention (suffix swapped, not a different directory).
+export function historyPath(repoRoot, featureId) {
+	return path.join(sbfDir(repoRoot), `${featureId}.history.jsonl`);
+}
+
+export function loadState(repoRoot, featureId) {
+	const file = statePath(repoRoot, featureId);
+	if (!fs.existsSync(file)) {
+		return { schema: STATE_SCHEMA, feature_id: featureId, gates: {} };
+	}
+	const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+	if (parsed.schema !== STATE_SCHEMA) {
+		throw new Error(`${file}: unrecognized state schema "${parsed.schema}" (expected ${STATE_SCHEMA})`);
+	}
+	// S5: the schema-const check above already covered "is this even a state file"; this covers
+	// everything else the schema declares (gate record shape, token format, etc.) -- catches a
+	// hand-edited or externally-corrupted .sbf/<feature>.json that still happens to carry the
+	// right `schema` value. A plain Error, same as the check above -- main()'s catch-all in
+	// bin/bskel.mjs already treats "a malformed-state read" as its own documented case (exit 14).
+	const { ok, errors } = validateAgainstSchema('state.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${file}: does not match schemas/state.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+// Atomic write (temp + rename) so a mid-write crash never leaves a half-written state.json
+// that a later `gate require` would parse as valid — same technique as archify's validator writer.
+export function saveState(repoRoot, featureId, state) {
+	// S5: validated before it ever touches disk -- a bskel bug producing an invalid state object
+	// should fail loudly right here, not get persisted and surface later as a confusing read-side
+	// error somewhere else entirely.
+	const { ok, errors } = validateAgainstSchema('state.schema.json', state);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid state record for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	const dir = sbfDir(repoRoot);
+	fs.mkdirSync(dir, { recursive: true });
+	const file = statePath(repoRoot, featureId);
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+	fs.renameSync(tmp, file);
+	return file;
+}
+
+// S4 (D-gate-history): derives which of the 4 real write-time events `gateRecord` represents --
+// no separate event-type parameter needed, the record's own shape already says which one it is.
+// Deliberately no "stale" event: staleness is derived at READ time (requireGate(), never
+// written to disk -- see state.schema.json's own status-enum comment), so there is nothing to
+// log an event for; logging on every `require`/`verify` read would turn this into read-path
+// noise, not a history of state CHANGES.
+function gateEventType(gateRecord) {
+	if (gateRecord.status === 'awaiting_disposition') return 'awaiting_disposition';
+	if (gateRecord.status === 'revoked') return 'revoke';
+	if (gateRecord.forced) return 'force';
+	return 'pass';
+}
+
+// S4: validated the same way every other persistence boundary is (S5's lib/schema-validate.mjs)
+// before it touches disk. Append-only -- fs.appendFileSync, never rewritten -- so a single line's
+// corruption (a partial write from a crash mid-append) can't take down the rest of the log; the
+// reader (bin/bskel.mjs's cmdGateHistory) is expected to skip an unparseable/invalid line with a
+// warning rather than fail the whole read, matching JSONL's own resilience rationale.
+function appendGateEvent(repoRoot, featureId, gateName, gateRecord) {
+	const line = {
+		schema: 'sbf.gate-event/1',
+		event: gateEventType(gateRecord),
+		gate: gateName,
+		at: gateRecord.at,
+		status: gateRecord.status,
+		token: gateRecord.token ?? null,
+		forced: gateRecord.forced ?? false,
+		reason: gateRecord.reason ?? null,
+	};
+	const { ok, errors } = validateAgainstSchema('gate-event.schema.json', line);
+	if (!ok) {
+		throw new Error(`refusing to append an invalid gate-history event for "${featureId}"/"${gateName}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	fs.mkdirSync(sbfDir(repoRoot), { recursive: true });
+	fs.appendFileSync(historyPath(repoRoot, featureId), `${JSON.stringify(line)}\n`);
+}
+
+// S5: load -> modify -> save under an exclusive per-repo lock -- passGate/awaitDispositionGate/
+// forceGate/revokeGate (lib/gates.mjs) all funnel through this one function, so this single
+// change closes the lost-update race for every gate write in the codebase. Confirmed live
+// before this fix existed: two processes racing this exact load-modify-save sequence silently
+// dropped one process's gate write. See lib/lock.mjs for why the lock itself is synchronous.
+// S4: also appends the same write to the per-feature history log, inside the same lock, so the
+// snapshot and the log can never observe each other's writes out of order.
+export function setGate(repoRoot, featureId, gateName, gateRecord) {
+	return withLockSync(repoRoot, 'state', () => {
+		const state = loadState(repoRoot, featureId);
+		state.gates[gateName] = gateRecord;
+		saveState(repoRoot, featureId, state);
+		appendGateEvent(repoRoot, featureId, gateName, gateRecord);
+		return state;
+	});
+}
+
+export function getGate(repoRoot, featureId, gateName) {
+	const state = loadState(repoRoot, featureId);
+	return state.gates[gateName] ?? null;
+}

package/lib/template.mjs

@@ -0,0 +1,35 @@
+// P2b (D-greenfield-parameters): the `{{VAR}}` substitution `stack/apply.mjs` has performed since
+// D7 and `new/fastapi.mjs` performed as a one-variable special case (`text.replaceAll('{{SLUG}}',
+// slug)`), extracted verbatim so both consume ONE implementation. Pure code motion -- the loop body
+// below is character-for-character what `stack/apply.mjs::renderTemplate()` ran before, which is why
+// `test/stack-cli.test.mjs` passes completely unmodified across this extraction (the same bar
+// `D-handles-providers`' own extraction met). Same precedent as `scanners/text-util.mjs` and
+// `scanners/adapters/_express-shared.mjs`: a helper two real call sites already duplicate gets its
+// own module, rather than a third private copy.
+import fs from 'node:fs';
+
+// P4 (D-extension-conformance) originally defined this inside `bin/bskel.mjs` for `catalog lint`.
+// It moved here when P2b gave it a second consumer: `new/fastapi.mjs` runs it over every rendered
+// file and fails the scaffold CLOSED, which is coverage `new/templates/**` never had (the P4 lint
+// only ever looked at `stack/catalog/`). Deliberately the SAME regex, not a similar one -- a
+// template variable this project's own renderer would never substitute looks identical whichever
+// template tree it is sitting in.
+export const RESIDUAL_TEMPLATE_VAR_RE = /\{\{[A-Z_][A-Z0-9_]*\}\}/g;
+
+export function renderTemplateText(text, vars) {
+	let content = text;
+	for (const [key, value] of Object.entries(vars)) {
+		content = content.replaceAll(`{{${key}}}`, String(value));
+	}
+	return content;
+}
+
+export function renderTemplateFile(templatePath, vars) {
+	return renderTemplateText(fs.readFileSync(templatePath, 'utf8'), vars);
+}
+
+// De-duplicated, in first-appearance order -- callers report these to a human, and the same
+// unfilled token appearing four times in one file is one problem, not four.
+export function findResidualTemplateVars(text) {
+	return [...new Set(text.match(RESIDUAL_TEMPLATE_VAR_RE) ?? [])];
+}

package/lib/verify.mjs

@@ -0,0 +1,206 @@
+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 { specPath } from './paths.mjs';
+import { loadManifest, manifestPath } from './handles-manifest.mjs';
+import { resolveWithinRoot } from './fsutil.mjs';
+import { PROVIDERS, providerById } from '../handles/registry.mjs';
+import { ADAPTERS, adapterById } from '../scanners/registry.mjs';
+
+// S6: iterates the single shared gate definition list (lib/gate-definitions.mjs) instead of a
+// local GATE_SPECS -- before this fix, GATE_SPECS was a second, hand-maintained gate list that
+// drifted from bin/bskel.mjs's GATE_RECOMPUTERS: `stack` was registered as a real, writable gate
+// but simply absent from GATE_SPECS, so `stack apply` could pass a repo-scoped `stack` gate that
+// `bskel verify` would never even look at. There is only one list left to consult now.
+export function collectGateStatuses(root, featureId, { getGate, requireNamedGate }) {
+	return GATE_NAMES.map((name) => {
+		const def = GATE_DEFINITIONS[name];
+		const scopeId = gateScopeId(name, featureId);
+		const record = getGate(root, scopeId, name);
+		const result = requireNamedGate(root, name, featureId);
+		return {
+			gate: name,
+			scope: def.scope,
+			policy: def.verifyPolicy,
+			required: def.verifyPolicy === VERIFY_POLICY.REQUIRED, // kept for existing JSON consumers
+			blocking: isBlockingGateResult(def, result),
+			ran: record !== null,
+			...result,
+		};
+	});
+}
+
+// Whether one gate's current result should block the overall verify verdict. Policy
+// interpretation lives in exactly this one place.
+export function isBlockingGateResult(def, result) {
+	if (result.code === EXIT.PASS) return false;
+	if (def.verifyPolicy === VERIFY_POLICY.REQUIRED) return true;
+	// required-when-present: a gate that has never run (not_run) does not block -- but once it
+	// HAS run, every non-pass status (stale, awaiting_disposition, ...) still blocks. "Optional"
+	// means "not every feature needs this", not "once run, correctness stops mattering".
+	return result.status !== 'not_run';
+}
+
+// D5: exported so lib/doctor.mjs can reuse the exact same detection logic (does this repo have a
+// recognized build wrapper at all) instead of re-implementing it -- `bskel doctor --workflow
+// handles` and `bskel verify --build` must never disagree about what counts as "a build tool was
+// found" for the same repo.
+export function detectBuildCommand(repoRoot) {
+	if (fs.existsSync(path.join(repoRoot, 'gradlew'))) {
+		return { tool: 'gradle', cmd: './gradlew', args: ['compileJava', '--console=plain'] };
+	}
+	if (fs.existsSync(path.join(repoRoot, 'pom.xml'))) {
+		return { tool: 'maven', cmd: './mvnw', args: ['compile', '-q'] };
+	}
+	if (fs.existsSync(path.join(repoRoot, 'package.json'))) {
+		return { tool: 'npm', cmd: 'npm', args: ['run', 'build', '--if-present'] };
+	}
+	return null;
+}
+
+export function runBuildCheck(repoRoot) {
+	const build = detectBuildCommand(repoRoot);
+	if (!build) return { ran: false, ok: null, tool: null, message: 'no recognized build tool (gradlew/pom.xml/package.json) found' };
+	try {
+		execFileSync(build.cmd, build.args, { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' });
+		return { ran: true, ok: true, tool: build.tool };
+	} catch (err) {
+		// S6 (D-verify-integrity): a failing build's most useful diagnostic text sometimes lands
+		// entirely on stderr (confirmed live -- npm's own generic "> pkg build\n> cmd" banner goes
+		// to stdout, the actual fatal error to stderr). Capturing stdout alone silently dropped it.
+		// Each stream gets its OWN last-30-lines window, not one combined window -- a long stdout
+		// must not crowd out a short stderr message.
+		const stdout = (err.stdout || '').toString().trim();
+		const stderr = (err.stderr || '').toString().trim();
+		const parts = [];
+		if (stdout) parts.push(`--- stdout (last 30 lines) ---\n${stdout.split('\n').slice(-30).join('\n')}`);
+		if (stderr) parts.push(`--- stderr (last 30 lines) ---\n${stderr.split('\n').slice(-30).join('\n')}`);
+		return { ran: true, ok: false, tool: build.tool, message: parts.join('\n\n') || (err.message || '').toString() };
+	}
+}
+
+// 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
+// missing/unreadable, or names a provider that isn't (or is no longer) loaded -- this is exactly
+// the java-spring behavior every existing test/real repo already depends on, unchanged.
+const DEFAULT_HANDLES_OUTPUTS = ['handles/migration.sql'];
+
+function handlesOutputsFor(root, featureId) {
+	const scanReportPath = specPath(root, featureId, 'brownfield-scan.json');
+	if (!fs.existsSync(scanReportPath)) return DEFAULT_HANDLES_OUTPUTS;
+	let scanReport;
+	try {
+		scanReport = JSON.parse(fs.readFileSync(scanReportPath, 'utf8'));
+	} catch {
+		return DEFAULT_HANDLES_OUTPUTS;
+	}
+	const provider = providerById(PROVIDERS, scanReport.adapter);
+	return provider ? provider.outputs.spec : DEFAULT_HANDLES_OUTPUTS;
+}
+
+// S6: `handles/migration.sql` used to only become a check item when the file already existed,
+// so a `handles` gate that had passed and then had its migration.sql deleted or moved could
+// never fail this check -- the `exists:false` item was never created in the first place. The
+// `handles` gate's own token (lib/gate-definitions.mjs) covers head_sha + the contract's hash,
+// NOT migration.sql's content, so this artifact check is the ONLY thing that notices that file
+// going missing. `gates` (the result of collectGateStatuses) tells us whether the handles gate
+// has ever run at all, independent of its current pass/stale status -- a stale or forced handles
+// gate still implies every one of its expected outputs should exist. A provider with zero
+// spec-scoped outputs simply produces no artifact items here at all, which is correct: there is
+// nothing to check (no provider currently declares an empty outputs.spec -- java-spring and
+// python-fastapi both emit migration.sql, G4's D-handles-providers follow-up -- but the code
+// path stays general for whatever provider comes next).
+export function checkArtifacts(root, featureId, gates = []) {
+	const checks = [];
+	const contractPath = specPath(root, featureId, 'contracts', `${featureId}.schema.json`);
+	checks.push({ artifact: 'contract', path: path.relative(root, contractPath), exists: fs.existsSync(contractPath) });
+
+	const handlesRan = gates.find((g) => g.gate === 'handles')?.ran ?? false;
+	for (const relOutput of handlesOutputsFor(root, featureId)) {
+		const outputPath = specPath(root, featureId, ...relOutput.split('/'));
+		const outputExists = fs.existsSync(outputPath);
+		if (handlesRan || outputExists) {
+			const label = path.basename(relOutput, path.extname(relOutput));
+			checks.push({ artifact: `handles ${label}`, path: path.relative(root, outputPath), exists: outputExists });
+		}
+	}
+	checks.push(...handlesManifestChecks(root, featureId, handlesRan));
+	return checks;
+}
+
+// S2 (c): the `handles` gate's token deliberately does NOT hash the CONTENT of the Java it
+// generated -- ResourceResolverStub.java.tmpl's patchField() is MEANT to be hand-finished
+// (D-resolver-scope), so hashing generated content into the token would report every intentional
+// human edit as `stale`, exactly backwards. What is never legitimate is the file being GONE:
+// nothing regenerates it implicitly, and the feature doesn't compile without it. Same mechanism
+// and reasoning as the migration.sql check above (S6) -- existence only, at verify time, entirely
+// outside the gate token.
+function handlesManifestChecks(root, featureId, handlesRan) {
+	let manifest;
+	try {
+		manifest = loadManifest(root);
+	} catch {
+		// A manifest that exists but can't be parsed/recognized is itself a finding -- report it
+		// instead of letting `bskel verify` die with a stack trace mid-report.
+		return [{ artifact: 'handles manifest (unreadable)', path: path.relative(root, manifestPath(root)), exists: false }];
+	}
+	const entries = Object.entries(manifest.files ?? {});
+	const owned = entries.filter(([, e]) => e.owner === featureId);
+	// A feature that never ran `handles emit` must produce NO items -- otherwise another feature's
+	// resolvers (and the repo-owned infra, which every feature's entry below would also match)
+	// would show up in THIS feature's verify report as if they were its own.
+	if (!handlesRan && owned.length === 0) return [];
+	// Repo-owned infra (global/handle/*) is included whenever handles ran for this feature at all,
+	// because this feature's resolvers do not compile without it -- a deleted HandleCodec.java
+	// breaks every feature that ever emitted handles, not just the one that happened to write it.
+	const relevant = new Map([...owned, ...entries.filter(([, e]) => e.ownership === 'repo')]);
+	return [...relevant.entries()]
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([relPath, e]) => {
+			const abs = resolveWithinRoot(root, relPath);
+			return {
+				artifact: e.kind === 'infra' ? 'handles infra' : 'handles resolver',
+				path: relPath,
+				exists: abs !== null && fs.existsSync(abs),
+			};
+		});
+}
+
+// S6 (D-verify-integrity): O2's real, content-derived conflict detection (classifyFile(), see
+// lib/handles-manifest.mjs) already runs on every `handles emit`/`handles plan --diff` -- but
+// `bskel verify` never invoked it, so a resolver that has genuinely diverged into a `conflict`
+// state (not the sanctioned "hand-finished patchField()" case classifyFile() already
+// distinguishes -- see the `handles` gate's own token comment above) passed `verify` silently.
+// This reuses the EXACT dry-run call `handles plan`'s own D4 preview makes
+// (provider.plan() -> provider.emit({dryRun:true})), never re-implementing classifyFile()'s
+// semantics here. Every precondition mirrors handlesManifestChecks()'s own graceful-skip
+// philosophy -- verify must never crash or false-block just because handle codegen doesn't apply
+// to this feature; that gating is `handles plan`/`handles emit`'s own job to enforce loudly, not
+// verify's job to duplicate.
+export function checkResolverConflicts(root, featureId, handlesRan) {
+	if (!handlesRan) return [];
+	const scanReportPath = specPath(root, featureId, 'brownfield-scan.json');
+	try {
+		const scanReport = JSON.parse(fs.readFileSync(scanReportPath, 'utf8'));
+		const adapter = adapterById(ADAPTERS, scanReport.adapter);
+		if (!adapter || !adapter.capabilities['codegen.handles']) return [];
+		const provider = providerById(PROVIDERS, scanReport.adapter);
+		if (!provider) return [];
+		for (const capability of provider.requiresCapabilities ?? []) {
+			if (!adapter.capabilities[capability]) return [];
+		}
+		const plan = provider.plan({ repoRoot: root, scanReport, module: null, resourceFilter: null });
+		const { conflicts } = provider.emit({
+			repoRoot: root, featureId, plan, resourceFilter: null, force: false, reason: '', dryRun: true, computeDiff: false,
+		});
+		return conflicts ?? [];
+	} catch {
+		// A provider-internal error here is that command's own concern (handles plan/emit already
+		// report it loudly) -- not something verify should crash on, and not something it should
+		// silently promote to a false "no conflicts" claim beyond returning no findings this run.
+		return [];
+	}
+}