amsd-pipeline-shared 0.5.0 → 0.5.2

package/orchestrations/scripts/lib/orchestration-resume.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# orchestration-resume.sh — SHOULD THIS RUN PICK UP WHERE ANOTHER LEFT OFF?
+#
+# Extracted verbatim from run-agent-orchestration.sh, where it sat as a top-level block among that
+# file's function definitions and could therefore be reached only by running the whole pipeline.
+#
+# What it decides is not small: a resume restores a checkpoint, works out which steps to skip, and
+# then continues the run or refuses it. Three refusals guard it, and the file prices the last one —
+# a resume that skips the spec pass against a PRD carrying none of its output hands the writer a
+# story with nothing to aim at, measured 2026-08-10 at $11.76 and no code.
+#
+# PURE CODE MOVEMENT. Assignments without `local` stay global, so ORCH_RUN_ID and the exported skip
+# environment reach the rest of the run exactly as before, and `exit` still exits the script.
+#
+# Requires from its caller: is_parent, restore_run_checkpoint, list_run_checkpoints,
+# resume_skip_env, resume_spec_output_present, error/info/success, and PRD_FILE.
+
+# THE SPEC PASS RUNS ON A RESUME FOR THE STORIES THAT LACK IT. The run mode turns the pass off
+# for a resume, which is right only while every pending story was elaborated; a story whose
+# content the remediation restored from canonical (its elaboration had gone to a placeholder
+# child) reached the writer with no spec, paid for (regintel run 20260915T101555Z, 2026-09-15).
+# The pass is turned back on when any pending story of the phase carries no spec output; the
+# spec runner then takes those stories and skips the elaborated ones (storiesForSpecPass).
+resume_spec_mode_for_pending_stories() {
+    [ "${EPAM_SPEC_MODE:-1}" = "0" ] || return 0
+    [ -n "${PRD_FILE:-}" ] && [ -f "${PRD_FILE}" ] || return 0
+    local _lacking
+    _lacking=$("${NODE_BIN:-node}" "$SCRIPT_DIR/lib/handlers/stories-lacking-spec.js" "$PRD_FILE" "${PHASE:-}" 2>/dev/null | tr '\n' ' ')
+    [ -n "${_lacking// /}" ] || return 0
+    info "[orch]   resume: EPAM_SPEC_MODE=1 — pending story(ies) with no spec output: ${_lacking}(the spec pass runs for these and skips the rest)"
+    export EPAM_SPEC_MODE=1
+    return 0
+}
+
+apply_resume_if_requested() {
+    if is_parent && [ -n "${EPAM_RESUME_RUN:-}" ]; then
+        # The roster and its briefs are stored against the run that minted them, so a resumed run
+        # must BE that run — otherwise the store reads as another run's and is not re-applied.
+        export ORCH_RUN_ID="$EPAM_RESUME_RUN"
+    
+        if ! restore_run_checkpoint "$EPAM_RESUME_RUN"; then
+            error "[orch] cannot resume run '${EPAM_RESUME_RUN}' — refusing to continue against un-restored state."
+            error "[orch] available checkpoints: $(list_run_checkpoints | tr '\n' ' ' 2>/dev/null || echo none)"
+            exit 1
+        fi
+    
+        if ! _resume_env=$(resume_skip_env "$EPAM_RESUME_RUN"); then
+            error "[orch] cannot determine what to skip for run '${EPAM_RESUME_RUN}' — refusing to guess."
+            exit 1
+        fi
+        while IFS= read -r _assign; do
+            [ -n "$_assign" ] || continue
+            export "${_assign?}"
+            info "[orch]   resume: ${_assign}"
+        done <<< "$_resume_env"
+        # Skipping the spec pass is only safe while its output still exists. restore_run_checkpoint
+        # and resume_skip_env both refuse rather than guess; this is the third case and was the
+        # silent one. Gated on the skip actually being in force — a resume that is about to RUN the
+        # spec pass has nothing to protect.
+        resume_spec_mode_for_pending_stories
+        if [ "${EPAM_SPEC_MODE:-1}" = "0" ] && ! resume_spec_output_present "$PRD_FILE"; then
+            error "[orch] resume '${EPAM_RESUME_RUN}' skips the spec pass (EPAM_SPEC_MODE=0), but the PRD"
+            error "[orch] at ${PRD_FILE} carries none of its output — no fixSiteAnalysis, no"
+            error "[orch] verificationCriteria, no declared files, no specification block."
+            error "[orch] Something overwrote the PRD after the spec pass ran. Running now would hand the"
+            error "[orch] writer a story with nothing to aim at — measured 2026-08-10 at \$11.76 and no code."
+            error "[orch] Recover with ONE of:"
+            error "[orch]   - restore the PRD that carries the spec (git, or a run archive), then resume again"
+            error "[orch]   - re-run the spec pass for this run: EPAM_SPEC_MODE=1 with the same EPAM_RESUME_RUN"
+            exit 1
+        fi
+        success "[orch] RESUMED run ${EPAM_RESUME_RUN} — continuing from its checkpoint"
+    fi
+}

package/orchestrations/scripts/lib/phase-exit.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# WHAT A PHASE'S EXIT CODE MEANS — DEFINED ONCE.
+#
+# run-agent-orchestration.sh exits non-zero for two completely different reasons, and
+# until 2026-08-14 both were exit 2:
+#
+#   REMEDIATED  a gate applied a fix; re-running the phase is expected to now pass.
+#   HALT        a change the reviewer never approved, at an EXHAUSTED ladder.
+#               Re-running cannot help — there is no higher rung to try.
+#
+# SEVEN separate call sites each wrote `if [ "$phase_exit" -eq 2 ]; then ...retry...`
+# — run-agent-orchestration.sh (twice), orchestrate.sh, and four tier3 launchers
+# (metrolinx, mock, skyscanner, travel-app) — so a HALT was retried by all of them.
+# The first sweep for this found only three; the class was wider than the sites that
+# happened to be open at the time, which is exactly why the comparison lives here now
+# and not at any call site.
+#
+# WHAT THAT COST, live run 20260814T213253Z (metrolinx, AMSD-2041): Step 3.6 correctly
+# printed "A change the reviewer never approved must NOT proceed — human review
+# required" and exited. The caller read 2, called it remediation, and retried. The
+# retry re-entered ensure_story_branch, which hard-reset the branch and orphaned the
+# already-committed, already-green work; it then burned 12 further attempts against a
+# ladder that had nothing left to escalate to, and failed. The pipeline spent ~15
+# minutes and real money to arrive where Step 3.6 already was.
+#
+# The distinction is the whole point, so it lives in ONE place. A caller asks
+# `phase_exit_is_retryable`; no caller compares a bare integer.
+
+# Exit code vocabulary. Values are the contract with run-agent-orchestration.sh.
+PHASE_EXIT_OK=0
+PHASE_EXIT_REMEDIATED=2
+PHASE_EXIT_HALT_REVIEW=3
+PHASE_EXIT_TESTS_STRENGTHENED=4
+
+# THE CODE WAS RIGHT; ITS TESTS WERE NOT (AMSD-2974 live L2, 2026-10-14). A gate finding that only tests can
+# resolve — a surviving mutant in correct code — went to the AC remediator and back to the CODE writer, who is
+# forbidden to touch tests, and looped. Such a finding now goes to the test-writer, which commits the
+# strengthened test; the phase is re-run on that commit WITHOUT --reset, so the stories keep their approved
+# work, Step 1 passes them as completed, and the review and the gates judge the new commit.
+
+# phase_exit_is_retryable <code>
+# True (0) ONLY for the code that means "a fix was applied, try again". Everything else
+# — success, halt, and any unrecognised code — is not retryable. An unknown code is
+# deliberately NOT retried: re-running an outcome nobody has classified is how a HALT
+# came to be retried in the first place.
+phase_exit_is_retryable() {
+    [ "${1:-}" = "$PHASE_EXIT_REMEDIATED" ] || [ "${1:-}" = "$PHASE_EXIT_TESTS_STRENGTHENED" ]
+}
+
+# phase_exit_retry_args <code> — the arguments a retry of this outcome re-runs the phase with, one per line.
+# REMEDIATED changed what the stories must do, so they are reset and re-written; TESTS_STRENGTHENED changed only
+# the tests, so the stories keep their work and the phase re-judges it.
+phase_exit_retry_args() {
+    case "${1:-}" in
+        "$PHASE_EXIT_REMEDIATED") printf '%s\n' '--reset' ;;
+        *) ;;
+    esac
+}
+
+# phase_exit_describe <code>
+# One line naming the outcome, so a failure reads as a decision rather than a number.
+phase_exit_describe() {
+    case "${1:-}" in
+        "$PHASE_EXIT_OK")          echo "completed" ;;
+        "$PHASE_EXIT_REMEDIATED")  echo "gate remediation applied — a retry is expected to help" ;;
+        "$PHASE_EXIT_TESTS_STRENGTHENED") echo "the test-writer strengthened the tests a gate found insufficient — the gates re-run on that commit" ;;
+        "$PHASE_EXIT_HALT_REVIEW") echo "HALT: the reviewer never approved the change and the ladder is exhausted — human review required, a retry cannot help" ;;
+        *)                         echo "failed (exit ${1:-?})" ;;
+    esac
+}
+
+# phase_retry_mark <codeline-root> — what the codeline holds before a self-heal retry (its commit), for
+# phase_retry_progressed. Empty when the root is not a repository.
+phase_retry_mark() {
+    git -C "${1:-.}" rev-parse -q --verify HEAD 2>/dev/null || true
+}
+
+# phase_retry_progressed <codeline-root> <mark> — true when the retry changed what the codeline holds.
+#
+# THE PIPELINE NEVER LOOPS (operator, 2026-10-14: "pipeline should NEVER get into a loop!!!"). A retry is repeated
+# while its gates remediate; AMSD-2974 live run L2 retried the 7.x line five times — each time the remediator added
+# criteria, the writer committed nothing, the same code failed the same gate (~$2.50 a round). A retry that changed
+# nothing cannot make the next one different: it is not repeated. With no mark (no repository), progress cannot be
+# told, and the retry is not repeated either.
+phase_retry_progressed() {
+    local _now
+    [ -n "${2:-}" ] || return 1
+    _now=$(phase_retry_mark "${1:-.}")
+    [ -n "$_now" ] && [ "$_now" != "$2" ]
+}

package/orchestrations/scripts/lib/pipeline-commit.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# pipeline_commit_flags — the flags every commit the PIPELINE makes passes to `git commit`, one per line.
+#
+# A codeline's hooks are written for its team's own checkout and machine. Operator decisions,
+# 2026-10-05 (AMSD-2974): the pipeline's commits skip them — first inside worktrees, then in the
+# checkout too. Proven on a copy of next.gotransit.com: its pre-commit hook (husky + lint-staged)
+# type-checks the WHOLE project, which fails on the untouched checkout with 6 errors because the
+# team's node_modules is older than its own develop branch expects (it needs an `npm install`, which
+# the pipeline may not run) — so the hook refused every pipeline commit there, whatever it held, and
+# the reproducing test of a correct fix was never committed. In worktrees the same hook also refused
+# the branch name and sourced a helper git does not track.
+#
+# What the hook checks is still checked by the pipeline: the story's own verification, Step 19/20's
+# type check judged against the phase baseline, the lint gate, review and the QA gates. The Step 17
+# merge onto the story branch still runs the codeline's commit-msg hook (git merge has no --no-verify
+# here), and its message is written to pass it.
+pipeline_commit_flags() {
+    echo "--no-verify"
+}

package/orchestrations/scripts/lib/plan-hash.js

@@ -0,0 +1,19 @@
+'use strict';
+/**
+ * planHash(plan) — the story's plan, identified: md5 of its JSON with keys sorted at every level; '' when there is
+ * none. What a spec was built under (story.specification.planHash) is compared with the plan the story has now.
+ */
+const crypto = require('crypto');
+
+function stable(v) {
+  if (Array.isArray(v)) return `[${v.map(stable).join(',')}]`;
+  if (v && typeof v === 'object') return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stable(v[k])}`).join(',')}}`;
+  return JSON.stringify(v);
+}
+
+function planHash(plan) {
+  if (!plan || typeof plan !== 'object') return '';
+  return crypto.createHash('md5').update(stable(plan)).digest('hex');
+}
+
+module.exports = { planHash };

package/orchestrations/scripts/lib/plan-scope.js

@@ -0,0 +1,73 @@
+'use strict';
+/**
+ * THE PLAN DECIDES THE CODELINES A STORY IS WORKED IN.
+ *
+ * Live AMSD-2974 run 1, 2026-10-09: discovery grounded four codelines; the AC gate's router picked one; the detective was
+ * shown that one ("No other codeline is in scope for this investigation") and planned no consumer and no back-port. The
+ * plan — written once, by the detective that reads the code — is the decision on which codelines change and which only
+ * receive (operator, 2026-10-06); the router's pick is only where the story starts.
+ *
+ * Both answers come from the run's own record of what discovery grounded (codeline-facts.json: one top-level key per
+ * codeline, each with its path, rewritten every run). Nothing is invented: a codeline the record does not hold is never
+ * given a lane, and a lane the story already has is never taken away.
+ */
+
+/** The codelines discovery grounded this run, with their paths, in the record's order. */
+function discovered(facts) {
+  if (!facts || typeof facts !== 'object') return [];
+  return Object.entries(facts)
+    .filter(([k, v]) => !k.startsWith('_') && v && typeof v === 'object' && typeof v.path === 'string' && v.path)
+    .map(([codeline, v]) => ({ codeline, path: v.path }));
+}
+
+function storyLanes(story) {
+  return (Array.isArray(story && story.codelines) && story.codelines.length ? story.codelines : [story && story.codeline])
+    .filter(Boolean);
+}
+
+/**
+ * planScope(story, prd, facts) → { codelines, outputDirs }: what the detective writing the plan is shown — the story's
+ * own codelines first, then every other codeline discovery grounded, each with where it is.
+ */
+function planScope(story, prd, facts) {
+  const dirs = (prd && prd.project && Array.isArray(prd.project.outputDirs)) ? prd.project.outputDirs : [];
+  const found = discovered(facts);
+  const codelines = [...new Set([...storyLanes(story), ...found.map((f) => f.codeline)])];
+  const outputDirs = codelines.map((cl) => dirs.find((d) => d && d.codeline === cl) || found.find((f) => f.codeline === cl))
+    .filter(Boolean).map((d) => ({ codeline: d.codeline, path: d.path }));
+  return { codelines, outputDirs };
+}
+
+/** Every codeline a plan names: its parts in plan order, then each package's provider and consumers. */
+function plannedCodelines(plan) {
+  if (!plan || typeof plan !== 'object') return [];
+  const parts = (Array.isArray(plan.codelines) ? plan.codelines : []).slice()
+    .sort((a, b) => (Number(a && a.order) || 0) - (Number(b && b.order) || 0)).map((c) => c && c.codeline);
+  const pkgs = Array.isArray(plan.packages) ? plan.packages : [];
+  const around = pkgs.flatMap((p) => [p && p.providedBy, ...((p && Array.isArray(p.consumers)) ? p.consumers.map((c) => c && c.codeline) : [])]);
+  return [...new Set([...parts, ...around].filter(Boolean))];
+}
+
+/**
+ * adoptPlanCodelines(story, prd, facts) → the codelines added: every codeline the story's plan names that discovery
+ * grounded becomes one of the story's codelines (story.codelines, routed one first) and one of the run's
+ * project.outputDirs, with its path. Mutates story and prd.
+ */
+function adoptPlanCodelines(story, prd, facts) {
+  if (!story || !story.overallPlan) return [];
+  const found = discovered(facts);
+  const have = storyLanes(story);
+  const added = plannedCodelines(story.overallPlan)
+    .filter((cl) => !have.includes(cl) && found.some((f) => f.codeline === cl));
+  if (!added.length) return [];
+  story.codelines = [...have, ...added];
+  prd.project = prd.project || {};
+  const dirs = Array.isArray(prd.project.outputDirs) ? prd.project.outputDirs : [];
+  for (const cl of added) {
+    if (!dirs.some((d) => d && d.codeline === cl)) dirs.push({ codeline: cl, path: found.find((f) => f.codeline === cl).path });
+  }
+  prd.project.outputDirs = dirs;
+  return added;
+}
+
+module.exports = { planScope, adoptPlanCodelines, plannedCodelines, discovered };

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

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# WHAT A QA GATE IS SHOWN DECIDES WHAT IT CAN CONCLUDE.
+#
+# Live 2026-09-09, run 20260908T215555Z — AMSD-1919, a one-line brownfield defect fixed at
+# CheckoutForm.tsx:306. Two gates were paid for and neither could reach a verdict about the change:
+#
+#   qa-gate:runtime-boundary  "CheckoutForm.tsx itself is unmodified (git diff confirms no
+#                              changes)."   — false, and stated with confidence
+#   qa-gate:mutant-hunter     "truncated to the first 100 of 436 lines and does not include the
+#                              case-sensitivity comparison logic around line 306"  — true, and
+#                              the reason it could only answer WARN
+#
+# Two different faults, one shape: the evidence window could not contain the answer.
+#
+#   1. The diff was built as `git diff "${_rev_base:-HEAD~1}" HEAD`, and `_rev_base=` appears
+#      nowhere in the engine. The fallback was not a fallback, it was the only behaviour — and
+#      HEAD~1..HEAD is the last commit alone. repro-test-writer always commits AFTER the writer,
+#      so on every brownfield defect that window holds the reproducing test and never the fix.
+#
+#   2. The excerpt was `head -n <window>` — anchored at the top of the file, so a 436-line
+#      component whose change sits at line 306 is out of reach at any window size. An earlier fix
+#      added a truncation NOTICE, which is why the agent refused honestly rather than guessing;
+#      it did not make the agent see.
+#
+# Both are fixed by deriving, never by declaring a number here: the base is the phase baseline the
+# run itself recorded, and every window size stays in config/evidence-windows.json.
+#
+# Sourced (not executed) — every function prints to stdout and returns non-zero when it cannot
+# produce evidence, so a caller can say "no evidence" instead of shipping a misleading window.
+
+# qa_gate_diff <project_root> <log_dir>
+#
+# The diff a QA gate must judge: everything THIS PHASE changed, from the baseline the phase
+# recorded. story_outputs_baseline_ref is the single reader of phase-baseline-sha.txt and already
+# serves story_outputs_deleted and story_outputs_files; this is the third consumer, not a second
+# way of answering the same question.
+#
+# ABSENT IS NOT AN EMPTY DIFF. A missing or unusable baseline returns non-zero WITH a sentence
+# saying so, because "nothing changed" and "I could not tell what changed" are opposite findings
+# and the gate acts on them differently.
+qa_gate_diff() {
+    local _root="${1:-}" _log="${2:-}"
+    if [ -z "$_root" ] || [ -z "$_log" ]; then
+        printf '(qa_gate_diff: no project root or log dir given — this gate has no diff to judge)'
+        return 1
+    fi
+
+    local _base=""
+    if command -v story_outputs_baseline_ref >/dev/null 2>&1; then
+        _base=$(story_outputs_baseline_ref "$_log" 2>/dev/null) || _base=""
+    fi
+    if [ -z "$_base" ]; then
+        printf '(no phase baseline was recorded for this run — this gate has no diff to judge, and MUST NOT read that as "nothing changed")'
+        return 1
+    fi
+
+    if ! git -C "$_root" rev-parse --verify --quiet "${_base}^{commit}" >/dev/null 2>&1; then
+        printf '(the recorded phase baseline %s is not a commit in this repository — this gate has no diff to judge)' "$_base"
+        return 1
+    fi
+
+    # A BASELINE THAT IS NOT AN ANCESTOR OF HEAD CANNOT DESCRIBE THIS PHASE.
+    #
+    # Live 2026-09-09, the second resume of run 20260908T215555Z: the baseline was recorded before
+    # ensure_story_branch hard-reset the story branch onto origin/<baseline>, so it named a commit
+    # from the PREVIOUS leg that the reset then orphaned. Diffing an orphan is not empty — it is a
+    # cross-branch comparison, and it produced 8 insertions and 11 deletions in the reproducing
+    # test with no sign of the source fix. runtime-boundary read that and reported the change was
+    # "confined to a Jest/RTL spec file" for the second run running.
+    #
+    # Refused rather than diffed: this whole file exists to keep "nothing changed" apart from
+    # "I cannot tell what changed", and a plausible wrong diff is the worse of the two.
+    if ! git -C "$_root" merge-base --is-ancestor "$_base" HEAD >/dev/null 2>&1; then
+        printf '(the recorded phase baseline %s is not an ancestor of HEAD — it does not describe this phase, so this gate has no diff to judge. A branch reset after the baseline was recorded is the usual cause.)' "$_base"
+        return 1
+    fi
+
+    # The size is DECLARED, like every other evidence window. A literal here would be the exact
+    # thing config/evidence-windows.json exists to stop.
+    local _cap
+    _cap=$(evidence_window qaGateDiffLines 2>/dev/null) || _cap=""
+    if [ -z "$_cap" ]; then
+        printf '(the qaGateDiffLines evidence window is not declared — refusing to invent a size)'
+        return 1
+    fi
+
+    git -C "$_root" diff "$_base" HEAD 2>/dev/null | head -n "$_cap"
+}
+
+# qa_gate_excerpt <project_root> <log_dir> <repo_relative_path> <window_name>
+#
+# The part of a file a gate needs: the region THIS PHASE changed, with the declared window's worth
+# of surrounding context — never the first N lines, which is a window on whatever the file happens
+# to open with.
+#
+# A file that fits inside its window is printed whole and says nothing about truncation: claiming
+# a cut that did not happen is its own kind of misleading.
+qa_gate_excerpt() {
+    local _root="${1:-}" _log="${2:-}" _rel="${3:-}" _win_name="${4:-}"
+    # CALLERS HOLD BOTH SHAPES. story_outputs_sources yields repo-relative paths and the
+    # find-fallback yields absolute ones; a function that accepted only one silently produced
+    # "(unreadable)" for the other, which reads exactly like a file that is not there.
+    local _abs
+    case "$_rel" in
+        /*) _abs="$_rel"; _rel="${_rel#"$_root"/}" ;;
+        *)  _abs="$_root/$_rel" ;;
+    esac
+    [ -f "$_abs" ] || { printf '(%s: unreadable)' "$_rel"; return 1; }
+
+    local _window
+    _window=$(evidence_window "$_win_name" 2>/dev/null) || _window=""
+    if [ -z "$_window" ] || [ "$_window" -le 0 ] 2>/dev/null; then
+        printf '(the %s evidence window is not declared — refusing to invent a size)' "$_win_name"
+        return 1
+    fi
+
+    local _total
+    _total=$(wc -l < "$_abs" 2>/dev/null | tr -d '[:space:]')
+    [ -n "$_total" ] || _total=0
+
+    printf -- '--- %s' "$_rel"
+
+    # Whole file, no claim of truncation.
+    if [ "$_total" -le "$_window" ]; then
+        printf -- ' ---\n'
+        cat "$_abs"
+        return 0
+    fi
+
+    # WHERE THE CHANGE IS, asked of git rather than assumed. -U0 so the hunk headers name only
+    # lines that actually changed; the surrounding context is this function's to decide.
+    local _first="" _last="" _base=""
+    if command -v story_outputs_baseline_ref >/dev/null 2>&1; then
+        _base=$(story_outputs_baseline_ref "$_log" 2>/dev/null) || _base=""
+    fi
+    if [ -n "$_base" ] && git -C "$_root" rev-parse --verify --quiet "${_base}^{commit}" >/dev/null 2>&1; then
+        local _hdr _start _count
+        while IFS= read -r _hdr; do
+            # @@ -a,b +c,d @@  — c is the first changed line on the new side, d how many.
+            _start=$(printf '%s' "$_hdr" | sed -n 's/^@@ -[0-9,]* +\([0-9]*\).*/\1/p')
+            _count=$(printf '%s' "$_hdr" | sed -n 's/^@@ -[0-9,]* +[0-9]*,\([0-9]*\).*/\1/p')
+            [ -n "$_start" ] || continue
+            [ -n "$_count" ] || _count=1
+            [ "$_count" -gt 0 ] 2>/dev/null || _count=1
+            local _end=$(( _start + _count - 1 ))
+            { [ -z "$_first" ] || [ "$_start" -lt "$_first" ]; } && _first="$_start"
+            { [ -z "$_last" ] || [ "$_end" -gt "$_last" ]; } && _last="$_end"
+        done < <(git -C "$_root" diff -U0 "$_base" HEAD -- "$_rel" 2>/dev/null | grep '^@@')
+    fi
+
+    local _from _to _anchored="around this phase's change"
+    if [ -n "$_first" ] && [ -n "$_last" ]; then
+        # Centre the window on the changed region.
+        local _span=$(( _last - _first + 1 ))
+        local _pad=$(( (_window - _span) / 2 ))
+        [ "$_pad" -lt 0 ] && _pad=0
+        _from=$(( _first - _pad ))
+        [ "$_from" -lt 1 ] && _from=1
+        _to=$(( _from + _window - 1 ))
+        if [ "$_to" -gt "$_total" ]; then
+            _to="$_total"
+            _from=$(( _to - _window + 1 ))
+            [ "$_from" -lt 1 ] && _from=1
+        fi
+    else
+        # NAMED, not silent. Falling back to the head of the file is the old behaviour, and the
+        # gate must be told that is what it is looking at.
+        _from=1
+        _to="$_window"
+        [ "$_to" -gt "$_total" ] && _to="$_total"
+        _anchored="from the START of the file — this phase's changed lines could not be located"
+    fi
+
+    printf -- ' (lines %s-%s of %s, %s) ---\n' "$_from" "$_to" "$_total" "$_anchored"
+    sed -n "${_from},${_to}p" "$_abs"
+}
+
+# qa_phase_baseline_sha <project_root> [baseline_branch]
+#
+# THE COMMIT THIS PHASE'S WORK DIVERGED FROM, which is not the same as HEAD.
+#
+# run-agent-orchestration.sh captured `rev-parse HEAD` before the story loop, and
+# ensure_story_branch then hard-reset the story branch onto origin/<baseline> — orphaning the very
+# commit just recorded. On a FIRST run the two agree, because HEAD is already the base; on every
+# RESUME the recorded baseline is the previous leg's tip and every diff-based gate reads it:
+# review-ranger, mutant-hunter, fuzz-weaver, sast-sentinel, runtime-boundary and the tsc/eslint
+# baseline gates.
+#
+# The merge-base gives the same answer before and after the reset, which is what makes it a
+# baseline rather than a snapshot of whatever the branch happened to be carrying.
+#
+# NOTHING IS INVENTED. A base branch that does not resolve falls back to HEAD — the previous
+# behaviour exactly — rather than to a guessed ref.
+qa_phase_baseline_sha() {
+    local _root="${1:-}" _branch="${2:-}"
+    [ -n "$_root" ] || return 1
+
+    local _head
+    _head=$(git -C "$_root" rev-parse --verify --quiet HEAD 2>/dev/null) || _head=""
+    [ -n "$_head" ] || return 1
+
+    if [ -n "$_branch" ]; then
+        # origin/<branch> first, as ensure_story_branch resolves it, then the bare name.
+        local _ref
+        for _ref in "origin/$_branch" "$_branch"; do
+            git -C "$_root" rev-parse --verify --quiet "${_ref}^{commit}" >/dev/null 2>&1 || continue
+            local _mb
+            _mb=$(git -C "$_root" merge-base "$_head" "$_ref" 2>/dev/null) || _mb=""
+            if [ -n "$_mb" ]; then
+                printf '%s' "$_mb"
+                return 0
+            fi
+        done
+    fi
+
+    printf '%s' "$_head"
+}
+
+# qa_record_phase_baseline <root> <base-branch> <log-dir> — WRITE THE PHASE BASELINE every gate reads.
+#
+# One recording for both ways a phase runs its stories. It lived only in Step 8 (main-branch stories),
+# so a brownfield lane that runs its story in a worktree — and skips Step 8 — had no
+# phase-baseline-sha.txt: every pre-existing failure was charged to its writer, eight attempts in a
+# row (£0 multi-lane run, 2026-10-04). Nothing resolvable is said out loud, never written as a guess.
+qa_record_phase_baseline() {
+    local _root="${1:-}" _branch="${2:-}" _log_dir="${3:-${LOG_DIR:-}}" _sha
+    [ -n "$_root" ] && [ -n "$_log_dir" ] || return 1
+    _sha="$(qa_phase_baseline_sha "$_root" "$_branch" 2>/dev/null || echo "")"
+    if [ -z "$_sha" ]; then
+        warning "[orch] could not resolve a baseline commit in $_root — every diff-based gate will compare against nothing"
+        return 1
+    fi
+    printf '%s\n' "$_sha" > "$_log_dir/phase-baseline-sha.txt"
+    printf '%s' "$_sha"
+}