@juicesharp/rpiv-pi 1.9.2 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.9.2",
+  "version": "1.10.1",
   "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);

package/skills/_shared/list-recent.test.ts

@@ -0,0 +1,77 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, utimesSync, 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 LIST_RECENT_MJS = fileURLToPath(new URL("./list-recent.mjs", import.meta.url));
+
+const run = (cwd: string, ...argv: string[]) =>
+	execFileSync("node", [LIST_RECENT_MJS, ...argv], {
+		cwd,
+		encoding: "utf-8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+
+const touch = (path: string, mtimeSec: number) => {
+	writeFileSync(path, "");
+	utimesSync(path, mtimeSec, mtimeSec);
+};
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "rpiv-list-recent-"));
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("list-recent.mjs", () => {
+	it("returns files sorted by mtime descending (newest first)", () => {
+		touch(join(dir, "old.md"), 1_000_000_000);
+		touch(join(dir, "mid.md"), 1_000_000_500);
+		touch(join(dir, "new.md"), 1_000_001_000);
+		const out = run(dir, dir, "10");
+		expect(out.trim().split("\n")).toEqual(["new.md", "mid.md", "old.md"]);
+	});
+
+	it("caps output at N entries", () => {
+		for (let i = 0; i < 5; i++) touch(join(dir, `f${i}.md`), 1_000_000_000 + i);
+		const out = run(dir, dir, "3");
+		expect(out.trim().split("\n")).toHaveLength(3);
+	});
+
+	it("emits nothing for a missing directory (exit 0)", () => {
+		const missing = join(dir, "does-not-exist");
+		const out = run(dir, missing, "10");
+		expect(out).toBe("");
+	});
+
+	it("emits nothing for an empty directory (exit 0)", () => {
+		const out = run(dir, dir, "10");
+		expect(out).toBe("");
+	});
+
+	it("skips subdirectories (files only)", () => {
+		touch(join(dir, "real.md"), 1_000_000_000);
+		execFileSync("mkdir", [join(dir, "sub")]);
+		const out = run(dir, dir, "10");
+		expect(out.trim().split("\n")).toEqual(["real.md"]);
+	});
+
+	it("defaults count to 10 when not provided", () => {
+		for (let i = 0; i < 15; i++) touch(join(dir, `f${i}.md`), 1_000_000_000 + i);
+		const out = run(dir, dir);
+		expect(out.trim().split("\n")).toHaveLength(10);
+	});
+
+	it("clamps count to ≥1 when given 0 or negative", () => {
+		touch(join(dir, "only.md"), 1_000_000_000);
+		const out = run(dir, dir, "0");
+		// Math.max(1, ...) — 0 becomes 1, so we get the single newest file.
+		expect(out.trim().split("\n")).toEqual(["only.md"]);
+	});
+});

package/skills/_shared/now.mjs

@@ -0,0 +1,14 @@
+// Print one tab-separated line: <iso>\t<slug>
+//   <iso>  — ISO 8601 with local timezone offset, e.g. 2026-05-19T11:23:04-0400
+//   <slug> — first 19 chars of <iso> with `T`→`_` and `:`→`-`, e.g. 2026-05-19_11-23-04
+// No trailing newline so the value can be inlined cleanly.
+// No locale dependence: timestamp built from Date components, not toLocaleString().
+const d = new Date();
+const pad = (n) => String(n).padStart(2, "0");
+const tzMin = -d.getTimezoneOffset();
+const tzSign = tzMin >= 0 ? "+" : "-";
+const tzAbs = Math.abs(tzMin);
+const offset = `${tzSign}${pad(Math.floor(tzAbs / 60))}${pad(tzAbs % 60)}`;
+const iso = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${offset}`;
+const slug = iso.slice(0, 19).replaceAll(":", "-").replace("T", "_");
+process.stdout.write(`${iso}\t${slug}`);

package/skills/_shared/now.test.ts

@@ -0,0 +1,48 @@
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const NOW_MJS = fileURLToPath(new URL("./now.mjs", import.meta.url));
+
+const runNow = () => execFileSync("node", [NOW_MJS], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+
+describe("now.mjs", () => {
+	it("emits exactly one tab-separated line: <iso>\\t<slug>", () => {
+		const out = runNow();
+		// Single line, no leading/trailing newline — every consumer in the
+		// skill set concatenates `echo` or `git-context.mjs` output directly
+		// after this. A trailing \n would still parse, but a trailing space or
+		// extra tab would silently corrupt the slug-based filename.
+		expect(out).not.toContain("\n");
+		const [iso, slug, ...rest] = out.split("\t");
+		expect(rest).toHaveLength(0);
+		expect(iso).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[+-]\d{4}$/);
+		expect(slug).toMatch(/^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}$/);
+	});
+
+	it("slug is derived from iso: T→_, :→-, first 19 chars", () => {
+		const out = runNow();
+		const [iso, slug] = out.split("\t");
+		expect(slug).toBe(iso.slice(0, 19).replaceAll(":", "-").replace("T", "_"));
+	});
+
+	it("no trailing newline (contract that revise/SKILL.md's `echo` separator depends on)", () => {
+		const out = runNow();
+		// If this assertion ever flips, every Metadata block that combines
+		// now.mjs with a second helper via `echo` will have a blank line
+		// inserted between them — harmless — but the explicit no-`echo` peer
+		// (none currently exist after the I1 fix) would now parse cleanly.
+		// Keep this contract pinned so revise/SKILL.md's `echo` line is
+		// load-bearing as documented.
+		expect(out.endsWith("\n")).toBe(false);
+		expect(out.endsWith("\t")).toBe(false);
+	});
+
+	it("iso timezone offset is exactly +HHMM or -HHMM (no colon, no Z)", () => {
+		const out = runNow();
+		const [iso] = out.split("\t");
+		expect(iso).toMatch(/[+-]\d{4}$/);
+		expect(iso.endsWith("Z")).toBe(false);
+		expect(iso).not.toMatch(/[+-]\d{2}:\d{2}$/);
+	});
+});

package/skills/blueprint/SKILL.md

@@ -2,6 +2,7 @@
 name: blueprint
 description: Plan complex features by decomposing them into vertical slices (one slice equals one phase) with developer micro-checkpoints between phases, producing an implement-ready phased plan in .rpiv/artifacts/plans/. Use for complex multi-component features touching 6+ files across multiple layers when iterative review between slices is valuable. Requires a research artifact or a solutions artifact (from explore). Prefer blueprint over plan when mid-flight micro-checkpoints matter, and prefer plan when a straightforward phased breakdown is enough.
 argument-hint: "[research artifact path]"
+shell-timeout: 10
 ---
 
 # Blueprint
@@ -12,6 +13,19 @@ You are tasked with planning how code will be shaped for a feature or change AND
 
 `$ARGUMENTS` — path to a research artifact (`.rpiv/artifacts/research/*.md`) or a solutions artifact (`.rpiv/artifacts/solutions/*.md`).
 
+## Metadata
+
+```!
+node "${SKILL_DIR}/../_shared/now.mjs"
+echo
+node "${SKILL_DIR}/../_shared/git-context.mjs"
+```
+
+- `now.mjs` (line 1) — `<iso>\t<slug>` tab-separated.
+- `git-context.mjs` (lines below) — `branch:` / `commit:` / `repo:` / `root:` / `in_repo:` / `author:`.
+
+Copy values verbatim — do not reformat the timezone offset.
+
 ## Flow
 
 1. Input → 2. Research → 3. Dimension sweep → 4. Self-critique → 5. Checkpoint → 6. Decompose → 7. Generate slices → 8. Integration verify → 9. Finalize → 10. Independent review → 11. Triage & iterate → 12. Follow-ups
@@ -200,8 +214,8 @@ After the design summary is confirmed, decompose the feature into vertical slice
 3. **Confirm decomposition** using the `ask_user_question` tool. Question: "{N} slices for {feature}. Slice 1: {name} (foundation). Slices 2-N: {brief}. Approve decomposition?". Header: "Slices". Options: "Approve (Recommended)" (Proceed to slice-by-slice code generation); "Adjust slices" (Reorder, merge, or split slices before generating); "Change scope" (Add or remove files from the decomposition).
 
 4. **Create skeleton artifact** — immediately after decomposition is approved:
-   - Determine metadata: filename `.rpiv/artifacts/plans/YYYY-MM-DD_HH-MM-SS_topic.md`, repository name from git root, branch and commit from the git context injected at the start of the session (fallbacks: "no-branch" / "no-commit"), author from the injected User (fallback: "unknown")
-   - Timestamp: run `date +"%Y-%m-%dT%H:%M:%S%z"` — raw for `date:` and `last_updated:`, first 19 chars (`T`→`_`, `:`→`-`) for filename slug.
+   - Determine metadata from the Metadata block above: filename `.rpiv/artifacts/plans/<slug>_<topic>.md` (use `<slug>` from `now.mjs` line 1); `repository:` from `repo:`; `branch:` / `commit:` from matching labels; `author:` ← matching label (fallback: `unknown`).
+   - Timestamp: use `<iso>` from `now.mjs` line 1 for `date:` and `last_updated:` (copy the offset verbatim).
    - Write skeleton using the Write tool with `status: in-progress` in frontmatter
    - **Include all prose sections filled** from Steps 1-5: Overview, Requirements, Current State Analysis, Desired End State, What We're NOT Doing, Decisions, Ordering Constraints, Verification Notes, Performance Considerations, Migration Notes, Pattern References, Developer Context, References
    - **Phase sections**: one `## Phase N: {slice name}` heading per slice from the decomposition (in slice order), each with `### Overview`, `### Changes Required:` (one `#### N. path/to/file.ext` subsection per file with empty code fence + NEW/MODIFY label), and `### Success Criteria:` (empty Automated + Manual subsection headers — filled in Step 7.4 on approval)

package/skills/changelog/SKILL.md

@@ -3,6 +3,7 @@ name: changelog
 description: Regenerate the [Unreleased] section of every affected CHANGELOG.md in Keep a Changelog style. Reads commits since the last release tag plus any uncommitted or staged changes, classifies them by Conventional Commit prefix, and rewrites each [Unreleased] block. Works in single-package repos and monorepos (one CHANGELOG.md per package). Use when preparing a release or drafting changelog entries. Idempotent — safe to re-run as work lands.
 argument-hint: [--since <ref>]
 allowed-tools: Bash(git *), Read, Edit
+shell-timeout: 10
 ---
 
 # Generate CHANGELOG entries
@@ -11,7 +12,17 @@ You are tasked with regenerating the `## [Unreleased]` section of every affected
 
 ## Input
 
-`$ARGUMENTS` — optional `--since <ref>` flag. Empty/literal → range starts at the last release tag from `git describe --tags --abbrev=0`.
+`$ARGUMENTS` — optional `--since <ref>` flag. Empty/literal → range starts at `last_tag:` from the Metadata block.
+
+## Metadata
+
+```!
+node "${SKILL_DIR}/../_shared/changelog-bootstrap.mjs"
+```
+
+- `in_repo:` — `yes` or `no`. Used by Step 1.1.
+- `last_tag:` — last release tag, or `(no tags)`. Used by Step 1.3 and Step 2.1 when no `--since` is supplied.
+- `---changelogs---` block — paths of every tracked `CHANGELOG.md` (one per line, empty if none). Used by Step 1.2.
 
 ## Workflow
 
@@ -24,13 +35,13 @@ You are tasked with regenerating the `## [Unreleased]` section of every affected
 
 ## Step 1: Bail-out checks
 
-1. Run `git rev-parse --is-inside-work-tree`. If not a git repo, tell the user "This directory is not a git repository." and stop.
-2. Run `git ls-files 'CHANGELOG.md' '**/CHANGELOG.md'` to discover every tracked changelog. If zero results, tell the user "No `CHANGELOG.md` found in the repository — create one (root or per-package) before running this skill." and stop.
-3. Run `git describe --tags --abbrev=0` to confirm at least one release tag exists. If none, ask the user to supply `--since <ref>` and stop until they do.
+1. If `in_repo:` is `no`, tell the user "This directory is not a git repository." and stop.
+2. If the `---changelogs---` block is empty, tell the user "No `CHANGELOG.md` found in the repository — create one (root or per-package) before running this skill." and stop.
+3. If `last_tag:` is `(no tags)` AND `$ARGUMENTS` lacks `--since <ref>`, ask the user to supply `--since <ref>` and stop until they do.
 
 ## Step 2: Determine the change range
 
-1. Parse the input for a `--since <ref>` flag. If absent, set `SINCE=$(git describe --tags --abbrev=0)`.
+1. Parse the input for a `--since <ref>` flag. If absent, use `last_tag:` from the Metadata block as `SINCE`.
 2. The range is `$SINCE..HEAD` for committed changes, plus the current uncommitted+staged working tree.
 
 ## Step 3: Determine each CHANGELOG's scope, then collect commits + uncommitted hunks
@@ -75,7 +86,7 @@ Skip any commit whose subject matches one of these — they are release pipeline
 
 Flag a commit as breaking if any of these are true:
 
-- The type has a `!` suffix (`feat!:`, `refactor!:`, etc.)
+- The type carries an exclamation suffix (`feat!:`, `refactor!:`, etc.)
 - The commit body contains a `BREAKING CHANGE:` footer
 - The diff removes or renames an exported symbol, removes a CLI flag, or removes a public file