@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/claude-materialize.js

@@ -1,1200 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/claude-materialize.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/claude-materialize.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-// claude-materialize.js — materialize the .claude/ methodology surface into an instance
-// (ADR 0108 §3, configurable-root W3 / task 1883).
-//
-// WHY. Claude Code discovers .claude/settings.json + hooks/ + skills/ from the PROJECT ROOT, never
-// from a dependency. Once the Cloud Bongos core installs as a pinned npm package (ADR 0108), the
-// ~35 skills sit in node_modules/@bongos/core/.claude/skills/ where Claude Code will not look —
-// so `bongos init`/`upgrade` must COPY .claude/ into the instance repo. And a copied skill can't run
-// `node scripts/gds/<x>.js`: scripts/ lives in the package, not at the instance root. So every
-// invocation is rewritten to the `bongos` bin, which resolves the heavy CLI inside the package —
-// a dedicated verb where one exists (`bongos ship`), else the generic `bongos exec scripts/gds/<x>.js`.
-//
-// BOUNDARY (publish-manifest). skills/ ships IN the core package (isPublishable) → materialized by
-// copy+transform. hooks/ + settings.json are TOPOLOGY (PROTECTED_TOPOLOGY_EXCLUDE) → NOT in the
-// package; this module copies+transforms them when they ARE present at the core root (today's single
-// checkout, and the core repo itself), and no-ops with a note when they aren't (an installed package).
-// Hooks self-resolve their core require()s at RUNTIME via the copied _core-resolve.js sibling
-// (task 2139, the former W3 follow-up), so no require-path rewriting happens here. The topology
-// STARTER for a package-only install is now HALF built: settings.json is written from
-// renderStarterSettings() below — permissions only, no hooks — because an instance that received
-// the skills but no permissions met the classifier on every blessed command (task 1003962). A hooks
-// starter remains a follow-up (task 1883), and is a different question: hooks ARE gate machinery,
-// where a list of allowed command names is not.
-//
-// SELF-COPY GUARD. When the instance dir IS the core root (running init inside the core checkout /
-// OTB today), there is nothing to materialize — a self-copy would be a no-op at best and corrupting
-// at worst. This module detects that and skips, so it is byte-identical for the live instance.
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-const crypto = require('node:crypto');
-const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
-const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
-const { isCorePackageName, CORE_PACKAGE_NAMES } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
-const { renderInstanceClaudeMd, refreshStarterCliLines } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
-
-// script basename (e.g. "ship.js") → dedicated bongos verb, for verbs that map to a bare script with
-// NO prefixArgs. Verbs whose script is driven by prefixArgs (box → api.js) are EXCLUDED so a generic
-// `node scripts/gds/dev.js …` never mis-maps to `bongos serve`; those fall to `bongos exec`. `exec`
-// itself has no script and is skipped.
-function scriptToVerb(verbs = VERBS) {
-  const m = {};
-  for (const [verb, def] of Object.entries(verbs)) {
-    if (!def || def.prefixArgs || !def.script) continue;
-    if (!(def.script in m)) m[def.script] = verb;
-  }
-  return m;
-}
-
-// Match `node [<quote>][$CLAUDE_PROJECT_DIR/|./]scripts/gds/<name>.js[<quote>]` — the invocation form
-// skills + settings.json hooks use. The optional $CLAUDE_PROJECT_DIR/ or ./ prefix and surrounding
-// quote are consumed so the whole thing collapses to the bongos form. `.claude/hooks/<x>.js` refs are
-// deliberately NOT matched (this targets scripts/gds/) — those stay instance-local after materialize.
-// The launcher is bare `node`, OR the hook resolver `sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"`
-// that every settings.json hook command goes through since task 1003548 (it finds node when the hook
-// shell's PATH lacks it). Both collapse to the same bongos form; a resolver call whose target is a
-// .claude/hooks/*.js stays untouched exactly like the bare-node form did.
-const LAUNCHER = String.raw`(?:node|sh\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?\.claude\/hooks\/run-node\.sh"?)`;
-const GDS_INVOCATION_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/gds\/([a-zA-Z0-9_-]+)\.js"?`, 'g');
-// A non-gds core script under scripts/ (rare in skills, but keep the transform total).
-const OTHER_SCRIPT_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?`, 'g');
-
-// How a project runs the CLI (task 1004621). The `bongos` bin ships inside the @bongos/core
-// dependency (node_modules/.bin/bongos), which is NOT on PATH, so a bare `bongos ship` written
-// into a project's skills failed with `command not found` on every session's first call and the
-// assistant had to recover by retrying through npx. `npx` finds the project's own bin right after
-// `npm install`, with no setup, on every OS and shell — so that is the spelling a project reads.
-const PROJECT_CLI = 'npx bongos';
-
-// A hand-written bare `bongos <verb>` in skill prose (e.g. "`bongos paste-token <token>`"), so it
-// takes the npx spelling too. Case-sensitive on purpose ("Bongos status" is a product noun), only a
-// KNOWN verb, and never when already prefixed by `npx ` or glued to a path/name (`@bongos/core`,
-// `bongos-feedback`, `bongos: command not found` all stay). The `npx ` lookbehind is what keeps a
-// second run from writing `npx npx bongos`.
-function bareVerbRe(verbs) {
-  const names = Object.keys(verbs || {}).filter((v) => /^[a-z][a-z-]*$/.test(v));
-  if (!names.length) return null;
-  names.sort((a, b) => b.length - a.length); // `paste-token` before a shorter prefix of it
-  return new RegExp(String.raw`(?<![\w@/.\-])(?<!npx )bongos (${names.join('|')})(?![\w-])`, 'g');
-}
-
-// Pure: rewrite core-script invocations in a skill/settings command string to the project's CLI
-// spelling (`npx bongos <verb>`, else `npx bongos exec scripts/gds/<x>.js`), and give any bare
-// `bongos <verb>` the same npx prefix. Idempotent: its own output contains neither a
-// `node scripts/…` invocation nor an un-prefixed `bongos <verb>`, so a second run changes nothing.
-function bongosify(text, verbs = VERBS) {
-  const map = scriptToVerb(verbs);
-  const bare = bareVerbRe(verbs);
-  let out = String(text == null ? '' : text);
-  if (bare) out = out.replace(bare, (_whole, verb) => `${PROJECT_CLI} ${verb}`);
-  return out
-    .replace(GDS_INVOCATION_RE, (_whole, script) => {
-      const verb = map[`${script}.js`];
-      return verb ? `${PROJECT_CLI} ${verb}` : `${PROJECT_CLI} exec scripts/gds/${script}.js`;
-    })
-    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `${PROJECT_CLI} exec scripts/${rel}`);
-}
-
-// ---- instance rebrand (task 2103) -----------------------------------------
-// The scaffolded .claude/ used to carry the SOURCE instance's identity verbatim:
-// hooks hardcoded the founder origin (e.g. a `https://example.com` fallback)
-// and config dir (`~/.config/otb`), so a fresh clone's hooks phoned home to the
-// WRONG instance — the 2026-07-08 demo-session failure. materialize now rewrites
-// those founder literals to the TARGET instance's own values, derived from the two
-// branding objects, so no source host survives. Focused + FULL-HOST (a subdomain
-// like demo.cloudbongos.com is preserved), fail-open (a missing field drops that
-// one rule), a no-op when source == target, and it touches ONLY the copied output
-// (never the running source hooks). It does NOT rewrite hooks' internal
-// require('scripts/gds/…') paths — those self-resolve at runtime via the copied
-// _core-resolve.js sibling (task 2139); this rule lands the origin/config-dir neutralization.
-
-function reEsc(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
-function hostOf(origin) { try { return new URL(String(origin)).host || null; } catch { return null; } }
-
-// Effective config dir / env prefix for a branding — the SAME neutral fallbacks
-// instance-config uses, so nothing here is ever a founder literal (R76-safe).
-function effConfigDir(b) { return (b && b.configDir) || ic.FALLBACK_DIR; }
-function effEnvPrefix(b) { return (b && b.envPrefix) || ic.FALLBACK_ENV_PREFIX; }
-// The brand token outbound User-Agents are built from, mirroring src/branding.js
-// userAgent(): repo name, else env prefix, lowercased. Kept in sync by the
-// tests/claude_materialize.mjs UA-rule case + tests/hook_user_agents.mjs.
-function effUaBase(b) {
-  const base = (b && b.repo && b.repo.name) || (b && b.envPrefix) || '';
-  return String(base).toLowerCase();
-}
-
-// Ordered source→target rebrand rules from two branding objects. PURE + exported.
-function buildRebrandRules(from = {}, to = {}) {
-  const rules = [];
-  const add = (a, b) => { if (a && b && a !== b) rules.push({ pattern: new RegExp(reEsc(a), 'g'), replace: b }); };
-  // Every configured origin HOST (public/builders/status/oauth) → the target's SAME-key
-  // host, or its publicOrigin host when that key is unset (so a source subdomain like
-  // builders.<founder> maps to the target's canonical origin, not builders.<target>).
-  // Full-host keeps real target subdomains; a bare founder host anywhere is caught too.
-  // Dedup by source host (first mapping wins) so one founder host can't spawn conflicting rules.
-  const fromD = from.domains || {}, toD = to.domains || {};
-  const toPublicHost = hostOf(toD.publicOrigin);
-  const hostMap = new Map();
-  for (const key of Object.keys(fromD)) {
-    const fh = hostOf(fromD[key]);
-    if (!fh || hostMap.has(fh)) continue;
-    const th = hostOf(toD[key]) || toPublicHost;
-    if (th) hostMap.set(fh, th);
-  }
-  for (const [fh, th] of hostMap) add(fh, th);
-  // Config dir in the shapes hooks reference it (~/.config/<dir>, /etc/<dir>, the [<dir>] log tag).
-  const fc = effConfigDir(from), tc = effConfigDir(to);
-  add(`.config/${fc}`, `.config/${tc}`);
-  add(`/etc/${fc}`, `/etc/${tc}`);
-  add(`[${fc}]`, `[${tc}]`);
-  // The instance env-var prefix (e.g. OTB_ → BONGOS_), bounded by its underscore.
-  add(`${effEnvPrefix(from)}_`, `${effEnvPrefix(to)}_`);
-  // task 1002672: the bare User-Agent brand token (e.g. `example-gds-cli/1.0`
-  // in a hook's outbound fetch). It carries no TLD, so none of the HOST rules above
-  // ever matched it and a founder-branded UA leaked into every materialized
-  // instance verbatim. Bounded by the `-gds` suffix (the userAgent() convention)
-  // so a bare founder word in prose is NOT rewritten — only the UA token shape.
-  // Both bases must resolve: an empty side would degenerate into a bare `-gds`
-  // rule that rewrites every occurrence of the suffix itself.
-  const fromUa = effUaBase(from), toUa = effUaBase(to);
-  if (fromUa && toUa) add(`${fromUa}-gds`, `${toUa}-gds`);
-  // Longest literal first so a full host is replaced before any bare token inside it.
-  rules.sort((x, y) => y.pattern.source.length - x.pattern.source.length);
-  return rules;
-}
-
-function rebrandText(text, rules) {
-  if (typeof text !== 'string' || !text || !rules || !rules.length) return text;
-  let out = text;
-  for (const r of rules) out = out.replace(r.pattern, r.replace);
-  return out;
-}
-
-function readJsonSafe(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } }
-
-// Every module that declares `contributes.skills`, with whether the TARGET instance
-// enables it: the target's config/modules.json wins, else the module's own `default`.
-// The one place that rule lives — disabledModuleSkills and moduleSkillSources both
-// read it. PURE-ish (reads the fs) + exported.
-function moduleSkillRoster({ coreRoot, instanceDir }) {
-  const roster = [];
-  const modulesDir = path.join(coreRoot, 'modules');
-  if (!fs.existsSync(modulesDir)) return roster;
-  const targetCfg = readJsonSafe(path.join(instanceDir, 'config', 'modules.json')) || {};
-  const enabledMap = (targetCfg.modules && typeof targetCfg.modules === 'object') ? targetCfg.modules : {};
-  for (const dir of fs.readdirSync(modulesDir)) {
-    const mj = readJsonSafe(path.join(modulesDir, dir, 'module.json'));
-    const skills = mj && mj.contributes && mj.contributes.skills;
-    if (!Array.isArray(skills)) continue;
-    const key = mj.key || dir;
-    const explicit = enabledMap[key];
-    const enabled = explicit === undefined ? mj.default === true : explicit === true;
-    roster.push({ key, dir: path.join(modulesDir, dir), enabled, skills });
-  }
-  return roster;
-}
-
-// Skills owned by a module that is DISABLED in the TARGET instance (task 2103b).
-// A skill owned by NO module is core and is never skipped.
-function disabledModuleSkills(opts) {
-  const skip = new Set();
-  for (const m of moduleSkillRoster(opts)) if (!m.enabled) for (const s of m.skills) skip.add(s);
-  return skip;
-}
-
-// A declared skill name is a path segment the materialiser WRITES under
-// .claude/skills/, so it is allowlisted before it ever reaches path.join: lowercase
-// slug only, no dots, no separators. A manifest carrying "../x" names nothing.
-const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
-
-// The vendoring gate a THIRD-PARTY skill must pass at copy time, not only in CI
-// (ADR 0198 §1–3): a PROVENANCE.md sidecar whose frontmatter names a licence on the
-// allowlist and a scan verdict that may land. The module's own skills/policy.json
-// (the ui-design shape) is the source of both lists when present; these defaults
-// are the same five licences and two verdicts otherwise. A gate that cannot read
-// the sidecar refuses — an unvetted copy never lands because a file was missing.
-const VENDOR_DEFAULT_POLICY = Object.freeze({
-  licenceAllowlist: ['Apache-2.0', 'MIT', 'BSD-2-Clause', 'BSD-3-Clause', 'CC-BY-4.0'],
-  verdictsThatMayLand: ['clean', 'caution'],
-});
-
-function sidecarFrontmatter(file) {
-  let text;
-  try { text = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; }
-  const m = text.match(/^---\n([\s\S]*?)\n---\n/);
-  if (!m) return null;
-  const out = {};
-  for (const line of m[1].split('\n')) {
-    const kv = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
-    if (kv) out[kv[1]] = kv[2].replace(/^["']|["']$/g, '').trim();
-  }
-  return out;
-}
-
-// → { ok: true } or { ok: false, reason } for one vendored skill dir. Exported for the test.
-function vendoredSkillGate(dir, policy = VENDOR_DEFAULT_POLICY) {
-  const fm = sidecarFrontmatter(path.join(dir, 'PROVENANCE.md'));
-  if (!fm) return { ok: false, reason: 'no PROVENANCE.md sidecar (or no frontmatter)' };
-  const licences = Array.isArray(policy.licenceAllowlist) ? policy.licenceAllowlist : VENDOR_DEFAULT_POLICY.licenceAllowlist;
-  const verdicts = Array.isArray(policy.verdictsThatMayLand) ? policy.verdictsThatMayLand : VENDOR_DEFAULT_POLICY.verdictsThatMayLand;
-  if (!licences.includes(fm.licence)) return { ok: false, reason: `licence "${fm.licence || ''}" is not on the allowlist` };
-  if (!verdicts.includes(fm.scanVerdict)) return { ok: false, reason: `scan verdict "${fm.scanVerdict || ''}" may not land` };
-  return { ok: true };
-}
-
-// Skills a module ships from its OWN tree instead of .claude/skills/ (task 1003321,
-// ADR 0198): modules/<key>/skills/<name>/ for a skill the module authors, or
-// modules/<key>/skills/vendor/<name>/ for a third-party skill carried with its
-// PROVENANCE.md sidecar (the `vendor/` segment is the one fitness-ratchets exempts
-// from the first-party line budgets). Only a name the module DECLARES in
-// contributes.skills resolves — the manifest stays the single declaration — a name
-// that fails SKILL_NAME_RE is refused before any path is built, a dir with no
-// SKILL.md is not a skill, and a vendored dir must pass vendoredSkillGate. Refusals
-// come back in `refused[]` so the caller can log them. Accepts a precomputed
-// `roster` so materializeClaude walks modules/ once. PURE-ish (reads the fs) + exported.
-function moduleSkillSources(opts) {
-  const out = [];
-  const refused = [];
-  const roster = (opts && opts.roster) || moduleSkillRoster(opts);
-  for (const m of roster) {
-    const policy = readJsonSafe(path.join(m.dir, 'skills', 'policy.json')) || VENDOR_DEFAULT_POLICY;
-    for (const name of m.skills) {
-      if (typeof name !== 'string' || !SKILL_NAME_RE.test(name)) { refused.push({ name: String(name), module: m.key, reason: 'name is not a lowercase slug' }); continue; }
-      const own = path.join(m.dir, 'skills', name);
-      const vendored = path.join(m.dir, 'skills', 'vendor', name);
-      const src = [own, vendored].find((p) => fs.existsSync(path.join(p, 'SKILL.md')));
-      if (!src) continue;
-      if (src === vendored) {
-        const gate = vendoredSkillGate(src, policy);
-        if (!gate.ok) { refused.push({ name, module: m.key, reason: gate.reason }); continue; }
-      }
-      out.push({ name, module: m.key, dir: src, enabled: m.enabled, vendored: src === vendored });
-    }
-  }
-  out.refused = refused;
-  return out;
-}
-
-// ---- retired core skills: the tombstone list (task 1004482) -----------------
-// A skill the core USED to ship from its own .claude/skills/ and no longer does (the dev-box
-// verbs, the old /dev /ideate /paint role playbooks, the pixel-art skills that moved into a
-// default-off module). Every instance materialized before task 1004482 received them as core
-// skills, and the provenance manifest then recorded only module-declared names — so step 1c
-// could never prove it had put them there and they stayed in .claude/skills/ for the harness to
-// load and the hall's Commands page to list, forever.
-//
-// From task 1004482 on the manifest records EVERY skill a materialize lands, so a skill the core
-// drops later is withdrawn by step 1c's ordinary rule. This list closes the historical gap only,
-// and is therefore a closed set: it should not need a new entry.
-//
-// "Never touch a skill the instance authored" is held by a fingerprint, not by the name: each
-// entry lists sha256 digests (first 16 hex) of every description the core ever shipped under that
-// name, as written and as bongosify() rewrote it. A dir whose SKILL.md description matches none of
-// them is not ours and is left in place with a note — an owner who wrote their own /dev keeps it.
-const RETIRED_CORE_SKILLS_FILE = path.join(__dirname, 'retired-core-skills.json');
-
-// The `description:` value of a SKILL.md's frontmatter, whitespace-collapsed — a plain scalar,
-// a quoted one, or a block scalar (`>` / `|`) with its indented continuation lines. null when
-// the file has no frontmatter or no description. PURE + exported.
-function skillDescription(text) {
-  const m = String(text == null ? '' : text).replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
-  if (!m) return null;
-  const lines = m[1].split('\n');
-  const i = lines.findIndex((l) => /^description:/.test(l));
-  if (i < 0) return null;
-  const parts = [lines[i].replace(/^description:\s*/, '')];
-  if (/^[>|][+-]?$/.test(parts[0])) parts[0] = '';
-  for (let j = i + 1; j < lines.length && /^\s+\S/.test(lines[j]); j += 1) parts.push(lines[j]);
-  const value = parts.join(' ').replace(/\s+/g, ' ').trim().replace(/^(["'])([\s\S]*)\1$/, '$2').trim();
-  return value || null;
-}
-
-function descriptionDigest(desc) {
-  return crypto.createHash('sha256').update(String(desc)).digest('hex').slice(0, 16);
-}
-
-// Does this instance skill dir carry a description the core shipped under `name`? Reads the
-// tombstone's digests; an unreadable SKILL.md or a missing description answers "no" (keep it).
-function isRetiredCoreCopy(dir, digests) {
-  if (!Array.isArray(digests) || !digests.length) return false;
-  let text;
-  try { text = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8'); } catch { return false; }
-  const desc = skillDescription(text);
-  return desc != null && digests.includes(descriptionDigest(desc));
-}
-
-function readRetiredCoreSkills(file = RETIRED_CORE_SKILLS_FILE) {
-  const j = readJsonSafe(file);
-  return j && j.skills && typeof j.skills === 'object' ? j.skills : {};
-}
-
-// ---- I/O: copy a tree, transforming text files through bongosify ----------
-
-const TEXT_EXT = new Set(['.md', '.txt', '.sh']); // command-bearing text we rewrite (skills are SKILL.md)
-
-// Every file under `dir`, as paths relative to it. Used to name a withdrawn skill dir's
-// files before it is removed — a deletion git reports one file at a time, never the dir.
-function listFilesRecursive(dir, base = '') {
-  const out = [];
-  let entries;
-  try { entries = fs.readdirSync(path.join(dir, base), { withFileTypes: true }); } catch { return out; }
-  for (const e of entries) {
-    const rel = path.join(base, e.name);
-    if (e.isDirectory()) out.push(...listFilesRecursive(dir, rel));
-    else out.push(rel);
-  }
-  return out;
-}
-
-// `overwrite` defaults true (greenfield init / upgrade — byte-identical to before).
-// `overwrite: false` is the `bongos init --adopt` layering path (ADR 0121): a file
-// that already exists at the destination is NEVER clobbered — it is skipped and
-// recorded in the returned `skipped[]` so the caller can report it.
-// `transform` (text→text) is applied to any file whose extension is in `textExt`
-// (default: bongosify over .md/.txt/.sh — the historical skills behavior). `skip(rel)`
-// excludes a whole subtree BEFORE it is walked (task 2103b — drop a disabled module's
-// skill dir); excluded top-level entries are returned in `excluded[]`.
-function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true, transform = bongosify, textExt = TEXT_EXT, skip } = {}) {
-  let files = 0;
-  const skipped = [];
-  const excluded = [];
-  const walk = (rel) => {
-    if (skip && skip(rel)) { excluded.push(rel); return; }
-    const absSrc = path.join(srcDir, rel);
-    const st = fs.statSync(absSrc);
-    if (st.isDirectory()) {
-      for (const name of fs.readdirSync(absSrc)) walk(path.join(rel, name));
-      return;
-    }
-    const absDest = path.join(destDir, rel);
-    if (!overwrite && fs.existsSync(absDest)) { // adopt: leave-and-report, never clobber
-      skipped.push(rel);
-      if (onFile) onFile(rel, { skipped: true });
-      return;
-    }
-    files += 1;
-    if (dryRun) { if (onFile) onFile(rel); return; }
-    fs.mkdirSync(path.dirname(absDest), { recursive: true });
-    if (textExt.has(path.extname(rel))) {
-      fs.writeFileSync(absDest, transform(fs.readFileSync(absSrc, 'utf8')));
-    } else {
-      fs.copyFileSync(absSrc, absDest); // binary / other — verbatim
-    }
-    if (onFile) onFile(rel);
-  };
-  if (!fs.existsSync(srcDir)) return { files: 0, skipped, excluded, present: false };
-  for (const name of fs.readdirSync(srcDir)) walk(name);
-  return { files, skipped, excluded, present: true };
-}
-
-// Transform settings.json: parse, rewrite every hook command through bongosify, re-serialize. Keeps
-// .claude/hooks/*.js commands (instance-local) untouched and rewrites the scripts/gds/*.js ones.
-// The blessed commands an instance builder runs to do the methodology, one rule
-// each (task 1003962). This MIRRORS the core repo's own `.claude/settings.json`
-// allow-list (ADR 0104 / task 1051), translated from `node scripts/gds/<x>.js`
-// into the verb form a materialized instance actually invokes — bongosify()
-// rewrites every skill to `bongos <verb>`, so a path-shaped rule would match
-// nothing there.
-//
-// THE GAP THIS CLOSES. `.claude/settings.json` is excluded from the published
-// package on purpose (PROTECTED_TOPOLOGY_EXCLUDE, beside infra/ and .github/):
-// the core's own copy is deploy and gate machinery that means nothing on an
-// instance. But the skills ship, so an instance received the methodology and
-// none of the permissions that let it run — every instance builder met the
-// auto-mode classifier on the normal workflow, which is how a live builder came
-// to be stuck mid-re-auth with no way forward.
-//
-// WHY THIS IS NOT AN AUTHORITY GRANT (ADR 0016). An allow-rule stops the local
-// agent REFUSING to run a command; it changes nothing about what the server
-// permits. Rank is read fresh from the database on every request by
-// `requireRank`, so a builder who edits this file grants themselves exactly
-// nothing. That is the distinction that makes shipping a list of command names
-// safe where shipping hooks — actual local gate machinery — is not.
-//
-// DELIBERATELY ABSENT: `bongos exec`. It runs any script inside the core by
-// path and is the agent's escape hatch, so allow-listing it would be a blanket
-// grant wearing a narrow rule's clothes. The one script the core's own list
-// blesses (`api.js`) is named in full instead.
-//
-// EVERY RULE IS THE `npx bongos` SPELLING (task 1004621): a project has no bare
-// `bongos` on PATH, so its skills, its CLAUDE.md and Settings → CLI access
-// (task 1004575) all say `npx bongos …`, and a bare-`bongos` rule would allow a
-// command nothing runs. An instance that took the older bare starter gains the
-// npx twin of each bare rule it still holds on its next upgrade
-// (topUpNpxAllowTwins below).
-const STARTER_COMMANDS = [
-  'npx bongos claim:*',
-  'npx bongos ship:*',
-  'npx bongos release:*',
-  'npx bongos reauth:*',
-  'npx bongos paste-token:*',
-  'npx bongos exec scripts/gds/api.js:*',
-  // The read-only subset (task 1003992, ADR 0304). `git branch` and `git fetch`
-  // are exact forms on purpose: a flag turns either into a write or an exec. No
-  // `git diff|log|show` rule, also on purpose: the harness already runs their
-  // read-only forms unprompted, and a prefix rule would switch off its flag check
-  // (`--output=<file>` writes anywhere, `diff --no-index` reads any file).
-  // tests/cli_allowlist_permissions.mjs pins this list to the core's, rule for rule.
-  'npx bongos start:*',
-  'npx bongos status:*',
-  // Exact form, no `:*`: reading the ship mode is how the agent knows whether to ship on its own
-  // (task 1004631, ADR 0369). `ship-mode auto|manual` WRITES it, and stays a prompt.
-  'npx bongos ship-mode',
-  'npx bongos recall:*',
-  'npx bongos exec scripts/gds/me.js:*',
-  'npx bongos doctor:*',
-  'npx bongos exec scripts/gds/preflight.js:*',
-  'npx bongos exec scripts/gds/skill-preflight.js:*',
-  'npx bongos exec scripts/gds/ship-check.js:*',
-  'npx bongos exec scripts/gds/fitness.js:*',
-  'npx bongos exec scripts/gds/strand-watch.js:*',
-  'npx bongos exec scripts/gds/stale-worktrees.js:*',
-  'npx bongos exec scripts/gds/read-session-export.js:*',
-  'git status:*',
-  'git branch --list',
-  'git branch --show-current',
-  'git branch -a',
-  'git branch -vv',
-  'git fetch',
-  'git fetch origin',
-  'git fetch origin main',
-  'gh pr view:*',
-  'gh pr checks:*',
-  'gh pr list:*',
-  'gh run view:*',
-  'gh run list:*',
-];
-// One rule per command PER SHELL TOOL (task 1004014): the shell tool is `PowerShell` on a Windows
-// laptop, and a `Bash(...)` rule says nothing about its commands. The tools are the ones the guards
-// see (`.claude/hooks/shell-tools.js`) — held equal by tests/cli_allowlist_permissions.mjs, not a require.
-const STARTER_SHELL_TOOLS = ['Bash', 'PowerShell'];
-const STARTER_ALLOW = STARTER_SHELL_TOOLS.flatMap((tool) => STARTER_COMMANDS.map((command) => `${tool}(${command})`));
-
-// The deny half (task 1003966): what the local agent may not READ. Keys are the
-// same exposure on every instance, so those rules ship verbatim.
-const STARTER_DENY_SECRETS = [
-  'Read(.env)', 'Read(**/.env)', 'Read(.env.local)', 'Read(**/.env.local)',
-  'Read(.env.*.local)', 'Read(**/.env.*.local)',
-  'Read(**/*.pem)', 'Read(**/id_rsa*)', 'Read(**/id_ed25519*)',
-];
-const SESSION_STORE_DENY = `Read(~/.config/${ic.FALLBACK_DIR}/instances/**)`;
-
-// A checkout's settings.json takes the identity rebrand like every copied file, and the store's
-// dir is one of the core's `.config/<dir>` literals it rewrites. The store does not move with the
-// brand (task 1003741), so its rule is put back where the CLI reads it (task 1004155).
-function rebrandSettings(text, rebrand) {
-  const moved = rebrand(SESSION_STORE_DENY);
-  return rebrand(text).split(JSON.stringify(moved)).join(JSON.stringify(SESSION_STORE_DENY));
-}
-
-// Credential files are derived from where the CLI actually reads them, not rebranded from the
-// core's literals: the rebrand would also move the host-keyed store, which sits at a fixed anchor
-// whatever the brand (cli-lib sessionStoreDir, task 1003741).
-//
-// credentialDeny is the half that may be added to a settings.json the instance already owns.
-// Every rule here stops the agent READING A SECRET, and nothing an instance legitimately does
-// requires reading its own key or session token from inside an agent session — which is what
-// makes appending one provably safe (ADR 0326: a deny rule is monotonic in the safe direction).
-function credentialDeny(branding = {}) {
-  const dirs = [...new Set([effConfigDir(branding), ...ic.LEGACY_DIRS])];
-  const credentialFiles = ['env', ...ic.SESSION_FILENAMES];
-  return [
-    ...STARTER_DENY_SECRETS,
-    ...dirs.flatMap((dir) => credentialFiles.map((file) => `Read(~/.config/${dir}/${file})`)),
-    SESSION_STORE_DENY,
-  ];
-}
-
-// starterDeny — what a FRESH instance gets: the credential half plus the shelf rules, which are
-// the only layer an instance has against the repo-global stash stack since the git-guard hook is
-// topology and does not ship.
-//
-// The shelf rules are starter-only, and deliberately NOT in the top-up (task 1004158, amending
-// ADR 0326, which named this exclusion as the remedy if the rule ever bit). They guard a WORKFLOW
-// rather than a secret, so the monotonicity argument that licenses the top-up does not reach them:
-// with no provenance by design, and deny beating allow in Claude Code's permission order, an
-// instance whose builders used the shelf as a set-aside could not re-enable it from its own
-// settings.json afterwards. A fresh instance is different in kind — there the rule is a visible
-// default present from the first commit, editable before any workflow has grown around it.
-function starterDeny(branding = {}) {
-  return [
-    ...credentialDeny(branding),
-    ...STARTER_SHELL_TOOLS.map((tool) => `${tool}(git stash:*)`),
-  ];
-}
-
-// topUpStarterDeny — the deny rules an instance's OWN settings.json is missing, added to it
-// (task 1004156). The starter is only ever written when the file is ABSENT, so every instance
-// that took the allow-only starter from task 1003962 keeps it forever and its local agent can
-// still read .env files, keys and session tokens. ADDING is the whole safety argument: a deny
-// rule can only ever narrow what the agent may do, so appending one cannot widen this instance's
-// permissions — which is why the owner's call (task 1004156) was "add them, and say which".
-// "Never clobber" is unchanged in the sense that matters: nothing the instance wrote is removed
-// or rewritten. Returns { text, added, reason }; `text` is null when nothing should be written.
-// `reason` is the STRUCTURED signal that the file could not be CHECKED — null means "healthy",
-// so callers branch on its presence rather than on the wording of a message. An unparseable or
-// unexpectedly-shaped file is LEFT ALONE and reported, the posture task 1004023 took for a
-// settings.json that will not parse: a half-understood rewrite of a permissions file is worse
-// than the gap it closes. Note the write re-emits the whole document at 2-space JSON, so an
-// instance indented some other way sees a whole-file diff — the RULES are still append-only,
-// which is what the safety argument rests on, and the run output says so.
-function topUpStarterDeny(existingText, wanted) {
-  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
-  const cannotCheck = (reason) => ({ text: null, added: [], reason });
-  let doc;
-  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
-  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
-  const perms = doc.permissions === undefined ? {} : doc.permissions;
-  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
-  const deny = perms.deny === undefined ? [] : perms.deny;
-  if (!Array.isArray(deny)) return cannotCheck('its "permissions.deny" is not an array');
-  const have = new Set(deny);
-  const added = wanted.filter((rule) => !have.has(rule));
-  if (!added.length) return { text: null, added: [], reason: null }; // healthy: every rule already there
-  const next = { ...doc, permissions: { ...perms, deny: [...deny, ...added] } };
-  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
-}
-
-// topUpNpxAllowTwins — the `npx bongos` twin of every bare-`bongos` allow rule an instance's OWN
-// settings.json holds (task 1004621). The skills an upgrade lands now say `npx bongos ship`, and a
-// `Bash(bongos ship:*)` rule does not match that, so without the twin the upgrade would trade a
-// `command not found` for a permission prompt on every blessed command. This is NOT the shell-rule
-// top-up task 1004158 ruled out: nothing new is offered. Each twin is a rule the owner already
-// holds, respelled for the one launcher that reaches the same project-local bin — a rule they
-// removed gets no twin, and nothing they wrote is removed or rewritten. Same { text, added, reason }
-// contract as topUpStarterDeny; an unreadable shape is left alone and reported.
-const BARE_BONGOS_RULE_RE = /^(\w+)\(bongos (.+)\)$/;
-function topUpNpxAllowTwins(existingText) {
-  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
-  const cannotCheck = (reason) => ({ text: null, added: [], reason });
-  let doc;
-  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
-  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
-  const perms = doc.permissions === undefined ? {} : doc.permissions;
-  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
-  const allow = perms.allow === undefined ? [] : perms.allow;
-  if (!Array.isArray(allow)) return cannotCheck('its "permissions.allow" is not an array');
-  const have = new Set(allow);
-  const added = [];
-  for (const rule of allow) {
-    const m = typeof rule === 'string' && rule.match(BARE_BONGOS_RULE_RE);
-    const twin = m && `${m[1]}(${PROJECT_CLI} ${m[2]})`;
-    if (twin && !have.has(twin)) { have.add(twin); added.push(twin); }
-  }
-  if (!added.length) return { text: null, added: [], reason: null };
-  const next = { ...doc, permissions: { ...perms, allow: [...allow, ...added] } };
-  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
-}
-
-// The starter an instance gets when the core root carries no settings.json — a
-// package-only install. Permissions ONLY: no hooks (they are topology), no env.
-function renderStarterSettings(branding = {}) {
-  return `${JSON.stringify({
-    _doc: 'Starter written by scripts/gds/claude-materialize.js (tasks 1003962, 1003966). Permissions only — the blessed Bongos commands, mirroring the core repo\'s own allow-list (ADR 0104), and the deny rules that keep the local agent from reading keys and session tokens. An allow-rule lets the local agent RUN a command; it grants no authority, which the server decides per request from your live rank (ADR 0016). Yours to edit: a later materialize never removes or rewrites a rule you wrote. It will ADD a CREDENTIAL deny rule this starter has gained since (task 1004156) and name it in the run output — additive only, so it can never widen what the local agent may do. Only that half is topped up: the shell rules below guard a workflow rather than a secret, so once this file exists they are yours alone and an upgrade will neither add nor remove one (task 1004158).',
-    permissions: { allow: STARTER_ALLOW, deny: starterDeny(branding) },
-  }, null, 2)}\n`;
-}
-
-// readSettingsTransform — the transform, as a result rather than a string:
-// { text, parsed, reason }. transformSettings below is the string face of it,
-// kept because that is what the tests and the historical callers use.
-//
-// WHY A PARSE FAILURE IS COPIED THROUGH UNTOUCHED (task 1004023). The old
-// fallback was `bongosify(raw)` — a best-effort regex rewrite over the whole
-// file. The script-invocation regex ends in an optional quote so it can swallow the
-// closing quote of a QUOTED PATH inside a command; run over raw JSON text it
-// swallows the JSON string's own closing quote instead:
-//
-//     bongosify('{"command": "node scripts/gds/strand-watch.js", }')
-//     -> {"command": "bongos exec scripts/gds/strand-watch.js, }
-//
-// So a file that was one trailing comma from valid was written to the instance
-// MORE broken than it arrived, with its strings running into each other. A
-// rewrite of text we could not parse is not worth a worse file: the raw bytes
-// are copied through unchanged and the caller is handed a reason to report. The
-// operator fixes one comma instead of unpicking mangled strings.
-//
-// The parse failure is NOT made fatal: the core's own settings.json is valid
-// JSON (pinned by a test), so reaching this means the operator has edited
-// theirs, and refusing the whole materialize over one file would be a worse
-// trade than copying it and saying so.
-function readSettingsTransform(srcPath) {
-  const raw = fs.readFileSync(srcPath, 'utf8');
-  let json;
-  try {
-    json = JSON.parse(raw);
-  } catch (err) {
-    return { text: raw, parsed: false, reason: (err && err.message) || 'not valid JSON' };
-  }
-  const hooks = json && json.hooks;
-  if (hooks && typeof hooks === 'object') {
-    for (const event of Object.values(hooks)) {
-      for (const matcher of Array.isArray(event) ? event : []) {
-        for (const h of (matcher && Array.isArray(matcher.hooks)) ? matcher.hooks : []) {
-          if (typeof h.command === 'string') h.command = bongosify(h.command);
-        }
-      }
-    }
-  }
-  // Permission rules name the SAME commands the hooks and skills do, so they take the same
-  // rewrite — a rule left as `node scripts/gds/ship.js` matches nothing once the instance's
-  // skills run `bongos ship` (task 1004012). `allow` gets the one spelling the skills use; a
-  // restrictive list gets BOTH ways an instance can reach the script, or it guards only one.
-  const perms = json && json.permissions;
-  if (perms && typeof perms === 'object') {
-    for (const [key, rules] of Object.entries(perms)) {
-      if (!Array.isArray(rules)) continue;
-      // an empty verb table makes bongosify emit the `bongos exec scripts/gds/<x>.js` spelling
-      const spellings =(r) => (key === 'allow' ? [bongosify(r)] : [bongosify(r), bongosify(r, {})]);
-      perms[key] = [...new Set(rules.flatMap((r) => (typeof r === 'string' ? spellings(r) : [r])))];
-    }
-  }
-  return { text: JSON.stringify(json, null, 2) + '\n', parsed: true, reason: null };
-}
-
-// transformSettings — the string face of readSettingsTransform. A caller that
-// only wants the bytes keeps working; one that needs to know the file could not
-// be parsed calls readSettingsTransform and reads `parsed`.
-function transformSettings(srcPath) {
-  return readSettingsTransform(srcPath).text;
-}
-
-// Materialize the .claude/ surface from `coreRoot` into `instanceDir`. Returns a summary.
-// `overwrite` defaults true (greenfield init / upgrade — unchanged). `overwrite: false`
-// is the `bongos init --adopt` layering path (ADR 0121): every pre-existing .claude/
-// file is LEFT untouched and recorded in `summary.skippedFiles` (never clobbered). The ONE
-// exception is settings.json in a package-only install, which GAINS any starter deny rule it is
-// missing and reports them in `summary.settingsDenyAdded` (task 1004156) — additive only, so
-// nothing the instance wrote is removed or rewritten.
-const HOOK_TEXT_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.sh', '.md', '.txt']); // hooks are .js — rebrand them too
-
-function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
-  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, settingsUnparsed: false, settingsDenyAdded: [], settingsDenyUncheckable: null, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, writtenPaths: [], notes: [] };
-  // Every instance-relative path this run WROTE or REMOVED (task 1003957). `bongos upgrade`
-  // hands these to persistPin as artifactPaths, exactly as task 1003926 already does for
-  // regenerateApiArtifacts' output: committing only the pin left the materialized files dirty,
-  // so the NEXT sweep's clean-tree guard called them "a human's work" and skipped the instance
-  // FOREVER — an enrolled co-tenant upgraded exactly once (proven on `charter` 2026-09-16).
-  //
-  // Recording what we wrote is a STRONGER provenance than a static file list: every path here
-  // is one this very run produced. It cannot carry an owner's edit either, and not for the
-  // "generated end to end" reason API_ARTIFACT_FILES gives — for a sharper one. Under
-  // `overwrite` the copy ALREADY replaced whatever the file held before reaching this line, so
-  // the only choice left is commit that overwrite or strand the instance; leaving it dirty
-  // protects nothing and stops every future update. Under `overwrite: false` (the `init
-  // --adopt` path) nothing is clobbered — copyTreeTransformed reports those as `skipped` and
-  // addWritten ignores them — so an adopting instance records nothing here and commits nothing.
-  const rel = (p) => String(p).split(path.sep).join('/');
-  const addWritten = (p) => { summary.writtenPaths.push(rel(p)); };
-  // A copyTreeTransformed onFile that records real writes under `base` and ignores the
-  // leave-and-report entries adopt mode emits.
-  const recordUnder = (base) => (r, info) => { if (!info || !info.skipped) addWritten(path.join(base, r)); };
-  if (path.resolve(instanceDir) === path.resolve(coreRoot)) {
-    summary.skipped = true;
-    summary.notes.push('instance dir is the core root — nothing to materialize (byte-identical no-op).');
-    log('  • .claude/ materialize: instance dir == core root — skipped (nothing to copy).');
-    return summary;
-  }
-  const srcClaude = path.join(coreRoot, '.claude');
-  const destClaude = path.join(instanceDir, '.claude');
-  const left = (n) => (overwrite || n === 0 ? '' : ` (${n} left untouched)`);
-
-  // Rebrand: rewrite the SOURCE instance's identity (origin host, config dir, env
-  // prefix) to the TARGET's, so a copied hook never phones home to the founder's
-  // instance (task 2103a). Derived from both config/branding.json files; empty — and
-  // thus a no-op — when they match or either is unreadable.
-  const fromBranding = readJsonSafe(path.join(coreRoot, 'config', 'branding.json')) || {};
-  const toBranding = readJsonSafe(path.join(instanceDir, 'config', 'branding.json')) || {};
-  const rebrandRules = buildRebrandRules(fromBranding, toBranding);
-  const rebrand = (t) => rebrandText(t, rebrandRules);
-  summary.rebrandRules = rebrandRules.length;
-  if (rebrandRules.length) log(`  • rebranding ${rebrandRules.length} founder literal(s) in the copied .claude/ → this instance's identity.`);
-
-  // Drop skills owned by a module this instance hasn't enabled (task 2103b). One
-  // walk of modules/ serves both this skip and step 1b's module-owned sources.
-  const roster = moduleSkillRoster({ coreRoot, instanceDir });
-  const skipSkills = new Set();
-  for (const m of roster) if (!m.enabled) for (const s of m.skills) skipSkills.add(s);
-  // A core checkout that materialised module skills into its own .claude/skills/ (task 1003330)
-  // carries them as untracked copies plus two dotfiles; step 1 must not ship those as core
-  // skills — step 1b lands them from the module, transformed, like everywhere else.
-  const materialisedInCore = readModuleSkillsManifest(path.join(coreRoot, '.claude', 'skills')).skills;
-  // The INSTANCE's own provenance record — what a PREVIOUS materialize landed here.
-  // Distinct from materialisedInCore above (that one is the core checkout's). Step 1c
-  // withdraws from this set and nothing else.
-  const landedPreviously = readInstanceSkillsManifest(path.join(destClaude, 'skills')).skills;
-  const skillSkip = (rel) => { const top = String(rel).split(/[\\/]/)[0]; return skipSkills.has(top) || top === MODULE_SKILLS_MANIFEST || top === INSTANCE_SKILLS_MANIFEST || top === '.gitignore' || Object.prototype.hasOwnProperty.call(materialisedInCore, top); };
-
-  // 1. skills — ship in the core package; copy, rewrite invocations→bongos, rebrand
-  //    identity, and exclude any skill owned by a disabled module.
-  const skillsSrc = path.join(srcClaude, 'skills');
-  const skillsRes = copyTreeTransformed(skillsSrc, path.join(destClaude, 'skills'), {
-    dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), skip: skillSkip,
-    onFile: recordUnder('.claude/skills'),
-  });
-  summary.skills = skillsRes.files;
-  summary.excludedSkills = skillsRes.excluded || [];
-  for (const rel of skillsRes.skipped || []) summary.skippedFiles.push(`skills/${rel}`);
-  if (!skillsRes.present) summary.notes.push('.claude/skills not found at the core root — none materialized.');
-  if (summary.excludedSkills.length) log(`  • excluded ${summary.excludedSkills.length} skill(s) owned by disabled module(s): ${summary.excludedSkills.join(', ')}`);
-  log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${skillsRes.files} skill file(s) → .claude/skills/ (invocations→bongos, identity rebranded)${left((skillsRes.skipped || []).length)}`);
-
-  // 1b. module-owned skills — shipped from modules/<key>/skills/ (own) or
-  //     modules/<key>/skills/vendor/ (third-party + PROVENANCE.md) and landed in the
-  //     SAME .claude/skills/<name>/ the builder's harness reads (task 1003321, ADR
-  //     0198). Same transforms as step 1; a disabled module's are excluded by the same
-  //     rule; a name the core's own .claude/skills/ already carries keeps the core copy;
-  //     a name that is not a slug, or a vendored dir that fails the sidecar gate, is
-  //     REFUSED here at copy time — the CI test is the second line, not the only one.
-  const sources = moduleSkillSources({ roster });
-  for (const r of sources.refused) {
-    summary.notes.push(`module skill "${r.name}" (${r.module}) refused: ${r.reason}.`);
-    log(`  ✗ refused module skill "${r.name}" (${r.module}): ${r.reason}`);
-  }
-  for (const s of sources) {
-    if (!s.enabled) { if (!summary.excludedSkills.includes(s.name)) summary.excludedSkills.push(s.name); continue; }
-    if (fs.existsSync(path.join(skillsSrc, s.name)) && !Object.prototype.hasOwnProperty.call(materialisedInCore, s.name)) {
-      summary.notes.push(`module skill "${s.name}" (${s.module}) also exists under the core's .claude/skills/ — the core copy was materialized, the module copy ignored.`);
-      continue;
-    }
-    const r = copyTreeTransformed(s.dir, path.join(destClaude, 'skills', s.name), { dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), onFile: recordUnder(`.claude/skills/${s.name}`) });
-    summary.moduleSkills += r.files;
-    for (const rel of r.skipped || []) summary.skippedFiles.push(`skills/${s.name}/${rel}`);
-  }
-  if (summary.moduleSkills) log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${summary.moduleSkills} module-owned skill file(s) → .claude/skills/ (from modules/<key>/skills/)`);
-
-  // 1c. WITHDRAW a skill a previous materialize landed here that this run no longer
-  //     lands — the module was switched off (or stopped declaring the name) on an
-  //     instance that ALREADY has the files. Step 1's skillSkip and step 1b's
-  //     `enabled` check both only decline to COPY, which is the whole bug: disabling
-  //     a module was honoured on a fresh instance and silently ignored on
-  //     `bongos upgrade`, leaving stale dirs in .claude/skills/ for the harness to
-  //     keep loading (task 1003632, found by the on/off proof of task 1003331).
-  //     materializeModuleSkillsIntoCore has done this for the core checkout since
-  //     task 1003330; this is the same mechanism for the instance side.
-  //
-  //     PROVENANCE-GATED, and that gate is the safety property: only a name the
-  //     manifest says a previous run LANDED is eligible. A skill the instance's owner
-  //     wrote by hand was never in the manifest, so it can never be deleted here even
-  //     if a module happens to declare the same name. With no manifest at all — an
-  //     instance last materialized before this shipped — nothing is withdrawn and a
-  //     note says so: that first run writes the provenance, and every run after it
-  //     honours a disable. Refusing to guess is the point; deleting a builder's skill
-  //     because we cannot prove we put it there is the one outcome worth avoiding.
-  const skillsDest = path.join(destClaude, 'skills');
-  const landedNow = {};
-  for (const src of sources) {
-    if (!src.enabled) continue;
-    // A dry run copied nothing, so it records what WOULD land; a real run confirms
-    // the dir is actually there before claiming provenance over it.
-    if (!dryRun && !fs.existsSync(path.join(skillsDest, src.name))) continue;
-    landedNow[src.name] = { module: src.module, source: path.relative(coreRoot, src.dir).split(path.sep).join('/'), vendored: src.vendored };
-  }
-  // A core-SHIPPED skill whose name a module also declares is landed by step 1, not
-  // step 1b — but it is withdrawable by the same disabled-module rule, so it needs
-  // provenance too.
-  for (const mod of roster) {
-    if (!mod.enabled) continue;
-    for (const name of mod.skills) {
-      if (landedNow[name] || !fs.existsSync(path.join(skillsSrc, name))) continue;
-      landedNow[name] = { module: mod.key, source: `.claude/skills/${name}`, coreShipped: true };
-    }
-  }
-  // A name the CORE ships now is the core's, whatever an older manifest said — a core
-  // skill can take over a name a module once owned, and step 1 copies it in on this very
-  // run. Without this guard 1c deleted it again immediately (task 1003818, a regression
-  // in 1003632's own first cut). materializeModuleSkillsIntoCore states the same rule for
-  // the checkout side via its `tracked(name)` check; this is the instance-side twin.
-  //
-  // The `!skipSkills.has(name)` half is load-bearing, not belt-and-braces: when a DISABLED
-  // module declares a core-shipped name, step 1 SKIPS the copy (that is the task 2103b
-  // exclusion), so the instance's dir really is stale and must still be withdrawn. Keeping
-  // it on the strength of "the core ships this name" would resurrect exactly the bug 1c
-  // exists to fix. Deliberately asked of the CORE source tree rather than the roster, so a
-  // name no enabled module declares any more is still recognised as legitimately sourced.
-  const coreShipsNow = (name) => fs.existsSync(path.join(skillsSrc, name)) && !skipSkills.has(name);
-  // Every CORE skill step 1 landed is recorded too (task 1004482), so a skill the core stops
-  // shipping in a later release is withdrawn by the rule below instead of lingering forever.
-  // When the core's .claude/skills/ could not be read at all, nothing was landed from it and
-  // nothing may be withdrawn on that account: the previous core entries are carried forward.
-  const coreTreeRead = skillsRes.present;
-  if (coreTreeRead) {
-    for (const name of fs.readdirSync(skillsSrc)) {
-      if (landedNow[name] || !SKILL_NAME_RE.test(name) || skillSkip(name)) continue;
-      if (!fs.statSync(path.join(skillsSrc, name)).isDirectory()) continue;
-      if (!dryRun && !fs.existsSync(path.join(skillsDest, name))) continue;
-      landedNow[name] = { source: `.claude/skills/${name}`, coreShipped: true };
-    }
-  } else {
-    for (const [name, rec] of Object.entries(landedPreviously)) if (rec && rec.coreShipped && !rec.module && !landedNow[name]) landedNow[name] = rec;
-  }
-  const withdrawable = Object.keys(landedPreviously).filter((n) => SKILL_NAME_RE.test(n) && !landedNow[n] && !coreShipsNow(n));
-  // The historical half (task 1004482): a skill the core retired BEFORE the manifest recorded
-  // core skills is withdrawn when its dir still carries a description the core shipped under
-  // that name. Anything else under a retired name is the instance's own and stays.
-  const retired = readRetiredCoreSkills();
-  const keptAsOwn = [];
-  for (const [name, entry] of Object.entries(retired)) {
-    if (!SKILL_NAME_RE.test(name) || landedNow[name] || coreShipsNow(name) || withdrawable.includes(name)) continue;
-    const dir = path.join(skillsDest, name);
-    if (!fs.existsSync(dir)) continue;
-    if (isRetiredCoreCopy(dir, entry && entry.descriptionDigests)) withdrawable.push(name);
-    else keptAsOwn.push(name);
-  }
-  if (keptAsOwn.length) summary.notes.push(`${keptAsOwn.length} skill dir(s) share a name the core once shipped but are not the core's copy (their description is not one it shipped), so they were left in place as the instance's own: ${keptAsOwn.sort().join(', ')}.`);
-  if (!overwrite) {
-    // adopt mode never clobbers what the owner already has; withdrawing is a clobber.
-    if (withdrawable.length) summary.notes.push(`${withdrawable.length} skill(s) the core no longer lands here were left in place (adopt mode does not withdraw): ${withdrawable.sort().join(', ')}.`);
-  } else {
-    for (const name of withdrawable.sort()) {
-      const dir = path.join(skillsDest, name);
-      if (!fs.existsSync(dir)) continue;
-      // A DELETION is a dirty path too, and `git status` names the individual files rather
-      // than the directory — so enumerate before removing, or the withdrawal is exactly the
-      // kind of leftover that wedges the next sweep (task 1003957).
-      for (const f of listFilesRecursive(dir)) addWritten(path.join('.claude/skills', name, f));
-      if (!dryRun) fs.rmSync(dir, { recursive: true, force: true });
-      summary.withdrawnSkills.push(name);
-    }
-    if (summary.withdrawnSkills.length) log(`  ${dryRun ? '[dry-run] would withdraw' : '✓ withdrew'} ${summary.withdrawnSkills.length} stale skill dir(s) the core no longer ships here (retired, or its module is off): ${summary.withdrawnSkills.join(', ')}`);
-  }
-  if (!Object.keys(landedPreviously).length && summary.excludedSkills.length) {
-    summary.notes.push('no .instance-skills.json provenance in .claude/skills/ yet, so nothing was withdrawn — this run records it; a later run can withdraw the skills of a module that has since been disabled.');
-  }
-  // Record what landed, so the NEXT run can withdraw what this one placed.
-  //
-  // REPORTED on a dry run, written only on a real one — the same split the starter CLAUDE.md
-  // below already uses. writtenPaths is a "what this run rewrites" list, and a dry run's job is
-  // to preview exactly that: upgrade.js asks for one to decide which dirty paths its clean-tree
-  // pre-flight may ignore (task 1004122), so a generated file missing from the preview is a file
-  // the pre-flight halts on and the real run then rewrites anyway.
-  if (overwrite) {
-    const names = Object.keys(landedNow).sort();
-    const manifest = { _doc: 'GENERATED by scripts/gds/claude-materialize.js (tasks 1003632, 1004482): every skill a materialize landed in this instance, core and module alike. It is the provenance record that lets a later run WITHDRAW a skill the core stopped shipping or whose module has since been disabled — a name absent from here is never deleted on that account, so a hand-written skill is safe. Commit it; do not hand-edit.', skills: Object.fromEntries(names.map((n) => [n, landedNow[n]])) };
-    if (!dryRun) {
-      fs.mkdirSync(skillsDest, { recursive: true });
-      fs.writeFileSync(path.join(skillsDest, INSTANCE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
-    }
-    addWritten(path.join('.claude/skills', INSTANCE_SKILLS_MANIFEST));
-  }
-
-  // 2. settings.json — topology; present in the checkout/core repo, absent in a package-only install.
-  const settingsSrc = path.join(srcClaude, 'settings.json');
-  if (fs.existsSync(settingsSrc)) {
-    const settingsDest = path.join(destClaude, 'settings.json');
-    if (!overwrite && fs.existsSync(settingsDest)) { // adopt: never clobber an owner's settings.json
-      summary.skippedFiles.push('settings.json');
-      log('  • .claude/settings.json already present — left untouched (adopt merges nothing here yet).');
-    } else {
-      // task 1004023: an unparseable settings.json is copied through BYTE FOR
-      // BYTE — no bongosify, no rebrand. Both are regex passes written for the
-      // strings inside a parsed file, and over raw JSON text they damage it.
-      // The instance gets what the core had, plus a note naming the parse error.
-      const settingsOut = readSettingsTransform(settingsSrc);
-      if (!dryRun) {
-        fs.mkdirSync(destClaude, { recursive: true });
-        fs.writeFileSync(settingsDest, settingsOut.parsed ? rebrandSettings(settingsOut.text, rebrand) : settingsOut.text);
-      }
-      addWritten('.claude/settings.json');
-      summary.settings = true;
-      if (!settingsOut.parsed) {
-        summary.settingsUnparsed = true;
-        summary.notes.push(`.claude/settings.json is not valid JSON (${settingsOut.reason}) — copied through UNCHANGED: no hook-command or permission-rule rewrite to bongos, and no identity rebrand. Fix the JSON at the core root and materialize again, or edit the instance copy by hand.`);
-      }
-      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json ${settingsOut.parsed ? '(hook commands + permission rules→bongos, identity rebranded)' : '(UNCHANGED — not valid JSON, nothing rewritten)'}`);
-    }
-  } else {
-    // Package-only install: the core root carries no settings.json to copy, so
-    // write the STARTER instead of leaving the instance with no permissions at
-    // all (task 1003962 — the note that used to sit here said "provide it from a
-    // starter" and nothing ever did). Written only when ABSENT, the same rule
-    // the starter CLAUDE.md below follows: an instance that has grown its own
-    // permissions owns them, and a later materialize must never clobber them.
-    const settingsDest = path.join(destClaude, 'settings.json');
-    if (fs.existsSync(settingsDest)) {
-      // The instance owns this file — but a deny rule the starter has gained since is ADDED to
-      // it rather than withheld forever (task 1004156). Nothing of theirs is removed or changed.
-      // Only the CREDENTIAL half is offered: the starter's shelf rules guard a workflow, not a
-      // secret, and are starter-only (task 1004158).
-      // The read is guarded: existsSync passing does not mean readable (a directory at that path,
-      // a locked or root-owned file), and this runs AFTER the pin moved and the migrations ran, so
-      // a throw here would leave a half-applied upgrade. It fails soft, like its sibling above.
-      // The npx twins of the owner's own bare-`bongos` allow rules ride the same single read and
-      // write (task 1004621): applied first, so the deny top-up below works on — and writes — the
-      // text that already carries them. An unparseable file trips both the same way and is
-      // reported once, by the deny half.
-      let topUp;
-      let twins = { text: null, added: [], reason: null };
-      try {
-        const raw = fs.readFileSync(settingsDest, 'utf8');
-        twins = topUpNpxAllowTwins(raw);
-        topUp = topUpStarterDeny(twins.text || raw, credentialDeny(toBranding));
-      } catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
-      if (twins.added.length) {
-        summary.settingsAllowTwinsAdded = twins.added;
-        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED the \`npx bongos\` twin of ${twins.added.length} bare-\`bongos\` allow rule(s) it held — the skills now say \`npx bongos …\`, which a bare rule does not match: ${twins.added.join(', ')}`);
-        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} the npx twin of ${twins.added.length} bare-bongos allow rule(s) to .claude/settings.json (skills now run \`npx bongos …\`; every rule you wrote is kept): ${twins.added.join(', ')}`);
-        if (!topUp.text && !topUp.reason) {
-          if (!dryRun) fs.writeFileSync(settingsDest, twins.text);
-          if (!dryRun) addWritten('.claude/settings.json'); // real run only — the same reasoning as the deny write below
-        }
-      }
-      if (topUp.text) {
-        if (!dryRun) fs.writeFileSync(settingsDest, topUp.text);
-        // Reported as written only on the REAL run, deliberately. writtenPaths doubles as the set
-        // the upgrade pre-flight IGNORES when it checks for a dirty tree (task 1004122), and that
-        // waiver is justified by "materialize overwrites these unconditionally, so whatever they
-        // hold now is discarded either way" — which is precisely NOT true of a top-up, the one
-        // path here that preserves existing content. Leaving it out of the dry-run preview keeps
-        // an owner's uncommitted edit to settings.json halting the bump, as it always did; putting
-        // it in the real run's summary still hands it to persistPin, so the pin commit carries the
-        // added rules and the next upgrade does not read them as a human's stray work.
-        if (!dryRun) addWritten('.claude/settings.json');
-        summary.settingsDenyAdded = topUp.added;
-        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED ${topUp.added.length} missing deny rule(s) — an instance that took the starter before task 1003966 carried none of them, so its local agent could still read keys and session tokens: ${topUp.added.join(', ')}`);
-        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} ${topUp.added.length} missing deny rule(s) to .claude/settings.json — every rule you wrote is kept, the file is re-indented to 2 spaces: ${topUp.added.join(', ')}`);
-      } else if (topUp.reason) {
-        // The security gap PERSISTS here, so it does not get the same quiet bullet as the
-        // all-clear. upgrade.js never iterates summary.notes, so this log line is the only
-        // channel that reaches the operator's terminal.
-        summary.skippedFiles.push('settings.json');
-        summary.settingsDenyUncheckable = topUp.reason;
-        summary.notes.push(`.claude/settings.json could not be checked for missing deny rules — ${topUp.reason}. It was left exactly as it is, so if it predates task 1003966 its local agent can still read keys and session tokens; compare its permissions.deny against the starter by hand, or fix the file and upgrade again.`);
-        log(`  ! .claude/settings.json could NOT be checked for missing deny rules — ${topUp.reason}. Left untouched; its deny half may still be missing.`);
-      } else if (!twins.added.length) {
-        summary.skippedFiles.push('settings.json');
-        log('  • .claude/settings.json already present — left untouched (the instance owns it; it already carries every credential deny rule. The starter\'s shelf rules are not offered here — they guard a workflow, not a secret, and are starter-only: task 1004158).');
-      }
-    } else {
-      if (!dryRun) {
-        fs.mkdirSync(destClaude, { recursive: true });
-        fs.writeFileSync(settingsDest, renderStarterSettings(toBranding));
-      }
-      addWritten('.claude/settings.json');
-      summary.settings = true;
-      summary.notes.push(`.claude/settings.json written from the starter — ${STARTER_COMMANDS.length} blessed command(s) for each of ${STARTER_SHELL_TOOLS.join(' + ')}, permissions only.`);
-      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (starter: ${STARTER_COMMANDS.length} blessed commands × ${STARTER_SHELL_TOOLS.length} shell tools, no hooks)`);
-    }
-  }
-
-  // 3. hooks — topology; copied WITH an identity rebrand (their .js internals carried
-  //    the founder origin/config-dir). Their core require()s self-resolve at runtime via
-  //    the copied _core-resolve.js sibling (task 2139) — no path rewriting needed here.
-  const hooksRes = copyTreeTransformed(path.join(srcClaude, 'hooks'), path.join(destClaude, 'hooks'), {
-    dryRun, overwrite, transform: rebrand, textExt: HOOK_TEXT_EXT, onFile: recordUnder('.claude/hooks'),
-  });
-  summary.hooks = hooksRes.files;
-  for (const rel of hooksRes.skipped || []) summary.skippedFiles.push(`hooks/${rel}`);
-  if (!hooksRes.present) {
-    summary.notes.push('.claude/hooks not present at the core root (topology, excluded from the package) — provide them from a starter.');
-  } else {
-    log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${hooksRes.files} hook file(s) → .claude/hooks/ (founder identity rebranded)${left((hooksRes.skipped || []).length)}`);
-    summary.notes.push('hooks: founder origin/config-dir rebranded to this instance; their internal `require(scripts/gds/…)` paths self-resolve inside the package at runtime via the copied _core-resolve.js sibling (task 2139).');
-  }
-
-  // 3b. scheduled-tasks — the cron routines (System 4 dispatcher, ADR 0078; task 2138). TOPOLOGY
-  //     like hooks (NOT in the package — PROTECTED_TOPOLOGY_EXCLUDE), so materialized by copy when
-  //     present at the core root and a no-op-with-note in a package-only install. Bodies (.md) are
-  //     bongosified so a judgment routine's `node scripts/gds/x.js` model-instructions become
-  //     `bongos exec …`; the deterministic routines' `.claude/scheduled-tasks/<x>.js` step commands
-  //     are NOT matched by bongosify and stay as-is. Companion .js are rebranded but keep their
-  //     paths: they resolve core require()s at runtime via the copied _core-resolve.js sibling
-  //     (task 2139), and run-routine.js finds the routines under resolveInstanceRoot() post-split.
-  const routinesRes = copyTreeTransformed(path.join(srcClaude, 'scheduled-tasks'), path.join(destClaude, 'scheduled-tasks'), {
-    dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), textExt: HOOK_TEXT_EXT, onFile: recordUnder('.claude/scheduled-tasks'),
-  });
-  summary.scheduledTasks = routinesRes.files;
-  for (const rel of routinesRes.skipped || []) summary.skippedFiles.push(`scheduled-tasks/${rel}`);
-  if (!routinesRes.present) {
-    summary.notes.push('.claude/scheduled-tasks not present at the core root (topology, excluded from the package) — provide them from a starter.');
-  } else {
-    log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${routinesRes.files} scheduled-task file(s) → .claude/scheduled-tasks/ (bodies→bongos, founder identity rebranded)${left((routinesRes.skipped || []).length)}`);
-    summary.notes.push('scheduled-tasks: cron routines materialized; run-routine.js resolves them under resolveInstanceRoot() and their companion .js resolve core via the copied _core-resolve.js sibling (task 2138).');
-  }
-
-  // 4. CLAUDE.md — the project-root framing an agent reads every session (task 2104).
-  //    Written from the neutral starter template, brand-substituted from THIS instance's
-  //    branding. Written only when ABSENT — never clobber a CLAUDE.md the instance has
-  //    grown (safe for init, adopt, and upgrade alike; the self-copy guard above already
-  //    keeps this from ever touching the core/OTB checkout's own CLAUDE.md).
-  //    One narrow exception (task 1004621): the starter's OWN sentences that told the assistant to
-  //    type a bare `bongos …` — not on PATH in a project — are swapped for their `npx bongos …` form
-  //    where they still read exactly as the starter wrote them (refreshStarterCliLines). Not in
-  //    adopt mode, which never touches what the owner already had.
-  const claudeMdPath = path.join(instanceDir, 'CLAUDE.md');
-  if (fs.existsSync(claudeMdPath)) {
-    let refreshed = { changed: 0 };
-    if (overwrite) {
-      try { refreshed = refreshStarterCliLines(fs.readFileSync(claudeMdPath, 'utf8')); } catch { /* unreadable: leave it, as before */ }
-    }
-    if (refreshed.changed) {
-      if (!dryRun) fs.writeFileSync(claudeMdPath, refreshed.text);
-      // Real run only, like the settings top-up: it preserves content, so the upgrade pre-flight's
-      // "materialize overwrites this anyway" waiver must not cover an owner's uncommitted edit.
-      if (!dryRun) addWritten('CLAUDE.md');
-      summary.claudeMdCliLines = refreshed.changed;
-      summary.notes.push(`CLAUDE.md kept as the instance's own, except ${refreshed.changed} unedited starter sentence(s) now say \`npx bongos …\` — the CLI is not on PATH in a project, so a bare \`bongos\` failed with command not found.`);
-      log(`  ${dryRun ? '[dry-run] would update' : '✓ updated'} ${refreshed.changed} unedited starter sentence(s) in CLAUDE.md to \`npx bongos …\` (everything else untouched)`);
-    } else {
-      summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
-    }
-  } else {
-    if (!dryRun) {
-      fs.mkdirSync(instanceDir, { recursive: true });
-      fs.writeFileSync(claudeMdPath, renderInstanceClaudeMd(toBranding));
-    }
-    addWritten('CLAUDE.md');
-    summary.claudeMd = true;
-    log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} CLAUDE.md (starter, brand-substituted for this instance)`);
-  }
-  return summary;
-}
-
-// materializeWillRewrite — the instance-relative paths a materialize WOULD rewrite here, changing
-// nothing. `bongos upgrade` asks before it starts, to decide which dirty paths its clean-tree
-// pre-flight may waive.
-//
-// THE WEDGE THIS EXISTS FOR (task 1004122). The upgrade's materialize step rewrites `.claude/`
-// from the new core on EVERY bump, so after an upgrade that did not commit it — one from before
-// task 1003957, or any run without --commit-pin — the instance carries ~40 modified
-// `.claude/skills/*` files that nobody edited. upgrade.js's clean-tree pre-flight then read them
-// as a human's uncommitted work and refused, so the instance took exactly one upgrade and stuck:
-// `test4` (instance 11) failed its Deploy-page upgrade this way, and provision-core-upgrade.js
-// passes --commit-pin but NOT --force, so the button stayed dead until someone committed by hand.
-//
-// Asking materializeClaude what it WOULD write is a real provenance answer, not a path
-// allow-list: the set is derived from the core actually installed here, and every path in it
-// is one the materialize step overwrites unconditionally a few seconds later. Whatever those files hold right
-// now is discarded either way, so refusing on them protects nothing and stops every future
-// update. A path materialize would NOT touch — an owner's own skill, a dirty migration, a
-// half-finished edit — is absent from the set and still halts the bump, which is the whole
-// safety property. Under --commit-pin the same paths come back from that step as persistPin's
-// artifactPaths and are committed, so the tree ends clean and the next upgrade needs none of this.
-//
-// Probed against the core on disk NOW, not the target: the target is not installed yet, and the
-// two ship the same `.claude/` surface. Fail-soft — a materialize that throws (no core
-// installed, an unreadable tree) returns nothing and the pre-flight is as strict as it ever was.
-function materializeWillRewrite({ instanceDir, coreRoot, materialize = materializeClaude }, err = console.error) {
-  try {
-    const root = coreRoot || path.join(instanceDir, 'node_modules', CORE_PACKAGE_NAMES[0]);
-    const sum = materialize({ coreRoot: root, instanceDir, dryRun: true, log: () => {} });
-    return (sum && Array.isArray(sum.writtenPaths)) ? sum.writtenPaths : [];
-  } catch (e) {
-    err(`  ! could not preview the .claude/ materialization (${e && e.message ? e.message : e}) — pre-flight will treat every dirty path as a human's work.`);
-    return [];
-  }
-}
-
-// ---- the dev checkout: module-owned skills materialised INTO the core (task 1003330, ADR 0224) ----
-// materializeClaude's self-copy guard is right for init/upgrade (instance == core is a no-op),
-// but Claude Code discovers only .claude/skills/ at the project root, so a builder working IN
-// the core checkout never sees modules/<key>/skills/. This lands every ENABLED module's skills
-// there as UNTRACKED, self-ignored dirs: verbatim copies (no bongosify — the checkout runs
-// `node scripts/gds/…`), a generated .claude/skills/.module-skills.json manifest naming what
-// was materialised and from where, and a generated .claude/skills/.gitignore covering the
-// manifest, itself and every materialised dir, so `git status` shows nothing new and nothing
-// can be committed by accident. The same vendoredSkillGate + SKILL_NAME_RE apply; a name the
-// core's own tracked .claude/skills/ carries is left to the core. Idempotent: every run first
-// removes what the last manifest named (so a skill a module stopped declaring does not
-// linger), then lands the current set; `clean` stops after the removal.
-// Is `root` the core CHECKOUT — a workbench a builder edits — rather than the core
-// package installed under a scaffolded instance's node_modules? Only a checkout's own
-// .claude/skills/ is the directory Claude Code reads for that project, so only there
-// does materialising the module-owned skills put them in front of anyone; an instance
-// already received them at ITS root from `bongos init`, and a second copy under
-// node_modules/@bongos/core would be invisible (task 1003486). Fail-soft by
-// construction: an unreadable package.json answers "not the core checkout", which is
-// the conservative no-op rather than a copy into a tree we could not identify.
-function isCoreCheckoutRoot(root) {
-  try {
-    const abs = path.resolve(root);
-    if (abs.split(/[\\/]+/).includes('node_modules')) return false;
-    return isCorePackageName(JSON.parse(fs.readFileSync(path.join(abs, 'package.json'), 'utf8')).name);
-  } catch (_) {
-    return false;
-  }
-}
-
-const MODULE_SKILLS_MANIFEST = '.module-skills.json';
-// The INSTANCE-side provenance record, deliberately a DIFFERENT filename from the
-// core's (task 1003632). They are different artifacts: MODULE_SKILLS_MANIFEST lists
-// the untracked copies materializeModuleSkillsIntoCore made inside a core CHECKOUT,
-// and is asserted never to travel to an instance; this one lists what materializeClaude
-// landed INTO an instance, and is what step 1c withdraws against. Sharing one name made
-// the instance's own record look like a core dotfile that had leaked across the boundary.
-const INSTANCE_SKILLS_MANIFEST = '.instance-skills.json';
-function readSkillsManifest(skillsDir, file) {
-  const m = readJsonSafe(path.join(skillsDir, file));
-  return m && m.skills && typeof m.skills === 'object' ? m : { skills: {} };
-}
-function readModuleSkillsManifest(skillsDir) {
-  return readSkillsManifest(skillsDir, MODULE_SKILLS_MANIFEST);
-}
-function readInstanceSkillsManifest(skillsDir) {
-  return readSkillsManifest(skillsDir, INSTANCE_SKILLS_MANIFEST);
-}
-function materializeModuleSkillsIntoCore({ coreRoot, dryRun = false, clean = false, log = () => {} }) {
-  const skillsDir = path.join(coreRoot, '.claude', 'skills');
-  const summary = { materialized: [], removed: [], refused: [], excluded: [], keptCore: [], files: 0, notes: [] };
-  const previous = readModuleSkillsManifest(skillsDir);
-  // A dir git tracks is the core's, whatever an older manifest said (a core skill can take
-  // over a name a module once owned); it is never removed or overwritten here.
-  const tracked = (name) => { try { return spawnSync('git', ['-C', coreRoot, 'ls-files', '--error-unmatch', '--', `.claude/skills/${name}`], { encoding: 'utf8' }).status === 0; } catch { return false; } };
-  for (const name of Object.keys(previous.skills)) {
-    const dir = path.join(skillsDir, name);
-    if (!SKILL_NAME_RE.test(name) || !fs.existsSync(dir)) continue;
-    if (tracked(name)) { summary.keptCore.push(name); summary.notes.push(`"${name}" is tracked by git now — the last manifest's copy was not removed; the core's dir is kept.`); continue; }
-    if (!dryRun) fs.rmSync(dir, { recursive: true, force: true });
-    summary.removed.push(name);
-  }
-  if (clean) {
-    for (const f of [MODULE_SKILLS_MANIFEST, '.gitignore']) { const p = path.join(skillsDir, f); if (fs.existsSync(p) && !dryRun) fs.rmSync(p); }
-    log(`  ${dryRun ? '[dry-run] would remove' : '✓ removed'} ${summary.removed.length} materialised module skill dir(s), the manifest and .claude/skills/.gitignore`);
-    return summary;
-  }
-  const roster = moduleSkillRoster({ coreRoot, instanceDir: coreRoot });
-  const sources = moduleSkillSources({ roster });
-  for (const r of sources.refused) { summary.refused.push(`${r.name} (${r.module}): ${r.reason}`); log(`  ✗ refused module skill "${r.name}" (${r.module}): ${r.reason}`); }
-  const manifest = { _doc: 'GENERATED by `node scripts/gds/claude-materialize.js --module-skills-only` (task 1003330, ADR 0224): the module-owned skills materialised into this core checkout as UNTRACKED copies so Claude Code sees them here. Every dir named below is ignored by the sibling .gitignore and removed by --clean; edit the module\'s skills/<name>/ source, never these copies, and re-run to refresh.', skills: {} };
-  for (const s of sources) {
-    if (!s.enabled) { summary.excluded.push(s.name); continue; }
-    const dest = path.join(skillsDir, s.name);
-    if (fs.existsSync(dest) && (!Object.prototype.hasOwnProperty.call(previous.skills, s.name) || tracked(s.name))) {
-      summary.keptCore.push(s.name);
-      summary.notes.push(`"${s.name}" (${s.module}) already exists under .claude/skills/ and is not a materialised copy — the core's own dir is kept.`);
-      continue;
-    }
-    const r = copyTreeTransformed(s.dir, dest, { dryRun, overwrite: true, transform: (t) => t });
-    summary.files += r.files;
-    summary.materialized.push(s.name);
-    manifest.skills[s.name] = { module: s.module, source: path.relative(coreRoot, s.dir).split(path.sep).join('/'), vendored: s.vendored, files: r.files };
-  }
-  const names = Object.keys(manifest.skills).sort();
-  manifest.skills = Object.fromEntries(names.map((n) => [n, manifest.skills[n]]));
-  const ignore = ['# GENERATED by scripts/gds/claude-materialize.js --module-skills-only (task 1003330): the module-owned skills', '# materialised into this checkout are untracked copies; this file and the manifest ignore themselves. Never commit these.', '/.gitignore', `/${MODULE_SKILLS_MANIFEST}`, ...names.map((n) => `/${n}/`)].join('\n') + '\n';
-  if (!dryRun) {
-    fs.mkdirSync(skillsDir, { recursive: true });
-    fs.writeFileSync(path.join(skillsDir, MODULE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
-    fs.writeFileSync(path.join(skillsDir, '.gitignore'), ignore);
-  }
-  log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${summary.materialized.length} module-owned skill(s) (${summary.files} file(s)) → .claude/skills/ as untracked copies: ${names.join(', ') || 'none'}`);
-  return summary;
-}
-
-// The CLI entry is the dev-checkout path only; init/upgrade call materializeClaude directly.
-if (require.main === module) {
-  const argv = process.argv.slice(2);
-  if (!argv.includes('--module-skills-only') || argv.includes('--help')) {
-    process.stderr.write('usage: node scripts/gds/claude-materialize.js --module-skills-only [--dry-run] [--clean]\n  Lands every enabled module\'s skills (modules/<key>/skills/<name>/) into THIS checkout\'s .claude/skills/ as untracked,\n  self-ignored copies so Claude Code sees them here (task 1003330). --clean removes them. The library behind bongos init / upgrade otherwise.\n');
-    process.exit(argv.includes('--help') ? 0 : 2);
-  }
-  const s = materializeModuleSkillsIntoCore({ coreRoot: path.resolve(__dirname, '..', '..'), dryRun: argv.includes('--dry-run'), clean: argv.includes('--clean'), log: (l) => process.stdout.write(l + '\n') });
-  for (const n of s.notes) process.stdout.write(`  • ${n}\n`);
-  process.stdout.write(`module skills → .claude/skills/: ${s.materialized.length} materialised (${s.files} file(s)), ${s.removed.length} refreshed or removed, ${s.excluded.length} excluded (module off), ${s.keptCore.length} kept as the core's own, ${s.refused.length} refused\n`);
-  process.exit(s.refused.length ? 1 : 0);
-}
-
-module.exports = { skillDescription, descriptionDigest, isRetiredCoreCopy, readRetiredCoreSkills, RETIRED_CORE_SKILLS_FILE, scriptToVerb, bongosify, PROJECT_CLI, topUpNpxAllowTwins, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+require('../bongos/forwarder.js').forward(module, 'claude-materialize.js');