@jenga-ai/agent 3.0.0 → 3.1.0

package/scripts/generate-legacy-shipped-paths.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * scripts/generate-legacy-shipped-paths.js — legacy shipped-path list generator (E26_S08_T03)
+ *
+ * Why this exists
+ * ────────────────
+ * `lib/postinstall-manifest.js`'s delete reconciliation (E26_S08_T01) is purely forward-looking:
+ * a consumer already installed before any manifest existed can never have their pre-existing
+ * orphans cleaned up, because the first manifest a fixed version ever writes for them records
+ * only what THAT run mirrored. This script produces the static list this package ships so the
+ * FIRST manifest a consumer ever gets can instead be *seeded* with paths known to have shipped in
+ * some real prior published version — see `seedFromLegacyPaths` in `lib/postinstall-manifest.js`
+ * and `scripts/postinstall.js`'s `no-prior-manifest` branch for how the seed is consumed.
+ *
+ * Why not git tags
+ * ─────────────────
+ * The task's design note allows deriving the list "from git tags" as an alternative to
+ * publish-time derivation. Checked and rejected for this repo specifically: this repo's local
+ * tags (`v0.0.1`, `v55.0.1`, `last-self-sync`) do not correspond to the real npm publish history
+ * at all — `npm view @jenga-ai/agent versions --json` shows the real, disconnected sequence
+ * (1.0.0 through 3.0.0 as of this writing). Reconstructing shipped paths from local git tags in
+ * this repo would silently produce a list bearing no relation to what was actually published.
+ *
+ * Two modes
+ * ─────────
+ *   --bootstrap   Fetches EVERY version `npm view <package> versions --json` currently lists from
+ *                 the real registry, `npm pack`s each one into a throwaway temp dir, and unions
+ *                 the `skills/`+`agents/` entries inside every tarball. Network-dependent. This is
+ *                 how the real historical shipped-path set is captured — including versions whose
+ *                 git history is not reliably reconstructable locally (verified true here). Meant
+ *                 to be run manually / rarely — a one-off backfill, or an occasional resync — NOT
+ *                 wired into the automatic per-publish flow (see incremental mode below for that).
+ *
+ *   (default)     Incremental, no network: reads whatever is already at the output path (if any)
+ *                 and unions it with the paths CURRENTLY on disk under this repo's own `skills/`
+ *                 and `agents/` directories — i.e. "what this release is about to ship" folds into
+ *                 the running cumulative record. This is the mode wired into the publish pipeline
+ *                 (`skills/publish/scripts/npm_pipeline.sh` / `npm_ci_pipeline.sh`, via the
+ *                 `generate:legacy-paths` npm script) so every future publish keeps the list
+ *                 current with zero network dependency and zero publish-time registry flakiness.
+ *
+ *                 IMPORTANT — this mode's first-ever run is NOT a substitute for --bootstrap: if
+ *                 the output file doesn't exist yet, incremental mode unions an EMPTY existing set
+ *                 with whatever's on disk in THIS repo's tree right now. That happens to currently
+ *                 equal the real historical union (this repo's working tree is a superset of every
+ *                 published version's file list, as of the 2026-09-07 verification below) — but
+ *                 that is a coincidence of this repo's current state, not a guarantee the mode
+ *                 itself provides. The very first generation of the shipped artifact MUST use
+ *                 --bootstrap so the baseline is verified against the real registry, not assumed.
+ *
+ * Output
+ * ──────
+ * `lib/legacy-shipped-paths.json` (ships automatically — `lib/` is already in package.json's
+ * `files` allow-list, no change needed there):
+ *
+ *   {
+ *     "generated_at": "<ISO 8601>",
+ *     "package": "@jenga-ai/agent",
+ *     "source": "bootstrap-from-registry+incremental" | "incremental",
+ *     "paths": ["agents/developer.md", "skills/do/SKILL.md", ...]
+ *   }
+ *
+ * `paths` are relative to a mirror root, POSIX-separated, deduped and sorted — matching the same
+ * shape convention `lib/postinstall-manifest.js`'s own manifest uses, for consistency.
+ *
+ * The generation step is regenerated automatically as part of the publish flow (incremental mode),
+ * per this task's AC — it is NOT hand-maintained, so it cannot silently go stale across releases.
+ *
+ * ESM, Node built-ins only — matches lib/postinstall-manifest.js and lib/mirror.js. `npm` itself is
+ * shelled out to (via `execFileSync`) only in `--bootstrap` mode.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.join(__dirname, '..');
+
+export const DEFAULT_OUTPUT_PATH = path.join(REPO_ROOT, 'lib', 'legacy-shipped-paths.json');
+export const DEFAULT_PACKAGE_NAME = '@jenga-ai/agent';
+
+/** Discovery-bound directories mirrored into a consumer's .agents/ and .claude/ (see docs/distribution.md §1). */
+const COPY_SET = ['skills', 'agents'];
+
+// ── walk a real directory tree ──────────────────────────────────────────────
+
+function walkDir(base, 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()) {
+      walkDir(base, abs, out);
+    } else if (entry.isFile()) {
+      out.push(path.relative(base, abs).split(path.sep).join('/'));
+    }
+    // symlinks intentionally ignored — matches lib/mirror.js's own walk behavior.
+  }
+}
+
+/**
+ * Relative POSIX paths this repo's CURRENT `skills/` + `agents/` trees would ship, i.e. exactly
+ * what a fresh install of the version about to be published would mirror.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} sorted, deduped
+ */
+export function currentShippedPaths(repoRoot = REPO_ROOT) {
+  const out = [];
+  for (const entry of COPY_SET) {
+    const dir = path.join(repoRoot, entry);
+    if (fs.existsSync(dir)) walkDir(repoRoot, dir, out);
+  }
+  return [...new Set(out)].sort();
+}
+
+// ── read existing output (if any) ───────────────────────────────────────────
+
+function readExistingPaths(outputPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+    return Array.isArray(parsed.paths) ? parsed.paths.filter((p) => typeof p === 'string') : [];
+  } catch (_) {
+    return []; // absent, unreadable, or corrupt — start from an empty cumulative set
+  }
+}
+
+// ── bootstrap from the real npm registry ────────────────────────────────────
+
+/**
+ * Fetch every currently-listed published version of `packageName`, `npm pack` each into a
+ * throwaway temp dir, and union the `skills/`+`agents/` entries found inside every tarball.
+ * Network-dependent — intended for manual/rare use (a one-off backfill or occasional resync),
+ * never called by the automatic per-publish (incremental) path.
+ *
+ * @param {string} packageName
+ * @returns {string[]} sorted, deduped relative POSIX paths
+ */
+export function bootstrapFromRegistry(packageName = DEFAULT_PACKAGE_NAME) {
+  const versionsRaw = execFileSync('npm', ['view', packageName, 'versions', '--json'], {
+    encoding: 'utf8',
+  });
+  const versions = JSON.parse(versionsRaw);
+  const all = new Set();
+
+  for (const version of versions) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'jenga-legacy-bootstrap-'));
+    try {
+      execFileSync('npm', ['pack', `${packageName}@${version}`, '--silent'], { cwd: tmp, stdio: 'ignore' });
+      const tarball = fs.readdirSync(tmp).find((f) => f.endsWith('.tgz'));
+      if (!tarball) continue;
+      const listing = execFileSync('tar', ['-tzf', path.join(tmp, tarball)], { encoding: 'utf8' });
+      for (const line of listing.split('\n')) {
+        const m = line.match(/^package\/(skills|agents)\/(.+)$/);
+        if (m && !line.endsWith('/')) all.add(`${m[1]}/${m[2]}`);
+      }
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+
+  return [...all].sort();
+}
+
+// ── generate ─────────────────────────────────────────────────────────────────
+
+/**
+ * @param {object}  [opts]
+ * @param {string}  [opts.outputPath]   Default: lib/legacy-shipped-paths.json
+ * @param {string}  [opts.packageName]  Default: @jenga-ai/agent
+ * @param {boolean} [opts.bootstrap]    Default: false (incremental, no network)
+ * @param {string}  [opts.repoRoot]     Default: this repo's own root
+ * @returns {{written: boolean, path: string, count: number, source: string}}
+ */
+export function generate({
+  outputPath = DEFAULT_OUTPUT_PATH,
+  packageName = DEFAULT_PACKAGE_NAME,
+  bootstrap = false,
+  repoRoot = REPO_ROOT,
+} = {}) {
+  const existing = readExistingPaths(outputPath);
+  let paths;
+  let source;
+
+  if (bootstrap) {
+    const registryPaths = bootstrapFromRegistry(packageName);
+    paths = [...new Set([...registryPaths, ...existing])].sort();
+    source = 'bootstrap-from-registry+incremental';
+  } else {
+    const current = currentShippedPaths(repoRoot);
+    paths = [...new Set([...existing, ...current])].sort();
+    source = 'incremental';
+  }
+
+  const artifact = {
+    generated_at: new Date().toISOString(),
+    package: packageName,
+    source,
+    paths,
+  };
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, JSON.stringify(artifact, null, 2) + '\n', 'utf8');
+
+  return { written: true, path: outputPath, count: paths.length, source };
+}
+
+/**
+ * Read the shipped legacy-paths artifact's `paths` array. Fail-toward-doing-nothing: any read or
+ * parse failure returns `[]` rather than throwing — a missing/corrupt legacy-paths file must
+ * never abort or degrade an unattended `npm install`, mirroring `readManifest`'s own posture in
+ * `lib/postinstall-manifest.js`.
+ *
+ * @param {string} artifactPath
+ * @returns {string[]}
+ */
+export function readLegacyShippedPaths(artifactPath = DEFAULT_OUTPUT_PATH) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+    if (!Array.isArray(parsed.paths)) return [];
+    return parsed.paths.filter((p) => typeof p === 'string' && p.length > 0);
+  } catch (_) {
+    return [];
+  }
+}
+
+// ── CLI guard ────────────────────────────────────────────────────────────────
+// node scripts/generate-legacy-shipped-paths.js [--bootstrap] [--package <name>] [outputPath]
+
+const invokedPath = process.argv[1] ? fs.realpathSync(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const bootstrap = argv.includes('--bootstrap');
+  const pkgFlagIndex = argv.indexOf('--package');
+  const packageName = pkgFlagIndex !== -1 ? argv[pkgFlagIndex + 1] : DEFAULT_PACKAGE_NAME;
+  const positional = argv.filter((a, i) => a !== '--bootstrap' && i !== pkgFlagIndex && i !== pkgFlagIndex + 1 && !a.startsWith('--'));
+  const outputPath = positional[0] || DEFAULT_OUTPUT_PATH;
+
+  const result = generate({ outputPath, packageName, bootstrap });
+  console.log(`✓ ${result.path} (${result.count} paths, ${result.source})`);
+}

package/scripts/postinstall.js

@@ -24,7 +24,86 @@
  *
  * The actual filesystem mirror is delegated to `lib/mirror.js`, which is the
  * single source of truth shared with the in-repo `/self-sync` skill. Consumer
- * install always uses `reconcileDeletes: false` (additive-only).
+ * install always uses `reconcileDeletes: false` (additive-only) — that flag diffs
+ * the destination's current contents against the source tree with no notion of who
+ * wrote a given file, so enabling it here would delete a consumer's own custom
+ * skills. It is deliberately left off; see the manifest mechanism below.
+ *
+ * Upgrade cleanup — manifest-based delete reconciliation (E26_S08_T01)
+ * ────────────────────────────────────────────────────────────────────
+ * Additive-only mirroring means a release that renames, removes, or excludes a
+ * skill leaves the previously installed copies in the consumer's mirror roots
+ * forever, so old and new forms both keep loading. To clean those up *without*
+ * risking consumer-authored files, each run records what it wrote and the next run
+ * removes only what it itself wrote last time and did not write again.
+ *
+ *   Location : one manifest per destination root, inside that root —
+ *                <consumer>/.agents/.jenga-postinstall-manifest.json
+ *                <consumer>/.claude/.jenga-postinstall-manifest.json
+ *              Keeping it inside the root it describes means it travels with that
+ *              mirror; moving or renaming the consumer project cannot desync it.
+ *
+ *   Format   : {
+ *                "manifest_version": 1,
+ *                "package":          "@jenga-ai/agent",
+ *                "package_version":  "3.0.1",
+ *                "generated_at":     "<ISO 8601>",
+ *                "dest_root":        ".agents",
+ *                "paths":            ["agents/developer.md", "skills/do/SKILL.md"]
+ *              }
+ *              `paths` are relative to the destination root, POSIX-separated,
+ *              deduped and sorted, and record REGULAR FILES ONLY — never
+ *              directories. Directory removal is derived by pruning parents that
+ *              become empty, which is precisely why a directory still holding a
+ *              consumer file is never removed.
+ *
+ *   Rule     : a path is deleted only if a manifest previously written by THIS
+ *              package's postinstall lists it AND the current run did not write it.
+ *              If no prior manifest exists, see the legacy-path seeding note below —
+ *              "we don't know what we wrote before" is never treated as "delete
+ *              everything we didn't just write". Every parse/IO failure likewise
+ *              degrades to additive-only.
+ *
+ *   Skipped   : if any `copySet` entry is missing from the package (a packaging
+ *              regression), BOTH the delete pass and the manifest write are skipped
+ *              for that run — otherwise the run would under-report what it wrote and
+ *              read an entire mirrored subtree as stale. The previous manifest is
+ *              left in place because it still describes what is on disk.
+ *
+ * Legacy-path seeding — first-manifest orphan cleanup (E26_S08_T03)
+ * ────────────────────────────────────────────────────────────────────
+ * T01's rule above is purely forward-looking: a consumer already installed BEFORE any
+ * manifest existed takes the `no-prior-manifest` branch on their first run of a fixed
+ * version, and the manifest that run writes records only what that one run mirrored —
+ * pre-existing orphans (e.g. a retired `j:`-form skill, an excluded `j-<name>` twin)
+ * were never in it, so they could never become deletion candidates on any FUTURE
+ * upgrade either. Confirmed empirically against a throwaway fixture, not merely
+ * reasoned about: such a file survived two upgrades, the second with an active delete
+ * pass, appearing 0 times in either manifest.
+ *
+ * On the `no-prior-manifest` branch, this run now additionally seeds a SYNTHETIC prior
+ * path list from `lib/legacy-shipped-paths.json` — a static, package-shipped list of
+ * paths known to have shipped in some real prior published version (see
+ * `scripts/generate-legacy-shipped-paths.js`) — intersected with what is ACTUALLY a
+ * regular file on disk in that mirror root right now
+ * (`seedFromLegacyPaths` in `lib/postinstall-manifest.js`). If anything seeds, it is
+ * reconciled against THIS run's copy set immediately (adopt-then-reconcile), so the
+ * cleanup lands on the very upgrade that introduces this feature rather than one cycle
+ * later. Provenance stays the entire compensating control: a path absent from every
+ * published version's file list is never in `lib/legacy-shipped-paths.json`, so it can
+ * never be seeded, regardless of where it sits in the mirror root — a consumer's own
+ * hand-authored file was never in any published version and stays untouchable exactly
+ * as before. A genuine first-ever install has nothing on disk to intersect with, so the
+ * seed set is naturally empty and this falls straight through to the additive-only
+ * behaviour — no separate "is this a first install" branch is needed for that to hold.
+ * The seeded reconciliation reuses the EXACT SAME boundary/type-checked delete engine
+ * as the manifest-backed path (`reconcileWithPriorPaths` shares its core with
+ * `reconcileFromManifest`), so invariants 3, 4, and 5 apply unchanged over seeded
+ * candidates too.
+ *
+ * Implementation lives in `lib/postinstall-manifest.js` (full rationale + safety
+ * invariants documented there) and `scripts/generate-legacy-shipped-paths.js` (legacy
+ * path list generation); consumer-facing docs in `docs/distribution.md`.
  */
 
 import fs   from 'node:fs';
@@ -32,7 +111,16 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { mirror } from '../lib/mirror.js';
+import {
+  toRelativePaths,
+  reconcileFromManifest,
+  reconcileWithPriorPaths,
+  seedFromLegacyPaths,
+  writeManifest,
+} from '../lib/postinstall-manifest.js';
+import { readLegacyShippedPaths } from './generate-legacy-shipped-paths.js';
 import { generateCopilotInstructions } from '../lib/generate-copilot-instructions.js';
+import { generateCopilotHooks } from '../lib/generate-copilot-hooks.js';
 import { generateSkillAllowList } from '../lib/generate-skill-allow-list.js';
 
 // ESM equivalent of __dirname
@@ -73,10 +161,12 @@ function main() {
 
   // Read this package's version
   let packageVersion = '0.0.0';
+  let packageName    = '';
   try {
     const pkgPath = path.join(packageRoot, 'package.json');
     const pkg     = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     packageVersion = pkg.version || '0.0.0';
+    packageName    = pkg.name || '';
   } catch (_) {
     // non-fatal — proceed with default
   }
@@ -120,14 +210,36 @@ function main() {
   // Warn about any copySet entries that are missing from the package — the
   // helper silently skips missing sources, so we surface it here for parity
   // with the previous UX.
+  const missingEntries = [];
   for (const entry of copySet) {
     if (!fs.existsSync(path.join(packageRoot, entry))) {
       console.log(`  ⚠  ${entry}/ not found in package — skipped`);
+      missingEntries.push(entry);
     }
   }
 
+  // A copySet entry missing from the package is a PACKAGING regression, not a signal
+  // that the consumer should lose those files. mirror() silently skips a missing
+  // source, so `currentPaths` would under-report everything under that entry and the
+  // delete pass would read the whole mirrored subtree as stale and wipe it — turning
+  // a bad publish into mass deletion on every consumer that installs it.
+  //
+  // So when anything is missing we skip BOTH the delete pass and the manifest write.
+  // Leaving the previous manifest untouched is deliberate: it still accurately
+  // describes what is on disk (those files are still there, just not refreshed), so a
+  // later healthy release reconciles correctly against it. Writing an under-reporting
+  // manifest here would merely defer the same mass delete to the next run.
+  const reconcileSafe = missingEntries.length === 0;
+  if (!reconcileSafe) {
+    console.log(
+      `  ⚠  Upgrade cleanup skipped — ${missingEntries.join(', ')} missing from the package. ` +
+      'Existing mirrored files are left untouched.'
+    );
+  }
+
   let totalCopied  = 0;
   let totalSkipped = 0;
+  let totalDeleted = 0;
 
   for (const targetRoot of targetRoots) {
     const destRoot = path.join(consumerRoot, targetRoot);
@@ -151,6 +263,82 @@ function main() {
       console.log(`  ✓ ${targetRoot}/${entry}/ — ${wrote} file(s) copied`);
     }
 
+    // ── Manifest-based delete reconciliation (E26_S08_T01) ───────────────────
+    // The copy set for manifest purposes is added + overwritten + SKIPPED. Including
+    // `skipped` is essential, not incidental: a file that was byte-identical and
+    // therefore skipped by mirror() is still a package-owned path, and leaving it out
+    // would make the very next run classify it as stale and delete it.
+    const currentPaths = toRelativePaths(destRoot, [
+      ...result.added,
+      ...result.overwritten,
+      ...result.skipped,
+    ]);
+
+    // Deletes only ever touch paths a manifest we ourselves wrote lists and this run
+    // did not rewrite. No prior manifest => see the E26_S08_T03 seeding branch below.
+    try {
+      let recon = reconcileSafe
+        ? reconcileFromManifest({ destRoot, currentPaths })
+        : { deleted: [], prunedDirs: [], refused: [], reason: 'skipped-incomplete-package' };
+
+      // ── Legacy-path seeding (E26_S08_T03) ───────────────────────────────────
+      // reconcileFromManifest returned 'no-prior-manifest' — this is either a genuine
+      // first-ever install, OR a consumer already installed before this manifest
+      // mechanism (E26_S08_T01) existed. The two are indistinguishable from a manifest
+      // alone, which is exactly the gap T03 closes: seed a SYNTHETIC prior-path list from
+      // this package's known-shipped legacy paths, intersected with what is ACTUALLY a
+      // regular file on disk right now (seedFromLegacyPaths never seeds a path that isn't
+      // really there), then reconcile against that seed in THIS SAME run
+      // (adopt-then-reconcile) rather than waiting one more upgrade cycle. A genuine
+      // first-ever install has nothing on disk to intersect with, so the seed set is
+      // naturally empty and this falls straight through to the additive-only branch below
+      // — no separate first-install check is needed for that to hold.
+      if (reconcileSafe && recon.reason === 'no-prior-manifest') {
+        const legacyPathsFile = path.join(packageRoot, 'lib', 'legacy-shipped-paths.json');
+        const legacyPaths = readLegacyShippedPaths(legacyPathsFile);
+        const seeded = seedFromLegacyPaths({ destRoot, legacyPaths });
+        if (seeded.length > 0) {
+          const seedRecon = reconcileWithPriorPaths({ destRoot, priorPaths: seeded, currentPaths });
+          // Only surface this as a distinct outcome if the seed actually produced
+          // something to report. A seeded path that is STILL part of this run's own
+          // currentPaths (e.g. a legacy path this release still ships) is neither
+          // stale nor refused — nothing happened, so the plain "no previous install
+          // manifest" additive-only message stays accurate and must not be hidden by
+          // an outcome-less 'seeded-reconciled' relabel.
+          if (seedRecon.deleted.length > 0 || seedRecon.prunedDirs.length > 0 || seedRecon.refused.length > 0) {
+            recon = { ...seedRecon, reason: 'seeded-reconciled' };
+          }
+        }
+      }
+
+      if (recon.reason === 'skipped-incomplete-package') {
+        // already reported once above, per-run rather than per-root
+      } else if (recon.reason === 'no-prior-manifest') {
+        console.log(`  ℹ  ${targetRoot}/ — no previous install manifest; additive copy only (no deletes)`);
+      } else if (recon.deleted.length > 0 || recon.prunedDirs.length > 0) {
+        const suffix = recon.reason === 'seeded-reconciled' ? ' (seeded from known-shipped legacy paths)' : '';
+        console.log(
+          `  ✓ ${targetRoot}/ — ${recon.deleted.length} stale file(s) removed${suffix}` +
+          (recon.prunedDirs.length ? `, ${recon.prunedDirs.length} empty dir(s) pruned` : '')
+        );
+        totalDeleted += recon.deleted.length;
+      }
+      for (const r of recon.refused) {
+        console.log(`  ⚠  ${targetRoot}/${r.path} — left in place (${r.reason})`);
+      }
+    } catch (e) {
+      // Cleanup is best-effort: a reconciliation failure must never fail the install.
+      console.log(`  ⚠  ${targetRoot}/ — upgrade cleanup skipped (${e.message})`);
+    }
+
+    try {
+      if (reconcileSafe) {
+        writeManifest({ destRoot, currentPaths, packageName, packageVersion });
+      }
+    } catch (e) {
+      console.log(`  ⚠  ${targetRoot}/ — could not write install manifest (${e.message})`);
+    }
+
     totalCopied  += result.added.length + result.overwritten.length;
     totalSkipped += result.skipped.length;
   }
@@ -199,11 +387,26 @@ function main() {
     console.log(`  ⚠  Could not bootstrap .github/copilot-instructions.md — ${e.message}`);
   }
 
+  // Bootstrap .github/hooks/jenga.json unconditionally, same pattern as the
+  // copilot-instructions.md bootstrap immediately above (E16_S03_T04). Wires Copilot CLI's
+  // native sessionEnd/userPromptSubmitted hooks to this package's hooks/copilot_session_end.sh
+  // and hooks/prompt_router.sh, using absolute node_modules/@jenga-ai/agent paths (packageRoot
+  // !== consumerRoot here, so lib/generate-copilot-hooks.js bakes in the stable installed-package
+  // path rather than a runtime git-root lookup — see that file's own header comment for why).
+  // Entirely Jenga-owned output (unlike copilot-instructions.md), so this is a plain
+  // idempotent overwrite — no marker-merge needed.
+  try {
+    const result = generateCopilotHooks(consumerRoot, packageRoot);
+    console.log(`  ✓ .github/hooks/jenga.json bootstrapped (${result.path})`);
+  } catch (e) {
+    console.log(`  ⚠  Could not bootstrap .github/hooks/jenga.json — ${e.message}`);
+  }
+
   // Write .jenga-version to record the installed version at consumer root
   fs.writeFileSync(versionFile, packageVersion + '\n', 'utf8');
 
   console.log('\n──────────────────────────────────────────────────────');
-  console.log(`  Summary: ${totalCopied} file(s) copied, ${totalSkipped} skipped`);
+  console.log(`  Summary: ${totalCopied} file(s) copied, ${totalSkipped} skipped, ${totalDeleted} stale file(s) removed`);
   console.log(`  .jenga-version written: ${packageVersion}`);
   console.log('──────────────────────────────────────────────────────\n');
 }