claude-code-session-manager 0.97.0 → 0.100.0

package/src/main/lib/prdCreate.cjs

@@ -11,8 +11,8 @@
  * anymore — both just point the headless executor at STANDARDS_PATH with an
  * instruction to read it before starting. There's nothing to go stale: the
  * executor always reads the live file at run time, same one-concept-one-
- * implementation reasoning that keeps the two PRD-creation paths in sync
- * (see SKILL.md).
+ * implementation reasoning that keeps the two PRD-creation paths (admin
+ * HTTP route, chat:create-prd IPC) in sync.
  */
 'use strict';
 
@@ -32,6 +32,8 @@ const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
 const { isFixPlanSlug } = require('./fixPlanSlug.cjs');
 const { isIncomplete, resolveChainTerminals, isValidPlanId, mintPlanId, resolveInheritedPlanId } = require('./prdDisposition.cjs');
 const { sizingWarnings } = require('./prdSizing.cjs');
+const { validateGate, validateFiles, renderFilesSection, renderGateSection } = require('./prdGateFiles.cjs');
+const { resolveGate, parseChain, isNoneGate } = require('./definitionOfDone.cjs');
 
 // A caller-supplied slug that already starts with its own `NN-` (e.g.
 // "254-perf-x") used to silently become the double-prefixed row
@@ -68,18 +70,19 @@ function deriveSlugFromTitle(title) {
 
 /**
  * Build the full PRD markdown body (frontmatter + required sections + a
- * pointer at the engineering standards file), matching the structure
- * `/develop`'s SKILL.md documents: frontmatter, then Goal / Acceptance
- * criteria / Implementation notes / Out of scope / Engineering standards,
- * in order.
+ * pointer at the engineering standards file), matching the body shape
+ * PRD_AUTHORING.md §13 documents: frontmatter, then Goal / Acceptance
+ * criteria / Files / Implementation notes / Out of scope / Gate /
+ * Engineering standards, in order.
  */
 function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
     implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, agentType, dependsOn, quietMachine, disposition, deliverable, artifactPaths, planId,
+    gate, files,
   } = input;
 
-  // No `parallelGroup` frontmatter key by convention (SKILL.md) — the NN-
+  // No `parallelGroup` frontmatter key (PRD_AUTHORING.md §5) — the NN-
   // filename prefix is the single source of truth for grouping; adding a
   // second one here would let the two drift out of sync.
   const fmLines = ['---', `title: ${title}`, `cwd: ${cwd}`, `estimateMinutes: ${estimateMinutes}`];
@@ -140,13 +143,22 @@ function buildPrdBody(input) {
     'do not re-read the whole file every run.',
   ].join('\n');
 
+  // `# Files` sits right after Acceptance criteria; `# Gate` sits after Out
+  // of scope, before Engineering standards (gate-and-files-in-PRD-body unit).
+  // Each section appears only when its field is given. Only the MCP tool
+  // refuses a call without them; createPrd() (so the HTTP route and the IPC
+  // handler too) just warns when either is absent.
   const bodyLines = [
     '# Goal', '', goal, '',
     '# Acceptance criteria', '', acLines, '',
+  ];
+  if (files && files.length) bodyLines.push(...renderFilesSection(files));
+  bodyLines.push(
     '# Implementation notes', '', implementationNotes, '',
     '# Out of scope', '', oosLines, '',
-    '## Engineering standards', '', standardsPointer, '',
-  ];
+  );
+  if (gate && gate.length) bodyLines.push(...renderGateSection(gate));
+  bodyLines.push('## Engineering standards', '', standardsPointer, '');
 
   return `${fmLines.join('\n')}${bodyLines.join('\n')}`;
 }
@@ -347,6 +359,67 @@ async function createPrd(input, remote) {
     }
   }
 
+  // Fake-heading guard (gate-and-files-in-PRD-body unit): a caller-supplied
+  // free-text field that itself contains a "# Gate" or "# Files" heading line
+  // would, after buildPrdBody splices in the real section below, read as TWO
+  // Gate/Files sections — readExplicitGate takes the FIRST fence/heading it
+  // finds, so the fake one would silently win and the executor would see the
+  // wrong gate. Checked before NN allocation so a refusal burns no number.
+  const HEADING_LINE_RE = /^ {0,3}#{1,6}[ \t]+(gate|files)[ \t]*#*[ \t]*$/i;
+  function headingGuardError(fieldLabel, text) {
+    if (typeof text !== 'string') return null;
+    for (const line of text.split(/\r\n|\r|\n/)) {
+      if (HEADING_LINE_RE.test(line)) {
+        return `The ${fieldLabel} text has a "# Gate" or "# Files" heading. The API writes those sections ` +
+          'from the gate and files fields. Remove the heading and call again.';
+      }
+    }
+    return null;
+  }
+  for (const [fieldLabel, text] of [['goal', input.goal], ['implementation notes', input.implementationNotes]]) {
+    const headingError = headingGuardError(fieldLabel, text);
+    if (headingError) return { ok: false, status: 400, error: headingError };
+  }
+  if (Array.isArray(input.acceptanceCriteria)) {
+    for (const entry of input.acceptanceCriteria) {
+      const headingError = headingGuardError('acceptance criteria', entry);
+      if (headingError) return { ok: false, status: 400, error: headingError };
+    }
+  }
+  if (Array.isArray(input.outOfScope)) {
+    for (const entry of input.outOfScope) {
+      const headingError = headingGuardError('out of scope', entry);
+      if (headingError) return { ok: false, status: 400, error: headingError };
+    }
+  }
+
+  // Gate + files validation (gate-and-files-in-PRD-body unit): fail-closed,
+  // checked BEFORE NN allocation so a refusal burns no number — same posture
+  // as the artifactPaths checks above. The actual shape rules live in
+  // prdGateFiles.cjs (pure, no I/O); this is just the accumulate-and-return glue.
+  const extraWarnings = [];
+  let gateCommands;
+  if (input.gate !== undefined) {
+    const gateValidation = validateGate(input.gate);
+    if (!gateValidation.ok) {
+      return { ok: false, status: 400, error: gateValidation.error };
+    }
+    gateCommands = gateValidation.commands;
+    extraWarnings.push(...gateValidation.warnings);
+  } else {
+    extraWarnings.push('No gate: the scheduler cannot re-check this PRD.');
+  }
+  let filesList;
+  if (input.files !== undefined) {
+    const filesValidation = validateFiles(input.files);
+    if (!filesValidation.ok) {
+      return { ok: false, status: 400, error: filesValidation.error };
+    }
+    filesList = filesValidation.files;
+  } else {
+    extraWarnings.push('No files list: the executor is not told which files it may change.');
+  }
+
   const nn = await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;
 
@@ -463,7 +536,32 @@ async function createPrd(input, remote) {
   }
   if (!planId) planId = mintPlanId();
 
-  const body = buildPrdBody({ ...input, planId });
+  const body = buildPrdBody({ ...input, planId, gate: gateCommands, files: filesList });
+
+  // Read-back check (gate-and-files-in-PRD-body unit): the whole point of a
+  // declared gate is that the scheduler's own reader (resolveGate/parseChain
+  // in definitionOfDone.cjs) gets back exactly what was declared. A stray
+  // ```gate fence elsewhere in the body (goal/notes/criteria/out-of-scope)
+  // would otherwise win — readExplicitGate takes the FIRST fence in the
+  // text — and the scheduler would silently re-run the wrong gate. Caught
+  // here, before the write, rather than discovered later from a job log.
+  if (gateCommands) {
+    const expectedSource = gateCommands.length === 1 && isNoneGate(gateCommands[0]) ? 'none' : 'explicit';
+    const expectedSequence = expectedSource === 'none' ? [] : gateCommands.flatMap(parseChain);
+    const resolved = resolveGate(body);
+    const matches = resolved.source === expectedSource
+      && JSON.stringify(resolved.sequence) === JSON.stringify(expectedSequence);
+    if (!matches) {
+      return {
+        ok: false,
+        status: 400,
+        error: 'The PRD text already holds a gate fence (three backticks + gate), so the scheduler would read '
+          + 'the wrong gate. Remove it from the goal, implementation notes, acceptance criteria, out of scope '
+          + 'or files, and call again.',
+      };
+    }
+  }
+
   const writeResult = await remote.writePrd(filenameSlug, body, input.cwd);
   if (!writeResult?.ok) {
     return { ok: false, status: 500, error: writeResult?.error ?? 'write failed' };
@@ -480,25 +578,59 @@ async function createPrd(input, remote) {
     sourceTabId: input.sourceTabId ?? null,
   });
 
+  // PRD 1446: writePrd() succeeding used to just promise "the next scheduler
+  // reconcile pass (~1 minute)" adopts this file — but nothing reliably ran
+  // that pass (the 60s pollLoop only reaches reconcile() via
+  // maybeLaunchWhenAvailable, which returns early while zero rows are
+  // pending; the 10-minute rescheduleTimer could itself stall behind a slow
+  // billing fetch). Trigger one reconcile immediately through the EXISTING
+  // broadcast-coalescer seam (remote.requestReconcile(), same one resetJob
+  // already uses) instead of waiting on either. Best-effort: a reconcile
+  // failure here must not fail a write that already landed on disk — the
+  // PRD file is real regardless, and the next scheduled pass still adopts
+  // it if this one didn't stick.
+  let enqueued = false;
+  if (typeof remote.requestReconcile === 'function') {
+    try {
+      await remote.requestReconcile();
+      if (typeof remote.getJob === 'function') {
+        enqueued = Boolean(await remote.getJob(filenameSlug));
+      }
+    } catch (e) {
+      console.warn(`[prdCreate] immediate requestReconcile failed (non-fatal, next scheduled pass will adopt it): ${e?.message ?? e}`);
+    }
+  }
+
   // No `status` field here, and never one named 'queued' — that string was
   // handed straight to callers as if it were a real ScheduleJob status, and
   // is exactly how the 1021/1022 incident's invalid `"status": "queued"`
   // rows got onto disk (this route's own response was the most likely
   // source). A PRD is a queue row's SOURCE, not the row itself: writePrd
-  // only ever joins an Epic and writes the .md file — the queue row is
-  // created separately, by the next reconcile() pass. `enqueued: false` is
-  // true by construction (this function never touches queue.json), so no
-  // caller can copy a fake job status out of this response again.
+  // only ever joins an Epic and writes the .md file — the queue row above
+  // is created separately, by reconcile(). `enqueued` reflects whether that
+  // reconcile pass (triggered synchronously above) actually produced the
+  // row before this function returned — it is not a fabricated status.
   return {
     ok: true,
     nn,
     filename: `${filenameSlug}.md`,
     prdPath: writeResult.path ?? null,
     epicId: writeResult.epicId ?? null,
-    enqueued: false,
-    note: 'PRD file written; the queue row is derived by the next scheduler reconcile pass, not created here',
-    // Advisory only (PRD 1403) — never blocks the write. See prdSizing.cjs.
-    warnings: sizingWarnings(input),
+    enqueued,
+    note: enqueued
+      ? 'PRD file written and adopted into the queue as a pending row'
+      : 'PRD file written; the queue row is derived by the next scheduler reconcile pass, not created here',
+    // gate-and-files-in-PRD-body unit: honest echo of what was actually
+    // validated and rendered, same spirit as `note` above — never a fabricated status.
+    gate: {
+      source: gateCommands ? (gateCommands.length === 1 && isNoneGate(gateCommands[0]) ? 'none' : 'explicit') : 'absent',
+      commands: gateCommands || [],
+    },
+    files: filesList || [],
+    // Advisory only (PRD 1403 sizing warnings + gate-and-files-in-PRD-body
+    // absent/none-gate warnings) — never blocks the write. See prdSizing.cjs
+    // and prdGateFiles.cjs.
+    warnings: [...extraWarnings, ...sizingWarnings(input)],
   };
 }
 
@@ -542,8 +674,10 @@ function registerAdminRoute(adminHttp, remote) {
       filename: result.filename,
       prdPath: result.prdPath ?? null,
       epicId: result.epicId ?? null,
-      enqueued: false,
+      enqueued: result.enqueued,
       note: result.note,
+      gate: result.gate,
+      files: result.files,
       warnings: result.warnings,
     });
   });

package/src/main/lib/prdDisposition.cjs

@@ -18,7 +18,7 @@
  *     an already-written PRD's disposition from the Scheduler UI. Uses
  *     computeDispositionRewrite() to validate the rewrite is safe before
  *     handing the new dependsOn to remote.updatePrd (which itself refuses a
- *     non-pending/quarantined row — see scheduler.cjs's updatePrd).
+ *     'running' or 'completed' row — see scheduler.cjs's updatePrd).
  *
  * `rows` throughout is the same shape listPrdsInternal() already produces:
  * { slug, status, dependsOn }. dependsOn entries are resolved against `rows`
@@ -151,7 +151,7 @@ function wouldCreateCycle(rows, slug, newDependsOn) {
  * behind another chain" action). Pure — returns the new dependsOn value on
  * success; the caller (scheduler.cjs's IPC handler) is responsible for
  * actually persisting it via remote.updatePrd, which independently refuses
- * a non-pending/quarantined row (defense in depth, not duplicated here).
+ * a 'running' or 'completed' row (defense in depth, not duplicated here).
  *
  * Refuses (ok: false) when:
  *   - `slug` isn't a known row.

package/src/main/lib/prdGateFiles.cjs

@@ -0,0 +1,284 @@
+'use strict';
+
+/**
+ * prdGateFiles.cjs — pure validate + render helpers for a PRD's `gate` and
+ * `files` fields (gate-and-files-in-PRD-body unit).
+ *
+ * Why: 74% of parked jobs had no gate the scheduler could read. The planner
+ * now declares the gate commands and the files list when it calls
+ * scheduler_create_prd; prdCreate.cjs's createPrd() validates them with the
+ * functions here, then renders them as two PRD body sections (`# Files`,
+ * `# Gate`). `resolveGate`/`parseChain` in definitionOfDone.cjs already read
+ * a fenced ```gate block back — renderGateSection's output must round-trip
+ * through them unchanged (checked by createPrd(), not here).
+ *
+ * No I/O, no scheduler imports — pure string-in, string/array-out.
+ */
+
+const { parseChain, explainChain, isNoneGate } = require('./definitionOfDone.cjs');
+
+const GATE_MIN_ENTRIES = 1;
+const GATE_MAX_ENTRIES = 10;
+const GATE_ENTRY_MAX_CHARS = 500;
+const FILES_MIN_ENTRIES = 1;
+const FILES_MAX_ENTRIES = 50;
+const FILES_ENTRY_MAX_CHARS = 300;
+
+const NONE_GATE_WARNING =
+  'Gate is none: the scheduler cannot re-check this PRD. Use none only for docs or config with no runnable check.';
+
+// Same whitespace/control-char rule explainChain's rule 1 uses
+// (definitionOfDone.cjs), minus tab — a tab has no legitimate place in a
+// repo-relative file path.
+const FILES_FOREIGN_WHITESPACE_RE = /[^\S ]|[\u0000-\u0008\u000A-\u001F\u007F]/;
+
+// Chars stripped from a gate entry's first word before comparing it to
+// "none" — quotes, plus the punctuation a typo or trailing comment tends to
+// add (`none.`, `"none"`, `none!`).
+const NONE_PUNCT_STRIP_RE = /^[.,;:!?()[\]{}#'"]+|[.,;:!?()[\]{}#'"]+$/g;
+
+/** Cut a string to 80 chars for an error message, marking truncation with "…". */
+function cut80(s) {
+  return s.length > 80 ? `${s.slice(0, 80)}…` : s;
+}
+
+/** `<field> entry <n> ("<cut entry>"): <rule>` — the shared error-text shape. */
+function entryError(field, index, entry, rule) {
+  return `${field} entry ${index} ("${cut80(entry)}"): ${rule}`;
+}
+
+/**
+ * True when `entry` reads as a typo'd "none" opt-out (`none.`, `"none"`,
+ * `none # docs`, `NONE!`) but is not the exact opt-out itself. The exact
+ * opt-out (isNoneGate) is never a near-miss.
+ */
+function isNearMissNone(entry) {
+  if (isNoneGate(entry)) return false;
+  const firstWord = entry.split(/[ \t]+/)[0] ?? '';
+  return /^none$/i.test(firstWord.replace(NONE_PUNCT_STRIP_RE, ''));
+}
+
+/**
+ * Validate a PRD's `gate` field.
+ *
+ * @param {unknown} gate
+ * @returns {{ok:true, commands:string[], warnings:string[]}|{ok:false, error:string}}
+ *   commands is `['none']` for the opt-out, else the trimmed entries verbatim
+ *   (one command chain per entry) — the exact strings renderGateSection and
+ *   createPrd's read-back check both work from.
+ */
+function validateGate(gate) {
+  if (!Array.isArray(gate) || gate.length < GATE_MIN_ENTRIES || gate.length > GATE_MAX_ENTRIES) {
+    return {
+      ok: false,
+      error: `gate must have ${GATE_MIN_ENTRIES} to ${GATE_MAX_ENTRIES} entries (got ${Array.isArray(gate) ? gate.length : 0}).`,
+    };
+  }
+
+  const trimmed = gate.map((e) => (typeof e === 'string' ? e.trim() : e));
+
+  // Per-entry shape rules — run uniformly over every entry, including "none"
+  // (it trivially satisfies all of them; the none/mixed semantics are a
+  // separate check below). explainChain's result is kept per entry so the
+  // missing-timeout warning pass below never re-parses.
+  const explainedByEntry = [];
+  for (let i = 0; i < trimmed.length; i++) {
+    const entry = trimmed[i];
+    const idx = i + 1;
+    if (typeof entry !== 'string' || entry.length === 0) {
+      return { ok: false, error: `gate entry ${idx}: must be a non-empty string.` };
+    }
+    if (entry.length > GATE_ENTRY_MAX_CHARS) {
+      return { ok: false, error: entryError('gate', idx, entry, `must be at most ${GATE_ENTRY_MAX_CHARS} chars.`) };
+    }
+    if (/[\r\n]/.test(entry)) {
+      return { ok: false, error: entryError('gate', idx, entry, 'must not contain a newline.') };
+    }
+    if (entry.includes('```')) {
+      return { ok: false, error: entryError('gate', idx, entry, 'must not contain a triple-backtick run (breaks the fence).') };
+    }
+    if (entry.startsWith('#')) {
+      return { ok: false, error: entryError('gate', idx, entry, 'must not start with "#" — the fence parser drops lines starting with "#".') };
+    }
+    if (isNearMissNone(entry)) {
+      return {
+        ok: false,
+        error: entryError('gate', idx, entry, 'write exactly none, with nothing else, for a PRD with no runnable check.'),
+      };
+    }
+    const explained = explainChain(entry);
+    if (!explained.ok) {
+      return { ok: false, error: entryError('gate', idx, entry, explained.error) };
+    }
+    explainedByEntry.push(explained);
+  }
+
+  // "none" semantics: alone it's the opt-out; mixed with anything else it's
+  // an error (one PRD cannot be both "no gate" and "here is a gate").
+  const noneIdx = trimmed.findIndex((e) => isNoneGate(e));
+  if (noneIdx !== -1) {
+    if (trimmed.length > 1) {
+      return {
+        ok: false,
+        error: entryError(
+          'gate', noneIdx + 1, trimmed[noneIdx],
+          '"none" must be the only entry when used — remove the other entries or remove "none".',
+        ),
+      };
+    }
+    return { ok: true, commands: ['none'], warnings: [NONE_GATE_WARNING] };
+  }
+
+  // Missing-timeout warning (never rejects) — a step without one can hang
+  // the run.
+  const warnings = [];
+  explainedByEntry.forEach((explained, i) => {
+    explained.steps.forEach((step, stepIdx) => {
+      if (!explained.timeoutGiven[stepIdx]) {
+        warnings.push(
+          `gate entry ${i + 1} step "${cut80(step.raw)}" does not start with "timeout <seconds>" — a step without a timeout can hang the run.`,
+        );
+      }
+    });
+  });
+
+  return { ok: true, commands: trimmed, warnings };
+}
+
+/**
+ * Validate a PRD's `files` field.
+ *
+ * @param {unknown} files
+ * @returns {{ok:true, files:string[]}|{ok:false, error:string}}
+ *   files is deduped (exact match, order preserved) with every leading `./`
+ *   stripped per entry.
+ */
+function validateFiles(files) {
+  if (!Array.isArray(files) || files.length < FILES_MIN_ENTRIES || files.length > FILES_MAX_ENTRIES) {
+    return {
+      ok: false,
+      error: `files must have ${FILES_MIN_ENTRIES} to ${FILES_MAX_ENTRIES} entries (got ${Array.isArray(files) ? files.length : 0}).`,
+    };
+  }
+
+  const seen = new Set();
+  const out = [];
+  for (let i = 0; i < files.length; i++) {
+    const idx = i + 1;
+    const original = files[i];
+    if (typeof original !== 'string') {
+      return { ok: false, error: `files entry ${idx}: must be a string.` };
+    }
+    const entry = original.trim();
+    if (entry.length === 0) {
+      return { ok: false, error: `files entry ${idx}: must not be empty.` };
+    }
+    if (entry.length > FILES_ENTRY_MAX_CHARS) {
+      return { ok: false, error: entryError('files', idx, entry, `must be at most ${FILES_ENTRY_MAX_CHARS} chars.`) };
+    }
+    if (/[\r\n]/.test(entry)) {
+      return { ok: false, error: entryError('files', idx, entry, 'must not contain a newline.') };
+    }
+    if (FILES_FOREIGN_WHITESPACE_RE.test(entry)) {
+      return {
+        ok: false,
+        error: entryError('files', idx, entry, 'has a character that is not a plain space (for example a tab, a no-break space, or a line break). Retype it.'),
+      };
+    }
+    if (entry.includes('\\')) {
+      return { ok: false, error: entryError('files', idx, entry, 'use "/" between folders, not "\\".') };
+    }
+    if (entry.includes('`')) {
+      return { ok: false, error: entryError('files', idx, entry, 'must not contain a backtick.') };
+    }
+    if (entry.startsWith('-')) {
+      return { ok: false, error: entryError('files', idx, entry, 'must not start with "-".') };
+    }
+    if (entry.startsWith('/') || entry.startsWith('~') || /^[A-Za-z]:/.test(entry)) {
+      return { ok: false, error: entryError('files', idx, entry, 'must be repo-relative — absolute paths are not allowed.') };
+    }
+    if (entry.includes('*') || entry.includes('?')) {
+      return { ok: false, error: entryError('files', idx, entry, 'must not contain "*" or "?" (no globs).') };
+    }
+
+    let normalized = entry;
+    while (normalized.startsWith('./')) normalized = normalized.slice(2);
+    if (normalized.length === 0) {
+      return { ok: false, error: entryError('files', idx, entry, 'is empty after removing "./".') };
+    }
+    const segments = normalized.split('/');
+    if (segments.includes('..')) {
+      return { ok: false, error: entryError('files', idx, entry, 'must not contain a ".." path segment.') };
+    }
+    if (segments.includes('.')) {
+      return { ok: false, error: entryError('files', idx, entry, 'must not contain a "." path segment.') };
+    }
+    if (normalized.includes('//')) {
+      return { ok: false, error: entryError('files', idx, entry, 'must not contain an empty path segment ("//").') };
+    }
+
+    if (!seen.has(normalized)) {
+      seen.add(normalized);
+      out.push(normalized);
+    }
+  }
+
+  return { ok: true, files: out };
+}
+
+/**
+ * Render the `# Files` body section as an array of lines (joinable with
+ * '\n' alongside the rest of buildPrdBody's bodyLines). `files` must already
+ * be validated/normalized (validateFiles's output).
+ *
+ * @param {string[]} files
+ * @returns {string[]}
+ */
+function renderFilesSection(files) {
+  return [
+    '# Files', '',
+    'Change only these files. If the work needs another file, change it and say why in your report.',
+    '',
+    ...files.map((f) => `- ${f}`),
+    '',
+  ];
+}
+
+/**
+ * Render the `# Gate` body section as an array of lines. `commandsOrNone`
+ * must already be validated (validateGate's `commands` output) — either
+ * `['none']` or the ordered command-chain strings to fence verbatim.
+ *
+ * @param {string[]} commandsOrNone
+ * @returns {string[]}
+ */
+function renderGateSection(commandsOrNone) {
+  const isNone = commandsOrNone.length === 1 && isNoneGate(commandsOrNone[0]);
+  if (isNone) {
+    return [
+      '# Gate', '',
+      'This PRD has no runnable check. Check each acceptance criterion by reading the files.',
+      '',
+      '```gate',
+      'none',
+      '```',
+      '',
+    ];
+  }
+  return [
+    '# Gate', '',
+    'Run these commands last, in order. Each must exit 0.',
+    '',
+    '```gate',
+    ...commandsOrNone,
+    '```',
+    '',
+  ];
+}
+
+module.exports = {
+  validateGate,
+  validateFiles,
+  renderFilesSection,
+  renderGateSection,
+};

package/src/main/lib/prdLocations.cjs

@@ -384,6 +384,64 @@ function deriveProjectCwdFromPrdPath(filePath) {
   return null;
 }
 
+// Incident (2026-09-30): an Epic can live in a non-git PARENT folder P
+// (P/session-manager-operations/scheduler/epics/<epicId>/prds/*.md) while
+// its PRDs' own frontmatter `cwd` points at a SUB-REPO, e.g. P/repo. P is
+// never itself a tracked project cwd (activeProjectCwds/allProjectCwds only
+// know about registered project roots), so no amount of
+// resolvePrdsDirs()/listEpicPrdDirs() enumeration ever visits it — only
+// walking UP from the job's own cwd does. Bounded to a few hops so a
+// same-machine but unrelated ancestor folder that happens to also contain a
+// `session-manager-operations/` tree can't be walked into indefinitely.
+const MAX_EPIC_ANCESTOR_HOPS = 3;
+
+/**
+ * epicId must be an exact, plain directory-name match — never a glob, never
+ * string-concatenated into a path. Mirrors resolveEpicPrdWriteDir's own
+ * guard above.
+ */
+function isSafeEpicId(epicId) {
+  return typeof epicId === 'string' && epicId.length > 0
+    && !epicId.includes('/') && !epicId.includes('\\') && !epicId.includes('..');
+}
+
+/**
+ * Walk up to MAX_EPIC_ANCESTOR_HOPS parent directories ABOVE `cwd` (never
+ * including `cwd` itself — that's already covered by resolveEpicsRoot/
+ * listEpicPrdDirs) looking for an EXACT
+ * `<ancestor>/session-manager-operations/scheduler/epics/<epicId>/<leafSubpath...>`
+ * match. Built only from `path.join` segments (never string concatenation
+ * with the caller-supplied epicId/cwd), with a resolved-path containment
+ * check as defense in depth. Returns only dirs that actually exist on disk.
+ */
+function ancestorEpicDirs(cwd, epicId, leafSubpath) {
+  if (!cwd || typeof cwd !== 'string' || !path.isAbsolute(cwd)) return [];
+  if (!isSafeEpicId(epicId)) return [];
+  const out = [];
+  let dir = path.dirname(cwd);
+  for (let hop = 0; hop < MAX_EPIC_ANCESTOR_HOPS; hop++) {
+    const candidate = path.join(dir, OPS_ROOT_DIR, ...EPICS_SUBPATH, epicId, ...leafSubpath);
+    const resolvedDir = path.resolve(dir);
+    if (path.resolve(candidate).startsWith(resolvedDir + path.sep) && fs.existsSync(candidate)) {
+      out.push(candidate);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // reached the filesystem root
+    dir = parent;
+  }
+  return out;
+}
+
+/** Ancestor-folder `epics/<epicId>/prds` dirs above `cwd` (see ancestorEpicDirs). */
+function ancestorEpicPrdDirs(cwd, epicId) {
+  return ancestorEpicDirs(cwd, epicId, ['prds']);
+}
+
+/** Ancestor-folder `epics/<epicId>/prds-archived` dirs above `cwd` (see ancestorEpicDirs). */
+function ancestorEpicArchivedPrdDirs(cwd, epicId) {
+  return ancestorEpicDirs(cwd, epicId, ['prds-archived']);
+}
+
 module.exports = {
   resolvePrdWriteDir,
   resolvePrdsDirs,
@@ -394,6 +452,9 @@ module.exports = {
   listArchivedPrdDirs,
   deriveEpicIdFromPrdPath,
   deriveProjectCwdFromPrdPath,
+  ancestorEpicPrdDirs,
+  ancestorEpicArchivedPrdDirs,
+  isSafeEpicId,
   PRD_SUBPATH,
   EPICS_SUBPATH,
 };

package/src/main/lib/prdMigration.cjs

@@ -20,6 +20,7 @@ const { splitFrontmatter, parsePrdFile, serializePrdFile } = require('./prdFront
 const { resolvePrdWriteDir, resolvePrdsDirs } = require('./prdLocations.cjs');
 const { projectQueuePath } = require('./queueStore.cjs');
 const { expandHome } = require('./expandHome.cjs');
+const atomicFs = require('./atomicFs.cjs');
 
 /**
  * Move every `.md` file in legacyPrdsDir whose frontmatter `cwd` resolves to
@@ -262,9 +263,7 @@ async function legacyAdoptExistingPrds() {
         fm.createdVia = 'legacy-adopted';
         fm.issuedAt = issuedAt;
         const newRaw = serializePrdFile(fm, body);
-        const tmp = `${filePath}.tmp-${process.pid}`;
-        await fsp.writeFile(tmp, newRaw, 'utf8');
-        await fsp.rename(tmp, filePath);
+        await atomicFs.writeTextAtomic(filePath, newRaw);
         stamped += 1;
       } catch (e) {
         if (e?.code === 'ENOENT') continue; // raced with a concurrent mover/archiver

package/src/main/lib/prdSizing.cjs

@@ -5,7 +5,8 @@
  * jobs finishing in <=10 min, yet nothing at the authoring gate flags an oversized PRD before
  * it lands. `sizingWarnings` is the single rule set; prdCreate.cjs's createPrd() surfaces its
  * output in the create-prd response, and scheduler-mcp-server.cjs's scheduler_create_prd
- * handler prints it as a "Sizing warnings:" block. Warnings never block a write.
+ * handler prints it as part of a "Warnings:" block (merged with the gate/files warnings
+ * from prdGateFiles.cjs). Warnings never block a write.
  */
 'use strict';