backend-skeleton 1.0.0-beta.1

package/lib/gate-definitions.mjs

@@ -0,0 +1,293 @@
+// S1: the single declared source of what a gate IS -- its scope, whether `bskel verify` treats
+// it as required, and how its token is recomputed from current repo state.
+//
+// WHY this module exists: before it, `bin/bskel.mjs`'s GATE_RECOMPUTERS (which gates get
+// written and how their tokens are computed) and `lib/verify.mjs`'s GATE_SPECS (which gates
+// `verify` reads and aggregates) were two hand-maintained lists. They drifted: `stack` was
+// registered in GATE_RECOMPUTERS but missing from GATE_SPECS, so `stack apply` could pass a
+// repo-scoped `stack` gate that `bskel verify` would never even look at. One list, consumed by
+// both the write side (lib/gates.mjs's passNamedGate/awaitNamedGateDisposition) and the read
+// side (lib/verify.mjs's collectGateStatuses), makes that specific class of drift structurally
+// impossible -- there is no second list left to fall out of sync.
+//
+// Each gate's token must be computed from the SAME function both when the gate is written
+// (pass) and when it's re-verified (require) -- otherwise "require" degenerates into comparing
+// stored data against itself, which can never detect drift. If HEAD moved, or spec.md changed,
+// or anything else in the gate's declared input set changed, the token mismatches and the gate
+// reports `stale` -- it cannot be satisfied once and then silently drift out of sync with
+// reality.
+import path from 'node:path';
+import { headSha, localDefaultBranch, remoteTrackingTip } from './repo.mjs';
+import { sha256File, fileMode, readJsonIfExists, resolveWithinRoot } from './fsutil.mjs';
+import { specPath, sbfPath } from './paths.mjs';
+import { ADAPTERS, adapterById } from '../scanners/registry.mjs';
+import { loadManifest } from './handles-manifest.mjs';
+
+// S2: prefix for stack's per-applied-file input keys -- lib/gates.mjs's diffInputs() compares
+// top-level keys only, so a manifest-shaped input (one hash per applied file) has to flatten
+// itself into distinctly-named keys here to let a stale report name the exact file that drifted.
+const APPLIED_FILE_PREFIX = 'applied_file:';
+// S6 (D-verify-integrity): content hashing alone is blind to a chmod-only change -- a
+// `chmod -x scripts/dev-tunnel.sh` leaves sha256File byte-identical, so the gate stayed `pass`
+// even though the script no longer runs. Tracked as a distinct key (not merged into the content
+// hash) so diffInputs() can name it specifically -- "the mode drifted" is a different, more
+// actionable report than a generic "stale".
+const APPLIED_FILE_MODE_PREFIX = 'applied_file_mode:';
+// S2 (D-gate-precision, continued): same flattened-manifest convention as APPLIED_FILE_PREFIX --
+// one key per file the adapter actually reads, so diffInputs() can name the exact file that
+// changed instead of a generic "stale".
+const SOURCE_FILE_PREFIX = 'source_file:';
+// S2 (D-gate-precision, part 2): same flattened-manifest convention -- one key per file belonging
+// to the DISPOSED module specifically (a narrower set than SOURCE_FILE_PREFIX's whole-adapter
+// read-set), so the `contract` gate stops being sensitive to every Java file in the repo.
+const MODULE_FILE_PREFIX = 'module_file:';
+
+// 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.
+// Both are stored under the same per-feature state-file mechanism using this reserved id.
+export const REPO_GATE_ID = '_repo';
+
+export const SCOPE = Object.freeze({ REPO: 'repo', FEATURE: 'feature' });
+
+// required               : `not_run` or `stale` (or anything else short of `pass`) always fails
+//                          `bskel verify`'s overall verdict.
+// required-when-present  : a gate that's never been run does not block verify (not every
+//                          feature needs UUID handles or a stack-choice decision) -- but once it
+//                          HAS run, every non-pass status (stale, awaiting_disposition, ...) is
+//                          still blocking. "Optional" means "not every feature needs this", not
+//                          "once run, its correctness stops mattering".
+export const VERIFY_POLICY = Object.freeze({
+	REQUIRED: 'required',
+	REQUIRED_WHEN_PRESENT: 'required-when-present',
+});
+
+export const GATE_DEFINITIONS = Object.freeze({
+	preflight: {
+		name: 'preflight',
+		scope: SCOPE.REPO,
+		verifyPolicy: VERIFY_POLICY.REQUIRED,
+		// D-preflight-freshness (S3): `origin_tip_sha` added alongside (not instead of) `head_sha`/
+		// `default_branch` -- D-gate-precision (S2) already decided this gate keeps `head_sha`, and
+		// removing it here would break the "a commit stales preflight too" assumption
+		// test/contract-cli.test.mjs and test/handles-ownership-cli.test.mjs already depend on.
+		// `remoteTrackingTip()` is purely local (`git rev-parse`, no fetch) -- `require` noticing
+		// this value moved only means something ELSE already fetched into this repo since the
+		// gate last passed; if nothing has, the value is unchanged and this check is a no-op. See
+		// D-preflight-freshness in DECISIONS.md for why that limited scope is honest, not a bug.
+		recompute: (root) => {
+			const defaultBranch = localDefaultBranch(root);
+			return { head_sha: headSha(root), default_branch: defaultBranch, origin_tip_sha: remoteTrackingTip(root, defaultBranch) };
+		},
+		// D-preflight-freshness (S3): the one "freshness policy" slot S1's own catalog entry asked
+		// for but never had a gate to fill. 30 minutes is not a guess -- derived from Team-IZ-
+		// Backend's actual `origin/develop` commit cadence (109 commits over 35.8 days: p10=3m,
+		// p25=25m, median=100m, p75=264m, p90=17h). Treating "P(the remote tip moves within the
+		// TTL window)" as an upper bound on "this pass is silently wrong by the time it's used",
+		// 30m -> 5.1%, 60m -> 9.4%, 24h -> 59.0% (making a day-long TTL meaningless). Re-derive for
+		// any repo with:
+		//   git log --first-parent --format=%ct origin/<default> | awk 'NR==1{p=$1;next}
+		//   {d=p-$1;if(d>=0)g[n++]=d;p=$1}END{s=0;for(i=0;i<n;i++)s+=g[i];ttl=1800;num=0;
+		//   for(i=0;i<n;i++)num+=(g[i]<ttl?g[i]:ttl);printf "P(moved within %dmin)=%.3f\n",
+		//   ttl/60,num/s}'
+		// See DECISIONS.md's D-preflight-freshness for the full table and reasoning.
+		freshness: { defaultMaxAgeMinutes: 30 },
+	},
+	// S2 (D-gate-precision, continued): head_sha is GONE -- it was a repo-wide commit proxy for
+	// "has the codebase moved since scanning?" that was simultaneously too broad (staled on any
+	// unrelated commit, e.g. a doc or Python edit when the adapter is java-spring) and too narrow
+	// (blind to an UNCOMMITTED edit -- confirmed live before this fix: editing a real controller's
+	// content without committing left `scan` reporting `pass`). Replaced with a precise, per-file
+	// content fingerprint of the adapter's own real read-set. Deliberately RE-DERIVED fresh via
+	// `adapter.listReadSet(root)` on every check, not re-hashed from the report's OWN persisted
+	// `files_read` list -- a stale persisted list would stay blind to a brand-NEW file the same way
+	// D-gate-precision's own rejected alternative (ii) already named ("a manifest built from the
+	// scan report's own matched files is structurally blind to a newly added colliding
+	// controller"). Still covers the scan report's own content hash (has disposition/re-scan
+	// changed it?) and spec.md's content hash if it exists yet (scan can run before a spec is
+	// written, so this may be null).
+	scan: {
+		name: 'scan',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED,
+		recompute: (root, featureId) => {
+			const reportPath = specPath(root, featureId, 'brownfield-scan.json');
+			const report = readJsonIfExists(reportPath);
+			const inputs = {
+				scan_report_hash: sha256File(reportPath),
+				spec_hash: sha256File(specPath(root, featureId, 'spec.md')),
+			};
+			// No report yet, an adapter this build no longer has, or one that predates
+			// listReadSet() (a hypothetical third-party adapter) -- fall back to the two hashes
+			// above only, same graceful-degradation shape lib/verify.mjs's checkResolverConflicts
+			// already established: never crash, never a false pass.
+			const adapter = report ? adapterById(ADAPTERS, report.adapter) : null;
+			if (adapter?.listReadSet) {
+				// Found live, not assumed: a generated resolver (O2) lives INSIDE the same
+				// src/main/java tree java-spring's listReadSet() globs -- without this exclusion,
+				// `handles emit` writing its own output would make `scan` newly "see" a file that
+				// didn't exist at scan time, indistinguishable from a human adding a real new
+				// controller, staling `scan` on every single `handles emit` run. O2's own
+				// generated-file registry (.sbf/handles-manifest.json) is the authoritative
+				// answer to "did backend-skeleton itself write this" -- reused here rather than a
+				// directory-name/filename-pattern guess. try/catch mirrors handlesManifestChecks():
+				// an unreadable manifest must not crash gate recomputation.
+				let generatedPaths;
+				try {
+					generatedPaths = new Set(Object.keys(loadManifest(root).files ?? {}));
+				} catch {
+					generatedPaths = new Set();
+				}
+				for (const rel of adapter.listReadSet(root)) {
+					if (generatedPaths.has(rel)) continue;
+					const abs = resolveWithinRoot(root, rel);
+					if (!abs) continue;
+					inputs[`${SOURCE_FILE_PREFIX}${rel}`] = sha256File(abs);
+				}
+			}
+			return inputs;
+		},
+	},
+	// The contract gate's token covers the emitted contract file's own hash (re-emitting after
+	// a re-scan invalidates it) and head_sha -- NOT the scan report's hash directly, since the
+	// contract is a derived artifact; if the scan changes but the contract hasn't been
+	// re-emitted, that should surface as "contract is out of date with scan", which is a
+	// judgment call for `bskel contract emit` to re-run, not something require silently papers
+	// over by trusting the old contract.
+	//
+	// A5: also covers the resolution (waiver) file's hash. A waiver is a human decision that lets
+	// a `partial` contract's outstanding warnings stop blocking `bskel verify` -- if that file is
+	// deleted or hand-edited, the gate must go stale the same way it would if the contract itself
+	// were tampered with; a gate that stays green after its waivers disappear underneath it is
+	// exactly the "pass in name only" failure mode this whole gate mechanism exists to prevent
+	// (see D1 in DECISIONS.md). `sha256File` returns null when the file doesn't exist, which is
+	// the common no-waivers case -- stable and fine as a token input.
+	//
+	// A1: also covers the OpenAPI reconciliation snapshot's hash, for the identical reason --
+	// path correction against a real OpenAPI document is only trustworthy for as long as the
+	// snapshot that recorded it is intact. `null` when `bskel contract emit` was never run with
+	// `--openapi-file` (the common case), which is stable and requires no special-casing here.
+	//
+	// S2 (D-gate-precision, part 2): head_sha is GONE, replaced by two PRECISE signals instead
+	// of the single opaque "upstream_token" this item's own earlier EXIT sketched -- an
+	// upstream_token equal to the scan gate's own token would inherit scan's deliberately
+	// whole-Java-tree-sensitive design (Part 1), reintroducing "any Java file anywhere stales
+	// this feature's contract" right back, which is exactly what per-feature narrowing means to
+	// avoid. `scan_report_hash` catches an explicit re-scan/re-disposition (including this
+	// module's own membership changing); `module_file:<relpath>` per-file hashes catch a content
+	// edit to an ALREADY-KNOWN file belonging to the DISPOSED module specifically (not the whole
+	// adapter read-set) -- the same "uncommitted change must be visible" property Part 1 already
+	// established for `scan`, one level down. Known, accepted limitation: a brand-new file added
+	// to the SAME already-disposed module, before the next explicit `bskel scan` re-run, is not
+	// caught by the per-file hashes (only `scan_report_hash`, at the next re-scan, catches it) --
+	// closing that precisely would mean re-running full module-assignment logic on every
+	// verify/gate-require call, real added cost for an edge case, not the common one.
+	contract: {
+		name: 'contract',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED,
+		recompute: (root, featureId) => {
+			const reportPath = specPath(root, featureId, 'brownfield-scan.json');
+			const report = readJsonIfExists(reportPath);
+			const inputs = {
+				scan_report_hash: sha256File(reportPath),
+				contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
+				resolution_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.resolution.json`)),
+				openapi_snapshot_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.openapi.snapshot.json`)),
+			};
+			const moduleName = report?.disposition?.module ?? report?.related_modules?.[0]?.module;
+			const mod = report?.related_modules?.find((m) => m.module === moduleName);
+			// DTOs deliberately excluded -- scanJavaSpring() stores them as bare class-name
+			// strings today, no `.file` field (Part 1's own named, out-of-scope gap).
+			for (const item of [...(mod?.controllers ?? []), ...(mod?.entities ?? []), ...(mod?.enums ?? [])]) {
+				if (!item.file) continue;
+				// related_modules[].{controllers,entities,enums}[].file are stored ABSOLUTE
+				// (unlike Part 1's own repo-relative files_read) -- confirmed live against a real
+				// scan report before writing this.
+				const rel = path.relative(root, item.file);
+				inputs[`${MODULE_FILE_PREFIX}${rel}`] = sha256File(item.file);
+			}
+			return inputs;
+		},
+	},
+	// Staleness = the generated Java (or the contract it was generated from) has moved since
+	// emit -- NOT "does the migration still match the DB schema" (unknowable without a live DB
+	// connection this tool deliberately never opens on its own, see D-migration-scope). Note
+	// this token does NOT cover specs/<id>/handles/migration.sql itself -- lib/verify.mjs's
+	// checkArtifacts() is the only thing that notices if that file goes missing (S6).
+	//
+	// S2 (D-gate-precision, part 2): head_sha dropped, no replacement needed -- contract_hash
+	// alone is already sufficient. `handles` is derived from the CONTRACT, not directly from
+	// source; now that `contract`'s own token is precise (above), contract_hash transitively
+	// carries that precision. `contract` is a REQUIRED gate, so bskel verify's overall verdict is
+	// already blocked whenever contract itself is stale -- `handles` reporting "pass" (its
+	// emitted Java still matches the currently-emitted contract) stays accurate even then.
+	handles: {
+		name: 'handles',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		recompute: (root, featureId) => ({
+			contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
+		}),
+	},
+	// Repo-scoped like preflight (a stack choice is a project-wide decision, not per-feature).
+	// Staleness here means "the applied files or the choice-of-catalog-entry are gone/changed",
+	// not "re-verify the tunnel is currently running" -- that's a runtime concern, not a gate.
+	// S2: the token now covers the CONTENT of every file the stack record says `stack apply` wrote,
+	// not just the record's own bytes. Before this, deleting or editing scripts/dev-tunnel.sh left
+	// stack.json byte-identical, so stack_record_hash never moved and the gate stayed `pass`
+	// forever -- while the comment right above claimed applied-file drift was covered. It now is.
+	// `head_sha` is deliberately gone: this gate's input set is precisely enumerated on disk (via
+	// `applied_files`), so a repo-wide "something, somewhere, moved" proxy adds nothing except
+	// staling the gate on every unrelated commit (D-gate-precision). The other four gates keep
+	// head_sha -- their real read-sets are not enumerable yet, see D-gate-precision's EXIT.
+	stack: {
+		name: 'stack',
+		scope: SCOPE.REPO,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		recompute: (root) => {
+			const recordPath = sbfPath(root, 'stack.json');
+			const record = readJsonIfExists(recordPath);
+			const inputs = { stack_record_hash: sha256File(recordPath) };
+			for (const rel of record?.applied_files ?? []) {
+				const abs = resolveWithinRoot(root, rel);
+				if (!abs) continue; // a path escaping the repo is not something `stack apply` wrote
+				inputs[`${APPLIED_FILE_PREFIX}${rel}`] = sha256File(abs); // null == deleted -> stale
+				inputs[`${APPLIED_FILE_MODE_PREFIX}${rel}`] = fileMode(abs); // null == deleted -> stale
+			}
+			return inputs;
+		},
+	},
+});
+
+// Explicit order (= workflow order), not `Object.keys(GATE_DEFINITIONS)` insertion order --
+// 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', 'contract', 'handles', 'stack']);
+
+export function getGateDefinition(name) {
+	return Object.hasOwn(GATE_DEFINITIONS, name) ? GATE_DEFINITIONS[name] : null;
+}
+
+// The typo-defense point. Before this, `bskel gate require scna` silently reported `not_run`
+// (exit 2) -- indistinguishable from "a real gate that just hasn't run yet" -- so a typo reads
+// as "not done" instead of "this gate doesn't exist", and a caller could wait forever for a
+// gate that will never pass because it was never real.
+export function requireGateDefinition(name) {
+	const def = getGateDefinition(name);
+	if (!def) {
+		throw new Error(`unknown gate "${name}" -- known gates: ${GATE_NAMES.join(', ')}`);
+	}
+	return def;
+}
+
+// Scope comes from the definition, not from whatever a caller happened to pass as --feature --
+// closes off the class of bug where a repo-scoped gate's write/read path depends on the caller
+// remembering to pass (or not pass) the right --feature value.
+export function gateScopeId(name, featureId) {
+	return requireGateDefinition(name).scope === SCOPE.REPO ? REPO_GATE_ID : featureId;
+}
+
+export function gateInputs(root, name, featureId) {
+	return requireGateDefinition(name).recompute(root, featureId);
+}

package/lib/gates.mjs

@@ -0,0 +1,263 @@
+// Gate primitives shared by every `bskel <verb>` that needs to read or write a gate.
+// A gate is "passed" only if a token recomputed from the CURRENT inputs matches the token
+// that was stored when the gate last passed. If HEAD moved, or spec.md changed, or anything
+// else in the gate's declared input set changed, the token mismatches and the gate reports
+// `stale` -- it cannot be satisfied once and then silently drift out of sync with reality.
+import { createHash } from 'node:crypto';
+import { getGate, setGate } from './state.mjs';
+import { getGateDefinition, gateScopeId, gateInputs } from './gate-definitions.mjs';
+import { EXIT_CODES } from './exit-codes.mjs';
+
+// D2: re-exported under these names (unchanged) from the single exit-code table in
+// lib/exit-codes.mjs -- every existing `EXIT.*` reference across bin/bskel.mjs and the test
+// suite keeps working unmodified.
+export const EXIT = Object.freeze({
+	PASS: EXIT_CODES.OK,
+	NOT_PASSED: EXIT_CODES.NOT_PASSED,
+	AWAITING_DISPOSITION: EXIT_CODES.AWAITING_DISPOSITION,
+	STALE: EXIT_CODES.STALE,
+});
+
+// S2: why a stale gate couldn't say WHICH input changed until now -- see diffInputs()/
+// explainStaleness() below.
+export const STALE_REASON = Object.freeze({
+	INPUTS_CHANGED: 'inputs_changed',
+	NO_RECORDED_INPUTS: 'no_recorded_inputs',
+	RECORDED_INPUTS_MISMATCH: 'recorded_inputs_mismatch',
+	UNKNOWN: 'unknown',
+	// D-preflight-freshness (S3): a gate whose token still matches current inputs, but whose pass
+	// is simply too OLD -- see checkFreshness() below.
+	TTL_EXPIRED: 'ttl_expired',
+	INVALID_TIMESTAMP: 'invalid_timestamp',
+});
+
+export function computeToken(inputs) {
+	const canonical = JSON.stringify(sortKeysDeep(inputs));
+	return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
+}
+
+function sortKeysDeep(value) {
+	if (Array.isArray(value)) return value.map(sortKeysDeep);
+	if (value && typeof value === 'object') {
+		return Object.fromEntries(
+			Object.keys(value).sort().map((key) => [key, sortKeysDeep(value[key])]),
+		);
+	}
+	return value;
+}
+
+// S2: `computeToken()` collapses an entire inputs object to one sha256 string -- once both sides
+// of a comparison are hashed down like that, there is nothing left to diff. Reporting exactly
+// which input changed requires comparing the PRE-hash objects, key by key, which is what this
+// does (given both objects, not gate state -- kept pure/fs-free so it's directly unit-testable).
+// Top-level keys only, by design: a gate whose real inputs are file-manifest-shaped (e.g. one
+// hash per applied file) must flatten them into prefixed keys in its own recompute() (see
+// `stack`'s `applied_file:<relpath>` convention in lib/gate-definitions.mjs) -- that's what lets
+// this diff name an exact file instead of just "some nested value changed".
+const ABSENT = Symbol('absent');
+
+export function diffInputs(storedInputs, currentInputs) {
+	const stored = storedInputs ?? {};
+	const current = currentInputs ?? {};
+	const keys = [...new Set([...Object.keys(stored), ...Object.keys(current)])].sort();
+	return keys.filter((key) => {
+		// A key present on only one side (a gate DEFINITION change -- an input added/removed by a
+		// bskel upgrade) must count as changed even when the other side's value is `null` (the
+		// common sha256File-on-a-missing-file case) -- comparing against `undefined` directly would
+		// let that collapse to "no diff" and report an empty changed_inputs list on a real change.
+		const a = Object.hasOwn(stored, key) ? JSON.stringify(sortKeysDeep(stored[key])) : ABSENT;
+		const b = Object.hasOwn(current, key) ? JSON.stringify(sortKeysDeep(current[key])) : ABSENT;
+		return a !== b;
+	});
+}
+
+function explainStaleness(record, currentInputs) {
+	if (!record.inputs || typeof record.inputs !== 'object') {
+		// A gate record written before S2 shipped -- still definitively stale (the token really did
+		// move), just without a pre-hash snapshot to diff against. The next real re-run of the
+		// underlying command writes a record WITH inputs, so this heals itself; there is no attempt
+		// to fabricate a retroactive snapshot (that would just fail the mismatch check below).
+		return { changed_inputs: null, stale_reason: STALE_REASON.NO_RECORDED_INPUTS };
+	}
+	if (computeToken(record.inputs) !== record.token) {
+		// The stored inputs snapshot doesn't even reproduce the token stored right next to it --
+		// e.g. .sbf state was hand-edited. Diffing against an unverified snapshot here would be a
+		// confident-sounding lie, so report the integrity failure instead of a key list.
+		return { changed_inputs: null, stale_reason: STALE_REASON.RECORDED_INPUTS_MISMATCH };
+	}
+	const changed = diffInputs(record.inputs, currentInputs);
+	// Unreachable by construction -- computeToken(record.inputs) matching record.token, plus
+	// currentToken having already failed to match record.token (the only place this is called
+	// from), means diffInputs must find at least one changed key. Kept as a defensive fallback so
+	// a future bug in either function degrades to "I don't know" instead of a confident empty list.
+	if (changed.length === 0) return { changed_inputs: [], stale_reason: STALE_REASON.UNKNOWN };
+	return { changed_inputs: changed, stale_reason: STALE_REASON.INPUTS_CHANGED };
+}
+
+// D-preflight-freshness (S3): a pass whose token still matches current inputs can still be too
+// OLD to trust -- e.g. preflight's `origin_tip_sha` input only moves if something else already
+// fetched into this repo; nothing forces that to happen on its own. Judged entirely separately
+// from diffInputs()/explainStaleness() above, which only ever compare input VALUES -- age lives
+// in the gate record's own `at` timestamp, never inside `inputs` itself (putting a timestamp
+// there would make every single require() call report a change, since "now" is never equal to
+// the recorded instant -- see D-preflight-freshness in DECISIONS.md, confirmed by direct
+// execution before this was written).
+//
+// S4 (D-gate-history): a FORCED record never inherits the underlying gate's own `def.freshness`
+// policy (e.g. preflight's 30-minute default) -- that policy exists to judge naturally-earned
+// evidence, not a human's explicit override. A forced pass only gets a TTL when the human asked
+// for one (`bskel gate force <name> --max-age-minutes N`, recorded the same way passGate already
+// records `evidence.freshness.max_age_minutes`) -- same "explicit, auditable" philosophy as
+// `--max-age-minutes 0` disabling preflight's own TTL.
+//
+// Returns null (fresh, or freshness not applicable) or `{ stale_reason, age_seconds,
+// max_age_seconds }`. Reads the max age from the PASS's own recorded evidence first (so a gate
+// that changes its default later doesn't retroactively judge an already-passed gate by a
+// different policy than the one it was passed under), falling back to the gate definition's
+// `defaultMaxAgeMinutes`. A max age of 0 (either source) disables the TTL entirely -- an explicit,
+// auditable choice (`bskel preflight --max-age-minutes 0`), not a silent bypass.
+function checkFreshness(def, record) {
+	const maxAgeMinutes = record.forced
+		? record.evidence?.freshness?.max_age_minutes
+		: (record.evidence?.freshness?.max_age_minutes ?? def?.freshness?.defaultMaxAgeMinutes);
+	if (!(maxAgeMinutes > 0)) return null;
+	const maxAgeSeconds = maxAgeMinutes * 60;
+	const passedAt = Date.parse(record.at);
+	if (!Number.isFinite(passedAt)) {
+		return { stale_reason: STALE_REASON.INVALID_TIMESTAMP, age_seconds: null, max_age_seconds: maxAgeSeconds };
+	}
+	// Clock rewind (a passed-at instant in the future) clamps to 0 rather than going negative --
+	// treated as "as fresh as possible", never as extra-stale.
+	const ageSeconds = Math.max(0, Math.round((Date.now() - passedAt) / 1000));
+	if (ageSeconds <= maxAgeSeconds) return null;
+	return { stale_reason: STALE_REASON.TTL_EXPIRED, age_seconds: ageSeconds, max_age_seconds: maxAgeSeconds };
+}
+
+// S2: `inputs` is stored alongside `token` (canonically sorted, same form the token was computed
+// from) -- purely additive, so this invariant holds for every record this module ever writes:
+// computeToken(record.inputs) === record.token. That invariant is what makes explainStaleness()'s
+// integrity check meaningful rather than a guess.
+export function passGate(repoRoot, featureId, gateName, inputs, evidence = {}) {
+	const token = computeToken(inputs);
+	return setGate(repoRoot, featureId, gateName, {
+		status: 'pass',
+		token,
+		inputs: sortKeysDeep(inputs),
+		at: new Date().toISOString(),
+		evidence,
+	});
+}
+
+export function awaitDispositionGate(repoRoot, featureId, gateName, inputs, evidence = {}) {
+	const token = computeToken(inputs);
+	return setGate(repoRoot, featureId, gateName, {
+		status: 'awaiting_disposition',
+		token,
+		inputs: sortKeysDeep(inputs),
+		at: new Date().toISOString(),
+		evidence,
+	});
+}
+
+// S4 (D-gate-history): `currentInputs` is now the gate's REAL current inputs (same shape
+// passGate() would bind to), not a synthetic {forced,reason} placeholder -- token/inputs bind to
+// what was actually true at force time, so a LATER input change (including HEAD moving, since
+// every gate but `stack` includes head_sha in its own inputs -- see D-gate-precision) makes this
+// record go stale exactly the way a real pass would, closing "a forced gate passes forever
+// regardless of changed inputs" without a separate commit-tracking mechanism. `maxAgeMinutes`
+// (opt-in, `bskel gate force <name> --max-age-minutes N`) is the OTHER independent axis --
+// checkFreshness() above never lets a forced record inherit the underlying gate's own TTL policy.
+export function forceGate(repoRoot, featureId, gateName, reason, currentInputs, { maxAgeMinutes = null } = {}) {
+	if (!reason || !reason.trim()) {
+		throw new Error('gate force requires --reason "..." -- every bypass must be auditable');
+	}
+	return setGate(repoRoot, featureId, gateName, {
+		status: 'pass',
+		token: computeToken(currentInputs),
+		inputs: sortKeysDeep(currentInputs),
+		at: new Date().toISOString(),
+		forced: true,
+		reason,
+		evidence: maxAgeMinutes != null ? { freshness: { max_age_minutes: maxAgeMinutes } } : {},
+	});
+}
+
+// S4 (D-gate-history): un-passes a gate with an explicit, auditable reason -- distinct from
+// "never ran" (`not_run`) so a human/agent reading `bskel gate show` can tell "this was
+// deliberately pulled back" from "nobody has checked this yet". `currentInputs`' token is stored
+// for schema consistency with every other record shape (state.schema.json requires `token`), not
+// because anything ever compares against it -- requireGate() short-circuits on `status !==
+// 'pass'`/`'awaiting_disposition'` before token comparison would even run.
+export function revokeGate(repoRoot, featureId, gateName, reason, currentInputs) {
+	if (!reason || !reason.trim()) {
+		throw new Error('gate revoke requires --reason "..." -- every revocation must be auditable');
+	}
+	return setGate(repoRoot, featureId, gateName, {
+		status: 'revoked',
+		token: computeToken(currentInputs),
+		at: new Date().toISOString(),
+		reason,
+	});
+}
+
+// Recomputes the token from `currentInputs` and compares it to what's on disk.
+// Returns { code, status, record } where code is one of EXIT.*.
+export function requireGate(repoRoot, featureId, gateName, currentInputs) {
+	const record = getGate(repoRoot, featureId, gateName);
+	if (!record) {
+		return { code: EXIT.NOT_PASSED, status: 'not_run', record: null };
+	}
+	if (record.status === 'awaiting_disposition') {
+		return { code: EXIT.AWAITING_DISPOSITION, status: 'awaiting_disposition', record };
+	}
+	if (record.status !== 'pass') {
+		// S4: covers 'revoked' (and anything else non-pass) generically -- no separate branch
+		// needed, `record.status` is already the right string and NOT_PASSED the right code.
+		return { code: EXIT.NOT_PASSED, status: record.status, record };
+	}
+	// S4: forced records now flow through the SAME staleness/freshness pipeline as a real pass --
+	// no more early-return special case. `token`/`inputs` were bound to the real current inputs at
+	// force time (forceGate() above), so this naturally catches "the input this was forced past
+	// has since changed"; checkFreshness() separately refuses to apply the underlying gate's own
+	// TTL policy to a forced record (see its own comment) so this doesn't silently start expiring
+	// forces that were never given an explicit --max-age-minutes.
+	const currentToken = computeToken(currentInputs);
+	if (currentToken !== record.token) {
+		return { code: EXIT.STALE, status: 'stale', record, currentToken, ...explainStaleness(record, currentInputs) };
+	}
+	// D-preflight-freshness (S3): checked only once the token has ALREADY matched -- an input
+	// that actually changed is always the more specific, more actionable answer, and takes
+	// priority over "also, it happens to be old".
+	const freshness = checkFreshness(getGateDefinition(gateName), record);
+	if (freshness) {
+		return { code: EXIT.STALE, status: 'stale', record, currentToken, changed_inputs: [], ...freshness };
+	}
+	return { code: EXIT.PASS, status: record.forced ? 'pass (forced)' : 'pass', record };
+}
+
+// S1: name-based layer over the primitives above. A caller that only knows a gate's NAME
+// (not its scope or its token inputs) can pass/await/require it without reaching into
+// lib/gate-definitions.mjs itself -- the scope and recomputed inputs come from the gate's own
+// declaration, so a call site can no longer hand-assemble the wrong inputs or write to the
+// wrong scope by mistake.
+export function passNamedGate(repoRoot, gateName, featureId, evidence = {}) {
+	return passGate(repoRoot, gateScopeId(gateName, featureId), gateName, gateInputs(repoRoot, gateName, featureId), evidence);
+}
+
+export function awaitNamedGateDisposition(repoRoot, gateName, featureId, evidence = {}) {
+	return awaitDispositionGate(repoRoot, gateScopeId(gateName, featureId), gateName, gateInputs(repoRoot, gateName, featureId), evidence);
+}
+
+export function requireNamedGate(repoRoot, gateName, featureId) {
+	return requireGate(repoRoot, gateScopeId(gateName, featureId), gateName, gateInputs(repoRoot, gateName, featureId));
+}
+
+// S4: same named-layer pattern -- forceGate/revokeGate now need the gate's real current inputs
+// too (to bind the token), so they get the same treatment passGate/requireGate already have.
+export function forceNamedGate(repoRoot, gateName, featureId, reason, options = {}) {
+	return forceGate(repoRoot, gateScopeId(gateName, featureId), gateName, reason, gateInputs(repoRoot, gateName, featureId), options);
+}
+
+export function revokeNamedGate(repoRoot, gateName, featureId, reason) {
+	return revokeGate(repoRoot, gateScopeId(gateName, featureId), gateName, reason, gateInputs(repoRoot, gateName, featureId));
+}

package/lib/handles-manifest.mjs

@@ -0,0 +1,92 @@
+// O2: generated-file ownership manifest for `bskel handles emit`.
+//   WHY: emitHandles() used to write every generated file unconditionally, which could erase a
+//        hand-completed patchField() (D-resolver-scope) on a rerun, or silently hand a resolver
+//        to a second feature. See DECISIONS.md D-handles-ownership for the full design.
+//   Safety is CONTENT-derived, not manifest-derived: classifyFile() below only ever produces a
+//   false CONFLICT when the manifest is missing/stale, never a false overwrite -- the manifest is
+//   an optimization that reduces false-positive conflicts, not the safety mechanism itself.
+import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { sbfPath } from './paths.mjs';
+
+const MANIFEST_SCHEMA = 'sbf.handles-manifest/1';
+
+export function manifestPath(root) {
+	return sbfPath(root, 'handles-manifest.json');
+}
+
+export function loadManifest(root) {
+	const parsed = readJsonIfExists(manifestPath(root));
+	if (!parsed) return { schema: MANIFEST_SCHEMA, files: {} };
+	if (parsed.schema !== MANIFEST_SCHEMA) {
+		throw new Error(`${manifestPath(root)}: unrecognized handles-manifest schema "${parsed.schema}" (expected ${MANIFEST_SCHEMA})`);
+	}
+	return parsed;
+}
+
+// Sorted keys for stable diffs if a target repo commits this file. Callers are responsible for
+// only calling this when something in `manifest.files` actually changed -- classifyFile()'s
+// 'unchanged' action means "don't touch the manifest entry", not "resave it unchanged", so a
+// true no-op re-emit leaves this file byte-identical (see test/handles-manifest.test.mjs and the
+// e2e regression in test/handles-ownership-cli.test.mjs).
+export function saveManifest(root, manifest) {
+	const sortedFiles = Object.fromEntries(Object.keys(manifest.files).sort().map((k) => [k, manifest.files[k]]));
+	writeFileAtomic(manifestPath(root), `${JSON.stringify({ schema: manifest.schema, files: sortedFiles }, null, 2)}\n`);
+}
+
+// Every resolver stub's doc comment carries "... for feature <id>." -- ResourceResolverStub.java
+// .tmpl's javadoc says "({@code bskel handles emit})", resolver.py.tmpl's docstring (python-
+// fastapi, G4) says the same thing without the javadoc {@code} wrapper -- the `(?:...)?` groups
+// below make both optional so one regex matches either language's own doc-comment convention.
+// Recovering the feature id lets the adoption path (no manifest entry) re-render with the file's
+// OWN original feature id instead of the current run's, which is what makes a second feature
+// touching the same resource type a content-derived ownership-transfer WARN instead of a
+// guaranteed false CONFLICT.
+const RESOLVER_OWNER_MARKER_RE = /Generated by backend-skeleton \((?:\{@code )?bskel handles emit\}?\) for feature (.+?)\./;
+
+export function extractResolverOwnerFeatureId(content) {
+	if (typeof content !== 'string') return null;
+	const m = content.match(RESOLVER_OWNER_MARKER_RE);
+	return m ? m[1] : null;
+}
+
+// Shared prefix of every provider's resolver doc-comment marker -- used only to decide "did bskel
+// plausibly generate this file" for orphan detection (never for the safety-critical conflict
+// decision itself, which is classifyFile()'s job). Deliberately short (G4: no longer includes the
+// javadoc-specific "({@code bskel handles emit})" suffix) so it matches every provider's own
+// resolver doc-comment convention via plain substring inclusion, without needing a per-language
+// variant here.
+export const BSKEL_GENERATED_MARKER = 'Generated by backend-skeleton';
+
+// Pure decision logic -- fs-free, so it's directly unit-testable (test/handles-manifest.test.mjs)
+// without a CLI/git fixture. handles/emit.mjs does every actual fs read/hash and calls this once
+// per candidate file.
+//
+//   exists                 -- does the target file exist on disk right now
+//   diskHash                -- sha256 of current disk content, or null (must be null iff !exists)
+//   manifestEntryHash        -- manifest.files[relPath]?.generated_hash, or null if no entry
+//   freshRenderHash          -- sha256 of rendering the template with THIS run's inputs
+//   matchesPristineRender    -- true if disk content equals SOME valid pristine render of this
+//                               file (for infra: the fresh render, since infra has no per-feature
+//                               input; for a resolver: a render using the owner recovered from its
+//                               own marker, which may differ from this run's featureId)
+//
+// Returns one of: 'create' | 'unchanged' | 'update' | 'adopt-unchanged' | 'adopt-update' | 'conflict'
+export function classifyFile({ exists, diskHash, manifestEntryHash, freshRenderHash, matchesPristineRender }) {
+	if (!exists) return 'create';
+	if (manifestEntryHash && diskHash === manifestEntryHash) {
+		// Provably untouched since bskel last wrote it -- safe to regenerate even if the fresh
+		// render differs (propagates a template upgrade or a live-derived value like
+		// requiredAuthority() picking up a controller's @PreAuthorize change; see D-security-7).
+		return freshRenderHash === diskHash ? 'unchanged' : 'update';
+	}
+	if (!manifestEntryHash) {
+		// No provenance record (first encounter after this feature shipped, a fresh checkout, or
+		// a repo that doesn't commit .sbf/) -- fall back to content comparison. This can only ever
+		// produce a false CONFLICT (fail-closed), never a false overwrite.
+		if (!matchesPristineRender) return 'conflict';
+		return freshRenderHash === diskHash ? 'adopt-unchanged' : 'adopt-update';
+	}
+	// A manifest entry exists but disk content has moved away from what it recorded -- a human
+	// (or something else) touched this file since bskel last wrote it.
+	return 'conflict';
+}