@jenga-ai/agent 2.0.0 → 3.1.0

package/agents/tester.md

@@ -167,7 +167,7 @@ Always include the sender object in the response.
 
 **Trigger.** During steps 4-6 of "Invoked for test implementation and/or execution" above, you find a defect. Before defaulting to step 9's rapport path, classify it: is this **mechanical** (safe to fix in place) or does it **need a rapport** (a design decision or real risk is involved)? This classification is what determines which of the two remediation paths below you take — it is not optional bookkeeping, and it happens at the moment the defect is found, not retroactively.
 
-**Motivating case.** `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md` Finding 3: the tester found `skills/dev-done/scripts/classify-commit-outcome.sh` committed without its executable bit (`chmod +x`) plus a dead, unreachable error branch. Both were one-line-class fixes, but the only path available at the time was the full formal one — a `test_failure` rapport, a separate developer fix commit, a re-verification pass, and a second complete `j:self-sync` mirror run. That produced 3 of the task's 6 total commits for defects that needed no design judgment at all. This subsection exists so that pattern doesn't repeat.
+**Motivating case.** `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md` Finding 3: the tester found `skills/dev-done/scripts/classify-commit-outcome.sh` committed without its executable bit (`chmod +x`) plus a dead, unreachable error branch. Both were one-line-class fixes, but the only path available at the time was the full formal one — a `test_failure` rapport, a separate developer fix commit, a re-verification pass, and a second complete `j.self-sync` mirror run. That produced 3 of the task's 6 total commits for defects that needed no design judgment at all. This subsection exists so that pattern doesn't repeat.
 
 **Qualifying examples (mechanical — fix in place).**
 - A missing executable bit or other permission-bit error (e.g. a script committed without `chmod +x`) — the exact E42_S04 Finding 3 case.
@@ -258,11 +258,11 @@ Append this as a new array entry — never overwrite existing log content. This
 
 **Trigger.** The task being verified — or its parent story — carries `crucial_level: locked` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
 
-**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j:jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03). As tester, verify this field is actually `inline` on any `locked` item you're validating — a value that slipped through would itself be a defect worth flagging.
+**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j.jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03). As tester, verify this field is actually `inline` on any `locked` item you're validating — a value that slipped through would itself be a defect worth flagging.
 
-**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j:jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
+**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
 
-**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j:do` guards above) before the developer ever begins work — none of this depends on you noticing or remembering anything mid-verification. Your only obligation is to recognize that a `locked` task always runs (and was always verified) in the current foreground session, and to never suggest or perform a workaround that would route around that guarantee. If you find evidence during verification that a `locked` item was actually run in a backgrounded or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to silently pass.
+**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j.do` guards above) before the developer ever begins work — none of this depends on you noticing or remembering anything mid-verification. Your only obligation is to recognize that a `locked` task always runs (and was always verified) in the current foreground session, and to never suggest or perform a workaround that would route around that guarantee. If you find evidence during verification that a `locked` item was actually run in a backgrounded or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to silently pass.
 
 ### Invoked for analysis or comparison testing
 When invoked to run an analysis or comparison:
@@ -455,7 +455,7 @@ There is no default analytics run. Analytics only happen when explicitly scoped
 
 ## Investigative Mode
 
-**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `j:uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
+**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `j.uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
 
 **Hard constraints.** Investigative Mode is strictly read-only:
 - No worktree is created for write purposes, no test files are written or modified, no test runs that mutate state, no dependency installs.

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 };
+}

package/lib/generate-skill-allow-list.js

@@ -55,10 +55,16 @@ function extractName(content) {
   const nameMatch = fmMatch[1].match(/^name:\s*(.+)$/m);
   if (!nameMatch) return null;
   const rawName = nameMatch[1].trim().replace(/^["']|["']$/g, "");
-  // Frontmatter may carry either the pre-E50_S01 bare form or the post-rename "j:<name>" form
-  // (skills/*/SKILL.md was migrated in E50_S01_T02) — strip the prefix so the allow-list always
+  // Frontmatter may carry the pre-E50_S01 bare form, the E50_S01 "j:<name>" form, or the
+  // current "j.<name>" form (E50_S07_T01 swapped the separator because GitHub Copilot CLI
+  // rejects ":" in a skill name) — strip whichever prefix is present so the allow-list always
   // holds bare identifiers, matching mcp/router/skill-index.js's `bareName` handling.
-  return rawName.replace(/^j:/i, "");
+  //
+  // Both separators must stay accepted: this guard is the E50_S02 anti-masquerading check, and
+  // a normalizer that fails to strip silently populates the allow-list with prefixed entries
+  // ("j.brainstorm" instead of "brainstorm"), which no longer match what the guard compares
+  // against. That is a security-guard failure, not a cosmetic one.
+  return rawName.replace(/^j[.:]/i, "");
 }
 
 /**