@juicesharp/rpiv-pi 1.9.1 → 1.10.0

package/extensions/rpiv-core/agents.test.ts

@@ -14,7 +14,6 @@ import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
-	BUNDLED_AGENTS_DIR,
 	CLEANUP_SKIP_REASON,
 	cleanupPerCwdAgents,
 	isSafeDestructiveOp,
@@ -22,6 +21,7 @@ import {
 	summarizeCleanupSkips,
 	syncBundledAgents,
 } from "./agents.js";
+import { BUNDLED_AGENTS_DIR } from "./paths.js";
 
 const sha256 = (s: string | Buffer) => createHash("sha256").update(s).digest("hex");
 

package/extensions/rpiv-core/agents.ts

@@ -26,27 +26,11 @@ import {
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { BUNDLED_AGENTS_DIR } from "./paths.js";
 import { isPlainObject, toErrorMessage } from "./utils.js";
 
-// ---------------------------------------------------------------------------
-// Package-root resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Resolves the rpiv-pi package root from this module's file URL.
- * Walks up from `extensions/rpiv-core/agents.ts` to the repo root.
- */
-export const PACKAGE_ROOT = (() => {
-	const thisFile = fileURLToPath(import.meta.url);
-	// extensions/rpiv-core/agents.ts -> rpiv-pi/
-	return dirname(dirname(dirname(thisFile)));
-})();
-
-export const BUNDLED_AGENTS_DIR = join(PACKAGE_ROOT, "agents");
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------

package/extensions/rpiv-core/paths.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolved filesystem paths for rpiv-pi's own bundled resources.
+ *
+ * `PACKAGE_ROOT` is computed at module load from this file's URL. The walk-up
+ * is anchored to this file's location (`extensions/rpiv-core/paths.ts`) — three
+ * `dirname` levels reach the rpiv-pi package root. Other resource directories
+ * mirror the `pi.skills` / `pi.extensions` declarations in package.json.
+ *
+ * Pi's SDK does not expose a "give me my own extension root" API, so this is
+ * the idiomatic resolution path (see also docs/packages.md on `pi.*` manifest
+ * paths being relative to the package root).
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_ROOT = (() => {
+	const thisFile = fileURLToPath(import.meta.url);
+	// extensions/rpiv-core/paths.ts -> rpiv-pi/
+	return dirname(dirname(dirname(thisFile)));
+})();
+
+export const BUNDLED_AGENTS_DIR = join(PACKAGE_ROOT, "agents");
+export const BUNDLED_SKILLS_DIR = join(PACKAGE_ROOT, "skills");

package/extensions/rpiv-core/session-hooks.test.ts

@@ -56,10 +56,17 @@ afterEach(() => {
 });
 
 describe("registerSessionHooks — event wiring", () => {
-	it("registers 5 events", () => {
+	it("registers 6 events", () => {
 		const { pi, captured } = createMockPi();
 		registerSessionHooks(pi);
-		for (const ev of ["session_start", "session_compact", "session_shutdown", "tool_call", "before_agent_start"]) {
+		for (const ev of [
+			"session_start",
+			"session_compact",
+			"session_shutdown",
+			"tool_call",
+			"before_agent_start",
+			"agent_end",
+		]) {
 			expect(captured.events.has(ev)).toBe(true);
 		}
 	});
@@ -458,7 +465,7 @@ describe("before_agent_start hook", () => {
 		registerSessionHooks(pi);
 		const handler = captured.events.get("before_agent_start")?.[0];
 		const ctx = createMockCtx({ cwd: projectDir });
-		const r = await handler?.({} as never, ctx as never);
+		const r = await handler?.({ prompt: "" } as never, ctx as never);
 		expect(r).toHaveProperty("message");
 	});
 
@@ -469,8 +476,59 @@ describe("before_agent_start hook", () => {
 		registerSessionHooks(pi);
 		const handler = captured.events.get("before_agent_start")?.[0];
 		const ctx = createMockCtx({ cwd: projectDir });
-		await handler?.({} as never, ctx as never);
-		const second = await handler?.({} as never, ctx as never);
+		await handler?.({ prompt: "" } as never, ctx as never);
+		const second = await handler?.({ prompt: "" } as never, ctx as never);
 		expect(second).toBeUndefined();
 	});
+
+	it("sets status to 'rpiv: <name>' when prompt contains an owned rpiv-pi skill block", async () => {
+		const { pi, captured } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc", user: "alice" }) as never,
+		});
+		registerSessionHooks(pi);
+		const handler = captured.events.get("before_agent_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir });
+		const skillPrompt = `<skill name="discover" location="/some/path">\nbody\n</skill>`;
+		await handler?.({ prompt: skillPrompt } as never, ctx as never);
+		expect(ctx.ui.setStatus).toHaveBeenCalledWith("rpiv-skill", "rpiv: discover");
+	});
+
+	it("does not set status for a skill block whose name is not bundled with rpiv-pi", async () => {
+		// Foreign / user-supplied skills must not be branded as rpiv: — only names that
+		// match a directory under packages/rpiv-pi/skills/ get the rpiv-skill status.
+		const { pi, captured } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc", user: "alice" }) as never,
+		});
+		registerSessionHooks(pi);
+		const handler = captured.events.get("before_agent_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir });
+		const skillPrompt = `<skill name="not-an-rpiv-skill" location="/home/u/.pi/skills/not-an-rpiv-skill">\nbody\n</skill>`;
+		await handler?.({ prompt: skillPrompt } as never, ctx as never);
+		const setStatusCalls = (ctx.ui.setStatus as ReturnType<typeof vi.fn>).mock.calls.filter(
+			(c) => c[0] === "rpiv-skill",
+		);
+		expect(setStatusCalls).toHaveLength(0);
+	});
+
+	it("does not set status when prompt has no skill block", async () => {
+		const { pi, captured } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc", user: "alice" }) as never,
+		});
+		registerSessionHooks(pi);
+		const handler = captured.events.get("before_agent_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir });
+		await handler?.({ prompt: "just a normal chat message" } as never, ctx as never);
+		expect(ctx.ui.setStatus).not.toHaveBeenCalled();
+	});
+});
+
+describe("agent_end hook", () => {
+	it("clears the rpiv-skill status", async () => {
+		const { pi, captured } = createMockPi();
+		registerSessionHooks(pi);
+		const handler = captured.events.get("agent_end")?.[0];
+		const ctx = createMockCtx();
+		await handler?.({ messages: [] } as never, ctx as never);
+		expect(ctx.ui.setStatus).toHaveBeenCalledWith("rpiv-skill", undefined);
+	});
 });

package/extensions/rpiv-core/session-hooks.ts

@@ -8,9 +8,12 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import {
+	type AgentEndEvent,
+	type BeforeAgentStartEvent,
 	type ExtensionAPI,
 	type ExtensionContext,
 	isToolCallEventType,
+	parseSkillBlock,
 	type ToolCallEvent,
 } from "@earendil-works/pi-coding-agent";
 import {
@@ -29,6 +32,7 @@ import {
 } from "./git-context.js";
 import { ARTIFACTS_SUBDIR, clearInjectionState, handleToolCallGuidance, injectRootGuidance } from "./guidance.js";
 import { findMissingSiblings } from "./package-checks.js";
+import { BUNDLED_SKILLS_DIR } from "./paths.js";
 
 const msgAgentsAdded = (n: number) => `Copied ${n} rpiv-pi agent(s) to ~/.pi/agent/agents/`;
 const msgAgentsHealed = (parts: string[]) => `Synced bundled agent(s): ${parts.join(", ")}.`;
@@ -60,7 +64,8 @@ export function registerSessionHooks(pi: ExtensionAPI): void {
 	pi.on("session_compact", async (_event, ctx) => onSessionCompact(_event, ctx, pi));
 	pi.on("session_shutdown", async () => onSessionShutdown());
 	pi.on("tool_call", async (event, ctx) => onToolCall(event, ctx, pi));
-	pi.on("before_agent_start", async () => onBeforeAgentStart(pi));
+	pi.on("before_agent_start", async (event, ctx) => onBeforeAgentStart(event, ctx, pi));
+	pi.on("agent_end", async (_event, ctx) => onAgentEnd(_event, ctx));
 }
 
 // ---------------------------------------------------------------------------
@@ -107,17 +112,45 @@ async function onToolCall(event: ToolCallEvent, ctx: ExtensionContext, pi: Exten
 }
 
 async function onBeforeAgentStart(
+	event: BeforeAgentStartEvent,
+	ctx: ExtensionContext,
 	pi: ExtensionAPI,
 ): Promise<{ message: ReturnType<typeof buildGitContextMessage> } | undefined> {
+	const parsed = parseSkillBlock(event.prompt);
+	if (parsed && isOwnedSkill(parsed.name)) ctx.ui.setStatus("rpiv-skill", `rpiv: ${parsed.name}`);
 	const content = await takeGitContextIfChanged(pi);
 	if (!content) return undefined;
 	return { message: buildGitContextMessage(pi, content) };
 }
 
+async function onAgentEnd(_event: AgentEndEvent, ctx: ExtensionContext): Promise<void> {
+	ctx.ui.setStatus("rpiv-skill", undefined);
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+// Allowlist of rpiv-pi's own skill names, generated at module load by reading
+// the package's bundled skills/ directory (see paths.ts — matches the
+// `pi.skills` manifest in package.json). Prevents the status bar from
+// claiming `rpiv:` ownership of user-supplied or third-party skills.
+const OWNED_SKILL_NAMES: ReadonlySet<string> = (() => {
+	try {
+		return new Set(
+			readdirSync(BUNDLED_SKILLS_DIR, { withFileTypes: true })
+				.filter((e) => e.isDirectory())
+				.map((e) => e.name),
+		);
+	} catch {
+		return new Set<string>();
+	}
+})();
+
+function isOwnedSkill(name: string): boolean {
+	return OWNED_SKILL_NAMES.has(name);
+}
+
 function resetInjectionState(): void {
 	clearInjectionState();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",

package/skills/_shared/changelog-bootstrap.mjs

@@ -0,0 +1,42 @@
+// Pre-bake the bail-out checks and reference values for the changelog skill.
+//
+// Prints:
+//   in_repo: yes|no
+//   last_tag: <tag>|(no tags)
+//   ---changelogs---
+//   <one CHANGELOG.md path per line>     (empty if none tracked)
+//
+// All values are bounded. The unbounded `git log` and `git diff` calls
+// remain LLM-issued via Bash (their output can exceed the 50KB tail budget).
+//
+// Always exits 0 — non-repo cwd collapses to `in_repo: no` and empty sections.
+import { execFileSync } from "node:child_process";
+
+const safe = (args, fb) => {
+	try {
+		return execFileSync("git", args, {
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+	} catch {
+		return fb;
+	}
+};
+
+const root = safe(["rev-parse", "--show-toplevel"], "").trim();
+const inRepo = root ? "yes" : "no";
+
+process.stdout.write(`in_repo: ${inRepo}\n`);
+
+if (!root) {
+	process.stdout.write("last_tag: (not in a git repo)\n");
+	process.stdout.write("---changelogs---\n");
+	process.exit(0);
+}
+
+const lastTag = safe(["describe", "--tags", "--abbrev=0"], "").trim();
+process.stdout.write(`last_tag: ${lastTag || "(no tags)"}\n`);
+
+const changelogs = safe(["ls-files", "CHANGELOG.md", "**/CHANGELOG.md"], "");
+process.stdout.write("---changelogs---\n");
+process.stdout.write(changelogs);

package/skills/_shared/git-changes.mjs

@@ -0,0 +1,70 @@
+// Pre-bake the "what's changed" snapshot for the commit skill.
+//
+// Prints:
+//   in_repo: yes|no
+//   ---status---
+//   <git status --short>            (capped at 200 lines + footer)
+//   ---diffstat---
+//   <git diff HEAD --stat --ignore-submodules=all>  | fallback for no-HEAD
+//
+// Full `git diff` is deliberately NOT included — large diffs would push the
+// 50KB / 2000-line tail-truncation budget. The commit skill issues
+// `git diff <file>` via the Bash tool when it needs per-file detail.
+//
+// Always exits 0 — non-repo cwd or no-HEAD initial repo collapses to safe
+// fallback strings so the skill body never receives a `[Shell error: ...]`.
+import { execFileSync } from "node:child_process";
+
+const LINE_CAP = 200;
+
+const safe = (args, fb) => {
+	try {
+		return execFileSync("git", args, {
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+	} catch {
+		return fb;
+	}
+};
+
+// Emit `raw` line-capped at LINE_CAP, with a truncation footer when over-limit.
+// Empty input → `emptyLabel`. Both the status and diffstat sections are
+// line-per-file in shape, so the "more files truncated" footer matches the
+// convention in code-review/_helpers/review-range.mjs.
+const emitCapped = (raw, emptyLabel) => {
+	const lines = raw.split("\n");
+	const trailingEmpty = lines.length > 0 && lines.at(-1) === "";
+	const real = trailingEmpty ? lines.slice(0, -1) : lines;
+	if (real.length === 0 || (real.length === 1 && real[0] === "")) {
+		process.stdout.write(`${emptyLabel}\n`);
+	} else if (real.length > LINE_CAP) {
+		process.stdout.write(real.slice(0, LINE_CAP).join("\n"));
+		process.stdout.write(`\n(... ${real.length - LINE_CAP} more files truncated ...)\n`);
+	} else {
+		process.stdout.write(`${real.join("\n")}\n`);
+	}
+};
+
+const root = safe(["rev-parse", "--show-toplevel"], "");
+const inRepo = root ? "yes" : "no";
+
+process.stdout.write(`in_repo: ${inRepo}\n`);
+
+if (!root) {
+	process.exit(0);
+}
+
+process.stdout.write("---status---\n");
+emitCapped(safe(["status", "--short"], ""), "(working tree clean)");
+
+// `git diff HEAD --stat` errors on a fresh repo with no commits — substitute
+// a fallback marker so the LLM knows the status block above already covers
+// what would land in the initial commit.
+const hasHead = safe(["rev-parse", "--verify", "--quiet", "HEAD"], "") !== "";
+process.stdout.write("---diffstat---\n");
+if (!hasHead) {
+	process.stdout.write("(no HEAD yet — initial commit; status above lists all files to be added)\n");
+} else {
+	emitCapped(safe(["diff", "HEAD", "--stat", "--ignore-submodules=all"], ""), "(no changes against HEAD)");
+}

package/skills/_shared/git-changes.test.ts

@@ -0,0 +1,107 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const GIT_CHANGES_MJS = fileURLToPath(new URL("./git-changes.mjs", import.meta.url));
+
+const run = (cwd: string) =>
+	execFileSync("node", [GIT_CHANGES_MJS], {
+		cwd,
+		encoding: "utf-8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+
+const gitIn = (cwd: string, ...args: string[]) =>
+	execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+
+const initRepo = (cwd: string) => {
+	gitIn(cwd, "init", "--initial-branch=main", "-q");
+	gitIn(cwd, "config", "user.email", "test@example.com");
+	gitIn(cwd, "config", "user.name", "Test User");
+	gitIn(cwd, "config", "commit.gpgsign", "false");
+};
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "rpiv-git-changes-"));
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("git-changes.mjs", () => {
+	it("emits `in_repo: no` and exits when cwd is not a git repo", () => {
+		const out = run(dir);
+		expect(out).toContain("in_repo: no");
+		expect(out).not.toContain("---status---");
+		expect(out).not.toContain("---diffstat---");
+	});
+
+	it("emits no-HEAD fallback for an initialized repo with zero commits", () => {
+		initRepo(dir);
+		writeFileSync(join(dir, "f.txt"), "hi");
+		gitIn(dir, "add", "f.txt");
+		const out = run(dir);
+		expect(out).toContain("in_repo: yes");
+		expect(out).toContain("---status---");
+		expect(out).toMatch(/^A\s+f\.txt$/m);
+		expect(out).toContain("---diffstat---");
+		expect(out).toContain("(no HEAD yet");
+	});
+
+	it("emits `(working tree clean)` when status is empty against HEAD", () => {
+		initRepo(dir);
+		writeFileSync(join(dir, "f.txt"), "hi");
+		gitIn(dir, "add", "f.txt");
+		gitIn(dir, "commit", "-m", "init", "-q");
+		const out = run(dir);
+		expect(out).toContain("---status---\n(working tree clean)");
+		expect(out).toContain("---diffstat---");
+		expect(out).toContain("(no changes against HEAD)");
+	});
+
+	it("emits diffstat lines when there are committed-tree differences", () => {
+		initRepo(dir);
+		writeFileSync(join(dir, "f.txt"), "hi");
+		gitIn(dir, "add", "f.txt");
+		gitIn(dir, "commit", "-m", "init", "-q");
+		writeFileSync(join(dir, "f.txt"), "hi\nworld\n");
+		const out = run(dir);
+		const diffstatBlock = out.slice(out.indexOf("---diffstat---"));
+		expect(diffstatBlock).toMatch(/f\.txt\s*\|\s*\d+/);
+	});
+
+	it("caps status at 200 files with `(... N more files truncated ...)` footer", () => {
+		initRepo(dir);
+		writeFileSync(join(dir, ".gitignore"), "");
+		gitIn(dir, "add", ".gitignore");
+		gitIn(dir, "commit", "-m", "init", "-q");
+		// Create 250 untracked files — `git status --short` lists each as `?? path`.
+		for (let i = 0; i < 250; i++) writeFileSync(join(dir, `f${i}.txt`), "");
+		const out = run(dir);
+		const statusBlock = out.slice(out.indexOf("---status---"), out.indexOf("---diffstat---"));
+		const statusLines = statusBlock.split("\n").filter((l) => l.startsWith("??"));
+		expect(statusLines).toHaveLength(200);
+		expect(statusBlock).toContain("(... 50 more files truncated ...)");
+	});
+
+	it("caps diffstat at 200 lines with truncation footer (I4 — symmetry with status cap)", () => {
+		initRepo(dir);
+		// Seed 250 files committed at HEAD, then modify all of them so
+		// `git diff HEAD --stat` produces 250+ lines (one per file + summary).
+		writeFileSync(join(dir, ".gitignore"), "");
+		gitIn(dir, "add", ".gitignore");
+		for (let i = 0; i < 250; i++) writeFileSync(join(dir, `f${i}.txt`), "a\n");
+		gitIn(dir, "add", "-A");
+		gitIn(dir, "commit", "-m", "seed", "-q");
+		for (let i = 0; i < 250; i++) writeFileSync(join(dir, `f${i}.txt`), "b\nc\n");
+		const out = run(dir);
+		const diffstatBlock = out.slice(out.indexOf("---diffstat---"));
+		expect(diffstatBlock).toContain("more files truncated ...)");
+	});
+});

package/skills/_shared/git-context.mjs

@@ -0,0 +1,37 @@
+// Print six labeled lines summarising the current cwd's git state.
+// Always exits 0 — every failure path collapses to a stable fallback so the
+// skill body never receives a `[Shell error: ...]` substitution.
+//
+//   branch: <name>|no-branch
+//   commit: <short-sha>|no-commit
+//   repo:   <basename of toplevel>|unknown
+//   root:   <absolute toplevel path>|(empty)
+//   in_repo: yes|no
+//   author: <git config user.name>|unknown
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+
+const safe = (args, fb) => {
+	try {
+		const out = execFileSync("git", args, {
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+		return out || fb;
+	} catch {
+		return fb;
+	}
+};
+
+const root = safe(["rev-parse", "--show-toplevel"], "");
+process.stdout.write(
+	[
+		`branch: ${safe(["branch", "--show-current"], "no-branch")}`,
+		`commit: ${safe(["rev-parse", "--short", "HEAD"], "no-commit")}`,
+		`repo: ${root ? basename(root) : "unknown"}`,
+		`root: ${root}`,
+		`in_repo: ${root ? "yes" : "no"}`,
+		`author: ${safe(["config", "user.name"], "unknown")}`,
+		"",
+	].join("\n"),
+);

package/skills/_shared/git-context.test.ts

@@ -0,0 +1,90 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const GIT_CONTEXT_MJS = fileURLToPath(new URL("./git-context.mjs", import.meta.url));
+
+// Spawn git-context.mjs with `cwd` overridden so the helper resolves the
+// passed tmpdir (not the test runner's repo root).
+const runIn = (cwd: string) =>
+	execFileSync("node", [GIT_CONTEXT_MJS], {
+		cwd,
+		encoding: "utf-8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+
+const gitIn = (cwd: string, ...args: string[]) =>
+	execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+
+const initRepo = (cwd: string) => {
+	gitIn(cwd, "init", "--initial-branch=main", "-q");
+	gitIn(cwd, "config", "user.email", "test@example.com");
+	gitIn(cwd, "config", "user.name", "Test User");
+	gitIn(cwd, "config", "commit.gpgsign", "false");
+};
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "rpiv-git-context-"));
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("git-context.mjs", () => {
+	it("emits six labeled lines for a fresh repo with one commit", () => {
+		initRepo(dir);
+		writeFileSync(join(dir, "f.txt"), "hello");
+		gitIn(dir, "add", "f.txt");
+		gitIn(dir, "commit", "-m", "init", "-q");
+
+		const out = runIn(dir);
+		const lines = out.split("\n");
+		// macOS `mkdtempSync` returns `/var/folders/...` but `git rev-parse
+		// --show-toplevel` normalises symlinks to `/private/var/folders/...`.
+		// Compare against realpath so the test is platform-stable.
+		const realDir = realpathSync(dir);
+		expect(lines).toContain("branch: main");
+		expect(lines.some((l) => /^commit: [0-9a-f]{7,}$/.test(l))).toBe(true);
+		expect(lines).toContain(`repo: ${basename(realDir)}`);
+		expect(lines).toContain(`root: ${realDir}`);
+		expect(lines).toContain("in_repo: yes");
+		expect(lines).toContain("author: Test User");
+	});
+
+	it("falls back gracefully when cwd is not a git repo", () => {
+		// No `git init` — `git rev-parse --show-toplevel` fails.
+		const out = runIn(dir);
+		const lines = out.split("\n");
+		expect(lines).toContain("branch: no-branch");
+		expect(lines).toContain("commit: no-commit");
+		expect(lines).toContain("repo: unknown");
+		expect(lines).toContain("root: ");
+		expect(lines).toContain("in_repo: no");
+		// `author:` may be "unknown" or pulled from global git config — the
+		// helper falls back to `unknown` when `git config user.name` errors
+		// (which it doesn't when global config is present). Either is OK; the
+		// contract is just that the line is emitted.
+		expect(lines.some((l) => l.startsWith("author: "))).toBe(true);
+	});
+
+	it("exits 0 in both repo and non-repo cwds (never surfaces [Shell error])", () => {
+		expect(() => runIn(dir)).not.toThrow();
+		initRepo(dir);
+		expect(() => runIn(dir)).not.toThrow();
+	});
+
+	it("emits a trailing newline so chained helpers parse on their own line", () => {
+		initRepo(dir);
+		writeFileSync(join(dir, "f.txt"), "hello");
+		gitIn(dir, "add", "f.txt");
+		gitIn(dir, "commit", "-m", "init", "-q");
+		const out = runIn(dir);
+		expect(out.endsWith("\n")).toBe(true);
+	});
+});

package/skills/_shared/list-recent.mjs

@@ -0,0 +1,35 @@
+// List N most recently modified files in a directory, newest first, one per line.
+// Usage: node list-recent.mjs <dir> [count=10]
+//   <dir>   — relative paths are resolved against the git root (or cwd if not in a repo).
+//   <count> — max entries to print (default 10).
+// Empty stdout when the directory does not exist or contains no files.
+// Always exits 0 — directory-missing is a recoverable state, not an error.
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+const [rawDir = ".", nStr = "10"] = process.argv.slice(2);
+const n = Math.max(1, Number.parseInt(nStr, 10) || 10);
+
+const gitRoot = (() => {
+	try {
+		return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+	} catch {
+		return "";
+	}
+})();
+
+const dir = isAbsolute(rawDir) ? rawDir : resolve(gitRoot || process.cwd(), rawDir);
+
+if (!existsSync(dir)) process.exit(0);
+
+const items = readdirSync(dir, { withFileTypes: true })
+	.filter((d) => d.isFile())
+	.map((d) => ({ name: d.name, mtime: statSync(join(dir, d.name)).mtimeMs }))
+	.sort((a, b) => b.mtime - a.mtime)
+	.slice(0, n);
+
+for (const it of items) console.log(it.name);