amsd-pipeline-shared 0.5.21 → 0.5.22

package/orchestrations/scripts/lib/project-prompt-builder.js

@@ -0,0 +1,1413 @@
+#!/usr/bin/env node
+/**
+ * THE MINT BUILDS THIS PROJECT'S PROMPTS.
+ *
+ * Operator design, 2026-08-15: the agent that mints the roster also builds the prompts,
+ * because it is the stage that already knows what this project is and which roles will work
+ * on it — the two things a specialised prompt needs.
+ *
+ * Before this existed, nothing generated project prompts. prompt-library.js renders only the
+ * project-authority copy and refuses to fall back to a template, so a project without them
+ * cannot run — yet the only way to obtain them was to write them by hand. Hence exactly seven
+ * in the repo, all for one project.
+ *
+ * TWO PROVISIONING MODES, DECLARED IN bootstrap.json:
+ *   copyVerbatim — installed byte-identical. These cannot be generated because generating
+ *                  them would require themselves (the mint's own prompt; this generator's).
+ *   generated    — specialised by the model, checked against the template, then installed.
+ *
+ * FAILURE IS LOUD AND TOTAL. A generated prompt that drops, renames or invents one
+ * placeholder does not degrade — prompt-library throws at whichever seam needed it, mid-run,
+ * after the roster is minted and the run is already spending. So a prompt that fails its
+ * contract is never written, and the builder throws rather than leaving a project
+ * half-provisioned. It never falls back to the generic template: running a template is
+ * forbidden outright, and a silent degrade is how an engine default runs a whole campaign
+ * without anyone noticing.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// The one template this builder reads a PROJECT copy of, in order to generate the rest. Named once
+// so the provisioning guard above and the read below cannot disagree about it.
+const PROJECT_PROMPT_GENERATOR_ID = 'project-prompt-generation';
+const crypto = require('crypto');
+
+const { checkGeneratedPrompt, buildGeneratedDoc, generatedTemplateDigest } = require('./project-prompt-contract.js');
+
+const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8'));
+
+/**
+ * Render the generator's own prompt for one template.
+ *
+ * The generator is itself a project-authority prompt (bootstrap-copied), so it is rendered
+ * through the same library as everything else rather than assembled here — an engine-side
+ * copy of its text is precisely the thing this whole design removes.
+ */
+const { refusalBlock } = require('./refusal-block.js');
+// THE VARIANT RULE, IMPORTED — NOT RE-EXPRESSED. engine-prompt resolves a brownfield variant for
+// the seams it renders; this builder resolves templates out of a directory handed to it, so it
+// answers existence itself and takes the same decision from the same function. Two copies of a
+// routing rule drift, and the drift is invisible: both sides keep working, on different prompts.
+const { variantIdFor } = require('./engine-prompt.js');
+
+/**
+ * The template's body as one string — the SAME expression checkGeneratedPrompt uses, so the text
+ * the generator is shown and the text its output is judged against cannot drift apart.
+ */
+/**
+ * THE SLOT THE GENERATOR EMBEDS THE TEMPLATE'S SEGMENTS IN — named once. The rehearsal mock finds
+ * the generator template by this slot; a second spelling there would drift from this one.
+ */
+const GEN_BODY_SLOT = '__GEN_TEMPLATE_BODY__';
+
+function templateBodyText(template) {
+  if (!template) return '';
+  if (typeof template.body === 'string' && template.body) return template.body;
+  const bodies = template.bodies && typeof template.bodies === 'object' ? template.bodies : {};
+  return Object.values(bodies).filter((b) => typeof b === 'string').join('\n');
+}
+
+
+/**
+ * WHAT IDENTIFIES A ROSTER, FOR CACHING — its roles, not the prose describing them.
+ *
+ * The mint reports each role as `- <name> [<kind>] — <rationale>`, and the rationale is written
+ * by a model, so it is reworded on every mint of the same codeline. Digesting the whole string
+ * meant two runs producing IDENTICAL roles got different cache keys: measured 2026-09-04, 39
+ * cache entries and 0 hits, 28 of them blocked on exactly this — regenerating 28 prompts at model
+ * prices every run for a difference no prompt can observe.
+ *
+ * The key is decided by what a prompt can OBSERVE. usesRoles() marks a prompt as roster-dependent
+ * by extracting role NAMES and asking whether the generated text mentions any of them, so names
+ * are the only thing that can invalidate it — with kinds, because a kind decides whether an agent
+ * may author code at all. The rationale is commentary the generator reads and never quotes.
+ *
+ * Sorted, because the mint promises no ordering. Nothing here names a role, a kind or a count.
+ */
+/**
+ * THE CODELINE THIS RUN DETECTED, from the artifact the run itself wrote.
+ *
+ * Operator, 2026-09-06: "code line is detected in a live run ... this var will never be preset in
+ * a live run." EPAM_CODELINE_ID is read in six places in this repo and SET in none — no launcher,
+ * config or env file exports it. In a live run the codeline becomes known when discovery resolves
+ * the PRD's scope: after pre-run-reset has finished, before the mint and this builder run. So
+ * waiting for the variable means the cache never hits, silently, while the log reports normally.
+ *
+ * The PRD is the run, and run-agent-orchestration.sh exports PRD_FILE, so it is already in this
+ * process's environment — there is no call site to wire and no seam to rot. The fields read are
+ * the ones lib/codeline-scope.sh's codeline_scope_paths already treats as the run's scope, so
+ * both sides of the engine answer "which codeline?" from one place.
+ *
+ * EXACTLY ONE, or nothing. A run scoped to two codelines produces prompts specialised for both;
+ * attributing them to either would hand the other's run a set built for a repository it is not
+ * working in. Nothing is a legitimate answer — the entries stay project-level, as before.
+ */
+function codelineFromPrd(prdFile) {
+  try {
+    const f = String(prdFile || '').trim();
+    if (!f || !fs.existsSync(f)) return '';
+    const prd = JSON.parse(fs.readFileSync(f, 'utf8'));
+    const project = (prd && prd.project) || {};
+    const dirs = []
+      .concat(Array.isArray(project.outputDirs) ? project.outputDirs.map((o) => o && o.path) : [])
+      .concat(project.outputDir ? [project.outputDir] : [])
+      .filter((d) => typeof d === 'string' && d.trim());
+    const unique = [...new Set(dirs.map((d) => path.basename(String(d).replace(/\/+$/, ''))))]
+      .filter(Boolean);
+    return unique.length === 1 ? unique[0] : '';
+  } catch { return ''; }
+}
+
+/** The PRD's codeline folders: every outputDirs path's folder, then outputDir's, each once, in the PRD's order. */
+function _prdCodelines(prdFile) {
+  try {
+    const f = String(prdFile || '').trim();
+    if (!f || !fs.existsSync(f)) return { all: [], own: '' };
+    const project = (JSON.parse(fs.readFileSync(f, 'utf8')) || {}).project || {};
+    const base = (d) => (typeof d === 'string' && d.trim() ? path.basename(d.replace(/\/+$/, '')) : '');
+    const all = [...new Set([...(Array.isArray(project.outputDirs) ? project.outputDirs.map((o) => base(o && o.path)) : []), base(project.outputDir)]
+      .filter(Boolean))].map(codelineSegment).filter(Boolean);
+    return { all, own: codelineSegment(base(project.outputDir)) };
+  } catch { return { all: [], own: '' }; }
+}
+
+/** EVERY CODELINE OF A STORY — the folders its PRD is worked in, in the PRD's order. */
+function codelinesFromPrd(prdFile) { return _prdCodelines(prdFile).all; }
+
+/**
+ * THE CODELINE A PRD IS WORKED IN: its project.outputDir's folder. A lane's PRD lists every codeline of the story in outputDirs
+ * and its own in outputDir; a story's PRD names its primary codeline there. With no outputDir, its only codeline.
+ */
+function codelineOfPrd(prdFile) {
+  const { all, own } = _prdCodelines(prdFile);
+  return own || (all.length === 1 ? all[0] : '');
+}
+
+/**
+ * A CODELINE'S RECORDED SET IS COMPLETE: its completion marker built from the current inputs, its minted agents, its prompts.
+ * { complete, reason } — the reason names the part that is not there.
+ */
+function codelineSetComplete({ projectConfigDir, codeline, templatesDir, registryFile } = {}) {
+  const m = codelinePromptsComplete({ projectConfigDir, codeline, templatesDir, registryFile });
+  if (m.complete !== true) return { complete: false, reason: m.reason };
+  if (!hasMintedSnapshot({ projectConfigDir, codeline })) return { complete: false, reason: `no recorded agents at ${mintedSnapshotDir(projectConfigDir, codeline)}` };
+  const rp = recordedPromptsDir(projectConfigDir, codeline);
+  if (!fs.existsSync(rp) || !fs.readdirSync(rp).some((n) => n.endsWith('.json'))) return { complete: false, reason: `no recorded prompts at ${rp}` };
+  return { complete: true, reason: '' };
+}
+
+/**
+ * THE CODELINE THE MINT'S REUSE IS DECIDED FOR. One codeline: it (codelineFromPrd, as before). Several: the story's own codeline
+ * (codelineOfPrd) when EVERY codeline of the story has its complete recorded set — the agents before the lanes then run from
+ * that codeline's set, and each lane from its own — else '' (provisioned again, and recorded for every codeline).
+ */
+function scopeCodelineFromPrd({ prdFile, projectConfigDir, templatesDir, registryFile } = {}) {
+  const one = codelineFromPrd(prdFile);
+  if (one) return one;
+  const all = codelinesFromPrd(prdFile);
+  if (all.length < 2 || !projectConfigDir) return '';
+  if (!all.every((codeline) => codelineSetComplete({ projectConfigDir, codeline, templatesDir, registryFile }).complete)) return '';
+  const own = codelineOfPrd(prdFile);
+  return all.includes(own) ? own : '';
+}
+
+/**
+ * A LANE WORKS FROM ITS OWN CODELINE'S SET: that codeline's recorded minted agents and prompts made the project's active set
+ * (restoreMinted). A codeline with no recorded agents, or no recorded prompts, is no set — said, and nothing is changed: a lane
+ * never runs another codeline's set or the project-wide one.
+ */
+function restoreCodelineSet({ projectConfigDir, codeline } = {}) {
+  if (!projectConfigDir || !codeline) return { ok: false, reason: 'no project or codeline named' };
+  if (!hasMintedSnapshot({ projectConfigDir, codeline })) return { ok: false, reason: `no recorded agents at ${mintedSnapshotDir(projectConfigDir, codeline)}` };
+  const rp = recordedPromptsDir(projectConfigDir, codeline);
+  if (!fs.existsSync(rp) || !fs.readdirSync(rp).some((n) => n.endsWith('.json'))) return { ok: false, reason: `no recorded prompts at ${rp}` };
+  return restoreMinted({ projectConfigDir, codeline }) ? { ok: true, reason: '' } : { ok: false, reason: 'its recorded set could not be restored' };
+}
+
+/**
+ * LANES THAT RUN TOGETHER SHARE ONE ACTIVE SET, so parallel lanes can each work from their own codeline's set only when those sets
+ * are the same, byte for byte (prompts and minted agents). The sets compared, and the first difference when they are not.
+ */
+function codelineSetsIdentical({ projectConfigDir, codelines } = {}) {
+  const read = (d) => (fs.existsSync(d) ? Object.fromEntries(fs.readdirSync(d).filter((n) => n.endsWith('.json')).sort()
+    .map((n) => [n, crypto.createHash('sha256').update(fs.readFileSync(path.join(d, n))).digest('hex')])) : {});
+  const sets = (codelines || []).map((c) => ({ c, prompts: read(recordedPromptsDir(projectConfigDir, c)), minted: read(mintedSnapshotDir(projectConfigDir, c)) }));
+  for (const x of sets.slice(1)) {
+    for (const part of ['prompts', 'minted']) {
+      if (JSON.stringify(x[part]) !== JSON.stringify(sets[0][part])) return { same: false, reason: `${x.c}'s recorded ${part} differ from ${sets[0].c}'s` };
+    }
+  }
+  return { same: true, reason: '' };
+}
+
+/**
+ * ONE SAFE PATH SEGMENT from a codeline id, or '' when none is declared.
+ *
+ * The id names a directory under .prompt-cache. It arrives from configuration and from a
+ * discovery step's output, so a separator or a traversal in it must decide nothing about where
+ * this process writes. Everything outside [A-Za-z0-9._-] collapses to '-', leading dots are
+ * dropped so '..' cannot survive, and an id that reduces to nothing is treated as undeclared
+ * rather than as a directory named ''.
+ */
+function codelineSegment(raw) {
+  const t = String(raw == null ? '' : raw).trim();
+  if (!t) return '';
+  const seg = t.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^\.+/, '');
+  return seg || '';
+}
+
+/**
+ * ADOPT PRE-CODELINE CACHE ENTRIES, ONCE.
+ *
+ * Before the cache was keyed by codeline, entries sat flat at <project>/.prompt-cache/<id>.json
+ * and recorded nothing about which codeline produced them. The only evidence that can attribute
+ * them is the codeline the run declares, so they move under it the first time one does. metrolinx
+ * carries 39 such entries beside a marker naming next.gotransit.com.
+ *
+ * Only when the codeline's directory does not exist yet: once it does, this codeline has its own
+ * entries and a flat file is a leftover, not an ancestor. The completion markers (.complete-*)
+ * carry no .json extension and are not moved — they already name their codeline.
+ *
+ * Never throws. A migration that cannot run costs a regeneration, never correctness.
+ */
+function migrateFlatEntries(cacheRoot, cacheDir, log) {
+  if (!cacheRoot || !cacheDir || cacheDir === cacheRoot) return 0;
+  try {
+    if (fs.existsSync(cacheDir)) return 0;
+    if (!fs.existsSync(cacheRoot)) return 0;
+    // ONLY WHAT PREDATES CODELINE KEYING, never what merely sits at the root today. If ANY
+    // codeline directory already exists, this cache has been keyed before, so a flat file is a
+    // leftover from a run that declared no codeline — and adopting it would attribute one
+    // codeline's prompts to another on no evidence. That guess is the contamination this whole
+    // change exists to remove, so the migration declines it and the prompts regenerate.
+    const alreadyKeyed = fs.readdirSync(cacheRoot)
+      .some((f) => { try { return fs.statSync(path.join(cacheRoot, f)).isDirectory(); } catch { return false; } });
+    if (alreadyKeyed) return 0;
+    const flat = fs.readdirSync(cacheRoot).filter((f) => f.endsWith('.json')
+      && fs.statSync(path.join(cacheRoot, f)).isFile());
+    if (!flat.length) return 0;
+    fs.mkdirSync(cacheDir, { recursive: true });
+    let moved = 0;
+    for (const f of flat) {
+      try { fs.renameSync(path.join(cacheRoot, f), path.join(cacheDir, f)); moved += 1; } catch { /* leave it */ }
+    }
+    if (moved && typeof log === 'function') {
+      log(`[prompt-builder] adopted ${moved} pre-codeline cache entr${moved === 1 ? 'y' : 'ies'} `
+        + `under ${path.basename(cacheDir)} — nothing regenerated`);
+    }
+    return moved;
+  } catch { return 0; }
+}
+
+function rolesIdentity(mintedRoles) {
+  const out = [];
+  for (const line of String(mintedRoles || '').split('\n')) {
+    // `- <name> [<kind>]` — the identity the mint declares, whatever follows it.
+    const m = line.match(/^\s*-\s*([A-Za-z0-9][A-Za-z0-9-]*)\s*\[([^\]]*)\]/);
+    if (m) out.push(`${m[1]}[${m[2].trim()}]`);
+  }
+  return out.sort().join(',');
+}
+
+/**
+ * THE ACTIVE SET'S ANSWER BUDGET, in characters — what one model turn can return on it, as the set
+ * declares (a runner's `limits`: the smallest visible answer measured, at the measured characters
+ * per token). Infinity when no runner of the active set declares one: nothing changes for that set.
+ */
+function answerBudgetChars() {
+  try {
+    // eslint-disable-next-line global-require
+    const { activeSetFile, readSetFile } = require('./llm-settings-resolve.js');
+    const f = activeSetFile();
+    const runners = (f && (readSetFile(f) || {}).runners) || {};
+    const budgets = Object.values(runners).map((r) => r && r.limits)
+      .filter((l) => l && l.visibleTokensObservedMin > 0 && l.charsPerTokenObserved > 0)
+      .map((l) => Math.floor(l.visibleTokensObservedMin * l.charsPerTokenObserved));
+    return budgets.length ? Math.min(...budgets) : Infinity;
+  } catch { return Infinity; }
+}
+
+/**
+ * THE TEMPLATE'S PROSE IN PARTS THAT FIT ONE TURN.
+ *
+ * A unit is one segment, or — when a single segment is itself longer than a turn can return — one
+ * piece of it, split at paragraph breaks (PARAGRAPH, rejoined with the same). Units are grouped so
+ * each group's reply (its markers and wording, at the length shown) stays within the budget. With
+ * no budget declared, or when everything fits, there is one group of the whole segments: the single
+ * call every set made before. Returns { units: [{ seg, text }], groups: [{ from, to }] }.
+ */
+const PARAGRAPH = '\n\n';
+function promptParts(segments, budget) {
+  // eslint-disable-next-line global-require
+  const { formatSegments } = require('./project-prompt-contract.js');
+  const whole = { units: segments.map((text, seg) => ({ seg, text })), groups: [{ from: 0, to: segments.length }] };
+  if (!Number.isFinite(budget) || formatSegments(segments).length <= budget) return whole;
+  const units = [];
+  segments.forEach((text, seg) => {
+    if (formatSegments([text]).length <= budget) { units.push({ seg, text }); return; }
+    let cur = [];
+    for (const para of text.split(PARAGRAPH)) {
+      if (cur.length && formatSegments([[...cur, para].join(PARAGRAPH)]).length > budget) { units.push({ seg, text: cur.join(PARAGRAPH) }); cur = []; }
+      cur.push(para);
+    }
+    units.push({ seg, text: cur.join(PARAGRAPH) });
+  });
+  const groups = []; let from = 0;
+  for (let i = 0; i < units.length; i += 1) {
+    if (i > from && formatSegments(units.slice(from, i + 1).map((u) => u.text)).length > budget) { groups.push({ from, to: i }); from = i; }
+  }
+  groups.push({ from, to: units.length });
+  return { units, groups };
+}
+
+/** The template's segments back from the units' replies: each segment's pieces rejoined as split. */
+function segmentsFromUnits(units, texts, segmentCount) {
+  const out = Array.from({ length: segmentCount }, () => []);
+  units.forEach((u, i) => out[u.seg].push(texts[i]));
+  return out.map((pieces) => pieces.join(PARAGRAPH));
+}
+
+function renderGeneratorPrompt({ generatorBody, template, projectContext, codelineContext, mintedRoles, refusal, part }) {
+  let out = generatorBody
+    .split('__GEN_TEMPLATE_ID__').join(template.id)
+    .split('__GEN_TEMPLATE_DESCRIPTION__').join(template.description || '')
+    // A MULTI-BODY TEMPLATE HAS NO .body, AND join(undefined) IS A COMMA.
+    //
+    // 21 templates carry `bodies` instead of `body`. This read template.body — undefined for every
+    // one of them — and String.prototype.join(undefined) falls back to its DEFAULT separator, so
+    // the generator prompt received the single character "," where the template should have been.
+    // The model was asked to rewrite a comma, could not possibly preserve the placeholders it had
+    // never seen, and the shape guard refused all three attempts for "dropped placeholder(s)".
+    //
+    // That aborted mock3 runs 9 and 10 at skill-assessment-prephase, each after ~29 single-body
+    // templates had generated cleanly — and it was invisible because the refusal named the
+    // placeholders rather than the empty input that caused them to be missing.
+    //
+    // Joined the way checkGeneratedPrompt already joins them, so the text the model is given and
+    // the text its output is checked against are the same text. Two readers of one template that
+    // disagree is the defect this whole file keeps meeting.
+    .split('__GEN_TEMPLATE_PLACEHOLDERS__').join((template.placeholders || []).join(', ') || '(none)')
+    // THE SAME LIST THE CONTRACT CHECK WILL JUDGE IT AGAINST, from the same function, so the
+    // generator cannot be refused for losing a field it was never told about.
+    .split('__GEN_TEMPLATE_OUTPUT_FIELDS__').join(
+      // eslint-disable-next-line global-require
+      (require('./project-prompt-contract.js').outputFieldsIn(templateBodyText(template)) || []).join(', ') || '(none)')
+    .split('__GEN_PROJECT_CONTEXT__').join(projectContext || '')
+    .split('__GEN_CODELINE_CONTEXT__').join(codelineContext || '')
+    .split('__GEN_MINTED_ROLES__').join(mintedRoles || '')
+    // THE RETRY MUST BE TOLD WHY — re-sending an identical instruction gets an identical answer,
+    // and the refusal is the only new information the next attempt has. The words that carry it
+    // are the GENERATOR PROMPT'S, not this file's: they used to be appended here in JavaScript,
+    // where the prompt layer could not review them, the drift checks could not see them, and no
+    // project could change them. roster-specialisation.json has always done it this way.
+    //
+    // An absent refusal substitutes empty, so a first attempt carries no heading for a refusal
+    // that never happened.
+    .split('__GEN_PREVIOUS_REFUSAL__').join(refusalBlock(refusal, 'prompt'));
+
+  // THE TEMPLATE BODY GOES IN LAST, AND THIS ORDER IS THE WHOLE POINT.
+  //
+  // Three of the generator's own placeholders — __PROJECT_CONTEXT__, __CODELINE_CONTEXT__ and
+  // __PREVIOUS_REFUSAL__ — are ALSO placeholders in templates it has to specialise. The body was
+  // embedded first and the value substitutions then ran across the entire string, so the embedded
+  // template's own placeholders were replaced with real project text before the model ever saw
+  // them. It was then refused for "dropping" placeholders it was never shown.
+  //
+  // Live 2026-08-27: roster-specialisation refused on exactly those three, on every attempt and on
+  // every rung, because no model can reproduce a token that is not in its input. Same shape as the
+  // join(undefined) comma that aborted runs 9 and 10 — the input was wrong, and the refusal
+  // described the output.
+  //
+  // Substituted last, the body is inert text by the time it arrives: nothing after this line can
+  // reach inside it.
+  out = out    // SEGMENTS, NOT THE BODY. The model is shown only the prose BETWEEN placeholders and asked
+    // for the same number back; the slots never enter its input or its output, so it cannot drop
+    // one. 25 refusals on 2026-09-08 were all "dropped placeholder(s) the template requires", and
+    // a dropped slot silently starves the agent of the evidence that slot carries.
+    .split(GEN_BODY_SLOT).join((() => {
+      const { splitByPlaceholders, formatSegments } = require('./project-prompt-contract.js');
+      const all = splitByPlaceholders(templateBodyText(template)).segments;
+      // A PART, when one turn cannot return the whole: only its pieces are shown and asked for,
+      // numbered from 1, and said to be a part so the model words them as part of the whole.
+      const segments = part ? part.texts : all;
+      const where = part && part.of > 1
+        ? `This is part ${part.index + 1} of ${part.of} of the template; the other parts are asked for separately.\n`
+        : '';
+      return where + formatSegments(segments) + '\n'
+        + `Reply with the same ${segments.length} markers, in order, each followed by your wording `
+        + 'for that segment, and close with the END SEGMENTS marker. Plain text between the '
+        + 'markers — no JSON, no escaping, no code fences. A segment may be empty. Do not write '
+        + 'any placeholder tokens; the pipeline restores them between your segments.';
+    })());
+  return out;
+}
+
+/**
+ * Provision every prompt this project needs.
+ *
+ * @param {object}   o
+ * @param {string}   o.templatesDir        the immutable generic zone
+ * @param {string}   o.bootstrapFile       declares copyVerbatim / generated (auxiliary prompts)
+ * @param {string}   [o.registryFile]      invocation-profiles.json — every seam.template needs a copy
+ * @param {string}   o.projectConfigDir    prompts are written to <dir>/prompts
+ * @param {Function} o.runText             async (prompt) => model's reply text
+ * @param {Function} [o.reviewPrompt]      async ({id,template,generated}) => {ok, reason}
+ *                                         falsifies the derivative's claims about the project;
+ *                                         omitted means no review, exactly as before
+ * @param {string}   o.projectContext      what this project is
+ * @param {string}   o.codelineContext     codelines and declared dependencies
+ * @param {string}   o.mintedRoles         the roles the mint just produced
+ * @param {number}   [o.attempts=3]        generation attempts per prompt
+ * @param {Function} [o.log]               progress sink
+ * @returns {Promise<{copied:string[], generated:string[]}>}
+ */
+/**
+ * WHAT NEEDS A PROJECT COPY — resolved from the registry, with bootstrap supplying only what the
+ * registry cannot know.
+ *
+ * Pure and exported so the contract is assertable without provisioning anything.
+ *
+ * THE REGISTRY IS THE SOURCE. A seam declaring `template: X` IS the statement that X needs a
+ * project copy. bootstrap.generated used to restate 25 of those by hand, and a hand-kept copy of a
+ * derivable fact only ever drifts: seven seam-run templates had already fallen out of it, the last
+ * being prompt-review — a seam added by the very session that documented the drift at six.
+ *
+ * bootstrap now carries ONLY auxiliary prompts: sub-prompts referenced INSIDE a template body
+ * (retry prefixes, hint bodies) which no seam names and which deriving alone would drop.
+ *
+ * A seam naming a template that exists NOWHERE throws. Under the old union that was rescued into
+ * silence; the registry being the source means a gap in it is an error, not something bootstrap
+ * quietly covers for.
+ *
+ * @param {object} o.bootstrap        parsed bootstrap.json
+ * @param {object} o.registry         parsed invocation-profiles.json
+ * @param {function} [o.templateExists] (id) => bool; defaults to assuming it does
+ * @returns {string[]} template ids needing a generated project copy
+ */
+function provisioningList({ bootstrap = {}, registry = {}, templateExists = () => true }) {
+  const copyVerbatim = Array.isArray(bootstrap.copyVerbatim) ? bootstrap.copyVerbatim : [];
+  const aux = Array.isArray(bootstrap.generated) ? bootstrap.generated : [];
+
+  const seamRun = [...new Set(
+    Object.values(registry.profiles || {}).map((p) => p && p.template).filter(Boolean),
+  )];
+
+  const orphaned = seamRun.filter((t) => !templateExists(t));
+  if (orphaned.length) {
+    throw new Error(
+      `[prompt-builder] seam registry names template(s) that exist nowhere: ${orphaned.join(', ')}. `
+      + 'A seam that runs a template with no file cannot be provisioned, and provisioning around it '
+      + 'would leave that seam executing nothing. Add the template, or correct the seam.');
+  }
+
+  // Union of the two KINDS, not of two copies of one kind: seam-declared, plus the auxiliaries the
+  // registry has no way to see. copyVerbatim is installed unchanged and is never generated.
+  return [...new Set([...seamRun, ...aux])].filter((t) => !copyVerbatim.includes(t));
+}
+
+/**
+ * WHAT THE SELF-HEAL ANALYST IS TOLD THE OUTPUT IS. It was told only the placeholder names, saw them
+ * unfilled in the output, and diagnosed that as the failure (AMSD-2974 run 3, 2026-10-09). A project
+ * prompt is reused for every call; its placeholders are filled per call at run time and must stay.
+ */
+function healContext(id, template) {
+  return `The output is a reusable PROJECT PROMPT generated from template ${id}: the same prompt serves every `
+    + 'story and every call this project makes to that agent. Its placeholders '
+    + `(${((template && template.placeholders) || []).join(', ')}) are filled per call at run time with that `
+    + 'call\'s story, files and criteria, and must appear unfilled — an unfilled placeholder is never the defect, '
+    + 'and the corrective never writes into one. Anything true only for one ticket belongs in those run-time '
+    + 'values, never in the prompt; what the prompt may say about the project is what stays true for every '
+    + 'story. Diagnose the refusal reason given in that light.';
+}
+
+async function buildProjectPrompts({
+  templatesDir, bootstrapFile, registryFile, projectConfigDir, runText, reviewPrompt,
+  projectContext, codelineContext, mintedRoles, attempts = 3, mode = 'generate', log = () => {},
+  keepExisting = false,
+}) {
+  // SAY WHICH IT WAS. This reviewer is opt-in (registry: prompt-review.optIn), and a run with no
+  // reviewer looked exactly like a run whose reviewer approved everything — 35 prompts
+  // provisioned, "REVIEW REJECTED: 0". Silence is not a clean bill of health, so the run states
+  // plainly that these prompts went in unexamined. Turned on per project via
+  // EPAM_PROMPT_REVIEW_ENABLED; see mint-agents-step.js.
+  if (typeof reviewPrompt === 'function') {
+    log('[prompt-builder] prompt review ENABLED — each generated prompt is falsified before install');
+  } else {
+    log('[prompt-builder] prompt review is OFF — generated prompts are installed NOT REVIEWED '
+      + '(this project set EPAM_PROMPT_REVIEW_ENABLED=0 — review is ON by default)');
+  }
+
+  const boot = readJson(bootstrapFile);
+  let copyVerbatim = Array.isArray(boot.copyVerbatim) ? boot.copyVerbatim : [];
+  let generated = Array.isArray(boot.generated) ? boot.generated : [];
+
+  // WHAT NEEDS A PROJECT COPY IS DERIVED FROM THE SEAM REGISTRY, NOT MAINTAINED BY HAND.
+  //
+  // A seam names the template it runs. If a seam runs it, that seam needs a PROJECT copy —
+  // otherwise it executes the immutable generic parent, unspecialised for the project it is
+  // working on. That makes the list a fact of the registry, not a list anyone curates.
+  //
+  // Curating it had already drifted: of 33 templates referenced by a seam, six appeared in
+  // bootstrap NOWHERE — codeline-bridge, e2e-route-check, assign-agent-roles, spec-story-block,
+  // skill-assessment-prephase, prd-model-coordinator. Those seams had no project-prompt path at
+  // all, and nothing reported it, because the only list was the one that omitted them.
+  //
+  // bootstrap.generated is still read: it carries AUXILIARY prompts that a seam template
+  // references but no seam names directly (retry prefixes, hint bodies, sub-prompts). Union, not
+  // replacement — deriving alone would silently drop those.
+  if (registryFile && fs.existsSync(registryFile)) {
+    // ONE RESOLUTION, ONE PLACE. provisioningList is the contract, asserted directly by
+    // test/unit/orchestration/bootstrap-duplicates-the-seam-registry.test.ts; computing the list a
+    // second time here is how the two would come to disagree.
+    generated = provisioningList({
+      bootstrap: boot,
+      registry: readJson(registryFile),
+      templateExists: (id) => fs.existsSync(path.join(templatesDir, `${id}.json`)),
+    });
+    log(`[prompt-builder] ${generated.length} template(s) need a project copy `
+      + '(seam-declared, plus bootstrap auxiliaries)');
+  }
+
+  // WHICH TEMPLATE AN ID ACTUALLY MEANS FOR THIS RUN.
+  //
+  // A brownfield run wants different text from the same seam. The variant is a dimension of the
+  // ID, so it is resolved once, here, and every reader that must follow it calls this — nobody
+  // chooses per call site and nobody can forget.
+  //
+  // WHAT DELIBERATELY DOES NOT USE IT: the existence guards and _layerOf, which stay on the BASE.
+  // The base must exist for every provisioned id regardless of variant — that is what makes the
+  // fallback total — and a variant must never move a prompt between layers, because that is the
+  // same seam being served from a different zone.
+  const _tplId = (id) => variantIdFor(id, (v) => fs.existsSync(path.join(templatesDir, `${v}.json`)));
+  const _tplPath = (id) => path.join(templatesDir, `${_tplId(id)}.json`);
+
+  // ONLY WHAT A PROJECT-LAYER RENDERER READS.
+  //
+  // There are two renderers and the split is deliberate: prompt-library.js reads the PROJECT
+  // copy, engine-prompt.js reads the TEMPLATE. A project copy of an engine-layer prompt can
+  // therefore never be executed — codeline discovery, for one, runs before the mint that would
+  // have written its copy.
+  //
+  // Provisioning them anyway cost three things: model spend under 'generate' mode; a file that
+  // reads as live to anyone who opens it; and a place for self-heal corrections to land and do
+  // nothing. One had already gone stale against its template and silently dropped the rule that
+  // makes discovery emit codeline facts — a capability lost in a file nothing runs.
+  //
+  // The template declares its own layer, because inference does not hold: a project prompt can be
+  // addressed dynamically (agent-inputs.js resolves an id through the seam registry), so no scan
+  // of call sites is complete. Absent means engine — the safe default writes nothing.
+  // EXISTENCE FIRST. Reading the layer of a template that is not there cannot answer the
+  // question, and answering 'engine' would silently drop it — turning a bootstrap that names a
+  // missing template into a quiet no-op instead of the loud refusal it must be.
+  for (const id of [...copyVerbatim, ...generated]) {
+    const p = path.join(templatesDir, `${id}.json`);
+    if (!fs.existsSync(p)) {
+      throw new Error(`[prompt-builder] bootstrap declares '${id}' but no template exists at ${p}`);
+    }
+  }
+
+  const _layerOf = (id) => readJson(path.join(templatesDir, `${id}.json`)).layer || 'engine';
+
+  // A TEMPLATE THIS BUILDER ITSELF READS CANNOT BE FILTERED OUT OF ITS OWN INSTALL.
+  //
+  // The layer heuristic decides whether a project copy is worth writing. But this builder reads
+  // the PROJECT copy of the generator prompt to produce every other prompt (see genId below), so
+  // dropping it is self-contradictory: bootstrap declares it, the filter removes it, and the
+  // failure surfaces eighty lines later as "'project-prompt-generation' is not installed. It must
+  // be declared in bootstrap.copyVerbatim" — which it already was.
+  //
+  // Derived from the code that reads them, not a list anyone maintains: whatever this builder
+  // requires from outDir is required, whatever its template metadata happens to say.
+  const _requiredFromProjectCopy = [PROJECT_PROMPT_GENERATOR_ID];
+  for (const id of _requiredFromProjectCopy) {
+    if ([...copyVerbatim, ...generated].includes(id) && _layerOf(id) !== 'project') {
+      throw new Error(
+        `[prompt-builder] '${id}' is declared in bootstrap but its template is layer='${_layerOf(id)}', `
+        + 'so provisioning would drop it — and this builder reads the project copy of it to generate '
+        + 'every other prompt. Set "layer": "project" on the template, or remove it from bootstrap.');
+    }
+  }
+
+  // A TEMPLATE A SEAM RUNS IS PROJECT-LAYER BY DEFINITION.
+  //
+  // The layer field was the only gate, and absent defaults to 'engine' — so 37 of 44 templates
+  // were dropped and their seams executed the generic parent on a specific project. That is the
+  // condition this whole layer exists to prevent, decided by a metadata field nobody set.
+  //
+  // Running it is the proof: if a seam names a template, that seam needs a specialised copy. The
+  // layer field still decides for templates NO seam names — auxiliary bodies that only another
+  // prompt references.
+  const _seamRun = new Set();
+  if (registryFile && fs.existsSync(registryFile)) {
+    for (const p of Object.values(readJson(registryFile).profiles || {})) {
+      if (p.template) _seamRun.add(p.template);
+    }
+  }
+  const _needsProjectCopy = (id) => _seamRun.has(id) || _layerOf(id) === 'project';
+  const _dropped = [...copyVerbatim, ...generated].filter((id) => !_needsProjectCopy(id));
+  if (_dropped.length) {
+    // Said out loud. A silently shorter list is indistinguishable from a bootstrap that never
+    // declared them.
+    log(`[prompt-builder] ${_dropped.length} template(s) are engine-layer and are not provisioned `
+      + `— nothing would ever read a project copy: ${_dropped.join(', ')}`);
+  }
+  copyVerbatim = copyVerbatim.filter(_needsProjectCopy);
+  generated = generated.filter(_needsProjectCopy);
+
+  // TWO PROVISIONING MODES, one per project, by operator design:
+  //
+  //   'copy'      the template layer is installed AS IS. What the project runs is exactly the
+  //               generic text — no model involved, nothing to draw differently twice.
+  //   'generate'  everything outside the bootstrap set is specialised by the agent that minted
+  //               the roster.
+  //
+  // The mode belongs to the PROJECT, not to this file: a project is data. Copy mode is not a
+  // degraded generate — it is the deliberate choice for a project whose prompts should stay
+  // identical to the generic ones until someone decides otherwise.
+  if (mode === 'copy') {
+    copyVerbatim = [...copyVerbatim, ...generated];
+    generated = [];
+  } else if (mode !== 'generate') {
+    throw new Error(`[prompt-builder] unknown mode '${mode}' — expected 'copy' or 'generate'`);
+  }
+
+  // ── A MULTI-PART TEMPLATE CANNOT SURVIVE GENERATION, SO IT IS NOT GENERATED ────────────────
+  //
+  // A template may declare several named bodies, and each consumer renders ONE by name:
+  //
+  //     renderEngineTemplate('spec-story-block', {...}, 'retrieved_docs')
+  //
+  // Generation had no concept of that. templateBodyText() joins every part into one string, the
+  // model rewrites the join, and buildGeneratedDoc writes a single `body`. The installed copy
+  // therefore has no parts at all and declares the UNION of every part's placeholders.
+  //
+  // What that does to a consumer asking for a part:
+  //   - where its values do not cover the union, the render is REFUSED. Live 2026-09-04:
+  //       "ticket-link review skipped (prompt 'spec-story-block' is missing values for:
+  //        __COMMENT_BLOCK__, __COMPONENTS__, ... __TITLE__)"
+  //     after the review had already fetched 4 of 4 linked documents, which then never reached
+  //     the run;
+  //   - where they DO cover it, there is no error at all and the agent is silently handed every
+  //     part concatenated — several prompts glued together. That is the worse half, and it was
+  //     invisible.
+  //
+  // 18 seam-declared templates are multi-part, including story-writer, spec-agent, the failure
+  // analyst and the QA gates. None of them has ever been correctly specialised: the specialised
+  // text was only ever delivered as an unusable merge. So copying them verbatim is not a loss of
+  // a working capability — it replaces a corrupt merge with the correct parts, costs 18 fewer
+  // model calls, and shortens the mint.
+  //
+  // Per-part generation is the richer answer and remains open: this is the decision that makes
+  // the parts correct now, and it is reversible.
+  const _multiPart = (id) => {
+    try {
+      const t = readJson(_tplPath(id));
+      return t && t.bodies && typeof t.bodies === 'object'
+        && Object.values(t.bodies).filter((b) => typeof b === 'string').length > 1;
+    } catch { return false; }
+  };
+  const _movedToVerbatim = generated.filter(_multiPart);
+  if (_movedToVerbatim.length) {
+    generated = generated.filter((id) => !_multiPart(id));
+    copyVerbatim = [...copyVerbatim, ..._movedToVerbatim];
+    // Said out loud: a provisioning decision nobody can see is one nobody can reverse.
+    log(`[prompt-builder] ${_movedToVerbatim.length} multi-part template(s) are copied verbatim `
+      + 'rather than generated — generation flattens their named bodies into one, which hands a '
+      + `consumer every part at once: ${_movedToVerbatim.join(', ')}`);
+  }
+
+  // EVERY DECLARED TEMPLATE MUST EXIST BEFORE ANYTHING IS WRITTEN. Discovering a missing one
+  // halfway through leaves the project partially provisioned, which starts and then dies.
+  for (const id of [...copyVerbatim, ...generated]) {
+    const p = path.join(templatesDir, `${id}.json`);
+    if (!fs.existsSync(p)) {
+      throw new Error(`[prompt-builder] bootstrap declares '${id}' but no template exists at ${p}`);
+    }
+  }
+
+  const outDir = path.join(projectConfigDir, 'prompts');
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // THE PREVIOUS RUN'S COMPLETION MARKER GOES FIRST.
+  //
+  // From here on this run is rewriting the project's prompts. If it dies partway, a marker
+  // left by the LAST run still reads 'complete', and the NEXT run would inherit a
+  // half-written set as finished. Cleared on the way in, rewritten only on the way out.
+  // The operator's explicit id still wins; otherwise the run's own detected scope decides.
+  const safeCodeline = codelineSegment(process.env.EPAM_CODELINE_ID)
+    || codelineSegment(codelineFromPrd(process.env.PRD_FILE));
+  // ONLY THIS CODELINE'S CLAIM: another codeline's completion records its own agents and prompts,
+  // so it stays true while this one rewrites prompts/ (A -> B -> A, 2026-10-01).
+  clearCompletionMarker({ outDir, codeline: safeCodeline });
+
+  // ── Bootstrap: verbatim, byte for byte ──────────────────────────────────
+  const copied = [];
+  // A RESUME COMPLETES, IT NEVER REBUILDS. keepExisting (a resumed run): a prompt already installed
+  // for this run is kept byte-for-byte — no call, no rewrite — and only the missing ones are built.
+  // An interrupted build left 15 of 43 prompts and a resume either skipped provisioning (so the
+  // failure analyst had no prompt) or would have rebuilt all of them (found 2026-09-25).
+  //
+  // KEPT ONLY WHILE IT IS STILL THE COPY OF ITS TEMPLATE. Each copy records the digest of the template
+  // it came from (derivedFromSha256); a resume that kept it regardless went on executing the old
+  // template's text after the template was corrected — a fix could not reach a resumed run (the
+  // analysts' fix-site input, 2026-10-04). A copy whose template moved on is rebuilt, and says so.
+  const _verbatimDigest = (doc) => (doc.bodies !== undefined
+    ? crypto.createHash('sha256').update(JSON.stringify(doc.bodies, null, 0)).digest('hex')
+    : crypto.createHash('sha256').update(String(doc.body)).digest('hex'));
+  const _alreadyInstalled = (id, kind) => {
+    const file = path.join(outDir, `${id}.json`);
+    if (!keepExisting || !fs.existsSync(file)) return false;
+    let installed; let tpl;
+    try { installed = readJson(file); tpl = readJson(_tplPath(id)); } catch { return false; }
+    const want = kind === 'generated' ? generatedTemplateDigest(tpl) : _verbatimDigest(tpl);
+    if (installed && installed.derivedFromSha256 === want) return true;
+    log(`[prompt-builder] ${id}: its template changed since this copy was made — rebuilding it`);
+    return false;
+  };
+  for (const id of copyVerbatim) {
+    if (_alreadyInstalled(id, 'verbatim')) { copied.push(id); log(`[prompt-builder] kept ${id} (installed for this run)`); continue; }
+    const src = _tplPath(id);
+    const doc = readJson(src);
+
+    // THE TEXT IS COPIED VERBATIM; THE PROVENANCE IS ADDED.
+    //
+    // A project copy must record which template it came from, or a later template edit is
+    // invisible: the project keeps running the older prompt while the template claims
+    // otherwise. Writing the file byte-for-byte lost that — and worse, ERASED the provenance
+    // the hand-minted copies already carried.
+    //
+    // The digest covers the prompt TEXT only, matching the convention the existing copies
+    // used: bodies for a multi-part prompt, body for a single one.
+    // TWO CONVENTIONS ALREADY EXIST, and both are load-bearing because separate tests assert
+    // each: a MULTI-PART prompt hashes JSON.stringify(bodies), a single-body prompt hashes the
+    // RAW body string. Picking one would have silently invalidated every copy of the other
+    // shape. Matched rather than unified — unifying them is a change to what "unchanged"
+    // means for prompts already in the field.
+    doc.derivedFromSha256 = _verbatimDigest(doc);
+    doc.authority = 'project';
+
+    fs.writeFileSync(path.join(outDir, `${id}.json`), JSON.stringify(doc, null, 2) + '\n');
+    copied.push(id);
+    log(`[prompt-builder] copied ${id}`);
+  }
+
+  // The generator's own prompt comes from the project copy just installed, not from an
+  // engine-side string.
+  const genId = PROJECT_PROMPT_GENERATOR_ID;
+  const genPath = path.join(outDir, `${genId}.json`);
+  const generatorBody = fs.existsSync(genPath) ? readJson(genPath).body : null;
+  if (generated.length && !generatorBody) {
+    throw new Error(
+      `[prompt-builder] cannot generate ${generated.length} prompt(s): '${genId}' is not installed. `
+      + 'It must be declared in bootstrap.copyVerbatim — it cannot be its own output.');
+  }
+
+  // ── Generated: specialise, check, then install ──────────────────────────
+  const built = [];
+  // WHAT WROTE AND JUDGED A GENERATED PROMPT: the generator's and the reviewer's installed copies, by the template
+  // digest each records. A kept prompt is judged again only when this differs from what it recorded.
+  const _judges = () => [genId, 'prompt-review'].map((j) => {
+    try { return readJson(path.join(outDir, `${j}.json`)).derivedFromSha256 || ''; } catch { return ''; }
+  }).join(':');
+  // WHERE THE TEMPLATES ARE BEING READ FROM, said once.
+  //
+  // Run 20260817T211517Z installed a copy whose seams did not match its template and whose
+  // provenance digest was empty — a value buildGeneratedDoc cannot produce. The same code
+  // reproduces correctly offline, so what differs is which FILE was read, and nothing recorded
+  // that. One line here answers it instead of another run spent guessing.
+  log(`[prompt-builder] templates read from ${templatesDir}`);
+
+  // ── REUSE: DO NOT PAY TWICE FOR THE SAME PROMPT ──────────────────────────────────────────
+  //
+  // The pre-run reset deletes <project>/prompts every run, so every prompt was regenerated from
+  // unchanged immutable templates. Measured on mock3 run 9: 29 prompts, $5.48 — 89% of the run's
+  // cost, before a single story was touched.
+  //
+  // The obstacle is __MINTED_ROLES__: the mint invents new role names every run, so a digest over
+  // all inputs never matches. But of run 9's 31 generated prompts only FOUR embed a minted role
+  // name. Whether a template's OUTPUT depends on the roster is a fact about that template, and it
+  // is knowable — after generating once, by looking at what it produced.
+  //
+  // Each entry records both digests and which one governs it: a prompt naming a minted role is
+  // regenerated when the roster changes, one that does not is reused. Nothing is guessed — a
+  // template not in the cache is always generated.
+  //
+  // The cache lives OUTSIDE prompts/ so the reset's clean slate is untouched. This is memoisation
+  // on an exact key, not surviving state.
+  const cacheRoot = path.join(outDir, '..', '.prompt-cache');
+  // KEYED BY CODELINE, because that is what a generated prompt is specialised FOR.
+  //
+  // Operator: "tagged to a CODELINE and reused for the CODELINE". The completion marker already
+  // carries the codeline in its name; the entries it vouches for did not, so a run under codeline
+  // B reused prompts naming codeline A's repositories, modules and dependencies. That is the
+  // cross-codeline contamination the marker exists to prevent, arriving through what it points at.
+  //
+  // A codeline id reaches here from configuration and from a discovery step's output, so it is
+  // reduced to a single safe path segment before it names a directory — 'a/b' and '../x' must not
+  // decide where this process writes.
+  // The operator's explicit id still wins; otherwise the run's own detected scope decides.
+  const cacheDir = safeCodeline ? path.join(cacheRoot, safeCodeline) : cacheRoot;
+  // MIGRATION, not discard. Entries written before this change sit flat at the cache root and
+  // record no codeline, so they can only be attributed by the codeline the run declares. Moving
+  // them costs nothing; discarding them would charge a full regeneration for a change that is
+  // purely about where they live. It happens once: after the move the root holds no *.json.
+  migrateFlatEntries(cacheRoot, cacheDir, log);
+  const sha = (t) => crypto.createHash('sha256').update(String(t)).digest('hex');
+  // THE TEMPLATE AND THE GENERATOR — NOT THE PROSE ABOUT THE PROJECT.
+  //
+  // This keyed on { t, generatorBody, projectContext, codelineContext }. The last two are written
+  // by the estate survey and codeline discovery, both of which run EVERY run, and a model rewords
+  // itself every time. So the key changed on every run and the cache never hit once: measured
+  // 2026-09-06 on pipeline-tests-27, 39 entries and 0 hits, with the templates byte-identical
+  // between v1.43 and v1.47 (git diff over prompts/templates: 0 files).
+  //
+  // Exactly the defect rolesIdentity fixes immediately below, one layer up and left unfixed:
+  // "Digesting the mint's raw text rebuilt every roster-dependent prompt on every run because a
+  // model rewords itself."
+  //
+  // What remains in the key is what actually decides the generated text: the template, and the
+  // generator body that rewrites it. The contexts are still PASSED to the generator — they shape
+  // the prompt — they just no longer invalidate a prompt that would come out the same.
+  //
+  // Codeline identity is not weakened by this: it is enforced separately and more strictly by the
+  // per-codeline completion marker (.complete-<codeline>), so one codeline's prompts cannot serve
+  // another even though the prose is no longer in the key.
+  const baseDigest = (t) => sha(JSON.stringify({ t, generatorBody }));
+  // The ROLES, not the prose about them — see rolesIdentity. Digesting the mint's raw text
+  // rebuilt every roster-dependent prompt on every run because a model rewords itself.
+  const rolesDigest = sha(rolesIdentity(mintedRoles));
+  const usesRoles = (doc, roles) => {
+    const names = String(roles || '').match(/[a-z][a-z0-9]*(?:-[a-z0-9]+)+/g) || [];
+    const body = JSON.stringify(doc);
+    return names.some((n) => body.includes(n));
+  };
+  const cacheRead = (id) => {
+    // NO CODELINE DECLARED CHANGES NOTHING. The requirement is that a codeline's prompts are
+    // reused FOR that codeline; it says nothing about a run that declares none, and no launcher in
+    // this repo sets EPAM_CODELINE_ID — the operator exports it. Making an undeclared run stop
+    // reusing would silently charge a full regeneration for a forgotten variable, and would break
+    // the remedy a-reused-prompt-was-reviewed encodes. Such a run reads the flat root, as before.
+    try { return JSON.parse(fs.readFileSync(path.join(cacheDir, `${_tplId(id)}.json`), 'utf8')); }
+    catch { return null; }
+  };
+  const cacheWrite = (id, entry) => {
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+      fs.writeFileSync(path.join(cacheDir, `${_tplId(id)}.json`), JSON.stringify(entry, null, 2) + '\n');
+    } catch { /* a cache that cannot be written costs money, never correctness */ }
+  };
+
+  // THE REVIEWER'S OWN PROMPT IS PROVISIONED FIRST, because it cannot review anything until it
+  // exists. In run 20260827T151832Z it was generated 32nd of 39: the first 31 prompts were
+  // handed to a reviewer whose prompt was not on disk yet, the render failed, and every one of
+  // them was installed UNREVIEWED — while the log said review was enabled.
+  //
+  // Ordering only. Nothing is skipped and nothing is generated twice; the reviewer is simply
+  // built before the artefacts it must judge.
+  // WHICH prompt is the reviewer's is DERIVED, never named here: it is the template run by the
+  // seam that produces the prompt verdict. A literal would put a seam's identity in engine code
+  // and go stale the moment the seam is renamed.
+  const _reviewerTemplate = (() => {
+    try {
+      const _reg = registryFile && fs.existsSync(registryFile) ? readJson(registryFile) : null;
+      for (const prof of Object.values((_reg && _reg.profiles) || {})) {
+        if (prof && prof.produces === 'prompt-verdict' && prof.template) return prof.template;
+      }
+    } catch { /* absent stays absent — provisioning order is then unchanged */ }
+    return '';
+  })();
+  if (_reviewerTemplate) {
+    generated = [...generated].sort((a, b) => (a === _reviewerTemplate ? -1
+      : b === _reviewerTemplate ? 1 : 0));
+  }
+  // ONE ROUTE TO THE ANALYST for every refusal of a generated prompt — the contract's and the
+  // reviewer's, of a fresh generation, a cached copy or a kept one — with the text that was refused.
+  const _heal = (id, template, reason, output, failureClass) => {
+    try {
+      // eslint-disable-next-line global-require
+      const _sh = require('./self-heal.js').selfHeal({
+        agent: `prompt-builder:${id}`, reason, output: output, failureClass,
+        // The rung that produced it — without this the analyst declines and heals nothing.
+        model: process.env.EPAM_MODEL || '', provider: process.env.AI_PROVIDER || '',
+        projectConfigDir: process.env.EPAM_PROJECT_CONFIG_DIR || '',
+        context: healContext(id, template),
+      });
+      if (_sh && _sh.rc === 2) log(`[prompt-builder] self-heal analyst FAILED for ${id} — the next attempt has no corrective`);
+    } catch { /* a diagnostic must never fail the run it is diagnosing */ }
+  };
+  for (const id of generated) {
+    // WHY THE PREVIOUS ANSWER WAS REFUSED — seeded when a kept or cached copy is rejected, so the
+    // regeneration that follows is told what was wrong rather than asked the same question again.
+    let refusal = '';
+    // A KEPT COPY IS JUDGED AGAIN BY THE CURRENT REVIEWER (operator, 2026-10-06). A resume keeps the
+    // prompts its run built, and the contract cannot see what the reviewer can: metrolinx's
+    // repro-test-writer was narrowed to one ticket with its slots displaced, every slot still present.
+    // Keeping it unexamined meant no correction to the generator or the reviewer could reach the run.
+    // Approved, or no verdict (a reviewer's own failure is not evidence against the prompt): kept.
+    // Rejected: regenerated, told why, and the rejection goes to the analyst.
+    let _keptRejected = false;
+    if (_alreadyInstalled(id, 'generated')) {
+      if (typeof reviewPrompt !== 'function') { built.push(id); log(`[prompt-builder] kept ${id} (installed for this run)`); continue; }
+      const _kept = readJson(path.join(outDir, `${id}.json`));
+      // JUDGED AGAIN ONLY WHEN WHAT JUDGED IT CHANGED (operator, 2026-10-13: "I don't want a full review"). The rule
+      // above exists so a corrected generator or reviewer reaches a resumed run; a copy whose template, generator and
+      // reviewer are the ones that approved it has nothing new to be judged by. A copy that predates the record is
+      // kept as built — re-judging it is the full review this replaced.
+      if (!_kept.judgedWith || _kept.judgedWith === _judges()) {
+        built.push(id);
+        log(`[prompt-builder] kept ${id} (installed for this run) — ${_kept.judgedWith
+          ? 'its template, generator and reviewer are the ones that approved it' : 'no record of what judged it; kept as built'}`);
+        continue;
+      }
+      const _v = await reviewPrompt({ id, template: readJson(_tplPath(id)), generated: _kept });
+      if (!_v || _v.ok !== false) {
+        built.push(id);
+        log(`[prompt-builder] kept ${id} (installed for this run) — ${_v && _v.reviewed === false
+          ? `unreviewed: the reviewer gave no verdict (${_v.reason || 'no reason'})`
+          : 'judged again by the current reviewer and approved'}`);
+        continue;
+      }
+      _keptRejected = true;
+      refusal = `the copy this run was using was rejected by the reviewer: ${_v.reason}`;
+      log(`[prompt-builder] ! ${id}: the kept copy was REJECTED by the current reviewer (${_v.reason}) — regenerating`);
+      _heal(id, readJson(_tplPath(id)), _v.reason, _kept.body, 'rejected');
+    }
+    const template = readJson(_tplPath(id));
+    // Per-template, only when it could matter: a template whose seam name differs from its id is
+    // the one case where losing `seams` is visible at all. 36 of 37 hide the same rewrite.
+    if (Array.isArray(template.seams) && template.seams.some((sm) => sm !== template.id)) {
+      log(`[prompt-builder] ${id}: template declares seams ${JSON.stringify(template.seams)}`);
+    }
+    // REUSE, before any model time is spent.
+    const _base = baseDigest(template);
+    const _hit = cacheRead(id);
+    // A CACHE ENTRY IS ONLY A HIT IF IT PASSED THE GATES THAT APPLY NOW.
+    //
+    // The key was (template, generatorBody, contexts) and said nothing about REVIEW. So when
+    // review was finally switched on, 39 entries written while it was off were reused verbatim —
+    // never regenerated, therefore never reviewed — and the run logged "prompt review ENABLED"
+    // while reviewing almost nothing.
+    //
+    // Memoisation on inputs must also be keyed on the gates the artefact passed. An entry made
+    // without review is a MISS while review is on; one made WITH review stays a hit, so the cache
+    // keeps paying for itself.
+    const _reviewNow = typeof reviewPrompt === 'function';
+    // A kept copy the reviewer just rejected is not served back from the cache, which may hold it.
+    const _inputsSame = !_keptRejected && !!(_hit && _hit.base === _base && (!_hit.usesRoles || _hit.roles === rolesDigest));
+    // WHAT A CACHED, UNREVIEWED PROMPT LACKS IS A REVIEW — NOT A NEW PROMPT. It used to be
+    // regenerated "so it is reviewed": a paid generation repeated (on a resume, a step run twice)
+    // when only the reviewer had not answered. It is reviewed as it stands; regenerated only if
+    // that review finds a false claim.
+    let _useCached = _inputsSame && (!_reviewNow || _hit.reviewed === true);
+    if (_inputsSame && _reviewNow && _hit.reviewed !== true) {
+      const _late = await reviewPrompt({ id, template, generated: _hit.doc });
+      if (_late && _late.ok !== false) {
+        _hit.reviewed = _late.reviewed !== false;
+        cacheWrite(id, _hit);
+        log(`[prompt-builder] ${id}: cached copy ${_hit.reviewed ? 'reviewed now' : 'still unreviewed — the reviewer gave no verdict'} — reused, not regenerated`);
+        _useCached = true;
+      } else {
+        log(`[prompt-builder] ${id}: cached copy failed review (${(_late && _late.reason) || 'no reason'}) — regenerating`);
+        refusal = `the cached copy was rejected by the reviewer: ${(_late && _late.reason) || 'no reason'}`;
+        _heal(id, template, (_late && _late.reason) || 'rejected by the reviewer', _hit.doc && _hit.doc.body, 'rejected');
+      }
+    }
+    if (_useCached) {
+      fs.writeFileSync(path.join(outDir, `${id}.json`), JSON.stringify(_hit.doc, null, 2) + '\n');
+      built.push(id);
+      log(`[prompt-builder] reused ${id} (inputs unchanged${_hit.usesRoles ? ', roster unchanged' : ''})`);
+      continue;
+    }
+
+    let callFailure = '';
+    let installed = false;
+
+    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt += 1) {
+      // ONE TURN PER PART: a set that declares an answer budget gets the segments in groups that
+      // fit it (CodeMie web cuts a longer answer and calls it a success — measured 2026-09-30).
+      const _allSegments = require('./project-prompt-contract.js').splitByPlaceholders(templateBodyText(template)).segments;
+      const _plan = promptParts(_allSegments, answerBudgetChars());
+      const _parts = _plan.groups.map((g, index) => ({ index, of: _plan.groups.length, from: g.from, to: g.to,
+        texts: _plan.units.slice(g.from, g.to).map((u) => u.text) }));
+      const prompt = renderGeneratorPrompt({
+        generatorBody, template, projectContext, codelineContext, mintedRoles, refusal, part: _parts.length > 1 ? _parts[0] : null,
+      });
+      // A CALL THAT NEVER CAME BACK IS THE MOST RETRYABLE FAILURE THERE IS.
+      //
+      // This loop already retries a prompt that came back WRONG — a dropped placeholder is refused,
+      // the reason is fed back, the next attempt corrects it. A call that THREW escaped the loop
+      // entirely, out of buildProjectPrompts and out of the mint step.
+      //
+      // Live 2026-08-17, run 20260817T185759Z: "prompt runner timed out after 360000ms" destroyed
+      // the estate survey, the minted roster, the story assignment and 12 already-generated
+      // prompts — 30 minutes into the first run that had cleared every earlier stage correctly.
+      // One slow call out of 51.
+      //
+      // Nothing is known to be wrong with the request; it simply did not finish. So it costs one
+      // attempt, exactly as a refusal does — but stays DISTINGUISHABLE from one, because a
+      // contract refusal is fixed in the prompt and a failed call is fixed in the budget or the
+      // provider, and collapsing them sends the reader to the wrong file.
+      let body;
+      const _replies = [];
+      try {
+        body = String((await runText(prompt, { id, attempt })) || '');
+        _replies.push(body);
+        for (const part of _parts.slice(1)) {
+          _replies.push(String((await runText(renderGeneratorPrompt({
+            generatorBody, template, projectContext, codelineContext, mintedRoles, refusal, part,
+          }), { id, attempt })) || ''));
+        }
+      } catch (err) {
+        const why = (err && err.message) || String(err);
+        callFailure = why;
+        refusal = `the previous attempt did not come back: ${why}. Nothing was found wrong with `
+          + 'your answer — it never arrived. Produce the same prompt again.';
+        log(`[prompt-builder] ! ${id} attempt ${attempt}/${attempts} CALL FAILED: ${why}`);
+        continue;
+      }
+      // THE PIPELINE ASSEMBLES THE BODY; THE MODEL ONLY WORDS THE PROSE.
+      //
+      // The reply is {"segments":[...]} — the prose between placeholders, in order. The slots are
+      // put back here, in their original positions, so nothing the model wrote can drop or invent
+      // one. Every contract invariant below then holds by construction rather than by retry.
+      //
+      // A reply that is not parseable segments costs one attempt, exactly like any other refusal,
+      // and says so precisely: the fix for "wrong segment count" is in the prompt, and the reader
+      // must not be sent looking for a dropped placeholder that cannot happen any more.
+      let assembled;
+      try {
+        const { splitByPlaceholders, assembleFromSegments, parseSegmentsReply } =
+          require('./project-prompt-contract.js');
+        const { slots } = splitByPlaceholders(templateBodyText(template));
+        // DELIMITED, NOT JSON. Escaping 7kB of prose containing quotes, commas and newlines is
+        // where the JSON form broke — team-lead-review burned five attempts on replies that were
+        // complete but unparseable. parseSegmentsReply reads the same marker shape the prompt
+        // shows, tolerates a false start by taking the last complete set, and still accepts JSON.
+        // Each part's reply carries its own segments; together, in order, they are the whole.
+        const parsed = _parts.length === 1
+          ? parseSegmentsReply(body, slots.length + 1)
+          : segmentsFromUnits(_plan.units, _parts.flatMap((part, i) => parseSegmentsReply(_replies[i], part.to - part.from)), slots.length + 1);
+        assembled = assembleFromSegments(parsed, slots);
+      } catch (err) {
+        refusal = `your answer could not be assembled: ${(err && err.message) || String(err)}. `
+          + 'Reply with one --- SEGMENT n --- marker per segment shown, in order, each followed by '
+          + 'your wording, closing with --- END SEGMENTS ---. Plain text, no JSON, no code fences, '
+          + 'and no placeholder tokens.';
+        log(`[prompt-builder] ! ${id} attempt ${attempt}/${attempts} refused: ${refusal}`);
+        continue;
+      }
+      const doc = buildGeneratedDoc(template, assembled);
+      const verdict = checkGeneratedPrompt(template, doc);
+
+      if (verdict.ok) {
+        // THE CONTRACT CHECK PROVES IT IS WIREABLE, NOT THAT IT IS TRUE.
+        //
+        // checkGeneratedPrompt verifies placeholders in and out. A derivative can satisfy that
+        // completely and still tell an agent this codeline's tests live in a directory it does
+        // not have, or that a dependency is present when it is not — and install cleanly, because
+        // every placeholder was in the right place. The agent then inherits the claim as
+        // instruction and nothing later questions it.
+        //
+        // The roster already gets this treatment: roster-review reads the repositories and
+        // falsifies a generated brief before any implementer inherits it. reviewPrompt is that
+        // reviewer pointed at prompts. It is OPTIONAL — a caller that supplies none provisions
+        // exactly as before, so this cannot block a project that has not adopted it.
+        let review = null;
+        if (typeof reviewPrompt === 'function') {
+          review = await reviewPrompt({ id, template, generated: doc });
+          if (review && review.ok === false) {
+            refusal = `a review of this prompt found claims about the project that are false: ${review.reason}`;
+            log(`[prompt-builder] ! ${id} attempt ${attempt}/${attempts} REVIEW REJECTED: ${review.reason}`);
+            // EVERY REJECTION REACHES THE ANALYST, with the prompt that was rejected — a review
+            // rejection is an agent failure like a contract refusal, and only reached the retry.
+            _heal(id, template, review.reason, doc.body, 'rejected');
+            continue;
+          }
+        }
+
+        // Written only once the contract passes AND the review found nothing false — never a
+        // partial, a refused, or an unreviewed-but-rejected prompt.
+        doc.judgedWith = _judges();
+        fs.writeFileSync(path.join(outDir, `${id}.json`), JSON.stringify(doc, null, 2) + '\n');
+        built.push(id);
+        installed = true;
+        // Whether this template's OUTPUT depends on the roster is decided by looking at what it
+        // produced, not guessed from what it was handed.
+        cacheWrite(id, { base: _base, roles: rolesDigest, usesRoles: usesRoles(doc, mintedRoles), doc,
+          // Whether a reviewer actually JUDGED it — not whether one was configured. A review that
+          // produced no verdict recorded `reviewed: true` here, and a later run reused the prompt as
+          // reviewed (found 2026-09-25).
+          reviewed: !!(review && review.reviewed !== false) });
+        log(`[prompt-builder] generated ${id} (attempt ${attempt}/${attempts})`);
+        break;
+      }
+      refusal = verdict.reason;
+      // THE REFUSED TEXT IS THE ONLY EVIDENCE OF WHY, AND IT WAS THROWN AWAY.
+      //
+      // The log records WHICH placeholders went missing; the model's actual answer — the thing
+      // that would say whether it emitted JSON, truncated, or rewrote the body — was discarded
+      // the moment the verdict came back. Run 20260827T092415Z aborted on 'tc-writer' after three
+      // refusals and left nothing to read, so the cause had to be inferred from the symptom. The
+      // comment at the top of this file records the same blindness misdiagnosing runs 9 and 10.
+      //
+      // Generated output must be persisted — a refused artefact most of all, because it is the
+      // only one nobody can regenerate by rerunning a step that now succeeds.
+      try {
+        const refusedDir = path.join(outDir, '.refused');
+        fs.mkdirSync(refusedDir, { recursive: true });
+        fs.writeFileSync(
+          path.join(refusedDir, `${id}.attempt-${attempt}.txt`),
+          `# refused: ${verdict.reason}\n`
+          + `# template: ${id}   attempt: ${attempt}/${attempts}\n`
+          + `# required placeholders: ${(template.placeholders || []).join(', ') || '(none)'}\n`
+          + `# ---------------- model reply below, verbatim ----------------\n`
+          + body);
+      } catch (e) {
+        // Never let evidence-keeping break the build it is evidence about.
+        log(`[prompt-builder] (could not persist refused ${id} attempt ${attempt}: ${e.message})`);
+      }
+      // THE ANALYST SEES THE REFUSED PROMPT ITSELF, not just which placeholder went missing.
+      // Seven generations were refused across runs 13 and 14 and none reached self-heal.
+      _heal(id, template, verdict.reason, body);
+      log(`[prompt-builder] ! ${id} attempt ${attempt}/${attempts} refused: ${verdict.reason}`);
+    }
+
+    if (!installed) {
+      // No fallback. The template is never executed, so there is nothing to degrade to, and
+      // a project missing one prompt must not look provisioned.
+      throw new Error(
+        `[prompt-builder] could not generate a valid '${id}' in ${attempts} attempt(s). `
+        + (callFailure
+          ? `The call itself failed: ${callFailure}. That is a budget or provider problem, not a `
+            + 'prompt one — check the seam\'s declared timeoutSecs before changing the template.'
+          : `Last refusal: ${refusal}`));
+    }
+  }
+
+  // EVERY PROMPT INSTALLED — say so, so the next run against this codeline reuses them.
+  //
+  // Reaching this line is the proof: the loop above THROWS when a prompt cannot be
+  // installed within its attempts ('a project missing one prompt must not look
+  // provisioned'), so there is no partial path to here. The marker records that fact
+  // rather than forming a second opinion that could disagree with it.
+  //
+  // Untagged is unusable: with no codeline the marker is not written at all, because a
+  // marker any codeline could claim is the cross-codeline reuse pre-run-reset refuses.
+  // A STORY OF SEVERAL CODELINES RECORDS ITS SET FOR EVERY ONE OF THEM (operator, 2026-10-22: "prompts/profiles BY codeline";
+  // "Reuse over codelines is fine"): each codeline of the story gets its own recorded set — the same set, reused — so every lane
+  // works from its own codeline's folder (lane_codeline_set_restore) and the mint is reused only when every codeline has one.
+  for (const codeline of (safeCodeline ? [safeCodeline] : codelinesFromPrd(process.env.PRD_FILE))) {
+    writeCompletionMarker({
+      outDir,
+      // THE SAME codeline the entries were filed under. A marker naming one codeline while
+      // the cache holds another lets the mint gate skip against a set it never checked.
+      codeline,
+      provisioned: copied.length + built.length,
+      // WHAT THESE PROMPTS WERE BUILT FROM, so the next launch can tell whether they still are.
+      templatesDir,
+      registryFile,
+    });
+  }
+
+  return { copied, generated: built };
+}
+
+/**
+ * promptInputsDigest({ templatesDir, registryFile }) — a digest of everything the project's
+ * prompts are built FROM: every template in the layer, the seam registry, and this builder's own
+ * generator. Two launches with the same digest would build byte-identical prompts.
+ *
+ * regintel 20260920T232518Z ($5.73, 2026-09-20): the completion marker was an empty file — it
+ * recorded that a build happened, not what it was built from — so a launch after a day of
+ * template changes reused prompts built from the previous day's templates, and four fixes were
+ * inert ("given values it does not use: __SHARED_FILE_OWNERSHIP_BLOCK__ … DROPPED").
+ */
+function promptInputsDigest({ templatesDir, registryFile } = {}) {
+  const h = crypto.createHash('sha256');
+  const dir = templatesDir || path.join(__dirname, '..', '..', 'prompts', 'templates');
+  const reg = registryFile || path.join(__dirname, '..', '..', 'agents', 'invocation-profiles.json');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort(); } catch { names = []; }
+  // ONLY THE TEMPLATES THIS BUILDER READS (AMSD-2974 run 9 iteration 3, 2026-10-13): the digest covered every file in
+  // the layer, so adding release-line-port — an engine template no project prompt is built from — made every kept
+  // prompt of the run "changed" and sent all 44 back to the reviewer, paid, mid-run. The inputs are the ones the build
+  // itself provisions (bootstrap.copyVerbatim, provisioningList) and the variant each resolves to; a bootstrap that
+  // cannot be read leaves the whole layer in, as before.
+  const _inputs = promptInputIds({ dir, registryFile: reg });
+  if (_inputs) names = names.filter((n) => _inputs.has(n.replace(/\.json$/, '')));
+  for (const n of names) {
+    h.update(n); h.update('\0');
+    try { h.update(fs.readFileSync(path.join(dir, n))); } catch { /* absent counts as absent */ }
+    h.update('\0');
+  }
+  try { h.update('registry\0'); h.update(fs.readFileSync(reg)); } catch { /* none */ }
+  try { h.update('builder\0'); h.update(fs.readFileSync(__filename)); } catch { /* none */ }
+  return h.digest('hex');
+}
+
+/**
+ * promptInputIds({ dir, registryFile }) — the template ids a build reads: bootstrap.copyVerbatim, the provisioning list
+ * (the same provisioningList the build uses) and the variant each resolves to for this run. null when the bootstrap
+ * beside the templates cannot be read.
+ */
+function promptInputIds({ dir, registryFile }) {
+  let boot;
+  try { boot = readJson(path.join(dir, '..', 'bootstrap.json')); } catch { return null; }
+  let registry = {};
+  try { registry = readJson(registryFile); } catch { registry = {}; }
+  const exists = (id) => fs.existsSync(path.join(dir, `${id}.json`));
+  const ids = new Set();
+  const copy = Array.isArray(boot.copyVerbatim) ? boot.copyVerbatim : [];
+  for (const id of [...copy, ...provisioningList({ bootstrap: boot, registry, templateExists: exists })]) {
+    ids.add(id);
+    ids.add(variantIdFor(id, exists));
+  }
+  return ids;
+}
+
+/**
+ * codelinePromptsComplete({ projectConfigDir, codeline, templatesDir, registryFile }) — whether
+ * the prompts on disk for this codeline were built from the CURRENT inputs. An empty marker (the
+ * old shape) proves nothing and reads as not complete. Returns { complete, reason }.
+ */
+function codelinePromptsComplete({ projectConfigDir, codeline, templatesDir, registryFile } = {}) {
+  if (!projectConfigDir || !codeline) return { complete: false, reason: 'no project or codeline named' };
+  const variant = process.env.EPAM_BROWNFIELD === '1' ? BROWNFIELD_VARIANT : '';
+  const p = path.join(projectConfigDir, '.prompt-cache', `.complete-${String(codeline).trim()}${variant}`);
+  let stored = '';
+  try { stored = fs.readFileSync(p, 'utf8').trim(); } catch { return { complete: false, reason: `no completion marker at ${p}` }; }
+  if (!stored) return { complete: false, reason: 'the completion marker is empty — it records that a build happened, not what it was built from; rebuilding from the current templates' };
+  const now = promptInputsDigest({ templatesDir, registryFile });
+  if (stored !== now) return { complete: false, reason: `the prompt inputs changed since these prompts were built (template layer, registry or generator: ${stored.slice(0, 12)} → ${now.slice(0, 12)}) — rebuilding the changed prompts; the roster is kept` };
+  return { complete: true, reason: 'prompt inputs unchanged since the build' };
+}
+
+/**
+ * THE MINT'S OUTPUTS — the files a codeline's agents live in. Defined HERE, once: the mint's clean
+ * slate (lib/mint-and-spec.sh, via mintedFiles) clears exactly these, and a completion records
+ * exactly these. Per project on disk; per codeline in the cache, as the prompts are.
+ */
+const MINTED_FILES = ['roster.json', 'project-roles.json', 'project-investigators.json', 'agent-profiles.json'];
+
+/** The marker-name suffix of a brownfield provisioning (kept in step with lib/prompt-variant.sh). */
+const BROWNFIELD_VARIANT = '.brownfield';
+
+/** Where a codeline's completion records the prompts it installed — beside its recorded agents. */
+function recordedPromptsDir(projectConfigDir, codeline) {
+  return path.join(String(projectConfigDir || ''), '.prompt-cache', codelineSegment(codeline) || '_', 'prompts');
+}
+
+function mintedSnapshotDir(projectConfigDir, codeline) {
+  return path.join(String(projectConfigDir || ''), '.prompt-cache', codelineSegment(codeline) || '_', 'minted');
+}
+
+function hasMintedSnapshot({ projectConfigDir, codeline } = {}) {
+  const d = mintedSnapshotDir(projectConfigDir, codeline);
+  return fs.existsSync(d) && fs.readdirSync(d).some((f) => MINTED_FILES.includes(f));
+}
+
+/**
+ * Record the minted files on disk as THIS codeline's (replacing any earlier record). None on disk
+ * records none — the prompts may still be complete, but their agents can then never be reused.
+ */
+function snapshotMinted({ projectConfigDir, codeline }) {
+  const d = mintedSnapshotDir(projectConfigDir, codeline);
+  fs.rmSync(d, { recursive: true, force: true });
+  fs.mkdirSync(d, { recursive: true });
+  let n = 0;
+  for (const f of MINTED_FILES) {
+    const src = path.join(projectConfigDir, f);
+    if (fs.existsSync(src)) { fs.copyFileSync(src, path.join(d, f)); n += 1; }
+  }
+  if (!n) fs.rmSync(d, { recursive: true, force: true });
+  return n;
+}
+
+/**
+ * Put THIS codeline's recorded agents on disk — every minted file it recorded, and none another
+ * codeline left behind. Returns false (touching nothing) when the codeline recorded none.
+ */
+function restoreMinted({ projectConfigDir, codeline } = {}) {
+  if (!hasMintedSnapshot({ projectConfigDir, codeline })) return false;
+  const d = mintedSnapshotDir(projectConfigDir, codeline);
+  for (const f of MINTED_FILES) {
+    const rec = path.join(d, f); const dst = path.join(projectConfigDir, f);
+    if (fs.existsSync(rec)) fs.copyFileSync(rec, dst); else fs.rmSync(dst, { force: true });
+  }
+  // AND ITS PROMPTS: prompts/ is one directory per project, so another codeline's may be on disk.
+  // Exactly the recorded set — none another codeline left behind.
+  const rp = recordedPromptsDir(projectConfigDir, codeline);
+  if (fs.existsSync(rp)) {
+    const out = path.join(projectConfigDir, 'prompts');
+    fs.rmSync(out, { recursive: true, force: true });
+    fs.mkdirSync(out, { recursive: true });
+    for (const f of fs.readdirSync(rp).filter((n) => n.endsWith('.json'))) fs.copyFileSync(path.join(rp, f), path.join(out, f));
+  }
+  return true;
+}
+
+/** The mint's clean slate: every minted file, removed. */
+function clearMinted({ projectConfigDir } = {}) {
+  for (const f of MINTED_FILES) fs.rmSync(path.join(String(projectConfigDir || ''), f), { force: true });
+}
+
+/**
+ * WHERE THE COMPLETION MARKER LIVES — beside the cache, never inside prompts/.
+ *
+ * pre-run-reset deletes and recreates prompts/ on any run that is not reusing, so a marker in
+ * there could never survive to be read by the run that needs it.
+ */
+function _markerPath(outDir, codeline) {
+  // THE CODELINE IS THE FILENAME, and the file is empty.
+  //
+  // This was a JSON document carrying {codeline, provisioned, refused} that the consumer parsed
+  // and compared field by field. Every one of those fields was redundant: the producer only runs
+  // after EVERY prompt installed (it throws otherwise), so the file's EXISTENCE already proves
+  // completeness, and putting the codeline in the NAME turns "does it match?" into "does it
+  // exist?". That deletes the parse, the field comparison, and the corrupt-marker case — a file
+  // with no content cannot be malformed.
+  // THE VARIANT IS PART OF THE CLAIM. The marker makes the mint skip ENTIRELY (four call sites),
+  // so without this a codeline provisioned greenfield would skip provisioning on the next
+  // brownfield run and serve the greenfield prompts sitting on disk — on a cached codeline, the
+  // normal case, the brownfield variant would never once execute.
+  //
+  // Greenfield's name is unchanged, byte for byte, so no marker already on disk is invalidated.
+  // Kept in step with prompt_marker_key in lib/prompt-variant.sh, which the shell call sites use.
+  const variant = process.env.EPAM_BROWNFIELD === '1' ? BROWNFIELD_VARIANT : '';
+  return path.join(outDir, '..', '.prompt-cache', `.complete-${codeline}${variant}`);
+}
+
+/**
+ * RECORD THAT THIS CODELINE'S PROMPTS ARE COMPLETE, so the next run reuses them.
+ *
+ * Operator, 2026-09-05: "not regenerated unless there is an override for the codeline to
+ * regenerate", and "if prompts complete this run we consider for the cache".
+ *
+ * The fact is already established by control flow — buildProjectPrompts THROWS when a prompt
+ * cannot be installed, so reaching the end means every one of them was. This writes that down
+ * rather than forming a second opinion that could disagree with it.
+ *
+ * UNTAGGED IS UNUSABLE. Without a codeline the marker would be honoured by whichever codeline ran
+ * next, which is exactly the cross-codeline reuse the consumer refuses — so it writes nothing.
+ *
+ * NEVER THROWS. The marker is a cost optimisation; the worst case of losing it is that the next
+ * run regenerates, which is today's behaviour. Failing a provisioned run over it would trade a
+ * saving for an outage.
+ */
+function writeCompletionMarker({ outDir, codeline, provisioned, templatesDir, registryFile } = {}) {
+  try {
+    if (!outDir) return;
+    if (!codeline || !String(codeline).trim()) return;
+    if (!(Number(provisioned) > 0)) return;
+    const p = _markerPath(outDir, String(codeline).trim());
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    // The agents this codeline was provisioned with, recorded beside its prompts. The mint keeps a
+    // codeline's agents only by restoring this record (codeline_minted_restore) — a marker alone
+    // says the prompts are complete, never whose agents are on disk.
+    snapshotMinted({ projectConfigDir: path.join(outDir, '..'), codeline: String(codeline).trim() });
+    const rp = recordedPromptsDir(path.join(outDir, '..'), String(codeline).trim());
+    fs.rmSync(rp, { recursive: true, force: true });
+    fs.mkdirSync(rp, { recursive: true });
+    for (const f of fs.readdirSync(outDir).filter((n) => n.endsWith('.json'))) fs.copyFileSync(path.join(outDir, f), path.join(rp, f));
+    // The digest of what was built from — never an empty file (see promptInputsDigest).
+    fs.writeFileSync(p, promptInputsDigest({ templatesDir, registryFile }) + '\n');
+  } catch { /* an optimisation must never fail the run it optimises */ }
+}
+
+/**
+ * DROP THE PREVIOUS RUN'S MARKER BEFORE THIS RUN PROVISIONS.
+ *
+ * The dangerous ordering, and the reason this exists separately: this run wipes prompts/ and
+ * starts regenerating. If it dies partway, a marker left by the LAST run still reads "complete",
+ * and the NEXT run inherits a half-written set as though it were finished. Cleared on the way in,
+ * rewritten only on the way out.
+ */
+function clearCompletionMarker({ outDir, codeline } = {}) {
+  try {
+    if (!outDir) return;
+    const dir = path.join(outDir, '..', '.prompt-cache');
+    // THIS CODELINE'S CLAIM, in either variant: its prompts are being rewritten. Another codeline's
+    // completion recorded its own agents and prompts, and the mint restores them when it keeps
+    // that codeline — so its claim stays true. With no codeline named, no claim is provably
+    // unaffected: every one goes.
+    const cl = String(codeline || '').trim();
+    const mine = cl ? [`.complete-${cl}`, `.complete-${cl}${BROWNFIELD_VARIANT}`] : null;
+    for (const n of (fs.existsSync(dir) ? fs.readdirSync(dir) : [])) {
+      if (!n.startsWith('.complete-')) continue;
+      if (!mine || mine.includes(n)) fs.rmSync(path.join(dir, n), { force: true });
+    }
+  } catch { /* best effort, same reasoning as above */ }
+}
+
+module.exports = { buildProjectPrompts, healContext, renderGeneratorPrompt, provisioningList, rolesIdentity, GEN_BODY_SLOT,
+  PROJECT_PROMPT_GENERATOR_ID, answerBudgetChars, promptParts,
+  writeCompletionMarker, clearCompletionMarker, promptInputsDigest, codelinePromptsComplete,
+  MINTED_FILES, mintedSnapshotDir, recordedPromptsDir, hasMintedSnapshot, restoreMinted, clearMinted,
+  // Exported so the codeline keying is assertable without provisioning: a segment that escapes
+  // the cache directory is a defect no end-to-end assertion would localise.
+  codelineSegment, migrateFlatEntries, codelineFromPrd, codelinesFromPrd, codelineOfPrd, scopeCodelineFromPrd, restoreCodelineSet, codelineSetsIdentical, codelineSetComplete,
+  // Exported so the prompt REVIEWER reads a template the same way the generator and the
+  // contract check do. Three readers of one shape is how the last three of these drifted.
+  templateBodyText };