backend-skeleton 1.0.0-beta.1

package/lib/doctor.mjs

@@ -0,0 +1,200 @@
+// D5: `bskel doctor`'s check computation, separated from CLI glue (bin/bskel.mjs) the same way
+// D1's lib/workflow.mjs separates `computeWorkflowState()` from its cmdStatus/cmdNext callers --
+// this stays pure enough to unit test without spawning the CLI, and bin/bskel.mjs just renders
+// whatever this returns.
+import { execFileSync } from 'node:child_process';
+import { detectBuildCommand } from './verify.mjs';
+import { listCatalogChoices, loadCatalogEntry } from '../stack/apply.mjs';
+import { detectAstHelperAvailable } from '../handles/providers/java-spring/ast-bridge.mjs';
+
+// D5: the three workflows that have tool requirements beyond "git + a supported Node runtime"
+// (every workflow needs those two -- preflight/contract don't need anything ELSE, so they're
+// deliberately not `--workflow` choices; see D-doctor-workflow in DECISIONS.md).
+export const WORKFLOWS = Object.freeze(['scan', 'handles', 'stack']);
+
+// P1 (D-npm-packaging): this used to be {major:20, minor:11} for contracts/validate.mjs's
+// `import.meta.dirname` (Node >=20.11.0 backported / >=21.2.0) -- the only thing in this
+// codebase's runtime code that needed anything above plain ES2022/Node 18. P1 fixed that one call
+// site to use the portable `path.dirname(fileURLToPath(import.meta.url))` pattern every other
+// file already used, so the real floor dropped back to package.json's own declared ">=18" --
+// confirmed by grepping the whole runtime tree (lib/, bin/, contracts/, scanners/, handles/,
+// stack/) for every other recent-ES-addition pattern (structuredClone, Object.groupBy,
+// .toSorted/.toReversed/.toSpliced/.with, Array.fromAsync, Promise.withResolvers, global fetch,
+// node:sqlite, using/await using, import.meta.resolve, AbortSignal.timeout/.any) -- zero hits.
+// `Object.hasOwn` (used throughout) is ES2022/Node 16.9+, and top-level await (scanners/
+// registry.mjs, handles/registry.mjs) is ESM/Node 14.8+ -- both already well under 18.
+// P3 (D-fixture-corpus): exported so test/ci-workflow.test.mjs can assert the CI Node matrix
+// never drifts below this floor -- the single source of truth for "what Node version does this
+// tool actually need", not a second hand-copied number in the workflow file.
+export const MIN_NODE = { major: 18, minor: 0 };
+
+function nodeVersionOk(versionString) {
+	const [major, minor] = versionString.split('.').map(Number);
+	return major > MIN_NODE.major || (major === MIN_NODE.major && minor >= MIN_NODE.minor);
+}
+
+function binaryCheck(name, { required, remediation }) {
+	let ok = true;
+	let detail = '';
+	try {
+		execFileSync(name, ['--version'], { stdio: 'pipe' });
+	} catch {
+		ok = false;
+		detail = 'not found on PATH';
+	}
+	return { name: `binary: ${name}`, required, ok, detail, remediation: ok ? null : remediation };
+}
+
+function nodeVersionCheck() {
+	const version = process.versions.node;
+	const ok = nodeVersionOk(version);
+	return {
+		name: 'Node version',
+		required: true,
+		ok,
+		detail: `running v${version}`,
+		remediation: ok ? null : (
+			`this Node runtime (v${version}) is older than what backend-skeleton needs ` +
+			`(>=${MIN_NODE.major}.${MIN_NODE.minor}.0, matching package.json's declared engines floor). Upgrade Node.`
+		),
+	};
+}
+
+// D5: not a PATH-binary check -- `bskel` itself never invokes `java`/`gradle`/`mvn` directly.
+// `handles emit`/`handles plan` only WRITE .java files, never compile them; the only place this
+// project runs a build at all is `bskel verify --build`, which needs a recognized WRAPPER SCRIPT
+// present in the target repo (see lib/verify.mjs's detectBuildCommand -- reused here, not
+// reimplemented, so this check and `verify --build` can never disagree about what "found" means).
+function buildWrapperCheck(root) {
+	const build = detectBuildCommand(root);
+	return {
+		name: 'build wrapper',
+		required: false,
+		ok: Boolean(build),
+		detail: build ? `${build.tool} (${build.cmd})` : 'no gradlew, pom.xml, or package.json found at repo root',
+		remediation: build ? null : (
+			'no recognized build wrapper found -- `bskel verify --build` will have nothing to run. ' +
+			'Not required for `handles emit` itself, which only writes .java files and never compiles them.'
+		),
+	};
+}
+
+// A2 Phase 2 (D-java-ast-helper): optional -- `bskel handles plan` works fully without this,
+// `--ast` is the one thing that needs it. Reuses the exact same detection function `--ast`'s own
+// upfront check calls, so `doctor` and the real command can never disagree about availability.
+function astHelperCheck() {
+	const detection = detectAstHelperAvailable();
+	return {
+		name: 'AST helper (java-spring --ast)',
+		required: false,
+		ok: detection.available,
+		detail: detection.available ? 'ready' : detection.reason,
+		remediation: detection.available ? null : `${detection.reason} -- only needed for \`bskel handles plan --ast\`, 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
+// "fill a schema field, it applies globally" pattern D7/G1 already established for this project.
+function stackToolChecks(root) {
+	const neededBy = new Map(); // binary -> [choiceId, ...]
+	for (const id of listCatalogChoices()) {
+		let entry;
+		try {
+			entry = loadCatalogEntry(id);
+		} catch {
+			continue; // a malformed catalog entry is `stack apply`'s problem to report, not doctor's
+		}
+		for (const bin of entry.runtime?.requires ?? []) {
+			if (!neededBy.has(bin)) neededBy.set(bin, []);
+			neededBy.get(bin).push(id);
+		}
+	}
+	return [...neededBy.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([bin, ids]) => (
+		binaryCheck(bin, {
+			required: false,
+			remediation: `needed by the bootstrap script \`bskel stack apply --apply\` writes for: ${ids.join(', ')} ` +
+				'-- not by `bskel stack apply` itself. Install before running the generated script.',
+		})
+	));
+}
+
+export function computeDoctorChecks(root, { workflow = null } = {}) {
+	if (workflow !== null && !WORKFLOWS.includes(workflow)) {
+		throw new Error(`unknown workflow "${workflow}" -- known workflows: ${WORKFLOWS.join(', ')}`);
+	}
+
+	const checks = [
+		{
+			name: 'inside a git repo',
+			required: true,
+			ok: Boolean(root),
+			detail: root ?? 'not a git repo',
+			remediation: root ? null : 'run this from inside a git repository',
+		},
+		binaryCheck('git', { required: true, remediation: 'install git (https://git-scm.com) and ensure it is on PATH' }),
+		nodeVersionCheck(),
+	];
+
+	// gh: only ever consulted by preflight's 3-way default-branch cross-check, and that script
+	// already `command -v gh`-guards it -- preflight does not hard-fail without it, so this is
+	// never workflow-scoped (there's no `--workflow preflight`) and never required. Shown only in
+	// the unscoped "everything" view.
+	if (workflow === null) {
+		checks.push(binaryCheck('gh', {
+			required: false,
+			remediation: 'optional -- only used for the 3-way default-branch cross-check in `bskel preflight` (already soft-guarded there); install with `gh` CLI (https://cli.github.com) if you want that extra check.',
+		}));
+	}
+
+	// rg: both scanner adapters use it directly for scan, and the java-spring handles provider's
+	// detectBasePackage() (handles/providers/java-spring/plan.mjs) shells out to it independently
+	// during `handles plan`/`handles emit` -- required for both, even though only java-spring.mjs's
+	// own call site lacks a try/catch (a separate, known, out-of-scope issue surfaced via that
+	// adapter's own diagnostics()).
+	if (workflow === null || workflow === 'scan' || workflow === 'handles') {
+		checks.push(binaryCheck('rg', { required: true, remediation: 'install ripgrep (`brew install ripgrep`) -- required for `bskel scan` and `bskel handles emit`.' }));
+	}
+
+	// G4: not required for bskel itself (the python-fastapi provider only ever WRITES .py files,
+	// never executes them) -- this is purely for a human/CI wanting to run this project's own
+	// test/handles-python-codec.test.mjs, which DOES require it to round-trip-verify the generated
+	// codec.py against the JS reference implementation.
+	if (workflow === null || workflow === 'handles') {
+		checks.push(binaryCheck('python3', {
+			required: false,
+			remediation: 'only needed for this project\'s own cross-language codec test (test/handles-python-codec.test.mjs) -- `bskel handles emit` itself never invokes python3.',
+		}));
+	}
+
+	// D-handles-providers (G4) follow-up: same asymmetry as python3 above -- not required for
+	// bskel itself (`handles emit` never invokes javac; the java-spring provider only ever WRITES
+	// .java files), purely for a human/CI wanting to run this project's own
+	// test/handles-java-codec.test.mjs, which DOES require it to round-trip-verify the rendered
+	// HandleCodec.java against the JS reference implementation. That test is mandatory, unlike
+	// this doctor check -- see its own header comment for why.
+	if (workflow === null || workflow === 'handles') {
+		checks.push(binaryCheck('javac', {
+			required: false,
+			remediation: 'only needed for this project\'s own cross-language codec test (test/handles-java-codec.test.mjs) -- `bskel handles emit` itself never invokes javac.',
+		}));
+	}
+
+	if (root && (workflow === null || workflow === 'handles')) {
+		checks.push(buildWrapperCheck(root));
+	}
+	if (workflow === null || workflow === 'handles') {
+		checks.push(astHelperCheck());
+	}
+	if (root && (workflow === null || workflow === 'stack')) {
+		checks.push(...stackToolChecks(root));
+	}
+
+	// The G1 adapter-diagnostics block (specificity/capabilities/detect result/diagnostics) is
+	// scan's own readiness story, and handles' codegen readiness depends on exactly the same
+	// adapter capabilities (resource.fetch/codegen.handles) -- not relevant to stack.
+	const showAdapters = workflow === null || workflow === 'scan' || workflow === 'handles';
+
+	return { checks, showAdapters };
+}

package/lib/exit-codes.mjs

@@ -0,0 +1,67 @@
+// D2 (D-cli-contract): the single, definitive table of every exit code `bskel` (and the bash
+// scripts it shells out to) can produce. Existed before this only as 4 values in `lib/gates.mjs`'s
+// own `EXIT` plus ~6 more scattered as literals across `bin/bskel.mjs`, plus 3 more (11/12/13)
+// defined only inside `scripts/preflight-base-ref.sh` with no JS-side reference at all.
+//
+// Numbers are NOT renumbered here -- they are already a public contract: SKILL.md documents them
+// in several places and existing tests assert specific values (`gate require`/`scan`/`handles
+// emit`/`contract validate` etc across 6+ test files). This table only gives the existing numbers
+// one name each and one place to look them up. See D-cli-contract in DECISIONS.md.
+export const EXIT_CODES = Object.freeze({
+	OK: 0,
+	CHECK_FAILED: 1,
+	NOT_PASSED: 2,
+	AWAITING_DISPOSITION: 3,
+	STALE: 4,
+	NOT_A_REPO: 10,
+	STALE_BASE: 11,
+	WRONG_DEFAULT: 12,
+	DIRTY: 13,
+	BAD_ARGS: 14,
+	HANDLES_CONFLICT: 15,
+	LOW_CONFIDENCE_SCAN: 16,
+	MISSING_CAPABILITY: 17,
+	REFRESH_FAILED: 18,
+});
+
+// `reason` values a `sbf.cli-diagnostic/1` envelope (lib/cli.mjs) can carry. Deliberately does
+// NOT introduce new exit codes for the two different things exit 2 has always meant ("a gate
+// this command depends on hasn't passed" vs "a referenced resource/adapter/provider doesn't
+// exist") -- the number is the stable public contract (see above); `reason` is the "stable but
+// supplementary precision" layer on top of it. See D-cli-contract's WHY in DECISIONS.md for why
+// renumbering exit 2 was rejected.
+export const EXIT_REASONS = Object.freeze({
+	BAD_ARGS: EXIT_CODES.BAD_ARGS,
+	NOT_A_REPO: EXIT_CODES.NOT_A_REPO,
+	MISSING_CAPABILITY: EXIT_CODES.MISSING_CAPABILITY,
+	GATE_AWAITING_DISPOSITION: EXIT_CODES.AWAITING_DISPOSITION,
+	GATE_STALE: EXIT_CODES.STALE,
+	// D-preflight-freshness (S3): `bskel preflight` itself failed to refresh from the remote and
+	// no --offline/--no-fetch was given -- a distinct failure class from GATE_STALE (which means
+	// "we successfully checked and it IS stale"), so it gets its own exit code rather than reusing
+	// STALE_BASE(11) or WRONG_DEFAULT(12), which would blur "we don't know" into "we know, and
+	// it's bad".
+	REFRESH_FAILED: EXIT_CODES.REFRESH_FAILED,
+	// all of the below share exit code NOT_PASSED (2) -- the reason is what tells them apart
+	GATE_NOT_PASSED: EXIT_CODES.NOT_PASSED,
+	MISSING_ARTIFACT: EXIT_CODES.NOT_PASSED,
+	// S5 (D-persistence-integrity): MISSING_ARTIFACT's sibling -- the file exists but fails its
+	// own declared schema (hand-edited or externally corrupted), a distinct case from "not there
+	// at all". Only used at the CLI-layer read helpers (loadScanReportOrExit/loadContract) that
+	// already own a fail() call for the sibling MISSING_ARTIFACT case; lib/state.mjs's own
+	// equivalent check throws a plain Error instead (an existing, separate convention -- see its
+	// own comment).
+	INVALID_ARTIFACT: EXIT_CODES.NOT_PASSED,
+	ADAPTER_UNAVAILABLE: EXIT_CODES.NOT_PASSED,
+	PROVIDER_UNAVAILABLE: EXIT_CODES.NOT_PASSED,
+	UNKNOWN_OPERATION: EXIT_CODES.NOT_PASSED,
+	SCAN_FAILED: EXIT_CODES.NOT_PASSED,
+	PLAN_FAILED: EXIT_CODES.NOT_PASSED,
+});
+
+// `scripts/preflight-base-ref.sh` defines STALE_BASE(11)/WRONG_DEFAULT(12)/DIRTY(13)/
+// REFRESH_FAILED(18, D-preflight-freshness/S3) itself (a standalone bash script, "reusable
+// outside this skill" per its own header comment -- it cannot import this module). Documented
+// here only so this table stays the one place a human looks up what a `bskel preflight` exit
+// code means; the script's own literals are the actual source of truth for these four values and
+// are not re-derived from here.

package/lib/featureid.mjs

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+
+export const FEATURE_ID_RE = /^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$/;
+
+export function isValidFeatureId(id) {
+	return typeof id === 'string' && FEATURE_ID_RE.test(id);
+}
+
+export function requireValidFeatureId(id) {
+	if (!isValidFeatureId(id)) {
+		throw new Error(`invalid feature_id "${id}" -- expected NNN-slug-words (e.g. 001-organization-management)`);
+	}
+	return id;
+}
+
+// The searchable words a feature_id itself contributes to a scan's term set, independent of
+// whatever spec.md may or may not say yet (scan can run before a spec exists).
+export function slugWords(featureId) {
+	return featureId.replace(/^[0-9]{3}-/, '').split('-').filter(Boolean);
+}
+
+// P2b (D-greenfield-parameters): exported (was module-private) so `new/params.mjs`'s
+// `--artifact-id` validator reuses the exact grammar `--slug` already enforces, rather than
+// declaring a second, subtly different one for the value `--artifact-id` defaults to.
+export const SLUG_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+// D-security-3: `gate require/force/show` accept `--feature <anything>` and pass it straight
+// into a path.join() (see lib/state.mjs) -- every OTHER feature-scoped command validates via
+// requireValidFeatureId() first, but the three gate commands originally didn't, so
+// `--feature ../../evil` could read/write a state file outside .sbf/. This accepts either the
+// repo-scoped sentinel or a real feature_id, so gate commands (the only ones that operate on
+// both scopes) can validate too. Found by the Codex security review.
+export function requireValidFeatureOrRepoId(id, repoSentinel) {
+	if (id === repoSentinel) return id;
+	return requireValidFeatureId(id);
+}
+
+export function requireValidSlug(slug) {
+	if (typeof slug !== 'string' || !SLUG_RE.test(slug)) {
+		throw new Error(`invalid slug "${slug}" -- expected lowercase-hyphenated words (e.g. organization-management)`);
+	}
+	return slug;
+}
+
+// Next NNN- prefix, one past whatever's already under specs/ (spec-kit's own numbering
+// convention -- reused rather than inventing a second one) -- 001 if specs/ doesn't exist yet.
+export function nextFeatureNumber(specsDir) {
+	if (!fs.existsSync(specsDir)) return '001';
+	const nums = fs.readdirSync(specsDir)
+		.map((name) => name.match(/^([0-9]{3})-/))
+		.filter(Boolean)
+		.map((m) => Number.parseInt(m[1], 10));
+	const next = nums.length > 0 ? Math.max(...nums) + 1 : 1;
+	return String(next).padStart(3, '0');
+}

package/lib/featurelifecycle.mjs

@@ -0,0 +1,205 @@
+// D6 (D-feature-lifecycle): everything beyond `feature init` -- list/show/rename/link/archive
+// over specs/<feature_id>/ and .sbf/feature-index.json. See DECISIONS.md for the full rename
+// blast-radius grounding and why `link` is index-only, never a state merge.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { specDir } from './paths.mjs';
+import { statePath, historyPath } from './state.mjs';
+import { loadManifest, saveManifest } from './handles-manifest.mjs';
+
+const FEATURE_SCHEMA = 'sbf.feature/1';
+const FEATURE_INDEX_SCHEMA = 'sbf.feature-index/1';
+
+export function featureIndexPath(root) {
+	return path.join(root, '.sbf', 'feature-index.json');
+}
+
+export function loadFeatureIndex(root) {
+	const file = featureIndexPath(root);
+	const parsed = readJsonIfExists(file);
+	if (!parsed) return { schema: FEATURE_INDEX_SCHEMA, by_uid: {} };
+	if (parsed.schema !== FEATURE_INDEX_SCHEMA) {
+		throw new Error(`${file}: unrecognized feature-index schema "${parsed.schema}" (expected ${FEATURE_INDEX_SCHEMA})`);
+	}
+	const { ok, errors } = validateAgainstSchema('feature-index.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${file}: does not match schemas/feature-index.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveFeatureIndex(root, index) {
+	const { ok, errors } = validateAgainstSchema('feature-index.schema.json', index);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid feature-index record:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(featureIndexPath(root), `${JSON.stringify(index, null, 2)}\n`);
+}
+
+function featureFilePath(root, featureId) {
+	return path.join(specDir(root, featureId), 'feature.json');
+}
+
+export function loadFeatureFile(root, featureId) {
+	const file = featureFilePath(root, featureId);
+	const parsed = readJsonIfExists(file);
+	if (!parsed) return null;
+	if (parsed.schema !== FEATURE_SCHEMA) {
+		throw new Error(`${file}: unrecognized feature schema "${parsed.schema}" (expected ${FEATURE_SCHEMA})`);
+	}
+	const { ok, errors } = validateAgainstSchema('feature.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${file}: does not match schemas/feature.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveFeatureFile(root, featureId, record) {
+	const { ok, errors } = validateAgainstSchema('feature.schema.json', record);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid feature record for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(featureFilePath(root, featureId), `${JSON.stringify(record, null, 2)}\n`);
+}
+
+// Scans specs/*/feature.json directly, not the index -- by_uid never held more than one id per
+// uid until this item, so it was never a "list every feature" source (lib/workflow.mjs's own
+// comment already established this). O6-style determinism: sorted by feature_id.
+export function listFeatures(root, { includeArchived = false } = {}) {
+	const specsRoot = path.join(root, 'specs');
+	if (!fs.existsSync(specsRoot)) return [];
+	const ids = fs.readdirSync(specsRoot, { withFileTypes: true })
+		.filter((d) => d.isDirectory())
+		.map((d) => d.name)
+		.sort();
+	const records = [];
+	for (const id of ids) {
+		let record;
+		try {
+			record = loadFeatureFile(root, id);
+		} catch {
+			continue; // a corrupt/foreign feature.json shouldn't take down `feature list` -- bskel status already surfaces read errors for the feature a user actually asked about
+		}
+		if (!record) continue; // a specs/ dir with no feature.json isn't a real feature
+		if (record.archived_at && !includeArchived) continue;
+		records.push(record);
+	}
+	return records;
+}
+
+export function currentFeatureIdForUid(index, uid) {
+	const ids = index.by_uid[uid];
+	return ids && ids.length > 0 ? ids[ids.length - 1] : null;
+}
+
+export function uidForFeatureId(index, featureId) {
+	for (const [uid, ids] of Object.entries(index.by_uid)) {
+		if (ids.includes(featureId)) return uid;
+	}
+	return null;
+}
+
+// True if `id` is already a real specs/ directory OR already appears anywhere in the index
+// (including a retired id from an earlier rename) -- a rename target must collide with neither.
+export function featureIdInUse(root, index, id) {
+	return fs.existsSync(specDir(root, id)) || uidForFeatureId(index, id) !== null;
+}
+
+function rewriteFeatureIdField(jsonPath, oldId, newId) {
+	const parsed = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+	if (parsed.feature_id !== oldId) return;
+	parsed.feature_id = newId;
+	writeFileAtomic(jsonPath, `${JSON.stringify(parsed, null, 2)}\n`);
+}
+
+// D6: the full migration a rename needs -- every featureId-keyed persisted artifact, traced by
+// direct exploration before writing this, not assumed: specs/<id>/ (the whole directory, plus 3
+// featureId-PREFIXED filenames inside contracts/ -- brownfield-scan.{json,md} use a fixed name,
+// not prefixed, so they move for free with the directory rename and need no rename here),
+// .sbf/<id>.json (filename AND its own feature_id field), .sbf/<id>.history.jsonl (filename
+// only -- gate-event lines never carry feature_id), .sbf/handles-manifest.json's resolver-entry
+// `owner` fields (`owner:'_repo'` infra entries are untouched -- not a feature id at all).
+//
+// Deliberately does NOT rewrite already-generated application code (a resolver .java/.py file's
+// own doc-comment keeps the OLD feature id baked in, and specs/<id>/handles/migration.sql keeps
+// the old id in its rendered SQL) -- cosmetic staleness, not a safety issue: classifyFile()'s
+// real conflict check is the manifest's content-hash, which IS updated here, and rewriting
+// already-generated files outside the normal emit path is exactly the class of thing this
+// project has repeatedly chosen not to do (D-migration-scope, D-config-patch).
+export function renameFeatureArtifacts(root, oldId, newId) {
+	const oldDir = specDir(root, oldId);
+	const newDir = specDir(root, newId);
+	fs.renameSync(oldDir, newDir);
+
+	// Rename featureId-prefixed filenames under contracts/ -- FILENAME ONLY, content is left
+	// byte-identical on purpose. Found live, not designed in from the start: an early draft also
+	// rewrote each file's own `feature_id` field, and a real `handles emit --check` against the
+	// just-renamed id immediately reported the contract gate as stale -- lib/gate-definitions.mjs's
+	// contract/handles gates hash these files' FULL CONTENT for their token (contract_hash/
+	// resolution_hash/openapi_snapshot_hash), so rewriting even one field inside them silently
+	// invalidates an already-passed gate's stored token, forcing a phantom re-verification of
+	// content that never actually changed. Same "cosmetic staleness accepted" principle already
+	// applied to a resolver's own doc-comment and migration.sql -- extended here to every
+	// gate-token-hashed artifact, not just already-generated application code.
+	const contractsDir = path.join(newDir, 'contracts');
+	if (fs.existsSync(contractsDir)) {
+		for (const name of fs.readdirSync(contractsDir)) {
+			if (!name.startsWith(`${oldId}.`)) continue;
+			fs.renameSync(path.join(contractsDir, name), path.join(contractsDir, newId + name.slice(oldId.length)));
+		}
+	}
+	// brownfield-scan.{json,md} use a fixed name (not featureId-prefixed) -- they move for free
+	// with the directory rename above and are, for the identical reason, never rewritten either
+	// (scan_report_hash hashes brownfield-scan.json's full content too).
+
+	// feature.json is the one specs/ artifact that is NOT hashed as input to any gate token --
+	// it's the authoritative CURRENT-identity record, safe (and correct) to rewrite in place.
+	rewriteFeatureIdField(path.join(newDir, 'feature.json'), oldId, newId);
+
+	const oldStatePath = statePath(root, oldId);
+	if (fs.existsSync(oldStatePath)) {
+		const newStatePath = statePath(root, newId);
+		fs.renameSync(oldStatePath, newStatePath);
+		rewriteFeatureIdField(newStatePath, oldId, newId);
+	}
+	const oldHistoryPath = historyPath(root, oldId);
+	if (fs.existsSync(oldHistoryPath)) {
+		fs.renameSync(oldHistoryPath, historyPath(root, newId));
+	}
+
+	const manifest = loadManifest(root);
+	let manifestChanged = false;
+	for (const entry of Object.values(manifest.files)) {
+		if (entry.owner === oldId) {
+			entry.owner = newId;
+			manifestChanged = true;
+		}
+	}
+	if (manifestChanged) saveManifest(root, manifest);
+}
+
+// D6: soft-delete only -- sets archived_at/archived_reason on feature.json in place, no
+// filesystem move. Every other command still works unmodified against an archived feature if a
+// human explicitly targets it; only listFeatures()'s default view hides it.
+export function archiveFeature(root, featureId, reason) {
+	const record = loadFeatureFile(root, featureId);
+	if (!record) return null;
+	const updated = { ...record, archived_at: new Date().toISOString(), archived_reason: reason };
+	saveFeatureFile(root, featureId, updated);
+	return updated;
+}
+
+// D6: index-only -- records that `aliasId` (its own feature, its own feature_uid, created via
+// its own `feature init`) should be treated as an alias for `keepId` going forward. Deliberately
+// separate from by_uid (which tracks ONE feature_uid's own rename history) -- aliasId's uid is
+// genuinely different from keepId's, this is a cross-reference, not a rename record. Does NOT
+// touch aliasId's own specs/.sbf/ artifacts or attempt to merge scan/contract/handles state --
+// genuinely ambiguous which side should win, the same never-auto-resolve-ambiguity discipline
+// D-config-patch already established for config patching. A human decides what to do with the
+// two features' actual content; this only records the cross-reference.
+export function linkFeature(index, keepId, aliasId) {
+	index.merged_into = { ...(index.merged_into ?? {}), [aliasId]: keepId };
+	return index;
+}

package/lib/fsutil.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export function sha256File(filePath) {
+	if (!fs.existsSync(filePath)) return null;
+	return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+// S6 (D-verify-integrity): sha256File's own permission-bit sibling -- content hashing is
+// deliberately blind to a chmod-only change (bytes are unchanged), so a gate that wants to notice
+// e.g. an executable script losing its executable bit needs a separate fingerprint. Same
+// null-means-missing convention as sha256File, for the same reason (a caller checking gate
+// staleness treats "gone" and "changed" the same way).
+export function fileMode(filePath) {
+	if (!fs.existsSync(filePath)) return null;
+	return (fs.statSync(filePath).mode & 0o777).toString(8);
+}
+
+export function sha256String(content) {
+	return createHash('sha256').update(content).digest('hex');
+}
+
+export function readJsonIfExists(filePath) {
+	if (!fs.existsSync(filePath)) return null;
+	return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+// Atomic write (temp + rename), same technique as lib/state.mjs -- reused by every command that
+// writes a durable artifact under specs/<feature_id>/ so a mid-write crash can't leave a
+// half-written file that a later gate check would treat as valid.
+export function writeFileAtomic(filePath, content) {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	const tmp = `${filePath}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, content);
+	fs.renameSync(tmp, filePath);
+}
+
+// S2: non-throwing sibling of stack/apply.mjs's assertContained() -- same containment check
+// (D-security-4's class of defense), but for callers reading a repo-relative path OUT OF untrusted
+// JSON (an O2 handles-manifest entry, a stack.json applied_files entry) where "this path escapes
+// the repo" should be treated as "not a file we generated" and skipped, not a thrown error that
+// would take down a `bskel verify` report over one bad entry.
+export function resolveWithinRoot(root, relPath) {
+	const resolvedRoot = path.resolve(root);
+	const resolvedTarget = path.resolve(root, relPath);
+	const rel = path.relative(resolvedRoot, resolvedTarget);
+	if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
+	return resolvedTarget;
+}