amsd-pipeline-shared 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# amsd-pipeline-shared
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The AMSD pipeline's shared components: one source of code for the bash pipeline (`amsd-pipeline`) and its Claude
+workflows (`amsd-pipeline-workflow`). A fix lands here, once, and both run the same bytes.
+
+## What is in it
+
+| Component | Files | What it does |
+|---|---|---|
+| The model-call gateway | `orchestrations/scripts/llm-handler.sh` and the 34 libraries it runs (`docs/gateway-files.txt`) | Every model call: retry up to `EPAM_CALL_MAX_ATTEMPTS`, the agent's ladder (next rung on a failure), the previous-refusal block, the KB episode for self-heal, cost and Langfuse |
+| The Writer's reviewer | `orchestrations/scripts/team-lead-review.sh` | A failed review call is no verdict — retried up its ladder, then *review incomplete*, never approved |
+| The Spec runner | `orchestrations/scripts/spec-mode-runner.js` | A failed mint re-proposal keeps the accepted roles and says so |
+| The KB synthesiser | `orchestrations/scripts/lib/kb-synthesizer.js` | Runs on its own seam's model |
+| Agent-to-agent messages | `orchestrations/scripts/lib/agent-messages.js` | send / receive / list / route on the pipeline's own bus format (`logs/messages/`, `agent-messages.jsonl`); "router" goes to the stage's router |
+
+Every file sits at the path it has in a pipeline install. The first commit is the 35 gateway files exactly as released
+in amsd-pipeline 2.0.80 (`docs/gateway-baseline-2.0.80.md5`); every change since is its own commit with its tests.
+`docs/CONSUMER-REVIEW-B56.md` reads every caller of the gateway before and after the fix.
+
+## Install
+
+After the pipeline, into the same install. The pipeline and its installer are not changed:
+
+```bash
+npx amsd-pipeline@2.0.80 --dest <install> --ref v2.0.80 --no-docker
+npx amsd-pipeline-shared@<version> install --into <install>
+npx amsd-pipeline-shared@<version> verify  --into <install>     # every file is this package's
+```
+
+`install` replaces a file only when the install holds the released 2.0.80 copy, or a copy an earlier version of this
+package laid down (an upgrade). Anything else — a local edit, another release — is refused before a byte is written,
+with the list. The replaced copies are kept in `<install>/.amsd-pipeline-shared/replaced/`, and
+`amsd-pipeline-shared revert --into <install>` puts the released bytes back exactly.
+
+Needs: Node 20+, bash, jq.
+
+## Messages from the shell
+
+For the bash pipeline (backlog B55), one JSON line out:
+
+```bash
+amsd-pipeline-shared messages send    --dir <logs/messages> --from <agent> --to <agent|router> --router <agent> --type info --subject S --text T
+amsd-pipeline-shared messages receive --dir <logs/messages> --agent <agent> [--mark-read yes]
+amsd-pipeline-shared messages list    --dir <logs/messages>
+```
+
+The pipeline's own `receive-messages.sh` and `list-messages.sh` read what this writes.
+
+## Tests
+
+```bash
+npm test     # node --test, one file at a time; against a pipeline install (AMSD_INSTALL, AMSD_PLAIN_INSTALL)
+```
+
+The gateway, the reviewer, the mint re-proposal and the synthesiser each have a test written red first and
+mutation-checked (md5 before and after). The install is tested on a copy of a 2.0.80 install: exactly the package's
+files change, an edited file is refused, an upgrade replaces only its own copies, revert gives back the release.
+
+## Version
+
+`amsd-pipeline-shared version`. Released with a git tag `v<version>` and the npm publish of the same version.

package/bin/amsd-pipeline-shared.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+// THE SHARED COMPONENT INTO A PIPELINE INSTALL — without changing the pipeline's installer (operator, 2026-10-18: no bash
+// pipeline change outside the shared component). After `npx amsd-pipeline@<v> --dest <install>`:
+//   amsd-pipeline-shared install --into <install>   lay this package's files into <install>/orchestrations
+//   amsd-pipeline-shared verify  --into <install>   every file is this package's (exit 1 and the list when not)
+//   amsd-pipeline-shared revert  --into <install>   put back the files this package replaced
+//   amsd-pipeline-shared messages send|receive|list --dir <bus> …   the agent-to-agent bus (lib/agent-messages.js)
+//   amsd-pipeline-shared version
+// A file is replaced only when the install holds the released copy this package was built from (docs/gateway-baseline-
+// 2.0.80.md5) or this package's own copy (a re-install); anything else is refused, file by file, and nothing is written.
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const ROOT = path.resolve(__dirname, '..');
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const FILES = fs.readFileSync(path.join(ROOT, 'docs', 'gateway-files.txt'), 'utf8').trim().split('\n').filter(Boolean);
+const BASE = Object.fromEntries(fs.readFileSync(path.join(ROOT, 'docs', 'gateway-baseline-2.0.80.md5'), 'utf8').trim().split('\n')
+  .map((l) => l.trim().split(/\s+/)).map(([sum, f]) => [f, sum]));
+const md5 = (f) => (fs.existsSync(f) ? crypto.createHash('md5').update(fs.readFileSync(f)).digest('hex') : null);
+const fail = (m, code = 1) => { process.stderr.write(`amsd-pipeline-shared: ${m}\n`); process.exit(code); };
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === 'version') { process.stdout.write(`${PKG.version}\n`); process.exit(0); }
+// THE MESSAGE BUS FOR SHELL CALLERS (the bash pipeline's adoption, backlog B55): one JSON line out
+if (cmd === 'messages') {
+  const m = require(path.join(ROOT, 'orchestrations', 'scripts', 'lib', 'agent-messages.js'));
+  const [sub, ...o] = rest; const opt = {}; for (let i = 0; i < o.length; i += 2) opt[o[i].replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = o[i + 1];
+  try {
+    const out = sub === 'send' ? m.send({ ...opt, data: opt.data ? JSON.parse(opt.data) : {} })
+      : sub === 'receive' ? m.receive({ ...opt, unread: opt.unread !== 'no', markRead: opt.markRead === 'yes' })
+        : sub === 'list' ? m.list(opt) : (() => { throw new Error('messages send|receive|list --dir <bus> …'); })();
+    process.stdout.write(`${JSON.stringify(out)}\n`); process.exit(0);
+  } catch (e) { fail(String(e && e.message)); }
+}
+const at = rest.indexOf('--into');
+if (!['install', 'verify', 'revert'].includes(cmd) || at < 0 || !rest[at + 1]) fail('usage: amsd-pipeline-shared install|verify|revert --into <pipeline install> | version', 64);
+const INSTALL = path.resolve(rest[at + 1]);
+const ORCH = path.join(INSTALL, 'orchestrations');
+if (!fs.existsSync(path.join(ORCH, 'scripts'))) fail(`${INSTALL} is not a pipeline install (no orchestrations/scripts)`);
+const STATE = path.join(INSTALL, '.amsd-pipeline-shared');
+const BACKUP = path.join(STATE, 'replaced');
+
+if (cmd === 'verify') {
+  const off = FILES.filter((f) => md5(path.join(ORCH, f)) !== md5(path.join(ROOT, 'orchestrations', f)));
+  if (off.length) fail(`${off.length} file(s) are not this package's (${PKG.version}):\n  ${off.join('\n  ')}`);
+  process.stdout.write(`amsd-pipeline-shared ${PKG.version}: all ${FILES.length} file(s) in ${ORCH} are this package's\n`);
+  process.exit(0);
+}
+
+if (cmd === 'revert') {
+  if (!fs.existsSync(path.join(STATE, 'installed.json'))) fail(`nothing to revert: no amsd-pipeline-shared install recorded in ${STATE}`);
+  for (const f of FILES) {
+    const b = path.join(BACKUP, f);
+    if (fs.existsSync(b)) fs.copyFileSync(b, path.join(ORCH, f));
+    else if (!BASE[f]) fs.rmSync(path.join(ORCH, f), { force: true });   // this package's own file: the release has none
+  }
+  const back = FILES.filter((f) => (BASE[f] ? md5(path.join(ORCH, f)) !== BASE[f] : fs.existsSync(path.join(ORCH, f))));
+  if (back.length) fail(`revert incomplete — not the released copy:\n  ${back.join('\n  ')}`);
+  fs.rmSync(STATE, { recursive: true, force: true });
+  process.stdout.write(`amsd-pipeline-shared: reverted ${FILES.length} file(s) to the released copies\n`);
+  process.exit(0);
+}
+
+// install: every target must be the released copy or this package's — checked for all files before any is written
+// an earlier version of this package laid down: its copies are replaceable too (an upgrade), never anyone else's
+let PREV = {}; try { PREV = JSON.parse(fs.readFileSync(path.join(STATE, 'installed.json'), 'utf8')).files || {}; } catch { PREV = {}; }
+const plan = FILES.map((f) => {
+  const now = md5(path.join(ORCH, f)); const ours = md5(path.join(ROOT, 'orchestrations', f));
+  if (now && now !== ours && PREV[f] === now) return { f, now, ours, state: 'previous' };
+  // a file the release never had (this package's own, e.g. lib/agent-messages.js): installed where absent
+  if (!BASE[f]) return { f, now, ours, state: now === ours ? 'current' : (now === null ? 'new' : 'other') };
+  return { f, now, ours, state: now === ours ? 'current' : (now === BASE[f] ? 'released' : 'other') };
+});
+const other = plan.filter((p) => p.state === 'other');
+if (other.length) {
+  fail(`refused — ${other.length} file(s) in the install are neither the released copy (2.0.80) nor this package's; nothing was written:\n  `
+    + other.map((p) => `${p.f} (md5 ${p.now || 'absent'})`).join('\n  '));
+}
+for (const p of plan.filter((x) => x.state === 'released')) {
+  const b = path.join(BACKUP, p.f); fs.mkdirSync(path.dirname(b), { recursive: true });
+  if (!fs.existsSync(b)) fs.copyFileSync(path.join(ORCH, p.f), b);
+}
+for (const p of plan.filter((x) => ['released', 'new', 'previous'].includes(x.state))) {
+  const dst = path.join(ORCH, p.f);
+  const mode = p.state === 'new' ? fs.statSync(path.join(ROOT, 'orchestrations', p.f)).mode : fs.statSync(dst).mode;
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.copyFileSync(path.join(ROOT, 'orchestrations', p.f), dst);
+  fs.chmodSync(dst, mode);
+}
+fs.mkdirSync(STATE, { recursive: true });
+fs.writeFileSync(path.join(STATE, 'installed.json'), `${JSON.stringify({ package: PKG.name, version: PKG.version,
+  files: Object.fromEntries(FILES.map((f) => [f, md5(path.join(ROOT, 'orchestrations', f))])) }, null, 2)}\n`);
+const n = plan.filter((x) => ['released', 'new', 'previous'].includes(x.state)).length;
+process.stdout.write(`amsd-pipeline-shared ${PKG.version} → ${ORCH}: ${n} file(s) replaced, ${FILES.length - n} already current\n`);

package/docs/CONSUMER-REVIEW-B56.md

@@ -0,0 +1,66 @@
+# B56 consumer review — who receives a real failure instead of "success, empty answer"
+
+The fix (`llm-handler.sh`, claude and codemie-claude arms): a call whose CLI fails is retried up to
+`EPAM_CALL_MAX_ATTEMPTS` (3) with the ladder consulted, the previous-refusal block added and a KB episode recorded; if
+every attempt fails, the hub exits 1. Before the fix every failed call exited 0 with an empty answer.
+
+Read by hand against amsd-pipeline v2.0.80 (`git show v2.0.80:…`), 2026-10-18. Every caller of `ai-run.sh` /
+`llm-handler.sh` / `AI_RUNNER_CMD` in `orchestrations/scripts` (tests and tools excluded).
+
+## Same outcome as today, after the hub's retries (a failure handled as an empty answer)
+| Caller | How it handles a non-zero exit |
+|---|---|
+| spec-mode-runner.js `runClaude` → `runAgentForJson` | rejects; each call site below catches |
+| — spec coordinator (:1825), coordinator review (:2524), LLM decisions (:2704) | catch → default / no review, logged |
+| — ticket links (:7614), spec agent (:7890), speckit review (:8223) | catch → "could not be read" / failed attempt |
+| — mint proposals (:4339), survey review (:4874) | inside `retryUntilParsedAsync`: "the call itself failed" → next attempt |
+| — roster review (:5476 via mint-agents-step :917), project roster review (:5249 via roster-seams :174) | catch → `review_failed` |
+| lib/llm-call.js (discovery, ac-gate, cpa) | already rejects on non-zero exit AND on empty — unchanged |
+| lib/kb-synthesizer.js | already handles `r.status !== 0` |
+| lib/cli-commands.sh :261, story-attempt.sh :752 / :791, review-cycle.sh :43, vc-coverage-check.sh :158, brownfield-repro-test-writer.sh :867, retry-extension.sh :199, run-agent-orchestration.sh :4052–4132 | `\|\| echo ""` / `\|\| true` / `if … then … else` — the empty-answer path |
+| prd-change-review.sh :216, :452 | `\|\| echo ""` / its else branch |
+
+## Better — the failure is now classified as a failure
+| Caller | Before | After |
+|---|---|---|
+| failure-healing.sh :1278 (failure analyst) | call "ok", answer unparseable | its call-failed branch; its own analyst retry/ladder loop runs |
+| model-ladder.sh :1378 (ladder coordinator) | call "ok", no JSON | its call-failed branch |
+| prd-change-review.sh :86 (PRD-change reviewer) | empty reply parsed | `verdict: fail — the change was NOT reviewed` |
+| post-impl-tc-writer.sh :234 | "no criteria extracted" | "Agent failed (exit 1)" (TC_EXIT is passed on) |
+| orch-prompt.sh :133 (the Writer, via claude.sh) | a crashed writer call looked like a finished attempt | `_rc` = 1 → the Writer's failure path (analyst, ladder) |
+| agent-attempt-analyst.sh :240 | — | already treats non-zero as `self_heal_failed` (exit 2) |
+| surveyEstate (:3724) | `not_investigated` | `failed` with the reason (catch) |
+
+## Changes that need a decision
+1. **Mint re-proposal (spec-mode-runner.js :4414) has no catch, nor has its caller (mint-agents-step.js :843 → the
+   top-level catch, exit 1).** Before: an empty re-proposal ended the loop and the mint kept the roles already accepted.
+   After: three failed attempts there fail the mint step.
+   **Fixed in this package** (operator: "yes move both in"): spec-mode-runner.js joined the component; the call is caught,
+   the loop ends as today and says so (test/mint-reproposal.test.js).
+2. **The reviewer (team-lead-review.sh :326 / :877) ignores the call's exit status and reads `2>&1`.** A failed call's
+   output is the hub's error text, which passes the "no verdict" check and is parsed as the review → the fallback
+   `changes_requested` with a "could not parse" blocker. Fail-safe (never approves) — before and after the fix — but the
+   Writer is sent to fix an issue that does not exist instead of "review incomplete — reviewer unavailable".
+   **Fixed in this package**: team-lead-review.sh joined the component; a failed call is no verdict — retried up the
+   reviewer's ladder, then review-incomplete (test/reviewer.test.js).
+
+## Cost
+A persistent failure now costs up to 3 hub attempts per caller attempt (callers with their own retry loop multiply:
+content-retry ×3, the failure analyst's ladder loop, the roster review ×2). Calls that succeed cost the same as before.
+
+## Found while proving the analyst in the real project environment (2026-10-18)
+- The analyst works there: `self-heal.js` → `agent-attempt-analyst.sh` diagnosed a planted no-json failure on
+  claude-sonnet-5 and marked it analysed. (It declined only in a stripped environment with no project config.)
+- One analysis = 4 model calls by design: the analyst + its plan pass, then `kb-synthesizer` + its plan pass (and 12 free
+  `--help` capability probes).
+- **`kb-synthesizer` runs with no model resolved** (AI_MODEL unset) — it falls back to the CLI's default model instead of
+  its seam's. An "appropriate LLM settings" defect. **Fixed in this package**: with no model given it runs on its seam's
+  start rung (seamInvocationEnv; claude-haiku-4-5 on the claude set); a named model still wins (test/kb-synthesizer-model.test.js).
+- **On a fresh install the synthesiser cannot render its prompt**: `projects/<p>/prompts/kb-enforcement-synthesis.json`
+  is a minted project prompt, absent on wf-280 ("project-authority prompt missing … Mint it"). To check against how the
+  codeline cache supplies prompts before the next live leg; the self-heal listener must report a synthesis failure.
+- **The ladder position `mid` resolves to the middle tier, `high`** (seam-invocation.js resolveTierPosition: base/mid/top
+  over the declared order medium/high/highest), whose chain is haiku → sonnet-5 → opus-5-5. config/llm-defaults.claude.json
+  says of `medium`: "A `mid` seam never reaches Opus: 14 seams resolve here". 12 seams declare `mid` (ticket-links among
+  them) and, by the code, can reach Opus. The pipeline's code and its declaration disagree — for the operator to rule;
+  the gateway follows the code (agent_ladder_model), as the hub does.

package/docs/gateway-baseline-2.0.80.md5

@@ -0,0 +1,37 @@
+b2470a21b73b03abb95713f05acaa827  scripts/agent-attempt-analyst.sh
+c45cda62ef52ee95c8de6acead3408f8  scripts/lib/agent-contract.js
+f881c989bd12e76e13e017ff2d984041  scripts/lib/agent-ladder.sh
+c2dfd2381db0242fdbc487a948fd7feb  scripts/lib/agent-si.js
+488870d661550b057077104147b54004  scripts/lib/constraint-compiler.js
+639d21b8d2adb82d2ed98ceffc3c2175  scripts/lib/constraint-sanity.js
+f31ac2a712f0e1f288606b0fdbb7d001  scripts/lib/content-retry.js
+e24bfedd32af37785a42fa8c168ae52a  scripts/lib/cost-emitter.js
+d7fb52664b0f0528b6142bf0574c1f49  scripts/lib/cost-record.sh
+f20fe173b49d25008e206f82ace56619  scripts/lib/engine-prompt.js
+773a5b134875d61f988b15934a9d5fec  scripts/lib/env-file.sh
+66f728a2d4f3f4dac44bfc08775cc485  scripts/lib/evidence-windows.js
+e80316d37f028cdf83f3a8fa43913509  scripts/lib/failure-signature.js
+1ada64b928930ab3937c4b26269fb4ec  scripts/lib/handlers/emit-cost.js
+dccf359893d3c9a2c233ab19e0a64728  scripts/lib/jq-vals.sh
+a2589a1ff6443fc1c18b43095d9d8872  scripts/lib/kb-apply.sh
+740f541460c80aa0f3220656069f0838  scripts/lib/kb-arbitration.js
+8d6e41fe34703497cf5e8b5d1320e3e7  scripts/lib/kb-cli.js
+c0a3a88d1a895e0a86ea483cada15411  scripts/lib/kb-store.js
+133c3a3df52044457822755a23f40bd2  scripts/lib/kb-synthesizer.js
+84348b573adb9c666eb040fb8f7621b2  scripts/lib/langfuse-emit.js
+991a2faba5aaa513e63fa64689761248  scripts/lib/llm-settings-resolve.js
+ed15fbd317db2643b19a3fd7ecd1979a  scripts/lib/model-ladder.sh
+4d2dc2a636736b5b77711ad7736f9075  scripts/lib/model-ladders.sh
+97d25b9108a01292d1b28da0d3c129e9  scripts/lib/pipeline-tools.js
+6bfffd3ba6eb845f738d3157168bf056  scripts/lib/relative-paths.js
+6894e248c7a86d07626b7e981d534354  scripts/lib/render-prompt-section.js
+912511e457b0a6f4801c479400b1c3a3  scripts/lib/seam-invocation.js
+010eaf91866f87040076c6889c6dc148  scripts/lib/seam-ladder.sh
+49cafcda352d69ed32966950902d8e4d  scripts/lib/self-heal.js
+177515d856a573dad5f515ece454d835  scripts/lib/stage-coverage-gate.sh
+be6d0a378fa9c3bc9da6240877aaeae3  scripts/lib/tool-timeouts.js
+5574182fb27aaeabbfff261b3a8d6d39  scripts/lib/transcript-tool-calls.js
+c4b96230c15b52a845cf20fd3266fe01  scripts/llm-handler.sh
+40c65de8360d5a9f59902fca26d1d7a8  scripts/update-monitor.sh
+dfa070b168a7c01fab8aab5a46d16192  scripts/team-lead-review.sh
+f206025f304e8320b8417a6dd6606044  scripts/spec-mode-runner.js

package/docs/gateway-files.txt

@@ -0,0 +1,38 @@
+scripts/agent-attempt-analyst.sh
+scripts/lib/agent-contract.js
+scripts/lib/agent-ladder.sh
+scripts/lib/agent-si.js
+scripts/lib/constraint-compiler.js
+scripts/lib/constraint-sanity.js
+scripts/lib/content-retry.js
+scripts/lib/cost-emitter.js
+scripts/lib/cost-record.sh
+scripts/lib/engine-prompt.js
+scripts/lib/env-file.sh
+scripts/lib/evidence-windows.js
+scripts/lib/failure-signature.js
+scripts/lib/handlers/emit-cost.js
+scripts/lib/jq-vals.sh
+scripts/lib/kb-apply.sh
+scripts/lib/kb-arbitration.js
+scripts/lib/kb-cli.js
+scripts/lib/kb-store.js
+scripts/lib/kb-synthesizer.js
+scripts/lib/langfuse-emit.js
+scripts/lib/llm-settings-resolve.js
+scripts/lib/model-ladder.sh
+scripts/lib/model-ladders.sh
+scripts/lib/pipeline-tools.js
+scripts/lib/relative-paths.js
+scripts/lib/render-prompt-section.js
+scripts/lib/seam-invocation.js
+scripts/lib/seam-ladder.sh
+scripts/lib/self-heal.js
+scripts/lib/stage-coverage-gate.sh
+scripts/lib/tool-timeouts.js
+scripts/lib/transcript-tool-calls.js
+scripts/llm-handler.sh
+scripts/update-monitor.sh
+scripts/team-lead-review.sh
+scripts/spec-mode-runner.js
+scripts/lib/agent-messages.js

package/orchestrations/scripts/agent-attempt-analyst.sh

@@ -0,0 +1,287 @@
+#!/usr/bin/env bash
+# agent-attempt-analyst.sh <failure_class> <failed_output_file> [context_file]
+#
+# Reusable AGENT-EXECUTION failure analyst — the self-heal for agents that fail by
+# producing NO usable output (max-iterations, no-file, no-json, malformed). This is the
+# greenfield-safe SIBLING of claude.sh's run_failure_analyst (which handles CODE/TEST
+# failures and is left untouched). It shares the crown-jewel discipline: the failure-analyst
+# profile, the escalation model, and GROUND-TRUTH context (the real task the agent was given),
+# so it diagnoses WHY the agent failed and prescribes a SHORT corrective directive for the
+# NEXT attempt — instead of a canned string.
+#
+# Used by: brownfield-repro-test-writer.sh (now), the code-graph-detective (next).
+#
+# It does NOT diagnose provider/infra failures (no agent-behaviour to correct) — for those it
+# emits nothing and the caller just retries/ladders.
+#
+# Output: the corrective directive on stdout (empty string = nothing to add, just retry).
+#
+# Exit contract (B30, 2026-07-25) — deliberately three-valued, because "produced
+# no corrective" is a LEGITIMATE outcome for provider/infra/timeout and must stay
+# distinguishable from a BROKEN analyst:
+#   0 + marker    -> analysed; the corrective is recorded as a KB EPISODE, not returned as prose
+#   0 + no marker -> deliberate skip (provider/infra/timeout: no behaviour to fix)
+#
+# THE CORRECTIVE IS NOT ON STDOUT. It used to be returned for the caller to prepend to the next
+# attempt; that is a self-heal push into a prompt, which is banned. Nothing has been written to
+# stdout since, so a caller distinguishing "analysed" from "skipped" by the presence of output
+# would read every success as a skip. The caller declares SELF_HEAL_ANALYSED_MARKER and this
+# script echoes it on stderr when it actually analyses.
+#   2             -> the analyst itself failed; the caller must RECORD that the
+#                    next attempt is running with no corrective guidance
+#
+# This is still best-effort and still must not block the caller. Previously it
+# was `exit 0` unconditionally, swallowed its runner's stderr, and emitted
+# self_heal_complete before checking anything had been produced — so a dead
+# analyst was indistinguishable from a working one in both logs and dashboard,
+# and every retry silently re-ran the identical prompt. Not blocking the caller
+# is not the same as not telling anyone.
+
+# THE PIPELINE DOES NOT RUN CODE NOBODY HAS TESTED. This stage asks how much of the code it is
+# about to execute has a test behind it, and halts when the project says it must.
+_scg_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/stage-coverage-gate.sh"
+# shellcheck source=/dev/null
+[ -f "$_scg_lib" ] && . "$_scg_lib" && require_stage_coverage selfheal || exit 1
+
+set -uo pipefail
+
+FAILURE_CLASS="${1:-}"
+FAILED_OUTPUT_FILE="${2:-/dev/null}"
+CONTEXT_FILE="${3:-/dev/null}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# jq_vals — prompt values files whose content never becomes an argv entry.
+# Placed with the other library sources, NOT beside SCRIPT_DIR: the path-resolution
+# block is lifted verbatim by tests that build a minimal script tree, and a source
+# line inside it makes those probes fail on a library they have no reason to carry.
+source "$SCRIPT_DIR/lib/jq-vals.sh"
+
+# THIS SEAM ASKS FOR ITS LADDER.
+#
+# Until 2026-08-12 only team-lead-review.sh called this, so sixteen of seventeen seams kept
+# whatever fixed model their script hardcoded while the registry looked authoritative. The
+# EVERY ENTRY POINT READS THE LADDER DECLARATION ITSELF.
+#
+# lib/model-ladders.sh exists so that "what a tier contains" is declared once and read the same
+# way everywhere. Only claude.sh, run-agent-orchestration.sh and detective-rerun.sh ever called
+# it, so this script resolved its model ONLY from environment its parent happened to export. Run
+# standalone — a replay, a retest, a test harness — nothing set EPAM_MODEL_LADDER_<TIER>,
+# seam_ladder_export set no EPAM_MODEL, and this seam skipped its work while exiting 0.
+#
+# export_model_ladders leaves an already-set value alone, so calling it here changes nothing when
+# the orchestrator has already exported the chain, and supplies it when nobody has.
+_ml_lib="${SCRIPT_DIR:-$(dirname "${BASH_SOURCE[0]}")}/lib/model-ladders.sh"
+if [ -f "$_ml_lib" ]; then
+    # shellcheck source=lib/model-ladders.sh
+    . "$_ml_lib" || true
+    command -v export_model_ladders >/dev/null 2>&1 \
+        && export_model_ladders "${EPAM_LLM_SETTINGS_FILE:-${EPAM_PROJECT_CONFIG_DIR:+$EPAM_PROJECT_CONFIG_DIR/llm-settings.json}}" || true
+fi
+# ask must come BEFORE any model is resolved below: seam_ladder_export sets EPAM_MODEL, and
+# a later assignment that wins makes the whole thing decorative.
+#
+# Guarded: these run mid-pipeline, and a packaging error must degrade to the previous fixed
+# model rather than kill a run.
+# shellcheck source=lib/seam-ladder.sh
+. "$SCRIPT_DIR/lib/seam-ladder.sh" 2>/dev/null || true
+# WHICH AGENT THIS IS — declared ONCE, and exported so ai-run.sh keys this agent's ladder rung
+# state to it. Without it every agent shared one counter ("agent__<story>"): one agent escalating
+# advanced the ladder for all of them, and team-lead-review's cross-process resume read a key
+# nothing ever wrote.
+_SEAM_NAME="agent-failure-analyst"
+export EPAM_AGENT_NAME="$_SEAM_NAME"
+command -v seam_ladder_export >/dev/null 2>&1 && seam_ladder_export "$_SEAM_NAME"
+
+AI_RUNNER_CMD="${AI_RUNNER_CMD:-$SCRIPT_DIR/ai-run.sh}"
+# shellcheck source=lib/agent-invoke.sh
+source "$SCRIPT_DIR/lib/agent-invoke.sh"
+
+log() { echo "[agent-attempt-analyst] $*" >&2; }
+
+# Provider/infra failures carry no agent behaviour to correct — skip (caller just retries).
+case "$FAILURE_CLASS" in
+    provider|infra|timeout) exit 0 ;;
+esac
+
+# THE SEAM DECIDES. seam_ladder_export (above) sets EPAM_MODEL to the first rung of the chain this
+# seam's ARCHETYPE declares, which is the whole point of declaring a ladder. The literal that stood
+# last in this chain overrode that silently: the seam asked for its tier and the answer was
+# discarded, so editing the declaration moved no model. Operator overrides still win; what is gone
+# is the hardcoded final fallback, which no configuration could remove.
+# HEAL ON THE RUNG THAT FAILED — the whole rung, not its model.
+#
+# Operator, 2026-08-22: "if analyst is used in a retry the self-heal ladder rung must be
+# inherited by the analyst."
+#
+# Diagnosing a stronger rung's attempt from a weaker one is guesswork about reasoning the
+# analyst cannot reproduce, and the diagnosis reads as authoritative anyway. Model alone is not
+# enough: claude.sh's ladder moves provider, reasoning effort and temperature with it, so an
+# analyst on the right model at the wrong effort is still analysing a setup that never ran.
+#
+# The rung is persisted by the writer on every attempt (lib/story-outputs.sh). No guard and no
+# fallback: for a story that has been attempted it EXISTS, and defending against its absence
+# would restore the silent seam-default diagnosis this replaces. An operator override still
+# wins — a deliberate cross-rung diagnosis stays possible.
+# shellcheck source=lib/story-outputs.sh
+. "$SCRIPT_DIR/lib/story-outputs.sh"
+_rung_model=$(story_rung_get "${LOG_DIR:-}" "${AGENT_ANALYST_STORY_ID:-}" model)
+_rung_provider=$(story_rung_get "${LOG_DIR:-}" "${AGENT_ANALYST_STORY_ID:-}" provider)
+_rung_effort=$(story_rung_get "${LOG_DIR:-}" "${AGENT_ANALYST_STORY_ID:-}" reasoningEffort)
+_rung_temperature=$(story_rung_get "${LOG_DIR:-}" "${AGENT_ANALYST_STORY_ID:-}" temperature)
+if [ -n "$_rung_model" ]; then
+    export EPAM_REASONING_EFFORT="$_rung_effort"
+    export EPAM_TEMPERATURE="$_rung_temperature"
+    warning "analyst inherits the failing rung: model=$_rung_model provider=$_rung_provider effort=${_rung_effort:-unset} temp=${_rung_temperature:-unset}"
+fi
+_model="${AGENT_ANALYST_MODEL:-${_rung_model:-${ESCALATION_MODEL:-${EPAM_MODEL:-${EPAM_MODEL:-}}}}}"
+_provider="${AGENT_ANALYST_PROVIDER:-${_rung_provider:-${ORCH_GATE_PROVIDER:-${EPAM_ORCHESTRATION_PROVIDER:-}}}}"
+if [ -z "$_model" ]; then
+    # A diagnosis produced by a guessed model is worse than an honest absence: it reads as
+    # authoritative and nothing downstream can tell it was never grounded in a declared tier.
+    warning "no model resolved for this seam — its archetype declares no ladder, or the tier's chain is unset. Not analysing rather than guessing a model."
+    exit 0
+fi
+
+# The analyst's identity is its SI (seam agent-failure-analyst), resolved by the hub — never a persona
+# pasted into the prompt (operator, 2026-09-30: one path).
+# THE PROMPT, AND THE FIVE CLASS HINTS, FROM THE TEMPLATE LAYER.
+#
+# All of it used to sit here: the fallback role line, a five-arm case statement whose every arm
+# was a sentence addressed to the analyst, and the prompt heredoc. The engine still chooses
+# WHICH hint by failure class -- that is a decision, not wording -- but it no longer holds the
+# wording of any of them.
+. "$SCRIPT_DIR/lib/render-engine-prompt.sh"
+
+_tpl="$(dirname "$SCRIPT_DIR")/prompts/templates/agent-failure-analyst.json"
+_body() { "${NODE_BIN:-node}" -e '
+  const d = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+  process.stdout.write(String((d.bodies || {})[process.argv[2]] || ""));
+' "$_tpl" "$1"; }
+
+
+_failed_output=$(cat "$FAILED_OUTPUT_FILE" 2>/dev/null || echo "")
+_context=$(cat "$CONTEXT_FILE" 2>/dev/null || echo "")
+
+# Class-specific framing so the analyst targets the right behaviour.
+case "$FAILURE_CLASS" in
+    max_iterations)    _class_hint="$(_body hint_max_iterations)" ;;
+    no_file)           _class_hint="$(_body hint_no_file)" ;;
+    no_json|malformed) _class_hint="$(_body hint_no_json)" ;;
+    rejected)          _class_hint="$(_body hint_rejected)" ;;
+    invalid_test)      _class_hint="$(_body hint_invalid_test)" ;;
+    *)                 _class_hint="$(_body hint_default)" ;;
+esac
+
+# Values via a FILE, never argv: a failed agent's output is routinely megabytes and argv is
+# capped at ARG_MAX. This is the same crash that took out the failure analyst on 2026-08-15.
+# WHY THE CALLER REFUSED THIS ATTEMPT (AGENT_ANALYST_REASON). Every caller knows it — a reviewer's
+# finding, a validator's verdict, a contract refusal — and none of it reached this prompt until
+# 2026-10-06. Absent is said aloud, in the prompt and here: a caller that drops it is a defect.
+_reason="${AGENT_ANALYST_REASON:-}"
+[ -n "${AGENT_ANALYST_REASON_FILE:-}" ] && [ -f "$AGENT_ANALYST_REASON_FILE" ] && _reason="$(cat "$AGENT_ANALYST_REASON_FILE")"
+[ -n "${_reason//[[:space:]]/}" ] || { log "WARNING: no reason was given for this ${FAILURE_CLASS} failure — the caller dropped it; the analyst diagnoses from the output alone"; _reason="(the caller gave no reason — diagnose from the output alone)"; }
+_aa_vals=$(mktemp "${TMPDIR:-/tmp}/agent-failure-analyst-vals-XXXXXX.json")
+# Where the spec pass's detective found the fix, for the story whose agent failed — the same
+# rendering the reviewer and impl-failure-analyst read (lib/handlers/fix-sites.js).
+_fix_sites=""
+if [ -n "${AGENT_ANALYST_STORY_ID:-}" ] && [ -f "${MAIN_PRD_FILE:-${PRD_FILE:-}}" ]; then
+    _fix_sites=$("${NODE_BIN:-node}" "$SCRIPT_DIR/lib/handlers/fix-sites.js" "${MAIN_PRD_FILE:-$PRD_FILE}" "$AGENT_ANALYST_STORY_ID" 2>/dev/null || true)
+fi
+jq_vals --arg class_hint "$_class_hint" \
+      --arg failure_class "$FAILURE_CLASS" \
+      --arg failure_reason "$_reason" \
+      --arg failed_output "${_failed_output:-(empty — it produced nothing)}" \
+      --arg context "${_context:-(not provided)}" \
+      --arg fix_sites "${_fix_sites:-(the spec pass recorded none for this story)}" \
+      '{"__CLASS_HINT__":$class_hint,"__FAILURE_CLASS__":$failure_class,"__FAILURE_REASON__":$failure_reason,"__FAILED_OUTPUT__":$failed_output,"__CONTEXT__":$context,"__FIX_SITES__":$fix_sites}' \
+      > "$_aa_vals"
+if ! _prompt=$(render_engine_prompt agent-failure-analyst "$_aa_vals" prompt); then
+    rm -f "$_aa_vals"
+    warning "cannot render the analyst prompt — not analysing rather than asking with no instructions"
+    exit 0
+fi
+rm -f "$_aa_vals"
+
+# Activity emit — the failure-agent is a first-class agent and MUST be visible in
+# agent-activity.html like every other agent (2026-07-24). storyId comes from the caller.
+_fa_sid="${AGENT_ANALYST_STORY_ID:-}"
+_emit_fa() { bash "$SCRIPT_DIR/update-monitor.sh" event "$1" "$2" "$_fa_sid" "main" "failure-analyst" 2>/dev/null || true; }
+_emit_fa "self_heal_start" "failure-analyst diagnosing ${FAILURE_CLASS}${_fa_sid:+ for ${_fa_sid}}"
+
+log "diagnosing ${FAILURE_CLASS} via ${_model}"
+
+# THE CALLER DECLARES HOW IT WILL RECOGNISE A REAL ANALYSIS, and this echoes it back.
+
+# self-heal.js used to decide by regex-matching the sentence above, so rewording one line
+
+# of prose turned every successful analysis into a "decline" — the same indistinguishable
+
+# state recorded live on 2026-08-27 as seven refusals with zero episodes and zero rc=2.
+
+# One string, chosen by the reader, and the prose is free to change.
+
+[ -n "${SELF_HEAL_ANALYSED_MARKER:-}" ] && printf '%s\n' "$SELF_HEAL_ANALYSED_MARKER" >&2
+
+# Keep the runner's stderr: it is the only evidence of WHY self-heal failed, and
+# both call sites used to discard it along with everything else.
+_analyst_err="$(mktemp 2>/dev/null || echo /tmp/agent-analyst-err.$$)"
+# THROUGH THE ONE DOOR -- AND THE ANALYST CAN FINALLY LOOK AT SOMETHING.
+#
+# This granted NO TOOLS. Not a restricted set: none. EPAM_ALLOWED_TOOLS was never set and the tool
+# gate was never opened, so the agent asked to work out WHY an attempt failed could not read the
+# file that failed, search for the symbol, or run the check that reported it. It diagnosed from a
+# description of the evidence.
+#
+# Its profile has declared "toolGrant": "execute" the whole time. Nothing read it, because nothing
+# went through lib/agent-invoke.sh -- so the declaration and the invocation disagreed and the
+# invocation won silently.
+#
+# The budget was the same story one field over: three ${VAR:-default} literals duplicating a
+# profile that already states them.
+_note=$(echo "$_prompt" | invoke_agent agent-failure-analyst \
+    --model "$_model" --provider "$_provider" \
+    --codeline "${PROJECT_ROOT:-}" \
+    2>"$_analyst_err")
+_analyst_rc=$?
+
+# Trim to a bounded directive; never emit a huge blob.
+_trimmed="$(printf '%s' "$_note" | head -c 800)"
+
+if [ "$_analyst_rc" -ne 0 ] || [ -z "${_trimmed//[[:space:]]/}" ]; then
+    log "FAILED — no corrective produced for ${FAILURE_CLASS} (exit=${_analyst_rc}, model=${_model})"
+    [ -s "$_analyst_err" ] && log "  runner stderr: $(head -c 400 "$_analyst_err" | tr '\n' ' ')"
+    log "  the next attempt will retry WITHOUT corrective guidance"
+    _emit_fa "self_heal_failed" "failure-analyst FAILED (${FAILURE_CLASS}, exit=${_analyst_rc}) — next attempt has NO corrective guidance"
+    rm -f "$_analyst_err" 2>/dev/null || true
+    exit 2
+else
+    _emit_fa "self_heal_complete" "failure-analyst prescribed corrective directive (${FAILURE_CLASS})"
+fi
+
+rm -f "$_analyst_err" 2>/dev/null || true
+
+# ── Feed the KB, never the prompt ────────────────────────────────────────────
+# The diagnosis used to be returned as prose for the caller to prepend to the
+# next attempt ("CORRECTIVE GUIDANCE FROM SELF-HEAL: ..."). That is a self-heal
+# push into a prompt, which is banned: appended text is silently trimmed on long
+# runs and nothing verifies the agent obeyed it.
+#
+# Instead the diagnosis becomes an EPISODE, and synthesis turns it into an
+# enforceable constraint via the path that is already tested and schema-bounded.
+# Threshold 1 because this heal is same-story: the retry happens seconds later,
+# and waiting for a second identical failure would leave the very next attempt —
+# the one that matters most — with nothing. Arbitration, TTL ageing and
+# quarantine are all in place, so a single-episode rule is safe: if it is wrong,
+# it ages out.
+_kb_lib="$SCRIPT_DIR/lib/kb-apply.sh"
+if [ -f "$_kb_lib" ]; then
+    # shellcheck disable=SC1090
+    . "$_kb_lib"
+    # Here-string, NOT a pipe: `x | kb_record_episode` runs the function in a
+    # subshell, so the signature it captures dies with it and synthesis has no key.
+    kb_record_episode "${AGENT_ANALYST_STORY_ID:-}" "${STORY_ROLE:-}" "$_trimmed" "$FAILURE_CLASS" \
+        <<< "$_failed_output" || true
+    KB_SYNTHESIS_THRESHOLD=1 kb_maybe_synthesize "${STORY_ROLE:-}" || true
+fi
+
+# Deliberately no stdout: there is no prose channel back to the caller any more.
+exit 0