amsd-pipeline-shared 0.5.11 → 0.5.13

package/orchestrations/prompts/templates/worktree-autocommit-message.json

@@ -0,0 +1,27 @@
+{
+  "$why": [
+    "Moved out of worktree-health-check.sh on 2026-08-16.",
+    "",
+    "Not a prompt — no model receives it. It is the commit message the health check writes when an",
+    "agent produced files and did not commit them, and it is PROSE: a human reads it in git log,",
+    "months later, trying to work out why a commit exists that no agent claims.",
+    "",
+    "Text a person reads belongs in the template layer for the same reason a prompt does. As a",
+    "heredoc it could not be reviewed, diffed against the other things the engine says, or changed",
+    "without editing a shell script — and the attribution line at the bottom had gone stale where",
+    "nobody could see it."
+  ],
+  "description": "The commit message written when an agent leaves its output uncommitted.",
+  "seams": [],
+  "consumer": "engine",
+  "id": "worktree-autocommit-message",
+  "version": 1,
+  "body": "chore(wt-__LANE__): auto-commit agent output for phase __PHASE__\n\nAutomated commit of __CHANGED_COUNT__ file(s) produced by the __LANE__ agent.\nPhase: __PHASE__\nLane: __LANE__\nTimestamp: __TIMESTAMP__\n\nWARNING: this was auto-committed by worktree-health-check.sh because the agent\ndid not commit its own changes. Review these files.\n\nCo-Authored-By: __AUTHOR__\n",
+  "placeholders": [
+    "__LANE__",
+    "__PHASE__",
+    "__CHANGED_COUNT__",
+    "__TIMESTAMP__",
+    "__AUTHOR__"
+  ]
+}

package/orchestrations/prompts/templates/writer-codegraph-block.json

@@ -0,0 +1,25 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16.",
+    "",
+    "Three mutually exclusive states, each a different instruction to the writer: the helper to",
+    "reuse is already identified, the prescribed fix is known to be incomplete, or nothing is",
+    "known and here is the tool to find out. One body each — collapsing them would tell a writer",
+    "a helper was found when none was."
+  ],
+  "description": "Tells the writer what CodeGraph already established about the fix, or how to query it.",
+  "seams": [
+    "story-writer"
+  ],
+  "id": "writer-codegraph-block",
+  "version": 1,
+  "bodies": {
+    "helper_identified": "## The helper to reuse is ALREADY identified — do NOT search\nThe Root Cause Analysis above names the exact existing helper(s) to reuse: `__PRESCRIBED_HELPER__`. EVERY ONE of them must be imported and called — a write that uses some but not all is rejected at write time for the ones it omitted, and the rejection names only what was missed. Do NOT run CodeGraph or explore the codebase to re-find them — that wastes your turn budget. Import them, apply the prescribed minimal fix, write your file(s), and stop. Only search if you hit something the prescribed fix genuinely does not cover.",
+    "fix_incomplete": "## The prescribed fix is KNOWN INCOMPLETE — explore for the rest\nThe Root Cause Analysis above names existing helper(s) to reuse: `__PRESCRIBED_HELPER__` — apply those parts directly and use EVERY one of them, do NOT re-search for them. But the prescribed fix does NOT address every verification criterion. These are UNCOVERED and need your own investigation beyond the prescribed sites:\n__UNCOVERED_LIST__\nUse the codegraph_query tool (mode=\"helpers\", args=\"<domain nouns>\") to find existing code for THESE before writing new logic — do not assume they are out of scope.",
+    "tool_available": "## CodeGraph Tool — find EXISTING functions to reuse (do this BEFORE writing any new helper)\nA codegraph_query tool is available — call it directly (NOT via Bash) to discover reusable functions instead of inventing new ones:\n  codegraph_query(mode=\"helpers\", args=\"<domain nouns>\")   # existing util/parser/formatter to REUSE (symbol + import path)\n  codegraph_query(mode=\"query\", args=\"<SymbolName>\")       # exact definition site of a symbol\n  codegraph_query(mode=\"callees\", args=\"<SymbolName>\")     # what a function already calls\nRULE: Before you add ANY new function, run `helpers` for what it would do. If a suitable function already exists, import and call it — do NOT duplicate it. Fewer lines of code is always better."
+  },
+  "placeholders": [
+    "__PRESCRIBED_HELPER__",
+    "__UNCOVERED_LIST__"
+  ]
+}

package/orchestrations/prompts/templates/writer-plan-section.json

@@ -0,0 +1,28 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16.",
+    "",
+    "Two sections appended to the writer's prompt: the execution plan it must follow, and the coordinator guidance identified from a previous failure. Both appear at more than one call site and were written out separately at each.",
+    "",
+    "The guidance section has two variants: one carries the whole amendment, the other the most recent three with the rest left in the log. That second one DECLARES its own truncation in the heading, which is the honest form -- whole entries dropped and said so, rather than a string cut mid-sentence."
+  ],
+  "description": "Sections appended to a writer prompt: the plan to follow, and guidance from a previous failure.",
+  "seams": [
+    "story-writer"
+  ],
+  "id": "writer-plan-section",
+  "version": 1,
+  "bodies": {
+    "coordinator_guidance_full": "__PROMPT__\n\n## Coordinator Guidance (retry __RETRY_COUNT__)\nThe following targeted instruction was identified from the previous failure:\n__COORDINATOR_PROMPT_AMENDMENT__",
+    "coordinator_guidance_trimmed": "__PROMPT__\n\n## Coordinator Guidance (retry __RETRY_COUNT__, showing most recent up to 3 — full retry history: __SCRATCHPAD_FILE__)\n__TRIMMED_AMENDMENT__",
+    "execution_plan": "__PROMPT__\n\n## Execution Plan\nFollow this plan step by step:\n__STORY_PLAN__"
+  },
+  "placeholders": [
+    "__COORDINATOR_PROMPT_AMENDMENT__",
+    "__RETRY_COUNT__",
+    "__PROMPT__",
+    "__TRIMMED_AMENDMENT__",
+    "__SCRATCHPAD_FILE__",
+    "__STORY_PLAN__"
+  ]
+}

package/orchestrations/prompts/templates/writer-string-invariants.json

@@ -0,0 +1,17 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16. Names the string literals a change must not disturb.",
+    "",
+    "The list was formatted inside the prompt by a sed pipeline. The caller formats it and passes it: a prompt that runs a shell pipeline to lay out its own content cannot be read as prose, which is what this layer exists for."
+  ],
+  "description": "Tells the writer which string literals in the target file must not change.",
+  "seams": [
+    "story-writer"
+  ],
+  "id": "writer-string-invariants",
+  "version": 1,
+  "body": "\n## CRITICAL COMPLIANCE: STRING INVARIANTS\nThe Acceptance Criteria above contain exact string matches required by the test suite.\nYou are FORBIDDEN from paraphrasing, summarizing, or optimizing these strings — reproduce them character-for-character, including case and spacing, wherever the AC requires them.\n\nLITERAL STRINGS TO USE VERBATIM:\n__STRING_LIST__\n",
+  "placeholders": [
+    "__STRING_LIST__"
+  ]
+}

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

@@ -0,0 +1,414 @@
+#!/usr/bin/env node
+/**
+ * THE CONTRACT A GENERATED PROJECT PROMPT MUST HONOUR.
+ *
+ * Templates are generic and immutable. The project-authority copy is generated from one and
+ * is the ONLY thing prompt-library.js will render — there is no fallback to the template, by
+ * operator mandate, because a silent degrade runs an engine-embedded default for a whole
+ * campaign without anyone noticing.
+ *
+ * WHY THIS IS CODE AND NOT AN INSTRUCTION IN THE PROMPT. Rendering is strict in both
+ * directions: every declared placeholder must appear in the body, every placeholder in the
+ * body must be declared, and every one must be supplied at render time. A generator that
+ * adds, drops or renames a single placeholder therefore produces a prompt that does not
+ * degrade — it THROWS, mid-run, after the roster is minted and the run is already spending.
+ * Asking a model nicely to preserve placeholders is not a guarantee; checking its output is.
+ *
+ * The check runs at GENERATION time so the failure names the generator, rather than surfacing
+ * three stages later at whichever seam happened to need that prompt.
+ */
+'use strict';
+
+const crypto = require('crypto');
+
+// ONE DEFINITION, IMPORTED — not a second copy of the rule.
+//
+// This file carried its own placeholder regex, and it was the GREEDY version. engine-prompt.js
+// was fixed to match lazily so that adjacent placeholders (__A____B__, which is what ${a}${b}
+// becomes) read as two, and this copy was not — so the contract saw seven adjacent blocks as
+// one token and refused every generated spec-agent-openspec as "dropping placeholders" the
+// template required. Two copies of a rule is two rules.
+const { placeholdersIn: _placeholdersIn } = require('./engine-prompt.js');
+
+/** Placeholders present in a body, deduped and sorted. */
+function placeholdersIn(body) {
+  return [..._placeholdersIn(body)].sort();
+}
+
+const sorted = (a) => [...(Array.isArray(a) ? a : [])].sort();
+const missingFrom = (want, have) => want.filter((p) => !have.includes(p));
+
+/**
+ * Is this generated prompt safe to install as the project authority?
+ *
+ * @param {{id:string, body:string, placeholders:string[]}} template  the generic source
+ * @param {{id:string, body:string, placeholders:string[]}} generated the model's output
+ * @returns {{ok:boolean, reason:string}}  reason NAMES the offending placeholders — a bare
+ *          "invalid" leaves the operator diffing two prompts by eye.
+ */
+function checkGeneratedPrompt(template, generated) {
+  if (!generated || typeof generated.body !== 'string' || !generated.body.trim()) {
+    return { ok: false, reason: 'the generated prompt has an empty body — nothing would be sent' };
+  }
+
+  const tplWanted = sorted(template && template.placeholders);
+  const genUsed = placeholdersIn(generated.body);
+  const genDeclared = sorted(generated.placeholders);
+
+  // 1. Every value the pipeline supplies must still have somewhere to land.
+  const dropped = missingFrom(tplWanted, genUsed);
+  if (dropped.length) {
+    return {
+      ok: false,
+      reason: `the generated prompt dropped placeholder(s) the template requires: ${dropped.join(', ')}. `
+        + 'The evidence they carry would silently never reach the agent.',
+    };
+  }
+
+  // 2. Nothing may be invented: render supplies values by NAME, so an unknown placeholder is
+  //    never substituted and prompt-library throws "still contains placeholders after rendering".
+  const invented = missingFrom(genUsed, tplWanted);
+  if (invented.length) {
+    return {
+      ok: false,
+      reason: `the generated prompt invented placeholder(s) nothing supplies: ${invented.join(', ')}. `
+        + 'Rendering would throw at the seam that needs this prompt.',
+    };
+  }
+
+  // 3. The declaration must match the body, in both directions — prompt-library enforces this
+  //    at render time, and catching it here names the generator instead of the seam.
+  const undeclared = missingFrom(genUsed, genDeclared);
+  if (undeclared.length) {
+    return { ok: false, reason: `body uses undeclared placeholder(s): ${undeclared.join(', ')}` };
+  }
+  const orphan = missingFrom(genDeclared, genUsed);
+  if (orphan.length) {
+    return { ok: false, reason: `declares placeholder(s) it never uses: ${orphan.join(', ')}` };
+  }
+
+  // 4. THE OUTPUT CONTRACT MUST SURVIVE GENERATION.
+  //
+  // A generated prompt may specialise anything about HOW an agent works — this project's
+  // codelines, its stack, its tools. It may not change what an ANSWER looks like, because the
+  // consumer that reads the answer was not regenerated with it.
+  //
+  // Checked because two real generations shipped without it. prompt-review lost
+  // <PROMPT_REVIEW>{"falseClaims": []}</PROMPT_REVIEW> while lib/prompt-review.js parses exactly
+  // that tag, so the reviewer's answer could never be read. skill-assessment-prephase lost every
+  // output key and came back half the length. Both are the run-8 shape: the agent obeys its
+  // prompt and the engine reads something else, and nothing can say which side is wrong.
+  //
+  // ADDITIONS ARE FINE. Only a LOSS is refused: the consumer still reads what the template
+  // promised, so dropping it is what breaks.
+  const tplBody = String((template && template.body) || Object.values((template && template.bodies) || {}).join('\n') || '');
+  const genBody = generated.body;
+
+  // Response tags — <PROMPT_REVIEW>, <SPEC_AGENT> — are how a consumer finds the answer at all.
+  // A RESPONSE TAG IS PAIRED. A VALUE PLACEHOLDER IS NOT.
+  //
+  // This took every <UPPERCASE> in the body. skill-assessment-prephase's instructions contain an
+  // example JSONL record — {"timestamp":"<ISO8601>", ...} — where <ISO8601> is a TYPE placeholder
+  // inside an illustration, not a marker any consumer looks for. The guard demanded the generated
+  // prompt reproduce it verbatim, the generator legitimately rephrased the example, and mock3
+  // run 9 exhausted all three attempts and failed the step after 29 prompts had succeeded.
+  //
+  // A tag a consumer parses always wraps something: <PROMPT_REVIEW>…</PROMPT_REVIEW>. Across all
+  // 117 templates that separates them exactly — 4 paired (DISCOVERY_VOCABULARY, MODEL_REVIEW,
+  // PROMPT_REVIEW, SPEC_REVIEW), 1 unpaired (ISO8601). So pairing is the discriminator, and it is
+  // derived from the template rather than an exception list that would go stale.
+  const tplTags = [...new Set(tplBody.match(/<[A-Z][A-Z0-9_]+>/g) || [])]
+    .filter((t) => tplBody.includes(`</${t.slice(1, -1)}>`))
+    .flatMap((t) => [t, `</${t.slice(1, -1)}>`]);
+  const lostTags = tplTags.filter((t) => !genBody.includes(t));
+  if (lostTags.length) {
+    return {
+      ok: false,
+      reason: `the generated prompt dropped the output tag(s) the template states: ${lostTags.join(', ')}. `
+        + 'The consumer looks for exactly that marker, so the answer would be unreadable however '
+        + 'good it is.',
+    };
+  }
+
+  // Field names the template states as part of its response shape.
+  const tplKeys = outputFieldsIn(tplBody);
+  const lostKeys = tplKeys.filter((k) => !genBody.includes(k));
+  if (lostKeys.length) {
+    return {
+      ok: false,
+      reason: `the generated prompt dropped output field(s) the template states: ${lostKeys.join(', ')}. `
+        + 'The consumer still reads them, so the agent would answer a shape nothing accepts.',
+    };
+  }
+
+  return { ok: true, reason: '' };
+}
+
+/**
+ * THE RESPONSE-SHAPE FIELD NAMES A TEMPLATE STATES.
+ *
+ * Defined once and exported, because two places need the same answer: this contract check, which
+ * REFUSES a generated prompt that lost a field, and the generator prompt, which must be TOLD the
+ * fields so it can keep them. Judging an agent against a list it was never shown is how
+ * skill-assessment-prephase came back missing timestamp, phase_id, agent_role, event,
+ * skill_category, context and added_by — the generator prompt gave placeholders their own section
+ * and an explicit list, and gave output fields one clause in the middle of a sentence.
+ */
+function outputFieldsIn(body) {
+  return [...new Set((String(body == null ? '' : body).match(/"([a-zA-Z][a-zA-Z0-9_]*)"\s*:/g) || [])
+    .map((m) => m.replace(/[":\s]/g, '')))];
+}
+
+/**
+ * Assemble the document to write as the project authority.
+ *
+ * derivedFromSha256 is taken over the TEMPLATE, so a later run can tell whether the template
+ * has moved on since this copy was generated. Without it, a project prompt generated from a
+ * since-corrected template looks indistinguishable from a current one.
+ */
+/** The template digest a GENERATED copy records — one definition, also read when a resume keeps a copy. */
+// THE TEXT, WHEREVER THE TEMPLATE KEEPS IT. Reading `body` alone hashed a template whose text is in `bodies` the same whatever
+// it said, so its project copy was never rebuilt (blocker-discipline v3, 2026-10-21). A `body` template hashes as before.
+function generatedTemplateDigest(template) {
+  const text = template.body !== undefined ? { body: template.body } : { body: template.body, bodies: template.bodies };
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify({ id: template.id, ...text, placeholders: sorted(template.placeholders) }))
+    .digest('hex');
+}
+
+function buildGeneratedDoc(template, generatedBody) {
+  const body = String(generatedBody);
+  return {
+    $why: [
+      `Generated from the ${template.id} template by the agent that minted this project's roster.`,
+      'The template is never executed; this copy is. Placeholders were checked against the',
+      'template before installation — see lib/project-prompt-contract.js.',
+    ],
+    authority: 'project',
+    body,
+    derivedFromSha256: generatedTemplateDigest(template),
+    derivedFromVersion: template.version == null ? null : template.version,
+    id: template.id,
+    // NO `seams` FIELD. It was a hand-maintained inverse index of something the registry already
+    // declares — a seam names the template it runs — and the two copies drifted: run
+    // 20260817T211517Z installed a copy claiming seams ["failure-analyst"] where its template says
+    // ["impl-failure-analyst"], and the link failed after 37 prompts had provisioned. Worse, that
+    // one template serves TWO seams and a single array cannot name both, so the relationship was
+    // unrepresentable rather than merely mis-copied.
+    //
+    // prompt-agent-link now reads the registry directly, so nothing consumes this field. Writing
+    // it anyway would only invite the drift back.
+    placeholders: placeholdersIn(body),
+    // THE DECLARATION TRAVELS WITH THE COPY THAT IS EXECUTED.
+    //
+    // mayBeEmpty says a placeholder may legitimately render blank — no prior gaps on a first pass,
+    // no fix sites before discovery, no forced retry on attempt one. The TEMPLATE declared it and
+    // this doc did not carry it, so every generated prompt lost the protection and the renderer
+    // refused at runtime on a block that was supposed to be empty.
+    //
+    // Live 2026-08-27, run 20260827T125654Z: the pipeline reached the specification pass for the
+    // first time and died there deterministically —
+    //   prompt 'spec-agent-openspec' was given EMPTY values for: __DECLARED_FILE_BLOCK__,
+    //   __FIX_SITE_BLOCK__, __FORCED_RETRY_BLOCK__, __PRIOR_GAPS_BLOCK__, …
+    // Three retries changed nothing because no model was ever asked anything, and both lanes
+    // halted. guard-vocabulary's template declared two and its generated copy carried none.
+    //
+    // FILTERED TO WHAT THIS BODY ACTUALLY HAS. A declaration naming a placeholder the generated
+    // text does not contain protects nothing and would only mislead the next reader — the same
+    // drift that removed the `seams` field above.
+    mayBeEmpty: (Array.isArray(template.mayBeEmpty) ? template.mayBeEmpty : [])
+      .filter((ph) => body.includes(ph)),
+  };
+}
+
+/**
+ * splitByPlaceholders(body) — prose segments and the slots between them.
+ *
+ * THE SLOTS ARE DELIMITERS, AND TREATING THEM AS PAYLOAD IS THE DEFECT. prompt-builder asked the
+ * model to rewrite a whole template while transcribing every __SLOT__ character-for-character:
+ * a writing task and a copying task at once. Models lose literals while rewriting the prose around
+ * them — live 2026-09-08, 25 refusals, every one "dropped placeholder(s) the template requires",
+ * and runtime-boundary-review lost all six of its slots five attempts running and aborted the run.
+ *
+ * Split here, and the model is only ever shown, and only ever returns, the prose BETWEEN slots.
+ * It cannot drop a placeholder it was never given.
+ *
+ * INVARIANT: body === segments[0] + slots[0] + segments[1] + ... + segments[n], so segments is
+ * always exactly one longer than slots, and every occurrence of a repeated slot is kept in order.
+ */
+function splitByPlaceholders(body) {
+  const text = String(body == null ? '' : body);
+  const slots = [];
+  const segments = [];
+  const re = /__[A-Z][A-Z0-9_]*?__/g;
+  let last = 0;
+  let m = re.exec(text);
+  while (m) {
+    segments.push(text.slice(last, m.index));
+    slots.push(m[0]);
+    last = m.index + m[0].length;
+    m = re.exec(text);
+  }
+  segments.push(text.slice(last));
+  return { segments, slots };
+}
+
+/**
+ * assembleFromSegments(segments, slots) — the body the pipeline builds, never the model.
+ *
+ * The slots go back exactly where they were, in their original order, however the model reworded
+ * the prose. Every contract invariant — nothing dropped, nothing invented, declared == used —
+ * therefore holds BY CONSTRUCTION rather than by inspection and retry.
+ *
+ * REFUSES A WRONG COUNT rather than padding. A model that returns the wrong number of segments has
+ * misunderstood the task, and quietly filling the gap would install a prompt whose prose no longer
+ * lines up with the evidence its slots carry — the same silent-wrongness this whole change exists
+ * to remove.
+ */
+function assembleFromSegments(segments, slots) {
+  const segs = Array.isArray(segments) ? segments : [];
+  const sl = Array.isArray(slots) ? slots : [];
+  if (segs.length !== sl.length + 1) {
+    throw new Error(
+      `[project-prompt-contract] expected ${sl.length + 1} segment(s) for ${sl.length} placeholder(s), got ${segs.length}`);
+  }
+  let out = '';
+  for (let i = 0; i < sl.length; i += 1) out += String(segs[i]) + sl[i];
+  return out + String(segs[segs.length - 1]);
+}
+
+/**
+ * extractSegmentsReply(text, expectedCount) — the segments a reply meant to give.
+ *
+ * MODELS THINK OUT LOUD, and that is not an error worth a paid retry. Live 2026-09-08 with real
+ * tokens, replies routinely looked like:
+ *
+ *   {"segments":["","","","","","","",""][0:0]}
+ *   Let me answer properly.
+ *   {"segments":["","\n\n---\nRUNTIME BOUNDARY REVIEW: "," — ", ...
+ *
+ * The first extractor used /\{[\s\S]*\}/ — greedy — so it spanned the abandoned attempt, the
+ * prose, and the real answer as one string and failed to parse every time. runtime-boundary-review
+ * burned all three attempts on replies whose FINAL object was perfectly good.
+ *
+ * Scanned with a brace counter that respects strings and escapes, because segment prose legitimately
+ * contains braces and quotes. The LAST candidate that parses and carries a segments array wins; when
+ * a count is known, a candidate matching it wins over one that does not, so a false start of the
+ * wrong length cannot beat the real answer.
+ */
+function extractSegmentsReply(text, expectedCount) {
+  const s = String(text == null ? '' : text);
+  const found = [];
+  for (let i = 0; i < s.length; i += 1) {
+    if (s[i] !== '{') continue;
+    let depth = 0; let inStr = false; let esc = false;
+    for (let j = i; j < s.length; j += 1) {
+      const ch = s[j];
+      if (esc) { esc = false; continue; }
+      if (inStr) {
+        if (ch === '\\') esc = true;
+        else if (ch === '"') inStr = false;
+        continue;
+      }
+      if (ch === '"') { inStr = true; continue; }
+      if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          try {
+            const o = JSON.parse(s.slice(i, j + 1));
+            if (o && Array.isArray(o.segments)) found.push(o.segments);
+          } catch { /* not this candidate */ }
+          i = j; // continue scanning AFTER this object
+          break;
+        }
+      }
+    }
+  }
+  if (!found.length) {
+    throw new Error('[project-prompt-contract] no {"segments":[...]} object in the reply');
+  }
+  if (typeof expectedCount === 'number') {
+    for (let k = found.length - 1; k >= 0; k -= 1) {
+      if (found[k].length === expectedCount) return found[k];
+    }
+  }
+  return found[found.length - 1];
+}
+
+/**
+ * parseSegmentsReply(text, expectedCount) — the segments a reply meant to give, delimited.
+ *
+ * WHY NOT JSON. The segments contract asked for the prose between placeholders as a JSON array.
+ * Live 2026-09-08, pipeline-tests-45: team-lead-review (17 placeholders, 5,545-char body) burned
+ * all five attempts and aborted the run at 7 of 39 prompts. The replies were not truncated -- they
+ * ended correctly with "]} -- they simply did not parse:
+ *
+ *   Expected ',' or ']' after array element at position 609
+ *   ..."worse than no fix.","\n---\nREVIEW TASK: Story ","," — ","\n\nDESCRIPTION:\n"...
+ *
+ * Segments that ARE punctuation -- ", ", "," -- sit badly beside JSON's own delimiters, and
+ * escaping quotes, commas and newlines across 7kB of prose is where it breaks. Another reply
+ * showed the model catching itself ("Wait — that response is invalid") and the corrected object
+ * failing to parse as well.
+ *
+ * The INPUT already uses --- SEGMENT n --- markers and the model reads them perfectly. Using the
+ * same shape for the OUTPUT removes escaping entirely: a newline is a newline and a segment that
+ * is a single comma is a line containing a comma.
+ *
+ * JSON is still accepted. A model that answers correctly in the harder format should not be
+ * refused for it.
+ *
+ * A FALSE START IS NORMAL. Models correct themselves mid-answer, so the LAST complete set wins.
+ */
+/**
+ * THE SEGMENT FORM, WRITTEN ONCE. The generator shows segments in this form and asks for the same
+ * form back; the parser below reads it. A second spelling anywhere — the builder's prompt, the
+ * rehearsal mock — is a copy that drifts, so both call this.
+ */
+function formatSegments(segments) {
+  return segments.map((seg, i) => `--- SEGMENT ${i + 1} ---\n${seg}`).join('\n')
+    + '\n--- END SEGMENTS ---\n';
+}
+
+function parseSegmentsReply(text, expectedCount) {
+  const s = String(text == null ? '' : text);
+
+  // Delimited form first: split on marker LINES so prose that merely mentions the marker inline
+  // cannot be mistaken for one.
+  const marker = /^[ \t]*-{2,}[ \t]*SEGMENT[ \t]+(\d+)[ \t]*-{2,}[ \t]*$/gm;
+  const hits = [];
+  let m = marker.exec(s);
+  while (m) { hits.push({ n: Number(m[1]), start: m.index, end: marker.lastIndex }); m = marker.exec(s); }
+  if (hits.length) {
+    // A reply may contain several attempts. Each time the numbering restarts at 1 a new set begins;
+    // the last set is the model's final answer.
+    let setStart = 0;
+    for (let i = 1; i < hits.length; i += 1) if (hits[i].n === 1) setStart = i;
+    const set = hits.slice(setStart);
+    const endMarker = /^[ \t]*-{2,}[ \t]*END SEGMENTS[ \t]*-{2,}[ \t]*$/gm;
+    endMarker.lastIndex = set[set.length - 1].end;
+    const tail = endMarker.exec(s);
+    const segs = set.map((h, i) => {
+      const from = h.end;
+      const to = i + 1 < set.length ? set[i + 1].start : (tail ? tail.index : s.length);
+      return s.slice(from, to).replace(/^\n/, '').replace(/\n$/, '');
+    });
+    if (typeof expectedCount !== 'number' || segs.length === expectedCount) return segs;
+    throw new Error(
+      `[project-prompt-contract] expected ${expectedCount} segment(s), got ${segs.length}`);
+  }
+
+  // JSON fallback, for a reply that got the harder format right.
+  const viaJson = (() => { try { return extractSegmentsReply(s, expectedCount); } catch { return null; } })();
+  if (viaJson) {
+    if (typeof expectedCount !== 'number' || viaJson.length === expectedCount) return viaJson;
+    throw new Error(
+      `[project-prompt-contract] expected ${expectedCount} segment(s), got ${viaJson.length}`);
+  }
+  throw new Error('[project-prompt-contract] no --- SEGMENT n --- blocks and no usable JSON in the reply');
+}
+
+module.exports = { checkGeneratedPrompt, buildGeneratedDoc, generatedTemplateDigest, placeholdersIn, outputFieldsIn,
+  splitByPlaceholders, assembleFromSegments, extractSegmentsReply, parseSegmentsReply, formatSegments };

package/orchestrations/scripts/refresh-project-prompts.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+// A PROJECT'S PROMPTS BROUGHT UP TO ITS CURRENT TEMPLATES, WITHOUT A RUN (operator, 2026-10-21: "only generate the ones
+// needed - I do not want to do a full pipeline run to adjust"). Exactly what the Agents phase does for a codeline whose
+// prompt set is no longer complete for the current templates, and nothing else of that phase: per codeline, the
+// codeline's recorded agents and prompts restored (restoreMinted, as codeline_minted_restore does), then the pipeline's
+// own builder (buildProjectPrompts) under its resume rule, keepExisting — a prompt still the copy of its template is kept
+// byte for byte with no call, one whose template moved on is regenerated and reviewed (lib/prompt-build-calls.js, the
+// mint's own generator and reviewer). The builder records the codeline's completion itself.
+//
+//   refresh-project-prompts.js --project <project config dir> --prd <run PRD> [--log-dir <dir>] [--stand-in]
+//
+// The codelines are the PRD's outputDirs, each one's id as the builder files it (codelineFromPrd of a one-codeline PRD).
+// --stand-in: no model is called — the generator answers with the template's own text and the reviewer approves — so
+// the rebuild can be rehearsed on a copy of the project at £0 and its decisions read: which prompts it would regenerate.
+// Run with the project's env loaded (lib/env-file.sh load_project_env), as the mint step is.
+const fs = require('fs');
+const path = require('path');
+
+const a = {}; const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i += 1) {
+  if (argv[i] === '--stand-in') a['stand-in'] = true; else { a[argv[i].replace(/^--/, '')] = argv[i + 1]; i += 1; }
+}
+const SCRIPTS = process.env.SCRIPT_DIR || __dirname;
+const ENGINE = path.resolve(SCRIPTS, '..', '..');
+const lib = (f) => require(path.join(SCRIPTS, 'lib', f));
+
+function standInCalls(templatesDir) {
+  const { splitByPlaceholders } = lib('project-prompt-contract.js');
+  const { templateBodyText } = lib('project-prompt-builder.js');
+  return {
+    runText: async (_prompt, meta) => {
+      const tpl = JSON.parse(fs.readFileSync(path.join(templatesDir, `${meta.id}.json`), 'utf8'));
+      return splitByPlaceholders(templateBodyText(tpl)).segments.map((s, i) => `--- SEGMENT ${i + 1} ---\n${s}`).join('\n');
+    },
+    reviewPrompt: async () => ({ ok: true, reviewed: true }),
+  };
+}
+
+async function main() {
+  if (!a.project || !a.prd) throw new Error('usage: refresh-project-prompts.js --project <dir> --prd <run prd.json> [--log-dir <dir>] [--stand-in]');
+  const projectConfigDir = path.resolve(a.project);
+  const logDir = path.resolve(a['log-dir'] || path.join(projectConfigDir, '..', '..', 'logs', 'refresh-project-prompts'));
+  fs.mkdirSync(logDir, { recursive: true });
+  const builder = lib('project-prompt-builder.js');
+  const promptsLib = lib('prompt-library.js');
+  const templatesDir = path.join(ENGINE, promptsLib.TEMPLATE_DIR_REL);
+  const prd = JSON.parse(fs.readFileSync(a.prd, 'utf8'));
+  const stories = prd.stories || [];
+  const dirs = ((prd.project && prd.project.outputDirs) || []).filter((o) => o && o.path);
+  if (!dirs.length) throw new Error(`${a.prd} names no codeline (project.outputDirs)`);
+  const report = [];
+  for (const o of dirs) {
+    const slice = path.join(logDir, `prd.${path.basename(o.path)}.json`);
+    fs.writeFileSync(slice, JSON.stringify({ ...prd, project: { ...prd.project, outputDirs: [o], outputDir: o.path } }));
+    const codeline = builder.codelineFromPrd(slice);
+    process.env.EPAM_CODELINE_ID = codeline;
+    process.env.EPAM_PROJECT_CONFIG_DIR = projectConfigDir;
+    process.env.PRD_FILE = slice;
+    const restored = builder.restoreMinted({ projectConfigDir, codeline });
+    const roles = lib('project-roster.js').mintedFromRegistries(projectConfigDir);
+    const codelines = [{ name: o.codeline, path: o.path }];
+    const codelineContext = lib('codeline-context.js').buildCodelineContext({
+      codelines, factsFile: path.join(projectConfigDir, 'codeline-facts.json'), surveyed: [] });
+    const calls = a['stand-in'] ? standInCalls(templatesDir) : (() => {
+      const spec = require(path.join(SCRIPTS, 'spec-mode-runner.js'));
+      return lib('prompt-build-calls.js').promptBuildCalls({
+        engineRoot: ENGINE, logDir, runClaude: spec.runClaude,
+        promptExec: spec.resolvePromptExec(process.env.AI_RUNNER_CMD || path.join(SCRIPTS, 'ai-run.sh')),
+        projectConfigDir, codelineContext, stories, mintedDetail: roles,
+        toolGrant: lib('agent-tools.js').readOnlyToolGrant(codelines.map((c) => c.path)),
+        reviewEnabled: String(process.env.EPAM_PROMPT_REVIEW_ENABLED ?? '1') !== '0',
+      });
+    })();
+    const lines = [];
+    const built = await builder.buildProjectPrompts({
+      keepExisting: true, templatesDir,
+      bootstrapFile: path.join(ENGINE, 'orchestrations', 'prompts', 'bootstrap.json'),
+      registryFile: path.join(ENGINE, 'orchestrations', 'agents', 'invocation-profiles.json'),
+      projectConfigDir, mode: process.env.EPAM_PROMPT_PROVISION_MODE,
+      attempts: Number(process.env.EPAM_PROMPT_ATTEMPTS || 5),
+      projectContext: [`Project: ${path.basename(projectConfigDir)}`,
+        `Tickets in scope: ${stories.map((t) => `${t.jiraKey || t.id}: ${t.title || ''}`).join(' | ')}`].join('\n'),
+      codelineContext,
+      mintedRoles: roles.length ? roles.map((m) => `- ${m.name} [${m.kind}] — ${m.rationale || ''}`).join('\n') : '(none minted this run)',
+      ...calls,
+      log: (m) => { lines.push(m); process.stderr.write(`[${codeline}] ${m}\n`); },
+    });
+    const rebuilt = lines.filter((l) => /template changed since this copy was made/.test(l)).map((l) => (l.match(/\] (\S+?):/) || [])[1]);
+    report.push({ codeline, restored, rebuilt, kept: built.generated.length + built.copied.length - rebuilt.length });
+  }
+  process.stdout.write(`${JSON.stringify(report)}\n`);
+}
+
+module.exports = { standInCalls };
+if (require.main === module) main().catch((e) => { process.stderr.write(`[refresh-project-prompts] FAILED: ${(e && e.stack) || e}\n`); process.exit(1); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amsd-pipeline-shared",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "The AMSD pipeline's shared components, one source for the bash pipeline and its Claude workflows: the model-call gateway (llm-handler.sh — retry, ladder, self-heal, cost) and the libraries it runs.",
   "license": "UNLICENSED",
   "bin": {