@jenga-ai/agent 3.0.0 → 3.1.1

package/README.md

@@ -40,7 +40,7 @@ Jenga AI solves each of these with structure: persistent engineering context mai
 - **Isolated git worktrees per task** — the Developer never works directly on your main branch
 - **Works with any AI coding agent or AI-native IDE** — Claude Code, GitHub Copilot, and Codex CLI are all supported today
 
-> 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
+> 📖 **Full reference:** [Docs site](https://samwelmunga.github.io/jenga-npm/reference.html) · **Intro Guide:** [Docs site](https://samwelmunga.github.io/jenga-npm/getting-started.html) — mirrored at [project/.wiki/documentation.md](project/.wiki/documentation.md) / [intro-guide.md](project/.wiki/intro-guide.md)
 
 ### "Isn't this just an LLM grading another LLM?"
 
@@ -171,6 +171,13 @@ Or clone directly:
 
 Run `j.status` at any time to see where the project stands.
 
+**CLI maintenance commands.** The `jenga` binary installed alongside the package (`jenga --help`)
+also ships a couple of maintenance commands, distinct from the in-agent `j.<name>` skills above:
+
+| Command | Description |
+|---|---|
+| `jenga doctor` (alias: `jenga clean`) | Scans `.agents/` and `.claude/` for orphaned package-owned files left behind by an upgrade (or any other mirror drift), previews them, and deletes only on explicit confirmation. Never deletes unattended — add `--dry-run` to preview only. See `docs/distribution.md` for the ownership heuristic and its false-positive posture. |
+
 ---
 
 ## Supported Platforms
@@ -208,7 +215,7 @@ Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your
 | `j.do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
 | `j.status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
 
-> 📖 **Full skill list** (planning, review, committing & maintenance commands): [project/.wiki/documentation.md](project/.wiki/documentation.md#skills)
+> 📖 **Full skill list** (planning, review, committing & maintenance commands): [Docs site](https://samwelmunga.github.io/jenga-npm/skills.html) — mirrored at [project/.wiki/documentation.md#skills](project/.wiki/documentation.md#skills)
 
 ---
 
@@ -225,4 +232,4 @@ Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your
 - You're doing a quick one-off script or single-session experiment
 - Your project has no meaningful test surface
 
-📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md)
+📖 **Full reference:** [Docs site](https://samwelmunga.github.io/jenga-npm/reference.html) — mirrored at [project/.wiki/documentation.md](project/.wiki/documentation.md)

package/bin/jenga.js

@@ -19,6 +19,8 @@ Usage:
   jenga init      Run the setup wizard (creates jenga.cli.json, registers hook)
   jenga attach    Write MCP config for this project so new sessions route through Jenga
   jenga status    Show router status and active session
+  jenga doctor    Scan .agents/ and .claude/ for orphaned package files and clean up
+                  interactively (alias: jenga clean). Add --dry-run to preview only.
 
 Options:
   --version, -v   Print version
@@ -57,6 +59,14 @@ async function main() {
       await runStatus(args);
       break;
     }
+    case "doctor":
+    case "clean": {
+      // Both names are the same code path (E26_S08_T02) — "doctor" and "clean" are
+      // intentionally interchangeable, never two implementations.
+      const { runDoctor } = await import("../lib/commands/doctor.js");
+      await runDoctor(args);
+      break;
+    }
     default:
       console.error(`Unknown command: ${cmd}\n`);
       console.log(USAGE);

package/hooks/copilot_session_end.sh

@@ -3,9 +3,13 @@
 #
 # Copilot CLI session-end entry point.
 #
-# GitHub Copilot CLI does not fire a native SessionEnd hook. Call this script
-# manually at the end of a Copilot session or as a post-step in any skill
-# that completes a significant pipeline stage (e.g. commit, lgtm).
+# GitHub Copilot CLI DOES fire a native `sessionEnd` hook (confirmed empirically against a real
+# installed `copilot` CLI under E16_S03_T03 — see docs/hook-parity.md). This script is wired as
+# that hook's command via `.github/hooks/jenga.json` (committed here; generated per-consumer at
+# `jenga init` / npm postinstall time via lib/generate-copilot-hooks.js — see E16_S03_T04).
+# It can also still be called manually — e.g. as a post-step in a skill, or on a Copilot install
+# that hasn't run `jenga init`/postinstall yet and so has no `.github/hooks/jenga.json` — the
+# manual path documented below remains a valid fallback, not the primary mechanism.
 #
 # This wrapper:
 #   1. Sources lib/resolve-project-dir.sh to export JENGA_PROJECT_DIR,

package/hooks/prompt_router_helper.js

@@ -1,16 +1,28 @@
 #!/usr/bin/env node
 // hooks/prompt_router_helper.js
-// Companion helper for prompt_router.sh — implements Claude Code UserPromptSubmit logic.
+// Companion helper for prompt_router.sh — implements the UserPromptSubmit /
+// userPromptSubmitted routing logic shared by Claude Code and GitHub Copilot CLI
+// (E16_S03_T04 — both platforms deliver a JSON stdin payload with a `prompt` field, so
+// no platform branching is needed here).
 // Reads JSON payload from stdin, checks if the Jenga Router is running,
 // and either routes the prompt or passes it through unchanged.
+//
+// ESM (root package.json sets "type": "module") — found and fixed under E16_S03_T04 while
+// verifying the new Copilot userPromptSubmitted wiring end-to-end: this file previously used
+// CommonJS require()/__dirname, which crashes under Node's ESM loader with
+// "ReferenceError: require is not defined in ES module scope". That crash predates this task
+// (present since the file's original authoring, e09242d) and affected the existing Claude-side
+// UserPromptSubmit hook equally — not something newly introduced by the Copilot wiring.
 
-"use strict";
-const { readFileSync, existsSync } = require("fs");
-const { join } = require("path");
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const projectRoot = join(__dirname, "..");
 
-// Read stdin (JSON payload from Claude Code: {"prompt": "..."})
+// Read stdin (JSON payload from Claude Code: {"prompt": "..."}, or from Copilot CLI's
+// userPromptSubmitted event: {"sessionId": "...", "timestamp": ..., "cwd": "...", "prompt": "..."})
 let input;
 try {
   const raw = readFileSync("/dev/stdin", "utf8").trim();

package/lib/commands/doctor.js

@@ -0,0 +1,351 @@
+/**
+ * lib/commands/doctor.js — `jenga doctor` / `jenga clean` interactive orphan cleanup (E26_S08_T02)
+ *
+ * Why this exists
+ * ────────────────
+ * `scripts/postinstall.js`'s manifest-based delete reconciliation (E26_S08_T01) only ever cleans
+ * up a path that a manifest THIS package's postinstall previously wrote lists. That is safe, but
+ * purely forward-looking: a consumer already installed before any manifest existed can never have
+ * their pre-existing orphans (retired `j:`-form skill files, excluded `j-<name>` twins, or any
+ * other drift) reconciled by postinstall alone — see `E26_S08`'s "Scope gap discovered after T01"
+ * section. `E26_S08_T03` closes that gap automatically for the pre-manifest-migration case
+ * specifically, going forward. This command is the manual stopgap that works right now, for any
+ * cause of drift (not only the one migration that surfaced the bug): a human runs it, reviews a
+ * candidate list, and confirms before anything is deleted.
+ *
+ * Heuristic — "looks package-owned"
+ * ──────────────────────────────────
+ * There is no manifest guarantee to lean on here (that is exactly the gap this command exists to
+ * cover), so eligibility is decided by a heuristic instead of provenance:
+ *
+ *   - A top-level directory under `<root>/skills/` is a candidate ONLY if it is not one of the
+ *     currently-installed package's own skill directories AND its `SKILL.md` (if present) carries
+ *     frontmatter whose `name:` matches `/^j[.:]/i` — the same anti-masquerading prefix regex
+ *     `lib/generate-skill-allow-list.js` already uses as the canonical "this looks like a genuine
+ *     Jenga skill identifier" signal. Every regular file recursively inside a confirmed candidate
+ *     directory becomes a delete candidate, grouped under that directory.
+ *   - A top-level `.md` file directly under `<root>/agents/` is a candidate if its name does not
+ *     match one of the currently-installed package's own agent files.
+ *   - Any path already recorded in that root's `.jenga-postinstall-manifest.json` is excluded —
+ *     manifest-listed paths already self-heal via the normal postinstall path (or will, once
+ *     E26_S08_T03 lands), so surfacing them here too would be redundant.
+ *
+ * False-positive posture (documented, not hidden): a consumer's own `SKILL.md` that happens to
+ * declare `name: j.<something>` frontmatter, or a consumer's own hand-dropped `.md` file placed
+ * directly under `agents/`, would be misclassified as package-owned. This is an accepted risk —
+ * the confirmation step below is the compensating control, not a convenience, per this task's
+ * `crucial_level: gated` note. A directory the package currently ships is NEVER inspected
+ * file-by-file, which is what lets a consumer's own extra file living inside an otherwise-current
+ * package skill directory survive untouched without a separate special case.
+ *
+ * Safety
+ * ──────
+ * Deletion re-uses the exact boundary/type checks `lib/postinstall-manifest.js`'s delete pass
+ * uses: `isInside` (must resolve strictly inside the mirror root), `lstatSync` regular-file check
+ * (symlinks refused, never followed), and directories are only ever pruned via the shared
+ * `pruneEmptyDirs` helper once genuinely empty — never deleted directly. Nothing is ever deleted
+ * without an explicit interactive "yes", and a non-TTY stdin never falls through to deleting.
+ *
+ * ESM, Node built-ins only — matches `lib/postinstall-manifest.js` and `lib/mirror.js`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+
+import { readManifest, isInside, pruneEmptyDirs } from '../postinstall-manifest.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Default package root: this file lives at <package>/lib/commands/doctor.js. */
+const DEFAULT_PACKAGE_ROOT = path.join(__dirname, '..', '..');
+
+/** Mirror roots a consumer install writes into (see docs/distribution.md). */
+const MIRROR_ROOTS = ['.agents', '.claude'];
+
+/** Jenga skill-name prefix regex — matches lib/generate-skill-allow-list.js's guard exactly. */
+const JENGA_NAME_PREFIX = /^j[.:]/i;
+
+// ── frontmatter helpers ─────────────────────────────────────────────────────
+
+/** Extract the frontmatter `name:` field from SKILL.md content, or null. */
+function extractSkillName(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  const nameMatch = fmMatch[1].match(/^name:\s*(.+)$/m);
+  if (!nameMatch) return null;
+  return nameMatch[1].trim().replace(/^["']|["']$/g, '');
+}
+
+/** True iff `<dir>/SKILL.md` exists and its frontmatter name looks like a genuine Jenga skill. */
+function looksLikeJengaSkillDir(dir) {
+  const skillMd = path.join(dir, 'SKILL.md');
+  let content;
+  try {
+    content = fs.readFileSync(skillMd, 'utf8');
+  } catch (_) {
+    return false; // no SKILL.md — not enough signal to call this package-owned
+  }
+  const name = extractSkillName(content);
+  return typeof name === 'string' && JENGA_NAME_PREFIX.test(name);
+}
+
+// ── package's own current shape ─────────────────────────────────────────────
+
+/** Top-level skill directory names the installed package currently ships. */
+function currentPackageSkillDirs(packageRoot) {
+  const dir = path.join(packageRoot, 'skills');
+  if (!fs.existsSync(dir)) return new Set();
+  return new Set(
+    fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+  );
+}
+
+/** Top-level agent `.md` file names the installed package currently ships. */
+function currentPackageAgentFiles(packageRoot) {
+  const dir = path.join(packageRoot, 'agents');
+  if (!fs.existsSync(dir)) return new Set();
+  return new Set(
+    fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => e.name)
+  );
+}
+
+// ── scan ─────────────────────────────────────────────────────────────────────
+
+/** Recursively collect relative POSIX paths of every regular file under `dir`. */
+function collectFiles(root, dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return;
+  }
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(root, abs, out);
+    } else {
+      let stat;
+      try {
+        stat = fs.lstatSync(abs);
+      } catch (_) {
+        continue;
+      }
+      if (!stat.isFile()) continue; // symlinks and other node types refused, not followed
+      out.push(path.relative(root, abs).split(path.sep).join('/'));
+    }
+  }
+}
+
+/**
+ * Scan one mirror root for orphan candidates.
+ *
+ * @param {object} opts
+ * @param {string} opts.destRoot     Absolute path to the mirror root (e.g. <consumer>/.agents).
+ * @param {string} opts.packageRoot  Absolute path to the currently-installed package root.
+ * @returns {{groups: Array<{label: string, files: string[]}>, total: number}}
+ */
+export function scanRoot({ destRoot, packageRoot }) {
+  const groups = [];
+  if (!fs.existsSync(destRoot)) return { groups, total: 0 };
+
+  const manifest = readManifest(destRoot);
+  const manifestPaths = new Set(manifest ? manifest.paths : []);
+
+  const currentSkillDirs = currentPackageSkillDirs(packageRoot);
+  const currentAgentFiles = currentPackageAgentFiles(packageRoot);
+
+  // skills/<name>/ — directory-level candidacy, then sweep every file inside.
+  const skillsDir = path.join(destRoot, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (currentSkillDirs.has(entry.name)) continue; // currently shipped — never inspected
+      const abs = path.join(skillsDir, entry.name);
+      if (!looksLikeJengaSkillDir(abs)) continue; // no Jenga-shaped SKILL.md — not enough signal
+
+      const files = [];
+      collectFiles(destRoot, abs, files);
+      const candidateFiles = files.filter((rel) => !manifestPaths.has(rel));
+      if (candidateFiles.length > 0) {
+        groups.push({ label: `skills/${entry.name}/`, files: candidateFiles });
+      }
+    }
+  }
+
+  // agents/<name>.md — flat file-level candidacy.
+  const agentsDir = path.join(destRoot, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      if (currentAgentFiles.has(entry.name)) continue; // currently shipped
+      const rel = `agents/${entry.name}`;
+      if (manifestPaths.has(rel)) continue;
+      let stat;
+      try {
+        stat = fs.lstatSync(path.join(agentsDir, entry.name));
+      } catch (_) {
+        continue;
+      }
+      if (!stat.isFile()) continue; // symlink refused
+      groups.push({ label: rel, files: [rel] });
+    }
+  }
+
+  const total = groups.reduce((n, g) => n + g.files.length, 0);
+  return { groups, total };
+}
+
+// ── delete ───────────────────────────────────────────────────────────────────
+
+/**
+ * Delete every file across `groups` (relative to `destRoot`), applying the same boundary/type
+ * checks the postinstall delete pass uses, then prune directories left empty.
+ *
+ * @returns {{deleted: string[], refused: Array<{path: string, reason: string}>}}
+ */
+function deleteGroups({ destRoot, groups }) {
+  const root = path.resolve(destRoot);
+  const deleted = [];
+  const refused = [];
+  const dirsToConsider = new Set();
+
+  for (const group of groups) {
+    for (const rel of group.files) {
+      const abs = path.resolve(root, rel);
+      if (!isInside(root, abs)) {
+        refused.push({ path: rel, reason: 'outside-dest-root' });
+        continue;
+      }
+      let stat;
+      try {
+        stat = fs.lstatSync(abs);
+      } catch (_) {
+        continue; // already gone
+      }
+      if (!stat.isFile()) {
+        refused.push({ path: rel, reason: 'not-a-regular-file' });
+        continue;
+      }
+      try {
+        fs.rmSync(abs);
+        deleted.push(rel);
+        dirsToConsider.add(path.dirname(abs));
+      } catch (e) {
+        refused.push({ path: rel, reason: `unlink-failed: ${e.code || e.message}` });
+      }
+    }
+  }
+
+  const prunedDirs = [];
+  for (const dir of dirsToConsider) {
+    pruneEmptyDirs(root, dir, prunedDirs);
+  }
+
+  return { deleted, refused, prunedDirs: prunedDirs.sort() };
+}
+
+// ── prompt ───────────────────────────────────────────────────────────────────
+
+function askYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {string[]} args
+ * @param {object}   [opts]
+ * @param {string}   [opts.packageRoot]   Installed package root (default: this file's own package).
+ * @param {string}   [opts.targetRoot]    Consumer project root to scan (default: process.cwd()).
+ * @param {boolean}  [opts.isInteractive] Test seam ONLY — overrides the real `process.stdin.isTTY`
+ *                                        check. Never set by `bin/jenga.js`'s CLI dispatch, which
+ *                                        always leaves this undefined so the real TTY check applies;
+ *                                        exists so `tests/postinstall-doctor-cleanup.bats` can drive
+ *                                        the actual confirm/decline delete code path deterministically
+ *                                        without needing a real pty, matching the same non-TTY
+ *                                        readline limitation already documented in tests/init.bats.
+ * @param {function} [opts.confirmFn]     Test seam ONLY — overrides the real interactive `askYesNo`
+ *                                        prompt with a function returning (or resolving to) a
+ *                                        boolean. Never set by `bin/jenga.js`.
+ */
+export async function runDoctor(args = [], opts = {}) {
+  const packageRoot = opts.packageRoot || DEFAULT_PACKAGE_ROOT;
+  const targetRoot = opts.targetRoot || process.cwd();
+  const dryRun = args.includes('--dry-run');
+  const isInteractive = typeof opts.isInteractive === 'boolean' ? opts.isInteractive : Boolean(process.stdin.isTTY);
+  const confirmFn = typeof opts.confirmFn === 'function' ? opts.confirmFn : askYesNo;
+
+  console.log('\n╔══════════════════════════════════════════════════════╗');
+  console.log('║              jenga doctor — orphan scan             ║');
+  console.log('╚══════════════════════════════════════════════════════╝\n');
+
+  const scans = MIRROR_ROOTS
+    .map((root) => ({ root, destRoot: path.join(targetRoot, root) }))
+    .filter(({ destRoot }) => fs.existsSync(destRoot))
+    .map(({ root, destRoot }) => ({ root, destRoot, ...scanRoot({ destRoot, packageRoot }) }));
+
+  const grandTotal = scans.reduce((n, s) => n + s.total, 0);
+
+  if (grandTotal === 0) {
+    console.log('  ✓ No orphan candidates found. Nothing to clean up.\n');
+    return { deleted: [], total: 0 };
+  }
+
+  for (const s of scans) {
+    if (s.total === 0) continue;
+    console.log(`  ${s.root}/ — ${s.total} candidate file(s):`);
+    for (const group of s.groups) {
+      console.log(`    ${group.label} (${group.files.length} file(s))`);
+    }
+  }
+  console.log(`\n  Total: ${grandTotal} candidate file(s) across ${scans.length} mirror root(s).\n`);
+
+  if (dryRun) {
+    console.log('  --dry-run: no files were deleted.\n');
+    return { deleted: [], total: grandTotal, dryRun: true };
+  }
+
+  if (!isInteractive) {
+    console.log('  Non-interactive session detected — nothing deleted.');
+    console.log('  Re-run `jenga doctor` interactively to confirm deletion.\n');
+    return { deleted: [], total: grandTotal, nonInteractive: true };
+  }
+
+  const confirmed = await confirmFn(`Delete all ${grandTotal} candidate file(s) listed above?`);
+  if (!confirmed) {
+    console.log('\n  Declined — nothing was deleted.\n');
+    return { deleted: [], total: grandTotal, confirmed: false };
+  }
+
+  let totalDeleted = 0;
+  for (const s of scans) {
+    if (s.total === 0) continue;
+    const { deleted, refused, prunedDirs } = deleteGroups({ destRoot: s.destRoot, groups: s.groups });
+    totalDeleted += deleted.length;
+    if (deleted.length > 0) {
+      console.log(`  ✓ ${s.root}/ — ${deleted.length} file(s) removed` +
+        (prunedDirs.length ? `, ${prunedDirs.length} empty dir(s) pruned` : ''));
+    }
+    for (const r of refused) {
+      console.log(`  ⚠  ${s.root}/${r.path} — left in place (${r.reason})`);
+    }
+  }
+
+  console.log(`\n  Done. ${totalDeleted} file(s) removed.\n`);
+  return { deleted: totalDeleted, total: grandTotal, confirmed: true };
+}
+
+export default { runDoctor, scanRoot };

package/lib/commands/init.js

@@ -6,6 +6,7 @@ import { validateConfig } from "../config-schema.js";
 import { injectSettings } from "../inject-settings.js";
 import { generateAgentContext } from "../generate-agent-context.js";
 import { generateCopilotInstructions } from "../generate-copilot-instructions.js";
+import { generateCopilotHooks } from "../generate-copilot-hooks.js";
 
 const CONFIG_FILE = "jenga.cli.json";
 
@@ -154,6 +155,21 @@ export async function runInit(args, projectRoot = process.cwd()) {
       console.warn(`Warning: Could not write .github/copilot-instructions.md — ${e.message}`);
     }
 
+    // Generate .github/hooks/jenga.json — Copilot CLI's native sessionEnd/userPromptSubmitted
+    // hook config (E16_S03_T04), wiring the same cleanup/routing logic Claude Code's own
+    // SessionEnd/UserPromptSubmit hooks invoke. Uses the shared generator
+    // (lib/generate-copilot-hooks.js), also used unconditionally by scripts/postinstall.js at
+    // install time, mirroring the copilot-instructions.md generation immediately above. When
+    // PACKAGE_ROOT === projectRoot (running `jenga init` inside this monorepo itself) the
+    // generator resolves hook script paths dynamically via `$(git rev-parse --show-toplevel)`
+    // rather than baking in this run's absolute path — see that file's header comment.
+    try {
+      const result = generateCopilotHooks(projectRoot, PACKAGE_ROOT);
+      console.log(`✓ .github/hooks/jenga.json written (${result.path})`);
+    } catch (e) {
+      console.warn(`Warning: Could not write .github/hooks/jenga.json — ${e.message}`);
+    }
+
     // Generate CLAUDE.md / AGENTS.md from templates/agent-context.md.tpl.
     // Unconditional — never gated on agentTarget (E41_S04): every agent
     // benefits from these files being cheap to write, and users switch

package/lib/generate-copilot-hooks.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * lib/generate-copilot-hooks.js — .github/hooks/jenga.json generation
+ *
+ * Single source of truth for scaffolding GitHub Copilot CLI's native hook config, wiring the two
+ * Copilot lifecycle events that map directly onto this project's existing Claude Code hooks
+ * (E16_S03_T04, following E16_S03_T03's empirical verification against a real installed
+ * `copilot` CLI):
+ *
+ *   sessionEnd          -> hooks/copilot_session_end.sh  (mirrors Claude's SessionEnd hook)
+ *   userPromptSubmitted -> hooks/prompt_router.sh         (mirrors Claude's UserPromptSubmit hook)
+ *
+ * `WorktreeCreate`/`WorktreeRemove` have no direct Copilot-native lifecycle equivalent (they are
+ * git-worktree-specific, not generic session events) — T03's finding recommends keeping the
+ * existing manual workaround rather than a fragile `preToolUse`/`postToolUse` text-match
+ * approximation, so this generator does not wire those two events at all.
+ *
+ * Used by:
+ *   - scripts/postinstall.js  (runs unconditionally, non-interactively, on every `npm install`)
+ *   - lib/commands/init.js    (the interactive `jenga init` CLI wizard)
+ *
+ * Placement rationale (recorded in E16_S03_T03's finding): `.github/hooks/jenga.json` has no
+ * pre-existing root-level source directory to mirror from — unlike `.github/agents/*.md`, which
+ * mirrors real content already living at `agents/*.md`. The closer precedent is `settings.json`
+ * itself (Claude's own hook config): committed directly at this monorepo's own root for its own
+ * dev use, and separately generated per-consumer because a consumer's hook commands must resolve
+ * absolute `node_modules/@jenga-ai/agent/hooks/*.sh` paths rather than this repo's relative ones.
+ * This is why `.github/hooks/jenga.json` is entirely Jenga-owned (unlike
+ * `.github/copilot-instructions.md`, which preserves user content around JENGA markers) — there
+ * is no legitimate reason for a consumer to hand-edit it, so a full deterministic overwrite on
+ * every run is safe and simpler than a marker-merge.
+ *
+ * No `skills/self-sync/scripts/run.js` wiring is needed either: self-sync mirrors root-level
+ * source directories, and this file has none to mirror — it is generated directly, exactly like
+ * `.github/copilot-instructions.md` is (also outside self-sync's `COPY_SET`/`GITHUB_COPY_SET`).
+ *
+ * ESM, Node built-ins only — mirrors lib/generate-copilot-instructions.js and lib/mirror.js.
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// This file lives at <package>/lib/generate-copilot-hooks.js — one level up is the installed
+// jenga-agent package root, which holds hooks/copilot_session_end.sh and hooks/prompt_router.sh.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_PACKAGE_ROOT = join(__dirname, "..");
+
+/**
+ * Build the `.github/hooks/jenga.json` config object.
+ *
+ * Two path-resolution modes, chosen by the caller (`generateCopilotHooks`) based on whether
+ * `projectRoot` and `packageRoot` are the same directory:
+ *
+ * - `dynamicRoot: true` (this monorepo generating its own config: `projectRoot === packageRoot`)
+ *   — commands resolve `hooks/*.sh` at RUN time via `$(git rev-parse --show-toplevel)`, exactly
+ *   like `settings.json`'s own hook commands already do. A baked-in absolute path would be wrong
+ *   here — it would hardcode wherever the generator happened to run from (e.g. a throwaway
+ *   worktree checkout) instead of resolving to whichever checkout of this repo is actually
+ *   running the hook.
+ * - `dynamicRoot: false` (a real npm consumer: `projectRoot` is the consumer's project,
+ *   `packageRoot` is the installed `node_modules/@jenga-ai/agent`) — commands bake in the
+ *   absolute `packageRoot`-relative path, mirroring `lib/inject-settings.js`'s
+ *   `resolve(PACKAGE_ROOT, "hooks", "prompt_router.sh")` for Claude's own `UserPromptSubmit`
+ *   hook. This is safe because a consumer's installed package path is stable once `npm install`
+ *   completes — unlike this monorepo's own dev checkouts/worktrees, which move around.
+ *
+ * @param {string} packageRoot - where hooks/*.sh actually live
+ * @param {boolean} dynamicRoot - see above
+ */
+function buildHooksConfig(packageRoot, dynamicRoot) {
+  const sessionEndCmd = dynamicRoot
+    ? 'bash "$(git rev-parse --show-toplevel)/hooks/copilot_session_end.sh"'
+    : `bash "${resolve(packageRoot, "hooks", "copilot_session_end.sh")}"`;
+  const promptRouterCmd = dynamicRoot
+    ? 'bash "$(git rev-parse --show-toplevel)/hooks/prompt_router.sh"'
+    : `bash "${resolve(packageRoot, "hooks", "prompt_router.sh")}"`;
+
+  return {
+    version: 1,
+    hooks: {
+      sessionEnd: [
+        { type: "command", bash: sessionEndCmd },
+      ],
+      userPromptSubmitted: [
+        { type: "command", bash: promptRouterCmd },
+      ],
+    },
+  };
+}
+
+/**
+ * Generate (or idempotently overwrite) `.github/hooks/jenga.json` at projectRoot.
+ *
+ * Idempotent by construction: the output is fully deterministic from `packageRoot` alone, so
+ * re-running (e.g. a later `jenga init`, or a repeat postinstall on the same version) always
+ * produces byte-identical content. Unlike `.github/copilot-instructions.md`, no marker-merge is
+ * needed — this file is entirely Jenga-owned.
+ *
+ * @param {string} projectRoot - project root directory to write into (default: cwd)
+ * @param {string} packageRoot - where hooks/*.sh live (default: derived from this file's own
+ *   location, i.e. this monorepo's own root when run in-repo)
+ * @returns {{written: boolean, path: string}}
+ */
+export function generateCopilotHooks(projectRoot = process.cwd(), packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const hooksDir = join(projectRoot, ".github", "hooks");
+  const targetPath = join(hooksDir, "jenga.json");
+
+  const dynamicRoot = resolve(projectRoot) === resolve(packageRoot);
+  const config = buildHooksConfig(packageRoot, dynamicRoot);
+
+  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+  writeFileSync(targetPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+
+  return { written: true, path: targetPath };
+}