amsd-pipeline-shared 0.5.3 → 0.5.5

package/docs/gateway-baseline-2.0.80.md5

@@ -88,3 +88,7 @@ ac166207d8a1d93a4c50a88568ef6e5c  scripts/lib/handlers/write-missing-plans.js
 ee4366721c38cbc8cd72ee0f779d22a8  scripts/lib/plan-scope.js
 aab7063cf68a9ecd54f6ef735adf895e  scripts/lib/engine-paths.sh
 1d0346da09c13150e511809034396949  scripts/lib/pipeline-commit.sh
+a01137cb36b65a3b80a8327404f4ed7a  scripts/lib/story-acs-block.sh
+043b6c85d1505ebc5da6c6b158000330  scripts/lib/plan-of-record.sh
+1cc1978d614fca875ad1117e9ac42f93  scripts/lib/render-engine-prompt.sh
+bad91b18bf546145a58423c770ba1a3a  prompts/templates/criterion-origin.json

package/docs/gateway-files.txt

@@ -6,6 +6,7 @@ config/resume-preserves.json
 config/run-modes.json
 prompts/doctor-repair.md
 prompts/templates/codeline-discovery.json
+prompts/templates/criterion-origin.json
 scripts/agent-attempt-analyst.sh
 scripts/lib/agent-contract.js
 scripts/lib/agent-ladder.sh
@@ -77,12 +78,14 @@ scripts/lib/phase-exit.sh
 scripts/lib/pipeline-commit.sh
 scripts/lib/pipeline-tools.js
 scripts/lib/plan-hash.js
+scripts/lib/plan-of-record.sh
 scripts/lib/plan-scope.js
 scripts/lib/preflight.sh
 scripts/lib/prelaunch.js
 scripts/lib/qa-gate-evidence.sh
 scripts/lib/relative-paths.js
 scripts/lib/release-lines.sh
+scripts/lib/render-engine-prompt.sh
 scripts/lib/render-prompt-section.js
 scripts/lib/resume-semantics.sh
 scripts/lib/run-checkpoint.sh
@@ -91,6 +94,7 @@ scripts/lib/seam-invocation.js
 scripts/lib/seam-ladder.sh
 scripts/lib/self-heal.js
 scripts/lib/stage-coverage-gate.sh
+scripts/lib/story-acs-block.sh
 scripts/lib/story-outputs.sh
 scripts/lib/story-retry-state.sh
 scripts/lib/tool-timeouts.js

package/orchestrations/prompts/templates/criterion-origin.json

@@ -0,0 +1,15 @@
+{
+  "$why": [
+    "2026-10-14 (operator: \"You are not permitted to hard code engine prose\"). The words that mark a criterion the",
+    "pipeline's remediator added — so the reviewer may retire it when it cannot be met, and never one of the plan's —",
+    "were a string in lib/story-acs-block.sh. One definition: the criteria block renders it beside such a criterion,",
+    "the reviewer's contract (review-finding-routing) names it, and retire-criteria.py accepts a name copied with it."
+  ],
+  "description": "How a criterion the remediator added is marked wherever criteria are shown to an agent.",
+  "id": "criterion-origin",
+  "version": 1,
+  "placeholders": [],
+  "bodies": {
+    "remediation": "[added by remediation — not the plan]"
+  }
+}

package/orchestrations/scripts/lib/codeline-lanes.sh

@@ -614,9 +614,15 @@ archive_prior_lane_state() {
     fi
     # B80 (RS-7): the run's start is its id when the id is a timestamp (as before); for ANY other id (every Claude workflows id is LIVE-…) it is NOW — the
     # first time this function runs for the run — which is only safe with the marker that stops a resume from archiving the run's own state
+    # B80 fix (run 11 leg 3): a RESUME's lane state is its own. Without a timestamp id there is no way to tell the run's earlier legs' files from an earlier run's, and
+    # the run's first legs may predate the marker — so a resume never archives (the released 0.5.3 moved 113 files of the run's own state and the Writer re-ran).
     local _start _how=""
     _start=$(printf '%s' "$_run" | sed -nE 's/^([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2})([0-9]{2})([0-9]{2})Z?$/\1-\2-\3 \4:\5:\6 UTC/p')
     if [ -z "$_start" ]; then
+        if [ -n "${EPAM_RESUME_RUN:-}" ]; then
+            log "[orch] the lane state of '${_run}' is kept: this is a resume, and its earlier legs' files are its own (the run id carries no start time to tell them from an earlier run's)" || true
+            return 0
+        fi
         if [ -z "$_marker" ]; then
             warning "[orch] the earlier lane state is not archived: run id '${_run}' carries no start time and there is no EPAM_PROJECT_CONFIG_DIR to record that it was archived (a resume would archive the run's own state)" || true
             return 0

package/orchestrations/scripts/lib/plan-of-record.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# plan-of-record.sh — THE STORY'S PLAN AS APPROVED AT PAUSE 2, WRITTEN ONCE, NEVER OVERWRITTEN.
+#
+# Operator, 2026-10-14 (option 3): which criteria are the plan's is decided by the plan approved at pause 2 — not by a
+# criterion's shape. The old rule ("exactly {text, status} means a remediator added it") was hard coding. The plan of
+# record lives beside the lane's pre-writer checkpoint; a release line reads its lane's (the line's plan is the lane's).
+# A run paused before this existed derives it once from that checkpoint — never from an earlier stage, which is not
+# the approved plan.
+
+# shellcheck source=run-checkpoint.sh
+declare -F checkpoint_dir >/dev/null 2>&1 || . "$(dirname "${BASH_SOURCE[0]}")/run-checkpoint.sh"
+
+# plan_of_record_file [run-id] — the path (it may not exist yet).
+plan_of_record_file() {
+    local _d; _d=$(EPAM_RELEASE_LINE='' checkpoint_dir "${1:-}" 2>/dev/null) || return 1
+    [ -n "$_d" ] || return 1
+    printf '%s/plan-of-record.json' "$_d"
+}
+
+# record_plan_of_record <prd> — write the plan of record from <prd>, ONCE: an existing one is never replaced.
+record_plan_of_record() {
+    local _src="${1:-}" _f
+    _f=$(plan_of_record_file) || return 0
+    [ -s "$_f" ] && return 0
+    [ -n "$_src" ] && [ -f "$_src" ] || return 0
+    mkdir -p "$(dirname "$_f")" 2>/dev/null || true
+    jq '{stories: [(.stories // [])[] | {id, acceptanceCriteria: (.acceptanceCriteria // [])}]}' "$_src" > "$_f.tmp" 2>/dev/null \
+        && mv "$_f.tmp" "$_f" || rm -f "$_f.tmp"
+}
+
+# plan_of_record_ensured — the plan of record's path when there is one: written now from the lane's pre-writer checkpoint
+# if this run paused before plans of record were kept; nothing when no pause-2 checkpoint exists.
+plan_of_record_ensured() {
+    local _f _d
+    _f=$(plan_of_record_file) || return 0
+    if [ ! -s "$_f" ]; then
+        _d=$(dirname "$_f")
+        [ -f "$_d/checkpoint.json" ] && [ -f "$_d/prd.json" ] || return 0
+        [ "$(_stage_rank "$(jq -r '.stage // empty' "$_d/checkpoint.json" 2>/dev/null)")" -ge "$(_stage_rank pre-writer)" ] || return 0
+        record_plan_of_record "$_d/prd.json"
+    fi
+    [ -s "$_f" ] && printf '%s' "$_f"
+}

package/orchestrations/scripts/lib/qa-gate-evidence.sh

@@ -229,9 +229,14 @@ qa_record_phase_baseline() {
     # B77 (RS-4, = B73): THE BASELINE IS RECORDED ONCE for a run and phase. A resume starts the phase again; the baseline it had must not move to wherever HEAD
     # is by then (that made "committed since the baseline" empty). A new phase, or a new run in the same log folder, has a different key and records its own.
     _key="${PHASE:-main}|${ORCH_RUN_ID:-}"
-    if [ -f "$_bf" ] && [ -f "$_kf" ] && [ "$(cat "$_kf" 2>/dev/null)" = "$_key" ]; then
+    # A RESUME ADOPTS A LEGACY BASELINE (a sha with no key file, recorded by the code before B77 — found replaying run 11's gotransit lane): on a resume it is the run's own, so a
+    # valid commit is kept and the key is written for every later call. Without a resume (a new run in the same folder) a keyless value is not trusted, as before.
+    local _legacy=0
+    [ -f "$_bf" ] && [ ! -f "$_kf" ] && [ -n "${EPAM_RESUME_RUN:-}" ] && _legacy=1
+    if [ -f "$_bf" ] && { [ "$_legacy" = 1 ] || { [ -f "$_kf" ] && [ "$(cat "$_kf" 2>/dev/null)" = "$_key" ]; }; }; then
         _have=$(tr -d '[:space:]' < "$_bf" 2>/dev/null)
         if [ -n "$_have" ] && git -C "$_root" cat-file -e "${_have}^{commit}" 2>/dev/null; then
+            [ "$_legacy" = 1 ] && printf '%s\n' "$_key" > "$_kf"
             printf '%s' "$_have"
             return 0
         fi

package/orchestrations/scripts/lib/render-engine-prompt.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# render-engine-prompt.sh — render a template-layer prompt from shell.
+#
+# Several seams that still carry embedded prompts are shell, not JavaScript, so
+# they need the same renderer the JS side uses. This is a thin wrapper over
+# lib/engine-prompt.js: one renderer, one strictness, one set of rules.
+#
+#   render_engine_prompt <template-id> <values-json-file>
+#
+# VALUES ARRIVE VIA A FILE, NEVER ARGV.
+# Prompt values routinely carry a whole diff, a suite dump or a PRD fragment.
+# ARG_MAX is 2 MiB, and passing a value that exceeds it makes the command exit
+# 126 with an empty result — which is exactly how the FailureAnalyst died on
+# 2026-08-15, silently, because the failure looked like a parse error three
+# steps later. A file has no such limit.
+#
+# Exit status is the contract: non-zero means nothing was rendered, and the
+# caller must refuse to invoke an agent rather than send it an empty prompt.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# shellcheck disable=SC2148
+_REP_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+render_engine_prompt() {
+    local _id="$1" _values_file="$2" _body_key="${3:-}"
+
+    if [ -z "$_id" ] || [ -z "$_values_file" ]; then
+        echo "[render-engine-prompt] usage: render_engine_prompt <template-id> <values-json-file>" >&2
+        return 2
+    fi
+    if [ ! -f "$_values_file" ]; then
+        echo "[render-engine-prompt] values file not found: $_values_file" >&2
+        return 2
+    fi
+
+    local _out _err
+    _err=$(mktemp "${TMPDIR:-/tmp}/render-prompt-err-XXXXXX")
+    # The values file path is the only thing on argv; the values themselves are read
+    # from disk by node.
+    _out=$("${NODE_BIN:-node}" -e '
+        const fs = require("fs");
+        const { renderEngineTemplate } = require(process.argv[1]);
+        const values = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
+        process.stdout.write(renderEngineTemplate(process.argv[2], values, process.argv[4] || undefined));
+    ' "$_REP_LIB_DIR/engine-prompt.js" "$_id" "$_values_file" "$_body_key" 2>"$_err")
+    local _rc=$?
+
+    if [ "$_rc" -ne 0 ] || [ -z "$_out" ]; then
+        # Loud, and naming the template. An agent invoked with an empty prompt answers
+        # from nothing and the answer looks like every other answer.
+        echo "[render-engine-prompt] FAILED to render '$_id': $(cat "$_err" 2>/dev/null)" >&2
+        rm -f "$_err"
+        return 1
+    fi
+    rm -f "$_err"
+    printf '%s' "$_out"
+}
+
+# render_or_keep <template-id> <values-json-file> [<body-key>]
+#
+# Renders, or prints NOTHING and returns non-zero — so the caller's variable keeps whatever it
+# already held instead of being blanked:
+#
+#     _r="$(render_or_keep writer-plan-section "$_vals" execution_plan)" && prompt="$_r"
+#
+# WHY. `prompt="$(render_engine_prompt ...)"` discards the exit status, so a dead render assigns
+# the empty string. Live metrolinx AMSD-2041, 2026-08-19: jq hit the 128KB argv cap, both the
+# writer prompt and the retry amendment silently became empty, and the run climbed the entire model
+# ladder invoking agents with nothing in hand — visible as attempts returning in 0.01 min having
+# consumed zero tokens. The header of this file already stated the rule the callers broke: exit
+# status is the contract, and a caller must refuse rather than send an empty prompt.
+#
+# AN EMPTY SUCCESSFUL RENDER IS ALSO A FAILURE here. At the call site the two are the same event —
+# an agent handed nothing — and only one of them was ever going to be noticed.
+render_or_keep() {
+    local _out _rc
+    _out=$(render_engine_prompt "$@")
+    _rc=$?
+    if [ "$_rc" -ne 0 ] || [ -z "$_out" ]; then
+        if command -v warning >/dev/null 2>&1; then
+            warning "  [render] '${1:-?}' produced nothing (exit ${_rc}) — keeping the previous value rather than blanking it"
+        else
+            echo "[render-engine-prompt] '${1:-?}' produced nothing (exit ${_rc}) — caller keeps its previous value" >&2
+        fi
+        return 1
+    fi
+    printf '%s' "$_out"
+}

package/orchestrations/scripts/lib/story-acs-block.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# story-acs-block.sh — the acceptance-criteria BLOCK a seam prompt receives, or nothing.
+#
+# Brownfield judges on verification criteria: a brownfield story has no acceptance criteria, and an
+# empty "ACCEPTANCE CRITERIA:" heading over nothing is worse than no heading (operator, 2026-09-01,
+# ea920ee7). Greenfield is authored WITH acceptance criteria and they are in scope (operator,
+# 2026-09-11). Both hold when the heading travels with the criteria: present, the block is the
+# heading and the numbered list; absent, the block is empty and the template's __STORY_ACS__
+# (declared mayBeEmpty) renders as nothing. Four seams read it — failure-analyst, team-lead-review,
+# code-review-cycle, code-graph-detective (spec-mode-runner.js builds the same shape in JS) — so
+# the shape is defined here once.
+#
+# story_acs_block <prd_file> <story_id> [heading]
+#   stdout: "<heading>\nAC1: ...\nAC2: ...\n\n" when the story declares acceptance criteria,
+#           "" otherwise. Default heading "ACCEPTANCE CRITERIA:".
+# A CRITERION THE REMEDIATOR ADDED SAYS SO (operator, 2026-10-14: a reviewer may retire one that cannot be met — never
+# one of the plan's). What the plan is comes from the plan of record (lib/plan-of-record.sh); the remediators also stamp
+# what they add {origin: "remediation"}.
+# THE MARKER IS TEMPLATE PROSE (prompts/templates/criterion-origin.json) — never a literal here. The criteria block renders
+# it, the reviewer's contract names it (story_criterion_mark_values), and retire-criteria.py accepts a name copied with it.
+# shellcheck source=plan-of-record.sh
+declare -F plan_of_record_ensured >/dev/null 2>&1 || . "$(dirname "${BASH_SOURCE[0]}")/plan-of-record.sh"
+# shellcheck source=render-engine-prompt.sh
+declare -F render_engine_prompt >/dev/null 2>&1 || . "$(dirname "${BASH_SOURCE[0]}")/render-engine-prompt.sh"
+story_criterion_mark() {
+    local _v _m; _v=$(mktemp "${TMPDIR:-/tmp}/criterion-origin-XXXXXX.json"); echo '{}' > "$_v"
+    _m=$(render_engine_prompt criterion-origin "$_v" remediation); rm -f "$_v"; printf '%s' "$_m"
+}
+# story_criterion_mark_values — the mark as a values object for a template that names it (__REMEDIATION_MARK__).
+story_criterion_mark_values() {
+    jq -cn --arg m "$(story_criterion_mark)" '{"__REMEDIATION_MARK__": $m}'
+}
+# B84 (finding RS-18): WHAT IS LOST IS SAID. The block stays what callers expect (stdout empty, status 0 — nothing is added to or removed from a prompt),
+# but a PRD that cannot be read, a PRD without the story, or a plan of record that cannot be read is named on stderr: the reviewer would otherwise judge without
+# criteria, or with the remediator's criteria unmarked, and nothing would say so. A story that simply declares no criteria (brownfield) is silent.
+_story_acs_said() { printf '[story-acs-block] %s\n' "$*" >&2; }
+story_acs_block() {
+    local _prd="${1:-}" _id="${2:-}" _heading="${3:-ACCEPTANCE CRITERIA:}"
+    [ -n "$_prd" ] && [ -n "$_id" ] || return 0
+    if [ ! -f "$_prd" ]; then _story_acs_said "the PRD $_prd was not found — no acceptance-criteria block for $_id"; return 0; fi
+    # WHAT THE PLAN IS — the plan of record (lib/plan-of-record.sh), never a criterion's shape. A criterion it does not
+    # list, or one the remediator stamped, is marked. With no plan of record only the stamp marks.
+    local _plan _list _plan_json=null _err
+    _plan=$(plan_of_record_ensured 2>/dev/null || true)
+    if [ -n "$_plan" ]; then
+        _plan_json=$(jq -c --arg id "$_id" '[.stories[] | select(.id == $id) | .acceptanceCriteria[]? | if type == "object" then (.text // "") else tostring end]' "$_plan" 2>/dev/null) \
+            || { _story_acs_said "the plan of record $_plan cannot be read — the criteria of $_id are shown but not marked against the plan"; _plan_json=null; }
+        [ -n "$_plan_json" ] || _plan_json=null
+    fi
+    _err=$(mktemp "${TMPDIR:-/tmp}/story-acs-err-XXXXXX")
+    _list=$(jq -r --arg id "$_id" --arg mark "$(story_criterion_mark)" --argjson plan "$_plan_json" \
+        '.stories[] | select(.id == $id) | .acceptanceCriteria // [] | map(select(. != null and . != "")) | to_entries
+         | map(.value as $v | ($v | if type == "object" then (.text // tostring) else tostring end) as $t
+               | "AC\(.key+1): " + $t
+               + (if (($v | type) == "object" and (($v.origin // "") == "remediation"))
+                     or ($plan != null and (($plan | index($t)) == null))
+                  then "  " + $mark else "" end))
+         | join("\n")' \
+        "$_prd" 2>"$_err")
+    local _rc=$?
+    if [ "$_rc" -ne 0 ]; then
+        _story_acs_said "the PRD $_prd is not readable for $_id ($(head -c 200 "$_err" | tr '\n' ' ')) — no acceptance-criteria block"
+        rm -f "$_err"; return 0
+    fi
+    rm -f "$_err"
+    if [ -z "$_list" ] && ! jq -e --arg id "$_id" '.stories[]? | select(.id == $id)' "$_prd" >/dev/null 2>&1; then
+        _story_acs_said "story $_id is not in the PRD $_prd — no acceptance-criteria block"
+        return 0
+    fi
+    [ -n "$_list" ] || return 0
+    printf '%s\n%s\n\n' "$_heading" "$_list"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amsd-pipeline-shared",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "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": {