@savvy-web/cli 0.3.1 → 0.4.1

package/commands/clean.js

@@ -0,0 +1,186 @@
+import { Command, Options } from "@effect/cli";
+import { Data, Effect } from "effect";
+import { WorkspaceDiscovery } from "workspaces-effect";
+import { join, sep } from "node:path";
+import { glob, realpath, rm } from "node:fs/promises";
+
+//#region src/commands/clean.ts
+/**
+* `savvy clean` — remove build/cache artifacts across a silk workspace.
+*
+* Globs a set of patterns at the top level of each workspace root (leaves
+* first, monorepo root last) and deletes matches. `--dry-run` previews without
+* touching disk. Uses Node's native `fs.promises.glob` (no third-party glob).
+*
+* @internal
+*/
+/** Default patterns cleaned when `--globs` is omitted. */
+const DEFAULT_GLOBS = [
+	"dist",
+	".turbo",
+	"coverage",
+	"node_modules",
+	".rslib"
+];
+/** Directory names a recursive (`**`) glob must never descend into. */
+const NO_DESCEND = new Set(["node_modules", ".git"]);
+/** Unexpected failure while planning or removing artifacts. */
+var CleanError = class extends Data.TaggedError("CleanError") {};
+/**
+* Glob `patterns` at the top of `pkgPath`, classify dir vs file, and enforce
+* that every match stays within `pkgPath` (rejecting symlink/`..` escapes and
+* the root directory itself).
+*/
+function collectTargets(pkgPath, patterns) {
+	return Effect.tryPromise({
+		try: async () => {
+			const rootReal = await realpath(pkgPath);
+			const seen = /* @__PURE__ */ new Map();
+			for await (const entry of glob(patterns, {
+				cwd: pkgPath,
+				withFileTypes: true,
+				exclude: (dirent) => NO_DESCEND.has(dirent.name) && dirent.isDirectory()
+			})) {
+				const abs = join(entry.parentPath, entry.name);
+				let real;
+				try {
+					real = await realpath(abs);
+				} catch {
+					continue;
+				}
+				if (real === rootReal || !real.startsWith(rootReal + sep)) continue;
+				if (real === join(rootReal, "package.json")) continue;
+				seen.set(abs, {
+					path: abs,
+					kind: entry.isDirectory() ? "dir" : "file"
+				});
+			}
+			return [...seen.values()];
+		},
+		catch: (e) => new CleanError({
+			step: `glob ${pkgPath}`,
+			reason: e instanceof Error ? e.message : String(e)
+		})
+	});
+}
+/** Max concurrent deletions. */
+const REMOVE_CONCURRENCY = 8;
+/**
+* Delete each target (`rm -rf`, missing paths are no-ops via `force`). On
+* `dryRun`, report without deleting. Per-target failures are collected, not
+* thrown, so one unremovable path does not abort the rest.
+*/
+function removeTargets(targets, dryRun) {
+	return Effect.gen(function* () {
+		const results = yield* Effect.forEach(targets, (target) => dryRun ? Effect.succeed({
+			target,
+			reason: null
+		}) : Effect.tryPromise(() => rm(target.path, {
+			recursive: true,
+			force: true
+		})).pipe(Effect.match({
+			onSuccess: () => ({
+				target,
+				reason: null
+			}),
+			onFailure: (e) => ({
+				target,
+				reason: e instanceof Error ? e.message : String(e)
+			})
+		})), { concurrency: REMOVE_CONCURRENCY });
+		return {
+			removed: results.filter((r) => r.reason === null).map((r) => r.target),
+			failed: results.filter((r) => r.reason !== null).map((r) => ({
+				target: r.target,
+				reason: r.reason
+			}))
+		};
+	});
+}
+/** Unicode symbols for output. */
+const CHECK_MARK = "✓";
+const BULLET = "•";
+const WARN_MARK = "⚠";
+/** Split the comma-separated `--globs` value; fall back to defaults when empty. */
+function parseGlobs(raw) {
+	const parts = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	return parts.length > 0 ? parts : DEFAULT_GLOBS;
+}
+/**
+* Discover packages, plan targets per workspace (leaves first, root last),
+* dedup across overlapping roots, remove (or preview), and report.
+*/
+function runClean(opts) {
+	const patterns = parseGlobs(opts.globs);
+	return Effect.gen(function* () {
+		const packages = yield* (yield* WorkspaceDiscovery).listPackages(process.cwd()).pipe(Effect.mapError((e) => new CleanError({
+			step: "discover workspaces",
+			reason: e.message
+		})));
+		const leaves = packages.filter((p) => !p.isRootWorkspace);
+		const roots = packages.filter((p) => p.isRootWorkspace);
+		const ordered = [...leaves, ...roots];
+		const planned = yield* Effect.forEach(ordered, (pkg) => collectTargets(pkg.path, patterns).pipe(Effect.map((targets) => ({
+			pkg,
+			targets
+		}))));
+		const seen = /* @__PURE__ */ new Set();
+		const groups = planned.map(({ pkg, targets }) => {
+			return {
+				pkg,
+				targets: targets.filter((t) => {
+					if (seen.has(t.path)) return false;
+					seen.add(t.path);
+					return true;
+				})
+			};
+		});
+		const leafGroups = groups.filter((g) => !g.pkg.isRootWorkspace);
+		const rootGroups = groups.filter((g) => g.pkg.isRootWorkspace);
+		const verb = opts.dryRun ? "would remove" : "removed";
+		let total = 0;
+		const failures = [];
+		for (const phase of [leafGroups, rootGroups]) {
+			const reports = yield* Effect.forEach(phase, (g) => removeTargets(g.targets, opts.dryRun).pipe(Effect.map((report) => ({
+				g,
+				report
+			}))));
+			for (const { g, report } of reports) {
+				if (g.targets.length === 0) continue;
+				yield* Effect.log(`\n${g.pkg.relativePath === "." ? "<root>" : g.pkg.relativePath}`);
+				for (const t of report.removed) yield* Effect.log(`  ${BULLET} ${verb} [${t.kind}] ${t.path}`);
+				for (const f of report.failed) yield* Effect.log(`  ${WARN_MARK} failed [${f.target.kind}] ${f.target.path}: ${f.reason}`);
+				total += report.removed.length;
+				failures.push(...report.failed);
+			}
+		}
+		yield* Effect.log(`\n${CHECK_MARK} ${opts.dryRun ? "Would remove" : "Removed"} ${total} item(s).`);
+		if (failures.length > 0) {
+			for (const f of failures) yield* Effect.logError(`Failed to remove ${f.target.path}: ${f.reason}`);
+			return yield* Effect.fail(new CleanError({
+				step: "remove",
+				reason: `${failures.length} target(s) could not be removed`
+			}));
+		}
+	});
+}
+/* v8 ignore start -- CLI option/registration; orchestration tested via runClean */
+const globsOption = Options.text("globs").pipe(Options.withAlias("g"), Options.withDescription(`Comma-separated glob patterns to remove from each workspace root (default: ${DEFAULT_GLOBS.join(",")})`), Options.withDefault(DEFAULT_GLOBS.join(",")));
+const dryRunOption = Options.boolean("dry-run").pipe(Options.withAlias("n"), Options.withDescription("Report what would be removed without deleting anything"), Options.withDefault(false));
+const _cleanCommand = Command.make("clean", {
+	globs: globsOption,
+	dryRun: dryRunOption
+}, (opts) => runClean(opts)).pipe(Command.withDescription("Remove build/cache artifacts across the workspace (leaves first, root last)"));
+/* v8 ignore stop */
+/**
+* The `savvy clean` command for the root assembly.
+*
+* @remarks
+* Typed with `any` at the export boundary to avoid TypeScript declaration-emit
+* errors from Effect's internal Command types, matching the other top-level
+* command exports.
+*/
+const cleanCommand = _cleanCommand;
+
+//#endregion
+export { cleanCommand };

package/commands/commit/check.js

@@ -0,0 +1,170 @@
+import { HUSKY_HOOK_PATH, POST_CHECKOUT_HOOK_PATH, POST_MERGE_HOOK_PATH } from "./constants.js";
+import { SECTION_DEF, savvyCommitBlock } from "./init.js";
+import { Command } from "@effect/cli";
+import { CheckResult, Commitlint, ManagedSection, SavvyBaseSection, SavvyHooksSection, VersioningStrategy, savvyBasePreamble, savvyHooksHygiene } from "@savvy-web/silk-effects";
+import { Effect } from "effect";
+import { WorkspaceDiscovery } from "workspaces-effect";
+import { FileSystem } from "@effect/platform";
+
+//#region src/commands/commit/check.ts
+/**
+* Check command - validate current commitlint setup.
+*
+* @internal
+*/
+/** Unicode cross symbol. */
+const CROSS_MARK = "✗";
+/** Unicode bullet symbol. */
+const BULLET = "•";
+/** Possible commitlint configuration file names, in priority order. */
+const CONFIG_FILES = [
+	"commitlint.config.ts",
+	"commitlint.config.mts",
+	"commitlint.config.cts",
+	"commitlint.config.js",
+	"commitlint.config.mjs",
+	"commitlint.config.cjs",
+	"lib/configs/commitlint.config.ts",
+	"lib/configs/commitlint.config.mts",
+	"lib/configs/commitlint.config.cts",
+	"lib/configs/commitlint.config.js",
+	"lib/configs/commitlint.config.mjs",
+	"lib/configs/commitlint.config.cjs",
+	".commitlintrc",
+	".commitlintrc.json",
+	".commitlintrc.yaml",
+	".commitlintrc.yml",
+	".commitlintrc.js",
+	".commitlintrc.cjs",
+	".commitlintrc.mjs",
+	".commitlintrc.ts",
+	".commitlintrc.cts",
+	".commitlintrc.mts"
+];
+/** DCO file path. */
+const DCO_FILE_PATH = "DCO";
+/** Maps versioning strategy types to release formats. */
+const STRATEGY_TO_FORMAT = {
+	single: "semver",
+	"fixed-group": "semver",
+	independent: "packages"
+};
+/**
+* Find the first existing config file.
+*
+* @param fs - FileSystem service
+* @returns Effect yielding the config file name or null
+*/
+function findConfigFile(fs) {
+	return Effect.gen(function* () {
+		for (const file of CONFIG_FILES) if (yield* fs.exists(file)) return file;
+		return null;
+	});
+}
+/**
+* Extract the config path from managed section content.
+*
+* @param managedContent - The content between managed section markers
+* @returns The config path found, or null if not found
+*/
+function extractConfigPathFromManaged(managedContent) {
+	const match = managedContent.match(/commitlint --config "\$ROOT\/([^"]+)"/);
+	return match ? match[1] : null;
+}
+/**
+* Detect the release format using silk-effects versioning service.
+*
+* @returns Effect yielding the release format string
+*/
+const detectReleaseFormat = Effect.gen(function* () {
+	const versioning = yield* VersioningStrategy;
+	const discovery = yield* WorkspaceDiscovery;
+	const publishableNames = (yield* Effect.catchAll(discovery.listPackages(), () => Effect.succeed([]))).filter((pkg) => !pkg.private || pkg.publishConfig?.access !== void 0).map((pkg) => pkg.name);
+	return STRATEGY_TO_FORMAT[(yield* Effect.catchAll(versioning.detect(publishableNames, process.cwd()), () => Effect.succeed({ type: "single" }))).type] ?? "semver";
+});
+/**
+* Run the check validation pipeline.
+*
+* Exported so Task B6's unified `savvy check` orchestrator can invoke the
+* commitlint check step directly without going through the CLI command layer.
+*
+* @returns An Effect that performs validation and logs results
+*
+* @internal
+*/
+function runCommitCheck() {
+	return Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const ms = yield* ManagedSection;
+		yield* Effect.log("Checking commitlint configuration...\n");
+		const foundConfig = yield* findConfigFile(fs);
+		if (foundConfig) yield* Effect.log(`${"✓"} Config file: ${foundConfig}`);
+		else yield* Effect.log(`${CROSS_MARK} No commitlint config file found`);
+		const hasHuskyHook = yield* fs.exists(HUSKY_HOOK_PATH);
+		if (hasHuskyHook) yield* Effect.log(`${"✓"} Husky hook: ${HUSKY_HOOK_PATH}`);
+		else yield* Effect.log(`${CROSS_MARK} No husky commit-msg hook found`);
+		let sectionsHealthy = true;
+		if (hasHuskyHook) {
+			const baseStatus = yield* ms.check(HUSKY_HOOK_PATH, SavvyBaseSection.block(savvyBasePreamble()));
+			if (CheckResult.$is("Found")(baseStatus) && baseStatus.isUpToDate) yield* Effect.log(`${"✓"} Base section: up-to-date`);
+			else if (CheckResult.$is("Found")(baseStatus)) {
+				sectionsHealthy = false;
+				yield* Effect.log(`${"⚠"} Base section: outdated (run 'savvy init' to update)`);
+			} else {
+				sectionsHealthy = false;
+				yield* Effect.log(`${BULLET} Base section: not found (run 'savvy init' to add)`);
+			}
+			const block = yield* ms.read(HUSKY_HOOK_PATH, SECTION_DEF);
+			if (block) {
+				const configPath = extractConfigPathFromManaged(block.content);
+				if (configPath) {
+					const status = yield* ms.check(HUSKY_HOOK_PATH, savvyCommitBlock(configPath));
+					if (CheckResult.$is("Found")(status) && status.isUpToDate) yield* Effect.log(`${"✓"} Commit section: up-to-date`);
+					else {
+						sectionsHealthy = false;
+						yield* Effect.log(`${"⚠"} Commit section: outdated (run 'savvy init' to update)`);
+					}
+				} else {
+					sectionsHealthy = false;
+					yield* Effect.log(`${"⚠"} Commit section: outdated (run 'savvy init' to update)`);
+				}
+			} else {
+				sectionsHealthy = false;
+				yield* Effect.log(`${BULLET} Commit section: not found (run 'savvy init' to add)`);
+			}
+		}
+		for (const hookPath of [POST_CHECKOUT_HOOK_PATH, POST_MERGE_HOOK_PATH]) {
+			if (!(yield* fs.exists(hookPath))) {
+				sectionsHealthy = false;
+				yield* Effect.log(`${BULLET} Hygiene hook: ${hookPath} not found (run 'savvy init' to add)`);
+				continue;
+			}
+			const hygieneStatus = yield* ms.check(hookPath, SavvyHooksSection.block(savvyHooksHygiene()));
+			if (CheckResult.$is("Found")(hygieneStatus) && hygieneStatus.isUpToDate) yield* Effect.log(`${"✓"} Hygiene hook: ${hookPath}`);
+			else if (CheckResult.$is("Found")(hygieneStatus)) {
+				sectionsHealthy = false;
+				yield* Effect.log(`${"⚠"} Hygiene hook: ${hookPath} outdated (run 'savvy init' to update)`);
+			} else {
+				sectionsHealthy = false;
+				yield* Effect.log(`${BULLET} Hygiene hook: ${hookPath} section not found (run 'savvy init' to add)`);
+			}
+		}
+		if (yield* fs.exists(DCO_FILE_PATH)) yield* Effect.log(`${"✓"} DCO file: ${DCO_FILE_PATH}`);
+		else yield* Effect.log(`${BULLET} No DCO file (signoff not required)`);
+		yield* Effect.log("\nDetected settings:");
+		yield* Effect.log(`  DCO required: ${Commitlint.detectDCO()}`);
+		const releaseFormat = yield* detectReleaseFormat;
+		yield* Effect.log(`  Release format: ${releaseFormat}`);
+		const scopes = yield* Effect.catchAll(Commitlint.detectScopes, () => Effect.succeed([]));
+		const scopeDisplay = scopes.length > 0 ? scopes.join(", ") : "(none - not a monorepo or no packages found)";
+		yield* Effect.log(`  Detected scopes: ${scopeDisplay}`);
+		yield* Effect.log("");
+		if (!foundConfig || !hasHuskyHook || !sectionsHealthy) yield* Effect.log(`${CROSS_MARK} Commitlint needs configuration. Run: savvy init`);
+		else yield* Effect.log(`${"✓"} Commitlint is configured correctly.`);
+	});
+}
+/* v8 ignore next 3 -- CLI registration; handler tested via runCommitCheck */
+const checkCommand = Command.make("check", {}, () => runCommitCheck()).pipe(Command.withDescription("Check current commitlint configuration and detected settings"));
+
+//#endregion
+export { runCommitCheck };

package/commands/commit/constants.js

@@ -0,0 +1,10 @@
+//#region src/commands/commit/constants.ts
+/** Husky commit-msg hook path (savvy-base + savvy-commit sections). */
+const HUSKY_HOOK_PATH = ".husky/commit-msg";
+/** Husky post-checkout hook path (savvy-hooks hygiene). */
+const POST_CHECKOUT_HOOK_PATH = ".husky/post-checkout";
+/** Husky post-merge hook path (savvy-hooks hygiene). */
+const POST_MERGE_HOOK_PATH = ".husky/post-merge";
+
+//#endregion
+export { HUSKY_HOOK_PATH, POST_CHECKOUT_HOOK_PATH, POST_MERGE_HOOK_PATH };

package/commands/commit/hook.js

@@ -0,0 +1,22 @@
+import { postCommitVerifyCommand } from "./hooks/post-commit-verify.js";
+import { preCommitMessageCommand } from "./hooks/pre-commit-message.js";
+import { sessionStartCommand } from "./hooks/session-start.js";
+import { userPromptSubmitCommand } from "./hooks/user-prompt-submit.js";
+import { Command } from "@effect/cli";
+
+//#region src/commands/commit/hook.ts
+/**
+* `savvy commit hook` parent command — internal CLI surface used by the
+* commitlint plugin's bash hooks.
+*
+* @internal
+*/
+const hookCommand = Command.make("hook").pipe(Command.withSubcommands([
+	sessionStartCommand,
+	preCommitMessageCommand,
+	postCommitVerifyCommand,
+	userPromptSubmitCommand
+])).pipe(Command.withDescription("Internal hook handlers used by the @savvy-web/commitlint plugin"));
+
+//#endregion
+export { hookCommand };

package/commands/commit/hooks/post-commit-verify.js

@@ -0,0 +1,121 @@
+import { Command } from "@effect/cli";
+import { Commitlint } from "@savvy-web/silk-effects";
+import { Effect } from "effect";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+//#region src/commands/commit/hooks/post-commit-verify.ts
+/**
+* `savvy commit hook post-commit-verify` — replays commitlint, checks the
+* signature, and verifies the closes trailer if the branch implies one.
+*
+* @internal
+*/
+const execFileP = promisify(execFile);
+function buildPostCommitAdvice(i) {
+	const lines = [];
+	if (i.commitlintFailed) lines.push("The commit you just created fails commitlint validation. Run pnpm exec commitlint --last to see the violations, then fix with git commit --amend.");
+	if (i.autoSignEnabled) {
+		if (i.sigStatus === "N") lines.push("The commit was unsigned but commit.gpgsign=true is configured. Re-sign with: git commit --amend --no-edit -S");
+		else if ([
+			"B",
+			"X",
+			"Y",
+			"R",
+			"E"
+		].includes(i.sigStatus)) lines.push(`The commit signature status is '${i.sigStatus}' (B=bad, X=expired sig, Y=expired key, R=revoked, E=missing key). Investigate your signing setup and amend.`);
+	}
+	if (i.branchTicketId !== null && !i.bodyHasClosing) lines.push(`Branch implies ticket #${i.branchTicketId} but the commit body has no Closes/Fixes/Resolves trailer for it. If this commit closes #${i.branchTicketId}, amend with: git commit --amend --no-edit --trailer "Closes: #${i.branchTicketId}"`);
+	return lines.length === 0 ? null : lines.join("\n\n");
+}
+function buildCommitlintInvocation(pm, configPath) {
+	const tail = configPath ? [
+		"commitlint",
+		"--config",
+		configPath,
+		"--last"
+	] : ["commitlint", "--last"];
+	switch (pm) {
+		case "pnpm": return {
+			command: "pnpm",
+			args: ["exec", ...tail]
+		};
+		case "yarn": return {
+			command: "yarn",
+			args: ["exec", ...tail]
+		};
+		case "bun": return {
+			command: "bunx",
+			args: tail
+		};
+		case "npm": return {
+			command: "npx",
+			args: [
+				"--no",
+				"--",
+				...tail
+			]
+		};
+	}
+}
+async function getRepoRoot() {
+	try {
+		const { stdout } = await execFileP("git", ["rev-parse", "--show-toplevel"]);
+		return stdout.trim();
+	} catch {
+		return process.cwd();
+	}
+}
+async function runCommitlintLast() {
+	const root = await getRepoRoot();
+	const { command, args } = buildCommitlintInvocation(await Commitlint.detectPackageManager(root), await Commitlint.readCommitlintConfigPath(root));
+	try {
+		await execFileP(command, args, { cwd: root });
+		return false;
+	} catch {
+		return true;
+	}
+}
+async function readSignatureStatus() {
+	try {
+		const { stdout } = await execFileP("git", [
+			"log",
+			"-1",
+			"--format=%G?"
+		]);
+		return stdout.trim();
+	} catch {
+		return "N";
+	}
+}
+async function readLastCommitBody() {
+	try {
+		const { stdout } = await execFileP("git", [
+			"log",
+			"-1",
+			"--format=%B"
+		]);
+		return stdout;
+	} catch {
+		return "";
+	}
+}
+const postCommitVerifyCommand = Command.make("post-commit-verify", {}, () => Effect.gen(function* () {
+	const branch = yield* Commitlint.readBranchInfo();
+	const signing = yield* Commitlint.readSigningDiagnostic();
+	const commitlintFailed = yield* Effect.promise(runCommitlintLast);
+	const sigStatus = yield* Effect.promise(readSignatureStatus);
+	const body = yield* Effect.promise(readLastCommitBody);
+	const bodyHasClosing = branch.inferredTicketId !== null && Commitlint.hasClosingTrailer(body, branch.inferredTicketId);
+	const advice = buildPostCommitAdvice({
+		commitlintFailed,
+		sigStatus,
+		autoSignEnabled: signing.autoSignEnabled,
+		branchTicketId: branch.inferredTicketId,
+		bodyHasClosing
+	});
+	if (advice !== null) yield* Effect.sync(() => process.stdout.write(`${JSON.stringify(Commitlint.postToolUseAdvise(advice))}\n`));
+}).pipe(Effect.provide(Commitlint.HookSilencer))).pipe(Command.withDescription("Verify the most recent commit (commitlint replay + signature + closes trailer)"));
+
+//#endregion
+export { postCommitVerifyCommand };

package/commands/commit/hooks/pre-commit-message.js

@@ -0,0 +1,64 @@
+import { Command } from "@effect/cli";
+import { Commitlint } from "@savvy-web/silk-effects";
+import { Effect, Schema } from "effect";
+import { resolve } from "node:path";
+
+//#region src/commands/commit/hooks/pre-commit-message.ts
+/**
+* `savvy commit hook pre-commit-message` — reads a PreToolUse envelope on
+* stdin and emits deny/advise/silent output for the bash hook.
+*
+* @internal
+*/
+async function evaluateMessage(command, ctx) {
+	const parsed = Commitlint.parseBashCommand(command);
+	if (parsed.kind === "unknown") return Commitlint.preToolUseSilent();
+	if (parsed.message === null) return Commitlint.preToolUseSilent();
+	const hits = [];
+	const collect = async (eff) => {
+		const h = await Effect.runPromise(eff);
+		if (h) hits.push(h);
+	};
+	await collect(Commitlint.forbiddenContentRule.check({ message: parsed.message }, void 0));
+	await collect(Commitlint.planLeakageRule.check({ message: parsed.message }, void 0));
+	await collect(Commitlint.softWrapRule.check({ message: parsed.message }, void 0));
+	await collect(Commitlint.verbosityRule.check({ message: parsed.message }, void 0));
+	await collect(Commitlint.closesTrailerRule.check({ message: parsed.message }, {
+		branchInfo: ctx.branchInfo,
+		openIssues: ctx.openIssues
+	}));
+	await collect(Commitlint.signingFlagConflictRule.check({ flags: parsed.flags }, { autoSignEnabled: ctx.autoSignEnabled }));
+	const { deny, advise } = Commitlint.partitionHits(hits);
+	if (deny.length > 0) return Commitlint.preToolUseDeny(["The following rules denied this commit message:", ...deny.map((h) => `- ${h.message}`)].join("\n"));
+	if (advise.length > 0) return Commitlint.preToolUseAdvise(["The commit message you are about to write has issues that should be addressed:", ...advise.map((h) => `- ${h.message}`)].join("\n"));
+	return Commitlint.preToolUseSilent();
+}
+const preCommitMessageCommand = Command.make("pre-commit-message", {}, () => Effect.gen(function* () {
+	const stdin = yield* Effect.promise(readStdin);
+	let envelope;
+	try {
+		envelope = Schema.decodeUnknownSync(Commitlint.PreToolUseEnvelope)(JSON.parse(stdin));
+	} catch {
+		return;
+	}
+	const command = String(envelope.tool_input.command ?? "");
+	if (!command) return;
+	const branchInfo = yield* Commitlint.readBranchInfo();
+	const signing = yield* Commitlint.readSigningDiagnostic();
+	const issuesPath = resolve(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), Commitlint.ISSUES_CACHE_RELATIVE_PATH);
+	const issues = (yield* Commitlint.readOpenIssuesFromCache(issuesPath)) ?? [];
+	const out = yield* Effect.promise(() => evaluateMessage(command, {
+		branchInfo,
+		openIssues: issues,
+		autoSignEnabled: signing.autoSignEnabled
+	}));
+	if (out !== null) yield* Effect.sync(() => process.stdout.write(`${JSON.stringify(out)}\n`));
+}).pipe(Effect.provide(Commitlint.HookSilencer))).pipe(Command.withDescription("Validate a candidate git commit / gh pr command's message"));
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+
+//#endregion
+export { preCommitMessageCommand };

package/commands/commit/hooks/session-start.js

@@ -0,0 +1,69 @@
+import { Command } from "@effect/cli";
+import { Commitlint } from "@savvy-web/silk-effects";
+import { Effect } from "effect";
+import { resolve } from "node:path";
+
+//#region src/commands/commit/hooks/session-start.ts
+/**
+* `savvy commit hook session-start` — emits the additionalContext block
+* the SessionStart hook injects into the agent's context.
+*
+* @internal
+*/
+const sessionStartCommand = Command.make("session-start", {}, () => Effect.gen(function* () {
+	const branch = yield* Commitlint.readBranchInfo();
+	const signing = yield* Commitlint.readSigningDiagnostic();
+	const issuesCachePath = resolve(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), Commitlint.ISSUES_CACHE_RELATIVE_PATH);
+	const issues = yield* Commitlint.readOrFetchOpenIssues(issuesCachePath);
+	const blocks = [];
+	blocks.push(buildSkillDirectiveBlock());
+	if (branch.branch) blocks.push(buildBranchBlock(branch.branch, branch.inferredTicketId, issues));
+	blocks.push(buildSigningBlock(signing));
+	const ctx = `<EXTREMELY_IMPORTANT>\n${blocks.join("\n\n")}\n</EXTREMELY_IMPORTANT>`;
+	const out = Commitlint.sessionStartContext(ctx);
+	yield* Effect.sync(() => process.stdout.write(`${JSON.stringify(out)}\n`));
+}).pipe(Effect.provide(Commitlint.HookSilencer))).pipe(Command.withDescription("Emit the SessionStart additionalContext for the commitlint plugin"));
+function buildSkillDirectiveBlock() {
+	return [
+		"Before you run git commit, gh pr create, gh pr edit, amend a commit, or compose",
+		"any commit message, you MUST invoke the commitlint:commit-create skill. It",
+		"contains the complete type enum, tdd scope grammar, subject and body rules, DCO",
+		"signoff format, Closes trailer pattern, and signing guidance.",
+		"",
+		"YOU DO NOT HAVE A CHOICE. Even if you believe the commit message is obvious,",
+		"you MUST load the skill first. This is not negotiable. You cannot rationalize",
+		"your way around it. The commit-msg hook will reject messages that violate the",
+		"rules defined in that skill."
+	].join("\n");
+}
+function buildBranchBlock(branch, ticketId, issues) {
+	const lines = [
+		"<branch_context>",
+		`<current_branch>${branch}</current_branch>`,
+		`<inferred_ticket_id>${ticketId ?? "null"}</inferred_ticket_id>`
+	];
+	if (issues && issues.length > 0) {
+		lines.push("<open_issues_in_repo>");
+		for (const i of issues) lines.push(`  - #${i.number}  ${i.title}`);
+		lines.push("</open_issues_in_repo>");
+	}
+	lines.push("</branch_context>");
+	return lines.join("\n");
+}
+function buildSigningBlock(d) {
+	const lines = [
+		"<signing_diagnostic>",
+		`<format>${d.format}</format>`,
+		`<auto_sign_enabled>${d.autoSignEnabled}</auto_sign_enabled>`,
+		`<signing_key_configured>${d.signingKeyConfigured}</signing_key_configured>`,
+		`<key_resolves>${d.keyResolves}</key_resolves>`,
+		`<agent_responsive>${d.agentResponsive}</agent_responsive>`,
+		"<warnings>"
+	];
+	for (const w of d.warnings) lines.push(`  - ${w}`);
+	lines.push("</warnings>", "</signing_diagnostic>");
+	return lines.join("\n");
+}
+
+//#endregion
+export { sessionStartCommand };