amsd-pipeline-shared 0.5.0 → 0.5.2

package/orchestrations/scripts/lib/run-modes.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# NAMED RUN MODES. "Resume the writer" is one word, not six variables to remember.
+#
+# On 2026-08-13 an operator asked for a writer resume. It was launched with three environment
+# variables and needed six, so the CPA pre-pass, the pre-phase skill assessment and the regression
+# guard ran anyway — each a separate default-ACTIVE step, none tied to the stated intent. The
+# operator noticed four minutes in.
+#
+# THIS FILE KNOWS NO MODES. It reads orchestrations/config/run-modes.json. Adding a mode is a
+# config edit; the engine never learns a mode's name.
+#
+# TWO RULES:
+#   FAILS CLOSED — an unknown mode, or a declaration file that will not parse, is a hard error.
+#     Silently ignoring either runs every gate the operator believed they had turned off.
+#   PRECEDENCE IS operator environment > mode > config-file default. A mode must beat a default
+#     (config.env carries SKIP_REGRESSION_GUARD=false, which silently defeated writer-only) while
+#     still yielding to a deliberate choice on the launch command — writer-only WITH the regression
+#     baseline is a legitimate thing to ask for. The two are only distinguishable before the config
+#     files load, which is what snapshot_operator_env captures.
+
+RUN_MODES_FILE="${RUN_MODES_FILE:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../config/run-modes.json}"
+
+# snapshot_operator_env — record which variables the OPERATOR set, before any config file is read.
+#
+# A mode must override a config-file DEFAULT (config.env carries SKIP_REGRESSION_GUARD=false, which
+# silently defeated writer-only on 2026-08-13) while still yielding to a deliberate choice on the
+# launch command. Those two are indistinguishable once both are in the environment — unless you
+# look BEFORE the config files load, which is the one moment only the operator's values exist.
+#
+# Launchers call this before their first load_env_file_safe. A caller that never calls it gets the
+# mode applied in full, which is the safe failure: a half-applied intent is worse than none.
+snapshot_operator_env() {
+    EPAM_OPERATOR_SET_VARS=" $(compgen -e 2>/dev/null | tr '\n' ' ')"
+    export EPAM_OPERATOR_SET_VARS
+}
+
+# run_mode_env <mode> — print the KEY=VALUE lines a mode declares. Non-zero if unknown.
+run_mode_env() {
+    local _mode="${1:-}"
+    [ -n "$_mode" ] || return 0
+    "${NODE_BIN:-node}" -e '
+      const fs = require("fs");
+      const [file, mode] = process.argv.slice(1);
+      let doc;
+      try {
+        doc = JSON.parse(fs.readFileSync(file, "utf8"));
+      } catch (e) {
+        process.stderr.write(`run-modes: cannot read ${file}: ${e.message}\n`);
+        process.exit(2);
+      }
+      const modes = doc.modes || {};
+      if (!Object.prototype.hasOwnProperty.call(modes, mode)) {
+        process.stderr.write(`run-modes: unknown mode "${mode}". Declared: ${Object.keys(modes).join(", ")}\n`);
+        process.exit(3);
+      }
+      const skips = modes[mode].skips || [];
+      process.stdout.write(skips.join("\n") + (skips.length ? "\n" : ""));
+    ' "$RUN_MODES_FILE" "$_mode"
+}
+
+# apply_run_mode <mode> — export what the mode declares, leaving anything already set alone.
+apply_run_mode() {
+    local _mode="${1:-}"
+    [ -n "$_mode" ] || return 0
+
+    local _env
+    _env=$(run_mode_env "$_mode") || {
+        if command -v error >/dev/null 2>&1; then
+            error "[run-mode] refusing to run: mode '$_mode' is not declared in $RUN_MODES_FILE"
+        else
+            printf '[run-mode] refusing to run: mode %s is not declared in %s\n' "$_mode" "$RUN_MODES_FILE" >&2
+        fi
+        return 1
+    }
+
+    local _line _key _val _already
+    while IFS= read -r _line; do
+        [ -n "$_line" ] || continue
+        _key="${_line%%=*}"
+        _val="${_line#*=}"
+        # Set by the OPERATOR — before any config file was read — so it wins. A value that only
+        # appeared once config.env loaded is a project default, and the mode is more specific than
+        # a default: the operator named this intent on the command line.
+        case "${EPAM_OPERATOR_SET_VARS:-}" in
+            *" ${_key} "*) continue ;;
+        esac
+        eval "export ${_key}=\"\$_val\""
+    done <<< "$_env"
+
+    RESOLVED_RUN_MODE="$_mode"
+    export RESOLVED_RUN_MODE
+    return 0
+}

package/orchestrations/scripts/lib/story-outputs.sh

@@ -0,0 +1,322 @@
+#!/usr/bin/env bash
+# story-outputs.sh — one shared answer to "what did this run actually produce?"
+#
+# Step 20's lint gate was fixed by handing it the writers' output instead of
+# letting it rediscover scope by linting the whole tree (see
+# lib/eslint-baseline-gate.sh). The reviewers still inferred it, each in its own
+# slightly different way — team-lead-review.sh, review-ranger and mutant-hunter
+# all reimplemented `git diff --name-only <baseline>..HEAD`. Three copies of one
+# idea is how they drift, and they already had:
+#
+#   * `<baseline>..HEAD` is commit-to-commit, so writer output not yet committed
+#     is invisible to review. The repro-test-writer commits separately from the
+#     impl agent, so this is a normal state, not an edge case.
+#   * All three fell back to `HEAD~1` when the baseline SHA file was missing —
+#     silently. That is the review-oracle failure shape: the diff covers an
+#     arbitrary previous commit, the reviewers examine nothing this run
+#     produced, and the gate reports success.
+#
+# The producer is record_story_outputs() in claude.sh. This is the reader.
+# STORY_OUTPUTS_SOURCE is set to manifest | baseline diff | none so callers can
+# report which one they got — a gate that quietly changes how it computes its
+# own scope is indistinguishable from one that is broken.
+
+# Paths the pipeline writes into a client repo. Never story output.
+# Was a two-entry regex ('^(\.codegraph/|\.epam/)') that missed orchestrations/,
+# .deepeval/ and .contracts/ — which is how orchestrations/agents/KB.md was recorded as
+# upexpress's writer output on run 20260804T225443Z. One shared definition now.
+# shellcheck source=engine-paths.sh
+. "$(dirname "${BASH_SOURCE[0]}")/engine-paths.sh"
+
+# Test-file conventions. Deliberately broad: mutant-hunter used to look only for
+# `*.test.ts` and therefore found nothing on the live metrolinx codeline, whose
+# tests are all `.spec.ts` — it reported "(no test files found)" on a run that
+# had just written a reproducing spec.
+_STORY_OUTPUTS_TEST_RE='(\.|_)(spec|test)\.[A-Za-z0-9]+$|/__tests__/|(^|/)test_[^/]+$'
+
+# story_outputs_record <project_root> <log_dir>
+# Appends what this producer just put in the tree to the phase manifest.
+#
+# Shared because there is more than one producer and they finish at different
+# times. Live metrolinx 2026-07-26: only the story loop recorded, at deliverable
+# verification — but the repro-test-writer commits its .spec.ts AFTERWARDS, so
+# the test never entered the manifest. mutant-hunter, freshly rewired to read
+# its tests from that manifest, saw none, every mutant survived, it scored 0 and
+# failed the gate — on a run whose test the repro gate had just proven fails on
+# baseline and passes with the fix. The gate then ran its remediation pipeline
+# against a finding that existed only because of the missing entry.
+#
+# Additive and idempotent: each producer records its own contribution and the
+# list is the union. Writes nothing when there is no baseline to diff against
+# (greenfield) — an ABSENT manifest means "fall back and say so", while an EMPTY
+# one would assert the writers produced nothing. Never fails the caller.
+story_outputs_record() {
+    local project_root="$1"
+    local log_dir="$2"
+    [ -n "$log_dir" ] || return 0
+    [ -n "$project_root" ] && [ -e "$project_root/.git" ] || return 0
+
+    # THE BASELINE SHA IS THE LANE'S IDENTITY. It resolves only in that lane's own repo
+    # (verified against all three live metrolinx lanes), so requiring it makes git's object
+    # database the identity oracle — no path comparison, no configuration.
+    #
+    # The `origin/${JIRA_BASELINE_BRANCH:-develop}` fallback this replaces is the silent
+    # wrong-scope shape this file's own header complains about: any repo that happens to
+    # have that ref satisfies it, including the engine's own.
+    local _ref
+    _ref=$(story_outputs_baseline_ref "$log_dir") || return 0
+    [ -n "$_ref" ] || return 0
+    git -C "$project_root" rev-parse --verify --quiet "${_ref}^{commit}" >/dev/null 2>&1 || return 0
+
+    local _manifest="$log_dir/story-outputs-${PHASE:-core}.txt"
+    # --diff-filter=ACMRT: Added/Copied/Modified/Renamed/Typechanged. DELETED paths are
+    # excluded deliberately — a path handed to a reviewer as "writer output" must exist, or
+    # story_outputs_tests nominates a test that cannot run. Deletions are reported
+    # separately by story_outputs_deleted, because a writer removing 10 tests is exactly
+    # what a gate needs to see and the old manifest lost it entirely.
+    local _produced
+    _produced=$( { git -C "$project_root" diff --name-only --diff-filter=ACMRT "$_ref" 2>/dev/null
+                   git -C "$project_root" ls-files --others --exclude-standard 2>/dev/null; } | \
+                 engine_paths_filter | grep -v '^$' | sort -u )
+
+    # OVERWRITE, never union. The previous form was
+    #   { cat "$_manifest"; printf '%s' "$_produced"; } | sort -u
+    # which can only ever grow: a file the writer reverted, or one recorded when a wrong
+    # root was passed, stayed listed forever with no provenance to say when it entered.
+    # The union was also unnecessary — the diff is against the PHASE BASELINE, so work a
+    # LATE producer committed (the repro-test-writer commits its spec after the story loop)
+    # is already included by recomputing.
+    #
+    # Written even when empty: with a valid baseline, "nothing was produced" is a FACT and
+    # the manifest should say so. ABSENT still means "no baseline — fall back and say so".
+    printf '%s\n' "$_produced" | grep -v '^$' > "${_manifest}.tmp" 2>/dev/null || true
+    mv "${_manifest}.tmp" "$_manifest" 2>/dev/null || rm -f "${_manifest}.tmp"
+    return 0
+}
+
+# story_outputs_baseline_ref <log_dir> — the phase baseline SHA, or non-zero if unknown.
+story_outputs_baseline_ref() {
+    local _log_dir="$1"
+    [ -f "$_log_dir/phase-baseline-sha.txt" ] || return 1
+    local _sha
+    _sha=$(tr -d '[:space:]' < "$_log_dir/phase-baseline-sha.txt" 2>/dev/null)
+    [ -n "$_sha" ] || return 1
+    printf '%s' "$_sha"
+}
+
+# story_outputs_deleted <project_root> <log_dir> — paths this phase REMOVED.
+#
+# The reviewer on run 20260804T225443Z reported the writer had deleted a 179-line test file
+# containing 10 tests, with no replacement. No manifest showed it: the producer recorded
+# deletions as though they were outputs, and every consumer then filtered them out as
+# missing files. Test count going DOWN is a gate-relevant fact and now has a channel.
+story_outputs_deleted() {
+    local project_root="$1"
+    local log_dir="$2"
+    [ -n "$project_root" ] && [ -e "$project_root/.git" ] || return 0
+    local _ref
+    _ref=$(story_outputs_baseline_ref "$log_dir") || return 0
+    git -C "$project_root" rev-parse --verify --quiet "${_ref}^{commit}" >/dev/null 2>&1 || return 0
+    git -C "$project_root" diff --name-only --diff-filter=D "$_ref" 2>/dev/null | \
+        engine_paths_filter | grep -v '^$' | sort -u
+    return 0
+}
+
+# story_outputs_files <project_root> <log_dir>
+# Prints repo-relative paths, one per line. Sets STORY_OUTPUTS_SOURCE.
+story_outputs_files() {
+    local project_root="$1"
+    local log_dir="$2"
+    STORY_OUTPUTS_SOURCE="none"
+
+    [ -n "$project_root" ] && [ -e "$project_root/.git" ] || return 0
+
+    local manifest="$log_dir/story-outputs-${PHASE:-core}.txt"
+    local raw=""
+    # -f, not -s: an EMPTY manifest is a real answer ("the writers produced nothing"),
+    # distinct from an ABSENT one ("no baseline — fall back and say so").
+    if [ -f "$manifest" ]; then
+        STORY_OUTPUTS_SOURCE="manifest"
+        raw=$(cat "$manifest" 2>/dev/null)
+    else
+        local baseline=""
+        if [ -f "$log_dir/phase-baseline-sha.txt" ]; then
+            baseline=$(tr -d '[:space:]' < "$log_dir/phase-baseline-sha.txt" 2>/dev/null)
+        fi
+        if [ -z "$baseline" ]; then
+            # No manifest and no baseline. Previously every caller substituted
+            # HEAD~1 here and reviewed an arbitrary commit. Returning an empty
+            # scope lets the caller say "nothing to review" truthfully instead.
+            return 0
+        fi
+        # TO STDERR: this function's stdout IS the scope a caller captures; a warning there was counted as a changed
+        # file and sent an unchanged story to review (rehearsal 2026-10-08).
+        command -v warning >/dev/null 2>&1 && \
+            warning "  no writer-output manifest at $manifest — falling back to the baseline diff for scope" >&2
+        export STORY_OUTPUTS_SOURCE="baseline diff"
+        raw=$( { git -C "$project_root" diff --name-only --diff-filter=ACMRT "$baseline" 2>/dev/null
+                 git -C "$project_root" ls-files --others --exclude-standard 2>/dev/null; } )
+    fi
+
+    printf '%s\n' "$raw" | grep -v '^$' | engine_paths_filter | sort -u
+    return 0
+}
+
+# story_outputs_tests <project_root> <log_dir> — test files only
+story_outputs_tests() {
+    story_outputs_files "$1" "$2" | grep -E "$_STORY_OUTPUTS_TEST_RE" || true
+}
+
+# story_outputs_tests_for <project_root> <log_dir> <story_id> — THIS story's test files.
+#
+# story_outputs_tests reads the PHASE manifest, which carries no story attribution at all. So a
+# caller looping over stories and taking `| head -1` gave every story in the phase the SAME test
+# file — the first one written by anybody. Step 3.56 did exactly that, and reported story B's
+# verification-criteria coverage against story A's test: a check that ran, produced a plausible
+# artefact, and measured the wrong thing.
+#
+# The story's own commit is the attribution that does exist. commit_completed_story writes
+# "<story_id>: story complete (N file(s))" and keeps that marker stable precisely so it can be
+# grepped — reset-to-baseline.sh already keys off it.
+#
+# Prints nothing when the story has no commit. That is a real answer: no commit means no files,
+# which the caller must report as "not checked", never as "covered".
+story_outputs_tests_for() {
+    local project_root="$1" story_id="$3"
+    [ -n "$project_root" ] && [ -e "$project_root/.git" ] || return 0
+    [ -n "$story_id" ] || return 0
+    # EVERY COMMIT OF THE STORY, not the one that says "story complete".
+    #
+    # The writer no longer produces a single commit: the fix and the bug-reproducing test land
+    # separately, and the fix's subject is free-form. Measured 2026-08-28 on the first fully green
+    # paid run — MOCK3-1's fix was "Fix: correct fare boundary for riders aged exactly 65" with no
+    # marker, and MOCK3-2's marker commit carried only its source. Both stories reported "no test
+    # file in the writer manifest — coverage NOT checked" while their tests sat on the branch. The
+    # gate ran, warned, and measured nothing, on a run reported green.
+    #
+    # The story-id PREFIX is the attribution the commit convention already requires, and it keeps
+    # the property this function exists for: one story never sees another's test.
+    #
+    # Scoped to the phase baseline where one is recorded, so a previous run's commit for the same
+    # story id cannot be mistaken for this run's work.
+    local _range=""
+    if [ -n "${2:-}" ] && [ -f "$2/phase-baseline-sha.txt" ]; then
+        local _base; _base=$(tr -d '[:space:]' < "$2/phase-baseline-sha.txt" 2>/dev/null)
+        [ -n "$_base" ] && git -C "$project_root" rev-parse --verify --quiet "$_base" >/dev/null 2>&1 \
+            && _range="${_base}..HEAD"
+    fi
+    git -C "$project_root" log ${_range:+"$_range"} --grep="^${story_id}:" \
+        --pretty=format: --name-only 2>/dev/null \
+        | grep -E "$_STORY_OUTPUTS_TEST_RE" 2>/dev/null | sort -u || true
+}
+
+# story_resume_completed_by_commit <project_root> <lane_log_dir> <lane_prd>
+#
+# A RESUME DOES NOT REWRITE COMMITTED WORK. A lane resumes from its pre-writer checkpoint, whose PRD predates the
+# writer, so every story reads "not completed" and the writer is invoked again — AMSD-2974 run 9, resume 3: "I didn't
+# need to change any code this turn: the earlier commit d429022 … already contains all three fixes", a paid call that
+# changed nothing, then a full review. A story whose work is committed in THIS run (the "<story>:" convention, scoped
+# to the lane's phase baseline) with no review rejection NEWER than that commit is marked completed in the lane PRD:
+# the writer skips it and the review judges the committed change. A newer rejection leaves it for the writer.
+story_resume_completed_by_commit() {
+    local project_root="$1" log_dir="$2" prd="$3"
+    [ -n "$project_root" ] && [ -e "$project_root/.git" ] && [ -f "$prd" ] || return 0
+    [ -f "$log_dir/phase-baseline-sha.txt" ] || return 0
+    local _base; _base=$(tr -d '[:space:]' < "$log_dir/phase-baseline-sha.txt" 2>/dev/null)
+    [ -n "$_base" ] && git -C "$project_root" rev-parse --verify --quiet "$_base" >/dev/null 2>&1 || return 0
+    local _id _ct _fb _fbt
+    for _id in $(jq -r '.stories[]? | select(.completed != true) | .id' "$prd" 2>/dev/null); do
+        _ct=$(git -C "$project_root" log "${_base}..HEAD" --grep="^${_id}:" -1 --format=%ct 2>/dev/null)
+        [ -n "$_ct" ] || continue
+        _fb="$log_dir/review-feedback-${_id}.json"
+        if [ -f "$_fb" ]; then
+            _fbt=$(stat -c %Y "$_fb" 2>/dev/null || echo 0)
+            [ "${_fbt:-0}" -gt "$_ct" ] && continue
+        fi
+        local _tmp; _tmp=$(mktemp)
+        jq --arg id "$_id" '(.stories[] | select(.id == $id)) |= (. + {completed: true})' "$prd" > "$_tmp" \
+            && mv "$_tmp" "$prd" || rm -f "$_tmp"
+        echo "[resume] ${_id}: its work is committed in this run ($(git -C "$project_root" log "${_base}..HEAD" --grep="^${_id}:" -1 --format=%h 2>/dev/null)) and no review rejection is newer — the writer is not invoked again; the review judges the committed change"
+    done
+    return 0
+}
+
+# story_outputs_sources <project_root> <log_dir> — everything that is not a test
+story_outputs_sources() {
+    story_outputs_files "$1" "$2" | grep -v -E "$_STORY_OUTPUTS_TEST_RE" || true
+}
+
+# ── THE RUNG THAT PRODUCED IT ────────────────────────────────────────────────
+#
+# Operator, 2026-08-22: "if writer's model moves up ladder, the reviewer must follow along and
+# use the same rung EXACT setup the writer used to converge. No hard coding. No guards.
+# Persistence."
+#
+# A RUNG IS NOT A MODEL. The writer's ladder moves model, provider, reasoning effort and
+# temperature together — rung 1 sets effort medium / temp 0, rung 2 escalates the model, rung 3
+# goes effort high / temp 0.7 — so a reviewer handed only the model still judges converged work
+# on a configuration the writer never ran.
+#
+# WRITTEN ON EVERY ATTEMPT, at the point the rung is settled and before the writer is invoked
+# (claude.sh, immediately after the escalation block closes). Deliberately not on a success
+# path: the last write is by definition the rung that produced the final output, whatever
+# happened on the way there, and a story that ends in rejection still has a real rung.
+#
+# Why persisted rather than passed in memory: run-agent-orchestration.sh spawns the writer as a
+# CHILD PROCESS per story (:2333) and the reviewer as a separate process per cycle (:7909). No
+# in-memory value crosses that. The reviewer's own ladder resume already works this way, for
+# this same reason.
+_story_rung_file() { echo "$1/story-rung/$2.json"; }
+
+# story_rung_record <log_dir> <story_id>
+# Captures the CURRENT rung from the writer's own variables. No arguments, on purpose: a
+# parameter list is a second definition of what a rung is, and it drifts the first time
+# claude.sh adds a knob to the ladder.
+story_rung_record() {
+    local log_dir="$1" story_id="$2"
+    [ -n "$log_dir" ] && [ -n "$story_id" ] || return 0
+    mkdir -p "$log_dir/story-rung" 2>/dev/null || true
+    jq -n \
+        --arg model       "${STORY_MODEL:-}" \
+        --arg provider    "${STORY_PROVIDER:-}" \
+        --arg effort      "${EPAM_REASONING_EFFORT:-}" \
+        --arg temperature "${EPAM_TEMPERATURE:-}" \
+        --arg iterations  "${STORY_MAX_ITERATIONS:-}" \
+        --arg outTokens   "${STORY_MAX_OUTPUT_TOKENS:-}" \
+        '{model:$model, provider:$provider, reasoningEffort:$effort,
+          temperature:$temperature, maxIterations:$iterations, maxOutputTokens:$outTokens}' \
+        > "$(_story_rung_file "$log_dir" "$story_id")" 2>/dev/null || true
+}
+
+# story_rung_get <log_dir> <story_id> <field>
+# Empty when the story has no rung on record. ABSENT IS NOT A DEFAULT: a caller that substitutes
+# something here makes a judge authoritative about work whose setup it never saw.
+# A RUNG RECORD THAT IS GONE IS DERIVED FROM THE RUN'S OWN LEDGER — never guessed, never written by
+# hand. regintel resume 3 (2026-09-21): the reset had wiped story-rung/ and the reviewer refused a
+# story the run itself had completed. The cost ledger holds the completed attempt's resolvedModel
+# and effort; the activity ledger the provider the story started on. What is derived is persisted,
+# marked derivedFrom, so the next reader finds a record. A story the ledger never completed derives
+# nothing, and the reviewer's refusal stands.
+_story_rung_derive() {
+    local log_dir="$1" story_id="$2" f cost act model effort provider
+    cost="$log_dir/phase-cost.jsonl"; act="$log_dir/agent-activity.jsonl"
+    [ -f "$cost" ] || return 0
+    model=$(jq -r --arg s "$story_id" 'select(.story_id == $s and .status == "completed") | .resolvedModel // ""' "$cost" 2>/dev/null | grep -v '^$' | tail -1)
+    [ -n "$model" ] || return 0
+    effort=$(jq -r --arg s "$story_id" 'select(.story_id == $s and .status == "completed") | .effort // ""' "$cost" 2>/dev/null | tail -1)
+    provider=""
+    [ -f "$act" ] && provider=$(jq -r --arg s "$story_id" 'select((.storyId // .story_id) == $s and .provider != null) | .provider' "$act" 2>/dev/null | grep -v '^$' | tail -1)
+    f="$(_story_rung_file "$log_dir" "$story_id")"
+    mkdir -p "$(dirname "$f")" 2>/dev/null || true
+    jq -n --arg model "$model" --arg provider "$provider" --arg effort "$effort" \
+        '{model:$model, provider:$provider, reasoningEffort:$effort, temperature:"", maxIterations:"", maxOutputTokens:"",
+          derivedFrom:"ledger: phase-cost.jsonl (completed attempt) + agent-activity.jsonl (provider)"}' > "$f" 2>/dev/null || true
+    echo "[story-rung] $story_id: no record on disk — rung derived from this run's ledger (model=$model provider=${provider:-?})" >&2
+}
+
+story_rung_get() {
+    local f; f="$(_story_rung_file "$1" "$2")"
+    [ -f "$f" ] || _story_rung_derive "$1" "$2"
+    [ -f "$f" ] || return 0
+    jq -r --arg k "$3" '.[$k] // ""' "$f" 2>/dev/null || true
+}