@monte3l/groundwork 0.0.0

package/templates/packs/harness-extras/files/.claude/hooks/reinject-compact-handoff.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * SessionStart (matcher `compact|resume|startup`): reads the handoff
+ * artifact `write-compact-handoff.mjs` (`PreCompact`) wrote and re-injects
+ * it as `additionalContext` -- so state reconstruction doesn't depend on the
+ * summary having retained it, whether the next session started because of a
+ * compaction, a `--resume`/`--continue`, or a fresh `startup` that inherits
+ * a worktree an earlier, since-killed session left dirty.
+ *
+ * `resume`/`startup` are included alongside `compact` because a
+ * `compact`-only registration would leave a handoff written by a
+ * `PreCompact` whose session was then killed (crash, OOM, Ctrl-C) sitting
+ * in `tmp/` forever -- the next session, on any source, would never see it.
+ * `SessionEnd` has no guaranteed abnormal-termination signal, so the fix is
+ * on this read side, not a new write-side hook.
+ *
+ * A `resume`/`startup` read has no one-compaction freshness guarantee the
+ * way a `compact` read does (it may be reading a handoff several sessions
+ * old), so `formatHandoff` flags anything older than 24h as likely stale.
+ *
+ * Advisory-only: always exits 0. A missing or unreadable artifact (first
+ * compaction ever, or the write hook failed) means nothing to inject --
+ * silently no-op rather than surfacing a confusing "handoff not found"
+ * line every time the artifact is legitimately absent.
+ */
+import process from "node:process";
+import { readFileSync, existsSync, unlinkSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { HANDOFF_REL_PATH } from "./write-compact-handoff.mjs";
+
+const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * True when `handoff.capturedAt` parses to a timestamp more than 24h before
+ * `nowMs`. A malformed or missing `capturedAt` is never treated as stale --
+ * silence here means "no age signal available", not "definitely fresh".
+ *
+ * @param {Record<string, any>} handoff
+ * @param {number} [nowMs] injectable for testing; defaults to `Date.now()`
+ * @returns {boolean}
+ */
+export function isStale(handoff, nowMs = Date.now()) {
+  const capturedAt = handoff.capturedAt;
+  if (typeof capturedAt !== "string") return false;
+  const capturedMs = Date.parse(capturedAt);
+  if (Number.isNaN(capturedMs)) return false;
+  return nowMs - capturedMs > STALE_THRESHOLD_MS;
+}
+
+/**
+ * Render a handoff payload (as built by `write-compact-handoff.mjs`) into
+ * the `additionalContext` string.
+ *
+ * @param {Record<string, any>} handoff
+ * @param {number} [nowMs] injectable for testing; defaults to `Date.now()`
+ * @returns {string}
+ */
+export function formatHandoff(handoff, nowMs = Date.now()) {
+  const lines = [
+    "Prior-session handoff -- state captured just before an earlier " +
+      "compaction, possibly from a session that has since ended:",
+    `  • Branch: \`${handoff.branch || "(unknown)"}\` at \`${
+      handoff.worktree || "(unknown)"
+    }\``,
+  ];
+
+  const lastCommit = handoff.lastCommit;
+  if (
+    lastCommit &&
+    typeof lastCommit === "object" &&
+    typeof lastCommit.sha === "string"
+  ) {
+    lines.push(
+      `  • Last commit: \`${lastCommit.sha.slice(0, 12)}\` ` +
+        `(signature: \`${lastCommit.signature ?? "?"}\`)`,
+    );
+  }
+
+  const uncommitted = Array.isArray(handoff.uncommittedFiles)
+    ? handoff.uncommittedFiles
+    : [];
+  if (uncommitted.length > 0) {
+    const shown = uncommitted.slice(0, 10);
+    const more = uncommitted.length - shown.length;
+    lines.push(
+      `  • Uncommitted (${uncommitted.length}): ${shown.join(", ")}` +
+        (more > 0 ? ` (+${more} more)` : ""),
+    );
+  }
+
+  const journals = Array.isArray(handoff.journals) ? handoff.journals : [];
+  if (journals.length > 0) {
+    lines.push(`  • Scratchpad journal(s): ${journals.join(", ")}`);
+  }
+
+  if (isStale(handoff, nowMs)) {
+    lines.push(
+      "  ⚠ This handoff is more than 24h old -- likely stale, verify " +
+        "carefully before trusting it.",
+    );
+  }
+
+  lines.push(
+    "Re-verify this against current `git status` before acting on it -- it " +
+      "is a snapshot from just before compaction, not necessarily still " +
+      "current.",
+  );
+  return lines.join("\n");
+}
+
+/** `SessionStart` `source` values this hook re-injects the handoff for. */
+export const REINJECT_SOURCES = new Set(["compact", "resume", "startup"]);
+
+/**
+ * Belt-and-suspenders alongside the settings.json
+ * `matcher: "compact|resume|startup"` registration -- if the harness ever
+ * routes an unmatched `SessionStart` here, stay silent rather than
+ * injecting a handoff into a `clear`/`fork` session it wasn't meant for.
+ * `input` can itself be `null` (valid JSON, e.g. a bare `null` payload) or
+ * any other shape -- read defensively rather than assume it's an object.
+ * Extracted from the CLI entry block so this check is unit-testable without
+ * spawning the script as a subprocess.
+ *
+ * @param {unknown} input the parsed `SessionStart` hook payload
+ * @returns {boolean} true when this SessionStart's source is one this hook
+ *   should re-inject the handoff for (compaction, resume, or startup)
+ */
+export function shouldReinject(input) {
+  if (typeof input !== "object" || input === null) return false;
+  const source = /** @type {{ source?: unknown }} */ (input).source;
+  return typeof source === "string" && REINJECT_SOURCES.has(source);
+}
+
+/**
+ * @param {string} handoffPath absolute path to the handoff artifact
+ * @returns {Record<string, any> | null} parsed payload, or null if absent
+ *   or unreadable/malformed
+ */
+export function readHandoff(handoffPath) {
+  if (!existsSync(handoffPath)) return null;
+  try {
+    return JSON.parse(readFileSync(handoffPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Deliberately inlined in every hook rather than shared: this pack's hook
+// budget is exactly its three hooks, so a helper module would cost a slot.
+// `import.meta.url` is symlink-resolved but `process.argv[1]` is not, so
+// comparing them directly is false under any symlinked path and the body would
+// never run -- exit 0.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  let input;
+  try {
+    input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    process.exit(0);
+  }
+
+  if (!shouldReinject(input)) process.exit(0);
+
+  const handoffPath = join(root, HANDOFF_REL_PATH);
+  const handoff = readHandoff(handoffPath);
+  if (handoff === null) process.exit(0);
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: formatHandoff(handoff),
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+
+  // One-shot: a stale handoff re-injected after a SECOND compaction would
+  // describe state from before the FIRST, no longer current. Consumed once.
+  try {
+    unlinkSync(handoffPath);
+  } catch {
+    // Not fatal -- the next PreCompact overwrites it regardless.
+  }
+  process.exit(0);
+}

package/templates/packs/harness-extras/files/.claude/hooks/write-compact-handoff.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * PreCompact: writes a structured handoff artifact to `tmp/compact-handoff.json`
+ * before Claude Code compacts the conversation.
+ *
+ * Durable artifacts outperform in-place summarization for long-running work:
+ * post-compaction state reconstruction shouldn't depend on the summary
+ * having retained it. `reinject-compact-handoff.mjs` (`SessionStart`,
+ * matcher `compact|resume|startup`) reads this artifact back as
+ * `additionalContext`.
+ *
+ * Deliberately git/fs-only, no network calls (no lookup for a PR number) --
+ * a PreCompact hook runs on the hot path of every compaction, so a network
+ * round-trip here would add latency to an already-slow moment. The branch
+ * name is enough to look up the PR when needed (`gh pr list --head <branch>`).
+ *
+ * "Pending gates" is deliberately NOT a live re-run of `pnpm verify` (far
+ * too slow for a hook) -- it's `git status --porcelain`, a fast, honest
+ * proxy for "there is uncommitted work here."
+ *
+ * "Journal paths" is best-effort: a hook has no documented way to address
+ * the ephemeral session scratchpad directory a subagent may have journaled
+ * to -- so this only lists journal-shaped files under this repo's own
+ * gitignored `tmp/` scratch directory (real, cheap, deterministic), not a
+ * claim of session-scratchpad discovery this hook cannot honestly make.
+ *
+ * Advisory-only: always exits 0. A write failure (e.g. `tmp/` unwritable)
+ * is swallowed -- losing a handoff on this one compaction is a hint the
+ * next session can't reconstruct as cheaply, not a fatal failure of the
+ * turn in progress.
+ */
+import process from "node:process";
+import {
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  existsSync,
+  realpathSync,
+} from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+export const HANDOFF_REL_PATH = "tmp/compact-handoff.json";
+
+/**
+ * Trims only trailing whitespace/newlines, never leading -- `git status
+ * --porcelain`'s first two columns are semantically meaningful status
+ * codes that can legitimately BE a leading space (` M` = modified in the
+ * worktree only, vs. `M ` = staged); a plain `.trim()` would silently
+ * corrupt that first line's status code.
+ *
+ * @param {string[]} args
+ * @returns {string | null} trailing-trimmed stdout, or null on any failure
+ *   (missing git, not a repo, command error) -- never throws.
+ */
+export function runGit(args, cwd = root) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+    }).replace(/\s+$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {string} current branch, "" if unavailable */
+export function currentBranch(cwd = root) {
+  return runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd) ?? "";
+}
+
+/** @returns {string} repo root of the worktree the hook is running in */
+export function currentWorktree(cwd = root) {
+  return runGit(["rev-parse", "--show-toplevel"], cwd) ?? cwd;
+}
+
+/**
+ * @returns {{ sha: string, signature: string } | null} the last commit's
+ *   SHA and its `%G?` signature-verification code (`G`=good, `B`=bad,
+ *   `N`=unsigned, ...), or null if no commits/not a repo.
+ */
+export function lastCommitInfo(cwd = root) {
+  const raw = runGit(["log", "-1", "--format=%H%x09%G?"], cwd);
+  if (raw === null || raw === "") return null;
+  const [sha, signature] = raw.split("\t");
+  if (!sha) return null;
+  return { sha, signature: signature ?? "N" };
+}
+
+/**
+ * @returns {string[]} `git status --porcelain` lines -- a fast, honest proxy
+ *   for "there is uncommitted work here," not a gate re-run.
+ */
+export function uncommittedFiles(cwd = root) {
+  const raw = runGit(["status", "--porcelain"], cwd);
+  if (raw === null || raw === "") return [];
+  return raw.split("\n").filter((line) => line.length > 0);
+}
+
+/**
+ * Journal-shaped files under this repo's gitignored `tmp/` scratch
+ * directory -- best-effort, not a claim of ephemeral session-scratchpad
+ * discovery (see file header).
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} repo-relative paths, sorted
+ */
+export function findScratchJournals(repoRoot) {
+  const tmpDir = join(repoRoot, "tmp");
+  if (!existsSync(tmpDir)) return [];
+  let entries;
+  try {
+    entries = readdirSync(tmpDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter(
+      (e) => e.isFile() && /journal/i.test(e.name) && e.name.endsWith(".md"),
+    )
+    .map((e) => `tmp/${e.name}`)
+    .sort();
+}
+
+/**
+ * Build the full handoff payload from live git/fs state.
+ *
+ * @param {string} cwd
+ * @returns {Record<string, unknown>}
+ */
+export function buildHandoff(cwd = root) {
+  const worktree = currentWorktree(cwd);
+  return {
+    capturedAt: new Date().toISOString(),
+    branch: currentBranch(cwd),
+    worktree,
+    lastCommit: lastCommitInfo(cwd),
+    uncommittedFiles: uncommittedFiles(cwd),
+    journals: findScratchJournals(worktree),
+  };
+}
+
+// Deliberately inlined in every hook rather than shared: this pack's hook
+// budget is exactly its three hooks, so a helper module would cost a slot.
+// `import.meta.url` is symlink-resolved but `process.argv[1]` is not, so
+// comparing them directly is false under any symlinked path and the body would
+// never run -- exit 0.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  // Drain stdin (Claude Code pipes the hook payload) even though this hook
+  // doesn't need any field from it -- leaving it unread can leave the pipe
+  // open under some harness/runtime combinations. `void` references the
+  // loop variable explicitly rather than relying on a project's eslint
+  // config exempting `^_`-prefixed vars for .mjs files, which this
+  // baseline's own eslint.config.js only does for `.ts`.
+  for await (const chunk of process.stdin) {
+    void chunk;
+  }
+
+  try {
+    const handoff = buildHandoff();
+    const handoffPath = join(root, HANDOFF_REL_PATH);
+    mkdirSync(join(root, "tmp"), { recursive: true });
+    writeFileSync(handoffPath, `${JSON.stringify(handoff, null, 2)}\n`);
+  } catch {
+    // Advisory-only -- never block or fail a compaction over this.
+  }
+  process.exit(0);
+}