amsd-pipeline-shared 0.5.21 → 0.5.23

package/orchestrations/scripts/lib/prompt-library.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * THE PROMPT LIBRARY. Resolves and renders an agent's PROJECT-AUTHORITY prompt.
+ *
+ * Operator mandate, 2026-08-11, verbatim:
+ *   "WE WILL NEVER EVER run the template version of the prompts - NEVER. NEVER - no
+ *    fallbacks. Only project authority prompts - the self-health mechanism is the only
+ *    process permitted to mutate project level prompts. You will keep each prompt in a
+ *    separate file (json) and never hide prompts in code ever again."
+ *
+ * So, precisely:
+ *   - The TEMPLATE (orchestrations/prompts/templates/<id>.json) is the immutable generic
+ *     source a project prompt is MINTED FROM. It is NEVER executed.
+ *   - The PROJECT prompt (<project-config-dir>/prompts/<id>.json) is the ONLY thing
+ *     rendered and sent to a model.
+ *   - A missing project prompt is a HARD FAILURE. It never degrades to the template,
+ *     because a silent degrade is how an engine-embedded default runs for a whole
+ *     campaign without anyone noticing.
+ *
+ * WHY THIS EXISTS AT ALL: the failure-analyst prompt lived as a 44-line shell heredoc in
+ * claude.sh, generic, with no project-level variant — so the self-heal mechanism had
+ * nothing to mutate, and the prompt could not be corrected without editing the engine.
+ * Four more prompts are still embedded the same way (PROMPT_HEADER, PLAN_PROMPT_EOF,
+ * MODRES_EOF, COORD_PROMPT); this module is the pattern they migrate to.
+ *
+ * RENDERING IS TOTAL AND STRICT. Every declared placeholder must be supplied, and every
+ * placeholder appearing in the body must be declared. A prompt that reaches a model with
+ * a literal __STORY_ACS__ in it has silently lost its evidence, which is exactly the
+ * class of defect this pipeline keeps paying for.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATE_DIR_REL = 'orchestrations/prompts/templates';
+const PROJECT_PROMPT_SUBDIR = 'prompts';
+// THE PLACEHOLDER RULE LIVES IN ONE PLACE.
+//
+// This regex existed in THREE files — here, engine-prompt.js and project-prompt-contract.js —
+// and only one of them was fixed when adjacent placeholders turned out to merge. ${a}${b}
+// becomes __A____B__ in a template, and a greedy match reads that as a single token. The two
+// unfixed copies then disagreed with the fixed one about what a template declares, so a valid
+// generated prompt was refused as "dropping placeholders" and a valid template was refused as
+// "using undeclared placeholders". Three copies of a rule is three rules.
+const { placeholdersIn: _placeholdersIn, substituteOnce } = require('./engine-prompt.js');
+
+/** Repo root, derived from this file's location — never an env guess. */
+function repoRoot() {
+  return path.resolve(__dirname, '..', '..', '..');
+}
+
+function templatePath(id) {
+  return path.join(repoRoot(), TEMPLATE_DIR_REL, `${id}.json`);
+}
+
+function projectPromptPath(id, projectConfigDir) {
+  return path.join(projectConfigDir, PROJECT_PROMPT_SUBDIR, `${id}.json`);
+}
+
+function readJson(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    throw new Error(`prompt file unreadable (${file}): ${e && e.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    // Never "fall back to the template" here. An unparseable project prompt means the
+    // authority for this agent is broken, and running SOMETHING ELSE hides that.
+    throw new Error(`prompt file is not valid JSON (${file}): ${e && e.message}`);
+  }
+}
+
+/**
+ * Load the project-authority prompt. NO FALLBACK — see the header.
+ * @param {string} id            prompt id, e.g. 'failure-analyst'
+ * @param {string} projectConfigDir  EPAM_PROJECT_CONFIG_DIR
+ */
+function loadProjectPrompt(id, projectConfigDir, opts) {
+  if (!id || typeof id !== 'string') throw new Error('prompt id is required');
+  if (!projectConfigDir) {
+    throw new Error(
+      `no project config dir given for prompt '${id}' — EPAM_PROJECT_CONFIG_DIR must be set. ` +
+      'The template is never executed, so there is nothing to fall back to.',
+    );
+  }
+  const file = projectPromptPath(id, projectConfigDir);
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `project-authority prompt missing: ${file}. Mint it from ` +
+      `${TEMPLATE_DIR_REL}/${id}.json — the template is NEVER executed directly.`,
+    );
+  }
+  const doc = readJson(file);
+
+  // A MULTI-PART PROMPT: ONE POLICY, SEVERAL AUDIENCES.
+  //
+  // Some rules bind more than one agent, and the two halves must never drift. "Tests are NOT
+  // your job" lived only in the writer's prompt; the reviewer had never heard of it and raised
+  // a blocker for missing tests, so the writer was ordered to create what it was forbidden to
+  // create. Splitting that across two prompt files would recreate the same defect with extra
+  // steps, so a prompt may declare `bodies: { <part>: text }` and each consumer asks for its
+  // own part of the SAME document.
+  //
+  // A part is REQUIRED when bodies exist: silently picking one would make the caller's audience
+  // an accident of ordering.
+  if (doc && doc.bodies && typeof doc.bodies === 'object') {
+    const part = opts && opts.part;
+    if (!part) {
+      throw new Error(
+        `prompt '${id}' declares parts (${Object.keys(doc.bodies).join(', ')}) — ask for one by name`);
+    }
+    if (typeof doc.bodies[part] !== 'string' || !doc.bodies[part].trim()) {
+      throw new Error(
+        `prompt '${id}' has no part '${part}' (declares: ${Object.keys(doc.bodies).join(', ')})`);
+    }
+    // THE PART'S CONTRACT IS THE PART'S PLACEHOLDERS. `placeholders` on a multi-part document
+    // is the UNION across parts — that is what the whole document declares. render() then
+    // compares it against ONE part's body and refuses it for "declaring placeholders it never
+    // uses", so every multi-part project prompt was unrenderable through this path.
+    //
+    // Surfaced when seam prompts started routing here instead of to the template renderer, which
+    // computes its declared set per body already. Narrowed rather than relaxing render(): a
+    // prompt that declares a placeholder its body never uses is still a real defect, and the
+    // check that catches it is worth keeping.
+    const used = new Set(placeholdersIn(doc.bodies[part]));
+    return {
+      ...doc,
+      body: doc.bodies[part],
+      placeholders: (doc.placeholders || []).filter((x) => used.has(x)),
+    };
+  }
+
+  if (!doc || typeof doc.body !== 'string' || !doc.body.trim()) {
+    throw new Error(`project-authority prompt has no body: ${file}`);
+  }
+  if (doc.authority && doc.authority !== 'project') {
+    throw new Error(`refusing to run a non-project prompt (authority='${doc.authority}'): ${file}`);
+  }
+  return doc;
+}
+
+/** Placeholders actually present in a body, deduped and sorted. */
+function placeholdersIn(body) {
+  return [..._placeholdersIn(body)].sort();
+}
+
+/**
+ * Render a prompt body with values. Strict in both directions.
+ *
+ * Values are substituted with a replacer FUNCTION, not a string, so that `$&`, `$1` and
+ * friends inside a value (a diff, a regex, a test log — all routine here) are inserted
+ * literally instead of being interpreted as replacement patterns. That bug would corrupt
+ * evidence silently and only for values that happen to contain a dollar sign.
+ */
+function render(doc, values) {
+  const body = doc.body;
+  const declared = Array.isArray(doc.placeholders) ? [...doc.placeholders].sort() : [];
+  const present = placeholdersIn(body);
+
+  const undeclared = present.filter((p) => !declared.includes(p));
+  if (undeclared.length) {
+    throw new Error(`prompt '${doc.id}' uses undeclared placeholders: ${undeclared.join(', ')}`);
+  }
+  const orphanDeclared = declared.filter((p) => !present.includes(p));
+  if (orphanDeclared.length) {
+    throw new Error(`prompt '${doc.id}' declares placeholders it never uses: ${orphanDeclared.join(', ')}`);
+  }
+
+  const supplied = values && typeof values === 'object' ? values : {};
+
+  // A VALUE NOTHING CONSUMES IS EVIDENCE THROWN AWAY.
+  //
+  // This checked three things and not this one, so a value supplied to a prompt with no
+  // matching placeholder was silently dropped. engine-prompt.js has always rejected exactly
+  // that — "was given values it does not use" — so the two renderers disagreed on the same
+  // class, and the lenient one lost evidence without a trace.
+  //
+  // Live 20260821T212250Z: prior-reviews.py produced the reviewer's history correctly and it
+  // was supplied as __PRIOR_REVIEW__. The project's prompt declares no such placeholder, so
+  // it went nowhere. All three review cycles ran with no memory of each other and the
+  // approval missed a regression the earlier cycle had caught. The run log mentions prior
+  // review zero times: a whole feedback loop absent, with nothing to show it.
+  //
+  // Loud, because the caller believed it sent something. A stale project prompt is now a
+  // failure at render rather than a quiet degrade — which is the same rule the rest of this
+  // file already applies in the other direction.
+  const unconsumed = Object.keys(supplied).filter((k) => /^__[A-Z0-9_]+__$/.test(k) && !present.includes(k));
+  if (unconsumed.length) {
+    // LOUD, NOT FATAL — and that asymmetry is deliberate.
+    //
+    // Throwing here kills the seam outright: the reviewer supplies __PRIOR_REVIEW__ to project
+    // prompts minted before that placeholder existed, so a hard failure would take the reviewer
+    // out of every such run. Losing one block of context is bad; losing the whole review is
+    // worse, and the operator has not asked for a re-mint.
+    //
+    // engine-prompt.js DOES throw on this, correctly: it renders templates, which are the
+    // in-repo source and can always be corrected. A project prompt is generated, may lag the
+    // template, and cannot be corrected from here.
+    //
+    // What was unacceptable was silence. This is the trace that was missing when the reviewer's
+    // entire prior-review history was dropped on 20260821T212250Z and the run log mentioned it
+    // zero times.
+    process.stderr.write(
+      `[prompt-library] '${doc.id}' was given values it does not use: ${unconsumed.join(', ')}. `
+      + 'That evidence is being DROPPED — the prompt has no placeholder for it. '
+      + 'Add the placeholder to this project prompt, or stop supplying the value.\n');
+  }
+
+  // A LOOKUP THAT FOUND NOTHING IS ABSENCE, NOT A VALUE. `p in supplied` is true for a key whose
+  // value is undefined, so the rule stated below — absent is not empty — was defeated by the one
+  // shape absence actually takes in JavaScript, and the prompt rendered with the literal word
+  // "undefined" where the evidence belonged. null is the same thing arriving from JSON.
+  const missing = present.filter((p) => !(p in supplied) || supplied[p] === undefined || supplied[p] === null);
+  if (missing.length) {
+    // An empty string is a legitimate value and must be passed explicitly. Absent is not
+    // empty: a prompt rendered without its evidence is worse than one that fails loudly.
+    throw new Error(`prompt '${doc.id}' is missing values for: ${missing.join(', ')}`);
+  }
+
+  // ONE PASS OVER THE BODY. Replacing each key in turn over the accumulating output meant every
+  // value was re-read by every later key: a diff that mentioned __B__ had __B__'s content
+  // spliced into it, and a diff carrying any double-underscore token — a Python dunder, a C
+  // macro — tripped the leftover check below and killed the render of a complete prompt. A
+  // single alternation pass inserts each value exactly where the BODY asked for it and never
+  // looks at what was inserted.
+  //
+  // Replacer FUNCTION, not a string, so a `$&` or `$1` inside a diff, a log or a JSON example
+  // is inserted literally instead of being read as a replacement pattern.
+  // AN EMPTY VALUE IS SILENCE, AND SILENCE REACHES THE MODEL AS A BLANK SECTION.
+  //
+  // The renderer refused a MISSING key and accepted a present-but-empty one, so `|| ''` — which
+  // fifteen call sites use — turned a failed lookup into a prompt that looked complete and said
+  // nothing. Live 2026-08-23: the roster reviewer was handed a header with a blank line under it
+  // for every agent, reported the briefs "entirely empty", and blocked the roster twice. The
+  // briefs existed; the lookup read the wrong map.
+  //
+  // A placeholder that may legitimately be empty says so IN THE TEMPLATE, as `mayBeEmpty`. A retry
+  // note absent on a first attempt is a real state; a brief is not. That distinction belongs with
+  // the prompt, which is reviewable, rather than in the producer, which is where it got lost.
+  const mayBeEmpty = new Set(Array.isArray(doc.mayBeEmpty) ? doc.mayBeEmpty : []);
+  const blank = present.filter((p) => !mayBeEmpty.has(p)
+    && typeof supplied[p] === 'string' && !supplied[p].trim());
+  if (blank.length) {
+    throw new Error(
+      `prompt '${doc.id}' was given EMPTY values for: ${blank.join(', ')}. An empty payload renders `
+      + 'as a blank section and the agent answers about silence — it cannot tell a failed lookup '
+      + 'from a genuinely absent one. Supply the value, or declare the placeholder in the '
+      + "template's `mayBeEmpty` if absent is a real state for it.");
+  }
+
+  const out = substituteOnce(body, present, supplied);
+
+  // The check that means something is on the BODY: a placeholder this pass did not cover.
+  // Scanning the OUTPUT could only ever find tokens that arrived as evidence.
+  const uncovered = placeholdersIn(body).filter((p) => !present.includes(p));
+  if (uncovered.length) {
+    throw new Error(`prompt '${doc.id}' has placeholders no value covered: ${uncovered.join(', ')}`);
+  }
+  return out;
+}
+
+/** Convenience: load + render in one call. */
+function buildPrompt(id, projectConfigDir, values, opts) {
+  return render(loadProjectPrompt(id, projectConfigDir, opts), values);
+}
+
+module.exports = {
+  loadProjectPrompt,
+  render,
+  buildPrompt,
+  placeholdersIn,
+  templatePath,
+  projectPromptPath,
+  TEMPLATE_DIR_REL,
+  PROJECT_PROMPT_SUBDIR,
+};
+
+/**
+ * CLI, so shell can use the library without reimplementing resolution:
+ *   node prompt-library.js render <id> <projectConfigDir> <values.json> [part]
+ * Values arrive as a JSON file rather than argv because they routinely contain newlines,
+ * quotes and megabytes of test output.
+ */
+if (require.main === module) {
+  const [, , cmd, id, dir, valuesFile, part] = process.argv;
+  try {
+    if (cmd !== 'render') throw new Error(`unknown command '${cmd}' (expected: render)`);
+    const values = valuesFile ? readJson(valuesFile) : {};
+    process.stdout.write(buildPrompt(id, dir, values, part ? { part } : undefined));
+  } catch (e) {
+    process.stderr.write(`[prompt-library] ${e && e.message}\n`);
+    process.exit(1);
+  }
+}

package/orchestrations/scripts/lib/prompt-variant.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# THE COMPLETION MARKER'S NAME — ONE DERIVATION, FOR EVERY SHELL CALL SITE.
+#
+# `.prompt-cache/.complete-<codeline>` is the claim that a codeline's prompts are fully
+# provisioned, and its presence makes the mint skip ENTIRELY. It is tested in three shell places
+# (run-agent-orchestration.sh twice, pre-run-reset.sh) and written by project-prompt-builder.js.
+#
+# A brownfield run generates DIFFERENT prompts from the same seams, so it must not inherit a
+# greenfield codeline's claim — it would skip provisioning and serve the greenfield prompts on
+# disk, which on a cached codeline means the brownfield variant never executes at all.
+#
+# Greenfield's name is unchanged, byte for byte: no marker already on disk is invalidated.
+# The JS side of this rule is _markerPath in lib/project-prompt-builder.js; the two are asserted
+# to agree by test/unit/orchestration/a-brownfield-run-generates-its-own-prompts.test.ts.
+prompt_marker_key() {
+    if [ "${EPAM_BROWNFIELD:-0}" = "1" ]; then
+        printf '.complete-%s.brownfield' "$1"
+    else
+        printf '.complete-%s' "$1"
+    fi
+}
+
+# codeline_prompts_complete <codeline> — were this codeline's prompts built from the CURRENT
+# inputs? Answered by project-prompt-builder.js (the digest the marker records vs the digest
+# of the template layer, registry and generator now). A marker's mere existence is not an
+# answer: an empty one let a launch reuse prompts built from the previous day's templates
+# (regintel 20260920T232518Z, $5.73). Says why on stderr when the answer is no.
+codeline_prompts_complete() {
+    local _cl="${1:-}"
+    [ -n "$_cl" ] && [ -n "${EPAM_PROJECT_CONFIG_DIR:-}" ] || return 1
+    local _here; _here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    local _builder="${_here}/project-prompt-builder.js"
+    local _out
+    _out=$("${NODE_BIN:-node}" -e '
+      const b = require(process.argv[1]);
+      const r = b.codelinePromptsComplete({ projectConfigDir: process.argv[2], codeline: process.argv[3],
+        templatesDir: process.env.EPAM_PROMPT_TEMPLATES_DIR || undefined, registryFile: process.env.EPAM_SEAM_REGISTRY_FILE || undefined });
+      process.stdout.write((r.complete ? "yes" : "no") + "\t" + (r.reason || ""));
+    ' "$_builder" "$EPAM_PROJECT_CONFIG_DIR" "$_cl" 2>/dev/null) || return 1
+    case "$_out" in
+        yes*) return 0 ;;
+        *) echo "[prompts] codeline ${_cl}: ${_out#*	}" >&2; return 1 ;;
+    esac
+}
+
+# THIS CODELINE'S MINTED AGENTS ON DISK — restored from what its completion recorded
+# (.prompt-cache/<codeline>/minted, project-prompt-builder.js). Returns 1, touching nothing, when the
+# codeline recorded none: a marker cannot vouch for agents it never saw (AMSD-2974 run 3, 2026-09-30).
+codeline_minted_restore() {
+    local _cl="${1:-}"
+    [ -n "$_cl" ] && [ -n "${EPAM_PROJECT_CONFIG_DIR:-}" ] || return 1
+    local _here; _here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    "${NODE_BIN:-node}" -e '
+      const b = require(process.argv[1]);
+      process.exit(b.restoreMinted({ projectConfigDir: process.argv[2], codeline: process.argv[3] }) ? 0 : 1);
+    ' "${_here}/project-prompt-builder.js" "$EPAM_PROJECT_CONFIG_DIR" "$_cl" 2>/dev/null
+}
+
+# The mint's clean slate: every minted file (the one list, in project-prompt-builder.js), removed.
+codeline_minted_clear() {
+    [ -n "${EPAM_PROJECT_CONFIG_DIR:-}" ] || return 0
+    local _here; _here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    "${NODE_BIN:-node}" -e 'require(process.argv[1]).clearMinted({ projectConfigDir: process.argv[2] });' \
+        "${_here}/project-prompt-builder.js" "$EPAM_PROJECT_CONFIG_DIR" 2>/dev/null || true
+}
+
+# lane_codeline_set_restore <lane PRD> — A LANE WORKS FROM ITS OWN CODELINE'S SET (operator, 2026-10-22: "prompts/profiles BY
+# codeline"). The lane's codeline is its PRD's project.outputDir folder; that codeline's recorded agents and prompts become the
+# active set before the lane's agents run (project-prompt-builder.js restoreCodelineSet). A codeline with no recorded set returns 1,
+# says why and changes nothing: the lane never runs another codeline's set or the project-wide one.
+lane_codeline_set_restore() {
+    local _prd="${1:-}"
+    [ -n "$_prd" ] && [ -f "$_prd" ] && [ -n "${EPAM_PROJECT_CONFIG_DIR:-}" ] || { echo "[prompts] lane: no PRD or project to resolve its codeline's set from" >&2; return 1; }
+    local _here; _here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    local _out
+    _out=$("${NODE_BIN:-node}" -e '
+      const b = require(process.argv[1]);
+      const codeline = b.codelineOfPrd(process.argv[3]);
+      const r = codeline ? b.restoreCodelineSet({ projectConfigDir: process.argv[2], codeline }) : { ok: false, reason: "its PRD names no codeline (project.outputDir)" };
+      process.stdout.write((r.ok ? "yes" : "no") + "\t" + (codeline || "?") + "\t" + (r.reason || ""));
+    ' "${_here}/project-prompt-builder.js" "$EPAM_PROJECT_CONFIG_DIR" "$_prd" 2>&1) || { echo "[prompts] lane: its codeline's set could not be resolved: ${_out}" >&2; return 1; }
+    local _ok="${_out%%	*}" _rest="${_out#*	}"; local _cl="${_rest%%	*}" _why="${_rest#*	}"
+    if [ "$_ok" = "yes" ]; then
+        echo "[prompts] lane: working from codeline ${_cl}'s own recorded agents and prompts" >&2
+        return 0
+    fi
+    echo "[prompts] lane: codeline ${_cl} has no recorded set (${_why}) — the lane does not run another codeline's or the project-wide set" >&2
+    return 1
+}
+
+# scope_codeline_of_prd <PRD> — the codeline the mint's reuse is decided for (project-prompt-builder.js scopeCodelineFromPrd): the
+# story's single codeline; for several, its own codeline when EVERY codeline of the story has its complete recorded set; else empty.
+scope_codeline_of_prd() {
+    local _prd="${1:-}"
+    [ -n "$_prd" ] && [ -f "$_prd" ] || return 0
+    local _here; _here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    "${NODE_BIN:-node}" -e '
+      const b = require(process.argv[1]);
+      process.stdout.write(b.scopeCodelineFromPrd({ prdFile: process.argv[3], projectConfigDir: process.argv[2],
+        templatesDir: process.env.EPAM_PROMPT_TEMPLATES_DIR || undefined, registryFile: process.env.EPAM_SEAM_REGISTRY_FILE || undefined }) || "");
+    ' "${_here}/project-prompt-builder.js" "${EPAM_PROJECT_CONFIG_DIR:-}" "$_prd" 2>/dev/null || true
+}
+
+# parallel_lanes_codeline_set_restore <lane PRD>... — LANES THAT RUN TOGETHER SHARE ONE ACTIVE SET. Each can work from its own
+# codeline's set only when those sets are the same, byte for byte (project-prompt-builder.js codelineSetsIdentical): then the set is
+# restored once, before they start. Otherwise returns 1 and says which differ — no lane runs another codeline's set; run the lanes
+# one at a time (EPAM_PARALLEL_CODELINES=0) and each restores its own.
+parallel_lanes_codeline_set_restore() {
+    [ "$#" -gt 0 ] || return 0
+    local _here; _here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    local _why
+    _why=$("${NODE_BIN:-node}" -e '
+      const b = require(process.argv[1]);
+      const codelines = process.argv.slice(3).map((f) => b.codelineOfPrd(f));
+      if (codelines.some((c) => !c)) { process.stdout.write("a lane PRD names no codeline (project.outputDir)"); process.exit(1); }
+      const r = b.codelineSetsIdentical({ projectConfigDir: process.argv[2], codelines });
+      if (!r.same) { process.stdout.write(r.reason); process.exit(1); }
+    ' "${_here}/project-prompt-builder.js" "${EPAM_PROJECT_CONFIG_DIR:-}" "$@" 2>&1) || {
+        echo "[prompts] parallel lanes: their codelines' recorded sets are not the same (${_why}) — run them one at a time (EPAM_PARALLEL_CODELINES=0) so each works from its own" >&2
+        return 1
+    }
+    lane_codeline_set_restore "$1"
+}