@hegemonart/get-design-done 1.46.0 → 1.47.0

package/scripts/lib/live/harness-mode.cjs

@@ -0,0 +1,93 @@
+'use strict';
+/**
+ * scripts/lib/live/harness-mode.cjs — Phase 47 (Live Mode) capability gate.
+ *
+ * `/gdd:live` drives the Claude Preview MCP at runtime (preview_inspect /
+ * preview_click / preview_eval / preview_screenshot). That whole loop is only
+ * available on a harness whose capability matrix reports `mcp_support: true`.
+ * Harnesses without MCP support cannot inject the runtime or read picks back, so
+ * live mode degrades to a screenshot-only experience on them.
+ *
+ * This module is the single source of truth for that gate. It reads the canonical
+ * harness record (scripts/lib/manifest/harnesses.cjs, a typed re-export of
+ * harnesses.json) and projects each harness onto one of two live-mode strings:
+ *
+ *   'puppeteer' — full live mode: the harness has mcp_support, the skill probes
+ *                 Preview, injects scripts/lib/live/runtime.cjs, and hot-swaps
+ *                 variants in place. (Named for the Preview MCP's Playwright /
+ *                 puppeteer-class browser driver, not a bundled dependency: there
+ *                 is NO bundled puppeteer; the skill drives the MCP.)
+ *   'degraded'  — screenshot-only: no mcp_support, so no live injection. The skill
+ *                 falls back to generating variants and capturing static
+ *                 screenshots, and says so up front.
+ *
+ * Design constraints (mirror the other scripts/lib/live/* modules):
+ *   - Pure, dependency-free apart from the manifest re-export. No fs, no network,
+ *     no Date / Math.random. Cross-platform (no path work, no OS calls).
+ *   - The harness list is injectable so tests can pass a fixture; it defaults to
+ *     the real manifest.
+ *
+ * Exports:
+ *   - liveModeFor(harnessId, harnesses?) -> 'puppeteer' | 'degraded'
+ *   - degradedHarnesses(harnesses?)      -> string[] of ids in degraded mode
+ *   - isMcpSupported(harnessId, harnesses?) -> boolean
+ *   - MODE_FULL / MODE_DEGRADED          -> the two mode string constants
+ */
+
+const MODE_FULL = 'puppeteer';
+const MODE_DEGRADED = 'degraded';
+
+/** Lazily resolve the default harness list (the typed re-export of harnesses.json). */
+function defaultHarnesses() {
+  return require('../manifest/harnesses.cjs');
+}
+
+/** Find a harness record by id in a list. Returns undefined when absent. */
+function findHarness(harnessId, harnesses) {
+  const list = Array.isArray(harnesses) ? harnesses : defaultHarnesses();
+  return list.find((h) => h && h.id === harnessId);
+}
+
+/**
+ * True when the named harness reports `capability_matrix.mcp_support === true`.
+ * Unknown harness ids and harnesses missing the flag are treated as false (no
+ * MCP -> no live injection).
+ */
+function isMcpSupported(harnessId, harnesses) {
+  const h = findHarness(harnessId, harnesses);
+  return Boolean(h && h.capability_matrix && h.capability_matrix.mcp_support === true);
+}
+
+/**
+ * Live mode for a harness: 'puppeteer' when mcp_support is true, else 'degraded'.
+ * An unknown harness id degrades (fail safe to screenshot-only).
+ *
+ * @param {string} harnessId
+ * @param {Array=} harnesses  Optional injected list; defaults to the manifest.
+ * @returns {'puppeteer'|'degraded'}
+ */
+function liveModeFor(harnessId, harnesses) {
+  return isMcpSupported(harnessId, harnesses) ? MODE_FULL : MODE_DEGRADED;
+}
+
+/**
+ * The ids of every harness currently in degraded (screenshot-only) live mode,
+ * in manifest order.
+ *
+ * @param {Array=} harnesses  Optional injected list; defaults to the manifest.
+ * @returns {string[]}
+ */
+function degradedHarnesses(harnesses) {
+  const list = Array.isArray(harnesses) ? harnesses : defaultHarnesses();
+  return list
+    .filter((h) => h && h.id && !isMcpSupported(h.id, list))
+    .map((h) => h.id);
+}
+
+module.exports = {
+  liveModeFor,
+  degradedHarnesses,
+  isMcpSupported,
+  MODE_FULL,
+  MODE_DEGRADED,
+};

package/scripts/lib/live/postcheck.cjs

@@ -0,0 +1,158 @@
+'use strict';
+/**
+ * scripts/lib/live/postcheck.cjs — Phase 47 (Live Mode) variant post-check.
+ *
+ * After /gdd:live generates a design variant, we run that variant's source through the
+ * in-repo gdd-detect engine (Phase 41) and surface its anti-pattern findings on the
+ * variant card. Per the Live Mode spec, an `error`-severity finding is FLAGGED but NOT
+ * auto-rejected — the human still chooses; the detector is advisory at dev-time. So
+ * `autoReject` is ALWAYS false; we only surface counts + a compact card summary.
+ *
+ * Pure, dependency-free CommonJS. We reuse the detect engine's `scanContent` +`RULES`
+ * (NOT a CLI shell-out, NOT a temp-file write) so post-checking a generated variant is
+ * fully in-memory and hermetically testable. The engine is the single source of truth
+ * for the finding shape ({ruleId, category, name, severity, file, line, column, match,
+ * references}); we never reimplement rule matching.
+ *
+ * Ships in the npm package (scripts/lib/** is in package.json `files`), so it requires
+ * only the in-repo detect engine — no runtime dependency, no network, no optional dep.
+ */
+
+const path = require('node:path');
+const { scanContent, run, RULES } = require('../detect/engine.cjs');
+
+/**
+ * Normalize the caller's `files`/`content` input into a list of
+ * `{ path, content, ext }` units to scan in-memory.
+ *
+ * Accepts either:
+ *   - `content`: a raw string (single anonymous unit), or
+ *   - `files`: an array of `{ path, content }` (or `{ name, content }`) units, or
+ *              an object map of `{ "<path>": "<content>" }`.
+ *
+ * @param {{files?: any, content?: string}} input
+ * @returns {{path: string, content: string, ext: string}[]}
+ */
+function normalizeUnits(input) {
+  const units = [];
+  if (input && typeof input.content === 'string') {
+    const p = input.path || input.file || 'variant';
+    units.push({ path: p, content: input.content, ext: path.extname(p).toLowerCase() });
+  }
+  const files = input && input.files;
+  if (Array.isArray(files)) {
+    for (const f of files) {
+      if (!f) continue;
+      if (typeof f === 'string') continue; // a bare path with no content is not scannable in-memory
+      const p = f.path || f.name || f.file || 'variant';
+      const content = typeof f.content === 'string' ? f.content : '';
+      units.push({ path: p, content, ext: path.extname(p).toLowerCase() });
+    }
+  } else if (files && typeof files === 'object') {
+    for (const p of Object.keys(files)) {
+      const content = typeof files[p] === 'string' ? files[p] : '';
+      units.push({ path: p, content, ext: path.extname(p).toLowerCase() });
+    }
+  }
+  return units;
+}
+
+/**
+ * Post-check a generated variant against the gdd-detect anti-pattern rule set.
+ *
+ * Prefers an in-memory scan of the supplied variant source via the detect engine's
+ * `scanContent`. When NO inline content is supplied but a `projectRoot` is given,
+ * falls back to the documented programmatic engine form `run(projectRoot)` so the
+ * caller can still post-check files already written to disk.
+ *
+ * @param {object} args
+ * @param {string} [args.projectRoot]  Repo root — used for the on-disk fallback and as the
+ *                                      `cwd` so finding `file` paths are repo-relative.
+ * @param {Array|object} [args.files]  Variant files: `[{path, content}]` or `{ "<path>": "<content>" }`.
+ * @param {string} [args.content]      A single raw variant source string.
+ * @returns {{findings: object[], errorCount: number, warnCount: number, autoReject: boolean}}
+ */
+function postCheckVariant(args = {}) {
+  const { projectRoot } = args;
+  const units = normalizeUnits(args);
+
+  let findings = [];
+  if (units.length > 0) {
+    const cwd = projectRoot || process.cwd();
+    for (const u of units) {
+      // Make the reported `file` repo-relative when projectRoot is known, mirroring the
+      // engine's own relativization in run().
+      let rel = u.path;
+      if (projectRoot && path.isAbsolute(u.path)) {
+        rel = path.relative(cwd, u.path).split(path.sep).join('/') || u.path;
+      }
+      const hits = scanContent(u.content, { path: rel, ext: u.ext }, RULES);
+      findings.push(...hits);
+    }
+    // Match the engine's deterministic ordering (file, line, column, ruleId).
+    findings.sort(
+      (a, b) =>
+        a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        a.column - b.column ||
+        a.ruleId.localeCompare(b.ruleId),
+    );
+  } else if (projectRoot) {
+    // No inline content — fall back to the documented programmatic engine form against
+    // files already on disk under projectRoot.
+    const result = run(projectRoot, { cwd: projectRoot });
+    findings = result.findings;
+  }
+
+  let errorCount = 0;
+  let warnCount = 0;
+  for (const f of findings) {
+    if (f.severity === 'error') errorCount += 1;
+    else warnCount += 1;
+  }
+
+  // Spec D: error-severity is flagged, NOT auto-rejected. autoReject is always false.
+  return { findings, errorCount, warnCount, autoReject: false };
+}
+
+/**
+ * Compact, single-line summary of a findings array for a variant card.
+ * Always returns a string (never null/undefined) so the skill can render it verbatim.
+ *
+ *   []                                  → "clean — no anti-patterns"
+ *   [1 error, 2 warn]                   → "2 issue(s): 1 error, 2 warn — BAN-06, BAN-01, BAN-08"
+ *
+ * Rule ids are de-duplicated and listed in first-seen order, capped so the card stays compact.
+ *
+ * @param {object[]} findings
+ * @returns {string}
+ */
+function summarizeForCard(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  if (list.length === 0) return 'clean — no anti-patterns';
+
+  let errors = 0;
+  let warns = 0;
+  const ids = [];
+  const seen = new Set();
+  for (const f of list) {
+    if (f && f.severity === 'error') errors += 1;
+    else warns += 1;
+    const id = f && f.ruleId;
+    if (id && !seen.has(id)) {
+      seen.add(id);
+      ids.push(id);
+    }
+  }
+
+  const MAX_IDS = 5;
+  const shownIds = ids.slice(0, MAX_IDS);
+  const idTail = ids.length > MAX_IDS ? `, +${ids.length - MAX_IDS} more` : '';
+  const parts = [];
+  if (errors) parts.push(`${errors} error`);
+  if (warns) parts.push(`${warns} warn`);
+
+  return `${list.length} issue(s): ${parts.join(', ')} — ${shownIds.join(', ')}${idTail}`;
+}
+
+module.exports = { postCheckVariant, summarizeForCard, normalizeUnits };

package/scripts/lib/live/runtime.cjs

@@ -0,0 +1,233 @@
+'use strict';
+/**
+ * scripts/lib/live/runtime.cjs — Phase 47 (Live Mode) browser-side runtime.
+ *
+ * The `/gdd:live` skill injects a small browser runtime into the running dev
+ * server via the Claude Preview MCP `preview_eval` tool. That runtime does two
+ * jobs:
+ *
+ *   1. PICK — install a one-shot click handler that captures the element the
+ *      user clicks and reports `{selector, computedStyle subset, boundingRect,
+ *      tagName, classList}` back to the agent (the live_pick payload).
+ *   2. SWAP — apply one of the N generated design variants in-place by setting a
+ *      `data-gdd-variant="N"` attribute on the picked element and applying that
+ *      variant's inline style / markup, and read back which variant is live.
+ *
+ * Why a string and not a real module: `preview_eval` ships a JS source string to
+ * the page and evaluates it there. There is no bundler in the loop, so the
+ * runtime is authored here as a plain template string (`RUNTIME_JS`) and injected
+ * verbatim. The IIFE is idempotent: re-injecting it rebinds the same singleton on
+ * `window.__gddLive` rather than stacking duplicate listeners.
+ *
+ * Design constraints (mirror the other scripts/lib/live/* modules):
+ *   - Pure, dependency-free CommonJS. No `fs`, no network, no Date.now() at the
+ *     module top level. `buildSelector` is a pure function of its input.
+ *   - Cross-platform: this file is plain JS text; nothing here touches the OS.
+ *   - Ships in the npm package (scripts/lib/ is in package.json `files`), so it
+ *     stays runtime-safe (no dev-only requires).
+ *
+ * Exports:
+ *   - RUNTIME_JS      the browser IIFE source string injected via preview_eval.
+ *   - pickReportShape a plain object documenting the live_pick payload fields.
+ *   - buildSelector   pure helper a test can assert against (id > data-attr >
+ *                     nth-of-type class path), shared with the in-page logic.
+ *   - DATA_ATTR       the variant marker attribute name ("data-gdd-variant").
+ *   - GLOBAL_KEY      the window singleton key ("__gddLive").
+ */
+
+/** The attribute the runtime stamps on the picked element to mark the live variant. */
+const DATA_ATTR = 'data-gdd-variant';
+
+/** The window-singleton key the IIFE installs itself under (idempotent re-inject). */
+const GLOBAL_KEY = '__gddLive';
+
+/**
+ * Shape of the payload the runtime reports for a pick. Documented here so the
+ * skill and the tests agree on the contract without parsing RUNTIME_JS. Values
+ * are field descriptions, not live data.
+ */
+const pickReportShape = {
+  selector: 'string — a stable CSS selector for the picked element (see buildSelector)',
+  tagName: 'string — lowercased tag name, e.g. "button"',
+  classList: 'string[] — the element classList as an array',
+  boundingRect: 'object — {x, y, width, height, top, right, bottom, left} from getBoundingClientRect',
+  computedStyle:
+    'object — a curated subset of getComputedStyle: color, backgroundColor, fontSize, ' +
+    'fontWeight, fontFamily, lineHeight, padding, margin, borderRadius, borderColor, ' +
+    'borderWidth, display, boxShadow',
+  variant: 'number|null — the current data-gdd-variant value on the element, or null',
+};
+
+/**
+ * Pure selector strategy, shared with the in-page runtime by being inlined into
+ * RUNTIME_JS below. Strategy, most-specific first:
+ *   1. `#id`                        when the element has an id.
+ *   2. `[data-testid="..."]`        when a stable data-testid / data-test is present.
+ *   3. `tag.class1.class2:nth-of-type(k)` — tag + (up to 2) classes + structural
+ *      nth-of-type index among same-tag siblings, for everything else.
+ *
+ * @param {{id?:string, dataTestId?:string, tagName?:string, classList?:string[], nthOfType?:number}} elInfo
+ * @returns {string}
+ */
+function buildSelector(elInfo) {
+  const info = elInfo || {};
+  if (info.id) return `#${info.id}`;
+  if (info.dataTestId) return `[data-testid="${info.dataTestId}"]`;
+  const tag = (info.tagName || 'div').toLowerCase();
+  const classes = Array.isArray(info.classList) ? info.classList.filter(Boolean).slice(0, 2) : [];
+  const classPart = classes.length ? '.' + classes.join('.') : '';
+  const nth = Number.isInteger(info.nthOfType) && info.nthOfType > 0 ? `:nth-of-type(${info.nthOfType})` : '';
+  return `${tag}${classPart}${nth}`;
+}
+
+/**
+ * The browser-side runtime, authored as a plain string. Injected verbatim by the
+ * skill via `preview_eval`. The in-page `buildSelector` mirrors the exported one
+ * above (kept in sync by the phase-47-runtime test asserting both prefer id over
+ * class). The IIFE is idempotent: it reuses window.__gddLive if already present.
+ */
+const RUNTIME_JS = `
+(function () {
+  var GLOBAL_KEY = ${JSON.stringify(GLOBAL_KEY)};
+  var DATA_ATTR = ${JSON.stringify(DATA_ATTR)};
+
+  // Idempotent: reuse the singleton on re-inject so listeners never stack.
+  if (window[GLOBAL_KEY] && window[GLOBAL_KEY].__installed) {
+    return window[GLOBAL_KEY];
+  }
+
+  // --- pure selector strategy (mirror of runtime.cjs buildSelector) ---
+  function buildSelector(el) {
+    if (!el || el.nodeType !== 1) return '';
+    if (el.id) return '#' + el.id;
+    var testId = el.getAttribute && (el.getAttribute('data-testid') || el.getAttribute('data-test'));
+    if (testId) return '[data-testid="' + testId + '"]';
+    var tag = (el.tagName || 'DIV').toLowerCase();
+    var classes = [];
+    if (el.classList && el.classList.length) {
+      for (var i = 0; i < el.classList.length && classes.length < 2; i++) classes.push(el.classList[i]);
+    }
+    var classPart = classes.length ? '.' + classes.join('.') : '';
+    var nth = '';
+    if (el.parentNode) {
+      var sameTag = [];
+      var sibs = el.parentNode.children || [];
+      for (var j = 0; j < sibs.length; j++) if (sibs[j].tagName === el.tagName) sameTag.push(sibs[j]);
+      if (sameTag.length > 1) {
+        var idx = sameTag.indexOf(el) + 1;
+        if (idx > 0) nth = ':nth-of-type(' + idx + ')';
+      }
+    }
+    return tag + classPart + nth;
+  }
+
+  // --- curated computed-style subset for the pick report ---
+  var STYLE_KEYS = [
+    'color', 'backgroundColor', 'fontSize', 'fontWeight', 'fontFamily', 'lineHeight',
+    'padding', 'margin', 'borderRadius', 'borderColor', 'borderWidth', 'display', 'boxShadow'
+  ];
+  function styleSubset(el) {
+    var out = {};
+    var cs = window.getComputedStyle ? window.getComputedStyle(el) : null;
+    if (!cs) return out;
+    for (var i = 0; i < STYLE_KEYS.length; i++) out[STYLE_KEYS[i]] = cs[STYLE_KEYS[i]];
+    return out;
+  }
+
+  function report(el) {
+    var r = el.getBoundingClientRect ? el.getBoundingClientRect() : {};
+    var classList = [];
+    if (el.classList) for (var i = 0; i < el.classList.length; i++) classList.push(el.classList[i]);
+    var v = el.getAttribute(DATA_ATTR);
+    return {
+      selector: buildSelector(el),
+      tagName: (el.tagName || '').toLowerCase(),
+      classList: classList,
+      boundingRect: {
+        x: r.x, y: r.y, width: r.width, height: r.height,
+        top: r.top, right: r.right, bottom: r.bottom, left: r.left
+      },
+      computedStyle: styleSubset(el),
+      variant: v == null ? null : Number(v)
+    };
+  }
+
+  var state = {
+    __installed: true,
+    picked: null,          // last picked element
+    lastReport: null,      // last pick report (read by the agent after a click)
+    originals: new WeakMap() // element -> {style, html} captured before first swap
+  };
+
+  // --- PICK: one-shot capture click handler ---
+  function onPick(ev) {
+    var el = ev.target;
+    if (!el || el.nodeType !== 1) return;
+    ev.preventDefault();
+    ev.stopPropagation();
+    state.picked = el;
+    state.lastReport = report(el);
+    document.removeEventListener('click', onPick, true);
+    state.picking = false;
+    return state.lastReport;
+  }
+  state.pick = function () {
+    state.picking = true;
+    document.addEventListener('click', onPick, true);
+    return true;
+  };
+  state.getLastPick = function () { return state.lastReport; };
+
+  // --- SWAP: apply / read a variant on the picked (or given) element ---
+  function captureOriginal(el) {
+    if (!state.originals.has(el)) {
+      state.originals.set(el, { style: el.getAttribute('style'), html: el.innerHTML });
+    }
+  }
+  // variant = {n:Number, style?:Object, html?:String}
+  state.swapVariant = function (variant, el) {
+    var target = el || state.picked;
+    if (!target || !variant) return null;
+    captureOriginal(target);
+    target.setAttribute(DATA_ATTR, String(variant.n));
+    if (variant.style && typeof variant.style === 'object') {
+      for (var k in variant.style) if (Object.prototype.hasOwnProperty.call(variant.style, k)) {
+        target.style[k] = variant.style[k];
+      }
+    }
+    if (typeof variant.html === 'string') target.innerHTML = variant.html;
+    return Number(target.getAttribute(DATA_ATTR));
+  };
+  state.currentVariant = function (el) {
+    var target = el || state.picked;
+    if (!target) return null;
+    var v = target.getAttribute(DATA_ATTR);
+    return v == null ? null : Number(v);
+  };
+  state.revert = function (el) {
+    var target = el || state.picked;
+    if (!target) return false;
+    var orig = state.originals.get(target);
+    if (orig) {
+      if (orig.style == null) target.removeAttribute('style'); else target.setAttribute('style', orig.style);
+      target.innerHTML = orig.html;
+    }
+    target.removeAttribute(DATA_ATTR);
+    return true;
+  };
+
+  // expose the pure helper for assertions / debugging
+  state.buildSelector = buildSelector;
+
+  window[GLOBAL_KEY] = state;
+  return state;
+})();
+`;
+
+module.exports = {
+  RUNTIME_JS,
+  pickReportShape,
+  buildSelector,
+  DATA_ATTR,
+  GLOBAL_KEY,
+};

package/scripts/lib/live/scope-guard.cjs

@@ -0,0 +1,145 @@
+'use strict';
+/**
+ * scripts/lib/live/scope-guard.cjs — Phase 47 (Live Mode) write-scope guard.
+ *
+ * `/gdd:live` lets the agent rewrite the source files behind a picked DOM
+ * element. To keep that powerful loop safe, EVERY write the live session makes
+ * must be inside an explicitly enumerated allow-set:
+ *
+ *   (a) the session's own bookkeeping: anything under `.design/live-sessions/`
+ *       and `.design/telemetry/` (relative to projectRoot), and
+ *   (b) the `implicated` source files — the concrete files the picked element
+ *       maps to (passed in by the caller from the element→source mapping).
+ *
+ * Anything else — a random repo file, a `package.json`, a `..` escape out of the
+ * project — is rejected. This is the runtime backstop for the same intent the
+ * Editor/Write protected-paths list expresses at author time.
+ *
+ * Resolution rules:
+ *   - All paths are resolved to absolute with path.resolve so `..` segments are
+ *     collapsed BEFORE comparison (a `../../etc/passwd` can never sneak past a
+ *     string-prefix check).
+ *   - Containment uses a normalized, separator-terminated prefix so that
+ *     `.design/live-sessions-evil/x` does NOT count as inside
+ *     `.design/live-sessions/` (sibling-directory false positive).
+ *   - On case-insensitive / Windows filesystems we still compare case-sensitive
+ *     prefixes after resolve; the implicated set is matched by exact resolved
+ *     path, which is the conservative choice (a guard that is too strict fails
+ *     closed, never open).
+ *
+ * Pure, dependency-free CommonJS (`path` only — no `fs`, no network, no clock).
+ * Cross-platform via path.resolve / path.join.
+ */
+
+const path = require('path');
+
+/** The two project-relative directory roots always writable by a live session. */
+const ALWAYS_ALLOWED_SUBDIRS = Object.freeze([
+  path.join('.design', 'live-sessions'),
+  path.join('.design', 'telemetry'),
+]);
+
+/**
+ * True when `child` is the same path as, or nested inside, `parentDir`.
+ * Both inputs must already be absolute + resolved. Uses a separator-terminated
+ * prefix so sibling dirs that share a name prefix are NOT treated as inside.
+ */
+function isWithin(parentDir, child) {
+  if (child === parentDir) return true;
+  const withSep = parentDir.endsWith(path.sep) ? parentDir : parentDir + path.sep;
+  return child.startsWith(withSep);
+}
+
+/**
+ * Normalize the allowed write-set for a live session into a flat, resolved
+ * structure the predicates can test against.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot           project root (required to anchor the always-allowed dirs)
+ * @param {Array<string>} [args.implicated]   source files the picked element maps to
+ * @returns {{ dirs: string[], files: Set<string> }}
+ *   `dirs` — resolved directory prefixes any descendant of which is allowed.
+ *   `files` — resolved exact file paths that are allowed.
+ */
+function enumerateScope(args = {}) {
+  const { projectRoot } = args;
+  if (!projectRoot) throw new TypeError('enumerateScope: projectRoot is required');
+  const root = path.resolve(projectRoot);
+
+  const dirs = ALWAYS_ALLOWED_SUBDIRS.map((rel) => path.resolve(root, rel));
+
+  const files = new Set();
+  const implicated = Array.isArray(args.implicated) ? args.implicated : [];
+  for (const f of implicated) {
+    if (f == null || !String(f).length) continue;
+    // Implicated paths may be absolute or relative-to-projectRoot; resolve both
+    // against the root so callers can pass either form.
+    files.add(path.resolve(root, String(f)));
+  }
+  return { dirs, files };
+}
+
+/**
+ * Whether `targetPath` is inside the enumerated scope.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.targetPath            the path about to be written
+ * @param {Array<string>} [args.implicated]   element→source files
+ * @returns {boolean}
+ */
+function isInScope(args = {}) {
+  const { projectRoot, targetPath } = args;
+  if (!projectRoot) throw new TypeError('isInScope: projectRoot is required');
+  if (targetPath == null || !String(targetPath).length) {
+    throw new TypeError('isInScope: targetPath is required');
+  }
+  const root = path.resolve(projectRoot);
+  const target = path.resolve(root, String(targetPath));
+  const { dirs, files } = enumerateScope({ projectRoot, implicated: args.implicated });
+
+  if (files.has(target)) return true;
+  for (const d of dirs) {
+    if (isWithin(d, target)) return true;
+  }
+  return false;
+}
+
+/**
+ * Throw unless `targetPath` is inside the enumerated scope. The error message
+ * enumerates the allowed set so a violation is diagnosable.
+ *
+ * @param {object} args  same shape as isInScope
+ * @returns {{ targetPath: string, resolved: string }} on success
+ */
+function assertInScope(args = {}) {
+  const { projectRoot, targetPath } = args;
+  if (!projectRoot) throw new TypeError('assertInScope: projectRoot is required');
+  if (targetPath == null || !String(targetPath).length) {
+    throw new TypeError('assertInScope: targetPath is required');
+  }
+  if (isInScope(args)) {
+    const root = path.resolve(projectRoot);
+    return { targetPath: String(targetPath), resolved: path.resolve(root, String(targetPath)) };
+  }
+  const root = path.resolve(projectRoot);
+  const resolved = path.resolve(root, String(targetPath));
+  const { dirs, files } = enumerateScope({ projectRoot, implicated: args.implicated });
+  const allowed = [
+    ...dirs.map((d) => `${d}${path.sep}* (always-allowed)`),
+    ...[...files].map((f) => `${f} (implicated)`),
+  ];
+  throw new Error(
+    `scope-guard: refusing to write "${resolved}" — outside the live-session write scope.\n` +
+      `Allowed:\n  ${allowed.length ? allowed.join('\n  ') : '(none)'}`,
+  );
+}
+
+module.exports = {
+  assertInScope,
+  isInScope,
+  enumerateScope,
+  // exported for callers + tests
+  isWithin,
+  ALWAYS_ALLOWED_SUBDIRS,
+};