backend-skeleton 1.4.0 → 1.6.0

package/handles/providers/typescript-express/plan.mjs

@@ -57,7 +57,13 @@ function findFetchRoute(controllers, entityClassName) {
 			if (ep.verb !== 'GET') continue;
 			const suffix = ep.path.slice(controller.basePath.length);
 			if (/^\/:[^/(]+(\([^)]*\))?$/.test(suffix)) {
-				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className };
+				// X5 (D-route-expansion-provenance): threaded through so the caller can distinguish
+				// "inline arrow handler" (this provider's real, current no-method case) from "1:N
+				// framework-synthesized route" (a declaration is present) in its note text. null on
+				// every endpoint in today's adapter (it never populates declarationIndex) --
+				// forward-compatible only, not yet reachable.
+				const declaration = ep.declarationIndex != null ? (controller.declarations?.[ep.declarationIndex] ?? null) : null;
+				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className, declaration };
 			}
 		}
 	}
@@ -183,7 +189,14 @@ export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter
 		if (!fetchRoute) {
 			notes.push(`${entity.className}: no single-resource GET route found on a router whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
 		} else if (!fetchRoute.method) {
-			notes.push(`${entity.className}: the single-resource GET route's handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.`);
+			// X5 (D-route-expansion-provenance): a declaration means this route was expanded from a
+			// 1:N framework construct (no literal per-action method exists at all, not yet reachable
+			// in this adapter); no declaration keeps this provider's own real, current cause (an
+			// inline arrow-function handler) unchanged.
+			const note = fetchRoute.declaration
+				? `the matched endpoint (GET ${fetchRoute.path}) was expanded from ${fetchRoute.declaration.label ?? fetchRoute.declaration.rule} at ${path.relative(repoRoot, fetchRoute.file)}:${fetchRoute.declaration.line} (rule: ${fetchRoute.declaration.rule}) -- the framework generates this handler at runtime, so no literal per-action source method exists to correlate to. Resolver NOT generated -- this is a structural boundary of static-scan-based handles codegen, not a bug. See D-resolver-scope.`
+				: 'the single-resource GET route\'s handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.';
+			notes.push(`${entity.className}: ${note}`);
 		} else if (!handlerFile) {
 			notes.push(`${entity.className}: could not resolve ${fetchRoute.method}'s own defining file (import, or one barrel hop, from ${path.relative(repoRoot, fetchRoute.file)}) -- resolver NOT generated.`);
 		} else if (!selectFields) {

package/lib/attest.mjs

@@ -4,7 +4,7 @@
 // sign, and verify a JSON payload -- it has no opinion about WHERE a key lives (bin/bskel.mjs's
 // `--key`/`--pubkey` flags are the only interface, per the user's own explicit choice to reject a
 // new home-directory key-storage convention for this slice -- see DECISIONS.md).
-import { generateKeyPairSync, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { generateKeyPairSync, createPublicKey, createHash, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
 import { sortKeysDeep } from './gates.mjs';
 
 export function generateKeypair() {
@@ -15,6 +15,13 @@ export function generateKeypair() {
 	};
 }
 
+// D-attestation-payload-completeness (K1): the named canonicalization algorithm this module
+// implements -- recorded in a signed payload's own `tool.canonicalization` field so a verifier on
+// a future bskel build can tell whether it's speaking the same dialect. Kept as `sortkeysdeep-json`
+// forever (never silently redefined) -- see K1 in DECISIONS.md for why RFC 8785/JCS was considered
+// and rejected for this codebase's value space.
+export const CANONICALIZATION_ID = 'sortkeysdeep-json';
+
 // Deep-sorted, whitespace-free JSON -- the ONLY thing that's ever actually signed/verified.
 // Reusing lib/gates.mjs's own sortKeysDeep() (already proven correct via every gate's `inputs`
 // field) rather than a second, possibly-subtly-different implementation.
@@ -22,7 +29,58 @@ export function canonicalize(value) {
 	return JSON.stringify(sortKeysDeep(value));
 }
 
+// D-attestation-payload-completeness (K1): fail-closed guard, called ONLY from signPayload() --
+// verifyPayload() keeps its shipped never-throws contract. A NaN/Infinity/undefined/BigInt/Date/
+// function/symbol reaching JSON.stringify would silently serialize to something other than
+// itself (or be dropped entirely) -- signing that payload would be signing a lie about what the
+// value actually was. Walks the value with the exact JSON path of the first offending node in the
+// thrown message, so a caller can find it without a second investigation.
+export function assertCanonicalizable(value, jsonPath = '$') {
+	if (value === null) return;
+	const t = typeof value;
+	if (t === 'string' || t === 'boolean') return;
+	if (t === 'number') {
+		if (!Number.isFinite(value)) throw new Error(`assertCanonicalizable: ${jsonPath} is ${Number.isNaN(value) ? 'NaN' : value}, not a finite JSON number`);
+		return;
+	}
+	if (t === 'undefined') throw new Error(`assertCanonicalizable: ${jsonPath} is undefined`);
+	if (t === 'bigint') throw new Error(`assertCanonicalizable: ${jsonPath} is a BigInt, which JSON.stringify cannot represent`);
+	if (t === 'function') throw new Error(`assertCanonicalizable: ${jsonPath} is a function`);
+	if (t === 'symbol') throw new Error(`assertCanonicalizable: ${jsonPath} is a symbol`);
+	if (Array.isArray(value)) {
+		value.forEach((item, i) => assertCanonicalizable(item, `${jsonPath}[${i}]`));
+		return;
+	}
+	// t === 'object' from here -- reject anything whose prototype isn't a plain object (Date, Map,
+	// Set, a class instance, ...): JSON.stringify would silently call .toJSON() or drop it instead
+	// of representing its real shape.
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) {
+		throw new Error(`assertCanonicalizable: ${jsonPath} is a non-plain object (${value?.constructor?.name ?? 'unknown'}), not a plain {} or []`);
+	}
+	for (const [key, v] of Object.entries(value)) assertCanonicalizable(v, `${jsonPath}.${key}`);
+}
+
+// D-attestation-payload-completeness (K6): 'ed25519:<32 hex chars>' -- sha256 over the public
+// key's SPKI DER bytes, first 16 bytes hex-encoded. A SELECTION HINT for `attest verify`'s error
+// message, never a trust claim: it lives OUTSIDE the signed bytes (only `report` is signed), so it
+// is exactly as attacker-modifiable as any other envelope field. See K6 in DECISIONS.md.
+function keyIdFromDer(der) {
+	return `ed25519:${createHash('sha256').update(der).digest('hex').slice(0, 32)}`;
+}
+
+export function publicKeyIdFromPublic(publicKeyPem) {
+	const der = createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+	return keyIdFromDer(der);
+}
+
+export function publicKeyIdFromPrivate(privateKeyPem) {
+	const der = createPublicKey(privateKeyPem).export({ type: 'spki', format: 'der' });
+	return keyIdFromDer(der);
+}
+
 export function signPayload(payload, privateKeyPem) {
+	assertCanonicalizable(payload);
 	const canonical = canonicalize(payload);
 	return cryptoSign(null, Buffer.from(canonical), privateKeyPem).toString('base64');
 }

package/lib/cli.mjs

@@ -84,13 +84,16 @@ export const COMMANDS = {
 	},
 	// D-gate-export: unlike `gate show`, always feature-scoped -- the whole point is one feature's
 	// own evidence trail across all 5 gates, not a single gate/repo-level snapshot.
+	// D-attestation-payload-completeness (K4): --allow-dirty only has an effect together with
+	// --sign (bskel gate export enforces this itself -- see cmdGateExport's own BAD_ARGS check).
 	'gate export': {
-		usage: 'bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath>] [--json]',
+		usage: 'bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath> [--allow-dirty]] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			out: { type: 'string', default: null },
 			sign: { type: 'boolean', default: false },
 			key: { type: 'string', default: null },
+			'allow-dirty': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -103,11 +106,16 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-attestation-payload-completeness (K5): three OPT-IN, default-off assertions, evaluated
+	// purely against fields already inside the (offline, repo-independent) report.
 	'attest verify': {
-		usage: 'bskel attest verify --file <path> --pubkey <path> [--json]',
+		usage: 'bskel attest verify --file <path> --pubkey <path> [--expect-head <sha>] [--max-age-minutes N] [--reject-dirty] [--json]',
 		options: {
 			file: { type: 'string', default: null, required: true },
 			pubkey: { type: 'string', default: null, required: true },
+			'expect-head': { type: 'string', default: null },
+			'max-age-minutes': { type: 'string', default: null, numeric: { min: 0 } },
+			'reject-dirty': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -339,6 +347,67 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-cross-feature-impact-graph: `check` is read-mostly (writes impact-report.json, never
+	// advances the baseline); `accept` is the only command that advances impact-baseline.json, and
+	// refuses (exit 3) if any proven outbound impact is undisposed or inbound migration
+	// unacknowledged. `--all` (check only) sweeps every active feature -- the only thing that closes
+	// the brand-new-counterparty narrowing gap the `impact` gate's own recompute() accepts (see D4/D7
+	// in DECISIONS.md).
+	'impact check': {
+		usage: 'bskel impact check (--feature <id> | --all) [--json]',
+		options: {
+			feature: { type: 'string', default: null },
+			all: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'impact accept': {
+		usage: 'bskel impact accept --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-cross-feature-impact-graph (D6): three modes, three mechanically different consequences --
+	// `migrate` requires --tracked-by, `waive` requires --expires-days. `compatible` needs neither.
+	'impact disposition': {
+		usage: 'bskel impact disposition --feature <id> --change <change_key> --downstream <id> --mode compatible|migrate|waive --reason "..." [--tracked-by "<ref>"] [--expires-days <N>] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			change: { type: 'string', default: null, required: true },
+			downstream: { type: 'string', default: null, required: true },
+			mode: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			'tracked-by': { type: 'string', default: null },
+			'expires-days': { type: 'string', default: null, numeric: { min: 1 } },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'impact ack': {
+		usage: 'bskel impact ack --feature <id> --from <upstream_id> --change <change_key> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			from: { type: 'string', default: null, required: true },
+			change: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-cross-feature-impact-graph (IG8): the one LLM-free seam to the exploration layer -- `--format
+	// graphify` writes graphify's own native extraction file shape directly (bypassing its own
+	// install/detect/extract steps), `--format json` writes the raw sbf.impact-graph/1 document,
+	// `--format mermaid` mirrors `bskel db erd`'s own posture. `--focus`/`--rings` implement IG9's
+	// Focus+Context data projection (ring/detail), written only into the export, never read back by
+	// any gate.
+	'impact export': {
+		usage: 'bskel impact export --format graphify|json|mermaid [--out <path>] [--focus <node-id>] [--rings <N>]',
+		options: {
+			format: { type: 'string', default: null, required: true },
+			out: { type: 'string', default: null },
+			focus: { type: 'string', default: null },
+			rings: { type: 'string', default: null, numeric: { min: 0 } },
+		},
+	},
 	// D-business-rules: `check` compiles + verifies + establishes the `rules` gate; `list`/`explain`
 	// are read-only. `--init` writes a starter rules.yaml only when none exists (never overwrites).
 	'rules check': {
@@ -582,20 +651,23 @@ export const COMMANDS = {
 	// to a known-good, git-recoverable prior state is materially lower-risk than forcing a forward
 	// edit whose collateral effects were never re-verified).
 	'patch propose': {
-		usage: 'bskel patch propose --feature <id> [--kind config-apply --choice <stackChoiceId> --target <config_check target path> | --kind ddl-apply --database-url-env <NAME> --sql-file <path> [--schema public]] [--json]',
+		usage: 'bskel patch propose --feature <id> [--kind config-apply --choice <stackChoiceId> --target <config_check target path> | --kind ddl-apply --database-url-env <NAME> --sql-file <path> [--schema public] | --kind java-source-splice --splice-file <path>] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			// D-ddl-apply: default 'config-apply' -- omitting --kind entirely is byte-identical to
-			// this project's prior behavior. choice/target/database-url-env/sql-file are validated
-			// by hand inside cmdPatchPropose (kind-conditional requirements aren't expressible via
-			// this table's own unconditional `required: true`), matching this file's existing
-			// convention for kind-conditional flags (e.g. --reason on approve/rollback).
+			// this project's prior behavior. choice/target/database-url-env/sql-file/splice-file are
+			// validated by hand inside cmdPatchPropose (kind-conditional requirements aren't
+			// expressible via this table's own unconditional `required: true`), matching this file's
+			// existing convention for kind-conditional flags (e.g. --reason on approve/rollback).
 			kind: { type: 'string', default: 'config-apply' },
 			choice: { type: 'string', default: null },
 			target: { type: 'string', default: null },
 			'database-url-env': { type: 'string', default: null },
 			schema: { type: 'string', default: 'public' },
 			'sql-file': { type: 'string', default: null },
+			// D-java-source-splice: a JSON request document, not raw text like --sql-file -- a method
+			// body cannot live in a shell flag, and the edit list itself needs real structure.
+			'splice-file': { type: 'string', default: null },
 			json: { type: 'boolean', default: false },
 		},
 	},

package/lib/doctor.mjs

@@ -94,6 +94,28 @@ function astHelperCheck() {
 	};
 }
 
+// D-java-source-splice: combines the two real prerequisites `bskel patch propose --kind
+// java-source-splice` needs beyond the base install -- the AST helper (reuses
+// detectAstHelperAvailable(), same function astHelperCheck() and the real command both call, so
+// this can never disagree with them) AND a recognized build command (detectBuildCommand()) to run
+// the compile postcondition against. Either missing means the whole kind is unusable, so this
+// check fails if EITHER is unavailable, naming which one(s).
+function javaSourceSpliceCheck(root) {
+	const ast = detectAstHelperAvailable();
+	const build = root ? detectBuildCommand(root) : null;
+	const ok = ast.available && build !== null;
+	const missing = [];
+	if (!ast.available) missing.push(`AST helper (${ast.reason})`);
+	if (!build) missing.push('a recognized build command (gradlew/pom.xml/package.json)');
+	return {
+		name: 'java-source-splice prerequisites',
+		required: false,
+		ok,
+		detail: ok ? `ready (build tool: ${build.tool})` : missing.join('; '),
+		remediation: ok ? null : `${missing.join('; ')} -- only needed for \`bskel patch propose --kind java-source-splice\`, never for the base install.`,
+	};
+}
+
 // D5: sourced from stack/catalog/*.yml's own `runtime.requires` field (schemas/stack-choice.
 // schema.json) rather than a hardcoded ["curl", "ngrok"] list here -- a future catalog entry
 // declares its own runtime binaries and doctor picks them up with zero code changes, the same
@@ -187,6 +209,7 @@ export function computeDoctorChecks(root, { workflow = null } = {}) {
 	}
 	if (workflow === null || workflow === 'handles') {
 		checks.push(astHelperCheck());
+		checks.push(javaSourceSpliceCheck(root));
 	}
 	if (root && (workflow === null || workflow === 'stack')) {
 		checks.push(...stackToolChecks(root));

package/lib/exit-codes.mjs

@@ -39,6 +39,23 @@ export const EXIT_CODES = Object.freeze({
 	// can find -- distinct from HANDLES_CONFLICT(15), which is about a GENERATED file diverging;
 	// this is about a hand-written file bskel never touches lacking an annotation it can't add.
 	HANDLES_REGISTRATION_GAP: 21,
+	// D-attestation-payload-completeness (K5): `attest verify`'s OPT-IN assertions (--expect-head /
+	// --max-age-minutes / --reject-dirty) failing on a document whose signature is genuinely VALID.
+	// Deliberately not a reuse of CHECK_FAILED(1): D-gate-attestation-signing's shipped contract is
+	// that exit 1 means, and only ever means, "the signature does not verify". Folding "authentic
+	// but not what you asked for" into the same number would destroy exactly the distinction that
+	// entry was written to preserve.
+	ATTESTATION_ASSERTION_FAILED: 22,
+	// D-resolver-policy-contract (PC9): `handles emit` refusing to proceed (without --force
+	// --reason) because at least one resource's fetch/patch authorization could not be safely
+	// auto-derived (see plan.mjs's derivePolicy() refusal ladder) -- an AuthorizationPolicy.java
+	// interface was still written (the human needs to see it), but nothing implements it yet, so
+	// the target app will not start once this resolver's bean is wired. Not a reuse of
+	// HANDLES_REGISTRATION_GAP(21), which is about a hand-written file lacking an annotation bskel
+	// can't add; this is about a generated file that is itself an unresolved authorization decision.
+	// Orthogonal to --enforce-registry (that axis produces 404s; this one produces 403s/boot
+	// failures) -- unconditional, not gated on enforceRegistry.
+	HANDLES_UNRESOLVED_POLICY: 23,
 });
 
 // `reason` values a `sbf.cli-diagnostic/1` envelope (lib/cli.mjs) can carry. Deliberately does

package/lib/gate-definitions.mjs

@@ -65,6 +65,23 @@ const OTHER_FEATURE_CONTRACT_PREFIX = 'other_feature_contract:';
 // specifically rather than reported as a generic "stale".
 const APPLIED_TARGET_PREFIX = 'applied_target:';
 const TRANSACTION_RECORD_PREFIX = 'transaction_record:';
+// D-cross-feature-impact-graph: same OTHER_FEATURE_*_PREFIX narrowing convention as
+// `cross_feature` above -- one pair of keys per OTHER feature the LAST persisted impact-report.json
+// actually named (either as an outbound downstream or an inbound upstream), not every feature in
+// the repo. Same accepted limitation: a brand-new counterparty is only caught at the next explicit
+// `bskel impact check --all` (see D-cross-feature-impact-graph's D4/D7 in DECISIONS.md).
+const IMPACT_DOWNSTREAM_DEPS_PREFIX = 'impact_downstream_deps:';
+const IMPACT_UPSTREAM_RESOLUTION_PREFIX = 'impact_upstream_resolution:';
+// D-cross-feature-impact-graph: path builders duplicated here rather than imported from
+// lib/impact-surface.mjs/lib/impact.mjs -- importing either would close a real circular-import
+// loop (gate-definitions.mjs -> lib/impact.mjs -> lib/impact-graph.mjs ->
+// lib/field-dependencies.mjs -> lib/gates.mjs -> gate-definitions.mjs), the SAME tradeoff
+// TARGET_FIELD_FILE_PREFIX's own header comment above already accepts for a two-line duplication
+// rather than a real coupling. If any of these three literal filenames ever changes, this must
+// change with it.
+const impactBaselineFilePath = (root, featureId) => specPath(root, featureId, 'impact-baseline.json');
+const impactReportFilePath = (root, featureId) => specPath(root, featureId, 'impact-report.json');
+const impactResolutionFilePath = (root, featureId) => specPath(root, featureId, 'impact-resolution.json');
 
 // The preflight and stack gates are repo-scoped, not feature-scoped -- preflight runs before a
 // feature_id exists at all, and a stack choice is a project-wide decision, not per-feature.
@@ -295,6 +312,47 @@ export const GATE_DEFINITIONS = Object.freeze({
 			return inputs;
 		},
 	},
+	// D-cross-feature-impact-graph: a change to THIS feature's own public surface (operations,
+	// resources, declared-dependency fields) that a downstream feature is provably wired to, with
+	// no recorded disposition yet. Complements `dependencies` above (which blocks the DOWNSTREAM
+	// side when what it depends on moves) by blocking the UPSTREAM side -- the feature that
+	// CHANGED, which is Codex's literal ask ("the next gate identifies downstream features and
+	// requires an explicit disposition"). Deliberately NOT a hard prerequisite of `handles emit`
+	// (see D7 in DECISIONS.md, citing this repo's own real CI incident from the `cross_feature`
+	// gate's identical mistake) -- gated only at `bskel verify`.
+	//
+	// recompute() is intentionally the cheapest possible: pure sha256File() over three already-
+	// persisted files plus the SAME artifacts `contract`/`dependencies`/`scan` already hash, never
+	// lib/impact-graph.mjs's buildImpactGraph() (real work -- O(features x artifacts) file reads,
+	// kept entirely out of the fast verify/require path, only ever called from `bskel impact
+	// check`/`export`). This is also what T6 (test/gate-definitions.test.mjs) asserts: this
+	// module's own transitive import closure contains no node:http/node:child_process/pg, and
+	// calling recompute() twice over an unchanged tree returns byte-identical inputs.
+	impact: {
+		name: 'impact',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		recompute: (root, featureId) => {
+			const inputs = {
+				impact_baseline_hash: sha256File(impactBaselineFilePath(root, featureId)),
+				impact_report_hash: sha256File(impactReportFilePath(root, featureId)),
+				impact_resolution_hash: sha256File(impactResolutionFilePath(root, featureId)),
+				contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
+				dependencies_hash: sha256File(dependenciesPath(root, featureId)),
+				scan_report_hash: sha256File(specPath(root, featureId, 'brownfield-scan.json')),
+			};
+			const report = readJsonIfExists(impactReportFilePath(root, featureId));
+			const others = new Set([
+				...(report?.outbound ?? []).map((o) => o.downstream_feature),
+				...(report?.inbound ?? []).map((i) => i.upstream_feature),
+			]);
+			for (const other of others) {
+				inputs[`${IMPACT_DOWNSTREAM_DEPS_PREFIX}${other}`] = sha256File(dependenciesPath(root, other));
+				inputs[`${IMPACT_UPSTREAM_RESOLUTION_PREFIX}${other}`] = sha256File(impactResolutionFilePath(root, other));
+			}
+			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:
@@ -394,7 +452,12 @@ export const GATE_DEFINITIONS = Object.freeze({
 			const inputs = {};
 			for (const txn of listTransactions(root, featureId)) {
 				if (txn.status !== 'applied') continue; // only a LIVE edit is drift-risk
-				if (txn.kind === 'config-apply') {
+				// D-java-source-splice: a second filesystem-targeting kind, added to this explicit list
+				// deliberately -- NOT via a dynamic getPatchKind(txn.kind) lookup, which would make
+				// lib/gate-definitions.mjs import lib/patch-kinds.mjs and, transitively, `pg`
+				// (scanners/db/ddl-apply.mjs) into EVERY gate recomputation, the exact live-dependency-
+				// in-a-gate coupling this gate's own header comment already refuses.
+				if (txn.kind === 'config-apply' || txn.kind === 'java-source-splice') {
 					const abs = resolveWithinRoot(root, txn.target.file);
 					if (!abs) continue; // a path escaping the repo is not something this feature applied
 					inputs[`${APPLIED_TARGET_PREFIX}${txn.transaction_id}`] = sha256File(abs); // null == deleted -> stale
@@ -429,7 +492,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', 'rules', 'handles', 'stack', 'patch_transactions', 'conformance']);
+export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'impact', 'rules', 'handles', 'stack', 'patch_transactions', 'conformance']);
 
 export function getGateDefinition(name) {
 	return Object.hasOwn(GATE_DEFINITIONS, name) ? GATE_DEFINITIONS[name] : null;

package/lib/gate-export.mjs

@@ -0,0 +1,199 @@
+// D-attestation-payload-completeness: pure report-construction logic for `bskel gate export`,
+// pulled out of bin/bskel.mjs so it is unit-testable without spawning a CLI process -- the same
+// split lib/verify.mjs and lib/gates.mjs already follow (CLI stays thin, real logic lives in lib/).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GATE_NAMES, gateScopeId } from './gate-definitions.mjs';
+import { collectGateStatuses } from './verify.mjs';
+import { getGate, historyPath } from './state.mjs';
+import { requireNamedGate } from './gates.mjs';
+import { sha256File } from './fsutil.mjs';
+import { specPath, sbfPath } from './paths.mjs';
+import { crossFeatureReportPath, crossFeatureResolutionPath } from './cross-feature-collisions.mjs';
+import { dependenciesPath } from './field-dependencies.mjs';
+import { impactBaselinePath } from './impact-surface.mjs';
+import { impactReportPath, impactResolutionPath } from './impact.mjs';
+import { manifestPath } from './handles-manifest.mjs';
+import { currentBranch, headSha, headTreeSha, worktreeStatus } from './repo.mjs';
+import { validateAgainstSchema } from './schema-validate.mjs';
+import { CANONICALIZATION_ID } from './attest.mjs';
+
+export const EXPORT_SCHEMA_VERSION = 'sbf.gate-export/3';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(__dirname, '..');
+
+let cachedToolVersion = null;
+// D-attestation-payload-completeness (K2): backend-skeleton's OWN package.json (this tool's
+// version), never the TARGET repo's -- resolved from this module's own file location, the same
+// derivation bin/bskel.mjs's SKILL_ROOT already uses. Memoized: it cannot change within one
+// process, and building one report already calls `sha256File`/git a dozen times.
+export function toolVersion() {
+	if (cachedToolVersion === null) {
+		cachedToolVersion = JSON.parse(fs.readFileSync(path.join(SKILL_ROOT, 'package.json'), 'utf8')).version;
+	}
+	return cachedToolVersion;
+}
+
+// S4 (D-gate-history), moved here from bin/bskel.mjs so both cmdGateHistory and
+// buildGateExportReport read history through one implementation instead of two copies that could
+// drift. Reads the append-only .sbf/<feature>.history.jsonl -- a corrupt/invalid line is skipped
+// with a warning, not a hard failure, matching JSONL's own resilience rationale (see
+// lib/state.mjs's appendGateEvent).
+export function readGateHistory(root, featureId, gateName, { onWarning } = {}) {
+	const file = historyPath(root, featureId);
+	if (!fs.existsSync(file)) return [];
+	const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+	const events = [];
+	for (const [i, line] of lines.entries()) {
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			onWarning?.(`${file}:${i + 1}: not valid JSON, skipped`);
+			continue;
+		}
+		const { ok, errors } = validateAgainstSchema('gate-event.schema.json', parsed);
+		if (!ok) {
+			onWarning?.(`${file}:${i + 1}: does not match schemas/gate-event.schema.json, skipped`, errors);
+			continue;
+		}
+		if (parsed.gate === gateName) events.push(parsed);
+	}
+	return events;
+}
+
+// D-attestation-payload-completeness (K2/K8): the ONE place an attestation-bound artifact is
+// declared -- adding a future artifact means adding one line here, the same single-source-of-
+// truth argument D-gate-definitions made for GATE_NAMES. Each value is (root, featureId) => an
+// absolute path; `test/gate-export-report.test.mjs` asserts this key set equals
+// `schemas/gate-export.schema.json`'s own `artifacts.properties` key set, so the two cannot drift.
+export const ARTIFACT_SOURCES = Object.freeze({
+	scan_report_hash: (root, featureId) => specPath(root, featureId, 'brownfield-scan.json'),
+	spec_hash: (root, featureId) => specPath(root, featureId, 'spec.md'),
+	contract_hash: (root, featureId) => specPath(root, featureId, 'contracts', `${featureId}.schema.json`),
+	contract_resolution_hash: (root, featureId) => specPath(root, featureId, 'contracts', `${featureId}.resolution.json`),
+	openapi_snapshot_hash: (root, featureId) => specPath(root, featureId, 'contracts', `${featureId}.openapi.snapshot.json`),
+	cross_feature_report_hash: (root, featureId) => crossFeatureReportPath(root, featureId),
+	cross_feature_resolution_hash: (root, featureId) => crossFeatureResolutionPath(root, featureId),
+	dependencies_hash: (root, featureId) => dependenciesPath(root, featureId),
+	rules_source_hash: (root, featureId) => specPath(root, featureId, 'rules.yaml'),
+	rules_compiled_hash: (root, featureId) => specPath(root, featureId, 'rules', `${featureId}.rules.json`),
+	conformance_report_hash: (root, featureId) => specPath(root, featureId, 'observe', `${featureId}.conformance-report.json`),
+	handles_manifest_hash: (root) => manifestPath(root),
+	stack_record_hash: (root) => sbfPath(root, 'stack.json'),
+	// D-cross-feature-impact-graph (IG4): additive, sbf.gate-export/2 -> /3 -- a /2 attestation
+	// still verifies (K7's own promise), it just won't have these three keys.
+	impact_baseline_hash: (root, featureId) => impactBaselinePath(root, featureId),
+	impact_report_hash: (root, featureId) => impactReportPath(root, featureId),
+	impact_resolution_hash: (root, featureId) => impactResolutionPath(root, featureId),
+});
+
+export function collectArtifactHashes(root, featureId) {
+	const out = {};
+	for (const [key, resolvePath] of Object.entries(ARTIFACT_SOURCES)) {
+		out[key] = sha256File(resolvePath(root, featureId));
+	}
+	return out;
+}
+
+// D-attestation-payload-completeness (K2): forced/revoked decisions rolled up from the gate
+// records already in the payload -- zero new file reads. Waivers (contract_resolution/
+// cross_feature_resolution) are represented by presence+hash only, never embedded content: the
+// content is already bound via `artifacts` above, and embedding it again would duplicate that
+// binding while ballooning the payload for no new guarantee.
+export function collectDecisions(gatesById, artifacts) {
+	const forced = [];
+	const revoked = [];
+	for (const [gate, entry] of Object.entries(gatesById)) {
+		const record = entry.current;
+		if (!record) continue;
+		if (record.forced) forced.push({ gate, scope: entry.scope, reason: record.reason ?? null, at: record.at ?? null });
+		if (record.status === 'revoked') revoked.push({ gate, scope: entry.scope, reason: record.reason ?? null, at: record.at ?? null });
+	}
+	return {
+		forced,
+		revoked,
+		waiver_files: {
+			contract_resolution: { present: artifacts.contract_resolution_hash !== null, hash: artifacts.contract_resolution_hash },
+			cross_feature_resolution: { present: artifacts.cross_feature_resolution_hash !== null, hash: artifacts.cross_feature_resolution_hash },
+		},
+	};
+}
+
+// D-attestation-payload-completeness (K2/K3): pure derivation from `live` -- what a human or CI
+// actually greps for, so they read one line instead of walking every gate.
+export function buildVerdict(liveEntries) {
+	const blocking_gates = liveEntries.filter((g) => g.blocking).map((g) => g.gate);
+	const passing = liveEntries.filter((g) => g.status === 'pass' || g.status === 'pass (forced)').length;
+	return { blocking_gates, passing, total: liveEntries.length, ok: blocking_gates.length === 0 };
+}
+
+// D-attestation-payload-completeness (K2/K3): the report `bskel gate export` builds and (with
+// --sign) signs. `gates[name].live` is RECOMPUTED at export time via lib/verify.mjs's
+// collectGateStatuses() -- the exact same function `bskel verify` uses -- so a gate export and
+// `bskel verify` can never disagree about the same repo's current state. `gates[name].current`
+// stays the raw STORED record (unchanged from schema /1), so a reader sees both "what was last
+// written" and "what is honestly true right now" side by side.
+export function buildGateExportReport(root, featureId, { now = new Date(), dirtyAcknowledged = false, dirtyCap = 200 } = {}) {
+	const liveResults = collectGateStatuses(root, featureId, { getGate, requireNamedGate });
+	const liveByName = new Map(liveResults.map((g) => [g.gate, g]));
+
+	const gates = {};
+	for (const name of GATE_NAMES) {
+		const live = liveByName.get(name);
+		// collectGateStatuses()'s own `scope` field is the gate's DEFINITION scope type
+		// ('repo'|'feature'), not the resolved scope id -- gateScopeId() computes the real one
+		// (REPO_GATE_ID for a repo-scoped gate, or featureId itself), matching cmdGateExport's own
+		// pre-existing lookup exactly.
+		const scopeId = gateScopeId(name, featureId);
+		gates[name] = {
+			scope: scopeId,
+			current: getGate(root, scopeId, name),
+			history: readGateHistory(root, scopeId, name),
+			live: {
+				policy: live.policy,
+				status: live.status,
+				blocking: live.blocking,
+				ran: live.ran,
+				current_token: live.currentToken ?? null,
+				stale_reason: live.stale_reason ?? null,
+				changed_inputs: live.changed_inputs && live.changed_inputs.length > 0 ? live.changed_inputs : null,
+			},
+		};
+	}
+
+	const artifacts = collectArtifactHashes(root, featureId);
+	const decisions = collectDecisions(gates, artifacts);
+	const verdict = buildVerdict(Object.entries(gates).map(([gate, g]) => ({ gate, blocking: g.live.blocking, status: g.live.status })));
+
+	const status = worktreeStatus(root, { cap: dirtyCap });
+	const dirty = status === null ? null : status.count > 0;
+
+	return {
+		schema: EXPORT_SCHEMA_VERSION,
+		feature_id: featureId,
+		generated_at: now.toISOString(),
+		tool: {
+			name: 'bskel',
+			version: toolVersion(),
+			gate_names: [...GATE_NAMES],
+			canonicalization: CANONICALIZATION_ID,
+		},
+		git: {
+			branch: currentBranch(root),
+			head_sha: headSha(root),
+			dirty,
+			head_tree_sha: headTreeSha(root),
+			dirty_acknowledged: Boolean(dirtyAcknowledged),
+			dirty_file_count: status?.count ?? 0,
+			dirty_files_truncated: status?.truncated ?? false,
+			dirty_files: status?.entries ?? [],
+		},
+		artifacts,
+		gates,
+		decisions,
+		verdict,
+	};
+}